# Configure RPC and gateways

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

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

Source: https://ensforge.com/docs/sdk/rpc-and-gateways

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 [#prerequisites]

- An `Ensforge.create` call. See [Create a client](/docs/sdk/create-a-client).

## Use a dedicated RPC URL [#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`](/docs/reference/errors/RATE_LIMITED) or
[`RPC_TIMEOUT`](/docs/reference/errors/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)

```ts title="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](/docs/sdk/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`](/docs/reference/errors/LOG_RANGE_TOO_LARGE). Use an indexer for history. See
  [Connect an indexer](/docs/sdk/connect-an-indexer).

## Set off-chain lookup gateways [#set-off-chain-lookup-gateways]

Some names keep their records off-chain and resolve through [CCIP-Read](/docs/reference/glossary#ccip-read)
(EIP-3668): the resolver names the [gateway](/docs/reference/glossary#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)

```ts title="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`](/docs/reference/errors/GATEWAY_REQUEST_FAILED) or
[`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID). With `ccipRead: false`,
reading an off-chain name fails with [`CCIP_READ_DISABLED`](/docs/reference/errors/CCIP_READ_DISABLED).
See [Look up off-chain names](/docs/sdk/off-chain-names).

## Tune read batching [#tune-read-batching]

ensforge coalesces concurrent contract reads into Multicall3 calls ([batching](/docs/reference/glossary#batch)). 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. |

```ts title="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](/docs/sdk/look-up-many-at-once).

## Set storage gateways [#set-storage-gateways]

[Avatars](/docs/reference/glossary#avatar) and content hashes point at decentralized storage (`ipfs://`, `ar://`, `bzz://`).
[`record.getAvatar`](/docs/reference/sdk/record/get-avatar) 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.

```ts title="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 [#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`](/docs/reference/errors/CHAIN_NOT_CONFIGURED). |

## Check the result [#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 [#troubleshooting]

### `RATE_LIMITED` [#rate_limited]

The RPC provider is limiting requests. Use a dedicated URL or a `fallback` transport. See
[`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED).

### Avatar URLs return HTTP 429 [#avatar-urls-return-http-429]

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

### `CONTRACT_NOT_DEPLOYED` [#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`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED).