80f0b8217c
- Restructure CLAUDE.md to lead with unique technical innovations - Add comprehensive TECHNICAL_APPENDIX.md with detailed analysis - Focus on conceptual clarity for AI assistant guidance - Merge redundant sections and condense development commands - Clarify economic model and user journeys - Add proper cross-references between documents 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
95 lines
No EOL
4.1 KiB
Markdown
95 lines
No EOL
4.1 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
|
|
- 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).* |