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

```solidity
// 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

```typescript
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