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

Continue after a failure

Resume a multi-step write that stopped part-way with plan.resume, without sending the steps that already finished a second time.

A registration or a migration is several transactions, grouped in a plan. When one fails, or the page reloads in the middle, plan.resume finishes the rest and skips what already landed.

Prerequisites

How a plan is tracked

Every write saves its progress to the client's storage after each submission. A failed write keeps the record, so you can continue it.

stateDiagram-v2
  [*] --> pending: write starts
  pending --> pending: step submitted
  pending --> failed: a step fails
  failed --> pending: plan.resume
  pending --> completed: last step submitted
  completed --> [*]

1. Find the plan id

A failure carries the id of its plan in error.context.planId, and error.context.step names the step that failed. A write that finished has it on result.plan.id.

Example (Catching a failed registration)

catch.ts
import type { EIP1193Provider } from "viem";

declare global {
  interface Window {
    ethereum?: EIP1193Provider;
  }
}

import { Duration, Ensforge, Errors, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, custom, http } from "viem";
import { sepolia } from "viem/chains";

const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) });
const [account] = await walletClient.requestAddresses();
const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions());

let planId: string | undefined;
try {
  await ens.registration.register({ names: "ensforge-docs-demo.eth", duration: Duration.years(1) });
} catch (error) {
  if (Errors.is(error)) planId = error.context.planId;
}

An aborted write (signal) rejects with signal.reason, which has no plan id. Look the plan up with plan.list, newest first.

Example (Listing plans that did not finish)

list.ts
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";

const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const account = "0xA11Ce00000000000000000000000000000000000"; // the account that sent the plans
const ens = Ensforge.create({ publicClient, account }).extend(ensActions());

const failed = await ens.plan.list({ account, status: "failed" });

2. Look at the progress

plan.get returns the saved record, or null when no plan has that id.

get.ts
import { Ensforge, 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 }).extend(ensActions());
declare const planId: string;

const record = await ens.plan.get({ id: planId });

record?.status; // "pending" | "completed" | "failed"
record?.submitted; // transaction hashes per step id
record?.error; // message of the last failure

3. Resume the plan

plan.resume continues the plan and resolves once the remaining transactions are submitted. Use plan.resumeSync to wait for the receipts.

Example (Resuming and waiting)

resume.ts
import type { EIP1193Provider } from "viem";

declare global {
  interface Window {
    ethereum?: EIP1193Provider;
  }
}

import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, custom, http } from "viem";
import { sepolia } from "viem/chains";

const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) });
const [account] = await walletClient.requestAddresses();
const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions());
declare const planId: string;

const { receipts } = await ens.plan.resumeSync({ id: planId });

What resuming does:

  • A step submitted before is confirmed, not sent again.
  • A transaction that was dropped, or a bundle that failed, is sent again.
  • Each remaining step is simulated against current state right before it is sent, because the earlier steps already changed it.
  • A plan for another chain, such as an L2 primary name, resumes on that chain's clients from the client's chains.

Resume takes the usual write options, such as onStep, mode and account.

Register again with the same secret

A registration has a second way to continue. The result of registration.register carries a secret. Call it again with the same options and that secret to finish the registration. The options are part of the commitment, so they must match exactly.

Record a transaction sent elsewhere

When you sent a step's transaction outside ensforge, tell the plan with plan.reconcile, passing the plan id, the step id and the hash. Resuming then treats the step as submitted.

Check the result

After resumeSync resolves, plan.get reports status: "completed", and receipts includes the steps that were submitted before.

Troubleshooting

PLAN_NOT_FOUND

The storage has no plan with that id. The default memory storage forgets plans on reload. Pass Plan.localStorage() or your own storage. See PLAN_NOT_FOUND.

PLAN_ROUTE_REQUIRED

Some steps were sent through a route (via), such as a smart account. Only that route can follow them, and sending them again from the wallet would run them twice. Pass the same via to plan.resume. See PLAN_ROUTE_REQUIRED.

PLAN_CHAIN_MISMATCH or PLAN_ACCOUNT_MISMATCH

The plan was prepared for another chain or account than the client's. Resume it with the client and account that started it. See PLAN_CHAIN_MISMATCH and PLAN_ACCOUNT_MISMATCH.

COMMITMENT_TOO_OLD

A resumed registration passed the registrar's commitment window. Start the registration again. See COMMITMENT_TOO_OLD.

Was this page helpful?