harb/onchain/CLAUDE.md

Smart Contracts - CLAUDE.md

This directory contains the core smart contracts for the KRAIKEN protocol.

Architecture Overview

Core Contracts

Kraiken.sol - ERC20 token with Harberger tax staking

• Controlled minting exclusively by LiquidityManager
• Tax collection and redistribution mechanism
• 20% supply cap for staking (20,000 positions)

LiquidityManager.sol - Dominant liquidity provider

• Three-position anti-arbitrage strategy (ANCHOR, DISCOVERY, FLOOR)
• Dynamic parameter adjustment via Optimizer contract
• Asymmetric slippage profile prevents profitable arbitrage

VWAPTracker.sol - Price memory protection

• Volume-weighted average with data compression (max 1000x)
• Prevents dormant whale manipulation

Optimizer.sol - Dynamic parameter optimization

• Analyzes staking sentiment (% staked, average tax)
• Returns four key parameters for liquidity management
• Upgradeable for future algorithms

Stake.sol - Harberger tax implementation

• Continuous auction mechanism
• Self-assessed valuations create prediction market

Three-Position Strategy

ANCHOR: Near current price, fast price discovery (1-100% width) DISCOVERY: Borders anchor, captures fees (11000 tick spacing)
FLOOR: Deep liquidity at VWAP-adjusted prices

Technical Specs:

• Fee Tier: 1% (10,000 basis points)
• Tick Spacing: 200 (base), 11,000 (discovery)
• Price Validation: 5-minute TWAP, 50-tick tolerance

Optimizer Parameters

1. capitalInefficiency (0 to 1e18): Capital buffer level
2. anchorShare (0 to 1e18): % of non-floor ETH in anchor
3. anchorWidth (0 to 100): Anchor position width %
4. discoveryDepth (0 to 1e18): Discovery liquidity density (2x-10x)

Development

forge build                # Build contracts
forge test                 # Run tests
forge test --gas-report    # Gas optimization
forge test --fuzz-runs 10000  # Extended fuzzing

Testing

• test/helpers/UniswapTestBase.sol - Uniswap integration base
• test/helpers/KraikenTestBase.sol - Common utilities
• Key tests: LiquidityManager.t.sol, Stake.t.sol, VWAPTracker.t.sol

Code Guidelines

• Check lib/uni-v3-lib for existing Uniswap math
• Use test/helpers for common patterns
• Security: Reentrancy protection, oracle validation
• Gas: Batch operations, optimize storage

Analysis Tools

Fuzzing Analysis

Tools for testing KRAIKEN's three-position strategy resilience against various market conditions and trading patterns.

Quick Start

# Run with specific optimizer (50 runs default)
./analysis/run-fuzzing.sh BullMarketOptimizer

# Custom runs and trades
./analysis/run-fuzzing.sh WhaleOptimizer runs=100 trades=30

# Debug mode with position tracking CSV (forces runs=1)
./analysis/run-fuzzing.sh NeutralMarketOptimizer debugCSV

Available Optimizers

• BullMarketOptimizer - Buying bias
• NeutralMarketOptimizer - Balanced trading
• BearMarketOptimizer - Selling bias
• WhaleOptimizer - Large positions
• RandomScenarioOptimizer - Random behavior

Output Structure

Each campaign creates fuzzing_results_[optimizer]_[timestamp]/:

• config.txt - Campaign parameters
• run_*.log - Individual run logs
• merged_profitable_scenarios.csv - Profitable scenarios combined
• summary.txt - Statistics and cumulative P&L
• debug_positions_*.csv - Position data (debugCSV mode only)

Visualization

# Automatic launch with debugCSV
./analysis/run-fuzzing.sh [optimizer] debugCSV

# Manual server (port 8000)
./analysis/view-scenarios.sh

Advanced Usage

# Manual fuzzing with environment variables
FUZZING_RUNS=500 TRACK_POSITIONS=true forge script analysis/FuzzingAnalysis.s.sol --ffi --via-ir

Environment variables:

• FUZZING_RUNS - Scenarios per market (default: 100)
• TRACK_POSITIONS - Enable position CSV (default: false)
• OPTIMIZER_CLASS - Optimizer to use
• TRADES_PER_RUN - Trades per run (default: 20)

Uniswap V3 Math

See UNISWAP_V3_MATH.md for detailed math concepts.