harb/onchain/AGENTS.md

<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
# Agent Brief: Kraiken Protocol

## Protocol Philosophy & Business Logic

**What KRAIKEN is:** A token with a self-managing liquidity manager (LM) on Uniswap V3. The LM positions liquidity across three positions (floor, anchor, discovery) and recenters them as price moves. An optimizer adjusts parameters based on staking sentiment.

**Revenue model: TRANSACTION FEES are the product.**
- Every swap through the LM's positions generates Uniswap LP fees
- Fees (WETH + KRK) flow to `feeDestination` — this is what founders withdraw
- Locked ETH in the protocol has NO value to founders — it's locked forever
- The protocol WANTS active trading, even if traders extract some ETH

**The optimization target is NOT "minimize trader PnL". It is "maximize fee revenue while keeping the protocol solvent."**

**Four optimizer parameters:**
- `capitalInefficiency (CI)` — adjusts VWAP for floor placement. **Zero effect on fee revenue** — pure risk lever. CI=0% is safest.
- `anchorShare (AS)` — ETH split between floor and anchor
- `anchorWidth (AW)` — anchor position width in ticks
- `discoveryDepth (DD)` — discovery position liquidity density. **Zero effect on floor safety.**

See [TECHNICAL_APPENDIX.md](../TECHNICAL_APPENDIX.md) for floor placement formula, parameter safety frontier, and asymmetric slippage analysis.

## OptimizerV3

`src/OptimizerV3.sol` — UUPS upgradeable. Binary bear/bull from staking sentiment.

**Inputs:** `percentageStaked` (0-100%), `averageTaxRate` (effective index 0-29)

**Mapping:**
- `staked <= 91%` → always **BEAR**: AS=30%, AW=100, CI=0, DD=0.3e18
- `staked > 91%` → **BULL** if `deltaS^3 * effIdx / 20 < 50`: AS=100%, AW=20, CI=0, DD=1e18

The binary step avoids the AW 40-80 kill zone. ~94% of state space maps to bear.

## Staking Triangle Cycle

The staking system traces a triangle in (staking%, avgTax) space:
1. **Fill up:** Staking grows 0→100%, tax low. Optimizer stays bear. Bull at ~95%.
2. **Snatching wars:** 100% staked, tax rises. Always bull.
3. **Collapse:** Nervous exits. Cubic term snaps to bear within 4-6% staking drop.

## System Snapshot
- Kraiken ERC20 with mint/burn via LiquidityManager. VERSION=2.
- LiquidityManager.sol: ANCHOR + DISCOVERY + FLOOR positions with asymmetric slippage.
- VWAPTracker.sol: squared price in X96, compression, directional recording (price-fall / ETH-outflow events only — buy-only cycles must NOT update VWAP or the floor tracks the inflated price, crystallising IL; see issue #543). Uses `_hasRecenterTick` boolean guard to decouple bootstrap detection from VWAP recording — prevents tick-0 ambiguity when `lastRecenterTick==0` after bootstrap (#609).
- OptimizerV3.sol: UUPS upgradeable, direct 2D binary mapping.
- Stake.sol: self-assessed tax, snatching auctions, discrete brackets, UBI redistribution.

## Development Workflow
- Foundry: `forge build`, `forge test`, `forge fmt`, `forge snapshot`.
- Repo: `src/` (contracts), `test/helpers/` (Uniswap/Kraiken bases), `lib/uni-v3-lib` (math), `script/` (deploy).
- Setup: `git submodule update --init --recursive`, `npm install` in `lib/uni-v3-lib/`, Foundry installed.
- **ABI flow**: `kraiken-lib/src/abis.ts` imports from `onchain/out/`. Run `forge build` to update ABIs stack-wide.

## Testing & Analysis
- Fuzzing under `analysis/`: configurable trade/stake biases, adversarial attacks, parameter sweeps. See `analysis/README.md`.
- Adversarial testing (`run-adversarial.sh`, `run-v3-adversarial.sh`) validates floor defense.
- Background LP analysis (`run-bglp-fee-test.sh`) measures fee retention under LP competition.

## Containerized Builds
- Git submodules must be initialized before building.
- `lib/uni-v3-lib/` needs `npm install` for Uniswap interfaces.
- Foundry image: `ghcr.io/foundry-rs/foundry:latest` (includes forge/cast/anvil, NOT jq/curl).
- Volume permissions: use `:z` (shared SELinux label) for multi-container mounts.

## Guardrails
- Respect access controls (`onlyLiquidityManager`, owner).
- `token0isWeth` flips amount semantics — confirm ordering before interpreting liquidity.
- Floor uses `vwapX96` directly (not sqrt) in fixed-point math.
- Outstanding supply excludes LM position balances and KRK held by `feeDestination` (only when `feeDestination != address(0) && feeDestination != address(this)`) and `stakingPool` (only when `stakingPoolAddr != address(0) && stakingPoolAddr != feeDestination`).
- `recenterAccess` is removed — `recenter()` always enforces cooldown and TWAP stability. No bypass path exists.
- `feeDestinationLocked` prevents CREATE2 bypass: once `feeDestination` is set to a contract address, it cannot be changed. `setFeeDestination` checks `.code.length > 0` to detect contract addresses.
- Optimizer input slots 0-7 all require `<= 1e18` — the overflow guard previously only applied to slot 0 (`percentageStaked`); slots 1-7 (including `averageTaxRate`) are now also validated (#997).
- Floor Ratchet attack (buy→stake→recenter oscillation) is defeated — evidence in `evidence/red-team/2026-03-22-floor-ratchet-oscillation.json` and `2026-03-23-floor-ratchet-oscillation.json` shows floor holds under the full 2000-trade oscillation sequence (#1082). Attack script now uses 200-iteration `buy_recenter_loop` with large stake (10M KRK) and proper `vm.warp` time advancement.
- `AttackRunner.s.sol`: `taxRate` param to `snatch()` is an **index into `TAX_RATES[]`**, not a raw rate value. `buy_recenter_loop` now advances `block.timestamp` by 61s per iteration (past 60s recenter cooldown) and calls `recenter()` in the same broadcast as the buy to avoid multi-key issues.
- Fee-income delta_bps calculation is documented in `evidence/README.md`; `LmTotalEth.s.sol` now captures the auditable snapshot methodology (#1084).