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`.