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 viem's ENS actions

Replace viem's getEnsAddress, getEnsName, getEnsAvatar, getEnsText and getEnsResolver with ensforge actions, and see what changes.

ensforge is built on viem and takes viem clients, so you can move one call at a time. viem's ENS actions cover reads. ensforge adds the same reads with typed errors, plus records in one call, lists, and every write. You keep your viem transports and wallet.

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 that calls viem's ENS actions.
  • @ensforge/sdk installed next to viem. See Installation.

1. Start with a bare viem client

Every ensforge action takes a client first, and a viem public client is accepted as it is. You do not have to create an ensforge client to replace a read.

addresses.ts
import { getEnsAddress } from "viem/actions"; 
import { Actions } from "@ensforge/sdk"; 
import { normalize } from "viem/ens"; 

const address = await getEnsAddress(publicClient, { name: normalize("nick.eth") }); 
const address = await Actions.record.getAddress(publicClient, { name: "nick.eth" }); 

ensforge normalises the name for you, so you can drop normalize.

Example (The same read, after)

addresses.ts
import { Actions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

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

const address = await Actions.record.getAddress(publicClient, { name: "nick.eth" });

2. Map each action

viemensforgeNotes
getEnsAddress({ name, coinType })record.getAddress({ name, coin })coin is a symbol ("btc"), a chain ({ chainId: 8453 }) or a coin type. Default is Ethereum.
getEnsName({ address })primaryName.get({ address })Checks that the name resolves back to the address by default.
getEnsAvatar({ name })record.getAvatar({ name })Returns a URL a browser can load. Set storage gateways with gateways.
getEnsText({ name, key })record.getText({ name, key })
getEnsResolver({ name })resolver.get({ name })Returns the resolver's address, its kind, who may write to it and its profiles.
normalize(name) from viem/ensName.normalize(name)ensforge actions normalise their inputs already.

These ensforge reads also take blockNumber or blockTag, gatewayUrls, strict and signal.

reads.ts
const name = await getEnsName(publicClient, { address }); 
const name = await Actions.primaryName.get(publicClient, { address }); 

const avatar = await getEnsAvatar(publicClient, { name: "nick.eth" }); 
const avatar = await Actions.record.getAvatar(publicClient, { name: "nick.eth" }); 

const resolver = await getEnsResolver(publicClient, { name: "nick.eth" }); 
const resolver = (await Actions.resolver.get(publicClient, { name: "nick.eth" }))?.address; 

3. Know what behaves differently

  • Gateway failures are errors. For an off-chain name whose gateway is unreachable or invalid, ensforge throws a GatewayError (GATEWAY_REQUEST_FAILED, GATEWAY_RESPONSE_INVALID). viem returns null.
  • strict means something else. In ensforge, strict: true throws a NotFoundError when data is missing instead of returning null.
  • Errors carry codes. Every action throws Errors.* classes with a stable code, so you can branch without parsing messages. See Handle errors.
  • A name with a resolver that reverts reads as empty, as in viem. Neither reads a record in that case.

4. Use what viem does not have

Once reads work, move to the parts viem has no action for:

For those, create a client once:

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

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

export const ens = Ensforge.create({ publicClient }).extend(ensActions());

await ens.record.getAddress({ name: "nick.eth" });

Check the result

Compare the old and the new result for a few names you know, such as nick.eth and one without an avatar. The values should match. A GatewayError instead of null for an off-chain name is the one expected difference.

Troubleshooting

UNKNOWN_CHAIN

The viem client's chain is not Ethereum mainnet or Sepolia. Create an ensforge client with deployment. See UNKNOWN_CHAIN.

A read that returned null in viem throws

You passed strict: true, or the name is off-chain and its gateway failed. See RECORD_NOT_FOUND and GATEWAY_REQUEST_FAILED.

Was this page helpful?