smom-dbis-138/docs/operations/LIQUIDITY_PROVIDER_GUIDE.md

# Liquidity Provider Guide

## Overview

This guide explains how to become a liquidity provider (LP) for the trustless bridge system. LPs provide liquidity to enable near-instant bridge releases while claims are being finalized.

## Becoming a Liquidity Provider

### Requirements

1. **Capital**: ETH or WETH to provide as liquidity
2. **Risk Tolerance**: Understand liquidity risks
3. **Technical Knowledge**: Understanding of bridge mechanics and liquidity pools

### Setup Steps

1. **Understand Risks**:
   - Review liquidity pool mechanics
   - Understand minimum liquidity ratio
   - Assess withdrawal restrictions
   - Review fee structure

2. **Prepare Capital**:
   - Decide on amount to provide
   - Choose asset type (ETH or WETH)
   - Ensure sufficient balance

3. **Test on Testnet**:
   - Test providing liquidity
   - Test withdrawals
   - Verify fee collection
   - Practice procedures

## LP Operations

### Providing Liquidity

**Function**: `LiquidityPoolETH.provideLiquidity()` or `depositWETH()`

**For ETH**:
```solidity
liquidityPool.provideLiquidity{value: amount}(LiquidityPoolETH.AssetType.ETH);
```

**For WETH**:
```solidity
// First approve WETH
weth.approve(address(liquidityPool), amount);
// Then deposit
liquidityPool.depositWETH(amount);
```

**Process**:
1. Approve tokens (for WETH)
2. Call provide function with amount
3. Receive LP shares (1:1 with deposit)
4. Start earning fees

### Withdrawing Liquidity

**Function**: `LiquidityPoolETH.withdrawLiquidity()`

**Process**:
```solidity
liquidityPool.withdrawLiquidity(amount, assetType);
```

**Restrictions**:
- Withdrawals blocked if below minimum liquidity ratio (110%)
- Must maintain: `availableLiquidity >= pendingClaims * 1.1`
- Check before withdrawing

**Check Availability**:
```solidity
(bool canWithdraw, string memory reason) = canWithdraw(amount, assetType);
```

### Fee Collection

**Fee Structure**:
- LP fee: 5 bps (0.05%) on bridge amount
- Fees remain in pool (increase effective liquidity)
- Distributed proportionally to LP shares

**Fee Calculation**:
- Fee = bridgeAmount * 0.0005
- Fees increase pool value
- LPs benefit from fee accumulation

## Economics

### Revenue

- **LP Fees**: 0.05% of bridge amounts
- **Fee Distribution**: Proportional to LP share
- **Example**: If pool processes 100 ETH, fees = 0.05 ETH

### Costs

- **Opportunity Cost**: Capital locked in pool
- **Gas Fees**: For deposits and withdrawals
- **Risk**: Liquidity risk, withdrawal restrictions

### Profitability

- Calculate: Fees Earned - Opportunity Cost - Gas Costs - Risk
- Consider pool utilization, fee rates, capital efficiency
- Monitor pool performance

## Risk Management

### Liquidity Risks

1. **Withdrawal Restrictions**:
   - Cannot withdraw if below minimum ratio
   - May need to wait for claims to finalize
   - Plan withdrawals accordingly

2. **Capital Lockup**:
   - Capital locked in pool
   - Limited withdrawal flexibility
   - Consider liquidity needs

3. **Pool Utilization**:
   - Low utilization = lower fees
   - High utilization = higher fees but more risk
   - Monitor utilization rates

### Best Practices

1. **Diversification**: Don't put all capital in one pool
2. **Monitoring**: Monitor pool status regularly
3. **Withdrawal Planning**: Plan withdrawals in advance
4. **Risk Assessment**: Assess risks before providing liquidity

## Monitoring

### Key Metrics

- **Total Liquidity**: Amount in pool
- **Pending Claims**: Amount locked in pending claims
- **Available Liquidity**: Total - Pending
- **Liquidity Ratio**: Available / Pending
- **Fees Earned**: Total fees collected
- **LP Share**: Your share of pool

### Monitoring Functions

```solidity
// Get pool statistics
(uint256 total, uint256 pending, uint256 available) = 
    liquidityPool.getPoolStats(assetType);

// Get your LP share
uint256 share = liquidityPool.getLpShare(yourAddress, assetType);

// Get available liquidity
uint256 available = liquidityPool.getAvailableLiquidity(assetType);
```

### Alerts

- **Low Liquidity Ratio**: Alert when ratio approaches minimum
- **High Utilization**: Alert on high pool utilization
- **Withdrawal Blocked**: Alert when withdrawals are blocked
- **Fee Accumulation**: Track fee earnings

## Best Practices

### 1. Capital Management

- **Adequate Capital**: Provide sufficient capital for efficiency
- **Reserve Funds**: Keep reserves outside pool
- **Diversification**: Diversify across asset types
- **Rebalancing**: Rebalance as needed

### 2. Risk Management

- **Monitor Ratios**: Monitor liquidity ratios regularly
- **Plan Withdrawals**: Plan withdrawals in advance
- **Understand Restrictions**: Understand withdrawal restrictions
- **Assess Risks**: Continuously assess risks

### 3. Optimization

- **Fee Maximization**: Optimize for fee earnings
- **Capital Efficiency**: Maximize capital efficiency
- **Gas Optimization**: Optimize gas usage
- **Timing**: Time deposits and withdrawals optimally

## Troubleshooting

### Withdrawal Blocked

- **Check Ratio**: Verify liquidity ratio
- **Wait**: Wait for claims to finalize
- **Reduce Amount**: Try smaller withdrawal
- **Monitor**: Monitor pool status

### Low Fees

- **Check Utilization**: Verify pool utilization
- **Consider Alternatives**: Consider other opportunities
- **Optimize**: Optimize capital allocation

### Pool Issues

- **Contact Support**: Contact operations team
- **Review Documentation**: Review pool documentation
- **Check Status**: Check pool status and health

## References

- Liquidity Pool Contract: `contracts/bridge/trustless/LiquidityPoolETH.sol`
- Architecture: `docs/bridge/trustless/ARCHITECTURE.md`
- Security: `docs/bridge/trustless/SECURITY.md`