api-v3 AGENTS.md

cfg-api-v3 — AI & contributor guide

Centrifuge protocol indexer: Ponder ingests EVM logs/blocks → src/handlers/ → src/services/ → PostgreSQL (Drizzle); GraphQL while running. Setup/ops: README.md. Extra Cursor rules: .cursor/rules/*.mdc (always-on summary: cfg-api-v3-core.mdc).

Hard rules

1. Handlers — Only under src/handlers/. Subscribe with multiMapper(...) or ponder.on(...). Thin: decode event.args, orchestrate; no heavy domain logic here.
2. No DB in handlers — No context.db.*, Drizzle builders, or raw SQL. Use services. Exception: call snapshotter for snapshot inserts (do not duplicate that pattern).
3. No ad-hoc Ponder handler DB — Persistence lives in entity services on Service.ts; do not inline context.db in handlers.
4. Batching — Prefer insertMany / saveMany; query once, update in memory, batch-save when it fits.
5. generated/ — Never edit. Regenerate via pnpm update-registry, pnpm codegen, or build/start tooling; fix registry/upstream instead.

Services

• Shape: one service per main schema entity (or tight group). export class EntityService extends Service<typeof Table> { static readonly entityTable = Table; static readonly entityName = "EntityName"; } — see AdapterService.ts. Statics (on Service): insert, insertMany, saveMany, get, getOrInit, upsert, query, count; instance save / delete. Add methods for shared business rules.
• Logging — serviceLog / serviceError from logger.ts; expandInlineObject for record-shaped logs. Every meaningful public/static method (DB, side effects, non-trivial branches) logs at least once; trivial pure accessors (e.g. shallow read()) need not. serviceLog is a no-op under ponder start; serviceError still logs — see logger.ts.
• Handlers never call context.db.sql / context.db.find; they call FooService.get(...) etc. Base layer uses Drizzle internally.
• Batch upserts — Extending saveMany: follow Service.ts comment; use sql.raw(\excluded."column"`)for Ponder’s PG proxy, not brokenexcluded` expansions.