EN

Wtfswap contract design

Author of this section: @Web3Pignard @Fish

this lecture will design the structure of the overall contract, define the interfaces of each contract, and do a preliminary technical analysis.

Contract Demand Description

wtfswap design each pool has a price range, swap can only deal within this price range

  1. anyone can create a pool, which can specify the current price and price range: [a, B] and rate f; There can be multiple pools for the same transaction pair and rate; You cannot delete or modify a pool;
  2. anyone can add liquidity, adding liquidity only in the specified price range [a, B];
  3. the liquidity provider can reduce the added liquidity and withdraw the two tokens corresponding to the reduced liquidity;
  4. liquidity providers can charge a fee in the anyone swap process, the fee is f, weighted equally to the liquidity provider according to the liquidity contribution;
  5. anyone can swap,swap needs to specify a pool, swap can specify input (maximize output) or specify output (minimize input), and if the specified pool is illiquid, only a partial deal will be made.

The above fee collection method is different from Uniswap, which has been simplified and will continue to be explained in the subsequent fee realization chapter.

Contract structure

on the principle of simplicity, we do not divide the contract periphery and core two separate warehouses, but are divided from top to bottom into the following four contracts.

  • PoolManager.sol : The top-level contract, which corresponds to the Pool page and is responsible for the creation and management of the Pool.
  • PositionManager.sol : top-level contract, corresponding to the Position page, responsible for the management of LP positions and liquidity;
  • SwapRouter.sol : The top-level contract, corresponding to the Swap page, is responsible for estimating prices and trading;
  • Factory.sol : the underlying contract, the Pool's factory contract;
  • Pool.sol : The lowest contract, corresponding to a trading pool, records the current price, position, liquidity and other information.

Here is the UML diagram of the contract:

contract interface design

because we are designing contracts from the top down, we first analyze what functions are needed on the front-end pages (Pool page, Position page, and Swap page) and design the top-level contract for this purpose, and then further analyze the details to design the bottom-level contract.

PoolManager

PoolManager.sol corresponding to the Pool page, let's first look at what functions the Pool page has.

The first is to show all the pool, corresponding to the front page as follows:

correspondingly, we need an interface to support DApp front-end to obtain all transaction pools. In Uniswap, this interface is provided by the server, which pulls the contract information on the chain and returns it to the front end. However, our design is to directly call the contract to obtain the current trading pool available for trading, so that DApp does not rely on the server (of course, for actual projects, relying on the server may be more appropriate). To this end, we define getAllPools interface, which is used to get all the trading pools, defines PoolInfo save information for each pool. 

struct PoolInfo {
    address token0;
    address token1;
    uint32 index;
    uint8 feeProtocol;
    int24 tickLower;
    int24 tickUpper;
    int24 tick;
    uint160 sqrtPriceX96;
}
function getAllPools() external view returns (PoolInfo[] memory poolsInfo);

The information for each pool includes:

  • the symbol and number of token pairs;
  • rates;
  • price range;
  • the current price;
  • the total liquidity of the three intervals.

In addition, there is an operation to add a pool. If you find that there is no corresponding pool when adding a position, you need to create a pool first.

Parameters include:

  • address and number of token0;
  • address and number of token1;
  • rate (percentage);
  • price range;
  • the current price.

The number of token0 not being 0 or the number of token1 not being 0 means that the initial fluidity is added.

The interface is defined as follows: 

struct CreateAndInitializeParams {
    address token0;
    address token1;
    uint24 fee;
    int24 tickLower;
    int24 tickUpper;
    uint160 sqrtPriceX96;
}

function createAndInitializePoolIfNecessary(
    CreateAndInitializeParams calldata params
) external payable returns (address pool);

PoolManager directly inherited. Factory (The factory contract of the trading pool), rather than being called by a contract call Factory , all trading pools need to be created through PoolManager . You can understand PoolManager it's an enhanced version. Factory contract.

The complete interface is in IPoolManager in.

PositionManager

PositionManager.sol corresponding to the Position page, let's first look at what functions the Position page has.

The first is to show the position created by the current address, corresponding to the front page as follows:

in our design PositionManager it is not necessary. Because in theory, LP can be called directly. Pool Contracts are used to manage positions, and DApp provides a back-end interface to get LP position information. But for the curriculum needs, we designed an ERC721 compliant PositionManager contracts to manage positions in LP. You can understand PositionManager it's an agent, an intermediary, helping LP manage positions. You can also call directly Pool contracts to inject liquidity, but this position will not be PositionManager perceived. 

import "@openzeppelin/contracts/token/ERC721/IERC721.sol";

interface IPositionManager is IERC721 {
    // 相关接口
}

PositionManager the contract is an ERC721 contract, LP can pass the id of NFT (corresponding to our definition positionId ) to obtain information on the positions he created, defining getPositionInfo method, the interface is defined as follows: 

struct PositionInfo {
    address owner;
    address token0;
    address token1;
    uint32 index;
    uint24 fee;
    uint128 liquidity;
    int24 tickLower;
    int24 tickUpper;
    uint256 tokensOwed0;
    uint256 tokensOwed1;
}

function getPositionInfo(
    uint256 positionId
) external view returns (PositionInfo memory positionInfo);

the information for each position includes:

  • the symbol and number of token pairs (the number here is the number of two tokens owned by the position);
  • rates;
  • price range;
  • added liquidity;
  • the fee charged for the two tokens.

Also we don't define the interface to get all positions separately, because the contract itself is an ERC721 contract, so we can pass something like ZAN Advanced API such a service to get all the positions of a user ( zan_getNFTsByOwner ).

Next, let's look at how to inject liquidity (add positions). There is an operation to add positions in the upper right corner of the UI design. Click to pop up the following page:

it is very similar to adding a pool, except that the price range and current price cannot be filled in. Parameters include:

  • address and number of token0;
  • address and number of token1;
  • rates (percent).

Definition mint method, the interface is defined as follows: 

struct MintParams {
    address token0;
    address token1;
    uint32 index;
    uint256 amount0Desired;
    uint256 amount1Desired;
    address recipient;
    uint256 deadline;
}

function mint(
    MintParams calldata params
)
    external
    payable
    returns (
        uint256 positionId,
        uint128 liquidity,
        uint256 amount0,
        uint256 amount1
    );

it is worth noting that the selected token0 and token1 are two drop-down boxes, and the rate will be displayed automatically. To implement this logic, we need to rely on PoolManager.sol the interfaces of are:

  • getPairs : Get all trading pairs for LP selection.
  • getAllPools: Get all the trading pool information, select the trading pair, you can get all the trading pool through this method, and filter according to the trading peer information selected by LP.

getPairs not defined in the above PositionManager, the interface definition is as follows:

function getPairs() external view returns (Pair[] memory);

there are also two buttons for the information on each line of position, which are burn and collect , representing the liquidity of the destroyed position, and the withdrawal of the full commission, respectively.

The interface is defined as follows: 

function burn(
    uint256 positionId
) external returns (uint256 amount0, uint256 amount1);

function collect(
    uint256 positionId,
    address recipient
) external returns (uint256 amount0, uint256 amount1);

the complete interface is in IPositionManager in.

SwapRouter

SwapRouter.sol corresponding to the Swap page, let's first look at what functions the Swap page has.

The corresponding front page is as follows:

first of all, token0 and token1 are also two drop-down boxes, which are consistent with the add position page, but will not show the rate, so there will be multiple pools after the user selects the trading pair.

DApp needs to analyze the optimal Swap path, which is used here. indexPath And sqrtPriceLimitX96 two parameters. indexPath the type uint32[] , indicating the serial number of the selected pool; sqrtPriceLimitX96 the type uint160 , which represents the limit price for each pool trade. The logic is as follows:

  • first from indexPath take out a index confirm the pool;
  • Swap in the pool, if the user's requirements are met (I. E., there are no remaining amount ) ends;
  • if touched sqrtPriceLimitX96 price limit, and Swap has not yet met the user's requirements (I. E., the remaining amount ), then deduct the transaction. amount back to the first step. If it is already the last pool, it will end with a partial deal.

Then there is the estimation logic. There are two methods:

  • quoteExactInput : The user inputs the number of token0 in the input box, and the output box automatically displays the number of token1;
  • quoteExactOutput : The number of token1 input in the user output box, and the number of token0 automatically displayed in the input box;

the interface is defined as follows: 

struct QuoteExactInputParams {
    address tokenIn;
    address tokenOut;
    uint32[] indexPath;
    uint256 amountIn;
    uint160 sqrtPriceLimitX96;
}

function quoteExactInput(
    QuoteExactInputParams memory params
) external returns (uint256 amountOut);

struct QuoteExactOutputParams {
    address tokenIn;
    address tokenOut;
    uint32[] indexPath;
    uint256 amount;
    uint160 sqrtPriceLimitX96;
}

function quoteExactOutput(
    QuoteExactOutputParams memory params
) external returns (uint256 amountIn);

finally, when the user clicks the Swap button, there are two ways to estimate the logical correspondence exactInput and exactOutput .

The interface is defined as follows: 

struct ExactInputParams {
    address tokenIn;
    address tokenOut;
    uint32[] indexPath;
    address recipient;
    uint256 deadline;
    uint256 amountIn;
    uint256 amountOutMinimum;
    uint160 sqrtPriceLimitX96;
}

function exactInput(
    ExactInputParams calldata params
) external payable returns (uint256 amountOut);

struct ExactOutputParams {
    address tokenIn;
    address tokenOut;
    uint32[] indexPath;
    address recipient;
    uint256 deadline;
    uint256 amountOut;
    uint256 amountInMaximum;
    uint160 sqrtPriceLimitX96;
}

function exactOutput(
    ExactOutputParams calldata params
) external payable returns (uint256 amountIn);

theoretically, the user can also call directly Pool to trade. But because there will be many trading pools for the same trading pair, we designed to make it easier for users to trade. SwapRouter contract. DApp selects the optimal trading pool by analyzing the trading pool, and then SwapRouter contract to call Pool contracts to complete transactions in different trading pools at once. Similar contracts are designed in Uniswap, except that Uniswap is used to select different trading pairs, and Uniswap supports cross-trading pairs, such as users who want to trade. A And C , but there is no direct trading pair, then Uniswap will choose. A and B and B and C two trading pairs to complete the transaction. In this course, in order to simplify the course, we do not do this design. But because we define different price ranges on a trading pool, we also design SwapRouter contracts to select trading pools with different price ranges.

The complete interface is in ISwapRouter in.

Factory

Factory.sol is the Pool's factory contract, which is relatively simple and defines getPool and createPool methods, and PoolCreated event.

The interface is defined as follows:

event PoolCreated(
    address indexed token0,
    address indexed token1,
    uint32 indexed index,
    address pool
);

function getPool(
    address token0,
    address token1,
    uint32 index
) external view returns (address pool);

function createPool(
    address token0,
    address token1,
    int24 tickLower,
    int24 tickUpper,
    uint24 fee
) external returns (address pool);

In particular, with reference to Uniswap, the factory contract is also designed to temporarily store the transaction pool contract initialization parameters, thus completing the transfer of parameters. Add the following method definitions: 

function parameters()
    external
    view
    returns (
        address factory,
        address token0,
        address token1,
        int24 tickLower,
        int24 tickUpper,
        uint24 fee
    );

the complete interface is in IFactory in.

Pool

Pool.sol is the lowest level of contracts, realized WTFSwap the Core Logic.

The first is some non-variable read methods, as follows: 

function factory() external view returns (address);

function token0() external view returns (address);

function token1() external view returns (address);

function fee() external view returns (uint24);

function tickLower() external view returns (int24);

function tickUpper() external view returns (int24);

then there is the reading of the current state variables, I .e. current price, tick, liquidity, and the liquidity and number of tokens in different position positions, as follows: 

function sqrtPriceX96() external view returns (uint160);

function tick() external view returns (int24);

function liquidity() external view returns (uint128);

we also define the initialization method, which, in contrast to Uniswap, specifies the price range when we initialize, as follows: 

function initialize(
    uint160 sqrtPriceX96
) external;

finally, there is the underlying implementation of the upper contract, which is mint , collect , burn , swap methods as well as events.

The interface is defined as follows: 

event Mint(
    address sender,
    address indexed owner,
    uint128 amount,
    uint256 amount0,
    uint256 amount1
);

function mint(
    address recipient,
    uint128 amount,
    bytes calldata data
) external returns (uint256 amount0, uint256 amount1);

event Collect(
    address indexed owner,
    address recipient,
    uint128 amount0,
    uint128 amount1
);

function collect(
    address recipient
) external returns (uint128 amount0, uint128 amount1);

event Burn(
    address indexed owner,
    uint128 amount,
    uint256 amount0,
    uint256 amount1
);

function burn(
    uint128 amount
) external returns (uint256 amount0, uint256 amount1);

event Swap(
    address indexed sender,
    address indexed recipient,
    int256 amount0,
    int256 amount1,
    uint160 sqrtPriceX96,
    uint128 liquidity,
    int24 tick
);

function swap(
    address recipient,
    bool zeroForOne,
    int256 amountSpecified,
    uint160 sqrtPriceLimitX96,
    bytes calldata data
) external returns (int256 amount0, int256 amount1);

in particular, you also need to define two callback interfaces, one for the pool contract. mint and swap of the callback. The interface is defined as follows: 

interface IMintCallback {
    function mintCallback(
        uint256 amount0Owed,
        uint256 amount1Owed,
        bytes calldata data
    ) external;
}

interface ISwapCallback {
    function swapCallback(
        int256 amount0Delta,
        int256 amount1Delta,
        bytes calldata data
    ) external;
}

the complete interface is in IPool.sol in.