johba/harb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
harb/onchain/AGENTS.md
johba 76d84341de feat: add ABI validation helpers for Ponder (#29) 
resolves https://codeberg.org/johba/harb/issues/23

Co-authored-by: openhands <openhands@all-hands.dev>
Reviewed-on: https://codeberg.org/johba/harb/pulls/29
2025-09-30 20:02:43 +02:00

3 KiB
Raw Blame History

Agent Brief: Kraiken Protocol

System Snapshot

  • Solidity/Foundry DeFi protocol built around the Kraiken ERC20 token, a staking auction, and a three-position Uniswap V3 liquidity manager.
  • LiquidityManager.sol mints/burns supply to maintain ANCHOR (near price), DISCOVERY (offset discovery band), and FLOOR (VWAP-protected) positions with asymmetric slippage to resist arbitrage.
  • VWAPTracker.sol stores squared price in X96 format, compresses history, and feeds adjusted VWAP data for FLOOR placement and ETH scarcity checks.
  • Optimizer.sol (upgradeable) interprets staking sentiment to output capitalInefficiency, anchorShare, anchorWidth, and discoveryDepth parameters.
  • Stake.sol runs the self-assessed tax staking system with snatching auctions, discrete tax brackets, and redistribution to tax recipients/UBI.

Development Workflow

  • Tooling: Foundry (forge build, forge test, forge fmt, forge snapshot), Anvil for local chain, Base Sepolia deployment script (forge script ...BaseSepoliaDeploy).
  • Repo structure highlights: src/ (core contracts), test/helpers/ (Uniswap/Kraiken bases), lib/uni-v3-lib (math + JS setup), script/ (deploy), out/ (artifacts), config via foundry.toml & remappings.txt.
  • Setup steps: clone repo, init/update submodules, install lib/uni-v3-lib dependencies (yarn), ensure Foundry installed.
  • ABI Architecture: Contract ABIs are exported via kraiken-lib/src/abis.ts, which imports directly from onchain/out/ (forge build artifacts). All consumers (ponder, web-app) import from kraiken-lib for type-safe, single-source-of-truth ABIs. Run forge build in onchain/ to update ABIs across the stack.

Strategy & Mechanics

  • Outstanding supply excludes liquidity position balances; enforce 20% staking cap (~20k positions).
  • Anchor width and discovery depth adjusted dynamically; anchorShare tunes ETH allocation, discoveryDepth controls liquidity density multiples (≈2x-10x), capitalInefficiency shifts VWAP floor valuation (70%-170%).
  • token0isWeth flag flips meaning of amount0/amount1 to ETH/KRAIKEN respectively.
  • Recenter logic keeps Uniswap positions aligned; ETH scarcity calculation uses sqrt(vwapX96) and fixed-point math.

Testing & Analysis Suite

  • Fuzzing scripts (./analysis/run-fuzzing.sh, run-recorded-fuzzing.sh) support configurable trade/stake biases, scenario recording (Run IDs), replay scripts, and summary outputs.
  • Optimizer modes: Bull, Bear, Neutral, Whale, Extreme, Malicious for varied stress profiles.
  • Recorded artifacts include JSON scenarios, replay Solidity scripts, CSV tick traces, and human-readable summaries for exploit triage.

Guardrails & Conventions

  • Respect access controls (onlyLiquidityManager, owner) and avoid editing implementation helpers like LiquidityProvider or ThreePositionStrategy.
  • Debug tips: inspect position CSVs, verify token type assumptions, and monitor EthScarcity events during simulations.
  • Staking positions tracked by positionId; tax rates drawn from discrete array within Stake.sol.