harb/services/ponder/AGENTS.md

Ponder Indexer - Agent Guide

Ponder-based indexer that records Kraiken protocol activity and exposes the GraphQL API consumed by the app and automation bot.

Responsibilities

• Track Kraiken token transfers and staking events to maintain protocol stats, hourly ring buffers, and position state.
• Serve a GraphQL endpoint at http://localhost:42069/graphql for downstream consumers.
• Support BASE_SEPOLIA_LOCAL_FORK, BASE_SEPOLIA, and BASE environments through a single TypeScript codebase.

Key Files

• ponder.config.ts - Network selection and contract bindings (update addresses after deployments).
• ponder.schema.ts - Stats, hourly data, and position tables.
• src/kraiken.ts / src/stake.ts - Event handlers; rely on Ponder v0.13 helpers for on-chain reads during sync.
• .ponder/ - Local SQLite/state cache (safe to delete when schemas change).

Development Workflow

• Primary path: nohup ./scripts/local_env.sh start & boots Anvil, deploys contracts, and launches Ponder in watch mode.
• Focused debugging: within services/ponder/, run npm install then PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK npm run dev once the stack is already online.
• For production-style runs, use npm run build followed by PONDER_NETWORK=BASE npm run start and point DATABASE_URL to PostgreSQL if persistence is required.

Operational Guidelines

• Confirm handler timestamps are monotonic; large gaps (>168 hours) reset the ring buffer by design.
• Regenerate typings after schema edits by restarting Ponder; generated artifacts live in generated/.
• If the stack script fails during boot, check .ponder/logs and RPC quota usage before rerunning.

Quality Checks

• Avoid reintroducing legacy subgraph assumptions; rely solely on Ponder schema helpers.
• Keep handler logic deterministic and idempotent; reorgs trigger replays.
• Use the Ponder client helpers (context.client, context.contracts) instead of manual RPC calls where possible.