Ponder

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

Documentation

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

Features

✅  Local development server with hot reloading ✅  create-ponder CLI tool to get started from an Etherscan link or Graph Protocol subgraph ✅  End-to-end type safety using ABIType and viem ✅  Autogenerated GraphQL API ✅  Easy to deploy anywhere using Node.js/Docker ✅  Compatible with all Ethereum-based blockchains, including test nodes like Anvil ✅  Supports multiple chains in the same app 🏗️  Gracefully handles chain reorganizations 🏗️  Handle transactions calls (in addition to logs) 🏗️  Run effects (e.g. send an API request) in event handler code

Quickstart

1. Run create-ponder

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.insert(`${name}-${owner}`, {
    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 an API reference.

Contributing

If you're interested in contributing to Ponder, please read the contribution guide.

Packages

• @ponder/core
• create-ponder

About

Ponder is MIT-licensed open-source software.