harb/AGENTS.md

Agent Brief: Harb Stack

Core Concepts

• KRAIKEN couples Harberger-tax staking with a dominant Uniswap V3 liquidity manager to create asymmetric slippage, sentiment-driven pricing, and VWAP "price memory" safeguards.
• Liquidity dominance is mission-critical; treat any regression that weakens the LiquidityManager's control as a priority incident.
• Harberger staking supplies the sentiment oracle that drives Optimizer parameters, which in turn tune liquidity placement and supply expansion.

User Journey

1. Buy - Acquire KRAIKEN on Uniswap.
2. Stake - Declare a tax rate on kraiken.org to earn from protocol growth.
3. Compete - Snatch undervalued positions to optimise returns.

Operating the Stack

• Start everything with nohup ./scripts/local_env.sh start & and stop via ./scripts/local_env.sh stop. Do not launch services individually.
• Supported environments: BASE_SEPOLIA_LOCAL_FORK (default Anvil fork), BASE_SEPOLIA, and BASE. Match contract addresses and RPCs accordingly.
• The stack boots Anvil, deploys contracts, seeds liquidity, starts Ponder, launches the landing site, and runs the txnBot. Wait for logs to settle before manual testing.

Component Guides

• onchain/ - Solidity + Foundry contracts, deploy scripts, and fuzzing helpers (details).
• services/ponder/ - Ponder indexer powering the GraphQL API (details).
• landing/ - Vue 3 marketing + staking interface (details).
• kraiken-lib/ - Shared TypeScript helpers for clients and bots (details).
• services/txnBot/ - Automation bot for recenter() and payTax() upkeep (details).

Testing & Tooling

• Contracts: run forge build, forge test, and forge snapshot inside onchain/.
• Fuzzing: scripts under onchain/analysis/ (e.g., ./analysis/run-fuzzing.sh [optimizer] debugCSV) generate replayable scenarios.
• Integration: after the stack boots, inspect Anvil logs, hit http://localhost:42069/graphql for Ponder, and poll http://127.0.0.1:43069/status for txnBot health.

Guardrails & Tips

• token0isWeth flips amount semantics; confirm ordering before seeding or interpreting liquidity.
• VWAP, ethScarcity, and Optimizer outputs operate on price^2 (X96). Avoid "normalising" to sqrt inadvertently.
• Fund the LiquidityManager with Base WETH (0x4200...0006) before expecting recenter() to succeed.
• Ponder stores data in .ponder/; drop the directory if schema changes break migrations.
• Keep git clean before committing; never leave commented-out code or untested changes.
• ES Modules: The entire stack uses ES modules. kraiken-lib, txnBot, Ponder, and web-app all require "type": "module" in package.json and use import syntax.
• Podman Named Volumes: kraiken-lib/dist/ is mounted as a named volume (harb_kraiken-dist). After changing module format or build configuration, delete the volume with podman volume rm harb_kraiken-dist and restart to force a clean rebuild.

Handy Commands

• foundryup - update Foundry toolchain.
• anvil --fork-url https://sepolia.base.org - manual fork when diagnosing outside the helper script.
• cast call <POOL> "slot0()" - inspect pool state.
• PONDER_NETWORK=BASE_SEPOLIA_LOCAL_FORK npm run dev (inside services/ponder/) - focused indexer debugging when the full stack is already running.
• curl -X POST http://localhost:42069/graphql -d '{"query":"{ stats(id:\"0x01\"){kraikenTotalSupply}}"}'
• curl http://127.0.0.1:43069/status

References

• Deployment history: onchain/deployments-local.json, onchain/broadcast/.
• Deep dives: TECHNICAL_APPENDIX.md, HARBERG.md, and onchain/UNISWAP_V3_MATH.md.