Pool contract LP related interface development

Author of this section: @Fish

this will be achieved. Pool the contract involves interfaces related to LP (liquidity provider), including adding liquidity, removing liquidity, withdrawing tokens, etc.

Contract Introduction

Pool the contract is the most complex contract in the tutorial, and it is determined by Factory contract creation, there may be multiple Pool contract. In our course design, each token pair may have multiple Pool contract, each Pool A contract is a trading pool, and each trading pool has its own price limit and fee.

This is different from Uniswap V2 and Uniswap V3. Uniswap's trading pool only has the transaction pair + fee attribute, while our trading pool also has the price upper and lower limit attribute. Our Code refers more to Uniswap V3, so this actually makes our development easier, because we only need to consider liquidity management and trading within this fixed range, while in Uniswap V3, you need to manage liquidity in different price ranges in a trading pool. In the later implementation, you will find that we refer heavily to the code of Uniswap V3, but in fact we only use a small part of its logic, which makes our course easier to learn.

The trading pool contract code for Uniswap V3 is in UniswapV3Pool.sol you can refer to this code to better understand our code, or refer to our course to learn the code of Uniswap V3. Of course, the code for Uniswap V2 UniswapV2Pair.sol you can also refer.

In this lecture, we will first implement the LP-related interface, and the transaction interface will be implemented in the next lecture.

Contract Development

the complete code is in demo-contract/contracts/wtfswap/Pool.sol in.

1. Add liquidity

adding liquidity is a call mint method, in our design, mint the method is defined as follows:

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

we pass in to add liquidity amount , and data , this data it is used to pass parameters in callback functions, which will be discussed later. recipient You can specify who the interest in liquidity is given. The thing to note here is that amount it is liquidity, not mint tokens. As for how liquidity is calculated, we are in PositionManager in this lecture, we will not start in detail. But in our implementation of this talk, we need to be based on the incoming amount calculated amount0 and amount1 and returns both values. amount0 and amount1 the number of two tokens, respectively, also need to be in mint the callback function we defined is called in the method. mintCallback , and modifications Pool some state in the contract.

First, we refer code for Uniswap V3 to write a _Modifyposition method, which is a priviate Function, which can only be called Inside the contract, in which the liquidity of the trading pool as a whole is modified. liquidity and calculate the return amount0 and amount1 .

First we need to define Position structure, used to record LP liquidity information:

struct Position {
    // 该 Position 拥有的流动性
    uint128 liquidity;
    // 可提取的 token0 数量
    uint128 tokensOwed0;
    // 可提取的 token1 数量
    uint128 tokensOwed1;
}
// 用一个 mapping 来存放所有 Position 的信息
mapping(address => Position) public positions;

and then implement _Modifyposition method is used in mint , burn modify positions information in:

function _modifyPosition(
    ModifyPositionParams memory params
) private returns (int256 amount0, int256 amount1) {
    // 通过新增的流动性计算 amount0 和 amount1
    // 参考 UniswapV3 的代码

    amount0 = SqrtPriceMath.getAmount0Delta(
        sqrtPriceX96,
        TickMath.getSqrtPriceAtTick(tickUpper),
        params.liquidityDelta
    );

    amount1 = SqrtPriceMath.getAmount1Delta(
        TickMath.getSqrtPriceAtTick(tickLower),
        sqrtPriceX96,
        params.liquidityDelta
    );
    Position storage position = positions[params.owner];

    // 修改 liquidity
    liquidity = LiquidityMath.addDelta(liquidity, params.liquidityDelta);
    position.liquidity = LiquidityMath.addDelta(
        position.liquidity,
        params.liquidityDelta
    );
}

function mint(
    address recipient,
    uint128 amount,
    bytes calldata data
) external override returns (uint256 amount0, uint256 amount1) {
    require(amount > 0, "Mint amount must be greater than 0");
    // 基于 amount 计算出当前需要多少 amount0 和 amount1
    (int256 amount0Int, int256 amount1Int) = _modifyPosition(
        ModifyPositionParams({
            owner: recipient,
            liquidityDelta: int128(amount)
        })
    );
}

compared to Uniswap V3 _Modifyposition our code is much simpler. The entire trading pool is fixed within a price range, and mint can only be mint within that price range. So we only need to take part of the code in Uniswap V3. in Uniswap V3, the upper and lower limits for Calculating liquidity are dynamically passed in by parameters. params.tickLower and params.tickUpper, and our code is fixed. tickLower and tickUpper .

In addition, it will be used in the calculation process. SqrtPriceMath library, this library is a tool library in Uniswap V3, also need you to introduce in our contract code, change the library also depends on several other libraries, also need to be introduced together, which FullMath.sol and TickMath.sol because dependent on solidity <0.8.0; version, but our course uses 0.8.0 + so we use code for Uniswap V4 , Uniswap V4 has not been officially released, but some of its basic libraries have already given support for the 0.8 version of solidity, so we can use it directly. 0.8 version of solidity has some differences from 0.7 in some mathematical operations, especially in the handling of overflow, which will not be expanded here.

Of course, you can also directly copy what the course provides. Code we don't have to modify it ourselves. We have already made these changes in our code. You can directly introduce the following code:

import "./libraries/SqrtPriceMath.sol";
import "./libraries/TickMath.sol";
import "./libraries/LiquidityMath.sol";
import "./libraries/LowGasSafeMath.sol";
import "./libraries/TransferHelper.sol";

Among them LowGasSafeMath is a library we will use below, it is to avoid errors caused by overflow in the calculation process (in fact, after the 0.8 of Solidity, overflow and underflow checks will be turned on by default, which is not necessary, you can view this article learn more), you need to add the following to the contract to use it:

contract Pool is IPool {
+  using LowGasSafeMath for uint256;

about using the keyword syntax, you can view. The Library Contract this article knows more.

amount0 and amount1 after the calculation is completed, you need to call mintCallback callback method, LP needs to transfer the corresponding token to Pool contract, so call Pool contract mint the method also needs to be a contract and defined in the contract. mintCallback methods, we will be in the future PositionManager Implement the relevant logic in the contract.

Complete mint the method code is as follows:

function mint(
    address recipient,
    uint128 amount,
    bytes calldata data
) external override returns (uint256 amount0, uint256 amount1) {
    require(amount > 0, "Mint amount must be greater than 0");
    // 基于 amount 计算出当前需要多少 amount0 和 amount1
    (int256 amount0Int, int256 amount1Int) = _modifyPosition(
        ModifyPositionParams({
            owner: recipient,
            liquidityDelta: int128(amount)
        })
    );
    amount0 = uint256(amount0Int);
    amount1 = uint256(amount1Int);

    uint256 balance0Before;
    uint256 balance1Before;
    if (amount0 > 0) balance0Before = balance0();
    if (amount1 > 0) balance1Before = balance1();
    // 回调 mintCallback
    IMintCallback(msg.sender).mintCallback(amount0, amount1, data);

    if (amount0 > 0)
        require(balance0Before.add(amount0) <= balance0(), "M0");
    if (amount1 > 0)
        require(balance1Before.add(amount1) <= balance1(), "M1");

    emit Mint(msg.sender, recipient, amount, amount0, amount1);
}

we need to check whether the corresponding token has arrived at the end and trigger a Mint event.

It should be noted here that we also need to add balance0 and balance1 two methods, which are also reference code for Uniswap V3 however, we have made a little adjustment to the definition in V3 IERC20Minimal use instead @openzeppelin/contracts/token/ERC20/IERC20.sol and, of course, real projects are used in IERC20Minimal it will reduce the size of the contract to some extent, but we use it directly in our course. @openzeppelin the next contract will be simpler and will allow everyone to understand it. OpenZeppelin related libraries.

The specific code is as follows:

/// @dev Get the pool's balance of token0
/// @dev This function is gas optimized to avoid a redundant extcodesize check in addition to the returndatasize
/// check
function balance0() private view returns (uint256) {
    (bool success, bytes memory data) = token0.staticcall(
        abi.encodeWithSelector(IERC20.balanceOf.selector, address(this))
    );
    require(success && data.length >= 32);
    return abi.decode(data, (uint256));
}

/// @dev Get the pool's balance of token1
/// @dev This function is gas optimized to avoid a redundant extcodesize check in addition to the returndatasize
/// check
function balance1() private view returns (uint256) {
    (bool success, bytes memory data) = token1.staticcall(
        abi.encodeWithSelector(IERC20.balanceOf.selector, address(this))
    );
    require(success && data.length >= 32);
    return abi.decode(data, (uint256));
}

In this way, our mint the method is complete.

2. Remove liquidity

next, let's move on to what we defined earlier. burn methods:

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

and mint similarly, it also needs to pass in a amount , but it does not need to have a callback, and the withdrawal of tokens is put. collect operated in. In burn in the method, we just remove the liquidity and calculate the value to be returned to LP. amount0 and amount1 , recorded in the contract state.

The complete code is as follows, we will continue to use the above _Modifyposition method, except that the parameter in liquidityDelta becomes negative:

function burn(
    uint128 amount
) external override returns (uint256 amount0, uint256 amount1) {
    require(amount > 0, "Burn amount must be greater than 0");
    require(
        amount <= positions[msg.sender].liquidity,
        "Burn amount exceeds liquidity"
    );
    // 修改 positions 中的信息
    (int256 amount0Int, int256 amount1Int) = _modifyPosition(
        ModifyPositionParams({
            owner: msg.sender,
            liquidityDelta: -int128(amount)
        })
    );
    // 获取燃烧后的 amount0 和 amount1
    amount0 = uint256(-amount0Int);
    amount1 = uint256(-amount1Int);

    if (amount0 > 0 || amount1 > 0) {
        (
            positions[msg.sender].tokensOwed0,
            positions[msg.sender].tokensOwed1
        ) = (
            positions[msg.sender].tokensOwed0 + uint128(amount0),
            positions[msg.sender].tokensOwed1 + uint128(amount1)
        );
    }

    emit Burn(msg.sender, amount, amount0, amount1);
}

we are in Position is defined in tokensOwed0 And tokensOwed1 , used to record the number of tokens that LP can withdraw, which is in. collect extracted from, then let's continue to implement collect methods.

3. Withdrawal of tokens

extracting tokens is a call collect method, we define it as follows:

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

and Uniswap V3 code the logic is similar, the complete code is as follows:

function collect(
    address recipient,
    uint128 amount0Requested,
    uint128 amount1Requested
) external override returns (uint128 amount0, uint128 amount1) {
    // 获取当前用户的 position
    Position storage position = positions[msg.sender];

    // 把钱退给用户 recipient
    amount0 = amount0Requested > position.tokensOwed0
        ? position.tokensOwed0
        : amount0Requested;
    amount1 = amount1Requested > position.tokensOwed1
        ? position.tokensOwed1
        : amount1Requested;

    if (amount0 > 0) {
        position.tokensOwed0 -= amount0;
        TransferHelper.safeTransfer(token0, recipient, amount0);
    }
    if (amount1 > 0) {
        position.tokensOwed1 -= amount1;
        TransferHelper.safeTransfer(token1, recipient, amount1);
    }

    emit Collect(msg.sender, recipient, amount0, amount1);
}

in the code, we introduce the Uniswap V3 code. TransferHelper the Library makes the transfer and sends the token to the incoming recipient address. At this point, the basic logic is completed.

Contract Testing

next, we add some unit tests. Because creating Pool we need to correspond to a trading pair, so we first create a meeting. ERC20 canonical token contracts. About ERC20 Specification, you can refer this article .

We are in demo-contract/contracts/wtfswap create a new one test-contracts/TestToken.sol file, which reads as follows:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract TestToken is ERC20 {
    uint256 private _nextTokenId = 0;

    constructor() ERC20("TestToken", "TK") {}

    function mint(address recipient, uint256 quantity) public payable {
        _mint(recipient, quantity);
    }
}

you can refer to the specific contract code. Here. , this contract we implemented a token contract that can be minted at will for testing.

Next, we build a new demo-contract/test/wtfswap/Pool.test.js file, write test code:

import { loadFixture } from "@nomicfoundation/hardhat-toolbox-viem/network-helpers";
import { expect } from "chai";
import hre from "hardhat";
import { TickMath, encodeSqrtRatioX96 } from "@uniswap/v3-sdk";

describe("Pool", function () {
  async function deployFixture() {
    // 初始化一个池子，价格上限是 40000，下限是 1，初始化价格是 10000，费率是 0.3%
    const factory = await hre.viem.deployContract("Factory");
    const tokenA = await hre.viem.deployContract("TestToken");
    const tokenB = await hre.viem.deployContract("TestToken");
    const token0 = tokenA.address < tokenB.address ? tokenA : tokenB;
    const token1 = tokenA.address < tokenB.address ? tokenB : tokenA;
    const tickLower = TickMath.getTickAtSqrtRatio(encodeSqrtRatioX96(1, 1));
    const tickUpper = TickMath.getTickAtSqrtRatio(encodeSqrtRatioX96(40000, 1));
    // 以 1,000,000 为基底的手续费费率，Uniswap v3 前端界面支持四种手续费费率（0.01%，0.05%、0.30%、1.00%），对于一般的交易对推荐 0.30%，fee 取值即 3000；
    const fee = 3000;
    const publicClient = await hre.viem.getPublicClient();
    await factory.write.createPool([
      token0.address,
      token1.address,
      tickLower,
      tickUpper,
      fee,
    ]);
    const createEvents = await factory.getEvents.PoolCreated();
    const poolAddress: `0x${string}` = createEvents[0].args.pool || "0x";
    const pool = await hre.viem.getContractAt("Pool" as string, poolAddress);

    // 计算一个初始化的价格，按照 1 个 token0 换 10000 个 token1 来算，其实就是 10000
    const sqrtPriceX96 = encodeSqrtRatioX96(10000, 1);
    await pool.write.initialize([sqrtPriceX96]);

    return {
      token0,
      token1,
      factory,
      pool,
      publicClient,
      tickLower,
      tickUpper,
      fee,
      sqrtPriceX96: BigInt(sqrtPriceX96.toString()),
    };
  }

  it("pool info", async function () {
    const { pool, token0, token1, tickLower, tickUpper, fee, sqrtPriceX96 } =
      await loadFixture(deployFixture);

    expect(((await pool.read.token0()) as string).toLocaleLowerCase()).to.equal(
      token0.address
    );
    expect(((await pool.read.token1()) as string).toLocaleLowerCase()).to.equal(
      token1.address
    );
    expect(await pool.read.tickLower()).to.equal(tickLower);
    expect(await pool.read.tickUpper()).to.equal(tickUpper);
    expect(await pool.read.fee()).to.equal(fee);
    expect(await pool.read.sqrtPriceX96()).to.equal(sqrtPriceX96);
  });
});

we deployed a Factory and two TestToken token contract and then created a Pool the contract, initialized the price, and then tested it. Pool basic information about the contract. In addition, we need to introduce @uniswap/v3-sdk for sqrtPriceX96 The code is as follows:

you also need to use it in your project. npm install @uniswap/v3-sdk install the required @uniswap/v3-sdk dependent. @uniswap/v3-sdk it is a Typescript SDK of Uniswap, which contains some basic computing logic. Besides being used in single test, it will also be used in our subsequent DApp front-end development.

Next, we can continue to write more test samples, for example, we add the following sample to test mint liquidity, and then check whether the token transfer is correct.

it("mint and burn and collect", async function () {
  const { pool, token0, token1, price } = await loadFixture(deployFixture);
  const testLP = await hre.viem.deployContract("TestLP");

  const initBalanceValue = 1000n * 10n ** 18n;
  await token0.write.mint([testLP.address, initBalanceValue]);
  await token1.write.mint([testLP.address, initBalanceValue]);

  await testLP.write.mint([
    testLP.address,
    20000000n,
    pool.address,
    token0.address,
    token1.address,
  ]);

  expect(await token0.read.balanceOf([pool.address])).to.equal(
    initBalanceValue - (await token0.read.balanceOf([testLP.address]))
  );
  expect(await token1.read.balanceOf([pool.address])).to.equal(
    initBalanceValue - (await token1.read.balanceOf([testLP.address]))
  );

  const position = await pool.read.positions([testLP.address]);
  expect(position).to.deep.equal([20000000n, 0n, 0n]);
  expect(await pool.read.liquidity()).to.equal(20000000n);
});

Because Pool the contract needs to handle the transfer of tokens through a callback function, so we need to add a new test. TestLP contract, this contract needs to be implemented IMintCallback interface, the specific code is as follows:

// SPDX-License-Identifier: MIT
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "../interfaces/IPool.sol";
import "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract TestLP is IMintCallback {
    function sortToken(
        address tokenA,
        address tokenB
    ) private pure returns (address, address) {
        return tokenA < tokenB ? (tokenA, tokenB) : (tokenB, tokenA);
    }

    function mint(
        address recipient,
        uint128 amount,
        address pool,
        address tokenA,
        address tokenB
    ) external returns (uint256 amount0, uint256 amount1) {
        (address token0, address token1) = sortToken(tokenA, tokenB);

        (amount0, amount1) = IPool(pool).mint(
            recipient,
            amount,
            abi.encode(token0, token1)
        );
    }

    function burn(
        uint128 amount,
        address pool
    ) external returns (uint256 amount0, uint256 amount1) {
        (amount0, amount1) = IPool(pool).burn(amount);
    }

    function collect(
        address recipient,
        address pool
    ) external returns (uint256 amount0, uint256 amount1) {
        (, , , uint128 tokensOwed0, uint128 tokensOwed1) = IPool(pool)
            .getPosition(address(this));
        (amount0, amount1) = IPool(pool).collect(
            recipient,
            tokensOwed0,
            tokensOwed1
        );
    }

    function mintCallback(
        uint256 amount0Owed,
        uint256 amount1Owed,
        bytes calldata data
    ) external override {
        // transfer token
        (address token0, address token1) = abi.decode(data, (address, address));
        if (amount0Owed > 0) {
            IERC20(token0).transfer(msg.sender, amount0Owed);
        }
        if (amount1Owed > 0) {
            IERC20(token1).transfer(msg.sender, amount1Owed);
        }
    }
}

you also need to note that because the calculation of liquidity to tokens is based on a relatively complex formula, there is also the problem of rounding when calculating. In our single test, we simply test some basic logic. In fact, you need more test cases to cover more situations and test whether the logic of specific mathematical operations is correct.

More test code you can indemo-contract/test/wtfswap/Pool.ts find it. At this point, we are done Pool in the contract LP related interface development, we will add in the next lecture swap interface, and add the logic related to the handling fee to complete the entire Pool development of contracts.