johba/harb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
harb/AGENTS.md
johba 6cbb1781ce tax rate, version and compose (#70) 
resolves #67

Co-authored-by: johba <johba@harb.eth>
Reviewed-on: https://codeberg.org/johba/harb/pulls/70
2025-10-07 19:26:08 +02:00

6.6 KiB
Raw Blame History

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/dev.sh start & and stop via ./scripts/dev.sh stop. Do not launch services individually.
  • Restart modes for faster iteration:
    • ./scripts/dev.sh restart --light - Fast restart (~10-20s): only webapp + txnbot, preserves Anvil/Ponder state. Use for frontend changes.
    • ./scripts/dev.sh restart --full - Full restart (~3-4min): redeploys contracts, fresh state. Use for contract changes.
  • 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).
  • services/ponder/ - Ponder indexer powering the GraphQL API (details).
  • landing/ - Vue 3 marketing + staking interface (details).
  • kraiken-lib/ - Shared TypeScript helpers for clients and bots (details).
  • services/txnBot/ - Automation bot for recenter() and payTax() upkeep (details).

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.
  • E2E Tests: Playwright-based full-stack tests in tests/e2e/ verify complete user journeys (mint ETH → swap KRK → stake). Run with npm run test:e2e from repo root. Tests use mocked wallet provider with Anvil accounts and automatically start/stop the stack. See INTEGRATION_TEST_STATUS.md and SWAP_VERIFICATION.md for details.

Version Validation System

  • Contract VERSION: Kraiken.sol exposes a VERSION constant (currently v1) that must be incremented for breaking changes to TAX_RATES, events, or core data structures.
  • Ponder Validation: On startup, Ponder reads the contract VERSION and validates against COMPATIBLE_CONTRACT_VERSIONS in kraiken-lib/src/version.ts. Fails hard (exit 1) on mismatch to prevent indexing wrong data.
  • Frontend Check: Web-app validates KRAIKEN_LIB_VERSION at runtime (currently placeholder; future: query Ponder GraphQL for full 3-way validation).
  • CI Enforcement: GitHub workflow validates that contract VERSION is in COMPATIBLE_CONTRACT_VERSIONS before merging PRs.
  • See VERSION_VALIDATION.md for complete architecture, workflows, and troubleshooting.

Podman Orchestration

  • Dependency Management: podman-compose.yml has NO depends_on declarations. All service ordering is handled in scripts/dev.sh via phased startup with explicit health checks.
  • Why: Podman's dependency graph validator fails when containers have compose metadata dependencies, causing "container not found in input list" errors even when containers exist.
  • Startup Phases: (1) Create all containers, (2) Start anvil+postgres and wait for healthy, (3) Start bootstrap and wait for completion, (4) Start ponder and wait for healthy, (5) Start webapp/landing/txn-bot, (6) Start caddy.
  • If you see dependency graph errors, verify depends_on was not re-added to podman-compose.yml.

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.
  • kraiken-lib Build: Run ./scripts/build-kraiken-lib.sh before podman-compose up so containers mount a fresh kraiken-lib/dist from the host.
  • Live Reload: scripts/watch-kraiken-lib.sh rebuilds on file changes (requires inotify-tools) and restarts dependent containers automatically.

Code Quality & Git Hooks

  • Pre-commit Hooks: Husky runs lint-staged on all staged files before commits. Each component (onchain, kraiken-lib, ponder, txnBot, web-app, landing) has .lintstagedrc.json configured for ESLint + Prettier.
  • Version Validation (Future): Pre-commit hook includes validation logic that will enforce version sync between onchain/src/Kraiken.sol (contract VERSION constant) and kraiken-lib/src/version.ts (COMPATIBLE_CONTRACT_VERSIONS array). This validation only runs if both files exist and contain version information.
  • Husky Setup: .husky/pre-commit orchestrates all pre-commit checks. Modify this file to add new validation steps.
  • To test hooks manually: git add <files> && .husky/pre-commit

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.