Skip to main content

Withdraw Liquidity

Overview​

Withdrawing liquidity is an important aspect of the Chromatic Protocol, as it allows users to retrieve their invested liquidity from the liquidity pools. The withdrawal process consists of two stages: "Remove Liquidity" and "Withdraw Liquidity."

Remove Liquidity​

To begin the liquidity withdrawal process in the Chromatic Protocol, users need to perform the "Remove Liquidity" stage. This stage is carried out after a successful removal of liquidity from a specific ChromaticMarket contract using the removeLiquidity function in the IChromaticRouter interface.

During the removal process, users specify the target ChromaticMarket contract, the fee rate of the liquidity bin, the amount of CLB tokens to be removed as liquidity, and the recipient address. The Chromatic Protocol evaluates the elapsed oracle version and determines the withdrawable amount of tokens from the specified CLB token amount based on the available free liquidity in the corresponding bin. Notably, the withdrawal of liquidity becomes possible from the next oracle version onwards.

Upon calling the removeLiquidity function, the Chromatic Protocol performs a burn operation on the CLB tokens equivalent to the withdrawable amount. This effectively removes the burned tokens from circulation and prepares them for the subsequent stage of withdrawing liquidity.

Withdraw Liquidity​

The "Withdraw Liquidity" stage allows users to finalize the liquidity withdrawal process by transferring the withdrawable tokens and the remaining CLB tokens to the recipient address. This stage becomes available once the oracle version has advanced following the "Remove Liquidity" stage.

To withdraw liquidity, users need to provide the target ChromaticMarket contract address and the receipt ID associated with the LP receipt representing the liquidity to be withdrawn. By invoking the withdrawLiquidity function in the IChromaticRouter interface, the Chromatic Protocol facilitates the transfer of the withdrawable tokens to the recipient address while leaving the remaining CLB tokens intact.

ChromaticRouter Interface​

The IChromaticRouter interface serves as the primary interface for interacting with the liquidity withdrawal functionality of the Chromatic Protocol. It extends the IChromaticLiquidityCallback interface, which provides additional callback functions. The ChromaticRouter interface includes the following functions:

removeLiquidity​

function removeLiquidity(
    address market,
    int16 feeRate,
    uint256 clbTokenAmount,
    address recipient
) external returns (LpReceipt memory receipt);

The removeLiquidity function allows users to remove liquidity from a specific ChromaticMarket contract. Users specify the target ChromaticMarket contract, the fee rate, the amount of CLB tokens to remove as liquidity, and the recipient address. Upon successful execution, the function returns an LP receipt that represents the removed liquidity.

withdrawLiquidity​

function withdrawLiquidity(address market, uint256 receiptId) external;

The withdrawLiquidity function enables users to withdraw liquidity from a ChromaticMarket contract. Users provide the target ChromaticMarket contract address and the receipt ID of the LP receipt representing the liquidity to be withdrawn. The function transfers the withdrawable tokens and the remaining CLB tokens to the recipient address.

Example Usage​

The following example demonstrates how to use the ChromaticRouter interface to remove and withdraw liquidity:

// Import the required interfaces
import "@openzeppelin/contracts/interfaces/IERC20.sol";
import "@chromatic-protocol/contracts/periphery/interfaces/IChromaticRouter.sol";
import "@chromatic-protocol/contracts/core/interfaces/IChromaticMarket.sol";

// Instantiate ChromaticRouter contract
IChromaticRouter router = IChromaticRouter(/* router address */);

// Define liquidity parameters
address market = /* market address */;  
int16 feeRate = /* fee rate */;         
uint256 clbTokenAmount = /* liquidity amount */; 
address recipient = /* recipient address */; 

// Remove liquidity
LpReceipt memory receipt = router.removeLiquidity(market, feeRate, clbTokenAmount, recipient);

// After the oracle version has elapsed

// Withdraw liquidity
router.withdrawLiquidity(market, receipt.id);

In this example, we first instantiate the ChromaticRouter contract. Then, we define the liquidity parameters such as the target ChromaticMarket contract, the fee rate, the CLB token amount, and the recipient address. We then call the removeLiquidity function to initiate the removal of liquidity from the ChromaticMarket contract, which returns an LP receipt. Finally, we use the withdrawLiquidity function to complete the liquidity withdrawal process by transferring the withdrawable tokens and the remaining CLB tokens to the recipient address.