# Save and resume plans

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

Keep plan progress in browser storage or your own database, so a multi-step write survives reloads, crashes and restarts.

Source: https://ensforge.com/docs/sdk/save-and-resume-plans

Every write saves its **plan** and progress to the client's storage after each step. With storage
that outlives your process, a registration or migration survives a page reload, a crash or a
serverless cold start. This page shows the built-in stores, how to write your own, and how to
serialise a plan.

## Prerequisites [#prerequisites]

- Know what [`plan.resume`](/docs/sdk/continue-after-a-failure) does.
- Read [How writes work](/docs/sdk/writing-to-ens) for what a plan is.

## What is saved [#what-is-saved]

A saved plan is a `Plan.Record`:

| Field        | Description                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| `plan`       | The plan: id, steps, calls, requirements, warnings, deployments and fees.                              |
| `status`     | `"pending"` while steps remain, `"completed"` once every step is submitted, `"failed"` after an error. |
| `submitted`  | Transaction hashes per submitted step id.                                                              |
| `bundles`    | EIP-5792 bundle id per step sent in a bundle.                                                          |
| `references` | Route references per step sent through `via`, such as UserOperation hashes.                            |
| `error`      | Message of the last failure.                                                                           |
| `updatedAt`  | Unix time in milliseconds.                                                                             |

The record is written before the first step, after every submission, and when the write fails or
completes. Saving is best effort: if the store throws, the write still runs, but it cannot be
resumed.

## Choose a store [#choose-a-store]

Pass `storage` to `Ensforge.create`.

| Store                            | Survives reload | Where it works                                                                                                                                             |
| -------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Plan.memoryStorage()` (default) | No              | Everywhere. Lost when the process or page reloads.                                                                                                         |
| `Plan.localStorage(key?)`        | Yes             | Browsers. Records are kept as JSON under one key, `ensforge:plans` by default. Calls reject where `localStorage` does not exist, such as server rendering. |
| Your own `Plan.Storage`          | Yes             | Anywhere, such as a database or key-value store.                                                                                                           |

**Example** (Plans That Survive a Page Reload)

```ts title="storage.ts"
import { Ensforge, Plan, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";

const publicClient = createPublicClient({ chain: sepolia, transport: http() });

export const ens = Ensforge.create({
  publicClient,
  storage: Plan.localStorage("my-app:plans"),
}).extend(ensActions());
```

After a reload, list what did not finish and resume it:

**Example** (Resuming Unfinished Plans)

```ts title="recover.ts"
import { Ensforge, Plan, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";

const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const ens = Ensforge.create({
  publicClient,
  storage: Plan.localStorage("my-app:plans"),
}).extend(ensActions());

const unfinished = await ens.plan.list({ status: "pending" });

for (const record of unfinished) {
  await ens.plan.resume({ id: record.plan.id });
}
```

## Write your own store [#write-your-own-store]

A store implements four Promise functions: `get`, `set`, `delete` and `list`. It holds `Plan.Record`
values, which contain `bigint`s, so a store that writes text needs a bigint-safe encoding.
`Plan.serialize` turns a record into text and `Plan.deserializeRecord` reads it back.

**Example** (A Key-Value Store)

```ts title="kv-storage.ts"
import { Plan } from "@ensforge/sdk";

type KeyValue = {
  get(key: string): Promise<string | null>;
  put(key: string, value: string): Promise<void>;
  delete(key: string): Promise<void>;
  keys(prefix: string): Promise<string[]>;
};

export const kvStorage = (kv: KeyValue, prefix = "ensforge:plan:"): Plan.Storage => ({
  get: async (id) => {
    const text = await kv.get(prefix + id);
    return text === null ? undefined : Plan.deserializeRecord(text);
  },
  set: (record) => kv.put(prefix + record.plan.id, Plan.serialize(record)),
  delete: (id) => kv.delete(prefix + id),
  list: async () => {
    const keys = await kv.keys(prefix);
    const texts = await Promise.all(keys.map((key) => kv.get(key)));
    return texts.flatMap((text) => (text === null ? [] : [Plan.deserializeRecord(text)]));
  },
});
```

- `set` stores the whole record as `Plan.serialize` text, which keeps bigints exact.
- `get` returns `undefined` for an unknown id. `plan.get` reports it as `null`.
- `list` returns every record.
- `Plan.deserializeRecord` throws [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) when the text is not a serialised record.

A store that keeps objects without text, such as IndexedDB or an in-process `Map`, needs none of
this.

## Serialise a plan [#serialise-a-plan]

Plans are plain data. `Plan.serialize` turns a plan or a record into JSON text with bigints
preserved. `Plan.deserialize` reads a plan back and `Plan.deserializeRecord` reads a record back. Use them to send a prepared plan to another
service, for review or signing elsewhere.

**Example** (Sending a Plan to Another Process)

```ts title="serialize.ts"
import { Ensforge, Plan, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";

const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const account = "0x225f137127d9067788314bc7fcc1f36746a3c3B5";
const ens = Ensforge.create({ publicClient, account }).extend(ensActions());

const plan = await ens.record.set.prepare({
  name: "ensforge-docs-demo.eth",
  texts: { url: "https://example.com" },
});

const text = Plan.serialize(plan);
const restored = Plan.deserialize(text);
```

`Plan.deserialize` throws [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) when the text is not a
serialised plan. A restored plan is for one chain and account: send it with
[`plan.send`](/docs/reference/sdk/plan/send) on a client for the same ones.

## Check the result [#check-the-result]

Start a write, reload the page or restart the process, and call `plan.list`. The plan should be
there with the steps already submitted.

## Troubleshooting [#troubleshooting]

### `PLAN_NOT_FOUND` [#plan_not_found]

The store has no plan with that id. With the default memory store, plans are lost on reload. See
[`PLAN_NOT_FOUND`](/docs/reference/errors/PLAN_NOT_FOUND).

### `localStorage is not available in this environment` [#localstorage-is-not-available-in-this-environment]

`Plan.localStorage()` ran where there is no `localStorage`. Use a custom store on the server.

### `PLAN_INVALID` [#plan_invalid]

The stored text is not a serialised plan or record. `Plan.localStorage()` rejects a broken record
with this error instead of returning bad data. Delete the entry, or clear the storage key. See
[`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID).

### Plans from two tabs overwrite each other [#plans-from-two-tabs-overwrite-each-other]

`Plan.localStorage` keeps every record under one key and rewrites the whole value on each save. Two
tabs writing at once can lose a record. Use a different key per tab, or a store that writes one row
per plan.