johba/harb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
harb/onchain/analysis/README.md
johba 137adfe82b another rewrite
2025-08-23 22:32:41 +02:00

4.3 KiB
Raw Blame History

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

  • 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

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

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

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