Documentation
API reference
ponder.config.ts

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.

fieldtype
namestringA unique name for the blockchain. Must be unique across all networks. Provided as an object property name.
chainIdnumberThe chain ID for the network.
transportviem.TransportA Viem http, webSocket, or fallback Transport.
pollingIntervalnumber | undefinedDefault: 1_000. Frequency (in ms) used when polling for new events on this network.
maxRequestsPerSecondnumber | undefinedDefault: 50. Maximum number of RPC requests per second. Can be reduced to work around rate limits.
maxHistoricalTaskConcurrencynumber | undefinedDefault: 20. (Deprecated) Maximum concurrency of tasks during the historical sync.
disableCacheboolean | undefinedDefault: 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.

fieldtype
namestringA unique name for the smart contract. Must be unique across all contracts. Provided as an object property name.
abiabitype.AbiThe contract ABI as an array as const. Must be asserted as constant, see ABIType documentation for details.
networkstringThe name of the network this contract is deployed to. References the networks field.
address0x{string} | 0x{string}[]One more more contract addresses. Mutually exclusive with factory.
factoryFactory?Factory pattern configuration. Mutually exclusive with address.
filterFilter?Event filter criteria.
startBlocknumber | undefinedDefault: 0. Block number to start syncing events. Usually set to the contract deployment block number. Default: 0
endBlocknumber | undefinedDefault: 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.
maxBlockRangenumber | undefinedThe 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

fieldtype
addressstringThe address of the factory contract that creates instances of this contract.
eventAbiEventThe ABI item of the event that announces the creation of a new child contract.
parameterstringThe name of the parameter within event that contains the address of the new child contract.

Filter

fieldtype
eventstring | string[] | undefinedDefault: undefined. One or more event names present in the provided ABI.
argsobject | undefinedDefault: 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

fieldtype
kind"sqlite"
directorystring | undefinedDefault: .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

fieldtype
kind"postgres"
connectionStringstring | undefinedDefault: DATABASE_PRIVATE_URL or DATABASE_URL env var. Postgres database connection string.
schemastring | undefinedDefault: "public". Postgres schema to use for indexed data.
poolConfigPoolConfig | undefinedDefault: { 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

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