# Agent Brief: Harb Stack ## What is KRAIKEN? 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. ## 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. ## Directory Map | Path | What | Guide | |------|------|-------| | `onchain/` | Solidity + Foundry contracts, deploy scripts, fuzzing | [onchain/AGENTS.md](onchain/AGENTS.md) | | `services/ponder/` | Ponder indexer powering the GraphQL API | [services/ponder/AGENTS.md](services/ponder/AGENTS.md) | | `landing/` | Vue 3 marketing + staking interface | [landing/AGENTS.md](landing/AGENTS.md) | | `web-app/` | Staking UI | [web-app/AGENTS.md](web-app/AGENTS.md) | | `kraiken-lib/` | Shared TypeScript helpers for clients and bots | [kraiken-lib/AGENTS.md](kraiken-lib/AGENTS.md) | | `services/txnBot/` | Automation bot for `recenter()` and `payTax()` upkeep | [services/txnBot/AGENTS.md](services/txnBot/AGENTS.md) | | `scripts/` | `dev.sh`, bootstrap, build helpers; `harb-evaluator/` red-team agent | — | | `tests/e2e/` | Playwright end-to-end tests | — | | `docs/` | Architecture, product truth, environment, ops guides | — | ## Quick Start ```bash ./scripts/dev.sh start # boots full stack (~3-6 min first time) ./scripts/dev.sh health # verify all services healthy ./scripts/dev.sh stop # stop and clean up ``` See [docs/dev-environment.md](docs/dev-environment.md) for restart modes, ports, Docker topology, and common pitfalls. ## Red-team Agent Context The red-team agent (`scripts/harb-evaluator/red-team.sh`) injects the following Solidity sources into the agent prompt so it can reason from exact contract logic: - `LiquidityManager.sol` — three-position manager, recenter, floor formula - `ThreePositionStrategy.sol` — position lifecycle abstractions - `Optimizer.sol` / `OptimizerV3.sol` — current candidate under test - `VWAPTracker.sol` / `PriceOracle.sol` — price oracle and VWAP mechanics - `Kraiken.sol` — `outstandingSupply()`, KRK mint/burn, transfer mechanics - `Stake.sol` — `snatch()`, withdrawal, KRK exclusion from floor denominator ## Key Patterns - **ES Modules everywhere**: The entire stack uses `"type": "module"` and `import` syntax. - **`token0isWeth`**: Flips amount semantics; confirm ordering before seeding or interpreting liquidity. - **Price^2 (X96)**: VWAP, `ethScarcity`, and Optimizer outputs operate on price^2. Avoid "normalising" to sqrt inadvertently. - **LiquidityManager funding**: Fund with Base WETH (`0x4200...0006`) before expecting `recenter()` to succeed. - **Ponder state**: Stored in `.ponder/`; drop the directory if schema changes break migrations. - **Harberger staking** supplies the sentiment oracle that drives Optimizer parameters, which in turn tune liquidity placement and supply expansion. ## Engineering Principles These apply to infrastructure (Docker, scripts, startup/teardown) and test/scenario execution — NOT to frontend polling of HTTP APIs where caching is the correct solution. 1. **Never use fixed delays or `waitForTimeout`** — react to actual events instead. Use `eth_subscribe` (WebSocket) for on-chain push notifications, `eth_newFilter` + `eth_getFilterChanges` for on-chain polling, DOM mutation observers or Playwright's `waitForSelector`/`waitForURL` for UI changes, callback patterns for async flows. Even if event-driven code takes more effort, it is always the right answer. 2. **Never use hardcoded expectations** — dynamic systems change. React to actual state, not assumed state. Don't assert a specific block number, token amount, or address unless it's a protocol constant. 3. **Event subscription > polling with timeout > fixed delay** — prefer true push subscriptions (`eth_subscribe`, WebSocket, observers). When push is unavailable (e.g. HTTP-only RPC), polling with a timeout and clear error is acceptable. A fixed `sleep`/`wait`/`waitForTimeout` is never acceptable. Existing violations should be replaced when touched. **Note:** Frontend components polling HTTP APIs (e.g. LiveStats polling Ponder GraphQL) are fine — the scalability solution there is caching at the proxy layer, not subscriptions. ## Before Opening a PR 1. `forge build && forge test` in `onchain/` — contracts must compile and pass. 2. Run `npm run test:e2e` from repo root if you touched frontend or services. 3. `git diff --check` — no trailing whitespace or merge markers. 4. Keep commits clean; never leave commented-out code or untested changes. 5. If you changed `kraiken-lib`, rebuild: `./scripts/build-kraiken-lib.sh`. 6. If you changed contract VERSION or events, update `COMPATIBLE_CONTRACT_VERSIONS` in `kraiken-lib/src/version.ts`. ## Code Quality & Git Hooks Pre-commit hooks (Husky + lint-staged) run ESLint + Prettier on staged files. Each component has its own `.lintstagedrc.json`. To test manually: `git add && .husky/pre-commit`. ## Deeper Docs | Topic | File | |-------|------| | Dev environment, Docker, ports, pitfalls | [docs/dev-environment.md](docs/dev-environment.md) | | Woodpecker CI setup and debugging | [docs/ci-pipeline.md](docs/ci-pipeline.md) | | Testing: Foundry, E2E, version validation | [docs/testing.md](docs/testing.md) | | Codeberg API access and webhooks | [docs/codeberg-api.md](docs/codeberg-api.md) | | Product truth and positioning | [docs/PRODUCT-TRUTH.md](docs/PRODUCT-TRUTH.md) | | Architecture overview | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | | UX decisions | [docs/UX-DECISIONS.md](docs/UX-DECISIONS.md) | | Environment configuration | [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) | | Version validation architecture | [VERSION_VALIDATION.md](VERSION_VALIDATION.md) | | Uniswap V3 math deep dive | [onchain/UNISWAP_V3_MATH.md](onchain/UNISWAP_V3_MATH.md) | | Technical appendix | [TECHNICAL_APPENDIX.md](TECHNICAL_APPENDIX.md) | | Harberger tax mechanics | [HARBERG.md](HARBERG.md) | ## References - Deployment history: `onchain/deployments-local.json`, `onchain/broadcast/`.