b4c829e4d6
resolves #25 Co-authored-by: openhands <openhands@all-hands.dev> Co-authored-by: johba <johba@harb.eth> Reviewed-on: https://codeberg.org/johba/harb/pulls/37
49 lines
3.7 KiB
Markdown
49 lines
3.7 KiB
Markdown
# 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](onchain/AGENTS.md)).
|
|
- `services/ponder/` - Ponder indexer powering the GraphQL API ([details](services/ponder/AGENTS.md)).
|
|
- `landing/` - Vue 3 marketing + staking interface ([details](landing/AGENTS.md)).
|
|
- `kraiken-lib/` - Shared TypeScript helpers for clients and bots ([details](kraiken-lib/AGENTS.md)).
|
|
- `services/txnBot/` - Automation bot for `recenter()` and `payTax()` upkeep ([details](services/txnBot/AGENTS.md)).
|
|
|
|
## 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`.
|