Liquidity Providers (CLP API)

Overview

Liquidity providers interact with the CLP vault, which mints an ERC-20 share token representing proportional ownership of the vault’s pooled base token/quote token inventory.

Core user entrypoints from CLP.sol:

• depositDual(baseAmountDesired, quoteAmountDesired, baseMin, quoteMin) -> shares
• withdrawDual(shares, baseMin, quoteMin) -> (baseOut, quoteOut)

APY metrics shown in app

Vault UI shows two annualized trailing-7D metrics:

• Spread APY: annualized trailing 7D spread-yield return, where spread-yield return is estimated spread PnL divided by 7D time-weighted average vault NAV.
• APY vs Passive Hold: annualized trailing 7D excess return vs passive hold, where excess return is ((1 + vault_return_7d) / (1 + passive_hold_return_7d)) - 1.
• Annualization uses compounding: APY = (1 + return_7d)^(365/7) - 1.
• If spread snapshots are unavailable in the window, Spread APY falls back to annualized trailing 7D excess return vs passive hold.

Depositing

depositDual

LPs deposit both assets and receive CLP shares:

• baseAmountDesired: desired base tokens to deposit
• quoteAmountDesired: desired quote tokens to deposit
• baseMin / quoteMin: slippage guards (enforced after the initial deposit)

Behavior notes from CLP.sol:

• If this is the initial deposit (totalSupply() == 0), only DEFAULT_ADMIN_ROLE or OPERATOR_ROLE can deposit (CLP__InitialDepositRestricted otherwise).
• After initialization, the vault computes an “optimal” ratio vs. realtime balances and may deposit less than your desired amounts to match the pool ratio.
• Fee-on-transfer (FOT) tokens are not supported; deposits will revert for such tokens.

Withdrawing

withdrawDual

LPs burn shares and receive both assets:

• shares: shares to burn
• baseMin / quoteMin: slippage guards

Additional mechanics:

• Withdrawal fee: withdrawalFeeBps (burned shares) may reduce the effective shares redeemed, capped by MAX_WITHDRAWAL_FEE_BPS.
  • Final LP exception: if you are the last remaining LP, the fee is not charged because there are no remaining LPs to benefit and MINIMUM_LIQUIDITY is locked.
• Cooldown: if withdrawalCooldown != 0, repeated withdrawals can revert with CLP__WithdrawalCooldown.

Liquidity availability

CLP assets may be:

• held directly by the vault
• withdrawable from MAOB (after maker claims/cancels + MAOB withdraw)
• locked in active MAOB orders (unfilled input)

If a withdrawal requires liquidity that is currently locked, CLP will attempt to:

1. claim active orders
2. withdraw MAOB withdrawables
3. cancel “outermost” active orders until enough liquidity exists

Inspecting vault state

Use getRealtimeBalances() to understand the vault’s current composition:

• freeBase/freeQuote: base token and quote token balances held by CLP
• withdrawableBase/withdrawableQuote: base token and quote token balances withdrawable from MAOB
• unfilledBase/unfilledQuote: base token and quote token input still resting in active orders
• unclaimedBase/unclaimedQuote: base token and quote token output claimable from fills
• totalBase/totalQuote: sum of all base token and quote token components