harb/onchain/analysis/README.md

# KRAIKEN Fuzzing & Parameter Analysis Tools

Tools for stress-testing the KRAIKEN LiquidityManager against exploitative trading patterns.
All scripts inherit shared infrastructure from `helpers/FuzzingBase.sol`.

For the full research report covering bugs found, floor defense design, parameter safety mapping, and optimizer evolution, see [KRAIKEN_RESEARCH_REPORT.md](KRAIKEN_RESEARCH_REPORT.md).

## Quick Start

```bash
cd onchain

# Single-optimizer fuzzing with per-run CSV output
./analysis/run-fuzzing.sh BullMarketOptimizer runs=10 trades=20

# Adversarial floor-drain attack (sell-heavy, 2000 trades)
./analysis/run-adversarial.sh as=3e17 aw=100

# V3 optimizer adversarial test with staking scenarios
./analysis/run-v3-adversarial.sh

# Fee revenue with background LP competition
./analysis/run-bglp-fee-test.sh as=3e17 aw=100 bglp=40

# Deep 4D parameter space search
./analysis/run-deep-search.sh

# Clean up generated CSV files
./analysis/clean-csvs.sh
```

## Scripts

### Shell Scripts

| Script | Purpose |
|--------|---------|
| `run-fuzzing.sh` | Single-optimizer fuzzing, CSV per run. Args: `runs=N trades=N buybias=N uncapped ci=N as=N aw=N dd=N` |
| `run-adversarial.sh` | Attack specific AS/AW configs with varied buy biases (10-30%). Tests floor drain resilience. |
| `run-v3-adversarial.sh` | Attack OptimizerV3 with staking scenarios (varied staking% and tax rates). |
| `run-v3-step-test.sh` | Test V3 step function across parameter space. **Known bug**: parameter passing causes false positives. |
| `run-deep-search.sh` | Deep search across 4D parameter space (CI × AS × AW × DD). |
| `run-bglp-fee-test.sh` | Fee revenue measurement with Gaussian background LP competition. Args: `as=N aw=N bglp=N` |
| `run-bullbear-sweep.sh` | Deterministic bull→bear parameter sweep. Modes: `quick` (27 combos), `standard` (225 combos). |
| `run-2d-frontier.sh` | 2D (AS × AW) safety frontier mapping. |
| `run-as-sweep.sh` | AS sweep at fixed AW. |
| `clean-csvs.sh` | Clean generated CSV files. |

### Python Scripts

| Script | Purpose |
|--------|---------|
| `scan-final.py` | On-chain LP distribution scanner. Scans real Uniswap V3 pools to compare LP concentration against the BackgroundLP model. |
| `scan-pool-ticks.py` | Pool tick scanner (original). |
| `scan-pool-ticks-fast.py` | Fast pool tick scanner. |
| `scan-pool-ticks-v2.py` | Pool tick scanner v2 with improved coverage. |
| `scan-wide.py` | Wide-range pool tick scanner. |

### Solidity Contracts

| Contract | Purpose |
|----------|---------|
| `StreamlinedFuzzing.s.sol` | Main fuzzing script. ConfigurableOptimizer, staking, BG LP, uncapped swaps. |
| `ParameterSweepFuzzing.s.sol` | Multi-combo sweep in single execution. |
| `BullBearSweep.s.sol` | Deterministic bull→bear scenario. |
| `helpers/FuzzingBase.sol` | Shared infrastructure (environment setup, trade execution, liquidation, CSV output). |
| `helpers/BackgroundLP.sol` | Gaussian competing LP — 5 stacked layers at ±10/20/40/80/160 tick spacings. Buys KRK from pool realistically. Rebalances every 10th recenter. |
| `helpers/SwapExecutor.sol` | Swap execution with optional `uncapped` mode (6th constructor arg) to bypass LiquidityBoundaryHelper. |

## Architecture

```
FuzzingBase.sol (abstract)
├── Environment setup, trade execution, liquidation, token recovery
├── Recenter with time advancement
├── LM ETH measurement, CSV parsing, string helpers
│
├── StreamlinedFuzzing.s.sol  → per-run CSV, named optimizer
├── ParameterSweepFuzzing.s.sol → multi-combo summary CSV
└── BullBearSweep.s.sol → deterministic bull→bear with floor tracking

helpers/
├── BackgroundLP.sol → Gaussian competing LP (5 layers, rebalances on recenters)
├── SwapExecutor.sol → uncapped swap mode
└── FuzzingBase.sol → shared base contract
```

### Shared Constants (FuzzingBase.sol)
| Constant | Value | Purpose |
|----------|-------|---------|
| `LM_FUNDING_ETH` | 200 ether | Default LM ETH funding |
| `LM_INITIAL_WETH` | 100 ether | Initial WETH deposit for LM |
| `RECENTER_GAS_LIMIT` | 50M | Gas limit for recenter calls |
| `RECENTER_TIME_ADVANCE` | 1 hour | Time warp before each recenter |
| `LIQUIDATION_MAX_ATTEMPTS` | 20 | Max sell attempts during liquidation |

## Environment Variables

All variables are read by `StreamlinedFuzzing.s.sol` and passed through by the shell scripts.

| Variable | Default | Description |
|----------|---------|-------------|
| `CI_VALUE` | 0 | Capital inefficiency (0-1e18). Pure risk lever, zero fee effect. |
| `AS_VALUE` | 1e17 | Anchor share (0-1e18). ETH split between floor and anchor. |
| `AW_VALUE` | 20 | Anchor width (0-200+). Ticks of anchor position width. |
| `DD_VALUE` | 5e17 | Discovery depth (0-1e18). Zero safety effect. |
| `BUY_BIAS` | 50 | % of trades that are buys (0-100). 10 = adversarial sell-heavy. |
| `TRADES_PER_RUN` | 15 | Trades per run. 2000 for deep adversarial tests. |
| `FUZZING_RUNS` | 1 | Runs per forge invocation. **Must be 1 for 2000-trade runs** (MemoryOOG). |
| `BATCH_SEED` | 0 | Random seed. Each batch produces unique scenario IDs. Loop in shell for >1 run. |
| `OPTIMIZER_CLASS` | BullMarketOptimizer | Which optimizer to deploy. Use `ConfigurableOptimizer` for custom params. |
| `UNCAPPED_SWAPS` | false | Bypass LiquidityBoundaryHelper for uncapped swap amounts. |
| `BG_LP_ETH_PER_LAYER` | 0 | ETH per BackgroundLP Gaussian layer (0 = disabled). 40 = 200 ETH total. |
| `STAKING_LEVEL` | 0 | Staking % for V3 optimizer (0-100). |
| `STAKING_TAX_RATE` | 3 | Tax rate index for V3 optimizer (0-29). |

### ParameterSweepFuzzing-specific
| Variable | Default | Description |
|----------|---------|-------------|
| `TRADES_PER_RUN` | 30 | Trades per run |
| `RUNS_PER_COMBO` | 5 | Runs per parameter combination |
| `CI_VALUES` | 0,0.5e18,1e18 | Comma-separated capitalInefficiency values |
| `AS_VALUES` | 0.1e18,0.5e18,1e18 | Comma-separated anchorShare values |
| `AW_VALUES` | 30,50,80 | Comma-separated anchorWidth values |
| `DD_VALUES` | 0.2e18,1e18 | Comma-separated discoveryDepth values |
| `BB_VALUES` | 60,80,100 | Comma-separated buyBias values |
| `SWEEP_TAG` | SWEEP | Output filename tag |

### BullBearSweep-specific
| Variable | Default | Description |
|----------|---------|-------------|
| `BULL_BUYS` | 10 | Number of buys in bull phase |
| `BUY_SIZE_ETH` | 15 | ETH per buy |
| `LM_FUNDING_ETH` | 200 | LM funding (ETH) |
| `SWEEP_TAG` | BULLBEAR | Output filename tag |

## Constraints

- **1 run per forge invocation**: EVM MemoryOOG after ~2 runs of 2000 trades. Loop in shell with `BATCH_SEED=N`.
- **VPS: 8GB RAM, no swap**: Cargo tests OOM. Use `CARGO_BUILD_JOBS=1`.
- **Disk**: Run `clean-csvs.sh` periodically to reclaim space.
- **Forge PATH**: `~/.foundry/bin/forge` (not in default PATH on VPS).
- **Bash integer overflow**: Wei values > 2^63 overflow `[ $A -gt $B ]` — use `bc` for comparison.

## Data Files

| File | Description |
|------|-------------|
| `2D_FRONTIER_LOG.md` | 29-combo (AS, AW) adversarial safety frontier |
| `2d-frontier-results.csv` | Machine-readable frontier data |
| `V3_FUZZING_LOG.md` | V3 adversarial test results |
| `V3_STEP_LOG.md` | Step function test results |
| `FUZZING_LOG.md` | General fuzzing log |
| `AS_SWEEP_LOG.md` | AS sweep results |
| `PARAMETER_SEARCH_RESULTS.md` | Full 4D parameter search (1050 combos) |
| `KRAIKEN_RESEARCH_REPORT.md` | Comprehensive research report (bugs, floor defense, optimizer, staking) |
| `fuzz-*.csv` | Per-run tick trace CSVs (generated, gitignored) |

## Visualization

```bash
# Generate CSVs and launch visualizer
./analysis/run-fuzzing.sh BullMarketOptimizer debugCSV

# Or manually
cd analysis && python3 -m http.server 8000
# Open http://localhost:8000/run-visualizer.html
```

## Test Coverage

`test/FuzzingAnalyzerBugs.t.sol` validates:
- Round-trip loss (buy→recenter→sell shows trader loss)
- PnL leakage prevention (cleanup between runs eliminates false positives)
- Multi-cycle cumulative loss
- Capped vs uncapped swap behavior
- WETH conservation across the system