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

Configure RPC and gateways

Choose RPC transports, off-chain lookup gateways, read batching and storage gateways for a production-ready ensforge client.

ensforge reads and writes through your viem clients and a few services around them. This guide covers each setting you may want to change before you go live.

Prerequisites

Use a dedicated RPC URL

ensforge makes the RPC requests your public client makes. Public endpoints are rate limited, which shows up as RATE_LIMITED or RPC_TIMEOUT. Give the public client a dedicated URL, and use viem's fallback transport to add a second provider.

Example (Two providers with fallback)

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

const publicClient = createPublicClient({
  chain: mainnet,
  transport: fallback([http("https://rpc-a.example.com"), http("https://rpc-b.example.com")]),
});

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

Two features need more from the RPC:

  • Plans simulate calls in order with eth_simulateV1. Without it, each call is simulated alone and a call that depends on an earlier one can fail in the simulation. See Preview before sending.
  • Reads at an old blockNumber, and event.get over long ranges, need an archive node and wide eth_getLogs ranges. A provider that limits log ranges fails with LOG_RANGE_TOO_LARGE. Use an indexer for history. See Connect an indexer.

Set off-chain lookup gateways

Some names keep their records off-chain and resolve through CCIP-Read (EIP-3668): the resolver names the gateway that holds its records. ensforge reads names through the Universal Resolver, which sends these lookups through a batch gateway. By default that is the Universal Resolver's own batch gateway. ccipRead.gatewayUrls sets the batch gateways instead, and ccipRead: false turns off-chain lookups off.

Example (Answering Lookups Locally)

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

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

const ens = Ensforge.create({
  publicClient,
  ccipRead: { gatewayUrls: ["x-batch-gateway:true"] },
});

x-batch-gateway:true makes viem answer the batch itself, so ensforge calls each resolver's gateway directly instead of going through a hosted batch gateway. A URL works too, for a batch gateway you run. A single call can override the client's gateways with gatewayUrls. When a gateway fails, the action throws a GatewayError such as GATEWAY_REQUEST_FAILED or GATEWAY_RESPONSE_INVALID. With ccipRead: false, reading an off-chain name fails with CCIP_READ_DISABLED. See Look up off-chain names.

Tune read batching

ensforge coalesces concurrent contract reads into Multicall3 calls (batching). It is on by default.

OptionDefaultDescription
batch.multicalltruefalse turns batching off.
batch.multicall.batchSize16384Calldata bytes per multicall chunk.
batch.multicall.wait0Milliseconds to wait for more reads before sending a chunk.
batching.ts
import { Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

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

const ens = Ensforge.create({
  publicClient,
  batch: { multicall: { batchSize: 8_192, wait: 10 } },
});

Lower batchSize if your provider rejects large calls. To batch reads yourself, see Look up many at once.

Set storage gateways

Avatars and content hashes point at decentralized storage (ipfs://, ar://, bzz://). record.getAvatar turns them into URLs a browser can load through gateways. The defaults are https://ipfs.io, https://arweave.net and https://api.gateway.ethswarm.org.

The public ipfs.io gateway is rate limited. Use a dedicated gateway in production.

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

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

const ens = Ensforge.create({
  publicClient,
  gateways: { ipfs: "https://gateway.pinata.cloud" },
});

A call's own gateways option overrides the client's. ContentHash.toGatewayUrl(uri, ens.config.gateways) reuses the client's gateways for content hashes.

Other defaults

OptionDefaultDescription
blockTag"latest"Block tag for reads. A call can pass blockNumber or blockTag.
simulatetrueSimulate writes before the wallet prompt.
chainsnoneClients for other chains, needed to set L2 primary names. Otherwise CHAIN_NOT_CONFIGURED.

Check the result

Read a name that needs a gateway, such as an off-chain name, and an avatar. Both should resolve without RATE_LIMITED or gateway errors.

Troubleshooting

RATE_LIMITED

The RPC provider is limiting requests. Use a dedicated URL or a fallback transport. See RATE_LIMITED.

Avatar URLs return HTTP 429

The default ipfs.io gateway is rate limited. Set gateways.ipfs.

CONTRACT_NOT_DEPLOYED

The chain has no ENS contracts at the addresses ensforge uses. Check the chain of your public client. See CONTRACT_NOT_DEPLOYED.

Was this page helpful?