fce4b8b068
AGENTS.md watermarks refreshed to HEAD (358f719). Content updates:
- scripts/harb-evaluator/AGENTS.md: documented wallet.ts auto-reconnect
fix (wagmi EIP-6963 auto-connect handling, 10s disconnect timeout)
- All other AGENTS.md files: watermark bump only
Pending actions (3): promote #1155 pitch-deck to backlog.
Escalate: #1158 (Phase 1 completion accuracy) — needs planner/human decision.
89 lines
6.7 KiB
Markdown
89 lines
6.7 KiB
Markdown
<!-- last-reviewed: 358f719e2143ed0f99c738c61f1af9b544b03422 -->
|
|
# 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) |
|
|
| `formulas/` | TOML pipeline definitions (sense/act) for the evaluator | [formulas/AGENTS.md](formulas/AGENTS.md) |
|
|
| `scripts/` | `dev.sh`, bootstrap, build helpers; `harb-evaluator/` red-team agent | [scripts/harb-evaluator/AGENTS.md](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
|
|
```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 <files> && .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/`.
|