Update documentation structure and add technical appendix
- 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>
This commit is contained in:
giteadmin
parent
eac7360ff9
commit
80f0b8217c
2 changed files with 213 additions and 152 deletions
222
CLAUDE.md
222
CLAUDE.md
|
|
@ -2,176 +2,94 @@
|
|||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Overview
|
||||
## Core Innovation
|
||||
|
||||
KRAIKEN is a multi-component DeFi protocol implementing a Harberger tax mechanism with dynamic liquidity provisioning. The project consists of:
|
||||
KRAIKEN is a token with a **dominant liquidity manager** that creates an unfair advantage in trading through:
|
||||
|
||||
- **Smart Contracts** (Solidity/Foundry) - Core protocol logic
|
||||
- **TypeScript Library** (kraiken-lib) - Helper functions and GraphQL client
|
||||
- **Subgraph** (AssemblyScript) - Blockchain data indexing
|
||||
- **Transaction Bot** (Node.js) - Automated market making service
|
||||
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
|
||||
|
||||
## Architecture
|
||||
**Critical Success Factor**: The liquidity manager must maintain its dominant position (trading most of the supply) - if it loses this, the project fails.
|
||||
|
||||
### Core Components
|
||||
## Economic Model
|
||||
|
||||
1. **Kraiken Contract** (`onchain/src/Kraiken.sol`) - Main protocol contract implementing Harberger tax mechanism
|
||||
2. **Stake Contract** (`onchain/src/Stake.sol`) - Staking mechanism for sentiment data
|
||||
3. **LiquidityManager Contract** (`onchain/src/LiquidityManager.sol`) - Uniswap V3 liquidity management
|
||||
4. **Optimizer Contract** (`onchain/src/Optimizer.sol`) - Dynamic liquidity optimization
|
||||
### 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
|
||||
|
||||
### Key Architecture Patterns
|
||||
### 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
|
||||
|
||||
- **Upgradeable Contracts**: Uses OpenZeppelin's upgradeable pattern
|
||||
- **Uniswap V3 Integration**: Direct integration with Uniswap V3 for liquidity provision
|
||||
- **Genetic Algorithm Approach**: Plans to evolve liquidity strategies using on-chain algorithms
|
||||
- **Sentiment Oracle**: Uses staking data (% staked, average tax rate) as sentiment indicators
|
||||
### 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
|
||||
|
||||
### Smart Contracts (onchain/)
|
||||
|
||||
### Essential Commands
|
||||
```bash
|
||||
# Setup dependencies
|
||||
git submodule init
|
||||
git submodule update
|
||||
cd lib/uni-v3-lib && yarn
|
||||
# Smart Contracts
|
||||
forge build && forge test
|
||||
|
||||
# Build contracts
|
||||
forge build
|
||||
# TypeScript Library
|
||||
npm test && npm run compile
|
||||
|
||||
# Run tests
|
||||
forge test
|
||||
# Subgraph
|
||||
npm run codegen && npm run build
|
||||
|
||||
# Format code
|
||||
forge fmt
|
||||
|
||||
# Gas snapshots
|
||||
forge snapshot
|
||||
|
||||
# Deploy (requires .env setup)
|
||||
forge clean && forge cache clean
|
||||
source .env
|
||||
forge script script/BaseSepoliaDeploy.sol:BaseSepoliaDeploy --slow --broadcast --verify --rpc-url ${BASE_SEPOLIA_RPC_URL}
|
||||
```
|
||||
|
||||
### TypeScript Library (harb-lib/)
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Generate GraphQL types
|
||||
npm run compile
|
||||
|
||||
# Watch for changes
|
||||
npm run watch
|
||||
```
|
||||
|
||||
### Subgraph (subgraph/base_sepolia/)
|
||||
|
||||
```bash
|
||||
# Generate code
|
||||
npm run codegen
|
||||
|
||||
# Build subgraph
|
||||
npm run build
|
||||
|
||||
# Deploy to The Graph
|
||||
npm run deploy
|
||||
|
||||
# Run tests
|
||||
npm run test
|
||||
```
|
||||
|
||||
### Transaction Bot (services/txnBot/)
|
||||
|
||||
```bash
|
||||
# Start service
|
||||
# Trigger Service
|
||||
node service.js
|
||||
```
|
||||
|
||||
## Key Contracts and Interfaces
|
||||
### Analysis Tools
|
||||
Critical for hardening the liquidity manager - see `onchain/analysis/README.md` for detailed usage and growth mechanism demonstrations.
|
||||
|
||||
### Kraiken.sol
|
||||
- Main protocol contract implementing Harberger tax
|
||||
- Integrates with Uniswap V3 for token swaps
|
||||
- Manages tax collection and distribution
|
||||
## Key Files
|
||||
|
||||
### LiquidityManager.sol
|
||||
- Handles Uniswap V3 position management
|
||||
- Implements recentering logic for dynamic liquidity
|
||||
- Uses UniswapHelpers for price calculations
|
||||
- **VWAP Integration**: Inherits from VWAPTracker for dormant whale protection
|
||||
- **Anti-Arbitrage Strategy**: Implements asymmetric slippage profile to protect against trade-recenter-reverse attacks
|
||||
- `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
|
||||
|
||||
#### Trade-Recenter-Reverse Attack Protection
|
||||
**The Exploit Pattern:**
|
||||
1. Trader executes large trade moving price significantly
|
||||
2. Price movement triggers recenter() function
|
||||
3. Trader immediately executes reverse trade at new liquidity configuration
|
||||
4. Net result: Trader profits from predictable rebalancing, LM loses value
|
||||
## 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
|
||||
|
||||
**Protection Mechanism - Asymmetric Slippage Profile:**
|
||||
- **ANCHOR Position**: Shallow liquidity around current price (high slippage, fast price movement)
|
||||
- **FLOOR + DISCOVERY Positions**: Deep liquidity at edges (low slippage, slow price movement)
|
||||
|
||||
**Attack Protection Logic:**
|
||||
1. First trade: Price moves quickly through shallow anchor → hits deep edge liquidity (high slippage cost)
|
||||
2. Recenter: Rebalances positions around new price
|
||||
3. Reverse trade: Price again moves quickly through new shallow anchor → hits opposite deep edge (high slippage cost)
|
||||
4. Result: Attacker pays high slippage twice, making round-trip unprofitable
|
||||
|
||||
#### Position Dependencies (_set function order)
|
||||
**Order:** ANCHOR → DISCOVERY → FLOOR
|
||||
|
||||
**Economic Rationale:**
|
||||
- **ANCHOR → DISCOVERY**: Discovery amount proportional to KRAIKEN minted by anchor; positions border anchor for continuous fee capture
|
||||
- **ANCHOR + DISCOVERY → FLOOR**: Floor must defend against maximum selling pressure from final circulating supply, only known after all position minting complete
|
||||
- **VWAP Exclusivity**: Only FLOOR position uses VWAP for historical price memory; ANCHOR/DISCOVERY use current tick for immediate market response
|
||||
|
||||
### VWAPTracker.sol
|
||||
- **Critical Security Component**: Provides "eternal memory" protection against dormant whale attacks
|
||||
- **Dormant Whale Attack Pattern**:
|
||||
1. Whale buys large amounts early at cheap prices
|
||||
2. Waits for extended periods while protocol accumulates volume
|
||||
3. Attempts to sell at inflated prices when market conditions are favorable
|
||||
- **Protection Mechanism**: VWAP maintains historical price memory that persists through data compression
|
||||
- **Compression Algorithm**: Limited to maximum 1000x compression to preserve historical significance
|
||||
- **Double-Overflow Analysis**: Extensive testing shows that double-overflow scenarios requiring >1000x compression would need:
|
||||
- Single transactions >10,000 ETH (unrealistic)
|
||||
- Token prices >$4.3 billion (exceeds global wealth)
|
||||
- Therefore, 1000x compression limit provides adequate protection against realistic scenarios
|
||||
- **Floor Position Calculation**: Uses adjusted VWAP (70% base + capital inefficiency) to set floor support levels
|
||||
|
||||
### Stake.sol
|
||||
- Staking mechanism for KRAIKEN tokens
|
||||
- Collects sentiment data through staking behavior
|
||||
- Provides tax rate and staking percentage data
|
||||
|
||||
## Deployment Addresses
|
||||
|
||||
### Base Sepolia
|
||||
- Kraiken: `0x22c264Ecf8D4E49D1E3CabD8DD39b7C4Ab51C1B8`
|
||||
- Stake: `0xe28020BCdEeAf2779dd47c670A8eFC2973316EE2`
|
||||
- LP: `0x3d6a8797693a0bC598210782B6a889E11A2340Cd`
|
||||
|
||||
### Base Mainnet
|
||||
- Kraiken: `0x45caa5929f6ee038039984205bdecf968b954820`
|
||||
- Stake: `0xed70707fab05d973ad41eae8d17e2bcd36192cfc`
|
||||
- LP: `0x7fd4e645ce258dd3942eddbeb2f99137da8ba13b`
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- **Unit Tests**: Individual contract functionality
|
||||
- **Integration Tests**: Cross-contract interactions
|
||||
- **Gas Optimization**: Use `forge snapshot` for gas tracking
|
||||
- **GraphQL Tests**: Test subgraph queries and data accuracy
|
||||
|
||||
## Key Libraries and Dependencies
|
||||
|
||||
- **OpenZeppelin**: Upgradeable contracts, ERC20, access control
|
||||
- **Uniswap V3**: Core liquidity provision and swapping
|
||||
- **ABDK Math**: Fixed-point arithmetic operations
|
||||
- **Apollo Client**: GraphQL client for subgraph data
|
||||
- **Ethers.js**: Ethereum interaction library
|
||||
*Note: Detailed technical analysis including attack vectors, VWAP algorithms, and Harberger tax implementation available in [TECHNICAL_APPENDIX.md](TECHNICAL_APPENDIX.md).*
|
||||
Loading…
Add table
Add a link
Reference in a new issue