johba/harb

johba e04885ad8a docs: Update onchain/CLAUDE.md with debugging insights

Added critical implementation details discovered during floor position debugging:
- VWAPTracker stores price² (squared) in X96 format
- Token calculation gotchas for Amount0/Amount1 functions
- Outstanding supply calculation details
- ETH scarcity sqrt calculation
- Precise optimizer parameter formulas

Made documentation more concise (133→108 lines) while adding actionable debugging tips.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-08-18 18:10:34 +02:00

3 KiB

Raw Blame History

Smart Contracts

Core KRAIKEN protocol contracts implementing the dominant liquidity manager strategy.

Core Contracts

Kraiken.sol - ERC20 with Harberger 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 - Harberger tax

Self-assessed valuations
Continuous auction mechanism

Critical Implementation Details

Token Calculations

When token0isWeth = true:

Amount0 functions return ETH amounts
Amount1 functions return KRAIKEN amounts
Discovery position must use getAmount1ForLiquidity() for KRAIKEN

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

capitalInefficiency (0-1e18)
- 0% = KRAIKEN valued at 70% for reserves
- 100% = KRAIKEN valued at 170% for reserves
anchorShare (0-1e18)
- Floor ETH = totalETH × (1 - anchorShare)²
- 95% anchorShare = 90.1% floor allocation
anchorWidth (0-100)
- % of current price for anchor range
discoveryDepth (0-1e18)
- 2x-10x liquidity multiplier vs anchor

Fuzzing Analysis

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

Optimizers: Bull, Bear, Neutral, Whale, Random

Output: fuzzing_results_[optimizer]_[timestamp]/

Position CSVs show tick placement
Summary shows profitable scenarios

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

3 KiB Raw Blame History Unescape Escape