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/core";
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/core";
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 contract data 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.
address	`0x{string} \| 0x{string}[]`	One more more contract addresses. Mutually exclusive with `factory`.
factory	`Factory?`	Factory pattern configuration. Mutually exclusive with `address`.
filter	`Filter?`	Event filter criteria.
startBlock	`number \| undefined`	Default: `0`. Block number to start syncing events. Usually set to the contract deployment block number. Default: `0`
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.

ponder.config.ts

import { createConfig } from "@ponder/core";
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,
    },
  },
});

Factory

field	type
address	`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.

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

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/core";
 
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/core";
 
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/core";
import { http } from "viem";
 
export default createConfig({
  networks: {
    mainnet: {
      chainId: 1,
      transport: http(process.env.PONDER_RPC_URL_1),
    },
  },
  contracts: {
    ArtGobblers: {
      network: "mainnet",
      abi: "./abis/ArtGobblers.json",
      address: "0x60bb1e2aa1c9acafb4d34f71585d7e959f387769",
      startBlock: 15863321,
    },
  },
});

Using top-level await

ponder.config.ts

import { createConfig } from "@ponder/core";
 
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: "./abis/ArtGobblers.json",
      address: "0x60bb1e2aa1c9acafb4d34f71585d7e959f387769",
      startBlock,
    },
  },
});

replaceBigInts ponder.schema.ts

Config API

File requirements

Networks

Contracts

Factory

Filter

Database

PGlite

Postgres

Examples

Basic example

Using top-level await

Resources

More

Connect