# 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

### Standard Fuzzing
Test strategy resilience across market conditions:

```bash
# 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**:
```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_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

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