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

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

If the database.kind option is specified, Ponder will use that database.
If the DATABASE_PRIVATE_URL environment variable is defined, Ponder will use Postgres with that as the connection string.
If the DATABASE_URL environment variable is defined, Ponder will use Postgres with that as the connection string.
If neither DATABASE_PRIVATE_URL nor DATABASE_URL are defined, Ponder will use SQLite.

For more details, see the guide on production deployments.

SQLite

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

Example ponder.config.ts using SQLite

ponder.config.ts

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

Postgres

field	type
kind	`"postgres"`
connectionString	`string \| undefined`	Default: `DATABASE_PRIVATE_URL` or `DATABASE_URL` env var. Postgres database connection string.
schema	`string \| undefined`	Default: `"public"`. Postgres schema to use for indexed data.
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",
    schema: "ponder_dev",
    poolConfig: {
      max: 100,
    },
  },
  // ... more config
});

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

Horizontal scaling ponder.schema.ts

Config API

File requirements

Networks

Contracts

Factory

Filter

Database

SQLite

Postgres

Options

Examples

Basic example

Using top-level await

Resources

More

Connect