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/sdkinstalled next toviem. 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.
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)
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
| viem | ensforge | Notes |
|---|---|---|
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/ens | Name.normalize(name) | ensforge actions normalise their inputs already. |
These ensforge reads also take blockNumber or blockTag, gatewayUrls, strict and signal.
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 returnsnull. strictmeans something else. In ensforge,strict: truethrows aNotFoundErrorwhen data is missing instead of returningnull.- Errors carry codes. Every action throws
Errors.*classes with a stablecode, 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:
- Several records in one request with
record.get. See Get text records. - A whole profile for many names with
Actions.batch. See Look up many at once. - A name's owner, expiry and status in one call. See Get a name's owner, expiry and status.
- Writes: set records, register a name, transfer a name, and the rest of Register and manage.
For those, create a client once:
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?