smom-dbis-138/docs/bridge/trustless/integration/LIQUIDITY_ENGINE.md

Automated Liquidity Engine

This document explains the automated liquidity engine with decision logic maps for intelligent routing.

Overview

The liquidity engine provides:

• Multi-protocol routing: Uniswap V3, Dodoex PMM, Balancer, Curve, 1inch
• Intelligent decision logic: Size-based, slippage-based, liquidity-based routing
• Quote aggregation: Compare prices across all protocols
• Automated optimization: Best execution automatically selected

Decision Logic Map

Size-Based Routing

• Small swaps (< $10k): Uniswap V3 → Dodoex

  • Fast execution, low gas
  • Uniswap V3 has best liquidity for small trades

• Medium swaps ($10k-$100k): Dodoex → Balancer → Uniswap V3

  • Dodoex PMM provides better price discovery
  • Balancer weighted pools for stablecoins

• Large swaps (> $100k): Dodoex → Curve → Balancer

  • Dodoex PMM minimizes slippage
  • Curve has deepest liquidity for large trades

Slippage-Based Routing

• Low slippage (< 0.1%): Prefer Dodoex

  • PMM model provides better price protection

• Medium slippage (< 0.5%): Prefer Balancer

  • Weighted pools offer good execution

• High slippage: Prefer Curve

  • Deepest liquidity pools

Liquidity-Based Routing

• High liquidity (> $1M): Prefer Uniswap V3

  • Best execution in liquid markets

• Medium liquidity: Prefer Dodoex

  • PMM adapts to market conditions

• Low liquidity: Prefer Curve

  • Concentrated liquidity for better execution

Admin Dashboard Features

Liquidity Engine Page

1. Provider Quotes: Real-time comparison of all providers
2. Decision Logic Editor: Configure routing rules
3. Simulation Tool: Test routing decisions before execution
4. Routing Statistics: Track performance by provider
5. Configuration Management: Update decision maps

Configuration Options

• Size thresholds (small/medium/large)
• Slippage rules and preferences
• Liquidity thresholds
• Provider enable/disable toggles
• Pool ID configuration (Balancer)

Benefits

1. Optimal Execution: Always uses best available price
2. Lower Slippage: Dodoex PMM for large trades
3. Resilience: Multiple fallback options
4. Transparency: All decisions visible and configurable
5. Automation: No manual intervention needed

Usage

Smart Contract

// Auto-select best route
(uint256 amountOut, SwapProvider provider) = enhancedSwapRouter.swapToStablecoin(
    LiquidityPoolETH.AssetType.WETH,
    usdtAddress,
    amountIn,
    amountOutMin,
    SwapProvider.UniswapV3 // 0 = auto-select
);

// Get quotes from all providers
(SwapProvider[] memory providers, uint256[] memory amounts) = 
    enhancedSwapRouter.getQuotes(usdtAddress, amountIn);

Backend Service

import LiquidityEngine from './services/liquidity-engine/liquidity-engine.service';

const engine = new LiquidityEngine(provider, routerAddress);

// Find best route
const decision = await engine.findBestRoute(
    'WETH',
    'USDT',
    BigInt('1000000000000000000'), // 1 ETH
    0.5 // max slippage 0.5%
);

console.log(`Best provider: ${decision.provider}`);
console.log(`Expected output: ${decision.expectedOutput}`);
console.log(`Reasoning: ${decision.reasoning}`);

Protocol Integration Details

Dodoex PMM

• Advantages: Lower slippage, better price discovery
• Best for: Large swaps, volatile markets
• Gas cost: ~180k gas

Balancer

• Advantages: Weighted pools, stablecoin optimization
• Best for: Medium swaps, stable/stable pairs
• Gas cost: ~220k gas

Uniswap V3

• Advantages: Highest liquidity, multiple fee tiers
• Best for: Small swaps, high liquidity markets
• Gas cost: ~150k gas

Curve

• Advantages: Deepest liquidity for stablecoins
• Best for: Large swaps, stable/stable pairs
• Gas cost: ~200k gas

Future Enhancements

1. Compound/Aave Integration: Yield generation on idle liquidity
2. MEV Protection: Time-based routing to avoid front-running
3. Predictive Routing: ML-based route selection
4. Cross-Protocol Arbitrage: Automatic arbitrage detection
5. Dynamic Fee Optimization: Adjust routing based on gas prices