Config API

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

The createConfig function exported from @ponder/core returns the config object, which must be exported (named export called config) from ponder.config.ts.

File requirements

The createConfig function exported by @ponder/core returns a config object which must be the default export of ponder.config.ts. By default, ponder dev and start look for ponder.config.ts in the current working directory. You can use the --config-file CLI option to specify a different path.

ponder.config.ts

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

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.
maxHistoricalTaskConcurrency	`number \| undefined`	Default: `20`. (Deprecated) Maximum concurrency of tasks during the historical sync.

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 Add contracts 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.
maxBlockRange	`number \| undefined`	The maximum block range that Ponder will use when calling `eth_getLogs` during the historical sync. If not provided, Ponder uses a sane default based on the network.

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

Ponder uses a SQL database to cache blockchain data and store indexed data. In development, Ponder uses a SQLite database located at .ponder/store. In production, Ponder works best with a PostgreSQL database. If no database is specified in ponder.config.ts, Ponder will use SQLite unless either the DATABASE_PRIVATE_URL or DATABASE_URL environment variable is present, in which case it will use PostgreSQL with that connection string. If both DATABASE_PRIVATE_URL and DATABASE_URL are present, DATABASE_PRIVATE_URL will be used.

See Deploy to production for more details.

field	type
kind	`"sqlite" \| "postgres"`	Kind of database to use.
connectionString	`string \| undefined`	Default: `process.env.DATABASE_URL`. Postgres database connection string. Only used if `kind: "postgres"`.

Options

field	type
maxHealthcheckDuration	`number`	*Default: `4 60`**. Maximum number of seconds to wait for event processing to be complete before responding as healthy. If event processing takes longer than this amount of time, the GraphQL API may serve incomplete data.

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,
    },
  },
});

API reference Schema

Config API

File requirements

Networks

Contracts

Factory

Filter

Database

Options

Examples

Basic example

Using top-level await

Resources

More

Connect