Create a new Ponder project
The create-ponder
CLI tool is the easiest way to get started with Ponder.
Run the create-ponder
CLI tool
This command creates a project folder called ponder
in the current working directory. There are two templates for getting started:
a) Etherscan contract link
The --from-etherscan
option bootstraps a Ponder project for a deployed contract. Replace the ...
with a link to a contract page on Etherscan (also accepts Polygonscan, Arbiscan, etc).
pnpm create ponder --from-etherscan <link>
b) Blank slate
If you don't have a contract in mind, this command will create a Ponder project for a sample NFT contract. Soon, create-ponder
will support more template options, like Foundry and Hardhat projects.
pnpm create ponder
Start the development server
The dev server is central to the Ponder development workflow. Just like Next.js, the dev server automatically reloads when you save changes in any project file. It also prints console.log
statements and errors encountered while running your code.
cd ponder
pnpm dev
Add an RPC URL
Ponder fetches data using the Ethereum RPC API. To get started, you'll need an RPC URL from a provider like Alchemy or Infura.
Open up .env.local
and paste in RPC URLs for any networks that your project uses:
PONDER_RPC_URL_1 = "https://eth-mainnet.g.alchemy.com/v2/..."
Define your schema
The schema.graphql
file defines the entity objects that our GraphQL API will serve. Any types marked with the @entity
directive will become available as entity models in your handler functions.
Using this schema, Ponder automatically generates a GraphQL API that serves entity data.
Write event handlers
The files in the src/
directory contain event handlers. Event handlers are JavaScript functions that accept a contract event and insert data into the entity store.
Here's a sample event handler for an ERC721 Transfer
event.
import { ponder } from "../generated";
ponder.on("MyNftContract:Transfer", async ({ event, context }) => {
const { Token } = context.entities;
const { MyNftContract } = context.contracts;
// Get an entity object
const token = await Token.get(event.params.id);
// Call a contract read function
const tokenUri = await MyNftContract.tokenUri(token.id);
// ...
});
Query the GraphQL API
As you write your event handlers and start inserting entity data, open the GraphiQL interface at http://localhost:42069/graphql
to explore your GraphQL API locally. Any changes you make to your schema.graphql
file will be reflected here.