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
formulas/	TOML pipeline definitions (sense/act) for the evaluator	formulas/AGENTS.md
scripts/	dev.sh, bootstrap, build helpers; harb-evaluator/ red-team agent	scripts/harb-evaluator/AGENTS.md
packages/analytics/	@harb/analytics — self-hosted Umami wrapper for funnel tracking	—
tests/e2e/	Playwright end-to-end tests — desktop + mobile viewports (iPhone 14, Pixel 7), Chromium + Firefox cross-browser matrix; includes conversion funnel spec (07-conversion-funnel.spec.ts)	—
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.

Docker / LXD Notes

• Containers require security_opt: apparmor=unconfined when running inside LXD to avoid permission denied errors on Unix socket creation (Anvil, Postgres).
• Umami analytics runs on port 3001 (moved from 3000 to avoid conflict with Forgejo when running alongside the disinto factory stack).

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.
• viem v2 slot0: slot0() returns an array, not a record. tick is at index 1 (e.g. slot0Response[1]), not slot0Response.tick.

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