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

## User Journey

1. **Buy**: Purchase KRAIKEN on Uniswap → Benefit from growing protocol-owned liquidity
2. **Stake**: Visit kraiken.org → Stake tokens → Set tax rate → Earn from protocol growth
3. **Compete**: Monitor staking positions → Snatch undervalued positions → Optimize tax rates

## Project Structure

- **`onchain/`** - Smart contracts (Solidity/Foundry) - [See onchain/CLAUDE.md](onchain/CLAUDE.md)
- **`web/`** - Vue 3/Vite staking interface - [See web/CLAUDE.md](web/CLAUDE.md)
- **`subgraph/base_sepolia/`** - The Graph indexing - [See subgraph/base_sepolia/CLAUDE.md](subgraph/base_sepolia/CLAUDE.md)
- **`kraiken-lib/`** - TypeScript helper library - [See kraiken-lib/CLAUDE.md](kraiken-lib/CLAUDE.md)
- **`services/txnBot/`** - Automated maintenance bot - [See services/txnBot/CLAUDE.md](services/txnBot/CLAUDE.md)
- **`onchain/analysis/`** - Growth mechanism analysis tools

## Quick Start

```bash
# 1. Install dependencies for all projects
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

# 2. Build smart contracts
cd onchain && forge build && forge test

# 3. Start web interface
cd web && npm run dev
```

## Key Concepts

### Liquidity Management
- Three-position strategy (ANCHOR, DISCOVERY, FLOOR)
- Asymmetric slippage prevents arbitrage
- VWAP tracking for price memory

### Harberger Tax Staking
- Self-assessed tax rates on positions
- Positions can be "snatched" by higher bidders
- Creates prediction market for token value
- Limited to 20% of total supply

### Protocol Growth
- Liquidity manager mints tokens when positions grow
- Stakers benefit from supply expansion
- Tax revenue redistributed to active participants

## Global Code Quality Guidelines

### DRY Principle
- Search for existing implementations before creating new functions
- Check libraries (uni-v3-lib, test helpers) for common utilities
- Refactor duplicated code into shared modules

### Testing
- Run tests after every change
- Never comment out failing tests
- Add tests for new functionality

### Repository Hygiene  
- Remove unused files immediately
- Clean up temporary files
- Check `git status` before commits

### Implementation Strategy
- Never fall back to simpler implementations
- Don't create "a simpler test" or "a simpler scenario" if things don't work out. just try to identify the error in more detail.

## Communication Style

### Direct & Technical
- Challenge suboptimal requests
- Highlight risks early and clearly
- Suggest better alternatives
- Refuse technically unsound solutions

### Priority Order
1. Technical correctness
2. Code quality
3. User satisfaction

**Remember**: Build the best possible system. Question assumptions, identify edge cases, and prioritize long-term success.

## Additional Resources

- **Technical Deep Dive**: See [TECHNICAL_APPENDIX.md](TECHNICAL_APPENDIX.md)
- **Contract Details**: See [onchain/CLAUDE.md](onchain/CLAUDE.md)
- **Frontend Architecture**: See [web/CLAUDE.md](web/CLAUDE.md)
- **Data Indexing**: See [subgraph/base_sepolia/CLAUDE.md](subgraph/base_sepolia/CLAUDE.md)