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
143
TECHNICAL_APPENDIX.md
Normal file
143
TECHNICAL_APPENDIX.md
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
# Technical Appendix
|
||||
|
||||
This document provides detailed technical analysis and implementation details for the KRAIKEN protocol's core innovations. For high-level overview, see CLAUDE.md.
|
||||
|
||||
## Asymmetric Slippage Strategy
|
||||
|
||||
### The Core Innovation
|
||||
The three-position liquidity structure creates an "unfair advantage" against traditional arbitrageurs by forcing asymmetric costs on round-trip trades.
|
||||
|
||||
### Trade-Recenter-Reverse Attack Pattern
|
||||
1. **Setup**: Trader identifies predictable rebalancing trigger
|
||||
2. **Exploit**: Large trade → triggers recenter() → reverse trade at new configuration
|
||||
3. **Expected Profit**: Trader profits from predictable liquidity movements
|
||||
4. **Reality**: Asymmetric slippage makes this unprofitable
|
||||
|
||||
### Protection Mechanism
|
||||
**Position Architecture:**
|
||||
- **ANCHOR**: Shallow liquidity (~current price) = high slippage, fast price movement
|
||||
- **DISCOVERY**: Medium liquidity (borders anchor) = fee capture zone
|
||||
- **FLOOR**: Deep liquidity (VWAP-adjusted) = low slippage, price memory
|
||||
|
||||
**Attack Protection Logic:**
|
||||
1. **First Trade**: Price moves quickly through shallow ANCHOR → hits deep DISCOVERY/FLOOR liquidity (high slippage cost)
|
||||
2. **Recenter**: Rebalances all positions around new price
|
||||
3. **Reverse Trade**: Price moves through new shallow ANCHOR → hits opposite deep liquidity (high slippage cost again)
|
||||
4. **Result**: Attacker pays high slippage twice, making round-trip unprofitable
|
||||
|
||||
### Mathematical Foundation
|
||||
The slippage differential between ANCHOR (shallow) and FLOOR (deep) positions ensures that any round-trip trade pays disproportionate costs, protecting the protocol's liquidity from exploitation.
|
||||
|
||||
## Dormant Whale Protection
|
||||
|
||||
### The Problem
|
||||
**Dormant Whale Attack Pattern:**
|
||||
1. **Accumulation**: Whale buys large amounts early at cheap prices
|
||||
2. **Dormancy**: Waits extended periods while protocol accumulates volume and prices rise
|
||||
3. **Exploitation**: Attempts to sell at inflated prices when market conditions are favorable
|
||||
4. **Impact**: Can crash token price using historical price advantages
|
||||
|
||||
### VWAP-Based Solution
|
||||
**Core Mechanism:**
|
||||
- **Historical Price Memory**: VWAP tracker maintains volume-weighted average pricing across time
|
||||
- **FLOOR Position Integration**: Only FLOOR position uses VWAP for price memory (ANCHOR/DISCOVERY use current tick)
|
||||
- **Compression Algorithm**: Data compression (max 1000x) preserves historical significance while managing storage
|
||||
|
||||
### Double-Overflow Analysis
|
||||
**Stress Testing Results:**
|
||||
Double-overflow scenarios requiring >1000x compression would need:
|
||||
- Single transactions >10,000 ETH (unrealistic for any individual)
|
||||
- Token prices >$4.3 billion (exceeds global wealth)
|
||||
- **Conclusion**: 1000x compression limit provides adequate protection against realistic scenarios
|
||||
|
||||
### Implementation Details
|
||||
**FLOOR Position Calculation:**
|
||||
```
|
||||
FLOOR_PRICE = VWAP_PRICE * (0.7 + CAPITAL_INEFFICIENCY)
|
||||
```
|
||||
|
||||
**Protection Mechanism:**
|
||||
- VWAP provides "eternal memory" of historical trading activity
|
||||
- Compression algorithm ensures memory persists even under extreme volume
|
||||
- FLOOR position acts as price anchor preventing manipulation of historical price disparities
|
||||
|
||||
## Harberger Tax Sentiment Oracle
|
||||
|
||||
### Mechanism Design
|
||||
**Continuous Auction Model:**
|
||||
- Stakers self-assign tax rates on their positions
|
||||
- Higher tax rates signal higher confidence in token value
|
||||
- Positions can be "snatched" by paying higher tax rates
|
||||
- Creates prediction market for token value through tax rate signals
|
||||
|
||||
### Data Collection
|
||||
**Sentiment Metrics:**
|
||||
- **Percentage Staked**: What portion of total supply is staked
|
||||
- **Average Tax Rate**: Weighted average of all staking tax rates
|
||||
- **Tax Rate Distribution**: Spread of tax rates across stakers
|
||||
|
||||
### Optimizer Integration
|
||||
**Sentiment Analysis:**
|
||||
```solidity
|
||||
function getLiquidityParams() returns (
|
||||
uint256 capitalInefficiency,
|
||||
uint256 anchorShare,
|
||||
uint24 anchorWidth,
|
||||
uint256 discoveryDepth
|
||||
) {
|
||||
// Analyze staking data to determine optimal liquidity parameters
|
||||
// Higher confidence (tax rates) → more aggressive positioning
|
||||
// Lower confidence → more conservative positioning
|
||||
}
|
||||
```
|
||||
|
||||
### Economic Incentives
|
||||
- **Tax Revenue**: Funds protocol operations and incentivizes participation
|
||||
- **Staking Benefits**: Percentage ownership of total supply (rather than fixed token amounts)
|
||||
- **Prediction Market**: Tax rates create market-based sentiment signals
|
||||
- **Liquidity Optimization**: Sentiment data feeds into dynamic parameter adjustment
|
||||
|
||||
## Position Dependencies Technical Details
|
||||
|
||||
### Execution Order: ANCHOR → DISCOVERY → FLOOR
|
||||
|
||||
**Economic Dependencies:**
|
||||
1. **ANCHOR → DISCOVERY**: Discovery liquidity amount depends on KRAIKEN minted by ANCHOR position
|
||||
2. **ANCHOR + DISCOVERY → FLOOR**: FLOOR must defend against maximum selling pressure from final circulating supply
|
||||
3. **VWAP Exclusivity**: Only FLOOR uses VWAP for historical price memory; ANCHOR/DISCOVERY use current tick
|
||||
|
||||
**Design Rationale:**
|
||||
- **ANCHOR**: Immediate price discovery and fast market response
|
||||
- **DISCOVERY**: Fee capture from trades that move through ANCHOR
|
||||
- **FLOOR**: Historical price anchoring and whale protection
|
||||
|
||||
### Recentering Trigger
|
||||
**Open Access Design:**
|
||||
- Any address can call `recenter()` when conditions are met
|
||||
- Incentivizes community participation in protocol maintenance
|
||||
- Removes single point of failure from automated systems
|
||||
- Trigger conditions based on price movement thresholds
|
||||
|
||||
### Critical Success Metrics
|
||||
**Dominant Position Requirement:**
|
||||
- LiquidityManager must trade majority of token supply
|
||||
- If position becomes non-dominant, project fails
|
||||
- Analysis tools in `/onchain/analysis/` monitor this metric
|
||||
- Growth mechanism depends on maintaining liquidity dominance
|
||||
|
||||
## Implementation References
|
||||
|
||||
### Key Contracts
|
||||
- **LiquidityManager.sol**: Core three-position strategy implementation
|
||||
- **VWAPTracker.sol**: Historical price memory and compression algorithm
|
||||
- **Optimizer.sol**: Sentiment analysis and parameter optimization
|
||||
- **Stake.sol**: Harberger tax mechanism and sentiment data collection
|
||||
|
||||
### Analysis Tools
|
||||
- **`/onchain/analysis/`**: Growth mechanism demonstrations and scenario testing
|
||||
- **Fuzzing Tests**: Stress testing of position strategies and edge cases
|
||||
- **Scenario Visualization**: Tools for understanding liquidity dynamics
|
||||
|
||||
### Related Documentation
|
||||
- **CLAUDE.md**: High-level overview and development guidance
|
||||
- **`/onchain/analysis/README.md`**: Detailed analysis tool usage
|
||||
Loading…
Add table
Add a link
Reference in a new issue