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

Send a transaction

Send any ensforge write with a wallet client, read the transaction hash, and wait for the receipt when the next step needs it.

Every write in ensforge (record.set, registration.register, name.transfer and the rest) sends the same way. You pass a wallet, call the action, and read the transaction hash it returns.

Prerequisites

  • A client that can read and sign. See Create a client.
  • A name your account may change. Examples use Sepolia and the name ensforge-docs-demo.eth; replace it with a name you own.

1. Create a client with a wallet

A write needs a viem wallet client and the account that signs. ensforge reads the chain from the public client and checks that the wallet is on the same chain before it sends anything.

Example (A Sepolia client with a browser wallet)

client.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();

export const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions());
  • walletClient signs and sends. It can also be a function that returns the client, for wallets that connect later.
  • account is the default signer. Without it, and without an account on the wallet client, a write fails with ACCOUNT_NOT_FOUND.

2. Send the write

Call the action and wait for it to resolve. The Promise resolves once every transaction of the write is submitted, not mined.

Example (Setting a text record)

send.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());

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

record.set simulates the write first, so a revert becomes a typed error before the wallet prompt. It then asks the wallet to sign. The result holds:

FieldDescription
hashHash of the last transaction.
hashesEvery submitted transaction, in order. Writes with several steps, such as a registration, have more than one.
idThe EIP-5792 bundle id when the calls went out as one batch, otherwise undefined.
planThe plan that was sent. plan.id is what plan.resume needs.

3. Wait for the receipt

Use the …Sync form of an action when the next step depends on the transaction being mined. It takes the same options and adds confirmations and timeout.

Example (Waiting for two confirmations)

send-sync.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());

const { receipt, receipts } = await ens.record.setSync({
  name: "ensforge-docs-demo.eth",
  texts: { url: "https://example.com" },
  confirmations: 2,
  timeout: 120_000,
});

receipt.status; // "success"
  • confirmations is the number of confirmations to wait for per transaction. The default is 1.
  • timeout is the milliseconds to wait for each receipt. When it passes, the call fails with RECEIPT_TIMEOUT. The transaction may still land.
  • receipt is the receipt of the last transaction and receipts holds all of them.
  • A reverted transaction fails with TRANSACTION_REVERTED.

Follow progress

Pass onStep to see each step of a write wait, submit, confirm or fail. It is how a UI shows "Step 2 of 3".

Example (Logging every step)

progress.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());

await ens.record.setSync({
  name: "ensforge-docs-demo.eth",
  texts: { url: "https://example.com" },
  onStep: ({ step, status, hashes }) => {
    console.log(step.description, status, hashes);
  },
});

status is waiting while ensforge waits for chain time before a step (a registration waits at least a minute between its commit and register steps), submitted once the step's transactions are sent, confirmed once their receipts are in, and failed with the error. With setSync, the last step reports confirmed too.

Change how a write is sent

These options work on every write and every …Sync form.

OptionDefaultEffect
accountthe client's accountSigner for this write.
simulatetrue (the client's config.simulate)Simulate every call before the wallet prompt.
mode"auto""batch" sends one EIP-5792 call, "sequential" one transaction per call, "auto" batches when the wallet supports atomic batches. See Bundle transactions.
maxBundleCalls10Most calls in one wallet bundle.
signalnoneCancels before the next wallet prompt. Transactions already submitted are not undone.
onStepnoneCalled as each step waits, is submitted, is confirmed or fails.
vianoneSend through another route, such as a smart account. See Use smart accounts.
paymasternoneSponsor the gas with an EIP-5792 paymaster. See Pay gas for users.

An aborted write rejects with signal.reason, so its plan id is not on the error. Read it from plan.list when you need to resume.

Check the result

Read the change back with the matching read. After setSync resolves, the new value is on chain.

check.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());

const url = await ens.record.getText({ name: "ensforge-docs-demo.eth", key: "url" });

Troubleshooting

WALLET_NOT_CONFIGURED

The client has no wallet. Pass walletClient to Ensforge.create. See WALLET_NOT_CONFIGURED.

CHAIN_MISMATCH

The wallet is on another chain than the client. Switch the wallet's network or create the client for the wallet's chain. See CHAIN_MISMATCH.

USER_REJECTED

The user closed or rejected the wallet prompt. Nothing was sent. Treat it as a normal outcome, not a failure. See USER_REJECTED.

RECEIPT_TIMEOUT

setSync stopped waiting, but the transaction may still be pending. Check the hash before you send again. See RECEIPT_TIMEOUT.

INSUFFICIENT_ETH

The account cannot pay for the gas or value of a step. Every write can fail this way. Fund the account, or sponsor the gas with a paymaster. See INSUFFICIENT_ETH.

CONTRACT_NOT_DEPLOYED

The chain has no ENS contract at an address the write calls. Every action can fail this way when the client is on the wrong chain. See CONTRACT_NOT_DEPLOYED.

For the rest of the codes and when a retry is safe, see Handle errors.

Was this page helpful?