124 lines
No EOL
4.1 KiB
Markdown
124 lines
No EOL
4.1 KiB
Markdown
# 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
|
|
- `ImprovedFuzzingAnalysis.s.sol` - Enhanced fuzzing script with staking support and memory optimizations
|
|
- `run-fuzzing.sh` - Shell script to orchestrate multiple fuzzing runs with configurable parameters
|
|
- `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] [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
|
|
./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: 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 200M 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
|
|
- Memory-optimized with circular buffer for position tracking
|
|
- Records all trades to CSV for complete visualization |