harb/onchain/CLAUDE.md

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:

outstandingSupply -= pulledHarb;      // Anchor KRAIKEN
outstandingSupply -= discoveryAmount; // Discovery KRAIKEN

ETH Scarcity Check

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

Standard Fuzzing

Test strategy resilience across market conditions:

# Quick test (50 runs, position CSV)
./analysis/run-fuzzing.sh BullMarketOptimizer debugCSV

# Full campaign (custom runs/trades)
./analysis/run-fuzzing.sh WhaleOptimizer runs=100 trades=30

Advanced Recording & Replay System

Find and Record Invariant Violations:

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

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

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 - Math reference
• IMPORTANT: do not modify implementation files like LiquidityProvider or ThreePositionStrategy