harb/onchain/analysis/README.md

# KRAIKEN Fuzzing Analysis Tools

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

## Quick Start

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
./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