ponder.config.ts

ponder.config.ts

Ponder's configuration file file contains smart contract addresses, paths to ABIs, RPC URLs, and database connection details.

  • ponder.config.ts must provide a named export called config, not a default export.
  • By default, ponder {dev/start/codegen} looks for ponder.config.ts in the current working directory, but you can specify a different path with the --config-file option to ponder dev or ponder start.
  • The config variable exported by ponder.config.ts can be an object, a function, or a function returning a Promise (you can do async stuff to determine your config).

Fields

Networks

Networks are Ethereum-based blockchains like Ethereum mainnet, Goerli, or Foundry's local Anvil node. Each network has a name, chainId, and rpcUrl.

⚠️

The rpcUrl field is optional, but you will need to provide an RPC URL from a provider like Alchemy or Infura in order to use Ponder effectively in development or production.

fieldtype
namestringA unique name for the blockchain. Must be unique across all networks.
chainIdnumberThe chain ID (opens in a new tab) for the network.
rpcUrlstring | undefinedAn optional RPC URL for the network. If not provided, a public (heavily rate-limited) RPC provider will be used (not recommended).
pollingIntervalnumber | undefinedDefault: 1_000. Frequency (in ms) used when polling for new events on this network.
maxRpcRequestConcurrencynumber | undefinedDefault: 10. Maximum concurrency of RPC requests during the historical sync.

Contracts

Contracts are smart contracts deployed to a network. All contracts defined here will become available as ReadOnlyContract objects in the event context. Ponder will fetch and handle event logs emitted by all contracts with isLogEventSource: true (the default).

fieldtype
namestringA unique name for the smart contract. Must be unique across all contracts & filters.
networkstringThe name of the network this contract is deployed to. References the networks.name field.
abistring | any[]The contract ABI (opens in a new tab). Can be a path to a JSON file, the ABI as a string, or the ABI as a JavaScript Array.
addressstringThe contract address.
startBlocknumber | undefinedDefault: 0. Block number to start handling events. Usually set to the contract deployment block number. Default: 0
endBlocknumber | undefinedDefault: undefined. Block number to stop handling events. If this field is specified, Ponder will not listen to "live" events. This field can be used alongside startBlock to only process events for a range of blocks.
maxBlockRangenumber | undefinedThe maximum block range that Ponder will use when calling eth_getLogs. If not provided, Ponder uses a sane default for the network.
isLogEventSourceboolean | undefinedDefault: true. Specifies if events should be handled for this contract. If false, this contrat will still be available on the event handler context.contracts.

Filters

Filters are custom event log filters. Ponder will fetch and handle event logs that match the filter field.

fieldtype
namestringA unique name for the custom filter. Must be unique across all contracts & filters.
networkstringThe name of the network for this filter. References the networks.name field.
abistring | any[]An ABI (opens in a new tab) containing all events matched by this filter. Can be a path to a JSON file, the ABI as a string, or the ABI as a JavaScript Array.
filterFilterThe filter object, see Filter.
startBlocknumber | undefinedDefault: 0. Block number to start handling events. Default: 0
endBlocknumber | undefinedDefault: undefined. Block number to stop handling events. If this field is specified, Ponder will not listen to "live" events. This field can be used alongside startBlock to only process events for a range of blocks.
maxBlockRangenumber | undefinedThe maximum block range that Ponder will use when calling eth_getLogs. If not provided, Ponder uses a sane default for the network.

Filter

fieldtype
addressstring | string[] | undefinedDefault: undefined. A contract address or array of contract addresses to filter for.
eventAbiEvent | undefinedDefault: undefined. An ABIType AbiEvent (opens in a new tab) object. Can be constructed using the parseAbiItem (opens in a new tab) helper function.
argsany[] | undefinedDefault: undefined. An array of indexed argument values to filter for.

Database

Ponder uses a SQL database to cache blockchain data and store entity data. In development, Ponder uses a SQLite database located at .ponder/cache.db. In production, Ponder needs 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.

fieldtype
kind"sqlite" | "postgres"Database connector to be used.
filenamestring | undefinedDefault: .ponder/cache.db. Path to a SQLite database file. Only used if kind: "sqlite".
connectionStringstring | undefinedDefault: process.env.DATABASE_URL. Postgres database connection string. Only used if kind: "postgres".

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 type { Config } from "@ponder/core";
 
export const config: Config = {
  networks: [
    {
      name: "mainnet",
      chainId: 1,
      rpcUrl: 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
      }
    ]
  };
};