johba/harb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
harb/AGENTS.md
johba 16abdcbefb fix: add RPC propagation delay after browser-initiated swap (#434) 
After `buyKrk()` completes (swap widget returns to idle), the Anvil RPC may briefly return stale balance state. Adds 2s delay to ensure `getKrkBalance` reads post-swap state.

Without this fix, the holdout scenario reports identical KRK balance before and after swap despite the transaction succeeding (success toast visible).

Co-authored-by: openhands <openhands@all-hands.dev>
Reviewed-on: https://codeberg.org/johba/harb/pulls/434
2026-03-03 22:20:02 +01:00

5 KiB
Raw Blame History

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.

Engineering Principles

These apply to ALL code in this repo — contracts, tests, scripts, indexers, frontend.

  1. Never use fixed delays or waitForTimeout — subscribe to events instead. Use eth_newFilter/eth_subscribe for on-chain events, DOM mutation observers 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 > fixed delay — if there is truly no way to subscribe to an event, polling with a timeout is acceptable. A fixed sleep/wait is never acceptable.

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