Config API

The ponder.config.ts file contains contract names, addresses, and ABIs; network information like chain IDs and RPC URLs; database configuration; and general options.

File requirements

The ponder.config.ts file must default export the object returned by createConfig.

ponder.config.ts

import { createConfig } from "ponder";
import { http } from "viem";
 
export default createConfig({
  networks: { /* ... */ },
  contracts: { /* ... */ },
});

By default, ponder dev and start look for ponder.config.ts in the current working directory. Use the --config-file CLI option to specify a different path.

Networks

The networks field is an object where each key is a network name containing that network's configuration. Networks are Ethereum-based blockchains like Ethereum mainnet, Goerli, or Foundry's local Anvil node.

⚠️

Most Ponder apps require a paid RPC provider plan to avoid rate-limiting.

field	type
name	`string`	A unique name for the blockchain. Must be unique across all networks. Provided as an object property name.
chainId	`number`	The chain ID for the network.
transport	`viem.Transport`	A Viem `http`, `webSocket`, or `fallback` Transport.
pollingInterval	`number \| undefined`	Default: `1_000`. Frequency (in ms) used when polling for new events on this network.
maxRequestsPerSecond	`number \| undefined`	Default: `50`. Maximum number of RPC requests per second. Can be reduced to work around rate limits.
disableCache	`boolean \| undefined`	Default: `false`. Disables the RPC request cache. Use when indexing a local node like Anvil.

ponder.config.ts

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

Contracts

💡

This is a low-level API reference. For an approachable overview & recipes, see the contracts & networks guide.

The contracts field is an object where each key is a contract name containing that contract's configuration. Ponder will sync & index logs or call traces according to the options you provide.

field	type
name	`string`	A unique name for the smart contract. Must be unique across all contracts. Provided as an object property name.
abi	`abitype.Abi`	The contract ABI as an array as const. Must be asserted as constant, see ABIType documentation for details.
network	`string`	The name of the network this contract is deployed to. References the `networks` field. Also supports multiple networks.
address	`0x{string} \| 0x{string}[] \| Factory \| undefined`	One or more contract addresses or factory configuration.
filter	`Filter`	Event filter criteria.
startBlock	`number \| undefined`	Default: `0`. Block number to start syncing events. Usually set to the contract deployment block number.
endBlock	`number \| undefined`	Default: `undefined`. Block number to stop syncing events. If this field is specified, the contract will not be indexed in realtime. This field can be used alongside `startBlock` to index a specific block range.
includeTransactionReceipts	`boolean \| undefined`	Default: `false`. If this field is `true`, `transactionReceipt` will be included in `event`.
includeCallTraces	`boolean \| undefined`	Default: `false`. If this field is `true`, each function in the abi will be available as an indexing function event name. See the call traces guide for details.

ponder.config.ts

import { createConfig } from "ponder";
 
import { BlitmapAbi } from "./abis/Blitmap";
 
export default createConfig({
  // ... more config
  contracts: {
    Blitmap: {
      abi: BlitmapAbi,
      network: "mainnet",
      address: "0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63",
      startBlock: 12439123,
    },
  },
});

Filter

field	type
event	`string \| string[] \| undefined`	Default: `undefined`. One or more event names present in the provided ABI.
args	`object \| undefined`	Default: `undefined`. An object containing indexed argument values to filter for. Only allowed if one event name was provided in `event`.

Accounts

The accounts field is an object similar to contracts where each key is an account name containing that account's configuration. Accounts are used to index transactions or native transfers.

field	type
name	`string`	A unique name for the smart contract. Must be unique across all contracts. Provided as an object property name.
network	`string`	The name of the network this contract is deployed to. References the `networks` field. Also supports multiple networks.
address	`0x{string} \| 0x{string}[] \| Factory \| undefined`	Address or factory configuration.
startBlock	`number \| undefined`	Default: `0`. Block number to start syncing events.
endBlock	`number \| undefined`	Default: `undefined`. Block number to stop syncing events. If this field is specified, the contract will not be indexed in realtime. This field can be used alongside `startBlock` to index a specific block range.
includeTransactionReceipts	`boolean \| undefined`	Default: `false`. If this field is `true`, `transactionReceipt` will be included in `event`.

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  // ... more config
  accounts: {
    coinbasePrime: {
      network: "mainnet",
      address: "0xCD531Ae9EFCCE479654c4926dec5F6209531Ca7b",
      startBlock: 12111233,
    },
  },
});

Blocks

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  // ... more config
  blocks: {
    ChainlinkPriceOracle: {
      network: "mainnet",
      startBlock: 19_750_000,
      interval: 5, // every minute
    },
  },
});

`factory()`

The factory() function is used to specify if an address is derived from the log of another contract. Both contracts and accounts support factory() in their address field.

field	type
address	`0x{string} \| 0x{string}[]`	The address of the factory contract that creates instances of this contract.
event	`AbiEvent`	The ABI item of the event that announces the creation of a new child contract.
parameter	`string`	The name of the parameter within `event` that contains the address of the new child contract.

Database

Here is the logic Ponder uses to determine which database to use:

If the database.kind option is specified, use the specified database.
If the DATABASE_URL environment variable is defined, use Postgres with that connection string.
If DATABASE_URL is not defined, use PGlite.

PGlite

field	type
kind	`"pglite"`
directory	`string \| undefined`	Default: `.ponder/pglite`. Directory path to use for PGlite database files.

Example ponder.config.ts using PGlite

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  database: {
    kind: "pglite",
    directory: "./.ponder/pglite",
  },
  // ... more config
});

Postgres

field	type
kind	`"postgres"`
connectionString	`string \| undefined`	Default: `DATABASE_URL` env var. Postgres database connection string.
poolConfig	`PoolConfig` \| `undefined`	Default: `{ max: 30 }`. Pool configuration passed to `node-postgres`.

Example ponder.config.ts using Postgres

ponder.config.ts

import { createConfig } from "ponder";
 
export default createConfig({
  database: {
    kind: "postgres",
    connectionString: "postgresql://user:password@localhost:5432/dbname",
    poolConfig: {
      max: 100,
    },
  },
  // ... more config
});

Examples

Basic example

ponder.config.ts

import { createConfig } from "ponder";
import { http } from "viem";
 
import { ArtGobblersAbi } from "./abis/ArtGobblers";
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: http(process.env.PONDER_RPC_URL_1),
    },
  },
  contracts: {
    ArtGobblers: {
      network: "mainnet",
      abi: ArtGobblersAbi,
      address: "0x60bb1e2aa1c9acafb4d34f71585d7e959f387769",
      startBlock: 15863321,
    },
  },
});

Using top-level await

ponder.config.ts

import { createConfig } from "ponder";
 
import { ArtGobblersAbi } from "./abis/ArtGobblers";
 
const startBlock = await fetch("http://...");
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: http(process.env.PONDER_RPC_URL_1),
    },
  },
  contracts: {
    ArtGobblers: {
      network: "mainnet",
      abi: ArtGobblersAbi,
      address: "0x60bb1e2aa1c9acafb4d34f71585d7e959f387769",
      startBlock,
    },
  },
});

replaceBigInts ponder.schema.ts

Config API

File requirements

Networks

Contracts

Filter

Accounts

Blocks

`factory()`

Database

PGlite

Postgres

Examples

Basic example

Using top-level await

Resources

More

Connect