Ponder: EVM Data Indexing Framework

Common errors

• Error: Ponder requires Node.js version >=18.14.

  cause The installed Node.js version is older than Ponder's minimum requirement.
  fix Upgrade Node.js to version 18.14 or newer using a version manager like `nvm` or `volta`.

• TS2307: Cannot find module 'ponder:registry' or its corresponding type declarations.

  cause TypeScript compiler or IDE cannot resolve Ponder's virtual modules, often due to a missing or outdated `ponder-env.d.ts` file or incorrect `tsconfig.json` configuration.
  fix Ensure `ponder-env.d.ts` is present in your project root and accept any changes Ponder's dev server suggests. Verify `tsconfig.json` is correctly configured to include this file.

• Error: Start block number (XXXX) cannot be greater than latest block number (YYYY). Are you sure the RPC endpoint is for the correct network?

  cause The RPC URL configured for a chain is either incorrect, points to a different network than expected, or the RPC provider is returning stale or invalid data.
  fix Double-check the RPC URL and `chain.id` in `ponder.config.ts`. Confirm the RPC endpoint is active and serves the correct network. Consider using a more robust RPC provider or a Viem fallback transport.

• Error: Invalid ABI: Contract ABI must be asserted as const.

  cause Ponder's type system (which leverages Viem and ABIType) requires ABIs to be explicitly asserted as `const` for proper type inference.
  fix When importing or defining your ABI, ensure it is `as const`, for example: `import { BaseRegistrarAbi } from './abis/BaseRegistrar' as const;` or `const MyAbi = [...] as const;`.

Warnings

• breaking Ponder has specific Node.js and TypeScript version requirements. For Node.js, version >=18.14 is required. For TypeScript, >=5.0.4 is mandatory to leverage its advanced type system. Older versions of these tools can lead to build failures or unexpected runtime errors.
  Fix: Ensure your development environment meets the minimum requirements: Node.js >=18.14, TypeScript >=5.0.4. If using VSCode, explicitly select the workspace TypeScript version.
• gotcha Ponder relies on several peer dependencies, including `hono`, `typescript`, and `viem`. These packages are critical for the framework's operation, and failing to install them or installing incompatible versions can lead to runtime errors or incomplete functionality.
  Fix: Always ensure peer dependencies are installed in your project. The `create-ponder` CLI usually handles this, but manual installation might require checking `package.json` for correct versions.
• gotcha Ponder uses 'virtual modules' like `ponder:registry` and `ponder:schema` for its zero-codegen type system. These modules are not actual files on disk and require specific TypeScript configuration (e.g., `ponder-env.d.ts`) to be recognized by your IDE and build tools. Problems with `tsconfig.json` or `ponder-env.d.ts` can cause 'Cannot find module' errors.
  Fix: Ensure `ponder-env.d.ts` is present and committed, and your `tsconfig.json` is correctly configured to include Ponder's type declarations. Patch releases (e.g., 0.16.5) have addressed issues with `tsconfig.json` payload, indicating past problems.
• gotcha Incorrect RPC endpoint configuration or unreliable RPC providers can lead to Ponder service shutdowns or stalled indexing. An `Error: Start block number (...) cannot be greater than latest block number (...)` indicates an RPC issue, often with an incorrect network or a down provider.
  Fix: Verify RPC URLs are correct for the specified `chain.id`. Use a reliable RPC provider or configure Viem fallback transports with multiple RPC URLs in `ponder.config.ts`.

Install

• npm install ponder npm
• yarn add ponder yarn
• pnpm add ponder pnpm

Imports

• createConfig
  wrong:

  import createConfig from 'ponder'

  correct:

  import { createConfig } from 'ponder'

  Used in `ponder.config.ts` to define chain and contract configurations. This is a named export.
• onchainTable

  import { onchainTable } from 'ponder'

  Used in `ponder.schema.ts` to define database tables based on on-chain data.
• ponder
  wrong:

  import { ponder } from 'ponder'

  correct:

  import { ponder } from 'ponder:registry'

  The main instance for registering event indexing functions. It's imported from the virtual module `ponder:registry`, which provides type-safe access to contract events and context.
• schema
  wrong:

  import { schema } from 'ponder:schema'

  correct:

  import schema from 'ponder:schema'

  Represents the database schema for interaction within indexing functions, imported as a default export from the virtual module `ponder:schema`.

Quickstart

This quickstart demonstrates how to set up a Ponder project, configure chains and contracts, define a database schema, and write an indexing function to process Ethereum events and persist them to a database.

import { createConfig } from "ponder";
import { BaseRegistrarAbi } from "./abis/BaseRegistrar"; // Assuming ABI is local
import { ponder } from "ponder:registry";
import schema from "ponder:schema";

// 1. Initialize a new Ponder project (run in terminal):
// npm init ponder@latest
// cd my-ponder-project

// 2. Start the development server (run in project directory):
// npm run dev

// 3. Define Ponder configuration in ponder.config.ts
export default createConfig({
  chains: {
    mainnet: {
      id: 1,
      rpc: process.env.MAINNET_RPC_URL ?? "https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_KEY", // Replace with your actual RPC URL
    },
  },
  contracts: {
    BaseRegistrar: {
      abi: BaseRegistrarAbi,
      chain: "mainnet",
      address: "0x57f1887a8BF19b14fC0dF6Fd9B2acc9Af147eA85",
      startBlock: 9380410,
    },
  },
});

// 4. Define your schema in ponder.schema.ts
export const ensName = schema.onchainTable("ens_name", (t) => ({
  name: t.string().primaryKey(),
  owner: t.string().notNull(),
  registeredAt: t.int().notNull(),
}));

// 5. Write indexing functions in src/BaseRegistrar.ts
ponder.on("BaseRegistrar:NameRegistered", async ({ event, context }) => {
  const { name, owner } = event.params;

  await context.db.insert(schema.ensName).values({
    name: name,
    owner: owner,
    registeredAt: Number(event.block.timestamp),
  });
});