harb/TECHNICAL_APPENDIX.md

# Technical Appendix

This document provides detailed technical analysis and implementation details for the KRAIKEN protocol's core innovations. For a high-level overview, see AGENTS.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
- **AGENTS.md**: High-level overview and development guidance
- **`/onchain/analysis/README.md`**: Detailed analysis tool usage