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 README.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 (Unified Formula):

floorTick = max(scarcityTick, mirrorTick, clampTick) toward KRK-cheap side

Three signals determine the floor:

• scarcityTick: derived from vwapX96 and ETH/supply ratio. Dominates when ETH is scarce.
• mirrorTick: currentTick + |adjustedVwapTick - currentTick| on KRK-cheap side. Reflects VWAP distance symmetrically. During sell pressure the mirror distance grows, resisting floor walkdown.
• clampTick: minimum distance from anchor edge. anchorSpacing = 200 + (34 × 20 × AW / 100) ticks.

VWAP Mirror Defense:

• During sell-heavy trading, the current tick drops but VWAP stays higher, so mirror distance grows — floor naturally resists being walked down.
• CI controls mirror distance through getAdjustedVWAP(CI) with no magic numbers. CI=0% is safest (proven zero effect on fee revenue).

Directional VWAP Recording:

• VWAP only records on ETH inflow (buys into the LM), preventing attackers from diluting VWAP with sells.
• shouldRecordVWAP compares lastRecenterTick to current tick to detect direction.

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

OptimizerV3 Integration

Direct 2D Binary Mapping (no intermediate score):

OptimizerV3 reads percentageStaked and averageTaxRate from the Stake contract and maps them directly to one of two configurations:

• staked ≤ 91% → always BEAR: AS=30%, AW=100, CI=0, DD=0.3e18
• staked > 91% → BULL if deltaS³ × effIdx / 20 < 50: AS=100%, AW=20, CI=0, DD=1e18

The binary step avoids the AW 40-80 kill zone where intermediate parameters are exploitable. Bull requires >91% staked with low enough tax; any decline snaps to bear instantly.

Parameter Safety (proven via 1050-combo 4D sweep):

• CI=0% always (zero effect on fee revenue, maximum protection)
• Fee revenue is parameter-independent (~1.5 ETH/cycle across all combos)
• Safety comes entirely from the AS×AW configuration

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 binary bear/bull parameter selection

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
• OptimizerV3.sol: Sentiment-driven binary bear/bull parameter selection (UUPS upgradeable)
• 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

• README.md: Project overview
• AGENTS.md: Development and operational guidance
• /onchain/analysis/README.md: Detailed analysis tool usage