# CLAUDE.md

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

## Core Innovation

KRAIKEN is a token with a **dominant liquidity manager** that creates an unfair advantage in trading through:

1. **Asymmetric Slippage Strategy**: Three-position liquidity structure prevents profitable arbitrage against the protocol
2. **Sentiment Oracle**: Harberger tax-based staking creates a prediction market for token value
3. **Dormant Whale Protection**: VWAP-based price memory prevents historical price manipulation

**Critical Success Factor**: The liquidity manager must maintain its dominant position (trading most of the supply) - if it loses this, the project fails.

## Economic Model

### User Journeys
1. **Token Holders**: Buy KRAIKEN on Uniswap → Hold to benefit from growing liquidity
2. **Stakers**: Stake tokens at kraiken.org → Convert discrete tokens to percentage of total supply → Pay continuous tax rate (self-assigned) → Position can be "snatched" if someone pays higher tax

### Harberger Tax Mechanism
- Continuous auction model where stakers self-assign tax rates on their positions
- Creates prediction market for token value through tax rate signals
- Volume of Stake positions limited to 20% of total supply
- Optimizer contract analyzes percentage staked and average tax rate as sentiment data

### Value Accrual
- Interlocking minting rights and liquidity management drive continuous growth
- More liquidity strengthens token market position
- Analysis scripts in `/onchain/analysis/` demonstrate the growth mechanism
- Exact ETH growth → token value relationship is being researched

## Technical Architecture

### Core Contracts

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

**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 for dormant whale protection)
- **Key Feature**: Asymmetric slippage profile prevents profitable trade-recenter-reverse attacks (verified by fuzzing tests and analysis scripts)

**VWAPTracker.sol** - "Eternal memory" protection against dormant whale attacks through volume-weighted average pricing with data compression (max 1000x)

**Optimizer.sol** - Analyzes staking sentiment data (% staked, average tax rate) and provides dynamic liquidity parameters. Upgradeable for future genetic algorithm implementation.

**Stake.sol** - Harberger tax-based staking mechanism that creates sentiment oracle through continuous auction of staking positions

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

**Recentering**: Open to all, called whenever possible to maintain optimal positions

## Development Commands

### Essential Commands
```bash
# Smart Contracts
forge build && forge test

# TypeScript Library  
npm test && npm run compile

# Subgraph
npm run codegen && npm run build

# Trigger Service
node service.js
```

### Analysis Tools
Critical for hardening the liquidity manager - see `onchain/analysis/README.md` for detailed usage and growth mechanism demonstrations.

## Key Files

- `onchain/src/LiquidityManager.sol` - Core liquidity strategy
- `onchain/src/Kraiken.sol` - Token and tax mechanism
- `onchain/src/Optimizer.sol` - Sentiment analysis and parameter optimization
- `onchain/analysis/` - Growth mechanism analysis and scenario testing
- `services/txnBot/` - Automated recentering and liquidation

## Project Structure
- `onchain/` - Smart contracts (Solidity/Foundry)
- `kraiken-lib/` - TypeScript helper library  
- `subgraph/base_sepolia/` - The Graph subgraph
- `services/txnBot/` - Trigger service for recentering and liquidation
- `onchain/analysis/` - Analysis tools and scenario testing

## Code Quality Guidelines

### CRITICAL: Avoid Duplicate Code
- **ALWAYS** search for existing implementations before creating new functions
    - for example in implementation: uniswap math functions are available from uni-v3-lib
    - for tests, see onchain/test/helpers
- **NEVER** copy/paste code - refactor into shared utilities instead
- If similar functionality exists, extend or refactor it rather than duplicating

### Test Integrity
- **ALWAYS** run `forge test` after making changes to verify all tests pass
- **NEVER** comment out or delete failing tests

### File Management
- **NEVER** leave dead/unused files in the repository
- **ALWAYS** remove files that are no longer needed
- Use `git status` to check for untracked files before committing
- Clean up temporary files and outdated implementations

### Before Any Code Changes
1. Search codebase for existing implementations
2. Run tests to establish baseline
3. Make minimal changes to achieve the goal

### After Any Code Change
1. Run tests again to ensure nothing breaks
2. Clean up any unused files created during development

## Communication Style

### CRITICAL: Project Success Over Politeness
- **CHALLENGE assumptions** - If a request seems suboptimal, question it directly
- **HIGHLIGHT risks** - Point out potential problems even if uncomfortable
- **SUGGEST alternatives** - Propose better approaches when you see them
- **NO sugar-coating** - Be direct about technical limitations or concerns
- **QUESTION requirements** - Ask "why" and "what if" before implementing

### Technical Rigor
- **ALWAYS** identify open questions or unknowns before starting work
- **POINT OUT** missing information or unclear requirements
- **WARN** about potential edge cases or failure modes
- **SUGGEST** additional testing or validation steps
- **REFUSE** to implement solutions you consider technically unsound

### Priority Order
1. **Technical correctness** and project success
2. **Code quality** and maintainability  
3. **User satisfaction** (only after 1 and 2 are met)

**Remember**: Your job is to build the best possible system, not to be agreeable. Challenge bad ideas, suggest improvements, and prioritize long-term success over short-term convenience.

*Note: Detailed technical analysis including attack vectors, VWAP algorithms, and Harberger tax implementation available in [TECHNICAL_APPENDIX.md](TECHNICAL_APPENDIX.md).*