Provide Liquidity

TL;DR: Liquidity providers earn trading fees by depositing liquidity at specific Fixed Yield ranges. Like Uniswap v3, you choose your range — tighter ranges mean more fees but more risk.

How LP Works in XCCY

The Role of LPs

LPs make markets by providing liquidity for traders to swap against:

┌─────────────────────────────────────────────────────────────┐
│                    LP IN XCCY                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Traders want to:          LPs provide:                    │
│   ─────────────────         ─────────────                   │
│   Lock Fixed Yield    ←───  Liquidity at FY ranges          │
│   Trade Variable Yield ←─┘                                  │
│                                                             │
│   In return, LPs earn:                                      │
│   • Trading fees (e.g., 0.01% per trade)                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Concentrated Liquidity

Like Uniswap v3, you choose a Fixed Yield range:

FY Rate Scale:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

0%                    5%        8%                      15%
│─────────────────────[████████]─────────────────────────│
                      ↑        ↑
                 tickLower   tickUpper
                 
Your liquidity is only active when FY is between 5% and 8%

Understanding LP Economics

Fee Income

Your Fee Share = (Your Liquidity / Total Liquidity in Range) × Trade Fees

Example:
- Pool fee: 0.01% (1 basis point)
- Trade volume: $1,000,000
- Total fees: $100
- Your liquidity share: 10%
- Your fees: $10

Impermanent Loss (IL)

When FY moves within your range, your position composition changes:

FY moves from 6% to 8%:
━━━━━━━━━━━━━━━━━━━━━━━

Before:
  fixedTokens: 50,000
  variableTokens: -50,000

After:
  fixedTokens: 30,000    (less FY exposure)
  variableTokens: -70,000  (more VY exposure)

Your position now has directional exposure!

Range Selection Trade-off

Range Width	Fees	Capital Efficiency	Risk
Narrow (6-7%)	High	Very high	IL risk if FY moves outside
Medium (5-8%)	Medium	Good	Balanced
Wide (3-12%)	Low	Low	Low IL risk

Opening an LP Position

Step 1: Choose Your Range

// Convert FY percentages to ticks
function fyToTick(fyPercent) {
    return Math.floor(Math.log(fyPercent / 100) / Math.log(1.0001));
}

// Example: 5% to 8% range
const tickLower = fyToTick(5);  // ≈ 4055
const tickUpper = fyToTick(8);  // ≈ 5545

// Round to tick spacing
const tickSpacing = 10;
const tickLowerRounded = Math.floor(tickLower / tickSpacing) * tickSpacing;
const tickUpperRounded = Math.ceil(tickUpper / tickSpacing) * tickSpacing;

console.log(`Tick Range: ${tickLowerRounded} to ${tickUpperRounded}`);

Step 2: Deposit Margin

// LPs need margin for potential position obligations
const marginAmount = ethers.parseUnits("10000", 6);  // 10,000 USDC

await usdc.approve(COLLATERAL_ENGINE, marginAmount);
await collateralEngine.updateAccountMargin(account, USDC, marginAmount);
console.log("Margin deposited for LP position");

Step 3: Mint Liquidity

const VAMM_MINT_ABI = [
    "function mint((address,address,uint256,uint256,uint256,int24) key, tuple(address,uint96,address) account, int24 tickLower, int24 tickUpper, uint128 amount) external returns (uint256)"
];

const vammManager = new ethers.Contract(VAMM_MANAGER, VAMM_MINT_ABI, signer);

// Liquidity amount (in liquidity units, not tokens)
const liquidityAmount = 1000000n;  // Example amount

const tx = await vammManager.mint(
    [
        poolKey.underlyingAsset,
        poolKey.compoundToken,
        poolKey.termStartTimestampWad,
        poolKey.termEndTimestampWad,
        poolKey.feeWad,
        poolKey.tickSpacing
    ],
    [account.owner, account.id, account.isolatedMarginToken],
    tickLowerRounded,
    tickUpperRounded,
    liquidityAmount
);

await tx.wait();
console.log("Liquidity minted!");

Managing Your LP Position

Check Earned Fees

Fees accumulate as traders swap within your range:

// Fees are added to your margin balance automatically
// Check your current balance
const balance = await collateralEngine.getAccountMargin(account, USDC);
console.log(`Current margin balance: ${ethers.formatUnits(balance, 6)} USDC`);

Monitor Your Range

async function checkIfInRange() {
    const [currentTick] = await vammManager.getVAMMState(poolId);
    
    if (currentTick < tickLowerRounded) {
        console.log("FY is BELOW your range - not earning fees");
        console.log("Your position is 100% variableTokens (VY exposure)");
    } else if (currentTick > tickUpperRounded) {
        console.log("FY is ABOVE your range - not earning fees");
        console.log("Your position is 100% fixedTokens (FY exposure)");
    } else {
        console.log("FY is IN your range - earning fees!");
        console.log(`Current tick: ${currentTick}`);
    }
}

Reposition if Needed

If FY moves outside your range, you can:

1. Wait — Maybe FY will return to your range

2. Burn and re-mint — Remove liquidity and add at new range

3. Add more liquidity — Widen your range by adding at different ticks

Removing Liquidity

Burn Liquidity

const VAMM_BURN_ABI = [
    "function burn((address,address,uint256,uint256,uint256,int24) key, tuple(address,uint96,address) account, int24 tickLower, int24 tickUpper, uint128 amount) external returns (uint256)"
];

const vammManager = new ethers.Contract(VAMM_MANAGER, VAMM_BURN_ABI, signer);

// Burn all liquidity
await vammManager.burn(
    poolKeyArray,
    accountTuple,
    tickLowerRounded,
    tickUpperRounded,
    liquidityAmount  // Amount to burn
);

console.log("Liquidity removed");

Settle After Maturity

At pool maturity, LP positions are settled like trader positions:

await collateralEngine.settlePosition(account, poolKey);
console.log("LP position settled");

LP Strategies

1. Wide Range (Passive)

Strategy: Provide liquidity across a wide range

Range: 2% — 15%
Pros: Always in range, low maintenance
Cons: Lower fee income, less capital efficient
Best for: Passive LPs who don't want to manage actively

2. Narrow Range (Active)

Strategy: Concentrate liquidity at current FY

Range: Current FY ± 1%
Pros: High fee income, very capital efficient
Cons: Requires active management, IL risk
Best for: Active LPs who monitor regularly

3. Range Around Expected FY

Strategy: Place range where you think FY will trade

1. Analyze historical FY data
2. Identify likely trading range
3. Place liquidity there
4. Adjust as market conditions change

Understanding LP Returns

Example Calculation

LP Position:
- Liquidity: 1,000,000 units
- Range: 5% — 8%
- Term: 90 days

Pool Activity:
- Trading volume: $10,000,000
- Your share of in-range liquidity: 5%
- Fee rate: 0.01%

Fee Income:
= $10,000,000 × 0.01% × 5%
= $500

Plus/Minus:
- Settlement PnL based on position composition at maturity
- Any IL from FY movement within range

APY Estimation

function estimateLPApy(
    feeEarned,
    marginDeposited,
    daysActive
) {
    const dailyReturn = feeEarned / marginDeposited / daysActive;
    const apy = dailyReturn * 365 * 100;
    return apy;
}

// Example
const apy = estimateLPApy(500, 10000, 90);
console.log(`Estimated APY: ${apy.toFixed(2)}%`);  // ~20.3%

Risks for LPs

1. Impermanent Loss

If FY moves significantly:
- Your position gains directional exposure
- At settlement, you realize this exposure as PnL
- Can result in losses even if you earned fees

2. Out of Range

If FY moves outside your range:
- You stop earning fees
- Your position is 100% on one side
- Decision: wait, reposition, or close

3. Low Volume

If trading volume is low:
- Fee income may not justify margin locked
- Consider wider ranges or different pools

Key Takeaways

1. LPs earn trading fees — 0.01% of volume in your range

2. Concentrated liquidity — Choose your FY range wisely

3. Narrower = more fees, more risk — Trade-off between efficiency and safety

4. Monitor your range — Reposition if FY moves outside

5. IL is real — Fees may not always offset impermanent loss

Next Steps

• Settlement — How LP positions settle

• Risk Management — LP-specific risks

• VAMM Explained — Technical deep dive