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

From ensforge 0.x

Move an app from ensforge 0.x (@ensforge/core and the Ensforge class) to the 1.0 client and actions, with before and after code.

ensforge 1.0 is a new API. Reads and writes are simpler and more uniform, and errors are typed by code. This guide maps every 0.x concept to its 1.0 form, with before and after code. The code marked before is the 0.x API as published in @ensforge/sdk@0.6.1 and @ensforge/core@0.6.1.

Code blocks that mark lines with [!code --] and [!code ++] are diffs: they show the old and the new line together, so the docs build does not compile them.

What changed

0.x1.0
@ensforge/core (actions) and @ensforge/sdk (the Ensforge class)One package, @ensforge/sdk. @ensforge/core is gone.
new Ensforge({ network, publicClient }) or createConfigEnsforge.create({ publicClient }). The chain of the public client picks the deployment.
Groups on the instance: sdk.records, sdk.name, sdk.resolution, sdk.reverse …Decorators you add: .extend(ensActions()). Groups are record, name, resolver, primaryName, registration, subname, wrapper and more.
One setter per record kind (setText, setAddress, setContentHash …)One action, record.set, with texts, addresses, contentHash and more.
Writes that waited for the receipt by default, with status, hash and receiptWrites resolve once submitted with Write.Result (hash, hashes, id, plan). The …Sync form waits for receipts.
writes: { simulation, confirmation } in the configsimulate and …Sync per call or per client.
Workflows (sdk.workflows)Plans (plan.get, plan.list, plan.resume).
ContractError, RpcError, NameError …Errors.* classes with stable codes.
createEnsforge from @ensforge/sdk/wagmi, or createWagmiConfig from @ensforge/core/wagmiEnsforge.fromWagmi from @ensforge/sdk/wagmi.
HCA actions on sdk.hcaThe @ensforge/hca package, as ens.hca.* and via: hca().

1. Update the packages

terminal
pnpm remove @ensforge/core
pnpm add @ensforge/sdk@latest

Also update @ensforge/react and @ensforge/contracts to 1.x. The public packages version together.

2. Create the client

The 0.x network option is gone. The public client's chain picks the deployment (Ethereum mainnet or Sepolia). For another chain, pass deployment.

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

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

const sdk = new Ensforge({ network: "mainnet", publicClient }); 
const ens = Ensforge.create({ publicClient }).extend(ensActions()); 

Other options moved too:

0.x1.0
networkGone. The public client's chain picks the deployment, or pass deployment.
walletClientwalletClient (also a function for wallets that connect later)
reads: { concurrency, multicallBatchSize }batch: { multicall: { batchSize, wait } }. See Configure RPC and gateways.
gateways (allowed hosts and limits for gateway requests)No counterpart. 1.0 gateways sets storage gateways for avatars and content hashes, and ccipRead sets the off-chain lookup gateways.
writes.simulation: "required" | "skip"simulate: true | false
writes.confirmationThe …Sync form of a write, with confirmations and timeout.
storage (workflow storage)storage (plan storage). See Save and resume plans.
indexer (GraphQL endpoints) or falseindexer: bigname(), goldsky(), fallback([...]) from @ensforge/sdk/indexer. Without it, no indexer.
hcaThe @ensforge/hca package.

3. Reads

Reads return the value, not a wrapper. A missing value is null.

reads.ts
const { address } = await sdk.records.getAddress({ name: "nick.eth" }); 
const address = await ens.record.getAddress({ name: "nick.eth" }); 

const { owner } = await sdk.name.getOwner({ name: "nick.eth" }); 
const { owner } = await ens.name.get({ name: "nick.eth" }); 

const primary = await sdk.reverse.getPrimaryName({ address }); 
const primary = await ens.primaryName.get({ address }); 
  • getAddress took coinType. 1.0 takes coin: a symbol ("btc"), a chain ({ chainId: 8453 }) or a coin type. See Get a name's address.
  • getPrimaryName returned { name, match } or null. 1.0 returns the name, or null, and checks that the name resolves back to the address by default (verify).
  • name.get returns the whole state in one call: owner, manager, registrant, expiry, resolver, wrapped, available, renewable and more. The single-fact reads of 0.x (getOwner, getExpiry, isWrapped …) map to its fields. See Get a name's owner, expiry and status.

Batched reads

readBatch returned a record of values. batch returns { results }, where each result is { status: "success", result } or { status: "failure", error } by default. readBatchSettled returned { status, value } outcomes; 1.0 names the field result.

batch.ts
const profile = await sdk.batch.readBatch({
  owner: sdk.name.getOwner.request({ name: "nick.eth" }), 
}); 
const { results } = await ens.batch({
  requests: { owner: Actions.name.get.request({ name: "nick.eth" }) }, 
  allowFailure: false, 
}); 

Actions comes from @ensforge/sdk. Settled results are now the default (allowFailure: true), and allowFailure: false behaves like readBatch. See Look up many at once.

4. Writes

One record.set replaces the setters. 0.x writes waited for the receipt by default (confirmation: { type: "confirmed" }). 1.0 writes resolve once submitted. Use …Sync to wait for the receipt, as the examples below do.

writes.ts
await sdk.records.setText({
  name: "ensforge-docs-demo.eth",
  key: "url",
  value: "https://example.com",
}); 
await ens.record.setSync({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } }); 

await sdk.records.setAddress({ name: "ensforge-docs-demo.eth", coinType: 60n, address }); 
await ens.record.setSync({ name: "ensforge-docs-demo.eth", addresses: { eth: address } }); 

See Set records and Send a transaction.

Where each 0.x action went

0.x group and actions1.0
records.get*record.get, record.getText, record.getAddress, record.getAvatar, record.getContentHash
records.set*, records.clearRecords, records.clearAvatarrecord.set (null deletes a value; clear: true deletes everything first)
name.getOwner, getManager, getRegistrant, getExpiry, getNameState, isWrapped, isMigrated …name.get
name.isAvailableregistration.isAvailable
resolution.getResolver, resolve*resolver.get, resolver.resolve
records.setAlias, resolution.getAliasresolver.link, resolver.getLink. See Resolvers and shared records.
resolution.setResolver, setResolverAndRecords, createResolver, upgradeResolverresolver.set, record.set({ resolver }), resolver.create, resolver.upgrade
reverse.setPrimaryName, clearPrimaryName, setPrimaryNameForAddress, setContractPrimaryNameprimaryName.set (name: null clears)
registration.registerName(s), commitName, completeRegistrationregistration.register (several names in one call), registration.commit; finish with the result's secret
registration.getRegistrationPrice, getRenewalPrice, getCommitmentStatusregistration.getPrice, getRenewalPrice, getCommitmentStatus
registration.renewName(s)registration.renew
ownership.transferName, transferRegistrant, reclaimName, setManager, setTtlname.transfer (role: "registrant"), name.reclaim, name.setManager, name.setTtl
subnames.*subname.create, subname.update, subname.remove
wrapping.*wrapper.wrap, unwrap, getFuses, setFuses, setChildFuses
migration.*migration.get, migration.migrate
dns.*dns.getStatus, dns.claim, dns.getProof, dns.getRecords, dns.setRecords
events.*event.get, event.watch, event.decode
permissions.*, capabilities.*permission.check, permission.get, permission.setRecordAccess, role.get, role.grant, role.revoke, approval.*
indexer.*indexer.* (19 actions; add indexerActions())
batch.prepareCalls, simulateCalls, estimateCalls, sendCalls, executeWritePlan.prepare, .simulate, .estimateGas on any write, and plan.send. See Preview before sending.
batch.getCallsStatus, resumeCalls, workflows.*plan.get, plan.list, plan.resume, plan.reconcile. See Continue after a failure.
hca.*, hcaAdmin@ensforge/hca. See Use smart accounts.

Some 0.x helpers, such as resolution.predictResolverAddress and name.getProtocol, have no action of their own in 1.0: resolver.create.prepare returns the address in plan.deploys, and name.get returns protocol. Browse the reference for what exists.

5. Errors

0.x errors were Effect TaggedErrors per area (ContractError, RpcError, NameError, TransactionError …) with codes such as REVERTED. 1.0 errors are Errors.* classes with stable codes (CONTRACT_REVERTED, NOT_OWNER, RECORD_NOT_FOUND) that Promise and Effect users receive as the same instance.

errors.ts
if (error._tag === "ContractError" && error.code === "REVERTED") {
  /* … */
} 
if (Errors.hasCode("CONTRACT_REVERTED")(error)) {
  /* … */
} 

Each action now documents its errors, and Errors.describe gives user-safe copy. See Handle errors.

6. wagmi

wagmi.ts
import { createEnsforge } from "@ensforge/sdk/wagmi"; 
import { Ensforge } from "@ensforge/sdk/wagmi"; 
import { ensActions } from "@ensforge/sdk"; 

const sdk = createEnsforge({ network: "mainnet", wagmiConfig }); 
const ens = Ensforge.fromWagmi(wagmiConfig).extend(ensActions()); 

Ensforge.fromWagmi(config, { chainId?, switchChain? }) reads through wagmi's transports and writes through the connected wallet, switching chain when needed.

7. Effect users

0.x actions in @ensforge/core returned Effects. In 1.0 the Effect API is @ensforge/sdk/effect, and Promises are the default. See The Effect API.

Check the result

Build and run your tests. TypeScript flags every renamed action and option. Read a name, change a record on Sepolia, and confirm the read-back.

Troubleshooting

ens.records is undefined

The group is called record in 1.0. See the table above.

UNKNOWN_CHAIN

0.x took network: "mainnet". In 1.0 the public client needs a chain, or you pass deployment. See UNKNOWN_CHAIN.

Receipts are missing from a write result

Writes resolve on submission. Use the …Sync form for receipt and receipts.

Was this page helpful?