Networks

Configure chain IDs and transports

Use the networks field in ponder.config.ts to configure network names, chain IDs, RPC URLs, and transport 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 networks: Ethereum mainnet and Optimism.

ponder.config.ts

import { createConfig } from "ponder";
import { http, fallback } from "viem";
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: http(process.env.PONDER_RPC_URL_1),
    },
    optimism: {
      chainId: 10,
      transport: fallback([
        http(process.env.PONDER_RPC_URL_10),
        http("https://optimism.llamarpc.com"),
      ]),
      maxRequestsPerSecond: 25,
    },
  },
  contracts: { /* ... */ },
});

Name

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

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

ponder.config.ts

import { createConfig } from "ponder";
import { http } from "viem";
 
export default createConfig({
  networks: {
    mainnet: { 
      chainId: 1,
      transport: http(process.env.PONDER_RPC_URL_1),
    },
  },
  contracts: {
    Blitmap: {
      abi: BlitmapAbi,
      network: "mainnet", 
      address: "0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63",
    },
  },
});

Chain ID

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

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

ponder.config.ts

import { createConfig } from "ponder";
import { http } from "viem";
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1, 
      transport: http("https://eth.llamarpc.com"),
    },
  },
  contracts: { /* ... */ },
});

Transport

Use the transport field to provide a Viem Transport for each network. The indexing engine uses the transport you provide for all RPC requests.

ponder.config.ts

import { createConfig } from "ponder";
import { http } from "viem"; 
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: http("https://eth-mainnet.g.alchemy.com/v2/..."), 
    },
  },
  contracts: { /* ... */ },
});

Here are a few common transport options.

HTTP

Use the http transport to connect to an RPC endpoint over HTTP. Read the Viem docs for more details.

ponder.config.ts

import { createConfig } from "ponder";
import { http } from "viem"; 
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: http("https://eth-mainnet.g.alchemy.com/v2/..."), 
    },
  },
  contracts: { /* ... */ },
});

WebSocket

Use the webSocket transport to connect to an RPC endpoint over WebSocket. Read the Viem docs for more details.

ponder.config.ts

import { createConfig } from "ponder";
import { webSocket } from "viem"; 
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: webSocket("wss://eth-mainnet.g.alchemy.com/v2/..."), 
    },
  },
  contracts: { /* ... */ },
});

Fallback

The fallback transport accepts an ordered list of inner transports and automatically retries failed requests using the next transport in the list. Note that the order matters. Read the Viem docs for more details.

ponder.config.ts

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

Load balance

The loadBalance transport distributes requests across a list of inner transports in a round-robin scheme.

ponder.config.ts

import { createConfig, loadBalance } from "ponder"; 
import { http } from "viem";
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: loadBalance([ 
        http("https://eth.llamarpc.com"), 
        http("https://ethereum-rpc.publicnode.com"), 
        http("https://eth.merkle.io"), 
      ]), 
    },
  },
});

Rate limit

The rateLimit transport wraps an inner transport and applies a rate limit according to the requestsPerSecond option.

ponder.config.ts

import { createConfig, rateLimit } from "ponder"; 
import { http } from "viem";
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: rateLimit(http("https://eth.llamarpc.com"), { 
        requestsPerSecond: 10, 
      }), 
    },
  },
});

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 networks.

ponder.config.ts

import { createConfig } from "ponder";
import { http } from "viem";
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: http(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";
import { http } from "viem";
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: http(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";
import { http } from "viem";
 
export default createConfig({
  networks: {
    anvil: {
      chainId: 31337,
      transport: http("http://127.0.0.1:8545"),
      disableCache: true, 
    },
  },
});