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.