Create a client
Create an ensforge client from viem clients or a wagmi config, add the actions you need, and set options such as indexer and storage.
The client is the object you call ENS actions on. You create it once, at app start, from the
viem clients your app already has, then add groups of actions to it with extend.
Create a client for reads
A viem public client is all a client needs to read. Its chain selects the ENS contracts: ensforge ships them for Ethereum mainnet and Sepolia.
Example (Creating a Client for Reads)
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http("https://your-rpc.example") }),
}).extend(ensActions());
const name = await ens.primaryName.get({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" });Ensforge.createreturns a client with no actions yet.extend(ensActions())returns a new client with every ENS action on it. The original client is left unchanged: clients are frozen.
A viem client on another chain fails with UNKNOWN_CHAIN unless
you pass deployment. See Custom deployments.
Add a wallet for writes
Writes need a signer. Pass a viem wallet client as walletClient. Reads still go through the
public client.
Example (Adding a Wallet Client)
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, custom, http, type EIP1193Provider } from "viem";
import { sepolia } from "viem/chains";
declare const provider: EIP1193Provider; // e.g. window.ethereum
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ chain: sepolia, transport: custom(provider) }),
}).extend(ensActions());- When the public client was created with an
account, it is also used as the wallet, sowalletClientcan be left out. walletClientcan also be a function that returns the wallet, orundefinedwhile none is connected. ensforge calls it on every write, so a wallet that connects later works.- Without a wallet, writes fail with
WALLET_NOT_CONFIGURED. Reads keep working.
From a wagmi config
Apps on wagmi create the client with Ensforge.fromWagmi, from @ensforge/sdk/wagmi. Reads use
wagmi's client for the ENS chain. Writes use whichever wallet is connected when they run.
Example (Creating a Client From wagmi)
import { ensActions } from "@ensforge/sdk";
import { Ensforge } from "@ensforge/sdk/wagmi";
import { wagmiConfig } from "./wagmi"; // your app's createConfig(...)
const ens = Ensforge.fromWagmi(wagmiConfig).extend(ensActions());- The ENS chain is mainnet when the wagmi config has it, otherwise the first configured chain
ensforge has contracts for. Pass
{ chainId: 11155111 }to pick Sepolia. - A wallet connected to another chain is asked to switch first. Pass
{ switchChain: false }to turn that off. - Every other chain in the wagmi config is added to
chains, so a primary name on an L2 uses wagmi's client and wallet there. fromWagmitakes every option ofEnsforge.createexcept the viem clients.
It works with wagmi 2 (2.14 or later) and wagmi 3. For React apps, see Use with wagmi.
Add actions with extend
extend adds a group of actions and returns a new client. Choose the groups by what your app does.
| Decorator | From | Adds |
|---|---|---|
ensActions() | @ensforge/sdk | Every ENS action (ens.name, ens.record, ens.registration, …) and ens.batch. Not the indexer actions. |
recordActions(), nameActions(), … | @ensforge/sdk | One group each, for smaller bundles. There is one per group, plus batchActions(). |
indexerActions() | @ensforge/sdk/indexer (also @ensforge/sdk) | ens.indexer.*: lists, search and history. Needs an indexer. |
hcaActions() | @ensforge/hca | Smart-account actions (experimental). See HCA. |
Example (Adding Indexer Actions)
import { Ensforge, ensActions } from "@ensforge/sdk";
import { bigname, indexerActions } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
indexer: bigname(),
})
.extend(ensActions())
.extend(indexerActions());
const page = await ens.indexer.getNamesForAddress({
address: "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
});The indexer actions are a separate group because they need an indexer service. Calling them on a
client without indexer fails with
INDEXER_NOT_CONFIGURED. See
Name lists and indexers.
Example (Only the Record Actions)
import { Ensforge, recordActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(recordActions());
const url = await ens.record.getText({ name: "nick.eth", key: "url" });A client with only recordActions() has ens.record and nothing else, so the other groups stay out
of your bundle. See Keep bundles small.
Options
Every option except publicClient is optional.
| Option | Type | Default | Description |
|---|---|---|---|
publicClient | viem client | (required) | Client for reads. Its chain selects the ENS deployment. |
walletClient | viem wallet client, or a function returning one | publicClient when it has an account | Client for writes. A function is called on every write. |
account | Account | Address | the wallet client's account | Default signer for writes. A write's own account overrides it. |
chains | Record<chainId, { publicClient, walletClient? }> | none | Clients for other chains, for writes ENS makes there, such as a primary name on an L2. Without one, such writes fail with CHAIN_NOT_CONFIGURED. |
deployment | Deployments.Profile | the built-in deployment for the chain | ENS contract addresses. Required for devnets, forks and other chains. |
ccipRead | { gatewayUrls? } | false | the Universal Resolver's own batch gateway | Off-chain lookups (CCIP-Read): the batch gateways the Universal Resolver sends them through. false turns them off. |
batch | { multicall?: boolean | { batchSize?, wait? } } | { multicall: true } | Groups reads made at the same time into multicall requests. wait is in milliseconds. |
blockTag | BlockTag | "latest" | Block that reads run at. |
storage | Plan.Storage | Plan.memoryStorage() | Where multi-step writes save their plan progress. Use Plan.localStorage() to survive a reload. |
simulate | boolean | true | Simulate writes before the wallet prompt. |
indexer | Indexer | none | Indexer for indexer.* actions and for finding records and subnames during migration, from @ensforge/sdk/indexer. |
gateways | { ipfs?, arweave?, swarm? } | https://ipfs.io, https://arweave.net, https://api.gateway.ethswarm.org | HTTP gateways for avatars and website links. The public IPFS gateway is rate limited: set your own in production. |
See Configure RPC and gateways.
Example (Adding an L2 for Primary Names)
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, custom, http, type EIP1193Provider } from "viem";
import { base, mainnet } from "viem/chains";
declare const provider: EIP1193Provider;
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
walletClient: createWalletClient({ chain: mainnet, transport: custom(provider) }),
chains: {
[base.id]: {
publicClient: createPublicClient({ chain: base, transport: http() }),
walletClient: createWalletClient({ chain: base, transport: custom(provider) }),
},
},
}).extend(ensActions());
await ens.primaryName.set({ name: "ensforge-docs-demo.eth", coin: { chainId: base.id } });Each key of chains must match the chain of its clients. A mismatch fails at creation with
CHAIN_NOT_CONFIGURED. See Set a primary name.
What the client holds
Besides its actions, every client has a few fields you can read.
| Field | Description |
|---|---|
chain | { id, name } of the ENS chain. |
account | The default signer's address, or undefined without a wallet. |
deployment | The ENS contracts on this chain: addresses and what they support. |
publicClient | The viem client used for reads. |
config | The resolved options, with defaults filled in. |
extend | Adds a group of actions and returns a new client. |
These names are reserved: an action group cannot use them.
Use a bare viem client
Every action also accepts a plain viem client in place of an ensforge client. ensforge creates a client for it with default options on first use, and reuses it for later calls.
Example (Calling an Action With a viem Client)
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" });Ensforge.from(client) does the same in your own helpers: it returns an ensforge client for either
kind of client. See Ways to call actions.
Was this page helpful?