harb/onchain/AGENTS.md

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 (git submodule update --init --recursive), install lib/uni-v3-lib dependencies (npm install in lib/uni-v3-lib/), 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.

Containerized Builds (Podman/Docker)

• Git Submodules: Must be initialized before building (git submodule update --init --recursive). Empty lib/ directories cause compilation failures.
• uni-v3-lib Dependencies: Requires npm install in lib/uni-v3-lib/ to populate node_modules/ with Uniswap interfaces (IUniswapV3Pool, IUniswapV3Factory) and solady dependencies.
• Foundry Image: Use ghcr.io/foundry-rs/foundry:latest for containers. The image includes forge, cast, anvil but NOT jq or curl.
• Root Access: Bootstrap scripts that create deployment artifacts may need to run as root (user: "0:0") to write to mounted volumes.
• Volume Permissions: Use :z (shared SELinux label) instead of :Z (private) for multi-container access to the same mount.

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.