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 (opens in a new tab) for the network.
transport	`viem.Transport`	A viem `http`, `webSocket`, or `fallback` Transport (opens in a new tab).
pollingInterval	`number \| undefined`	Default: `1_000`. Frequency (in ms) used when polling for new events on this network.
maxRpcRequestConcurrency	`number \| undefined`	Default: `10`. Maximum concurrency of RPC requests during the historical sync. Can be reduced to work around rate limits.

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 (opens in a new tab) as an array as const. Must be asserted as constant, see ABIType documentation (opens in a new tab) 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` (opens in a new tab)	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	`AbiEvent \| undefined`	Default: `undefined`. An ABIType `AbiEvent` (opens in a new tab) object. Can be constructed using the `parseAbiItem` (opens in a new tab) helper function.
args	`any[] \| undefined`	Default: `undefined`. An array of indexed argument values to filter for.

Database

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

See Deploy to production for more details.

field	type
kind	`"sqlite" \| "postgres"`	Database connector to use.
filename	`string \| undefined`	Default: `.ponder/cache.db`. Path to a SQLite database file. Only used if `kind: "sqlite"`.
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 const config = createConfig({
  networks: [
    {
      name: "mainnet",
      chainId: 1,
      transport: http(process.env.PONDER_RPC_URL_1),
    },
  ],
  contracts: [
    {
      name: "ArtGobblers",
      network: "mainnet",
      abi: "./abis/ArtGobblers.json",
      address: "0x60bb1e2aa1c9acafb4d34f71585d7e959f387769",
      startBlock: 15863321,
    },
  ],
});

Async function

ponder.config.ts

import type { Config } from "@ponder/core";
 
export const config: Config = async () => {
  const startBlock = await fetch("http://...");
 
  return {
    networks: [ /* ... */ ],
    contracts: [
      {
        name: "ArtGobblers",
        network: "mainnet",
        abi: "./abis/ArtGobblers.json",
        address: "0x60bb1e2aa1c9acafb4d34f71585d7e959f387769",
        startBlock: startBlock
      }
    ]
  };
};

Compared to subgraphs