another fixup of fuzzer

2025-09-16 22:46:43 +02:00 · 2025-09-16 22:46:43 +02:00 · 0de1cffea8
commit 0de1cffea8
parent c32f1b102b
8 changed files with 375 additions and 700 deletions
--- a/onchain/CLAUDE.md
+++ b/onchain/CLAUDE.md
@ -1,163 +0,0 @@
-# Smart Contracts
-
-Core KRAIKEN protocol contracts implementing the dominant liquidity manager strategy.
-
-## Core Contracts
-
-**Kraiken.sol** - ERC20 with self-assessed tax staking
- `outstandingSupply()` = totalSupply - liquidityManager balance
- Proportional staking pool growth/shrink on mint/burn
- 20% supply cap (20k positions max)
-
-**LiquidityManager.sol** - Three-position strategy
- ANCHOR: Near price (1-100% width)
- DISCOVERY: Borders anchor (11k tick spacing)  
- FLOOR: Deep liquidity at VWAP-adjusted price
- Asymmetric slippage prevents arbitrage
-
-**VWAPTracker.sol** - Historical price memory
- **Stores price² (squared) in X96 format**
- Records anchor midpoint on scrape
- Max 1000x compression on overflow
- `getAdjustedVWAP()` applies capital inefficiency
-
-**Optimizer.sol** - Dynamic parameters
- Reads staking sentiment (% staked, avg tax)
- Returns 4 params for position adjustment
- Upgradeable for new strategies
-
-**Stake.sol** - Self-assessed tax system
- Self-assessed valuations
- Continuous auction mechanism
-
-## Critical Implementation Details
-
-### Token Calculations
-When `token0isWeth = true`:
- Amount0 functions return **ETH** amounts
- Amount1 functions return **KRAIKEN** amounts
-
-### Outstanding Supply
-Excludes tokens used for liquidity positions:
-```solidity
-outstandingSupply -= pulledHarb;      // Anchor KRAIKEN
-outstandingSupply -= discoveryAmount; // Discovery KRAIKEN
-```
-
-### ETH Scarcity Check
-```solidity
-// VWAP is price² in X96, must take sqrt
-uint256 sqrtVwapX96 = Math.sqrt(vwapX96) << 48;
-uint256 requiredEth = outstandingSupply.mulDiv(sqrtVwapX96, 1 << 96);
-```
-
-## Optimizer Parameters
-
-1. **capitalInefficiency** (0-1e18)
-   - 0% = KRAIKEN valued at 70% for reserves
-   - 100% = KRAIKEN valued at 170% for reserves
-   
-2. **anchorShare** (0-1e18)  
-   - 0 anchorShare = 5% of ETH in anchor
-   - 1e18 anchorShare = 25% of ETH in anchor
-   
-3. **anchorWidth** (0-100)
-   - token width of the anchor position, for now we keep it an 50
-   
-4. **discoveryDepth** (0-1e18)
-   - 2x-10x liquidity multiplier vs anchor
-
-## Fuzzing Analysis
-
-### Fuzzing with Staking
-Test strategy resilience with configurable trading and staking:
-
-```bash
-# Basic test with default parameters
-./analysis/run-fuzzing.sh BullMarketOptimizer runs=20
-
-# Advanced test with custom parameters
-./analysis/run-fuzzing.sh BullMarketOptimizer runs=50 staking=on buybias=85 trades=60 stakingbias=95
-```
-
-**Parameters**:
- `runs=N`: Number of fuzzing scenarios (default: 20)
- `staking=on|off`: Enable/disable staking (default: on)
- `buybias=N`: 0-100% bias towards buying vs selling (default: 50)
- `trades=N`: Number of trades per scenario (default: 15, supports 100+ with optimizations)
- `stakingbias=N`: 0-100% bias towards staking vs unstaking (default: 80)
-
-**How it works**:
- Uses random trading strategy with configurable biases
- Staking/unstaking happens automatically every 3rd trade
- Records position data for every trade for complete visualization
- Tracks staking metrics: attempts, successes, snatching events
-
-### Advanced Recording & Replay System
-
-**Find and Record Invariant Violations**:
-```bash
-# Run fuzzing with automatic scenario recording
-./analysis/run-recorded-fuzzing.sh BullMarketOptimizer runs=50
-
-# Output includes unique Run ID (e.g., 241218-A7K9)
-# When profitable scenarios found, creates:
-#   - scenario_[RUN_ID]_seed[N].json  (full recording)
-#   - replay_[RUN_ID]_seed[N].sol     (replay script)
-#   - summary_[RUN_ID]_seed[N].txt    (human summary)
-```
-
-**Replay Captured Scenarios**:
-```bash
-# List all scenarios from a run
-./analysis/replay-scenario.sh 241218-A7K9
-
-# Replay specific scenario
-./analysis/replay-scenario.sh 241218-A7K9 1
-
-# Creates test file and runs replay automatically
-```
-
-**Workflow for Debugging Invariant Violations**:
-1. **Find violations**: Run recorded fuzzing until profitable scenario found
-2. **Capture details**: System automatically records exact action sequence
-3. **Share reference**: Use Run ID (e.g., "Found exploit 241218-A7K9")
-4. **Replay & debug**: Deterministically reproduce the exact scenario
-5. **Test fixes**: Verify fix prevents the recorded exploit
-
-**Optimizers**: 
- `BullMarketOptimizer`: Aggressive risk-taking (best for finding exploits)
- `BearMarketOptimizer`: Conservative positioning
- `NeutralMarketOptimizer`: Balanced approach
- `WhaleOptimizer`: Large capital movements
- `ExtremeOptimizer`: Cycles through parameter extremes
- `MaliciousOptimizer`: Intentionally adversarial parameters
-
-**Output**: `fuzzing_results_[optimizer]_[timestamp]/`
- Unique Run ID for each campaign
- JSON recordings of profitable scenarios
- Replay scripts for exact reproduction
- Position CSVs showing tick movements
- Summary reports with profit calculations
-
-## Development
-
-```bash
-forge build              # Compile
-forge test              # Run tests  
-forge test -vvv         # Debug mode
-forge test --mc Test    # Match contract
-```
-
-**Debugging Tips**:
- Check positions CSV for tick placement
- Verify token types in calculations
- Use EthScarcity events for diagnostics
-
-## Key Files
-
- `test/helpers/UniswapTestBase.sol` - Pool setup
- `test/helpers/KraikenTestBase.sol` - Common utils
- `lib/uni-v3-lib/` - Uniswap V3 math
- [UNISWAP_V3_MATH.md](UNISWAP_V3_MATH.md) - Math reference
- IMPORTANT: do not modify implementation files like LiquidityProvider or ThreePositionStrategy