Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

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

What is saved

A saved plan is a Plan.Record:

FieldDescription
planThe plan: id, steps, calls, requirements, warnings, deployments and fees.
status"pending" while steps remain, "completed" once every step is submitted, "failed" after an error.
submittedTransaction hashes per submitted step id.
bundlesEIP-5792 bundle id per step sent in a bundle.
referencesRoute references per step sent through via, such as UserOperation hashes.
errorMessage of the last failure.
updatedAtUnix 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.

StoreSurvives reloadWhere it works
Plan.memoryStorage() (default)NoEverywhere. Lost when the process or page reloads.
Plan.localStorage(key?)YesBrowsers. 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.StorageYesAnywhere, such as a database or key-value store.

Example (Plans That Survive a Page Reload)

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)

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

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)

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 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

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)

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 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?