Chains

Configure chain IDs and RPC endpoints

Use the chains field in ponder.config.ts to configure chain IDs and names, RPC endpoints, and connection options.

This guide describes each configuration option and suggests patterns for common use cases. Visit the config API reference for more information.

Example

This config sets up two chains: Ethereum mainnet and Optimism.

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  chains: {
    mainnet: {
      id: 1,
      rpc: process.env.PONDER_RPC_URL_1,
    },
    optimism: {
      id: 10,
      rpc: [
        process.env.PONDER_RPC_URL_10,
        "https://optimism.llamarpc.com",
      ],
    },
  },
  contracts: { /* ... */ },
});

Name

Each chain must have a unique name, provided as a key to the chains object. The contract, account, and block interval chain options reference the chain name.

Within indexing functions, the context.chain.name property contains the chain name of the current event.

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  chains: {
    mainnet: { 
      id: 1,
      rpc: process.env.PONDER_RPC_URL_1,
    },
  },
  contracts: {
    Blitmap: {
      abi: BlitmapAbi,
      chain: "mainnet", 
      address: "0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63",
    },
  },
});

Chain ID

Use the id field to specify a unique Chain ID for each chain. Within indexing functions, the context.chain.id property contains the chain ID of the current event.

The indexing engine uses id in the cache key for RPC responses. To avoid cache issues, make sure id always matches the chain ID of the configured RPC endpoint.

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  chains: {
    mainnet: {
      id: 1, 
      rpc: "https://eth.llamarpc.com",
    },
  },
  contracts: { /* ... */ },
});

RPC endpoints

Use the rpc field to provide one or more RPC endpoints for each chain.

If you provide multiple endpoints, Ponder intelligently balances requests across them and uses fallback logic to improve reliability.

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  chains: {
    mainnet: {
      id: 1,
      rpc: "https://eth-mainnet.g.alchemy.com/v2/...", 
    },
  },
  contracts: { /* ... */ },
});

Custom transport

The rpc field also accepts a Viem Transport, which can be useful if you need more granular control over how RPC requests are made.

ponder.config.ts

import { createConfig } from "ponder";
import { http, fallback } from "viem"; 
 
export default createConfig({
  chains: {
    mainnet: {
      id: 1,
      transport: fallback([ 
        http("https://eth-mainnet.g.alchemy.com/v2/..."), 
        http("https://quaint-large-card.quiknode.pro/..."), 
      ]), 
    },
  },
});

Here are a few common transport options.

Polling interval

The pollingInterval option controls how frequently (in milliseconds) the indexing engine checks for a new block in realtime. The default is 1000 (1 second).

If you set pollingInterval greater than the chain's block time, it does not reduce RPC usage. The indexing engine still fetches every block to check for reorgs. The default is suitable for most chains.

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  chains: {
    mainnet: {
      id: 1,
      rpc: process.env.PONDER_RPC_URL_1,
      pollingInterval: 2_000, // 2 seconds
    },
  },
});

Requests per second

Use maxRequestsPerSecond to set an upper bound on the number of RPC requests the indexing engine will make in a 1-second bucket. The default is 50.

If you are running a large historical backfill, try increasing maxRequestsPerSecond until you start hitting rate limits. In practice, the indexing engine applies a soft cap of ~250 to avoid resource contention issues.

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  chains: {
    mainnet: {
      id: 1,
      rpc: process.env.PONDER_RPC_URL_1,
      maxRequestsPerSecond: 200, 
    },
  },
  // ...
});

Disable caching

Use the disableCache option to disable caching for RPC responses. The default is false.

Set this option to true when indexing a development node like Anvil, where the chain state / history may change. Read more about indexing Anvil.

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  chains: {
    anvil: {
      id: 31337,
      rpc: "http://127.0.0.1:8545",
      disableCache: true, 
    },
  },
});