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

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

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

## 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] [staking=on|off] [buybias=N] [trades=N] [stakingbias=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
./run-fuzzing.sh BullMarketOptimizer runs=50 staking=on buybias=85 trades=100 stakingbias=95  # Full config
```

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

## 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)

## Development

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

## Notes

- 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