harb/AGENTS.md

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
services/ponder/	Ponder indexer powering the GraphQL API	services/ponder/AGENTS.md
landing/	Vue 3 marketing + staking interface	landing/AGENTS.md
web-app/	Staking UI	web-app/AGENTS.md
kraiken-lib/	Shared TypeScript helpers for clients and bots	kraiken-lib/AGENTS.md
services/txnBot/	Automation bot for recenter() and payTax() upkeep	services/txnBot/AGENTS.md
scripts/	dev.sh, bootstrap, build helpers	—
tests/e2e/	Playwright end-to-end tests	—
docs/	Architecture, product truth, environment, ops guides	—

Quick Start

./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 for restart modes, ports, Docker topology, and common pitfalls.

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.

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 <files> && .husky/pre-commit.

Deeper Docs

Topic	File
Dev environment, Docker, ports, pitfalls	docs/dev-environment.md
Woodpecker CI setup and debugging	docs/ci-pipeline.md
Testing: Foundry, E2E, version validation	docs/testing.md
Codeberg API access and webhooks	docs/codeberg-api.md
Product truth and positioning	docs/PRODUCT-TRUTH.md
Architecture overview	docs/ARCHITECTURE.md
UX decisions	docs/UX-DECISIONS.md
Environment configuration	docs/ENVIRONMENT.md
Version validation architecture	VERSION_VALIDATION.md
Uniswap V3 math deep dive	onchain/UNISWAP_V3_MATH.md
Technical appendix	TECHNICAL_APPENDIX.md
Harberger tax mechanics	HARBERG.md

References

• Deployment history: onchain/deployments-local.json, onchain/broadcast/.