harb/CLAUDE.md

# 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:

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

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

## User Journey

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

## Project Structure

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

## Quick Start

```bash
# 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](TECHNICAL_APPENDIX.md)
- **Uniswap V3 Math**: [onchain/UNISWAP_V3_MATH.md](onchain/UNISWAP_V3_MATH.md)