UniswapV2周邊合約學習(三)-- UniswapV2Router02.sol(下)

2020-10-20 12:00:02

記得朋友圈看到過一句話,如果Defi是以太坊的皇冠,那麼Uniswap就是這頂皇冠中的明珠。Uniswap目前已經是V2版本,相對V1,它的功能更加全面優化,然而其合約原始碼卻並不複雜。本文為個人學習UniswapV2原始碼的系列記錄文章。

在序列文章的上一篇我們學習了UniswapV2Router02.sol合約原始碼的上半部分(流動性供給部分),這次我們來學習下半部分,也就是資產交易部分。

建議讀者在開始學習之前閱讀我的另一篇文章:UniswapV2介紹 來對UniswapV2的整體機制有個大致瞭解;當然也建議閱讀前面的系列文章,特別是核心合約部分,這樣更有助於理解原始碼。

本文接下來內容中,會交替使用資產和ERC20代幣這兩個術語,在涉及到交易對時,它們基本上是等同的。

一、資產交易函數原始碼學習

  1. _swap函數。該函數是一個internal函數,它也是其它資產交易介面的核心,我們先看其原始碼:

    // **** SWAP ****
    // requires the initial amount to have already been sent to the first pair
    function _swap(uint[] memory amounts, address[] memory path, address _to) internal virtual {
        for (uint i; i < path.length - 1; i++) {
            (address input, address output) = (path[i], path[i + 1]);
            (address token0,) = UniswapV2Library.sortTokens(input, output);
            uint amountOut = amounts[i + 1];
            (uint amount0Out, uint amount1Out) = input == token0 ? (uint(0), amountOut) : (amountOut, uint(0));
            address to = i < path.length - 2 ? UniswapV2Library.pairFor(factory, output, path[i + 2]) : _to;
            IUniswapV2Pair(UniswapV2Library.pairFor(factory, input, output)).swap(
                amount0Out, amount1Out, to, new bytes(0)
            );
        }
    }
    

    它把交易資產的核心邏輯抽象出來獨立為一個內部函數,方便各個資產交易外部介面呼叫(程式碼複用),此函數為內部函數,使用者無法直接呼叫。從註釋中我們可以知道,需要事先將初始數量的代幣傳送到第一個交易對( 這是UniswapV2的先轉移後交易特性決定的)。

    可以看到它有兩個輸入引數 amountspath,分別為uint及地址陣列,那麼它們代表什麼含義呢?

    在系列文章的周邊合約工具庫學習時已經提到,UniswapV2支援交易鏈模式。也就假定有A/B 和B/C 這兩個交易對(但不是存在A/C交易對),我們可以在一個交易內先將A總換成B,然後再將B兌換成C,這樣就相當於A兌換成了C。整個交換流程為:A => B => C ,順序涉及的三種代幣為A,B,C。path顧名思義就指這條路徑的,它的內容是交易鏈中依次出現的各代幣地址。因此,path的內容為[addressA,addressB,addressC]amounts代表什麼呢,它代表整個交易過程中交易鏈依次涉及的代幣數量。在A => B => C 交易鏈中,amounts的內容為:[amountA,amountB,amountC]。因為初始資產只能賣出,所以amounts[0]代表賣出的初始資產數量,在本例中為amountA。而最終得到的資產只能買進,所以amounts陣列的最後一個元素代表買進的最終資產數量,例如amountC。陣列中間的元素代表涉及到的中間代幣的數量,例如amountB,它們是前一個交易對(A/B交易對)的買進值,同時也是下一個交易對(B/C交易對)的賣出值。

    下面的解釋仍然以 A => B => C 交易鏈為例(假定當前沒有直接A到C的交易對)。

    函數體是一個for迴圈,雖然我們的path長度為3,但是交易對數量只有2個,為什麼呢。其實很簡單,大家想一想五線譜中的間與線的數量關係是什麼?是五線四間,而這裡是三個地址兩個交易對。這裡面的關係圖是不是一樣的? 😉😉😉😊😊😊。所以迴圈的判定條件不是通常的i < path.length,而要少一次,為i < path.length - 1

    • 迴圈內的第一行用來獲取當前交易對中的兩種代幣地址。以i = 0來講,input就是A,output就是B。

    • 迴圈內的第二行用來獲取較小的代幣地址,因為交易對內的代幣地址及對應的代幣數量是排序過的(按地址大小從小到大排列)。

    • 迴圈內的第三行用來從amounts中獲取當前交易對的買進值(同時也是下一交易對的賣出值,如果還有交易對的話)。

    • 迴圈內的第四行用來判斷如果input(A)是較小值(交易對排過序後的較小地址為A),那麼當前交易對買進的兩種代幣數量分別為(0,amountOut),也就是賣出A,得到amountOut數量的B;如果output(B)是較小值(交易對排過序後的較小地址為B),當前交易對買進的兩種代幣數量分別為(amountOut,0),同樣也為賣出A,得到amountOut數量的B。

      這麼做的原因是在UniswapV2中,交易對合約的swap函數的前兩個引數對應的代幣地址是從小到大排序的。詳情見核心合約學習三中對swap函數的額外說明。

    • 迴圈內的第五行用來計算當前交易對的接收地址。因為UniswapV2是一個交易代幣先行轉入系統,所以下一個交易對就直接是前一個交易對的接收地址了(如果還有下一個交易對)。這裡如果i迴圈到最後一次i == path.length - 2,那麼後面沒有交易對了,其接收地址為使用者指定的接收者地址;如果未到最後一次(後面還有交易對),那麼接收地址就是通過工具庫計算的下一個交易對的地址。

    • 迴圈內的最後一行程式碼先是計算了當前交易對的地址,然後呼叫了該地址交易對合約的swap介面,將指定買進的代幣數量和接收地址及空負載(不執行回撥)作為引數傳給該函數。

    理解了_swap函數這個核心,再學習資產交易部分的其它外部介面(被使用者直接呼叫的函數)就很簡單了,因為它們基本上都是對本函數的呼叫。

  2. swapExactTokensForTokens函數。從函數名稱可以看出它是指定賣出固定數量的某種資產,買進另一種資產,該值由計算得來,同時支援交易對鏈(也就是上面講到的 A => B => C模式)。函數程式碼為:

    function swapExactTokensForTokens(
        uint amountIn,
        uint amountOutMin,
        address[] calldata path,
        address to,
        uint deadline
    ) external virtual override ensure(deadline) returns (uint[] memory amounts) {
        amounts = UniswapV2Library.getAmountsOut(factory, amountIn, path);
        require(amounts[amounts.length - 1] >= amountOutMin, 'UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT');
        TransferHelper.safeTransferFrom(
            path[0], msg.sender, UniswapV2Library.pairFor(factory, path[0], path[1]), amounts[0]
        );
        _swap(amounts, path, to);
    }
    

    其引數分別為賣出的初始資產數量,買進的另一種資產的最小值,交易對鏈,接收者地址和最遲交易時間。返回值amounts的含義見_swap函數。

    • 函數程式碼的第一行用來計算當前該交易的amounts,注意它使用了自定義工具庫的getAmountsOut函數進行鏈上實時計算的,所以得出的值是準確的最新值。amounts[0]就是賣出的初始資產數量,也就是amountIn

    • 函數的第二行用來驗證最終買進的代幣數量不能小於使用者限定的最小值(防止價格波動較大,超出使用者的預期)。

    • 函數的第三行將擬賣出的初始資產轉移到第一個交易對中去,這正好映證了_swap函數的註釋,必須先轉移賣出資產到交易對。

    • 函數的第四行呼叫_swap函數進行交易操作。

    • 該函數將使用者欲賣出的資產轉移到了第一個交易對合約中,該資產是一種ERC20代幣,因此必須先得到使用者的授權。

      那麼這裡可不可以採用移除流動性的permit方式實行線下簽名訊息授權呢?答案是不能。因為採用這種方式授權時permit函數必須包含在ERC20代幣的合約程式碼中。在UniswapV2中,交易對本身就是ERC20代幣合約(本交易對流動性代幣的合約),它裡面是包含了permit函數的。但是交易對裡面的兩種資產(ERC20代幣)卻是外部的ERC20代幣合約,基本上沒有這個permit函數。

  3. swapTokensForExactTokens函數。從函數名稱可以看出它是指定交易時買進的資產數量,而賣出的資產數量則不指定,該值可以通過計算得來。結合函數2我們可以看到,函數介面可以分為指定買進(本函數)和指定賣出(函數2)兩種型別。那麼為什麼會有這兩種方式呢?因為Uniswap交易對採用了恆定乘積演演算法,它的價格是個曲線,不是線性的。因此指定買進和指定賣出計算的方式是不一樣的。於是這裡便有了這兩種介面(函數),然而它們的底層實現卻是統一的邏輯(_swap函數)。本函數程式碼為:

    function swapTokensForExactTokens(
        uint amountOut,
        uint amountInMax,
        address[] calldata path,
        address to,
        uint deadline
    ) external virtual override ensure(deadline) returns (uint[] memory amounts) {
        amounts = UniswapV2Library.getAmountsIn(factory, amountOut, path);
        require(amounts[0] <= amountInMax, 'UniswapV2Router: EXCESSIVE_INPUT_AMOUNT');
        TransferHelper.safeTransferFrom(
            path[0], msg.sender, UniswapV2Library.pairFor(factory, path[0], path[1]), amounts[0]
        );
        _swap(amounts, path, to);
    }
    

    函數的引數同函數2類似,只不過前兩個引數變成了擬買進的資產的數量和指定賣入資產的最大值(保護使用者,防止價格波動過大從而使賣出資產數量大大超過使用者預期)。返回值amounts的含義和前面一樣,這裡不再重複闡述了。

    • 函數的第一行呼叫庫函數來計算返回值amounts,因為它是同一個交易裡合約實時計算,所以不必擔心時效性問題,總是交易時的最新值。
    • 第二行驗證計算得到的賣出的初始資產數量要小於使用者限定的最大值。
    • 第三行將初始資產轉入第一個交易對中,轉移數量在第一行中計算得到。
    • 最後一行呼叫_swap函數進行交易操作。
    • 該函數也需要事先得到使用者授權以轉移初始賣出資產到交易對合約。
  4. swapExactETHForTokens函數。同swapExactTokensForTokens類似,只不過將初始賣出的Token換成了ETH。在上一篇文章學習流動性供給時已經介紹了ETH/WETH的相互兌換,這裡就不再闡述了。注意這裡函數引數不再有amountInMax,因為隨方法傳送的ETH數量就是使用者指定的最大值(WETH與ETH是等額1:1兌換的)。如果計算的結果超了則ETH會不足,丟擲錯誤重置整個交易。

    function swapExactETHForTokens(uint amountOutMin, address[] calldata path, address to, uint deadline)
        external
        virtual
        override
        payable
        ensure(deadline)
        returns (uint[] memory amounts)
    {
        require(path[0] == WETH, 'UniswapV2Router: INVALID_PATH');
        amounts = UniswapV2Library.getAmountsOut(factory, msg.value, path);
        require(amounts[amounts.length - 1] >= amountOutMin, 'UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT');
        IWETH(WETH).deposit{value: amounts[0]}();
        assert(IWETH(WETH).transfer(UniswapV2Library.pairFor(factory, path[0], path[1]), amounts[0]));
        _swap(amounts, path, to);
    }
    
    • 函數的第一行驗證第一個代幣地址必須為WETH地址。因為Uniswap交易對為ERC20/ERC20交易對,賣出ETH之前會自動轉換成為等額WETH(一種ERC20代幣)。第一個交易對實質上是WETH/ERC20交易對,需要在此賣出WETH,所以第一個地址(賣出的初始資產地址)必須為WETH。
    • 第二行用來計算amounts
    • 第三行,驗證最終買進的資產數量必須大於使用者指定的值,防止價格波動太大。
    • 第四行,將ETH兌換成WETH
    • 第五行,將WETH轉移到第一個交易對合約中。WETH代幣合約原始碼已經公開了,該合約的資產轉移函數transfer會返回一個bool值,所以不需要再呼叫自定義庫中的safeTransferFrom函數,直接使用assert函數來斷言該值必須為true即可。
    • 第六行呼叫_swap函數進行交易操作。
    • 本函數沒有轉移使用者的ERC20代幣,所以沒有授權操作。ETH兌換後的WETH就在本合約裡,是合約自己的資產,所以呼叫了WETH合約的transfer方法而不是transferFrom方法。
  5. swapTokensForExactETH函數。同swapTokensForExactTokens類似,只不過指定買進的不是Token(ERC20代幣),而是ETH。所以交易鏈的最後一個代幣地址必須為WETH,這樣才會買進WETH,然後再將它兌換成等額ETH。

    function swapTokensForExactETH(uint amountOut, uint amountInMax, address[] calldata path, address to, uint deadline)
        external
        virtual
        override
        ensure(deadline)
        returns (uint[] memory amounts)
    {
        require(path[path.length - 1] == WETH, 'UniswapV2Router: INVALID_PATH');
        amounts = UniswapV2Library.getAmountsIn(factory, amountOut, path);
        require(amounts[0] <= amountInMax, 'UniswapV2Router: EXCESSIVE_INPUT_AMOUNT');
        TransferHelper.safeTransferFrom(
            path[0], msg.sender, UniswapV2Library.pairFor(factory, path[0], path[1]), amounts[0]
        );
        _swap(amounts, path, address(this));
        IWETH(WETH).withdraw(amounts[amounts.length - 1]);
        TransferHelper.safeTransferETH(to, amounts[amounts.length - 1]);
    }
    
    • 函數的第一行驗證path中最後一個必須是WETH地址。
    • 第二行通過庫函數計算amounts,含義同上。
    • 第三行驗證計算得到的賣出資產數量必須小於使用者限定的最大值,價格保護。
    • 第四行,將欲賣出的資產轉移到第一個交易對中。
    • 第五行,呼叫_swap函數進行交易操作,注意接收者地址為本合約地址。因為從最後一個交易對得到的是WETH,並不是使用者想要的ETH。
    • 第六行,將本合約接收的WETH轉成ETH。
    • 第七行,將兌換好的ETH傳送給使用者指定的接收者to
    • 此函數在轉移賣出資產到第一個交易對時也需要事先授權。
  6. swapExactTokensForETH函數。同``swapExactTokensForTokens函數類似,只不過將最後獲取的ERC20代幣改成ETH了。因此,交易鏈的最後一個代幣地址必須為WETH,這樣才能賣進WETH然後再兌換成等額ETH。該函數同上一個函數swapTokensForExactETH`也類似,只不過一個是指定買進多少ETH,另一個是指定賣出多少資產。函數程式碼為:

    function swapExactTokensForETH(uint amountIn, uint amountOutMin, address[] calldata path, address to, uint deadline)
        external
        virtual
        override
        ensure(deadline)
        returns (uint[] memory amounts)
    {
        require(path[path.length - 1] == WETH, 'UniswapV2Router: INVALID_PATH');
        amounts = UniswapV2Library.getAmountsOut(factory, amountIn, path);
        require(amounts[amounts.length - 1] >= amountOutMin, 'UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT');
        TransferHelper.safeTransferFrom(
            path[0], msg.sender, UniswapV2Library.pairFor(factory, path[0], path[1]), amounts[0]
        );
        _swap(amounts, path, address(this));
        IWETH(WETH).withdraw(amounts[amounts.length - 1]);
        TransferHelper.safeTransferETH(to, amounts[amounts.length - 1]);
    }
    
    • 第一行驗證path中的最後一個代幣地址為WETH地址。
    • 第二行通過庫函數計算amounts,含義同上。
    • 第三行驗證交易鏈最終買進的的WETH數量(會兌換成等額ETH)不能小於使用者的限定值。
    • 第四行將使用者擬賣出的資產轉入到第一個交易對中。
    • 第七行呼叫_swap進行交易操作,注意接收者地址為本合約地址。因為最後從交易對得到的是WETH,並不是使用者想要的ETH。
    • 第八行,將本合約接收的WETH轉成ETH。
    • 第九行,將兌換好的ETH傳送給使用者指定的接收者to
    • 此函數在轉移賣出資產到第一個交易對時也需要事先授權。
  7. swapETHForExactTokens函數。賣出一定數量的ETH,買進指定數量的資產(TOKEN)。因為前面已經學習了好幾個類似的函數,再學習這個函數就很簡單了,這裡可以直接列出該函數的大致邏輯:

    要賣出ETH,所以第一個地址必定為WETH地址。因為是指定買進資產,肯定是利用工具庫函數反向遍歷來計算amounts。又因為第一個交易對是包含WETH的交易對,所以交易前必須將擬賣出的ETH兌換成WETH到本合約,然後將WETH從合約傳送到第一個交易對。接著會呼叫_swap函數進行交易,最後將多餘的ETH退回給呼叫者。大家可以對照一下該函數的程式碼看是不是這樣:

    function swapETHForExactTokens(uint amountOut, address[] calldata path, address to, uint deadline)
        external
        virtual
        override
        payable
        ensure(deadline)
        returns (uint[] memory amounts)
    {
        require(path[0] == WETH, 'UniswapV2Router: INVALID_PATH');
        amounts = UniswapV2Library.getAmountsIn(factory, amountOut, path);
        require(amounts[0] <= msg.value, 'UniswapV2Router: EXCESSIVE_INPUT_AMOUNT');
        IWETH(WETH).deposit{value: amounts[0]}();
        assert(IWETH(WETH).transfer(UniswapV2Library.pairFor(factory, path[0], path[1]), amounts[0]));
        _swap(amounts, path, to);
        // refund dust eth, if any
        if (msg.value > amounts[0]) TransferHelper.safeTransferETH(msg.sender, msg.value - amounts[0]);
    }
    

    通過對照可以發現猜想的邏輯只是少了一個驗證計算得到的賣出ETH數量。雖然不驗證時,如果amounts[0] > msg.value的話,在兌換WETH時會因為ETH不足而出錯重置。但萬一由於某種原因導致合約本身的ETH數量不為0,那麼此時就有可能通過了(相當於用合約已有的ETH幫你支付)。所以這裡還是需要驗證amounts[0] <= msg.value

  8. _swapSupportingFeeOnTransferTokens函數。這個函數從名稱上看,和_swap函數的區別是支援使用轉移的代幣支付手續費。在上一篇文章流動性供給時已經提到了使用轉移代幣支付手續費,筆者以此也不熟悉,現實中也未接觸或者使用過。但是可以簡單認為此類代幣(拓展的ERC20代幣)在資產轉移時可能會有損耗(部分資產轉移到一個協定地址來支付手續費),轉移的數量未必就是最後接收的數量。這是筆者的個人理解,未必正確,請大家見諒,也請大家留言指出使用轉移的代幣支付手續費的正確理解方式。此函數的程式碼為:

    // **** SWAP (supporting fee-on-transfer tokens) ****
    // requires the initial amount to have already been sent to the first pair
    function _swapSupportingFeeOnTransferTokens(address[] memory path, address _to) internal virtual {
        for (uint i; i < path.length - 1; i++) {
            (address input, address output) = (path[i], path[i + 1]);
            (address token0,) = UniswapV2Library.sortTokens(input, output);
            IUniswapV2Pair pair = IUniswapV2Pair(UniswapV2Library.pairFor(factory, input, output));
            uint amountInput;
            uint amountOutput;
            { // scope to avoid stack too deep errors
            (uint reserve0, uint reserve1,) = pair.getReserves();
            (uint reserveInput, uint reserveOutput) = input == token0 ? (reserve0, reserve1) : (reserve1, reserve0);
            amountInput = IERC20(input).balanceOf(address(pair)).sub(reserveInput);
            amountOutput = UniswapV2Library.getAmountOut(amountInput, reserveInput, reserveOutput);
            }
            (uint amount0Out, uint amount1Out) = input == token0 ? (uint(0), amountOutput) : (amountOutput, uint(0));
            address to = i < path.length - 2 ? UniswapV2Library.pairFor(factory, output, path[i + 2]) : _to;
            pair.swap(amount0Out, amount1Out, to, new bytes(0));
        }
    }
    

    相比_swap函數,從輸入引數來看,少了一個amounts,也就是涉及到的此類資產數量不能再由自定義的工具庫函數計算得到了。函數體內同樣是一個for迴圈,用來遍歷每個交易對進行交易。

    • 迴圈體內的第一行獲取當前交易對的兩種代幣地址。

    • 迴圈體內的第二行將這兩種代幣地址進行排序(排序的作用在_swap函數中已經講過)。

    • 迴圈體內的第三行用來得到當前交易對合約的範例。

    • 迴圈體內的第4-5行定義兩個臨時變數,一個代表賣出資產數量,一個代表買進資產的數量,使用InputOutput便於閱讀。

    • 迴圈體內的第6行和第11行是使用一對{}將變數進行scope,防止堆疊過深問題。相關的內容在序列文章核心合約學習(三)中已經介紹過了。

    • 迴圈體內的第7行用來獲取交易對資產池中兩種資產的值(用於恆定乘積計算的),注意這兩個值是按代幣地址(不是按代幣數量)從小到大排過序的。

    • 迴圈體內的第8行用來將交易對資產池中兩種資產的值和第一行中獲取的兩個代幣地址對應起來,並儲存在兩個帶有inputoutput的臨時reserve變數中,含義更加明顯,便於閱讀。

    • 迴圈體內的第9行用來計算當前交易對賣出資產的數量(交易對地址的代幣餘額減去交易對資產池中的值)

    • 迴圈體內的第10行根據恆定乘積演演算法來計算當前交易對買進的資產值 。為什麼要計算得買進的資產值呢?因為交易對合約的swap函數的輸入引數為買進的兩種代幣資產值而不是賣出的兩種代幣資產值。(這麼做個人認為第一方面是因為UniswapV2是先行轉入賣出資產系統,賣出的數量通過比較合約地址的代幣餘額與合約資產池中的相應值可以得到;第二方面是交易對合約的swap函數是個先借後還系統,函數引數為買進的資產數量可以方便的先借出相應資產)。

    • 迴圈體內的第12行將計算得到的買進資產值和零值按代幣地址從小到大的順序排序,這樣就會和交易對中swap函數的輸入引數順序保持一致。另一個為什麼是零值呢?很顯然,在交易鏈模式中,每個交易對只會賣出其中一種資產來買進另一種資產,而不會兩種資產全買進。

    • 迴圈體內的第13行是計算接收地址,計算過程同_swap函數。

    • 迴圈體內的最後一行呼叫交易對合約的swap函數進行實際交易。

    • 該函數和本合約的_swap主要區別就是交易鏈交易過程中轉移的資產數量不再提前使用工具庫函數計算好,而是在函數內部根據實際數值計算。

      因為資產在實際轉移過程可能會有部分損耗來支付交易費用,到底損耗多少是未知的,每種資產也是不一樣的,所以無法提前通過統一庫函數來計算得到。

      實際計算賣出資產的數量的方法為:在交易對中賣出的資產數量等於交易對合約地址的資產餘額減去交易對合約資產池中相應的數值,假設該方法叫M。

      買進的資產數量由恆定乘積演演算法算出,然而該值未必就是下一個交易對的資產賣出數量。因為此類資產在從當前交易對轉移到下一個交易對的過程中,可能存在損耗,所以下一個交易對的賣進資產也是通過方法M計算(在for的下一個迴圈裡)。

      剛才說了一大堆估計大家都有點暈😂😂😂😂,讓我們簡單一點吧🤩🤩🤩🤩:

      1. 在不支援代幣支付交易手續費的交易中,前一個交易對的買進資產數量就是後一個交易對的賣出資產數量(或者接收數量);第一個交易對的賣出資產數量就是使用者直接轉移的資產數量.
      2. 在支援代幣支付交易手續費的交易中,因為資產轉移過程中可能有損耗,所以每一個交易對的賣出資產數量必須由方法M計算得到,包含第一個交易對的賣出資產數量。
  9. swapExactTokensForTokensSupportingFeeOnTransferTokens。有了上面的_swapSupportingFeeOnTransferTokens函數做鋪墊,這個函數就比較好理解了。從名稱上看,它和swapExactTokensForTokens函數相同,只不過多了支援FeeOnTransferTokens。函數程式碼為:

    function swapExactTokensForTokensSupportingFeeOnTransferTokens(
        uint amountIn,
        uint amountOutMin,
        address[] calldata path,
        address to,
        uint deadline
    ) external virtual override ensure(deadline) {
        TransferHelper.safeTransferFrom(
            path[0], msg.sender, UniswapV2Library.pairFor(factory, path[0], path[1]), amountIn
        );
        uint balanceBefore = IERC20(path[path.length - 1]).balanceOf(to);
        _swapSupportingFeeOnTransferTokens(path, to);
        require(
            IERC20(path[path.length - 1]).balanceOf(to).sub(balanceBefore) >= amountOutMin,
            'UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT'
        );
    }
    
    • 第一行將使用者欲賣出的資產轉入到第一個交易對中。

    • 第四行用來記錄接收者地址在交易鏈最後一個代幣合約中的餘額。假定 A => B => C,就是C代幣的餘額。

    • 第五行呼叫可複用的內部函數(函數8)進行實際交易。

    • 最後的require函數用來驗證接收者買進的資產數量不能小於指定的最小值。

      前面已經講過,由於此類代幣在轉移過程中可能有損耗,所以最終接收者買進的資產數量不再等於恆定乘積公式計算出來的值,必須使用當前餘額減去交易前餘額來得到實際接收值。

    • 轉移賣出資產時需要提前授權,這個接下來不再重複提及了。

  10. swapExactETHForTokensSupportingFeeOnTransferTokens函數。同函數9類似,只不過將賣出的TOKEN改成了ETH。既然賣出ETH,它就又和函數swapExactETHForTokens類似。因此,邏輯上也很好理解,和普通TOKEN => TOKEN介面相比,多了一個計算並驗證買進的資產數量並和WETH/ETH的相互兌換。函數程式碼為:

    function swapExactETHForTokensSupportingFeeOnTransferTokens(
        uint amountOutMin,
        address[] calldata path,
        address to,
        uint deadline
    )
        external
        virtual
        override
        payable
        ensure(deadline)
    {
        require(path[0] == WETH, 'UniswapV2Router: INVALID_PATH');
        uint amountIn = msg.value;
        IWETH(WETH).deposit{value: amountIn}();
        assert(IWETH(WETH).transfer(UniswapV2Library.pairFor(factory, path[0], path[1]), amountIn));
        uint balanceBefore = IERC20(path[path.length - 1]).balanceOf(to);
        _swapSupportingFeeOnTransferTokens(path, to);
        require(
            IERC20(path[path.length - 1]).balanceOf(to).sub(balanceBefore) >= amountOutMin,
            'UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT'
        );
    }
    
    • 函數的第一行用來驗證交易鏈第一個代幣地址為WETH地址,原因前面已經講過了。
    • 第二行:隨函數傳送的ETH就是欲賣出的資產,ETH需要兌換成WETH。
    • 第三行,將ETH兌換成WETH。
    • 第四行,將WETH傳送到第一個交易對,因為這裡是傳送本合約的WETH,所以無需授權交易。
    • 第五行以後,同函數9。用來呼叫函數8進行交易操作。同時記錄接收者地址交易前後最後一種代幣的餘額,從而計算出實際買進的數量,來驗證它不能小於使用者指定的最小值。
    • WETH這裡不用考慮也不會有損耗,為什麼呢?因為它是開源的,它是不支援轉移代幣支付手續費的。
  11. swapExactTokensForETHSupportingFeeOnTransferTokens函數。有了前面的學習,這個函數也很簡單了,就是賣出指定數量的初始TOKEN,最後得到一定數量的ETH,同時支援使用轉移的代幣支付手續費。函數程式碼為:

    function swapExactTokensForETHSupportingFeeOnTransferTokens(
        uint amountIn,
        uint amountOutMin,
        address[] calldata path,
        address to,
        uint deadline
    )
        external
        virtual
        override
        ensure(deadline)
    {
        require(path[path.length - 1] == WETH, 'UniswapV2Router: INVALID_PATH');
        TransferHelper.safeTransferFrom(
            path[0], msg.sender, UniswapV2Library.pairFor(factory, path[0], path[1]), amountIn
        );
        _swapSupportingFeeOnTransferTokens(path, address(this));
        uint amountOut = IERC20(WETH).balanceOf(address(this));
        require(amountOut >= amountOutMin, 'UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT');
        IWETH(WETH).withdraw(amountOut);
        TransferHelper.safeTransferETH(to, amountOut);
    }
    
    • 函數的第一行用來驗證交易鏈最後一個地址為WETH地址,原因不再重複了。
    • 第2-4行用來將初始資產傳送給第一個交易對,注意這裡需要提前授權。
    • 第5行呼叫內部函數8進行交易操作。注意,此時的接收地址為本合約地址,因為使用者買進的的是ETH,而這裡得到的是WETH,不能直接讓使用者接收,需要轉換成ETH。
    • 第6行用來獲取交易鏈中買進的資產(WETH)數量。因為周邊合約本身不存有任何資產(交易前WETH餘額為0),所以本合約地址當前WETH餘額就是買進的WETH數量。
    • 第7行驗證買進的WETH數量要大於使用者指定的最小值。
    • 第8-9行,將WETH兌換成等額ETH並行送給接收者。
    • WETH並不會有損耗,原因同上。
  12. quote函數。註釋中可以看到,從該函數起,主要就是庫函數功能了,它們都是直接呼叫庫函數做一些計算。因為庫函數一般是無狀態的,所以它們基本上也都是pure型別的(和對應的庫函數一致)。工具庫函數的說明也可以參照序列文章中的周邊合約學習(一)–工具庫的學習。

    // **** LIBRARY FUNCTIONS ****
    function quote(uint amountA, uint reserveA, uint reserveB) public pure virtual override returns (uint amountB) {
        return UniswapV2Library.quote(amountA, reserveA, reserveB);
    }
    

    該函數及接下來的幾個函數都未在本合約使用,它們主要是直接包裝了工具庫函數提供給外部合約使用。為什麼這麼做呢?個人猜想是因為外部合約很大可能 不會使用UniswapV2這個自定義的工具庫UniswapV2Library,所以周邊合約提供了相應的介面方便外部合約使用這些庫函數功能(當然也可以是鏈下呼叫而非合約呼叫)。

    該函數的功能為根據交易對中兩種資產比例,給出一種代幣數值,計算另一種代幣數值。本合約在流動性供給計算時直接使用了相同功能的工具庫函數。

  13. getAmountOut函數,根據恆定乘積演演算法,指定賣出資產的數量,計算買進資產的數量。計算時考慮了手續費,僅適用於單個交易對。

  14. getAmountIn函數,根據恆定乘積演演算法,指定買進資產的數量,計算賣出資產的數量。計算時考慮了手續費,僅適用於單個交易對。

    這裡有一點需要提一下,其函數程式碼為(超級簡單):

    function getAmountIn(uint amountOut, uint reserveIn, uint reserveOut)
        public
        pure
        virtual
        override
        returns (uint amountIn)
    {
        return UniswapV2Library.getAmountIn(amountOut, reserveIn, reserveOut);
    }
    

    注意:在上一篇文章介紹Router時,官方檔案提到Router1合約有一個低風險的Bug,就是指這個函數。那麼到底是什麼Bug呢?我們來對照一下Router1合約中相應的程式碼:

    function getAmountIn(uint amountOut, uint reserveIn, uint reserveOut) public pure override returns (uint amountIn) {
        return UniswapV2Library.getAmountOut(amountOut, reserveIn, reserveOut);
    }
    

    😄😄😄,該bug是一處筆誤,將UniswapV2Library.getAmountIn寫成了UniswapV2Library.getAmountOut。然而該函數週邊合約本身並未呼叫,只是作為介面提供給外部使用,因此為低風險的。但是由於合約部署之後無法更改,所以只能等到Router2來更改過來了。

  15. getAmountsOut函數。多了一個s,代表多個,意味著它用於交易鏈的計算中,指定賣出資產數量,計算涉及到的每種資產數量並順序儲存在一個陣列中。

  16. getAmountsIn函數。多了一個s,代表多個,意味著它用於交易鏈的計算中,指定買進資產數量,反向推導計算出涉及到的每種資產數量並順序儲存在一個陣列中。

二、資產交易函數分類

上面這麼多swap函數,大家肯定看得眼花繚亂了👻👻👻。下面我們根據交易資產的種類和指定的是賣出資產數量/買進資產數量,對它們做一個簡單的分類:

2.1、 TOKEN => TOKEN

就是兩種ERC20代幣交易,可分為:

  1. 指定賣出代幣數量,得到另一種代幣,函數為swapExactTokensForTokens
  2. 指定買進代幣數量,賣出另一種代幣,函數為swapTokensForExactTokens

2.2、ETH => TOKEN

ETH兌換成ERC20代幣,也分為兩種:

  1. 指定賣出ETH數量,得到另一種ERC20代幣,函數為swapExactETHForTokens
  2. 指定買進ERC20代幣數量,賣出ETH,函數為swapETHForExactTokens

2.3、TOKEN => ETH

ERC20代幣兌換成ETH。等等,有人會說這不是和 ETH => TOKEN 一樣的麼,既然能通過交易鏈實現 ETH => TOKEN,那麼必能反向通過該交易鏈實現 TOKEN => ETH。

是這樣的沒錯,但是因為不能直接交易ETH,所以會涉及到一個ETH和WETH的相兌換(轉換髮生在不同方向的交易鏈的不同階段),因此實現邏輯還是不同的,所以這裡提供了另外兩個介面。

  1. 指定賣出ERC20代幣數量,得到ETH,函數為swapExactTokensForETH
  2. 指定買進ETH數量,賣出另一種ERC20代幣,函數為swapTokensForExactETH

2.4、支援FeeOnTransferTokens函數

此外還有三個支援FeeOnTransferTokens函數,分別為函數9、函數10,函數11。注意它們的函數名稱,均表示指定賣出資產數量。也就是說它們只能用於交易鏈中指定賣出資產數量這種場景,不支援指定買進資產的場景中進行的反向交易鏈數值計算,因此只有3個該類函數。

為什麼會這樣呢?

個人認為是因為此類資產在轉移過程中可能會有損耗,但損耗到底多少是無法知曉的。因此指定買進資產數量反推賣出資產數量的話,是無法得到的。因為該值為計算得到的值加上損耗值。如果指定賣出資產數量的話,每個交易對的實際賣出資產數量和最終接收的買進資產數量均可以通過比較相應地址交易前後的資產餘額來計算出,因此此種交易場景是可行的。

因此2.1-2.3三種交易型別每種型別只有一個支援FeeOnTransferTokens函數,分別為:

  1. TOKEN => TOKEN 為 swapExactTokensForTokensSupportingFeeOnTransferTokens函數。
  2. ETH => TOKEN 為swapExactETHForTokensSupportingFeeOnTransferTokens函數。
  3. TOKEN => ETH 為swapExactTokensForETHSupportingFeeOnTransferTokens函數。

綜合得到Router2合約用於資產交易的對外介面共分四類9個介面。

三、總結

從前面的學習中可以看出,雖然資產交易對外提供了四類共9個介面,但來回就是對兩個核心_swap函數的呼叫。其中支援使用轉移的代幣支付手續費的介面中,轉移資產的實際數量不再等於根據恆定乘積計算出來的結果值,而需要根據相應地址的兩次資產餘額相減計算出來。交易鏈中如果有涉及到ETH交易的,需要在交易鏈的對應階段(開始或者結束階段)進行ETH/WETH的兌換。因為UniswapV2交易對全部為ERC20/ERC20交易對,因此交易鏈中間流程不可能有ETH出現。

至此,UniswapV2Router02.sol合約原始碼學習(下)就到此結束了,計劃下一次進行周邊合約中的UniswapV2Migrator.sol的原始碼學習。

由於個人能力有限,難免有理解錯誤或者不正確的地方,還請大家多多留言指正。

在UniswapV2合約的原始碼學習過程中,UniswapV2Router02.sol合約篇幅最長,也比較複雜。因此本合約的學習記錄(上/下篇)的撰寫也比較耗時,更新時間較久。

如果本文能給大家帶來一點幫助,請大家手留餘香,點個贊,借用CSDN的一句話:你們的支援是筆者寫下去的最大動力。