harb/onchain/analysis/CLAUDE.md

KRAIKEN LiquidityManager Fuzzing Analysis

Tools for testing the KRAIKEN LiquidityManager's resilience against various trading strategies to identify scenarios where traders can profit.

Quick Start

Using run-fuzzing.sh (Recommended)

The run-fuzzing.sh script provides an easy way to run fuzzing campaigns with different market optimizers:

# Basic usage - run with specific optimizer
./analysis/run-fuzzing.sh BullMarketOptimizer

# Specify number of runs (default: 50)
./analysis/run-fuzzing.sh WhaleOptimizer runs=100

# Specify trades per run (default: 20, actual will be ±5)
./analysis/run-fuzzing.sh BearMarketOptimizer runs=10 trades=50

# Debug mode - generates position tracking CSV (forces runs=1)
./analysis/run-fuzzing.sh NeutralMarketOptimizer debugCSV

# Multiple parameters
./analysis/run-fuzzing.sh BullMarketOptimizer runs=25 trades=30

Available optimizers:

• BullMarketOptimizer - Biased towards buying
• NeutralMarketOptimizer - Balanced trading
• BearMarketOptimizer - Biased towards selling
• WhaleOptimizer - Large position trading
• MockOptimizer - Test optimizer
• RandomScenarioOptimizer - Random behavior

Features:

• Automatic results aggregation and summary generation
• Progress tracking with colored output
• Cumulative P&L calculation across all runs
• Automatic visualization launch for profitable scenarios
• Organized output in timestamped directories

Manual Fuzzing (Advanced)

# Run fuzzing analysis with default settings (100 runs per market)
forge script analysis/FuzzingAnalysis.s.sol --ffi --via-ir

# Custom configuration
FUZZING_RUNS=500 forge script analysis/FuzzingAnalysis.s.sol --ffi --via-ir

# With position tracking (generates detailed CSV for each scenario)
TRACK_POSITIONS=true FUZZING_RUNS=50 forge script analysis/FuzzingAnalysis.s.sol --ffi --via-ir

Configuration

run-fuzzing.sh Parameters

• optimizer_class: Required. The optimizer class to use (e.g., BullMarketOptimizer)
• runs=N: Optional. Number of fuzzing runs (default: 50)
• trades=N: Optional. Trades per run (default: 20, actual will be ±5)
• debugCSV: Optional. Enable debug mode with position tracking CSV (forces runs=1)

Environment Variables (Manual Mode)

• FUZZING_RUNS: Number of random trading scenarios per market type (default: 100)
• TRACK_POSITIONS: Enable detailed position tracking CSV output (default: false)
• OPTIMIZER_CLASS: The optimizer to use (default: BullMarketOptimizer)
• TRADES_PER_RUN: Number of trades per run (default: 20)
• SEED_OFFSET: Starting seed for random number generation (default: 0)

How It Works

1. Real Deployments: Deploys actual Uniswap V3 factory, pool, and LiquidityManager
2. Random Trading: Generates random buy/sell patterns with varying amounts and timing
3. Recenter Calls: Triggers lm.recenter() at random intervals
4. Profit Detection: Identifies scenarios where traders end with more ETH than they started
5. CSV Export: Saves all profitable scenarios to profitable_scenarios_[timestamp].csv

Output Files

Using run-fuzzing.sh

Each campaign creates a timestamped directory: fuzzing_results_[optimizer]_[timestamp]/

• config.txt - Campaign configuration
• run_*.log - Individual run logs
• merged_profitable_scenarios.csv - All profitable scenarios combined
• summary.txt - Campaign summary with statistics
• debug_positions_*.csv - Position tracking data (when debugCSV is used)

Manual Mode

• profitable_scenarios_[timestamp].csv - Details of all profitable trading sequences
• positions_[scenario]_[seed].csv - Liquidity position data (only with TRACK_POSITIONS=true)

Visualization

# View results in browser
python3 -m http.server 8000
# Open http://localhost:8000/scenario-visualizer.html

# Or use the shell script
./view-scenarios.sh

Analysis Tools

• AnalysisVisualizer.py - Generates charts from CSV data
• scenario-visualizer.html - Interactive web visualization
• RISK_ANALYSIS_FINDINGS.md - Summary of discovered vulnerabilities

Components

• run-fuzzing.sh - Main campaign runner with automatic visualization
• FuzzingAnalysis.s.sol - Core fuzzing script
• helpers/SwapExecutor.sol - Shared swap execution logic
• helpers/CSVManager.sol - CSV generation utilities
• helpers/CSVHelper.sol - CSV formatting helpers

Example Campaign Comparison

To run fuzzing campaigns comparing different market optimizers:

# Run campaigns for all three market conditions
./analysis/run-fuzzing.sh BullMarketOptimizer runs=100
./analysis/run-fuzzing.sh NeutralMarketOptimizer runs=100
./analysis/run-fuzzing.sh BearMarketOptimizer runs=100

# Check results
cat fuzzing_results_*/summary.txt | grep -E "(Optimizer:|Success rate:|Average P&L)"