@nickstracke/ponder-core NPM

Ponder

Ponder is an open-source framework for blockchain application backends.

Documentation

Visit ponder.sh for documentation, guides, and the API reference.

Support

Join Ponder's telegram chat for support, feedback, and general chatter.

Features

✅ Local development server with hot reloading ✅ create-ponder-fork CLI tool to get started from an Etherscan link or Graph Protocol subgraph ✅ End-to-end type safety using viem and ABIType ✅ Autogenerated GraphQL API ✅ Easy to deploy anywhere using Node.js/Docker ✅ Supports all Ethereum-based blockchains, including test nodes like Anvil ✅ Index events from multiple chains in the same app ✅ Reconciles chain reorganization 🏗️ Transaction call event handlers 🏗️ Support for factory contracts like Uniswap V2/V3

Quickstart

1. Run `create-ponder-fork`

You will be asked for a project name, and if you are using an Etherscan or Graph Protocol template (recommended).

npm init ponder@latest
# or
pnpm create ponder
# or
yarn create ponder

2. Start the development server

The development server automatically reloads your app when you save changes in any project file, and prints console.log statements and errors in your code.

npm run dev
# or
pnpm dev
# or
yarn dev

3. Add contracts & networks

Ponder fetches event logs for the contracts added to ponder.config.ts, and passes those events to the handler functions you write.

// ponder.config.ts

export const config = {
  networks: [
    {
      name: "mainnet",
      chainId: 1,
      rpcUrl: "https://eth-mainnet.g.alchemy.com/v2/...",
    },
  ],
  contracts: [
    {
      name: "BaseRegistrar",
      network: "mainnet",
      abi: "./abis/BaseRegistrar.json",
      address: "0x57f1887a8BF19b14fC0dF6Fd9B2acc9Af147eA85",
      startBlock: 9380410,
    },
  ],
};

4. Define your schema

The schema.graphql file specifies the shape of your application's data.

// schema.graphql

type EnsName @entity {
  id: String!
  name: String!
  owner: String!
  registeredAt: Int!
}

5. Write event handlers

Use event handler functions to convert raw blockchain events into application data.

// src/BaseRegistrar.ts

import { ponder } from "@/generated";

ponder.on("BaseRegistrar:NameRegistered", async ({ event, context }) => {
  const { EnsName } = context.entities;
  const { name, owner } = event.params;

  await EnsName.create({
    id: `${name}-${owner}`,
    data: {
      name: name,
      owner: owner,
      registeredAt: event.block.timestamp,
    },
  });
});

6. Query the GraphQL API

Ponder automatically generates a frontend-ready GraphQL API based on your project's schema.graphql. The API will serve the data that you inserted in your event handler functions.

{
  ensNames(first: 2) {
    name
    owner
    registeredAt
  }
}

{
  "ensNames": [
    {
      "name": "vitalik.eth",
      "owner": "0x0904Dac3347eA47d208F3Fd67402D039a3b99859",
      "registeredAt": 1580345271
    },
    {
      "name": "joe.eth",
      "owner": "0x6109DD117AA5486605FC85e040ab00163a75c662",
      "registeredAt": 1580754710
    }
  ]
}

That's it! Visit ponder.sh for documentation, guides for deploying to production, and the API reference.