152 lines
6.7 KiB
Markdown
152 lines
6.7 KiB
Markdown
# 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).*
|