Registry / web-framework / ponder

ponder

JSON →
library0.16.6jsnpmunverified

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.

npm install ponder
INSTALL
IMPORT
SIG · PONDER
P
ponder
web-frameworkjavascriptv0.16.6
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createConfig
import { createConfig } from 'ponder'
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
import { ponder } from 'ponder:registry'
import { ponder } from 'ponder'
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
import schema from 'ponder:schema'
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`.

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), }); });
ponder --version
Debug
Known issues
breakingPonder 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.
affects: <=0.16.x
gotchaPonder 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.
affects: >=0.1.0
gotchaPonder 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.
affects: >=0.1.0
gotchaIncorrect 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`.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Ponder requires Node.js version >=18.14.
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.
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?
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.
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;`.
Upgrade
Version history
0.16.6latest on npm
Audit
Dependencies
honorequiredUsed for building the HTTP API and serving GraphQL/SQL queries. Required for Ponder's API server.
typescriptrequiredPonder is a TypeScript-first framework and leverages advanced TypeScript features for type safety. Required for development.
viemrequiredAn Ethereum client library used by Ponder for interacting with EVM chains, including RPC communication.
Agent activity
17 hits · last 30 days
node
16
Resources
ponder — npm install ponder · libregistry