johba/harb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

chore: analysis tooling, research artifacts, and code quality

Browse source 
- 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>
This commit is contained in:
openhands 2026-02-13 18:22:03 +00:00
parent d64b63aff4
commit b7260b2eaf
256 changed files with 30276 additions and 1579 deletions
Download patch file Download diff file Expand all files Collapse all files

248
onchain/analysis/README.md
View file

@ -1,125 +1,177 @@
# KRAIKEN Fuzzing Analysis Tools
# KRAIKEN Fuzzing & Parameter Analysis Tools
This directory contains tools for fuzzing the KRAIKEN LiquidityManager to identify potential profitable trading scenarios.
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
# Run fuzzing with default settings (50 runs, 20 trades)
./run-fuzzing.sh BullMarketOptimizer
cd onchain
# Run with custom parameters
./run-fuzzing.sh WhaleOptimizer runs=100 trades=50
# Single-optimizer fuzzing with per-run CSV output
./analysis/run-fuzzing.sh BullMarketOptimizer runs=10 trades=20
# Clean up generated files
./clean.sh
# 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
```
## Files
## Scripts
### Core Scripts
- `StreamlinedFuzzing.s.sol` - Streamlined fuzzing script with staking support and accurate trade recording
- `run-fuzzing.sh` - Shell script to orchestrate multiple fuzzing runs with configurable parameters
- `clean-csvs.sh` - Cleanup script to remove generated CSV files
### Shell Scripts
### Helpers
- `helpers/SwapExecutor.sol` - Handles swap execution through Uniswap
- `helpers/CSVManager.sol` - CSV generation utilities
- `helpers/CSVHelper.sol` - CSV formatting helpers
| 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. |
### Visualization
- `run-visualizer.html` - Interactive web visualization for analyzing individual trades from fuzzing runs
- Supports row-by-row navigation through trades with liquidity distribution charts
### Python Scripts
## Available Optimizers
| 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. |
- `BullMarketOptimizer` - Aggressive parameters for bull market conditions
- `NeutralMarketOptimizer` - Balanced parameters
- `BearMarketOptimizer` - Conservative parameters for bear market conditions
- `WhaleOptimizer` - Simulates large position dominance
- `MockOptimizer` - Standard mock with configurable parameters
- `RandomScenarioOptimizer` - Randomized parameters for each run
### Solidity Contracts
## Usage
| 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. |
### Running Fuzzing Campaigns
## Architecture
```bash
# Basic usage
./run-fuzzing.sh <optimizer_class> [runs=N] [staking=on|off] [buybias=N] [trades=N] [stakingbias=N]
```
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
# Examples
./run-fuzzing.sh BullMarketOptimizer # Uses defaults
./run-fuzzing.sh WhaleOptimizer runs=100 # 100 runs
./run-fuzzing.sh BearMarketOptimizer trades=50 # 50 trades per run
./run-fuzzing.sh NeutralMarketOptimizer runs=25 trades=30 # Both params
./run-fuzzing.sh BullMarketOptimizer runs=50 staking=on buybias=85 trades=100 stakingbias=95 # Full config
helpers/
├── BackgroundLP.sol → Gaussian competing LP (5 layers, rebalances on recenters)
├── SwapExecutor.sol → uncapped swap mode
└── FuzzingBase.sol → shared base contract
```
Parameters:
- `optimizer_class` - Required. The optimizer class to use
- `runs=N` - Optional. Number of fuzzing runs (default: 20)
- `staking=on|off` - Optional. Enable/disable staking (default: on)
- `buybias=N` - Optional. 0-100% bias towards buying vs selling (default: 50)
- `trades=N` - Optional. Trades per run (default: 15, supports 100+ trades)
- `stakingbias=N` - Optional. 0-100% bias towards staking vs unstaking (default: 80)
### Output
Each fuzzing campaign creates a timestamped directory with:
- Individual run logs (`run_N.log`)
- Merged CSV of profitable scenarios
- Summary report with statistics
- Configuration file for reproducibility
### Visualization
To visualize results:
```bash
# Start local web server from analysis directory
cd analysis && python3 -m http.server 8000
# Then open http://localhost:8000/run-visualizer.html
# Or use debugCSV mode which automatically launches visualizer
./analysis/run-fuzzing.sh BullMarketOptimizer debugCSV
```
### Cleanup
Remove all generated files:
```bash
./clean.sh
```
### 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
The fuzzing script supports these environment variables:
- `FUZZING_RUNS` - Number of runs (overridden by script parameter)
- `OPTIMIZER_CLASS` - Optimizer to use (overridden by script parameter)
- `TRADES_PER_RUN` - Trades per run (overridden by script parameter)
- `TRACK_POSITIONS` - Enable detailed position tracking (default: true)
- `ENABLE_STAKING` - Enable staking operations (default: true)
- `BUY_BIAS` - Buy bias percentage (default: 50)
- `STAKING_BIAS` - Staking bias percentage (default: 80)
All variables are read by `StreamlinedFuzzing.s.sol` and passed through by the shell scripts.
## Development
| 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). |
To add a new optimizer:
1. Create the optimizer contract in `../test/mocks/`
2. Import it in `ImprovedFuzzingAnalysis.s.sol`
3. Add it to the `_getOptimizerByClass` function
4. Update this README
### 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 |
## Notes
### 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 |
- Each run deploys a fresh Uniswap V3 environment
- Gas limit is set to 300M for script execution
- Results are deterministic based on the seed
- The fuzzer tests random buy/sell patterns with periodic recenters
- Supports staking operations with position snatching mechanics
- Only records trades that actually execute (non-zero amounts)
- Records actual traded amounts after liquidity limits are applied
- CSV files are written to the analysis/ directory
- Every trade properly updates the tick value
## 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