harb/onchain/analysis

KRAIKEN Fuzzing Analysis Tools

This directory contains tools for fuzzing the KRAIKEN LiquidityManager to identify potential profitable trading scenarios.

Quick Start

# Run fuzzing with default settings (50 runs, 20 trades)
./run-fuzzing.sh BullMarketOptimizer

# Run with custom parameters
./run-fuzzing.sh WhaleOptimizer runs=100 trades=50

# Clean up generated files
./clean.sh

Files

Core Scripts

• FuzzingAnalysis.s.sol - Main Solidity fuzzing script that tests trading scenarios
• run-fuzzing.sh - Shell script to orchestrate multiple fuzzing runs
• clean.sh - Cleanup script to remove generated files

Helpers

• helpers/SwapExecutor.sol - Handles swap execution through Uniswap
• helpers/CSVManager.sol - CSV generation utilities
• helpers/CSVHelper.sol - CSV formatting helpers

Visualization

• AnalysisVisualizer.py - Python script to generate charts from CSV data
• scenario-visualizer.html - Interactive web visualization
• view-scenarios.sh - Quick script to launch web server for visualization

Available Optimizers

• 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

Usage

Running Fuzzing Campaigns

# Basic usage
./run-fuzzing.sh <optimizer_class> [runs=N] [trades=N]

# 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

Parameters:

• optimizer_class - Required. The optimizer class to use
• runs=N - Optional. Number of fuzzing runs (default: 50)
• trades=N - Optional. Trades per run (default: 20, actual will be ±5)

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:

# Start local web server
./view-scenarios.sh

# Or use Python directly
python3 -m http.server 8000
# Then open http://localhost:8000/scenario-visualizer.html

Cleanup

Remove all generated files:

./clean.sh

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: false)

Development

To add a new optimizer:

1. Create the optimizer contract in ../test/mocks/
2. Import it in FuzzingAnalysis.s.sol
3. Add it to the _getOptimizerByClass function
4. Update this README

Notes

• Each run deploys a fresh Uniswap V3 environment
• Gas limit is set to 200M for --via-ir compilation
• Results are deterministic based on the seed
• The fuzzer tests random buy/sell patterns with periodic recenters