harb/onchain/analysis/README.md

KRAIKEN Fuzzing & Parameter Analysis Tools

Tools for stress-testing the KRAIKEN LiquidityManager against exploitative trading patterns. All scripts inherit shared infrastructure from helpers/FuzzingBase.sol.

For the full research report covering bugs found, floor defense design, parameter safety mapping, and optimizer evolution, see KRAIKEN_RESEARCH_REPORT.md.

Quick Start

cd onchain

# Single-optimizer fuzzing with per-run CSV output
./analysis/run-fuzzing.sh BullMarketOptimizer runs=10 trades=20

# Adversarial floor-drain attack (sell-heavy, 2000 trades)
./analysis/run-adversarial.sh as=3e17 aw=100

# V3 optimizer adversarial test with staking scenarios
./analysis/run-v3-adversarial.sh

# Fee revenue with background LP competition
./analysis/run-bglp-fee-test.sh as=3e17 aw=100 bglp=40

# Deep 4D parameter space search
./analysis/run-deep-search.sh

# Clean up generated CSV files
./analysis/clean-csvs.sh

Scripts

Shell Scripts

Script	Purpose
run-fuzzing.sh	Single-optimizer fuzzing, CSV per run. Args: runs=N trades=N buybias=N uncapped ci=N as=N aw=N dd=N
run-adversarial.sh	Attack specific AS/AW configs with varied buy biases (10-30%). Tests floor drain resilience.
run-v3-adversarial.sh	Attack OptimizerV3 with staking scenarios (varied staking% and tax rates).
run-v3-step-test.sh	Test V3 step function across parameter space. Known bug: parameter passing causes false positives.
run-deep-search.sh	Deep search across 4D parameter space (CI × AS × AW × DD).
run-bglp-fee-test.sh	Fee revenue measurement with Gaussian background LP competition. Args: as=N aw=N bglp=N
run-bullbear-sweep.sh	Deterministic bull→bear parameter sweep. Modes: quick (27 combos), standard (225 combos).
run-2d-frontier.sh	2D (AS × AW) safety frontier mapping.
run-as-sweep.sh	AS sweep at fixed AW.
clean-csvs.sh	Clean generated CSV files.

Python Scripts

Script	Purpose
scan-final.py	On-chain LP distribution scanner. Scans real Uniswap V3 pools to compare LP concentration against the BackgroundLP model.
scan-pool-ticks.py	Pool tick scanner (original).
scan-pool-ticks-fast.py	Fast pool tick scanner.
scan-pool-ticks-v2.py	Pool tick scanner v2 with improved coverage.
scan-wide.py	Wide-range pool tick scanner.

Solidity Contracts

Contract	Purpose
StreamlinedFuzzing.s.sol	Main fuzzing script. ConfigurableOptimizer, staking, BG LP, uncapped swaps.
ParameterSweepFuzzing.s.sol	Multi-combo sweep in single execution.
BullBearSweep.s.sol	Deterministic bull→bear scenario.
helpers/FuzzingBase.sol	Shared infrastructure (environment setup, trade execution, liquidation, CSV output).
helpers/BackgroundLP.sol	Gaussian competing LP — 5 stacked layers at ±10/20/40/80/160 tick spacings. Buys KRK from pool realistically. Rebalances every 10th recenter.
helpers/SwapExecutor.sol	Swap execution with optional uncapped mode (6th constructor arg) to bypass LiquidityBoundaryHelper.

Architecture

FuzzingBase.sol (abstract)
├── Environment setup, trade execution, liquidation, token recovery
├── Recenter with time advancement
├── LM ETH measurement, CSV parsing, string helpers
│
├── StreamlinedFuzzing.s.sol  → per-run CSV, named optimizer
├── ParameterSweepFuzzing.s.sol → multi-combo summary CSV
└── BullBearSweep.s.sol → deterministic bull→bear with floor tracking

helpers/
├── BackgroundLP.sol → Gaussian competing LP (5 layers, rebalances on recenters)
├── SwapExecutor.sol → uncapped swap mode
└── FuzzingBase.sol → shared base contract

Shared Constants (FuzzingBase.sol)

Constant	Value	Purpose
LM_FUNDING_ETH	200 ether	Default LM ETH funding
LM_INITIAL_WETH	100 ether	Initial WETH deposit for LM
RECENTER_GAS_LIMIT	50M	Gas limit for recenter calls
RECENTER_TIME_ADVANCE	1 hour	Time warp before each recenter
LIQUIDATION_MAX_ATTEMPTS	20	Max sell attempts during liquidation

Environment Variables

All variables are read by StreamlinedFuzzing.s.sol and passed through by the shell scripts.

Variable	Default	Description
CI_VALUE	0	Capital inefficiency (0-1e18). Pure risk lever, zero fee effect.
AS_VALUE	1e17	Anchor share (0-1e18). ETH split between floor and anchor.
AW_VALUE	20	Anchor width (0-200+). Ticks of anchor position width.
DD_VALUE	5e17	Discovery depth (0-1e18). Zero safety effect.
BUY_BIAS	50	% of trades that are buys (0-100). 10 = adversarial sell-heavy.
TRADES_PER_RUN	15	Trades per run. 2000 for deep adversarial tests.
FUZZING_RUNS	1	Runs per forge invocation. Must be 1 for 2000-trade runs (MemoryOOG).
BATCH_SEED	0	Random seed. Each batch produces unique scenario IDs. Loop in shell for >1 run.
OPTIMIZER_CLASS	BullMarketOptimizer	Which optimizer to deploy. Use ConfigurableOptimizer for custom params.
UNCAPPED_SWAPS	false	Bypass LiquidityBoundaryHelper for uncapped swap amounts.
BG_LP_ETH_PER_LAYER	0	ETH per BackgroundLP Gaussian layer (0 = disabled). 40 = 200 ETH total.
STAKING_LEVEL	0	Staking % for V3 optimizer (0-100).
STAKING_TAX_RATE	3	Tax rate index for V3 optimizer (0-29).

ParameterSweepFuzzing-specific

Variable	Default	Description
TRADES_PER_RUN	30	Trades per run
RUNS_PER_COMBO	5	Runs per parameter combination
CI_VALUES	0,0.5e18,1e18	Comma-separated capitalInefficiency values
AS_VALUES	0.1e18,0.5e18,1e18	Comma-separated anchorShare values
AW_VALUES	30,50,80	Comma-separated anchorWidth values
DD_VALUES	0.2e18,1e18	Comma-separated discoveryDepth values
BB_VALUES	60,80,100	Comma-separated buyBias values
SWEEP_TAG	SWEEP	Output filename tag

BullBearSweep-specific

Variable	Default	Description
BULL_BUYS	10	Number of buys in bull phase
BUY_SIZE_ETH	15	ETH per buy
LM_FUNDING_ETH	200	LM funding (ETH)
SWEEP_TAG	BULLBEAR	Output filename tag

Constraints

• 1 run per forge invocation: EVM MemoryOOG after ~2 runs of 2000 trades. Loop in shell with BATCH_SEED=N.
• VPS: 8GB RAM, no swap: Cargo tests OOM. Use CARGO_BUILD_JOBS=1.
• Disk: Run clean-csvs.sh periodically to reclaim space.
• Forge PATH: ~/.foundry/bin/forge (not in default PATH on VPS).
• Bash integer overflow: Wei values > 2^63 overflow [ $A -gt $B ] — use bc for comparison.

Data Files

File	Description
2D_FRONTIER_LOG.md	29-combo (AS, AW) adversarial safety frontier
2d-frontier-results.csv	Machine-readable frontier data
V3_FUZZING_LOG.md	V3 adversarial test results
V3_STEP_LOG.md	Step function test results
FUZZING_LOG.md	General fuzzing log
AS_SWEEP_LOG.md	AS sweep results
PARAMETER_SEARCH_RESULTS.md	Full 4D parameter search (1050 combos)
KRAIKEN_RESEARCH_REPORT.md	Comprehensive research report (bugs, floor defense, optimizer, staking)
fuzz-*.csv	Per-run tick trace CSVs (generated, gitignored)

Visualization

# Generate CSVs and launch visualizer
./analysis/run-fuzzing.sh BullMarketOptimizer debugCSV

# Or manually
cd analysis && python3 -m http.server 8000
# Open http://localhost:8000/run-visualizer.html

Test Coverage

test/FuzzingAnalyzerBugs.t.sol validates:

• Round-trip loss (buy→recenter→sell shows trader loss)
• PnL leakage prevention (cleanup between runs eliminates false positives)
• Multi-cycle cumulative loss
• Capped vs uncapped swap behavior
• WETH conservation across the system