Local development

Run Anvil, deploy the contracts, start the indexer, and run the app.

The local stack

Local EVM
Mocks + CreditTopUp
Services
Ponder + credit worker

Configure the stack

The workspace contains apps/web, apps/indexer, packages/contracts, and packages/shared. Use the environment example in each service directory. Web and indexer must share the PostgreSQL database, chain, registry, and payment deployment. Hardhat scripts run on Node; Bun manages workspace scripts.

Start a local node on chain ID 56 or 97. Point browser, server, and indexer RPCs at it.

Run bun run contracts:deploy:mocks:local with a local-only deployer. This creates mock USDT, oracle, and Agent ID registry.

Set TREASURY_ADDRESS, ADMIN_ADDRESS, USDT_ADDRESS, ORACLE_ADDRESS, and AGENT_ID_REGISTRY. Run bun run --filter @agentpass/contracts deploy:topup:local.

Create the database and apply apps/web/supabase.sql, then migrations 002, 003, and 004.

Copy the workspace environment examples and configure the printed topup address/start block, mock registry, chain, RPC, shared database, and session secret. Keep test keys out of git.

Run bun run indexer:dev and bun run dev in separate terminals.

Set a mock handle and token balance for your test wallet. Refresh the mock oracle timestamp if it becomes stale.

The local node must support finalized. Mine at least 15 blocks after a payment and advance finality before expecting credit. A missing finalized tag intentionally blocks settlement.

Exercise the workspace

Open Overview, connect your funded test wallet, and sign in with the gas-free message. Pay a custom amount in Top up and verify the receipt, app.onchain_topups row, and permanent grant. Repeat a worker pass to confirm that credit is not duplicated.

Configure the server-only AI provider credentials before testing Chat or inference. Create a key, list enabled models, send a completion, and compare the charge with the wallet's usage. Test Chat history by reloading with the same wallet. This history is local browser state, not a database migration.

Checks

Database suites require TEST_DATABASE_URL pointing to a local database named agentpass_test_*. Each suite resets its application schema, so run them sequentially when sharing a database.

The full payment-to-credit rehearsal is bun run --filter @agentpass/indexer test:topups:e2e. It needs compiled contract artifacts, Anvil, free ports 8546 and 4201, and its own disposable test database. See the repository runbook docs/28-onchain-topups.md for the test environment and release evidence.