Liquidity Provisioning
Liquidity provisioning involves adding asset pairs (X and Y) to a pool to facilitate trading. In return, liquidity providers (LPs) receive Liquidity Tokens representing their share of the pool and earn trading fees.
Depositing Liquidity
Depositing into a CPMM V2 pool is a two-step process because standard TON transactions usually carry only one type of asset. To handle this, the protocol uses a temporary Deposit contract.
The Deposit Flow
- Step 1: Send Asset X. The user sends the first asset (e.g., TON) to the Pool with a
Depositpayload. The Pool deploys a temporary Deposit contract and credits the asset to it. - Step 2: Send Asset Y. The user sends the second asset (e.g., Jetton) to the Pool (not the Deposit contract directly). The Pool forwards this credit to the existing Deposit contract.
- Completion: Once the Deposit contract holds the required amounts of both X and Y, it automatically triggers a
JoinLiquiditymessage to the Pool. - Minting: The Pool calculates the liquidity tokens to mint, updates reserves, and sends the liquidity tokens to the user's Position contract.
Deposit Payload
Both payments (Step 1 and Step 2) must include a DepositPayload.
struct (0xc9a015da) DepositPayload {
amountX: coins
amountY: coins
minimalLiquidity: coins
lockedLiquidityShare: uint16
}| Parameter | Description |
|---|---|
amountX | The expected total amount of Asset X to be deposited. |
amountY | The expected total amount of Asset Y to be deposited. |
minimalLiquidity | Slippage Protection. The minimum amount of LP tokens to mint. If the actual minted amount is lower (due to reserve changes between steps), the transaction fails and assets are refunded. |
lockedLiquidityShare | A portion (in BPS, 0-10000) of the minted liquidity to permanently lock. Useful for initial liquidity offerings or protocol-owned liquidity. |
When depositing TON, use the PayNative message with DepositPayload.
When depositing Jettons, use Transfer with forward_payload containing PayJetton → DepositPayload.
Withdrawing Liquidity
Withdrawing removes liquidity from the pool and returns the proportional share of Asset X and Asset Y to the user. This
creates a Withdraw message sent to the Pool, which forwards it to the user's Position.
Withdraw Flow
Withdraw Message
struct (0x20b5ef89) Withdraw {
queryId: uint64
liquidity: coins
minimalXOut: coins
minimalYOut: coins
autoClaimFees: bool
payoutConfig: Cell<BasicPayoutConfig>
}| Parameter | Description |
|---|---|
liquidity | The amount of LP tokens to burn. |
minimalXOut | Minimum amount of Asset X to receive (slippage protection). |
minimalYOut | Minimum amount of Asset Y to receive (slippage protection). |
autoClaimFees | If true, the operation will also claim any accrued trading fees attached to this position. |
payoutConfig | Defines where to send the withdrawn assets (X and Y). |
Claiming Fees
Liquidity providers earn trading fees. These fees accumulate in the Position contract and are not automatically
auto-compounded into the pool reserves. Users must explicitly claim them or use autoClaimFees during withdrawal.
Claim Flow
To claim fees without withdrawing liquidity, send a ClaimPositionFees message to the Pool.
Message Structure
struct (0x5652f1df) ClaimPositionFees {
queryId: uint64
excessesTo: address
}