Skip to main content

Provide Liquidity

Overview​

The Chromatic Protocol allows users to provide liquidity to the protocol's liquidity pools. Providing liquidity is an essential aspect of the protocol as it ensures sufficient liquidity for perpetual futures trading. The liquidity provision process consists of two stages:

Add Liquidity​

To participate in the Chromatic Protocol and provide liquidity, users can add funds by calling the addLiquidity function of the ChromaticRouter contract. This function allows users to specify the target ChromaticMarket contract, the desired fee rate, the amount of liquidity to be added, and the recipient address.

Before invoking the addLiquidity function, users must ensure that they have approved the token to be deposited to the ChromaticRouter contract. This approval process allows for a seamless transfer of funds during the liquidity addition.

Claim Liquidity​

After adding liquidity and receiving an LP receipt, users can claim their corresponding CLBToken from the ChromaticMarket contract. However, it is important to note that users can only claim liquidity starting from the next oracle version recorded in the LP receipt. The Chromatic Protocol enforces this restriction to ensure that the claimed liquidity aligns with the updated state of the protocol.

To claim liquidity, users need to call the claimLiquidity function of the ChromaticRouter contract. This function requires the target ChromaticMarket contract address and the receipt ID of the LP receipt associated with the liquidity they wish to claim. By executing this function, users can receive the CLBToken representing their liquidity from the ChromaticMarket contract.

ChromaticRouter Interface​

The IChromaticRouter interface is used to interact with the liquidity provision functionality of the Chromatic Protocol. It extends the IChromaticLiquidityCallback interface and provides the following functions:

addLiquidity​

The addLiquidity function allows users to add liquidity to a specific ChromaticMarket contract. It takes the target ChromaticMarket contract address, the fee rate, the liquidity amount, and the recipient address as input parameters. Users must approve the token to be deposited to the ChromaticRouter contract before calling this function. The function returns an LP receipt that represents the user's added liquidity.

claimLiquidity​

The claimLiquidity function enables users to claim their corresponding CLBToken from a specific ChromaticMarket contract. Users need to provide the target ChromaticMarket contract address and the receipt ID of the LP receipt they want to claim.

LP Receipt Structure​

The LPReceipt struct represents a receipt of an LP action performed. It contains the following properties:

  • id: An identifier for the receipt.
  • oracleVersion: The oracle version associated with the action.
  • amount: The amount involved in the action.
  • recipient: The address of the recipient of the action.
  • action: An enumeration representing the type of LP action performed.
  • tradingFeeRate: The trading fee rate associated with the LP action.

Example Usage​

Here is an example that demonstrates how to use the ChromaticRouter interface to add liquidity and claim 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 amount = /* liquidity amount */; 
address recipient = /* recipient address */; 

// Approve tokens for deposit
IERC20 token = IERC20(IChromaticMarket(market).settlementToken());
token.approve(address(router), amount);

// Add liquidity
LpReceipt memory receipt = router.addLiquidity(market, feeRate, amount, recipient);

// After the oracle version has elapsed

// Claim liquidity
router.claimLiquidity(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 liquidity amount, and the recipient address. Before calling the addLiquidity function, users should approve the token to be deposited to the ChromaticRouter contract. We then invoke the addLiquidity function to add liquidity to the ChromaticMarket contract, which returns an LP receipt. Finally, we use the claimLiquidity function to claim the corresponding CLBToken for the added liquidity.