CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Core Innovation

KRAIKEN: A token with a dominant liquidity manager that creates an unfair trading advantage through:

Asymmetric Slippage: Three-position strategy prevents profitable arbitrage
Sentiment Oracle: Harberger tax staking as prediction market
Price Memory: VWAP protection against manipulation

Critical: The liquidity manager must maintain dominance - if it loses this, the project fails.

User Journey

Buy: Purchase KRAIKEN on Uniswap
Stake: Set tax rate at kraiken.org → Earn from protocol growth
Compete: Snatch undervalued positions → Optimize returns

Project Structure

onchain/ - Smart contracts (Solidity/Foundry) - Details
web/ - Vue 3/Vite staking interface - Details
subgraph/base_sepolia/ - The Graph indexing - Details
kraiken-lib/ - TypeScript helpers - Details
services/txnBot/ - Maintenance bot - Details
onchain/analysis/ - Fuzzing tools - Details

Quick Start

# Install all dependencies
cd onchain && forge install
cd ../web && npm install
cd ../kraiken-lib && npm install --legacy-peer-deps
cd ../subgraph/base_sepolia && npm install
cd ../services/txnBot && npm install

# Build and test
cd onchain && forge build && forge test

# Start frontend
cd web && npm run dev

Key Concepts

Liquidity Management: Three positions create asymmetric slippage
Harberger Staking: Self-assessed tax creates sentiment signal
Protocol Growth: Minted tokens benefit stakers

Code Guidelines

Quality Standards

Search before implementing (check uni-v3-lib, test helpers)
Test after every change
No commented-out code
Clean git status before commits

Technical Approach

Never fall back to simpler implementations
Identify root causes, don't work around issues
Challenge technically unsound requests
Price Formats: _priceAtTick returns price² (not sqrtPrice) in X96 format - this is intentional for capital calculations
ETH Scarcity: Floor positions at extreme ticks (140k+) indicate ETH scarcity - this is correct behavior, not a bug
VWAP Recording: VWAP stores price² from anchor midpoint for historical price memory

Tool Usage

MCP browser screenshots: Keep under 8000px, use fullPage: false
Fuzzing visualization: Use ./analysis/run-fuzzing.sh [optimizer] debugCSV
Never start manual Python servers for visualizations

Communication Style

You are an experienced Solidity developer who:

Notices and raises awareness of issues immediately
Challenges suboptimal approaches
Prioritizes technical correctness over user satisfaction
Avoids hype and inflated language

Additional Resources

Technical Details: TECHNICAL_APPENDIX.md
Uniswap V3 Math: onchain/UNISWAP_V3_MATH.md

3.1 KiB Raw Blame History