harb/AGENTS.md

Agent Brief: Harb Stack

System Map

• onchain/: Foundry workspace for Kraiken token, Harberger staking, Optimizer, and LiquidityManager logic. Deployment scripts live in script/, tests in test/, fuzzing toolchain in analysis/. Use .secret.local mnemonic for local scripts.
• ponder/: New indexer replacing The Graph. ponder.config.ts selects network/contracts, src/ holds TypeScript event handlers, ponder.schema.ts defines tables, README.md documents usage. Generated artifacts in generated/ are auto-created by Ponder.
• subgraph/base_sepolia/: Legacy AssemblyScript implementation kept for reference during migration. Do not modify unless syncing schema changes between stacks.
• landing/: Vue 3 app (Vite + TypeScript) for the public launch site and forthcoming staking UI. See src/views/ for pages, env.d.ts for injected globals.
• services/txnBot/: Node service that consumes the GraphQL API (.graphclient) to trigger recenter() and payTax() on-chain when profitable.
• kraiken-lib/: Shared TypeScript helpers (e.g., bytesToUint256) consumed by the landing app + bots.

Execution Workflow

1. Contracts

   • Build/test via forge build and forge test inside onchain/.
   • Local deployment: run Anvil fork, execute forge script script/DeployLocal.sol --fork-url http://127.0.0.1:8545 --broadcast with .secret.local mnemonic. Script attaches to Base Uniswap V3 factory, creates pool if absent, deploys Optimizer proxy + LiquidityManager, configures Kraiken/Stake links.
   • Post-deploy: fund LiquidityManager (cast send <LM> --value 0.1ether) and call recenter().

2. Indexer (Ponder)

   • Install deps (npm install).
   • Configure environment via PONDER_NETWORK (local, baseSepolia, or base). Update ponder.config.ts addresses if deployments change.
   • Run dev mode with npm run dev; GraphQL served at http://localhost:42069/graphql.
   • Handlers in src/kraiken.ts and src/stake.ts maintain rolling supply stats, ring-buffered hourly metrics, and position state.

3. Frontend

• npm install then npm run dev in landing/. Currently static marketing copy with placeholders for wallet/staking flows.

4. Automation Bot
   • Requires .env with RPC + key. Queries indexer (Graph or Ponder) to decide when to pay tax or recenter liquidity.

Migration Notes (Subgraph → Ponder)

• Schema parity: ensure any entity changes land in both ponder.schema.ts and legacy Graph schema.graphql until cutover.
• Event coverage: Stake events (PositionCreated/Removed/Shrunk/TaxPaid/RateHiked) mirrored from AssemblyScript handlers. Kraiken Transfer powers mint/burn/tax/UBI tracking.
• Ring buffer logic in kraiken.ts depends on block timestamps being monotonic; gaps >168 hours zero out the buffer. Verify startBlock in ponder.config.ts to avoid reprocessing genesis noise.
• Local deployment requires updating ponder.config.ts local contract addresses after each run or injecting via env overrides.
• Ponder v0.13 exposes helpers via context.client / context.contracts; use these to seed stats from on-chain totalSupply and refresh outstandingStake straight from the Stake contract. All hourly projections now run off a JSON ring buffer on the stats row.
• Subgraph naming differs from the new schema (stats_collection, decimal shares). Until the web-app switches to Ponder’s GraphQL endpoint, keep the legacy entity shape in mind. Plan to provide either a compatibility layer or update web-app/src/composables/useStatCollection.ts to hit the new schema.
• Tax accounting must listen to PositionTaxPaid instead of guessing via hard-coded addresses. The old subgraph missed this; Ponder now increments the ring buffer segment on each tax payment.
• Liquidity bootstrap still depends on the Uniswap pool stepping through recenter(). On current Base-Sepolia forks the LM reverts with LOK. Investigate before relying on scripts/local_env.sh start for an unattended setup.

Testing Playbook

• Unit/Fuzz: forge test and scripts under onchain/analysis/ to stress liquidity + staking edge cases.
• Integration (local fork):
  1. anvil --fork-url https://sepolia.base.org (or base mainnet RPC) in terminal 1.
  2. From onchain/, deploy with forge script script/DeployLocal.sol --fork-url http://127.0.0.1:8545 --broadcast.
  3. Fund LiquidityManager, call recenter(), and execute sample trades (KRK buy, stake, unstake) using cast or Foundry scripts.
  4. Start Ponder (PONDER_NETWORK=local npm run dev) and watch logs for handler errors.
  5. Query GraphQL (stats, positions) to confirm indexed state.

Gotchas & Tips

• token0isWeth toggles amount0/amount1 semantics—check pool ordering before seeding liquidity.
• VWAP/ethScarcity logic expects squared price format; do not convert to sqrt unintentionally.
• LiquidityManager recenter() reverts unless funded with WETH (Base WETH address 0x4200...006). Use cast send with sufficient ETH when testing locally.
• Ponder’s SQLite store lives in .ponder/ (gitignored). Delete between runs if schema changes.
• Legacy subgraph still powers services/txnBot until cutover—coordinate endpoint switch when Ponder is production-ready.
• web-app/ currently points at The Graph Studio URLs (see src/config.ts). When Ponder replaces the subgraph, update those envs and mirror the expected GraphQL shape (the app queries stats_collection with camelCase fields). Consider adding an adapter layer or bumping the frontend to the new schema before deleting subgraph/.

Useful Commands

• foundryup / forge clean / forge snapshot
• anvil --fork-url https://sepolia.base.org
• cast call <POOL> "slot0()"
• PONDER_NETWORK=local npm run dev
• curl -X POST http://localhost:42069/graphql -d '{"query":"{ stats(id:\"0x01\"){kraikenTotalSupply}}"}'
• ./scripts/local_env.sh start boots Anvil+contracts+ponder+frontend; stop with Ctrl+C or ./scripts/local_env.sh stop.

Contacts & Artifacts

• Deployment addresses recorded in onchain/deployments-local.json (local) and broadcast traces under onchain/broadcast/.
• Technical deep dive: TECHNICAL_APPENDIX.md & HARBERG.md.
• Liquidity math references: onchain/UNISWAP_V3_MATH.md.