Smart Contracts - CLAUDE.md

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

Architecture Overview

Core Contracts

Kraiken.sol - ERC20 token contract with controlled minting/burning capabilities

Implements Harberger tax mechanism for staking positions
Controls minting rights exclusively for LiquidityManager
Handles tax collection and redistribution

LiquidityManager.sol - Dominant liquidity provider with three-position anti-arbitrage strategy

Uses Optimizer contract for dynamic parameter adjustment
Inherits from ThreePositionStrategy and PriceOracle (with VWAPTracker)
Key Feature: Asymmetric slippage profile prevents profitable trade-recenter-reverse attacks

VWAPTracker.sol - "Eternal memory" protection against dormant whale attacks

Volume-weighted average pricing with data compression (max 1000x)
Provides historical price memory to prevent manipulation

Optimizer.sol - Sentiment analysis and parameter optimization

Analyzes staking data (% staked, average tax rate)
Provides dynamic liquidity parameters
Upgradeable for future genetic algorithm implementation

Stake.sol - Harberger tax-based staking mechanism

Creates sentiment oracle through continuous auction
Limited to 20% of total supply (20,000 positions)
Self-assessed tax rates create prediction market

Position Strategy

Order: ANCHOR → DISCOVERY → FLOOR

ANCHOR: Shallow liquidity around current price for fast price movement (1-100% width range)
DISCOVERY: Proportional to KRAIKEN minted by anchor; borders anchor for fee capture (11000 tick spacing)
FLOOR: Deep liquidity using VWAP-adjusted pricing for historical price memory

Technical Specifications:

Fee Tier: 1% (10,000 basis points)
Tick Spacing: 200 (base), 11,000 (discovery)
Price Validation: 5-minute TWAP with 50-tick deviation tolerance
VWAP Compression: Maximum 1000x compression factor

Development Commands

# Build contracts
forge build

# Run all tests
forge test

# Run tests with gas reporting
forge test --gas-report

# Run specific test file
forge test --match-path test/LiquidityManager.t.sol

# Run fuzzing with more runs
forge test --fuzz-runs 10000

# Deploy contracts (see script/Deploy.s.sol)
forge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast

Testing Architecture

Test Helpers

test/helpers/UniswapTestBase.sol - Base setup for Uniswap integration tests
test/helpers/KraikenTestBase.sol - Common test utilities for KRAIKEN contracts
test/helpers/PositionRenderer.sol - Visualization tools for liquidity positions

Key Test Files

test/LiquidityManager.t.sol - Core liquidity management tests
test/abstracts/ThreePositionStrategy.t.sol - Position strategy validation
test/Stake.t.sol - Harberger tax mechanism tests
test/VWAPTracker.t.sol - Price memory and compression tests

Code Quality Guidelines

CRITICAL: Avoid Duplicate Code

ALWAYS check lib/uni-v3-lib for existing Uniswap math functions
NEVER reimplement standard math operations
Use test/helpers for common test patterns

Security Considerations

All external calls must be reentrancy protected
Price oracles must validate against manipulation
Tax calculations must handle edge cases (0 rates, max uint256)

Gas Optimization

Batch operations where possible
Use storage patterns that minimize SSTORE operations
Leverage Uniswap's existing math libraries

Analysis Tools

The analysis/ subdirectory contains critical tools for understanding and hardening the protocol:

Growth mechanism simulations
Attack vector analysis
Liquidity depth scenarios
See analysis/README.md for detailed usage

3.7 KiB Raw Blame History