b7260b2eaf
- Analysis: parameter sweep scripts, adversarial testing, 2D frontier maps - Research: KRAIKEN_RESEARCH_REPORT, SECURITY_REVIEW, STORAGE_LAYOUT - FuzzingBase: consolidated fuzzing helper, BackgroundLP simulation - Sweep results: CSV data for full 4D sweep (1050 combos), bull-bear, AS sweep, VWAP fix validation - Code quality: .gitignore for fuzz CSVs, gas snapshot, updated docs - Remove dead analysis helpers (CSVHelper, CSVManager, ScenarioRecorder) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
177 lines
7.9 KiB
Markdown
177 lines
7.9 KiB
Markdown
# 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
|