harb/onchain/README.md

# KRAIKEN Onchain

Solidity contracts for the KRAIKEN protocol. Built with Foundry.

## Contracts

| Contract | Description |
|----------|-------------|
| `Kraiken.sol` | ERC20 token with mint/burn controlled by LiquidityManager. VERSION=2. |
| `LiquidityManager.sol` | Three-position Uniswap V3 strategy (Anchor, Discovery, Floor). |
| `Stake.sol` | Harberger-tax staking with snatching auctions and discrete tax brackets. |
| `OptimizerV3.sol` | UUPS upgradeable. Binary bear/bull parameter selection from staking sentiment. |
| `VWAPTracker.sol` | Volume-weighted average price with directional recording and compression. |

## Setup

```bash
git submodule update --init --recursive
cd lib/uni-v3-lib && npm install && cd ../..
forge build
forge test
```

## Deploy

```bash
source .env
forge script script/BaseSepoliaDeploy.sol:BaseSepoliaDeploy --slow --broadcast --verify --rpc-url ${BASE_SEPOLIA_RPC_URL}
```

See [docs/DEPLOYMENT_RUNBOOK.md](../docs/DEPLOYMENT_RUNBOOK.md) for production deployment.

## Deployments

### Base Mainnet

| Contract | Address |
|----------|---------|
| Kraiken | `0x45caa5929f6ee038039984205bdecf968b954820` |
| Stake | `0xed70707fab05d973ad41eae8d17e2bcd36192cfc` |
| LiquidityManager | `0x7fd4e645ce258dd3942eddbeb2f99137da8ba13b` |

### Base Sepolia

| Contract | Address |
|----------|---------|
| Kraiken | `0x22c264Ecf8D4E49D1E3CabD8DD39b7C4Ab51C1B8` |
| Stake | `0xe28020BCdEeAf2779dd47c670A8eFC2973316EE2` |
| LiquidityManager | `0x3d6a8797693a0bC598210782B6a889E11A2340Cd` |

## Research & Analysis

The `analysis/` directory contains fuzzing scripts, parameter sweep tools, and security analysis:

- [SECURITY_REVIEW.md](analysis/SECURITY_REVIEW.md) — Security analysis and vulnerability assessment
- [KRAIKEN_RESEARCH_REPORT.md](analysis/KRAIKEN_RESEARCH_REPORT.md) — Comprehensive research report
- [README.md](analysis/README.md) — Analysis tool usage guide

Key findings: critical sqrt price bug fixed, 1050-combo 4D parameter sweep completed, floor ratchet vulnerability identified. See the research report for details.

## ABI Architecture

Contract ABIs flow through the stack via `kraiken-lib/src/abis.ts`, which imports directly from `out/` (forge build artifacts). Run `forge build` to update ABIs across all consumers (ponder, web-app).

## References

- [AGENTS.md](AGENTS.md) — Agent guide for onchain development
- [UNISWAP_V3_MATH.md](UNISWAP_V3_MATH.md) — Uniswap V3 math reference
- [hAIrberger.md](hAIrberger.md) — Dynamic LP strategy design document