Skip to content

onflow/tidal-protocol-research

BranchesTags
 
 

Repository files navigation

tidal-protocol-research — Consumer DeFi Lending Research for Flow

A comprehensive DeFi lending protocol simulation and analysis framework that models sophisticated lending strategies, liquidation mechanisms, and yield-bearing token systems with authentic Uniswap V3 mathematics and realistic agent behaviors.

Overview

This repository contains a sophisticated multi-layer simulation system that models the complete Tidal Protocol lending ecosystem, featuring:

Core Protocol Components

  • Tidal Protocol Engine: Kinked interest rate models with Ebisu-style debt cap calculations
  • High Tide Vault Strategy: Active rebalancing using yield tokens to prevent liquidations
  • AAVE Protocol Engine: Traditional liquidation mechanisms for performance comparison
  • MOET Stablecoin: Fee-less stablecoin with ±2% stability bands and peg maintenance
  • Yield Token System: 10% APR rebasing tokens with continuous compound interest

Advanced Mathematical Systems

  • Authentic Uniswap V3 Implementation: Tick-based concentrated liquidity with Q64.96 fixed-point arithmetic
  • Cross-Tick Swap Mechanics: Sophisticated multi-range trading with realistic slippage
  • Asymmetric Pool Configuration: Configurable token ratios (10:90 to 90:10) with intelligent tick alignment
  • Monte Carlo Simulation Framework: Statistical robustness with 10-50 agents per simulation

Multi-Agent Ecosystem

  • High Tide Agents: Active rebalancing with 3 risk profiles (Conservative, Moderate, Aggressive)
  • AAVE Agents: Traditional liquidation behavior (passive until liquidation)
  • Pool Rebalancers: ALM and algorithmic arbitrage agents for pool price accuracy
  • Liquidators & Traders: Realistic market-making and liquidation execution

Quick Start

Prerequisites

  • Python 3.8+
  • Git

Installation

# Clone the repository
git clone https://github.com/unit-zero-labs/tidal-protocol-research.git
cd tidal-protocol-research

# Create and activate virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

# Install dependencies
pip install -r analysis_requirements.txt

Dependencies

Core Python packages required:

  • matplotlib>=3.5.0 - Advanced visualization and charting
  • seaborn>=0.11.0 - Statistical plotting and analysis
  • pandas>=1.3.0 - Data manipulation and time series analysis
  • numpy>=1.21.0 - Numerical computing and mathematical operations

🚀 Usage Examples & Simulation Scenarios

1. High Tide vs AAVE Comparison (Recommended Start)

Compare High Tide active rebalancing against traditional AAVE liquidations:

python comprehensive_ht_vs_aave_analysis.py

What this simulation does:

  • Duration: 60-minute BTC decline scenario
  • Market Stress: 15-25% BTC price drop (from $100k to $75k-$85k)
  • High Tide Strategy: Agents actively rebalance using yield tokens when health factors decline
  • AAVE Strategy: Agents hold positions until liquidation (no rebalancing)
  • Analysis: Side-by-side performance comparison with survival rates, costs, and efficiency metrics

2. Comprehensive Realistic Pool Analysis

Run detailed multi-configuration analysis:

python comprehensive_realistic_pool_analysis.py

Advanced Features:

  • Pool Configurations: Multiple sizes ($250k, $500k, $2M) with varied concentrations
  • Risk Profiles: Conservative (HF 2.1-2.4), Moderate (HF 1.5-1.8), Aggressive (HF 1.3-1.5)
  • LP Curve Evolution: Real-time liquidity distribution tracking
  • Utilization Analysis: Protocol sustainability under different stress conditions
  • Asymmetric Pool Testing: 75/25 MOET:YT ratios with intelligent tick alignment

3. Monte Carlo Scenario Analysis

Statistical robustness testing with varied agent populations:

python balanced_scenario_monte_carlo.py

Monte Carlo Features:

  • Dynamic Agent Count: 10-50 agents per simulation run
  • Risk Profile Randomization: Varied initial and target health factors
  • Statistical Analysis: Multiple runs for confidence intervals
  • Pool Arbitrage: Optional ALM and algorithmic rebalancing agents

4. Target Health Factor Optimization

Analyze optimal health factor thresholds:

python target_health_factor_analysis.py

5. Long-Term Protocol Analysis

Extended 12-month simulation with realistic market dynamics:

python longterm_scenario_analysis.py

Long-Term Features:

  • Duration: Up to 12 months with hourly price updates
  • Market Dynamics: Geometric Brownian Motion for BTC price evolution
  • Pool Arbitrage: ALM (12-hour intervals) and Algo (50 bps threshold) rebalancers
  • Yield Accrual: Full 10% APR compound interest over extended periods
  • Flash Crash Events: Optional extreme market stress testing

6. Yield Token Pool Capacity Testing

Examine pool liquidity limits and rebalancing capacity:

python yield_token_pool_capacity_analysis.py

Capacity Analysis:

  • Single Swap Limits: Up to $350k trades within concentrated ranges
  • Consecutive Rebalancing: Multi-agent competition for shared liquidity
  • Slippage Progression: 0.01% (small trades) to 2%+ (range-crossing trades)
  • Pool Sustainability: Liquidity exhaustion and recovery scenarios

7. Comprehensive Stress Testing Suite

Run full stress test library with multiple scenarios:

python tidal_protocol_sim/main.py --full-suite --monte-carlo 100

Stress Test Categories:

  • Single Asset Shocks: ETH (-30%), BTC (-35%), FLOW (-50%)
  • Multi-Asset Crashes: Crypto winter scenarios with correlated declines
  • Liquidity Crises: MOET depeg events and pool liquidity drain
  • Parameter Sensitivity: Collateral factors, liquidation thresholds, fee tiers
  • Extreme Events: Black swan events, cascading liquidations

8. Individual Scenario Analysis

Test specific market conditions:

python tidal_protocol_sim/main.py --scenario ETH_Flash_Crash --detailed-analysis

🏗️ System Architecture

The simulation system follows a sophisticated 5-layer modular architecture designed for maximum flexibility and mathematical rigor:

┌─────────────────────────────────────────────────────────────┐
│                    Entry Points & CLI                       │
│  main.py, comprehensive_*.py, longterm_*.py, run_*.py      │
│  Monte Carlo Scripts, Stress Testing Suites               │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                  Simulation Engines                        │
│  HighTideVaultEngine, AaveProtocolEngine, TidalEngine     │
│  BaseLendingEngine, BTCPriceManager                        │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                 Agent System & Policies                    │
│  HighTideAgent, AaveAgent, PoolRebalancer (ALM/Algo)      │
│  TidalLender, Liquidator, Trader, BaseAgent               │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│              Core Protocol Mathematics                      │
│  TidalProtocol, UniswapV3Math, YieldTokens,               │
│  MoetStablecoin, AssetPools, LiquidityPools                │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│          Analysis & Stress Testing Framework               │
│  Metrics Calculator, Visualization Suite, Stress Scenarios │
│  Results Management, Agent Tracking, LP Curve Analysis     │
└─────────────────────────────────────────────────────────────┘

Orchestration vs Execution Layers

The system uses clear separation between orchestration and execution:

🎯 Orchestration Layer (Engines):

  • Coordinates agent actions and decisions
  • Tracks rebalancing events, slippage costs, and performance metrics
  • Records all trading activity for comprehensive analysis
  • Manages simulation flow and agent lifecycle

⚙️ Execution Layer (Agents + Pools):

  • Agents calculate portfolio needs and execute real swaps
  • Pools execute authentic Uniswap V3 swaps with permanent state mutations
  • Shared liquidity creates realistic competition between agents
  • Real economic impact where each swap affects subsequent trades

🔬 Core Protocol Mathematics

1. Tidal Protocol Engine (tidal_protocol_sim/core/protocol.py)

Purpose: Core lending protocol with kinked interest rate model and Ebisu-style debt cap calculations

Key Components:

  • Asset Support: ETH, BTC, FLOW, USDC, MOET with individual pool management
  • Kinked Interest Rate Model: Base rate + multiplier below 80% kink, jump rate above
  • Collateral Factors: ETH/BTC (75%), FLOW (50%), USDC (90%)
  • Liquidation Mechanics: 8% penalty, 50% close factor, 1.2 target health factor

Mathematical Models:

# Kinked Interest Rate Model
if utilization <= kink (0.80):
    rate = base_rate + (utilization × multiplier_per_block)
else:
    rate = base_rate + (kink × multiplier) + ((utilization - kink) × jump_rate)

# Ebisu-Style Debt Cap Formula
debt_cap = total_liquidation_capacity × dex_allocation × weighted_underwater_percentage

2. MOET Stablecoin System (tidal_protocol_sim/core/moet.py)

Purpose: Fee-less stablecoin with ±2% stability bands and peg maintenance

Key Features:

  • 1:1 Minting/Burning: No fees for optimal capital efficiency
  • Stability Bands: $0.98 - $1.02 target range with pressure detection
  • Peg Maintenance: Automatic stability pressure analysis and recommendations

3. Yield Token System (tidal_protocol_sim/core/yield_tokens.py)

Purpose: 10% APR rebasing tokens with continuous compound interest for High Tide strategy

Advanced Features:

  • Rebasing Mechanism: Continuous value increase without quantity change
  • Flexible Creation: Direct minting (minute 0) vs Uniswap V3 trading
  • Portfolio Management: Yield-first sales with principal preservation
  • Real Swap Execution: Engine-level coordination with pool state mutations

Mathematical Model:

# Continuous yield accrual (per-minute precision)
minute_rate = APR * (minutes_elapsed / 525600)  # 525600 minutes/year
current_value = principal × (1 + minute_rate)

4. Authentic Uniswap V3 Implementation (tidal_protocol_sim/core/uniswap_v3_math.py)

Purpose: Production-grade tick-based concentrated liquidity with Q64.96 fixed-point arithmetic

Advanced Capabilities:

  • Tick System: MIN_TICK (-887272) to MAX_TICK (887272) with proper spacing
  • Concentrated Liquidity:
    • MOET:BTC pools: 80% concentration around BTC price
    • MOET:Yield Token pools: 95% concentration around 1:1 peg
    • Asymmetric ratios: 10:90 to 90:10 with intelligent tick alignment
  • Cross-Tick Swaps: Multi-step swaps with proper slippage calculation
  • Discrete Liquidity Ranges: Three-tier system (concentrated core + wide ranges)

Core Mathematical Functions:

# Tick to price conversion (Q64.96 format)
sqrt_price_x96 = int(1.0001^(tick/2) × 2^96)

# Liquidity delta calculations
amount0_delta = (liquidity × Q96 × (sqrt_price_b - sqrt_price_a)) / (sqrt_price_b × sqrt_price_a)
amount1_delta = (liquidity × (sqrt_price_b - sqrt_price_a)) / Q96

# Within-range price impact (whitepaper formula)
delta_sqrt_price = amount_in × Q96 / liquidity

🤖 Multi-Agent Ecosystem

High Tide Agents (tidal_protocol_sim/agents/high_tide_agent.py)

Strategy: Active rebalancing using yield tokens to prevent liquidations

Risk Profiles & Distribution:

  • Conservative (30%): Initial HF 2.1-2.4, Target buffer 0.05-0.15
  • Moderate (40%): Initial HF 1.5-1.8, Target buffer 0.15-0.25
  • Aggressive (30%): Initial HF 1.3-1.5, Target buffer 0.15-0.4

Advanced Rebalancing Logic:

  1. Initial Setup: Deposit 1 BTC, borrow MOET based on initial HF, buy yield tokens
  2. Health Monitoring: Continuous health factor tracking vs target thresholds
  3. Iterative Rebalancing: Multi-cycle approach with slippage monitoring
  4. Yield-First Sales: Sell accrued yield before touching principal
  5. Emergency Actions: Full liquidation of remaining yield tokens if HF ≤ 1.0

AAVE Agents (tidal_protocol_sim/agents/aave_agent.py)

Strategy: Traditional passive approach - hold positions until liquidation

Key Differences from High Tide:

  • Same initial setup (1 BTC collateral, yield token purchase)
  • NO rebalancing - positions held until liquidation
  • Traditional AAVE liquidation: 50% collateral seizure + 5% bonus
  • Passive yield accrual without portfolio management

Pool Rebalancer Agents (tidal_protocol_sim/agents/pool_rebalancer.py)

Purpose: Maintain MOET:YT pool price accuracy through arbitrage

ALM Rebalancer:

  • Trigger: Time-based (default: 12 hours)
  • Purpose: Asset Liability Management - systematic pool maintenance

Algo Rebalancer:

  • Trigger: Threshold-based (≥50 basis points deviation)
  • Purpose: Algorithmic arbitrage - profit from price inefficiencies

Arbitrage Mechanism:

  • Shared $500k liquidity pool (all MOET initially)
  • External YT sales at true price to replenish reserves
  • Profit = (Pool Price - True Price) × Amount Traded

⚙️ Simulation Engines

1. High Tide Vault Engine (tidal_protocol_sim/engine/high_tide_vault_engine.py)

Purpose: BTC decline scenario with sophisticated active rebalancing strategies

Key Features:

  • Market Stress Simulation: 60-minute BTC decline (15-25% drop) with realistic volatility
  • Agent Orchestration: Coordinates 10-50 High Tide agents with Monte Carlo variation
  • Real Swap Execution: Engine-level coordination of yield token sales with pool state mutations
  • Iterative Rebalancing: Multi-cycle approach with slippage monitoring and cost tracking

Data Flow:

Agent Needs MOET → Engine._execute_yield_token_sale() → Agent.execute_yield_token_sale() 
→ YieldTokenPool.execute_yield_token_sale() → Uniswap V3 Pool Swap (Real) → Pool State Updated

2. AAVE Protocol Engine (tidal_protocol_sim/engine/aave_protocol_engine.py)

Purpose: Traditional AAVE-style liquidation for direct comparison with High Tide

Key Differences:

  • No Rebalancing: Agents hold positions until liquidation (passive strategy)
  • AAVE Liquidation: 50% collateral + 5% bonus when HF ≤ 1.0
  • Same Market Conditions: Identical BTC decline for fair comparison
  • Uniswap V3 Integration: Real liquidation swaps through MOET:BTC pool

3. Base Lending Engine (tidal_protocol_sim/engine/base_lending_engine.py)

Purpose: Common simulation framework providing shared functionality

Core Features:

  • Agent action processing loop with minute-by-minute updates
  • Health factor monitoring and liquidation detection
  • Comprehensive metrics recording throughout simulation lifecycle
  • Common swap execution and slippage calculation infrastructure

4. BTC Price Manager (tidal_protocol_sim/engine/btc_price_manager.py)

Purpose: Realistic market stress simulation with authentic volatility patterns

Price Dynamics:

  • Historical Volatility: Based on real BTC decline patterns
  • Convergence Logic: Gradual convergence to target price in final 20% of simulation
  • Configurable Parameters: Initial price, duration, final price range
  • Long-Term Support: Geometric Brownian Motion for extended simulations

🔧 Configuration & Customization

Core Configuration Files

Simulation Parameters (tidal_protocol_sim/engine/config.py):

  • Agent populations and risk profile distributions
  • Pool sizes and concentration levels
  • BTC price decline parameters and volatility settings
  • Monte Carlo variation controls

Pool Configurations:

# MOET:BTC Pool (for liquidations)
moet_btc_pool_config = {
    "size": 500_000,         # $500k total liquidity
    "concentration": 0.80,   # 80% at current BTC price
    "fee_tier": 0.003        # 0.3% fee tier
}

# MOET:Yield Token Pool (for rebalancing)
moet_yt_pool_config = {
    "size": 500_000,         # $250k each side  
    "concentration": 0.95,   # 95% at 1:1 peg
    "token0_ratio": 0.75,    # 75% MOET, 25% YT
    "fee_tier": 0.0005       # 0.05% fee tier
}

Agent Configuration:

  • High Tide Agents: 10-50 agents with Monte Carlo risk profile variation
  • AAVE Agents: Identical setup to High Tide but no rebalancing capability
  • Pool Rebalancers: ALM (12-hour intervals) and Algo (50 bps threshold) agents

Advanced Customization Options

Asymmetric Pool Ratios:

  • Configurable MOET:YT ratios from 10:90 to 90:10
  • Intelligent tick alignment for precise target ratios
  • Automatic bounds calculation with mathematical optimization

Market Stress Parameters:

  • BTC decline duration (default: 60 minutes)
  • Final price ranges (default: 15-25% decline)
  • Volatility patterns based on historical data
  • Long-term Geometric Brownian Motion for extended simulations

Pool Arbitrage Settings:

# Pool Rebalancer Configuration
enable_pool_arbing = True                    # Enable arbitrage agents
alm_rebalance_interval_minutes = 720         # 12 hours
algo_deviation_threshold_bps = 50.0          # 50 basis points
total_rebalancer_liquidity = 500_000         # $500k shared liquidity

📚 Technical Documentation

Comprehensive Documentation Library (readmes/)

Core Mathematics:

Simulation Engines:

Specialized Systems:

Workflow Examples

1. Research Workflow: High Tide Efficacy Analysis

# Step 1: Run baseline comparison
python comprehensive_ht_vs_aave_analysis.py

# Step 2: Analyze different pool configurations
python comprehensive_realistic_pool_analysis.py

# Step 3: Test statistical robustness
python balanced_scenario_monte_carlo.py

# Step 4: Examine long-term sustainability
python longterm_scenario_analysis.py

2. Parameter Sensitivity Analysis

# Test different health factor thresholds
python target_health_factor_analysis.py

# Analyze yield token pool capacity limits
python yield_token_pool_capacity_analysis.py

# Test pool rebalancing effectiveness
python rebalance_liquidity_test.py

3. Stress Testing Protocol Limits

# Run comprehensive stress test suite
python tidal_protocol_sim/main.py --full-suite --monte-carlo 50

# Test specific extreme scenarios
python tidal_protocol_sim/main.py --scenario BTC_Flash_Crash --detailed-analysis
python tidal_protocol_sim/main.py --scenario MOET_Depeg_Crisis --detailed-analysis

About Flow

This repo is part of the Flow network, a Layer 1 blockchain built for consumer applications, AI agents, and DeFi at scale.

About

Tidal Protocol research. Python simulations and research artifacts for consumer DeFi lending protocols on the Flow network

flow.com

Topics

python flow research simulation blockchain web3 lending cadence defi tokenomics consumer-defi protocol-research

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Python 100.0%