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/sdkinstalled. 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.
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.
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.
| ensjs | ensforge |
|---|---|
getAddressRecord({ name, coin }) | record.getAddress({ name, coin }) |
getTextRecord({ name, key }) | record.getText |
getContentHashRecord, getAbiRecord | record.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 }) |
resolveNameData | resolver.resolve({ name, data }) |
getAvailable, isRenewable | registration.isAvailable, or name.get (available, renewable) |
getRegisterPrice, getRenewPrice | registration.getPrice, registration.getRenewalPrice |
public/v1: getOwner, getExpiry, getWrapperData | name.get: owner, manager, registrant, expiry, wrapped |
public/v2: getNameRegistries, getExpiry, getTokenId, getNameRolesAccounts … | name.get, registry.get, role.get, permission.get |
getSupportedInterfaces | resolver.get: profiles lists what the resolver supports |
dns: getDnsImportData, importDnsName, getDnsOwner, getDnsOffchainData | dns.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.
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 | null4. 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.
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.
| ensjs | ensforge |
|---|---|
setTextRecord, setAddressRecord, setContentHashRecord, setAbiRecord, setRecords, clearRecords | record.set (clear: true deletes everything first) |
commitName, registerName | registration.register (one call runs commit, wait and register), registration.commit |
renewName | registration.renew |
setPrimaryName | primaryName.set |
transferName | name.transfer |
setResolver | resolver.set |
createSubname, deleteSubname | subname.create, subname.remove |
wrapName, unwrapName, setFuses, setChildFuses | wrapper.wrap, wrapper.unwrap, wrapper.setFuses, wrapper.setChildFuses |
grantRoles, revokeRoles, grantResolverRoles, revokeResolverRoles | role.grant, role.revoke |
linkToNode, linkToRecord | resolver.link |
deploySubregistry, setSubregistry, setParent | registry.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 subgraph | ensforge |
|---|---|
getNamesForAddress, getResolvedNamesForAddress | indexer.getNamesForAddress |
getSubnames | indexer.getSubnames |
getNameHistory | indexer.getHistory, or event.get over RPC |
getSubgraphRecords | indexer.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 returnsnull.
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?