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 ensjs

Replace ensjs (@ensdomains/ensjs) public, wallet and subgraph actions with ensforge actions, with before and after code for each one.

ensjs and ensforge are both action libraries on top of viem, so the move is mostly renaming. The differences are that ensforge needs no chain wrapper, routes between ENSv1 and ENSv2 for you, has one record.set for all record writes, and fails with typed errors. This guide maps the ensjs 5.x actions.

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.

Prerequisites

  • An app using @ensdomains/ensjs.
  • @ensforge/sdk installed. See Installation.

1. Replace the client setup

ensjs needs addEnsContracts(chain) so the viem chain knows the ENS addresses. ensforge picks the deployment from the chain ID (Ethereum mainnet and Sepolia), so the chain stays a plain viem chain.

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

const client = createPublicClient({ chain: addEnsContracts(mainnet), transport: http() }); 
const publicClient = createPublicClient({ chain: mainnet, transport: http() }); 
const ens = Ensforge.create({ publicClient }).extend(ensActions()); 

ensjs actions are free functions you call with a client, and ensforge supports the same style: Actions.record.getAddress(publicClient, options). Use that form to keep your call sites close to what they were. See Ways to call actions.

2. Reads

ensjs read results are objects with a value, or null. ensforge returns the value.

reads.ts
import { getAddressRecord, getName, getTextRecord } from "@ensdomains/ensjs/public"; 

const record = await getAddressRecord(client, { name: "nick.eth" }); 
const address = record?.value ?? null; 
const address = await ens.record.getAddress({ name: "nick.eth" }); 

const url = await getTextRecord(client, { name: "nick.eth", key: "url" }); 
const url = await ens.record.getText({ name: "nick.eth", key: "url" }); 

const result = await getName(client, { address }); 
const primary = result?.match === true ? result.name : null; 
const primary = await ens.primaryName.get({ address }); 

primaryName.get returns the name only when it resolves back to the address, so the match check is built in.

ensjsensforge
getAddressRecord({ name, coin })record.getAddress({ name, coin })
getTextRecord({ name, key })record.getText
getContentHashRecord, getAbiRecordrecord.getContentHash, record.get with abi: true
getRecords({ name, texts, coins, contentHash, abi })record.get({ name, texts, addresses, contentHash, abi })
getName({ address })primaryName.get({ address })
getResolver({ name })resolver.get({ name })
resolveNameDataresolver.resolve({ name, data })
getAvailable, isRenewableregistration.isAvailable, or name.get (available, renewable)
getRegisterPrice, getRenewPriceregistration.getPrice, registration.getRenewalPrice
public/v1: getOwner, getExpiry, getWrapperDataname.get: owner, manager, registrant, expiry, wrapped
public/v2: getNameRegistries, getExpiry, getTokenId, getNameRolesAccounts …name.get, registry.get, role.get, permission.get
getSupportedInterfacesresolver.get: profiles lists what the resolver supports
dns: getDnsImportData, importDnsName, getDnsOwner, getDnsOffchainDatadns.getProof, dns.claim, dns.getStatus, dns.getOffchainResolver

You do not pick public/v1 or public/v2. ensforge finds which version a name lives on. See ENS versions under the hood.

3. Records in one call

getRecords maps directly. The coins option is addresses in ensforge, and the result has exactly the fields you asked for. ensjs returns texts as an array of { key, value }. ensforge returns an object keyed by the text key.

records.ts
const records = await getRecords(client, {
  name: "ens.eth",
  texts: ["com.twitter", "avatar"],
  contentHash: true,
}); 
const records = await ens.record.get({
  name: "ens.eth",
  texts: ["com.twitter", "avatar"],
  contentHash: true,
}); 

records.texts["com.twitter"]; // string | null

4. Writes

ensjs has one write per record kind (setTextRecord, setAddressRecord, setContentHashRecord, setAbiRecord), a setRecords for ENSv1 and ENSv2, and wallet actions you call with a wallet client. ensforge has record.set for all of them, and sends with the wallet you gave the client.

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

ensforge reads the name's resolver itself, so you do not pass resolverAddress. Writes resolve when submitted. The …Sync form waits for the receipt. See Send a transaction.

ensjsensforge
setTextRecord, setAddressRecord, setContentHashRecord, setAbiRecord, setRecords, clearRecordsrecord.set (clear: true deletes everything first)
commitName, registerNameregistration.register (one call runs commit, wait and register), registration.commit
renewNameregistration.renew
setPrimaryNameprimaryName.set
transferNamename.transfer
setResolverresolver.set
createSubname, deleteSubnamesubname.create, subname.remove
wrapName, unwrapName, setFuses, setChildFuseswrapper.wrap, wrapper.unwrap, wrapper.setFuses, wrapper.setChildFuses
grantRoles, revokeRoles, grantResolverRoles, revokeResolverRolesrole.grant, role.revoke
linkToNode, linkToRecordresolver.link
deploySubregistry, setSubregistry, setParentregistry.deploy, registry.attach

A registration does the commit, the wait and the register in one call, with progress through onStep. See Register a name.

5. Subgraph reads

ensjs queries ENS's subgraph through @ensdomains/ensjs/subgraph (getNamesForAddress, getSubnames, getNameHistory, getSubgraphRecords) and needs graphql. ensforge reads lists from an indexer you connect to the client.

ensjs subgraphensforge
getNamesForAddress, getResolvedNamesForAddressindexer.getNamesForAddress
getSubnamesindexer.getSubnames
getNameHistoryindexer.getHistory, or event.get over RPC
getSubgraphRecordsindexer.getRecords

See Connect an indexer and List names for an address.

6. Errors

ensjs throws viem and ensjs BaseErrors. ensforge throws Errors.* with stable codes. See Handle errors.

7. Know what behaves differently

  • Encoded labels. ensjs refuses [labelhash] labels. ensforge resolves the name.
  • A reverting resolver. ensjs throws when a resolver reverts or answers malformed data. ensforge reads no record.
  • Gateways. ensforge reports an unreachable or invalid gateway as a GatewayError. ensjs returns null.

Check the result

Compare old and new results for a few names, including one with no records. Values should match, and null should stay null.

Troubleshooting

UNKNOWN_CHAIN

The chain is not mainnet or Sepolia, or it was wrapped with addEnsContracts for a custom setup. Pass a plain viem chain, or give deployment. See UNKNOWN_CHAIN.

An ensjs option has no equivalent

ensjs resolverAddress, universalResolverAddress and similar overrides are not needed: ensforge reads them from the deployment. For a custom deployment, see Create a client.

Was this page helpful?