HomeLearning PathsDeFiSwap

Adding Liquidity in a DEX

On This Page

Summary

  • Adding liquidity in a DEX involves users providing token pairs to create trading pools
  • The process is managed through the add_liquidity function, which handles token withdrawal, deposit, and LP token minting
  • Optimal amounts are calculated to maintain the pool's price ratio and prevent manipulation
  • LP tokens are minted proportionally to the liquidity provided, with special considerations for initial liquidity
  • Safety measures include slippage protection, minimum liquidity requirements, and atomic state updates
  • Events are emitted for transparency and off-chain tracking of pool activities
  • The process ensures fair distribution of LP tokens and maintains the constant product formula

Introduction to Adding Liquidity in a DEX

Adding liquidity is a fundamental operation in any Decentralized Exchange (DEX). When users provide token pairs to create trading pools, they receive Liquidity Provider (LP) tokens in return. This process is crucial for maintaining the DEX's functionality and liquidity. Let's dive into the detailed implementation of the add_liquidity function and its components, breaking it down for beginners.

1. Understanding the Main Entry Point: add_liquidity

The add_liquidity function is the primary way users interact with the liquidity pool. Let's examine its structure and purpose:

public fun add_liquidity<X, Y>(
    sender: &signer,
    amount_x: u64,
    amount_y: u64
): (u64, u64, u64) acquires TokenPairReserve, TokenPairMetadata, PairEventHolder {
    let (a_x, a_y, coin_lp, fee_amount, coin_left_x, coin_left_y) = 
    add_liquidity_direct(
        coin::withdraw<X>(sender, amount_x), 
        coin::withdraw<Y>(sender, amount_y)
    );
    
    let sender_addr = signer::address_of(sender);
    let lp_amount = coin::value(&coin_lp);
    assert!(lp_amount > 0, ERROR_INSUFFICIENT_LIQUIDITY);
    
    check_or_register_coin_store<LPToken<X, Y>>(sender);
    coin::deposit(sender_addr, coin_lp);
    coin::deposit(sender_addr, coin_left_x);
    coin::deposit(sender_addr, coin_left_y);
    
    let pair_event_holder = borrow_global_mut<PairEventHolder<X, Y>>(DEFAULT_ADMIN);
    event::emit_event<AddLiquidityEvent<X, Y>>(
        &mut pair_event_holder.add_liquidity,
        AddLiquidityEvent<X, Y> {
            user: sender_addr,
            amount_x: a_x,
            amount_y: a_y,
            liquidity: lp_amount,
            fee_amount: (fee_amount as u64),
        }
    );

    (a_x, a_y, lp_amount
}

1.1. Input Parameters Explained

  • sender: &signer: This represents the account that's adding liquidity. In Move, a signer is a special type that proves ownership of an account.
  • amount_x: u64: The amount of token X the user wants to add to the pool. u64 means it's an unsigned 64-bit integer.
  • amount_y: u64: The amount of token Y the user wants to add to the pool.
  • Returns: (u64, u64, u64): This function returns three values:
    • The actual amount of token X used
    • The actual amount of token Y used
    • The number of LP tokens received

1.2. Understanding Coin Operations

The function starts by withdrawing tokens from the sender's account:

coin::withdraw<X>(sender, amount_x),
coin::withdraw<Y>(sender, amount_y)
  • These operations move tokens from the user's account to the contract's control.
  • The coin::withdraw function automatically checks if the user has sufficient balance.
  • If the balance is insufficient, the operation will fail, preventing any further execution.

1.3. Processing Return Values

After adding liquidity, the function checks if LP tokens were successfully minted:

let lp_amount = coin::value(&coin_lp);
assert!(lp_amount > 0, ERROR_INSUFFICIENT_LIQUIDITY);
  • This verifies that a non-zero amount of LP tokens were minted.
  • If no LP tokens were minted (lp_amount = 0), the function will abort with an error.
  • This check ensures that users always receive LP tokens when adding liquidity, preventing potential loss of funds.

1.4. Managing Token Stores

Before depositing LP tokens, the function ensures the user can receive them:

check_or_register_coin_store<LPToken<X, Y>>(sender);

Let's look at the helper function implementation:

public fun check_or_register_coin_store<X>(sender: &signer) {
    if (!coin::is_account_registered<X>(signer::address_of(sender))) {
        coin::register<X>(sender);
    };
}
  • This function checks if the sender's account is registered to hold the LP token.
  • If not registered, it automatically registers the account to receive the token.
  • This prevents failures when trying to deposit LP tokens to an unregistered account.

2. Deep Dive into Direct Liquidity Addition

The core logic of adding liquidity is handled by the add_liquidity_direct function. Let's break it down:

fun add_liquidity_direct<X, Y>(
    x: coin::Coin<X>,
    y: coin::Coin<Y>,
): (u64, u64, coin::Coin<LPToken<X, Y>>, u64, coin::Coin<X>, coin::Coin<Y>)
    acquires TokenPairReserve, TokenPairMetadata {
    let amount_x = coin::value(&x);
    let amount_y = coin::value(&y);
    let (reserve_x, reserve_y, _) = token_reserves<X, Y>();
    
    // Calculate optimal amounts
    let (a_x, a_y) = if (reserve_x == 0 && reserve_y == 0) {
        (amount_x, amount_y)
    } else {
        calculate_optimal_amounts(amount_x, amount_y, reserve_x, reserve_y)
    };

    assert!(a_x <= amount_x, ERROR_INSUFFICIENT_AMOUNT);
    assert!(a_y <= amount_y, ERROR_INSUFFICIENT_AMOUNT);

    let left_x = coin::extract(&mut x, amount_x - a_x);
    let left_y = coin::extract(&mut y, amount_y - a_y);
    
    deposit_x<X, Y>(x);
    deposit_y<X, Y>(y);
    
    let (lp, fee_amount) = mint<X, Y>();
    
    (a_x, a_y, lp, fee_amount, left_x, left_y)
}

2.1. Calculating Optimal Amounts

The function handles two scenarios: initial liquidity and subsequent additions.

For initial liquidity (when the pool is empty):

if (reserve_x == 0 && reserve_y == 0) {
    (amount_x, amount_y)
}
  • When the pool is empty, all provided tokens are used.
  • This sets the initial price ratio for the pool.

For subsequent additions:

let amount_y_optimal = swap_utils::quote(amount_x, reserve_x, reserve_y);
if (amount_y_optimal <= amount_y) {
    (amount_x, amount_y_optimal)
} else {
    let amount_x_optimal = swap_utils::quote(amount_y, reserve_y, reserve_x);
    assert!(amount_x_optimal <= amount_x, ERROR_INVALID_AMOUNT);
    (amount_x_optimal, amount_y)
}

The quote function calculates the optimal amount to maintain the current price ratio:

public fun quote(amount_x: u64, reserve_x: u64, reserve_y: u64): u64 {
    assert!(amount_x > 0, ERROR_INSUFFICIENT_AMOUNT);
    assert!(reserve_x > 0 && reserve_y > 0, ERROR_INSUFFICIENT_LIQUIDITY);
    (((amount_x as u128) * (reserve_y as u128) / (reserve_x as u128)) as u64)
}
  • This calculation ensures the constant product formula: (x + Δx)/(y + Δy) = x/y
  • It prevents price manipulation by maintaining the current pool ratio.
  • The function uses u128 (128-bit integers) for intermediate calculations to prevent overflow.

2.2. Depositing Tokens into the Pool

After calculating optimal amounts, the tokens are deposited into the pool:

fun deposit_x<X, Y>(amount: coin::Coin<X>) acquires TokenPairMetadata {
    let metadata = borrow_global_mut<TokenPairMetadata<X, Y>>(DEFAULT_ADMIN);
    coin::merge(&mut metadata.balance_x, amount);
}

fun deposit_y<X, Y>(amount: coin::Coin<Y>) acquires TokenPairMetadata {
    let metadata = borrow_global_mut<TokenPairMetadata<X, Y>>(DEFAULT_ADMIN);
    coin::merge(&mut metadata.balance_y, amount);
}
  • These functions update the pool's balances by merging the new tokens with existing reserves.
  • The borrow_global_mut function allows modifying global storage.
  • Using separate functions for X and Y tokens ensures type safety and prevents mixing up token types.

3. Understanding the LP Token Minting Process

After depositing tokens, the contract mints LP tokens for the liquidity provider:

fun mint<X, Y>(): (coin::Coin<LPToken<X, Y>>, u64) acquires TokenPairReserve, TokenPairMetadata {
    let metadata = borrow_global_mut<TokenPairMetadata<X, Y>>(DEFAULT_ADMIN);
    let (balance_x, balance_y) = (coin::value(&metadata.balance_x), 
                                 coin::value(&metadata.balance_y));
    let reserves = borrow_global_mut<TokenPairReserve<X, Y>>(DEFAULT_ADMIN);
    
    let amount_x = (balance_x as u128) - (reserves.reserve_x as u128);
    let amount_y = (balance_y as u128) - (reserves.reserve_y as u128);
    
    let fee_amount = mint_fee<X, Y>(reserves.reserve_x, reserves.reserve_y, metadata);
    let total_supply = total_lp_supply<X, Y>();
    
    let liquidity = calculate_liquidity_amount(
        amount_x, 
        amount_y, 
        total_supply, 
        reserves
    );
    
    let lp = mint_lp<X, Y>((liquidity as u64), &metadata.mint_cap);
    update<X, Y>(balance_x, balance_y, reserves);
    metadata.k_last = (reserves.reserve_x as u128) * (reserves.reserve_y as u128);
    
    (lp, fee_amount)
}

3.1. Initial Liquidity Calculation

For the first liquidity provider, LP tokens are calculated as follows:

if (total_supply == 0u128) {
    let sqrt = math128::sqrt(amount_x * amount_y);
    assert!(sqrt > MINIMUM_LIQUIDITY, ERROR_INSUFFICIENT_LIQUIDITY_MINTED);
    let l = sqrt - MINIMUM_LIQUIDITY;
    mint_lp_to<X, Y>(DEFAULT_ADMIN, (MINIMUM_LIQUIDITY as u64), &metadata.mint_cap);
    l
}
  • The geometric mean (square root of the product) of deposits is used to determine initial LP tokens.
  • A small amount (MINIMUM_LIQUIDITY) is locked forever to prevent the pool from being drained completely.
  • This approach helps in setting a fair initial price and prevents exploitation by the first liquidity provider.

3.2. Subsequent Liquidity Calculation

For subsequent liquidity additions, LP tokens are calculated proportionally:

let liquidity = math128::min(
    amount_x * total_supply / (reserves.reserve_x as u128),
    amount_y * total_supply / (reserves.reserve_y as u128)
);
assert!(liquidity > 0u128, ERROR_INSUFFICIENT_LIQUIDITY_MINTED);
  • This calculation ensures fair distribution of LP tokens based on the proportion of liquidity added.
  • Using the minimum of the two ratios prevents dilution and maintains fairness.
  • The assert statement ensures that some LP tokens are always minted, preventing zero-value operations.

4. Event Emission for Transparency

The contract emits an event after successfully adding liquidity:

struct AddLiquidityEvent<phantom X, phantom Y> has drop, store {
    user: address,
    amount_x: u64,
    amount_y: u64,
    liquidity: u64,
    fee_amount: u64
}
  • This event records all relevant details of the liquidity addition.
  • It includes the user's address, amounts of both tokens used, LP tokens received, and any fees paid.
  • Emitting events allows for off-chain tracking and analysis of pool activities.

5. Crucial Safety Considerations

  1. Slippage Protection:

    • The contract calculates optimal amounts to maintain the asset ratio.
    • Any unused tokens are returned to the user, preventing unexpected losses.

  2. Minimum Requirements:

    • The contract enforces a non-zero liquidity check to prevent dust amounts.
    • A minimum LP token amount is required to prevent exploitation.

  3. State Updates:

    • All operations are performed atomically to ensure consistency.
    • The constant product (K value) is maintained throughout the process.

  4. **Error Handling:**The contract uses clear error codes for different failure scenarios:

    const ERROR_INSUFFICIENT_LIQUIDITY_MINTED: u64 = 0x004;
const ERROR_INSUFFICIENT_AMOUNT: u64 = 0x006;
const ERROR_INVALID_AMOUNT: u64 = 0x008;
    • These error codes help in identifying and debugging issues quickly.
    • Each error corresponds to a specific failure case, improving error handling and user feedback.

This detailed breakdown of the add_liquidity function and its components provides a comprehensive understanding of how liquidity is added to a DEX. Next, we'll explore the remove_liquidity function to complete our understanding of liquidity management in a DEX