Indexer

The indexer runs two processes: Ponder records chain events, and a credit worker settles finalized payments into application credit.

bun run indexer:start supervises both processes. bun run indexer:serve serves indexed data only; it does not replace the credit worker. For separate services, use bun run --filter @agentpass/indexer start:chain and bun run --filter @agentpass/indexer start:credits with matching configuration.

Configuration

Set DATABASE_URL, DATABASE_SCHEMA, PONDER_CHAIN_ID, PONDER_RPC_URL, PONDER_TOPUP_ADDRESS, and PONDER_TOPUP_START_BLOCK. The address is the new payment contract; the start block must include its deployment and all payments. Use the same PostgreSQL database as the web app.

Legacy proxy addresses are optional. When set, PONDER_START_BLOCK is also required. Keep them configured if you need historical claims and reward indexing.

The current testnet deployment uses schema agentpass_testnet_topups_v2, topup start block 140887163, and legacy start block 140218512. The previous agentpass_testnet and agentpass_testnet_topups schemas are retained. The first payment contract was paused and all its events were reconciled with credited payments before switching the worker. Existing legacy rows were compared before switching the web app. The undeployed TaxSplitter placeholder is disabled.

Ponder build changes require a new deployment schema. Start in production mode, let backfill finish, compare historical data, then point the app at that schema. Keep the application ledger and shared sync cache. Do not run development mode against a retained production schema.

Both commands supervise Ponder and the credit worker. Workspace commands start:chain and start:credits run them separately. PGlite supports chain-only indexing, not application credit settlement.

Finality and replay

The worker uses the lower of RPC finalized height and head - 15. It re-fetches each successful receipt and canonical block, matches the configured contract and event payload, then records one credit grant per event. Missing finality support or RPC errors delay credit and are retried.

The application primary key is (chain_id, contract_address, tx_hash, log_index). Grant sources contain the same identity. Application payment and grant insertion are atomic, including under multiple workers.

Ponder may replay its event tables after reorgs or deployments. Preserve the application schema. Replaying already-credited events cannot add credit again.

Monitor settlement errors and finalized events waiting for a credit record. Repair the source of a mismatch before retrying; do not manually add another grant for the same payment.