Save and resume plans
Keep plan progress in browser storage or your own database, so a multi-step write survives reloads, crashes and restarts.
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
- Know what
plan.resumedoes. - Read How writes work for what a plan is.
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
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)
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)
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
A store implements four Promise functions: get, set, delete and list. It holds Plan.Record
values, which contain bigints, 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)
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)]));
},
});setstores the whole record asPlan.serializetext, which keeps bigints exact.getreturnsundefinedfor an unknown id.plan.getreports it asnull.listreturns every record.Plan.deserializeRecordthrowsPLAN_INVALIDwhen 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
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)
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 when the text is not a
serialised plan. A restored plan is for one chain and account: send it with
plan.send on a client for the same ones.
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
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.
localStorage is not available in this environment
Plan.localStorage() ran where there is no localStorage. Use a custom store on the server.
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.
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.
Was this page helpful?