MIMSwap

Overview

MIMSwap is a decentralized automated market maker (AMM) designed for creating and managing liquidity pools. This documentation provides a detailed guide on the MIMSwap Router, MagicLP liquidity pools, and integration steps for third-party applications. MIMSwap is based off of Dodo DSP v2, complementary information can be found in Dodo's documentation.

MagicLP Liquidity Pools

Introduction

MagicLP liquidity pools are the core components of the MIMSwap system. They facilitate token swaps, liquidity provision, and yield generation. This section focuses on the MagicLP contract, detailing how it works, how to interact with it directly, and how the MIMSwap Router leverages its functionalities.

Key Functions in MagicLP

1. Swapping Tokens

   • sellBase

   • sellQuote

2. Adding Liquidity

   • buyShares

3. Removing Liquidity

   • sellShares

4. Query Functions

   • querySellBase

   • querySellQuote

Swapping Tokens

sellBase

This function sells base tokens (e.g., MIM) for quote tokens (e.g., USDC).

function sellBase(address to) external nonReentrant onlyClones whenNotPaused returns (uint256 receiveQuoteAmount)

Process:

1. Balance Calculation: Calculates the base tokens received.

2. Query: Uses querySellBase to determine the amount of quote tokens to send in return.

3. Transfer: Transfers the calculated quote tokens to the recipient.

4. Update Reserves: Updates the pool reserves.

Example Usage:

address mim = 0xFEa7a6a0B346362BF88A9e4A88416B77a57D6c2A;
address usdc = 0xaf88d065e77c8cC2239327C5EDb3A432268e5831;
address lp = '0xPoolAddress'; // Address of the MagicLP pool
address to = msg.sender; // Recipient address
uint256 amountIn = 100 * 1e18; // Amount of base tokens (MIM) to sell

// Query the expected amount of quote tokens (USDC)
(uint256 receiveQuoteAmount, uint256 mtFee) = IMagicLP(lp).querySellBase(to, amountIn);

// Execute the sell
IMagicLP(lp).sellBase(to);

sellQuote

This function sells quote tokens (e.g., USDC) for base tokens (e.g., MIM).

function sellQuote(address to) external nonReentrant onlyClones whenNotPaused returns (uint256 receiveBaseAmount)

Process:

1. Balance Calculation: Calculates the quote tokens received.

2. Query: Uses querySellQuote to determine the amount of base tokens to send in return.

3. Transfer: Transfers the calculated base tokens to the recipient.

4. Update Reserves: Updates the pool reserves.

Example Usage:

address mim = 0xFEa7a6a0B346362BF88A9e4A88416B77a57D6c2A;
address usdc = 0xaf88d065e77c8cC2239327C5EDb3A432268e5831;
address lp = '0xPoolAddress'; // Address of the MagicLP pool
address to = msg.sender; // Recipient address
uint256 amountIn = 100 * 1e6; // Amount of quote tokens (USDC) to sell

// Query the expected amount of base tokens (MIM)
(uint256 receiveBaseAmount, uint256 mtFee) = IMagicLP(lp).querySellQuote(to, amountIn);

// Execute the sell
IMagicLP(lp).sellQuote(to);

Adding Liquidity

buyShares

This function allows users to provide liquidity to the pool in exchange for LP tokens.

function buyShares(address to) external nonReentrant onlyClones whenNotPaused returns (uint256 shares, uint256 baseInput, uint256 quoteInput)

Process:

1. Balance Calculation: Calculates the base and quote tokens added to the pool.

2. Share Calculation: Determines the number of LP tokens to mint based on the input tokens.

3. Minting: Mints the LP tokens and sends them to the specified address.

4. Update Reserves: Updates the pool reserves.

Example Usage:

address mim = 0xFEa7a6a0B346362BF88A9e4A88416B77a57D6c2A;
address usdc = 0xaf88d065e77c8cC2239327C5EDb3A432268e5831;
address lp = '0xPoolAddress'; // Address of the MagicLP pool
address to = msg.sender; // Recipient address
uint256 baseInAmount = 500 * 1e18; // Amount of base tokens (MIM) to add
uint256 quoteInAmount = 500 * 1e6; // Amount of quote tokens (USDC) to add

// Provide liquidity and get LP tokens
IMagicLP(lp).buyShares(to);

Removing Liquidity

sellShares

This function allows users to redeem their LP tokens for the underlying base and quote tokens.

function sellShares(uint256 shareAmount, address to, uint256 baseMinAmount, uint256 quoteMinAmount, bytes calldata data, uint256 deadline) external nonReentrant onlyClones whenNotPaused returns (uint256 baseAmount, uint256 quoteAmount)

Process:

1. Share Calculation: Determines the amount of base and quote tokens to return based on the LP tokens being redeemed.

2. Transfer: Transfers the base and quote tokens to the specified address.

3. Burning: Burns the redeemed LP tokens.

4. Update Reserves: Updates the pool reserves.

Example Usage:

address mim = 0xFEa7a6a0B346362BF88A9e4A88416B77a57D6c2A;
address usdc = 0xaf88d065e77c8cC2239327C5EDb3A432268e5831;
address lp = 0xPoolAddress; // Address of the MagicLP pool
address to = msg.sender; // Recipient address
uint256 sharesIn = 1e18; // Amount of LP tokens to redeem

// Redeem LP tokens for underlying assets
IMagicLP(lp).sellShares(sharesIn, to, 400 * 1e18, 400 * 1e6, "", block.timestamp + 300);

Query Functions

querySellBase

Returns the amount of quote tokens received for selling a specified amount of base tokens.

function querySellBase(address trader, uint256 payBaseAmount) public view returns (uint256 receiveQuoteAmount, uint256 mtFee)

Usage:

address mim = 0xFEa7a6a0B346362BF88A9e4A88416B77a57D6c2A;
address usdc = 0xaf88d065e77c8cC2239327C5EDb3A432268e5831;
address lp = 0xPoolAddress; // Address of the MagicLP pool
address trader = msg.sender; // Trader address
uint256 payBaseAmount = 100 * 1e18; // Amount of base tokens (MIM) to sell

// Get the expected quote tokens (USDC)
(uint256 receiveQuoteAmount, uint256 mtFee) = IMagicLP(lp).querySellBase(trader, payBaseAmount);

querySellQuote

Returns the amount of base tokens received for selling a specified amount of quote tokens.

function querySellQuote(address trader, uint256 payQuoteAmount) public view returns (uint256 receiveBaseAmount, uint256 mtFee)

Usage:

address mim = 0xFEa7a6a0B346362BF88A9e4A88416B77a57D6c2A;
address usdc = 0xaf88d065e77c8cC2239327C5EDb3A432268e5831;
address lp = 0xPoolAddress; // Address of the MagicLP pool
address trader = msg.sender; // Trader address
uint256 payQuoteAmount = 100 * 1e6; // Amount of quote tokens (USDC) to sell

// Get the expected base tokens (MIM)
(uint256 receiveBaseAmount, uint256 mtFee) = IMagicLP(lp).querySellQuote(trader, payQuoteAmount);

Example: Using the Router to Interact with MagicLP

While the MagicLP contract provides all the necessary functions for token swaps and liquidity operations, the MIMSwap Router simplifies these interactions by providing a unified interface. Let's walk through an example of how the Router interacts with the MagicLP pools to perform a token swap.

Step-by-Step Swap Example Using the Router

1. Determine the Path and Directions

   Assume we want to swap MIM for USDC through a single liquidity pool.

   address[] memory path = new address[](1);
   path[0] = '0xPoolAddress'; // The address of the MIM-USDC liquidity pool
   
   uint256 directions = 0; // Sell base token (MIM)
   
   

2. Get the Expected Price

   Use the querySellBase function to get the expected amount of USDC for the given amount of MIM.

   (uint256 receiveQuoteAmount, uint256 mtFee) = IMagicLP(0xPoolAddress).querySellBase(msg.sender, amountInMIM);

3. Execute the Swap

   Call the swapTokensForTokens function on the router with the determined path and directions.

   uint256 minimumOut = receiveQuoteAmount;
   uint256 deadline = block.timestamp + 300; // 5 minutes from now
   
   router.swapTokensForTokens(
       msg.sender,
       amountInMIM,
       path,
       directions,
       minimumOut,
       deadline
   );

By following these steps, third-party systems can effectively integrate MIMSwap's swapping functionality, providing their users with seamless and efficient token swaps.