# 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
- Tax 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** - Main protocol contract implementing Harberger tax mechanism, token swaps, and tax collection

**LiquidityManager.sol** - Dominant liquidity provider with three-position anti-arbitrage strategy:
- Uses Optimizer contract for dynamic parameter adjustment  
- Inherits from VWAPTracker for dormant whale protection
- **Key Feature**: Asymmetric slippage profile prevents profitable trade-recenter-reverse attacks

**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
- **DISCOVERY**: Proportional to KRAIKEN minted by anchor; borders anchor for fee capture  
- **FLOOR**: Deep liquidity using VWAP-adjusted pricing for historical price memory

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

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