johba/harb

2025-09-24 09:57:20 +02:00

6.3 KiB

Raw Blame History

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

Setup: Trader identifies predictable rebalancing trigger
Exploit: Large trade → triggers recenter() → reverse trade at new configuration
Expected Profit: Trader profits from predictable liquidity movements
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:

First Trade: Price moves quickly through shallow ANCHOR → hits deep DISCOVERY/FLOOR liquidity (high slippage cost)
Recenter: Rebalances all positions around new price
Reverse Trade: Price moves through new shallow ANCHOR → hits opposite deep liquidity (high slippage cost again)
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:

Accumulation: Whale buys large amounts early at cheap prices
Dormancy: Waits extended periods while protocol accumulates volume and prices rise
Exploitation: Attempts to sell at inflated prices when market conditions are favorable
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:

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:

ANCHOR → DISCOVERY: Discovery liquidity amount depends on KRAIKEN minted by ANCHOR position
ANCHOR + DISCOVERY → FLOOR: FLOOR must defend against maximum selling pressure from final circulating supply
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

AGENTS.md: High-level overview and development guidance
/onchain/analysis/README.md: Detailed analysis tool usage

6.3 KiB Raw Blame History