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
- An
Ensforge.createcall. See Create a client.
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)
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, andevent.getover long ranges, need an archive node and wideeth_getLogsranges. A provider that limits log ranges fails withLOG_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)
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.
| Option | Default | Description |
|---|---|---|
batch.multicall | true | false turns batching off. |
batch.multicall.batchSize | 16384 | Calldata bytes per multicall chunk. |
batch.multicall.wait | 0 | Milliseconds to wait for more reads before sending a chunk. |
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.
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
| Option | Default | Description |
|---|---|---|
blockTag | "latest" | Block tag for reads. A call can pass blockNumber or blockTag. |
simulate | true | Simulate writes before the wallet prompt. |
chains | none | Clients 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?