`ponder.config.ts`

The ponder.config.ts config file contains smart contract addresses, paths to ABIs, RPC URLs, database config, and plugin config.

Some things to know:

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.

field	type
name	`string`	A unique name for the blockchain. Must be unique across all networks.
chainId	`number`	The chain ID (opens in a new tab) for the network.
rpcUrl	`string \| undefined`	An optional RPC URL for the network. If not provided, a public (heavily rate-limited) RPC provider will be used (not recommended).

Contracts

Contracts are smart contracts deployed to a network. Ponder will fetch all the event logs emitted by each contract defined here.

field	type
name	`string`	A unique name for the smart contract. Must be unique across all contracts in `ponder.config.ts`.
network	`string`	The name of the network this contract is deployed to. References the `networks.name` field.
abi	`string \| 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.
address	`string`	The contract address.
startBlock	`number \| undefined`	Default: `0`. The block number to start handling events for this contract. Usually the contract deployment block number. Default: `0`
endBlock	`number \| undefined`	Default: `undefined`. The optional block number to stop handling events for this contract. If this field is specified, Ponder will not listen to "live" events for this contract. This field can be used alongside `startBlock` to only process events for a range of blocks.
blockLimit	`number \| undefined`	Default: `50`. The maximum block range that Ponder will use when calling `eth_getLogs`.
isIndexed	`boolean \| undefined`	Default: `true`. Specifies if Ponder should process events for this contract. If `false`, Ponder will not fetch events for this contract, but it will still be available on the event handler `context.contracts`.

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.

field	type
kind	`"sqlite" \| "postgres"`	Database connector to be used.
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"`.

Plugins

Ponder has a work-in-progress plugin system. Currently, the graphql plugin provided by @ponder/graphql is the only official plugin, and it is required for all Ponder apps.

Examples

Basic example

ponder.config.ts

import type { PonderConfig } from "@ponder/core";
import { graphqlPlugin } from "@ponder/graphql";
 
export const config: PonderConfig = {
  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,
    },
  ],
  plugins: [graphqlPlugin()],
};

Async function

ponder.config.ts

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

Last updated on February 8, 2023

Create Ponder schema.graphql