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
• web/ - Vue 3/Vite staking interface - See web/CLAUDE.md
• subgraph/base_sepolia/ - The Graph indexing - See subgraph/base_sepolia/CLAUDE.md
• kraiken-lib/ - TypeScript helper library - See kraiken-lib/CLAUDE.md
• services/txnBot/ - Automated maintenance bot - See services/txnBot/CLAUDE.md
• onchain/analysis/ - Growth mechanism analysis tools

Quick Start

# 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
• Contract Details: See onchain/CLAUDE.md
• Frontend Architecture: See web/CLAUDE.md
• Data Indexing: See subgraph/base_sepolia/CLAUDE.md