Ponder

https://ponder.sh/docs
Admin
Ponder is an open-source framework for custom Ethereum indexing that transforms onchain data using...
Tokens:55,440
Snippets:611
Trust Score:6.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Setup event usage

Source: https://ponder.sh/docs/api-reference/ponder/indexing-functions

Define a setup function to initialize state before indexing begins.

```typescript

import { ponder } from "ponder:registry";
import { world } from "ponder:schema";
 
ponder.on("FunGame:NewPlayer", async ({ context }) => {
  await context.db
    .insert(world)
    .values({ id: 1, playerCount: 0 })
    .onConflictDoUpdate((row) => ({
      playerCount: row.playerCount + 1,
    }));
});
```

```typescript

import { ponder } from "ponder:registry";
import { world } from "ponder:schema";
 
ponder.on("FunGame:setup", async ({ context }) => {
  await context.db.insert(world).values({
    id: 1,
    playerCount: 0,
  });
});
 
ponder.on("FunGame:NewPlayer", async ({ context }) => {
  await context.db
    .update(world, { id: 1 })
    .set((row) => ({
      playerCount: row.playerCount + 1,
  }));
});
```

--------------------------------

### Install Ponder 0.7

Source: https://ponder.sh/docs/migration-guide

Install the core package for the 0.7 release.

```bash
pnpm add @ponder/core@0.7
```

--------------------------------

### Start the development server

Source: https://ponder.sh/docs/get-started

Command to launch the local Ponder development server.

```bash
pnpm dev
```

--------------------------------

### Install @ponder/client

Source: https://ponder.sh/docs/api-reference/ponder-client

Add the package to your project using pnpm.

```bash
pnpm add @ponder/client
```

--------------------------------

### Pretty Log Output Example

Source: https://ponder.sh/docs/advanced/observability

Example of the default pretty log output format.

```text
12:12:15.391 INFO  Indexed block chain=mainnet number=23569900 event_count=14 (23ms)
12:12:16.159 INFO  Indexed block chain=polygon number=77633630 event_count=0 (1ms)
12:12:16.174 INFO  Indexed block chain=optimism number=142386579 event_count=1 (4ms)
12:12:16.226 INFO  Indexed block chain=base number=36791294 event_count=9 (14ms)
12:12:18.068 INFO  Indexed block chain=optimism number=142386580 event_count=2 (8ms)
12:12:18.125 INFO  Indexed block chain=polygon number=77633631 event_count=0 (1ms)
12:12:18.188 INFO  Indexed block chain=base number=36791295 event_count=10 (16ms)
12:12:20.021 INFO  Indexed block chain=optimism number=142386581 event_count=0 (4ms)
```

--------------------------------

### Install @ponder/react dependencies

Source: https://ponder.sh/docs/api-reference/ponder-react

Install the required packages using pnpm.

```bash
pnpm add @ponder/react @ponder/client @tanstack/react-query
```

--------------------------------

### Development server logs

Source: https://ponder.sh/docs/get-started

Example logs showing the startup process and indexing progress.

```text
12:16:42.845 INFO  Connected to database type=postgres database=localhost:5432/demo (35ms)
12:16:42.934 INFO  Connected to JSON-RPC chain=mainnet hostnames=["eth-mainnet.g.alchemy.com"] (85ms)
12:16:43.199 INFO  Created database tables count=4 tables=["account","transfer_event","allowance","approval_event"] (17ms)
12:16:43.324 INFO  Created HTTP server port=42069 (5ms)
12:16:43.325 INFO  Started returning 200 responses endpoint=/health
12:16:43.553 INFO  Started backfill indexing chain=mainnet block_range=[13142655,13150000]
12:16:43.555 INFO  Started fetching backfill JSON-RPC data chain=mainnet cached_block=13145448 cache_rate=38.0%
12:16:43.796 INFO  Indexed block range chain=mainnet event_count=4259 block_range=[13142655,13145448] (164ms)
12:16:43.840 INFO  Indexed block range chain=mainnet event_count=33 block_range=[13145449,13145474] (4ms)
```

--------------------------------

### Project initialization output

Source: https://ponder.sh/docs/get-started

Example output showing the prompts and initialization steps during project creation.

```text
✔ What's the name of your project? › new-project
✔ Which template would you like to use? › Default
 
✔ Installed packages with pnpm.
✔ Initialized git repository.
```

--------------------------------

### Ponder Start Command

Source: https://ponder.sh/docs/api-reference/ponder/cli

Starts the application in production mode with file changes ignored.

```bash
Usage: ponder start [options]
 
Start the production server
 
Options:
  --schema <SCHEMA>          Database schema (max: 45 characters)
  --views-schema <SCHEMA>    Views database schema (max: 45 characters)
  -p, --port <PORT>          Port for the web server (default: 42069)
  -H, --hostname <HOSTNAME>  Hostname for the web server (default: "0.0.0.0" or "::")
  -h, --help                 display help for command
```

--------------------------------

### JSON Log Output Example

Source: https://ponder.sh/docs/advanced/observability

Example of the JSON log output format.

```json
{"level":30,"time":1760372079306,"msg":"Indexed block","chain":"mainnet","chain_id":1,"number":23569912,"event_count":17,"duration":27.752416999996058}
{"level":30,"time":1760372080106,"msg":"Indexed block","chain":"polygon","chain_id":137,"number":77633702,"event_count":0,"duration":3.4684160000033444}
{"level":30,"time":1760372080122,"msg":"Indexed block","chain":"optimism","chain_id":10,"number":142386651,"event_count":0,"duration":2.3179999999993015}
{"level":30,"time":1760372080314,"msg":"Indexed block","chain":"base","chain_id":8453,"number":36791366,"event_count":10,"duration":18.320999999996275}
{"level":30,"time":1760372082131,"msg":"Indexed block","chain":"optimism","chain_id":10,"number":142386652,"event_count":0,"duration":3.074124999999185}
{"level":30,"time":1760372082258,"msg":"Indexed block","chain":"polygon","chain_id":137,"number":77633703,"event_count":0,"duration":1.7850829999952111}
{"level":30,"time":1760372082328,"msg":"Indexed block","chain":"base","chain_id":8453,"number":36791367,"event_count":4,"duration":9.394625000000815}
{"level":30,"time":1760372084153,"msg":"Indexed block","chain":"optimism","chain_id":10,"number":142386653,"event_count":0,"duration":2.679999999993015}
```

--------------------------------

### Update Ponder start command

Source: https://ponder.sh/docs/migration-guide

Include the --views-schema flag in the start command to enable the database views pattern.

```bash
pnpm start --schema $RAILWAY_DEPLOYMENT_ID 
pnpm start --schema $RAILWAY_DEPLOYMENT_ID --views-schema my_project
```

--------------------------------

### Initialize a Ponder project

Source: https://ponder.sh/docs/api-reference/create-ponder

Basic command to start a new Ponder project using pnpm.

```bash
pnpm create ponder {...options}
```

--------------------------------

### Terminal UI Output Example

Source: https://ponder.sh/docs/advanced/observability

Visual representation of the dynamic terminal UI.

```text
Chains
 
│ Chain    │ Status │ Block     │ RPC (req/s) │
├──────────┼────────┼───────────┼─────────────┤
│ optimism │ live   │ 142388578 │         1.6 │
│ polygon  │ live   │  77635629 │        17.2 │
│ base     │ live   │  36793293 │         4.2 │
│ mainnet  │ live   │  23570232 │         7.5 │
 
Indexing (live)
 
│ Event         │ Count │ Duration (ms) │
├───────────────┼───────┼───────────────┤
│ WETH:Deposit  │   107 │         1.554 │
 
API endpoints
Live at http://localhost:42069
```

--------------------------------

### Configure Ponder start command for Railway

Source: https://ponder.sh/docs/production/railway

Use this command in the Railway Custom Start Command setting to enable zero-downtime deployments.

```bash
pnpm start --schema $RAILWAY_DEPLOYMENT_ID
```

--------------------------------

### Ponder Dev Command

Source: https://ponder.sh/docs/api-reference/ponder/cli

Starts the development server with hot reloading enabled.

```bash
Usage: ponder dev [options]
 
Start the development server with hot reloading
 
Options:
  --schema <SCHEMA>          Database schema (max: 45 characters)
  --disable-ui               Disable the terminal UI
  -p, --port <PORT>          Port for the web server (default: 42069)
  -H, --hostname <HOSTNAME>  Hostname for the web server (default: "0.0.0.0" or "::")
  -h, --help                 display help for command
```

--------------------------------

### Ponder Serve Command

Source: https://ponder.sh/docs/api-reference/ponder/cli

Starts the HTTP server in production without the indexer, suitable for horizontal scaling.

```bash
Usage: ponder serve [options]
 
Start the production HTTP server without the indexer
 
Options:
  --schema <SCHEMA>          Database schema (max: 45 characters)
  -p, --port <PORT>          Port for the web server (default: 42069)
  -H, --hostname <HOSTNAME>  Hostname for the web server (default: "0.0.0.0" or "::")
  -h, --help                 display help for command
```

--------------------------------

### GraphQL query for accounts

Source: https://ponder.sh/docs/get-started

Example GraphQL query to fetch top accounts by balance.

```graphql
query {
  accounts(orderBy: "balance", orderDirection: "desc", limit: 2) {
    items {
      address
      balance
    }
    totalCount
  }
}
```

--------------------------------

### Install Hono peer dependency

Source: https://ponder.sh/docs/migration-guide

Required command to install Hono as a peer dependency after upgrading to version 0.5.0.

```bash
pnpm add hono@latest
```

--------------------------------

### Legacy Allowance Creation

Source: https://ponder.sh/docs/migration-guide

Example of creating an allowance record using the 0.6 and below API.

```typescript
// Create a single allowance
await context.db.Allowance.create({
  id: event.log.id,
  data: {
    owner: event.args.owner,
    spender: event.args.spender,
    amount: event.args.amount,
  },
});
```

--------------------------------

### Import Foundry broadcast files

Source: https://ponder.sh/docs/guides/foundry

Directly import deployment JSON files into your configuration to dynamically set contract addresses and start blocks.

```typescript
import { createConfig } from "ponder";
import { http, getAddress, hexToNumber } from "viem";
import { counterABI } from "../abis/CounterAbi";
import CounterDeploy from "../foundry/broadcast/Deploy.s.sol/31337/run-latest.json"; 
 
const address = getAddress(CounterDeploy.transactions[0]!.contractAddress); 
const startBlock = hexToNumber(CounterDeploy.receipts[0]!.blockNumber); 
 
export default createConfig({
  chains: {
    anvil: {
      id: 31337,
      rpc: "http://127.0.0.1:8545",
      disableCache: true,
    },
  },
  contracts: {
    Counter: {
      chain: "anvil",
      abi: counterABI,
      address, 
      startBlock, 
    },
  },
});
```

--------------------------------

### Update viem dependency

Source: https://ponder.sh/docs/migration-guide

Install the latest version of viem to satisfy the updated peer dependency requirement.

```bash
pnpm add viem@latest
```

--------------------------------

### Execute Arbitrary SQL Select

Source: https://ponder.sh/docs/migration-guide

Example of using the context.db.sql interface to perform a select query with ordering and limits.

```typescript
import { desc } from "@ponder/core";
import { account } from "../ponder.schema";
 
ponder.on("...", ({ event, context }) => {
  const result = await context.db.sql
    .select()
    .from(account)
    .orderBy(desc(account.balance))
    .limit(1);
});
```

--------------------------------

### Advanced Schema Definition

Source: https://ponder.sh/docs/migration-guide

Example demonstrating indexes and composite primary keys using the new schema API.

```typescript
import { onchainTable, index, primaryKey } from "@ponder/core";
 
export const transferEvents = onchainTable(
  "transfer_event",
  (t) => ({
    id: t.text().primaryKey(),
    amount: t.bigint().notNull(),
    timestamp: t.integer().notNull(),
    from: t.hex().notNull(),
    to: t.hex().notNull(),
  }),
  (table) => ({
    fromIdx: index().on(table.from),
  })
);
 
export const allowance = onchainTable(
  "allowance",
  (t) => ({
    owner: t.hex().notNull(),
    spender: t.hex().notNull(),
    amount: t.bigint().notNull(),
  }),
  (table) => ({
    pk: primaryKey({ columns: [table.owner, table.spender] }),
  })
);
 
export const approvalEvent = onchainTable("approval_event", (t) => ({
  id: t.text().primaryKey(),
  amount: t.bigint().notNull(),
  timestamp: t.integer().notNull(),
  owner: t.hex().notNull(),
  spender: t.hex().notNull(),
}));
```

--------------------------------

### Define a custom view for pet ownership

Source: https://ponder.sh/docs/schema/views

Example of creating a pet leaderboard view that aggregates pet counts by owner.

```typescript
import { onchainTable, onchainView, count } from "ponder";
 
export const pets = onchainTable("pets", (t) => ({
  id: t.text().primaryKey(),
  name: t.text().notNull(),
  owner: t.text().notNull(),
}));
 
export const petLeaderboard = onchainView("pet_leaderboard").as((qb) =>
  qb
    .select({
      ownerName: pets.owner,
      petCount: count().as("pet_count"),
    })
    .from(pets)
    .groupBy(pets.owner)
);
```

--------------------------------

### Update dependencies for Ponder 0.17

Source: https://ponder.sh/docs/migration-guide

Install the required versions of Viem and TypeScript for Ponder 0.17 using pnpm.

```bash
pnpm add viem@^2.35.0
pnpm add --save-dev typescript@^5.4.0
```

--------------------------------

### Define Schema with onchainTable

Source: https://ponder.sh/docs/migration-guide

Basic example of defining a table using the new onchainTable API.

```typescript
import { onchainTable } from "@ponder/core";
 
export const accounts = onchainTable("account", (t) => ({
  address: t.hex().primaryKey(),
  daiBalance: t.bigint().notNull(),
  isAdmin: t.boolean().notNull(),
  graffiti: t.text(),
}));
```

--------------------------------

### Configure Blocks with BlockConfig

Source: https://ponder.sh/docs/api-reference/ponder/config

Use BlockConfig to define block indexing parameters like start block and interval.

```typescript
import { createConfig, type BlockConfig } from "ponder"; 
 
const ChainlinkPriceOracle = { 
  chain: "mainnet", 
  startBlock: 19_750_000, 
  interval: 5, 
} as const satisfies BlockConfig; 
 
export default createConfig({
  blocks: {
    ChainlinkPriceOracle,
  },
  // ...
});
```

--------------------------------

### Configure Contracts in Ponder

Source: https://ponder.sh/docs/api-reference/ponder/config

Define smart contract indexing parameters such as ABI, address, and start block within the contracts object.

```typescript

import { createConfig } from "ponder";
import { BlitmapAbi } from "./abis/Blitmap";
 
export default createConfig({
  contracts: { 
    Blitmap: { 
      abi: BlitmapAbi, 
      chain: "mainnet", 
      address: "0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63", 
      startBlock: 12439123, 
    }, 
  }, 
  // ...
});
```

--------------------------------

### Index the factory contract and child contracts

Source: https://ponder.sh/docs/guides/factory

Register both the factory contract and the factory-managed contracts in the configuration to handle setup logic for child contracts.

```typescript
import { createConfig, factory } from "ponder";
import { parseAbiItem } from "viem";
import { SudoswapPoolAbi } from "./abis/SudoswapPool";
import { SudoswapFactoryAbi } from "./abis/SudoswapFactory";
 
export default createConfig({
  chains: { /* ... */ },
  contracts: {
    SudoswapFactory: { 
      abi: SudoswapFactoryAbi, 
      chain: "mainnet", 
      address: "0xb16c1342E617A5B6E4b631EB114483FDB289c0A4", 
      startBlock: 14645816, 
    }, 
    SudoswapPool: {
      abi: SudoswapPoolAbi,
      chain: "mainnet",
      address: factory({
        address: "0xb16c1342E617A5B6E4b631EB114483FDB289c0A4",
        event: parseAbiItem("event NewPair(address poolAddress)"),
        parameter: "poolAddress",
      }),
      startBlock: 14645816,
    },
  },
});
```

--------------------------------

### Define an hourly bucket aggregation view

Source: https://ponder.sh/docs/schema/views

Example of an ERC20 indexer view that aggregates transfer volumes and counts into hourly buckets.

```typescript
import { onchainTable, onchainView, index, sql, sum, count } from "ponder";
 
export const transferEvent = onchainTable("transfer_event", (t) => ({
  id: t.text().primaryKey(),
  amount: t.bigint().notNull(),
  timestamp: t.integer().notNull(),
  from: t.hex().notNull(),
  to: t.hex().notNull(),
}));
 
export const hourlyBucket = onchainView("hourly_bucket").as((qb) =>
  qb
    .select({
      hour: sql`FLOOR(${transferEvent.timestamp} / 3600) * 3600`.as("hour"),
      totalVolume: sum(transferEvent.amount).as("total_volume"),
      transferCount: count().as("transfer_count"),
    })
    .from(transferEvent)
    .groupBy(sql`FLOOR(${transferEvent.timestamp} / 3600)`)
);
```

--------------------------------

### View CLI help and options

Source: https://ponder.sh/docs/api-reference/create-ponder

Displays the usage instructions and available flags for the create-ponder command.

```bash
Usage:
  $ create-ponder <directory> [options]
 
Options:
  -t, --template [id]             Use a template
  --npm                           Use npm as your package manager
  --pnpm                          Use pnpm as your package manager
  --yarn                          Use yarn as your package manager
  --skip-git                      Skip initializing a git repository
  --skip-install                  Skip installing packages
  -h, --help                      Display this message
  -v, --version                   Display version number
```

--------------------------------

### Initialize project from template

Source: https://ponder.sh/docs/api-reference/create-ponder

Creates a new project based on a specific template ID.

```bash
pnpm create ponder --template feature-factory
```

--------------------------------

### Create a new Ponder project with Bun

Source: https://ponder.sh/docs/guides/bun

Use the Bun CLI to initialize a new Ponder project with the Bun package manager and runtime.

```shell
bun --bun create ponder {...options}
```

--------------------------------

### Initialize a new Ponder project

Source: https://ponder.sh/docs/get-started

Use the create-ponder CLI tool to scaffold a new project.

```bash
pnpm create ponder
```

--------------------------------

### GraphQL Relationship Query

Source: https://ponder.sh/docs/schema/relations

Example of querying a one-to-many relationship between a person and their dogs.

```APIDOC
## GraphQL Query

### Description
Queries a record and its related entities based on the schema definitions.

### Query Example
```graphql
query {
  person(id: "Bob") {
    id
    dogs {
      id
    }
  }
}
```

### Response Example
```json
{
  "person": {
    "id": "Bob",
    "dogs": [
      { "id": "Chip" },
      { "id": "Spike" }
    ]
  }
}
```
```

--------------------------------

### Set up @ponder/client

Source: https://ponder.sh/docs/query/sql-over-http

Initialize the Ponder client with the SQL endpoint and schema.

```typescript
import { createClient } from "@ponder/client";
import * as schema from "../../ponder/ponder.schema"; 
 
const client = createClient("http://localhost:42069/sql", { schema }); 
```

--------------------------------

### Create a query client

Source: https://ponder.sh/docs/query/sql-over-http

Initialize the client to connect to the server's SQL middleware path.

```typescript
import { createClient } from "@ponder/client";
 
const client = createClient("http://localhost:42069/sql");
```

--------------------------------

### Set up PonderProvider

Source: https://ponder.sh/docs/query/sql-over-http

Wrap the application with the PonderProvider to provide the client context.

```typescript
import { PonderProvider } from "@ponder/react";
import { client } from "../lib/ponder";
 
function App() {
  return (
    <PonderProvider client={client}>
      {/** ... */}
    </PonderProvider>
  );
}
```

--------------------------------

### GET /status

Source: https://ponder.sh/docs/advanced/observability

Retrieves the current indexing status of the application via HTTP.

```APIDOC
## GET /status

### Description
Returns the indexing status for each chain configured in the application, including the most recently indexed block number and timestamp.

### Method
GET

### Endpoint
/status

### Response
#### Success Response (200)
- **[chain_name]** (object) - An object containing the chain ID and the most recently indexed block information.
- **id** (number) - The chain ID.
- **block** (object|null) - The most recently indexed block, containing 'number' and 'timestamp', or null if backfill is not complete.

#### Response Example
{
  "mainnet": {
    "id": 1,
    "block": {
      "number": 20293450,
      "timestamp": 1720823759
    }
  }
}
```

--------------------------------

### GET /metrics

Source: https://ponder.sh/docs/advanced/observability

Retrieves the current state of application metrics in Prometheus format.

```APIDOC
## GET /metrics

### Description
Returns the current Prometheus metrics for the Ponder application, including indexing progress, historical sync status, database performance, and HTTP server statistics.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
- **ponder_indexing_total_seconds** (gauge) - Total number of seconds required for indexing
- **ponder_indexing_completed_seconds** (gauge) - Number of seconds that have been completed
- **ponder_indexing_completed_events** (gauge) - Number of events that have been processed
- **ponder_indexing_completed_timestamp** (gauge) - Timestamp through which all events have been completed
- **ponder_indexing_function_duration** (histogram) - Duration of indexing function execution
- **ponder_indexing_function_error_total** (counter) - Total number of errors encountered during indexing function execution
- **ponder_historical_start_timestamp** (gauge) - Unix timestamp (ms) when the historical sync service started
- **ponder_historical_total_blocks** (gauge) - Number of blocks required for the historical sync
- **ponder_historical_cached_blocks** (gauge) - Number of blocks that were found in the cache for the historical sync
- **ponder_historical_completed_blocks** (gauge) - Number of blocks that have been processed for the historical sync
- **ponder_realtime_is_connected** (gauge) - Boolean (0 or 1) indicating if the realtime sync service is connected
- **ponder_realtime_latest_block_number** (gauge) - Block number of the latest synced block
- **ponder_realtime_latest_block_timestamp** (gauge) - Block timestamp of the latest synced block
- **ponder_realtime_reorg_total** (counter) - Count of how many re-orgs have occurred
- **ponder_database_method_duration** (histogram) - Duration of database operations
- **ponder_database_method_error_total** (counter) - Total number of errors encountered during database operations
- **ponder_http_server_active_requests** (gauge) - Number of active HTTP server requests
- **ponder_http_server_request_duration_ms** (histogram) - Duration of HTTP responses served by the server
- **ponder_http_server_request_size_bytes** (histogram) - Size of HTTP requests received by the server
- **ponder_http_server_response_size_bytes** (histogram) - Size of HTTP responses served by the server
- **ponder_rpc_request_duration** (histogram) - Duration of RPC requests
- **ponder_rpc_request_error_total** (counter) - Total number of failed RPC requests
- **ponder_postgres_pool_connections** (gauge) - Gauge of current connections for PostgreSQL pools
- **ponder_postgres_query_queue_size** (gauge) - Current size of the query queue for PostgreSQL
- **ponder_postgres_query_total** (counter) - Total number of queries processed by PostgreSQL
```

--------------------------------

### Querying One-to-Many Relationships

Source: https://ponder.sh/docs/schema/relations

Example GraphQL query to fetch a person and their associated dogs.

```graphql
query {
  person(id: "Bob") {
    id
    dogs {
      id
    }
  }
}
```

--------------------------------

### Initialize Ponder Client

Source: https://ponder.sh/docs/api-reference/ponder-client

Create a client instance by providing the server URL and the schema exported from your Ponder project.

```typescript
import { createClient } from "@ponder/client";
import * as schema from "../../ponder/ponder.schema";
 
const client = createClient("https://.../sql", { schema });
 
export { client, schema };
```

--------------------------------

### Define sample person data

Source: https://ponder.sh/docs/query/graphql

Initial dataset used for the following filtering examples.

```json
[
  { "id": 1, "name": "Barry", "age": 57 },
  { "id": 2, "name": "Lucile", "age": 32 },
  { "id": 3, "name": "Sally", "age": 22 },
  { "id": 4, "name": "Pablo", "age": 71 },
]
```

--------------------------------

### Manage database views with CLI commands

Source: https://ponder.sh/docs/production/self-hosting

Use CLI commands to create or automate database views for the latest deployment.

```bash
pnpm db create-views --schema=deployment-123 --views-schema=project-name
```

```bash
pnpm start --schema=deployment-123 --views-schema=project-name
```

--------------------------------

### create-ponder <directory> [options]

Source: https://ponder.sh/docs/api-reference/create-ponder

Initializes a new Ponder project in the specified directory with optional configuration flags.

```APIDOC
## create-ponder <directory> [options]

### Description
Creates a new Ponder project in the specified directory, including all required files like package.json and ponder.config.ts.

### Usage
`pnpm create ponder <directory> [options]`

### Options
- **-t, --template [id]** (string) - Optional - Use a specific template to initialize the project.
- **--npm** (flag) - Optional - Use npm as the package manager.
- **--pnpm** (flag) - Optional - Use pnpm as the package manager.
- **--yarn** (flag) - Optional - Use yarn as the package manager.
- **--skip-git** (flag) - Optional - Skip initializing a git repository.
- **--skip-install** (flag) - Optional - Skip installing packages.
- **-h, --help** (flag) - Optional - Display help message.
- **-v, --version** (flag) - Optional - Display version number.
```

--------------------------------

### createClient

Source: https://ponder.sh/docs/api-reference/ponder-client

Initializes a client object connected to a Ponder server.

```APIDOC
## createClient(baseUrl, options)

### Description
Creates a client instance to communicate with the Ponder server.

### Parameters
- **baseUrl** (string) - Required - Ponder server URL where the client middleware is running.
- **options.schema** (Schema) - Optional - The schema exported by ponder.schema.ts.

### Returns
A Client object with methods for querying the database.
```

--------------------------------

### Filter records with case-insensitive search

Source: https://ponder.sh/docs/query/graphql

Retrieve persons with a name starting with 'p' regardless of case.

```graphql
query {
  persons(where: { name_starts_with_nocase: "p" }) {
    name
    age
  }
}
```

--------------------------------

### Configure API endpoints in src/api/index.ts

Source: https://ponder.sh/docs/migration-guide

Required setup for serving GraphQL APIs in Ponder 0.9.

```typescript
import { db } from "ponder:api";
import schema from "ponder:schema";
import { Hono } from "hono";
import { graphql } from "ponder";
 
const app = new Hono();
 
app.use("/", graphql({ db, schema }));
app.use("/graphql", graphql({ db, schema }));
 
export default app;
```

--------------------------------

### Avoid manual Viem client instantiation

Source: https://ponder.sh/docs/indexing/read-contracts

Do not manually create a Viem client; use the built-in context.client to ensure proper caching and performance.

```typescript
import { ponder } from "ponder:registry";
import { createPublicClient, http } from "viem";
 
// Don't do this! ❌ ❌ ❌
const publicClient = createPublicClient({
  transport: http("https://eth-mainnet.g.alchemy.com/v2/..."),
});
 
ponder.on("Blitmap:Mint", async ({ event, context }) => {
  const tokenUri = await publicClient.readContract({
    abi: context.contracts.Blitmap.abi,
    address: context.contracts.Blitmap.address,
    method: "tokenUri",
    args: [event.args.tokenId],
  });
});
```

--------------------------------

### Define a basic Hono endpoint

Source: https://ponder.sh/docs/api-reference/ponder/api-endpoints

Register a simple GET route in the Hono application instance.

```typescript

import { Hono } from "hono";
 
const app = new Hono();
 
app.get("/hello", (c) => {
  return c.text("Hello, world!");
});
 
export default app;
```

--------------------------------

### Configure Database Schema

Source: https://ponder.sh/docs/migration-guide

Set the database schema via environment variables or CLI flags as required in 0.8.

```text
DATABASE_SCHEMA=my_schema
```

```shell
ponder start --schema my_schema
```

--------------------------------

### Handle insertion errors

Source: https://ponder.sh/docs/indexing/write

Examples of errors triggered by missing required columns or unique constraint violations.

```typescript
import { accounts } from "ponder:schema";
 
const row = await db.insert(accounts).values({
  address: "0x7Df1",
});
 
// Error: Column "balance" is required but not present in the values object.
```

```typescript
import { accounts } from "ponder:schema";
 
const row = await db.insert(accounts).values({
  address: "0x7Df1",
});
 
// Error: Column "balance" is required but not present in the values object.
```

--------------------------------

### Configure a contract for indexing

Source: https://ponder.sh/docs/config/contracts

Define a contract in ponder.config.ts by specifying its ABI, chain, address, and starting block.

```typescript
import { createConfig } from "ponder";
import { BlitmapAbi } from "./abis/Blitmap";
 
export default createConfig({
  chains: {
    mainnet: { id: 1, rpc: process.env.PONDER_RPC_URL_1 },
  },
  contracts: {
    Blitmap: {
      abi: BlitmapAbi,
      chain: "mainnet",
      address: "0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63",
      startBlock: 12439123,
    },
  },
});
```

--------------------------------

### Ponder Create-Views Command

Source: https://ponder.sh/docs/api-reference/ponder/cli

Creates database views for the views pattern.

```bash
Usage: ponder create-views [options]
 
Create database views for the views pattern
 
Options:
  --schema <SCHEMA>          Database schema (max: 45 characters)
  --views-schema <SCHEMA>    Views database schema (max: 45 characters)
  -h, --help                 display help for command
```

--------------------------------

### Configure client with schema

Source: https://ponder.sh/docs/query/sql-over-http

Pass the schema to createClient to enable type inference for your queries.

```typescript
import { createClient } from "@ponder/client";
import * as schema from "../../ponder/ponder.schema"; 
 
const client = createClient("http://localhost:42069/sql", { schema });
```

--------------------------------

### getPonderQueryOptions

Source: https://ponder.sh/docs/api-reference/ponder-react

A helper function to build the TanStack Query `queryFn` and `queryKey` for executing SQL queries over HTTP.

```APIDOC
## getPonderQueryOptions

### Description
Builds the necessary configuration for TanStack Query to execute SQL queries against a Ponder server.

### Parameters
- **client** (Client) - Required - A client instance created by `createClient`.
- **queryFn** ((db: Client["db"]) => Promise<Result>) - Required - Function that receives the Drizzle query builder and returns a query result promise.

### Returns
- **queryKey** (QueryKey) - A TanStack Query Key that encodes the SQL statement.
- **queryFn** (() => Promise<Result>) - A TanStack Query Function that executes the SQL query over HTTP.
```

--------------------------------

### Run Ponder with Bun

Source: https://ponder.sh/docs/guides/bun

Execute development or production commands using the Bun runtime.

```shell
bun dev
```

--------------------------------

### Legacy ERC20 Transfer Upsert

Source: https://ponder.sh/docs/migration-guide

Example of an ERC20 transfer indexing function using the legacy upsert method.

```typescript
import { ponder } from "@/generated";
 
ponder.on("ERC20:Transfer", async ({ event, context }) => {
  const { Account, TransferEvent } = context.db;
 
  await Account.upsert({
    id: event.args.from,
    create: {
      balance: BigInt(0),
      isOwner: false,
    },
    update: ({ current }) => ({
      balance: current.balance - event.args.amount,
    }),
  });
});
```

--------------------------------

### List Database Schemas

Source: https://ponder.sh/docs/migration-guide

Use the db list command to view active database schemas and table counts.

```shell
$ ponder db list
 
│ Schema        │ Active   │ Last active    │ Table count │
├───────────────┼──────────┼────────────────┼─────────────┤
│ indexer_prod  │      yes │            --- │          10 │
│ test          │       no │    26m 58s ago │          10 │
│ demo          │       no │      1 day ago │           5 │
```

--------------------------------

### Update package.json scripts for Bun

Source: https://ponder.sh/docs/guides/bun

Configure project scripts to use the --bun flag to opt-in to the Bun runtime.

```json
"scripts": {
  "dev": "ponder dev", 
  "start": "ponder start", 
  "codegen": "ponder codegen", 
  "dev": "bun --bun ponder dev", 
  "start": "bun --bun start", 
  "codegen": "bun --bun ponder codegen", 
  "lint": "eslint .",
  "typecheck": "tsc"
},
```

--------------------------------

### Enable SQL-over-HTTP middleware

Source: https://ponder.sh/docs/api-reference/ponder/api-endpoints

Mount the client middleware to serve SQL queries submitted by @ponder/client.

```typescript

import { db } from "ponder:api";
import schema from "ponder:schema";
import { Hono } from "hono";
import { client } from "ponder"; 
 
const app = new Hono();
 
app.use("/sql/*", client({ db, schema })); 
 
export default app;
```

--------------------------------

### Define Indexing Function with New API

Source: https://ponder.sh/docs/migration-guide

Example of an indexing function using the Drizzle-based API and table objects from ponder.schema.ts.

```typescript
import { ponder } from "@/generated";
import { account } from "../ponder.schema";
 
ponder.on("ERC20:Transfer", async ({ event, context }) => {
  await context.db
    .insert(account)
    .values({ 
      address: event.args.from, 
      balance: 0n, 
      isOwner: false,
    })
    .onConflictDoUpdate((row) => ({
      balance: row.balance - event.args.amount,
    }));
});
```

--------------------------------

### client.live

Source: https://ponder.sh/docs/api-reference/ponder-client

Subscribes to real-time database updates using server-sent events.

```APIDOC
## client.live(queryFn, onData, onError)

### Description
Subscribes to live updates from the database. The client multiplexes all live queries over a single SSE connection.

### Parameters
- **queryFn** (function) - Required - A callback that builds the query using the provided db instance.
- **onData** (function) - Required - Callback invoked with new query results.
- **onError** (function) - Optional - Callback invoked when an error occurs.

### Returns
An object containing an `unsubscribe` method to stop receiving updates.
```

--------------------------------

### Migrate Package Name

Source: https://ponder.sh/docs/migration-guide

Switch from the deprecated @ponder/core package to the new ponder package.

```shell
pnpm remove @ponder/core
pnpm add ponder
```

--------------------------------

### Configure contracts for multiple chains

Source: https://ponder.sh/docs/indexing/read-contracts

Define contract addresses and start blocks per chain in the ponder configuration file.

```typescript
import { createConfig } from "ponder";
import { UniswapV3FactoryAbi } from "./abis/UniswapV3Factory";
 
export default createConfig({
  chains: {
    mainnet: { id: 1, rpc: process.env.PONDER_RPC_URL_1 },
    base: { id: 8453, rpc: process.env.PONDER_RPC_URL_8453 },
  },
  contracts: {
    UniswapV3Factory: {
      abi: UniswapV3FactoryAbi,
      chain: { 
        mainnet: { 
          address: "0x1F98431c8aD98523631AE4a59f267346ea31F984", 
          startBlock: 12369621, 
        }, 
        base: { 
          address: "0x33128a8fC17869897dcE68Ed026d694621f6FDfD", 
          startBlock: 1371680, 
        }, 
      }, 
    },
  },
});
```

--------------------------------

### Factory Event Signature Eligibility

Source: https://ponder.sh/docs/guides/factory

Examples of event signatures that are eligible or ineligible for the factory pattern based on parameter types and indexing.

```solidity
// ✅ Eligible. The parameter "child" has type "address" and is non-indexed.
event ChildContractCreated(address child);
 
// ✅ Eligible. The parameter "pool" has type "address" and is indexed.
event PoolCreated(address indexed deployer, address indexed pool, uint256 fee);
 
// ❌ Not eligible. The parameter "contracts" is an array type, which is not supported
// with `parameter`.
// ✅ Eligible with `location` if the byte offset of the child address is known.
event ContractsCreated(address[] contracts);
```

--------------------------------

### Initialize Hono API instance

Source: https://ponder.sh/docs/query/api-endpoints

The src/api/index.ts file must default export a Hono instance to serve as the API router.

```typescript
import { Hono } from "hono";
 
const app = new Hono();
 
export default app;
```

--------------------------------

### Configure account indexing in ponder.config.ts

Source: https://ponder.sh/docs/config/accounts

Define an account to track transactions or native transfers by specifying the chain, address, and start block.

```typescript
import { createConfig } from "ponder";
 
export default createConfig({
  chains: {
    mainnet: { id: 1, rpc: process.env.PONDER_RPC_URL_1 },
  },
  accounts: { 
    BeaverBuild: { 
      chain: "mainnet", 
      address: "0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5", 
      startBlock: 20000000, 
    }, 
  }, 
});
```

--------------------------------

### Configure chain-specific block intervals

Source: https://ponder.sh/docs/config/block-intervals

Define different intervals and start blocks for multiple chains within a single block configuration.

```typescript
import { createConfig } from "ponder";
 
export default createConfig({
  chains: { /* ... */ },
  blocks: {
    PointsAggregation: {
      chain: {
        mainnet: {
          startBlock: 19783636, 
          interval: (60 * 60) / 12, // Every 60 minutes (12s block time) 
        }, 
        optimism: { 
          startBlock: 119534316, 
          interval: (60 * 60) / 2, // Every 60 minutes (2s block time) 
        },
      },
    },
  },
});
```

--------------------------------

### Configure block intervals in ponder.config.ts

Source: https://ponder.sh/docs/config/block-intervals

Define a block interval by specifying the chain, interval frequency, and start block within the blocks object.

```typescript
import { createConfig } from "ponder";
 
export default createConfig({
  chains: {
    mainnet: { id: 1, rpc: process.env.PONDER_RPC_URL_1 },
  },
  blocks: {
    ChainlinkOracleUpdate: {
      chain: "mainnet",
      interval: 10, // Every 10 blocks
      startBlock: 1000,
    },
  },
});
```

--------------------------------

### Configure Log Level via CLI

Source: https://ponder.sh/docs/advanced/observability

Use CLI flags to set the log level or use shortcuts for debug and trace levels.

```bash
ponder dev --log-level warn
# or, use the shortcut flag for debug
ponder dev -v
```

--------------------------------

### Ponder CLI General Usage

Source: https://ponder.sh/docs/api-reference/ponder/cli

Displays the base command structure and global options available for the Ponder CLI.

```bash
Usage: ponder <command> [OPTIONS]
 
Options:
  --root <PATH>          Path to the project root directory (default: working directory)
  --config <PATH>        Path to the project config file (default: "ponder.config.ts")
  -v, --debug            Enable debug logs, e.g. realtime blocks, internal events
  -vv, --trace           Enable trace logs, e.g. db queries, indexing checkpoints
  --log-level <LEVEL>    Minimum log level ("error", "warn", "info", "debug", or "trace", default: "info")
  --log-format <FORMAT>  The log format ("pretty" or "json") (default: "pretty")
  -V, --version          Show the version number
  -h, --help             Show this help message
 
Commands:
  dev [options]          Start the development server with hot reloading
  start [options]        Start the production server
  serve [options]        Start the production HTTP server without the indexer
  db                     Database management commands
  codegen                Generate the ponder-env.d.ts file, then exit
```

--------------------------------

### Read contract data in Ponder event handler

Source: https://ponder.sh/docs/indexing/read-contracts

An example of using context.client.readContract inside a Ponder event handler to fetch and store metadata during a mint event.

```typescript
import { ponder } from "ponder:registry";
import { zorbs } from "ponder:schema";
 
ponder.on("ZorbNft:Transfer", async ({ event, context }) => {
  if (event.args.from === ZERO_ADDRESS) {
    // If this is a mint, read gradient metadata from the contract. 
    const gradientData = await context.client.readContract({ 
      abi: context.contracts.ZorbNft.abi, 
      address: context.contracts.ZorbNft.address, 
      functionName: "gradientForAddress", 
      args: [event.args.to], 
    }); 
 
    await context.db.insert(zorbs).values({
      id: event.args.tokenId,
      gradient: gradientData,
      ownerId: event.args.to,
    });
  } else {
    // If not a mint, just update ownership information.
    await context.db
      .update(zorbs, { id: event.args.tokenId })
      .set({ ownerId: event.args.to });
  }
});
```

--------------------------------

### Method Migration Reference

Source: https://ponder.sh/docs/migration-guide

Side-by-side comparison of legacy ORM methods and new query builder methods.

```typescript
// create -> insert
await context.db.Account.create({
  id: event.args.from,
  data: { balance: 0n },
});
await context.db.insert(account).values({ id: event.args.from, balance: 0n });
 
// createMany -> insert
await context.db.Account.createMany({
  data: [
    { id: event.args.from, balance: 0n },
    { id: event.args.to, balance: 0n },
  ],
});
await context.db.insert(account).values([
  { id: event.args.from, balance: 0n },
  { id: event.args.to, balance: 0n },
]);
 
// findUnique -> find
await context.db.Account.findUnique({ id: event.args.from });
await context.db.find(account, { address: event.args.from });
 
// update
await context.db.Account.update({
  id: event.args.from,
  data: ({ current }) => ({ balance: current.balance + 100n }),
});
await context.db
  .update(account, { address: event.args.from })
  .set((row) => ({ balance: row.balance + 100n }));
 
// upsert
await context.db.Account.upsert({
  id: event.args.from,
  create: { balance: 0n },
  update: ({ current }) => ({ balance: current.balance + 100n }),
});
await context.db
  .insert(account)
  .values({ address: event.args.from, balance: 0n })
  .onConflictDoUpdate((row) => ({ balance: row.balance + 100n }));
 
// delete
await context.db.Account.delete({ id: event.args.from });
await context.db.delete(account, { address: event.args.from });
 
// findMany -> raw SQL select, see below
await context.db.Account.findMany({ where: { balance: { gt: 100n } } });
await context.db.sql.select().from(account).where(eq(account.balance, 100n));
 
// updateMany -> raw SQL update, see below
await context.db.Player.updateMany({
  where: { id: { startsWith: "J" } },
  data: { age: 50 },
});
await context.db.sql
  .update(player)
  .set({ age: 50 })
  .where(like(player.id, "J%"));
```

--------------------------------

### Ponder DB List Command

Source: https://ponder.sh/docs/api-reference/ponder/cli

Lists all Ponder deployments and their status.

```bash
Usage: ponder db list [options]
 
List all Ponder deployments
 
Options:
  -h, --help  display help for command
```

```text
│ Schema        │ Active   │ Last active    │ Table count │
├───────────────┼──────────┼────────────────┼─────────────┤
│ indexer_prod  │      yes │            --- │          10 │
│ test          │       no │    26m 58s ago │          10 │
│ demo          │       no │      1 day ago │           5 │
```

--------------------------------

### Configure PonderProvider

Source: https://ponder.sh/docs/api-reference/ponder-react

Wrap your application with PonderProvider to provide the SQL client instance to child components.

```typescript
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { PonderProvider } from "@ponder/react";
import { client } from "../lib/ponder"; // Client instance from @ponder/client
 
const queryClient = new QueryClient();
 
function App() {
  return (
    <PonderProvider client={client}>
      <QueryClientProvider client={queryClient}>
        {/* Your application components */}
      </QueryClientProvider>
    </PonderProvider>
  );
}
```
Tokens:
Raw