{"id":15764,"library":"ponder","title":"Ponder: EVM Data Indexing Framework","description":"Ponder is an open-source TypeScript framework designed for indexing data from EVM-compatible blockchains. It provides tools to define a database schema, write indexing functions to process on-chain events, and then query the indexed data via automatically generated GraphQL or SQL APIs. The current stable version is 0.16.6, with frequent patch releases indicating active development. Ponder differentiates itself by offering a powerful local development server with hot reloading, end-to-end type safety, support for Postgres, and the ability to index data from multiple chains within a single application. It aims to provide a robust, performant alternative to traditional subgraph indexing solutions, optimized for application developers who require custom backend logic and greater control over their data infrastructure.","status":"active","version":"0.16.6","language":"javascript","source_language":"en","source_url":"https://github.com/ponder-sh/ponder","tags":["javascript","typescript"],"install":[{"cmd":"npm install ponder","lang":"bash","label":"npm"},{"cmd":"yarn add ponder","lang":"bash","label":"yarn"},{"cmd":"pnpm add ponder","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for building the HTTP API and serving GraphQL/SQL queries. Required for Ponder's API server.","package":"hono","optional":false},{"reason":"Ponder is a TypeScript-first framework and leverages advanced TypeScript features for type safety. Required for development.","package":"typescript","optional":false},{"reason":"An Ethereum client library used by Ponder for interacting with EVM chains, including RPC communication.","package":"viem","optional":false}],"imports":[{"note":"Used in `ponder.config.ts` to define chain and contract configurations. This is a named export.","wrong":"import createConfig from 'ponder'","symbol":"createConfig","correct":"import { createConfig } from 'ponder'"},{"note":"Used in `ponder.schema.ts` to define database tables based on on-chain data.","symbol":"onchainTable","correct":"import { onchainTable } from 'ponder'"},{"note":"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.","wrong":"import { ponder } from 'ponder'","symbol":"ponder","correct":"import { ponder } from 'ponder:registry'"},{"note":"Represents the database schema for interaction within indexing functions, imported as a default export from the virtual module `ponder:schema`.","wrong":"import { schema } from 'ponder:schema'","symbol":"schema","correct":"import schema from 'ponder:schema'"}],"quickstart":{"code":"import { createConfig } from \"ponder\";\nimport { BaseRegistrarAbi } from \"./abis/BaseRegistrar\"; // Assuming ABI is local\nimport { ponder } from \"ponder:registry\";\nimport schema from \"ponder:schema\";\n\n// 1. Initialize a new Ponder project (run in terminal):\n// npm init ponder@latest\n// cd my-ponder-project\n\n// 2. Start the development server (run in project directory):\n// npm run dev\n\n// 3. Define Ponder configuration in ponder.config.ts\nexport default createConfig({\n  chains: {\n    mainnet: {\n      id: 1,\n      rpc: process.env.MAINNET_RPC_URL ?? \"https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_KEY\", // Replace with your actual RPC URL\n    },\n  },\n  contracts: {\n    BaseRegistrar: {\n      abi: BaseRegistrarAbi,\n      chain: \"mainnet\",\n      address: \"0x57f1887a8BF19b14fC0dF6Fd9B2acc9Af147eA85\",\n      startBlock: 9380410,\n    },\n  },\n});\n\n// 4. Define your schema in ponder.schema.ts\nexport const ensName = schema.onchainTable(\"ens_name\", (t) => ({\n  name: t.string().primaryKey(),\n  owner: t.string().notNull(),\n  registeredAt: t.int().notNull(),\n}));\n\n// 5. Write indexing functions in src/BaseRegistrar.ts\nponder.on(\"BaseRegistrar:NameRegistered\", async ({ event, context }) => {\n  const { name, owner } = event.params;\n\n  await context.db.insert(schema.ensName).values({\n    name: name,\n    owner: owner,\n    registeredAt: Number(event.block.timestamp),\n  });\n});\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<=0.16.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade Node.js to version 18.14 or newer using a version manager like `nvm` or `volta`.","cause":"The installed Node.js version is older than Ponder's minimum requirement.","error":"Error: Ponder requires Node.js version >=18.14."},{"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.","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.","error":"TS2307: Cannot find module 'ponder:registry' or its corresponding type declarations."},{"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.","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.","error":"Error: Start block number (XXXX) cannot be greater than latest block number (YYYY). Are you sure the RPC endpoint is for the correct network?"},{"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;`.","cause":"Ponder's type system (which leverages Viem and ABIType) requires ABIs to be explicitly asserted as `const` for proper type inference.","error":"Error: Invalid ABI: Contract ABI must be asserted as const."}],"ecosystem":"npm"}