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:

liquidityPool.provideLiquidity{value: amount}(LiquidityPoolETH.AssetType.ETH);

For WETH:

// 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:

liquidityPool.withdrawLiquidity(amount, assetType);

Restrictions:

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

Check Availability:

(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

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