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.x | 1.0 |
|---|---|
@ensforge/core (actions) and @ensforge/sdk (the Ensforge class) | One package, @ensforge/sdk. @ensforge/core is gone. |
new Ensforge({ network, publicClient }) or createConfig | Ensforge.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 receipt | Writes resolve once submitted with Write.Result (hash, hashes, id, plan). The …Sync form waits for receipts. |
writes: { simulation, confirmation } in the config | simulate 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/wagmi | Ensforge.fromWagmi from @ensforge/sdk/wagmi. |
HCA actions on sdk.hca | The @ensforge/hca package, as ens.hca.* and via: hca(). |
1. Update the packages
pnpm remove @ensforge/core
pnpm add @ensforge/sdk@latestAlso 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.
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.x | 1.0 |
|---|---|
network | Gone. The public client's chain picks the deployment, or pass deployment. |
walletClient | walletClient (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.confirmation | The …Sync form of a write, with confirmations and timeout. |
storage (workflow storage) | storage (plan storage). See Save and resume plans. |
indexer (GraphQL endpoints) or false | indexer: bigname(), goldsky(), fallback([...]) from @ensforge/sdk/indexer. Without it, no indexer. |
hca | The @ensforge/hca package. |
3. Reads
Reads return the value, not a wrapper. A missing value is null.
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 }); getAddresstookcoinType. 1.0 takescoin: a symbol ("btc"), a chain ({ chainId: 8453 }) or a coin type. See Get a name's address.getPrimaryNamereturned{ name, match }ornull. 1.0 returns the name, ornull, and checks that the name resolves back to the address by default (verify).name.getreturns the whole state in one call:owner,manager,registrant,expiry,resolver,wrapped,available,renewableand 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.
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.
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 actions | 1.0 |
|---|---|
records.get* | record.get, record.getText, record.getAddress, record.getAvatar, record.getContentHash |
records.set*, records.clearRecords, records.clearAvatar | record.set (null deletes a value; clear: true deletes everything first) |
name.getOwner, getManager, getRegistrant, getExpiry, getNameState, isWrapped, isMigrated … | name.get |
name.isAvailable | registration.isAvailable |
resolution.getResolver, resolve* | resolver.get, resolver.resolve |
records.setAlias, resolution.getAlias | resolver.link, resolver.getLink. See Resolvers and shared records. |
resolution.setResolver, setResolverAndRecords, createResolver, upgradeResolver | resolver.set, record.set({ resolver }), resolver.create, resolver.upgrade |
reverse.setPrimaryName, clearPrimaryName, setPrimaryNameForAddress, setContractPrimaryName | primaryName.set (name: null clears) |
registration.registerName(s), commitName, completeRegistration | registration.register (several names in one call), registration.commit; finish with the result's secret |
registration.getRegistrationPrice, getRenewalPrice, getCommitmentStatus | registration.getPrice, getRenewalPrice, getCommitmentStatus |
registration.renewName(s) | registration.renew |
ownership.transferName, transferRegistrant, reclaimName, setManager, setTtl | name.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.
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
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?