資安

PHP快速對接Uniswap

Uniswap.php 開發包適用於為PHP應用快速增加對Uniswap協議的支持能力。即支持使用自有部署以太坊區塊鏈節點的應用場景,也支持使用第三方節點的輕量級部署場景。官方下載地址:Uniswap.php對接開發包

1、開發包概述

Uniswap.php開發包主要包含以下特性:

  • 一鍵部署Uniswap協議,便於快速開發與測試
  • 支持Uniswap協議的全部接口,並提供開發人員友好的API
  • 支持ERC20/ERC20、ETH/ERC20等各種交易對的流動性添加、移除與兌換交易
  • 支持自動做市價格計算與滑點計算
  • 支持以太坊交易gas用量與gas價格的自動估算與手動設定
  • 支持EIP712簽名授權,單一交易內完成流動性維護

Uniswap.php開發包運行在 Php 7.1+ 環境下,當前版本1.0.0,主要類/接口及關係如下圖所示:

在這裡插入圖片描述

Uniswap.php開發包的主要代碼文件清單參見官網說明:http://sc.hubwiz.com/codebag/uniswap-php/

2、使用示例代碼

2.1 編譯合約

在終端進入項目目錄,執行如下命令編譯Uniswap及開發包提供的測試Token合約:

~$ cd ~/uniswap.php
~/uniswap.php$ ./build-contract.sh

執行結果如下:

在這裡插入圖片描述

2.2 部署合約

首先在另一個終端啟動開發私鏈:

~$ ganache-cli -d

然後進入項目demo目錄,執行如下命令部署合約:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php deploy-contracts.php

執行結果如下:

在這裡插入圖片描述

注意 :如果需要在以太坊測試鏈,例如Ropsten、Rinkeby等,或者在主鏈 部署上述合約,或者使用其他參數啟動ganache-cli,需要修改demo/config.php 中的賬號配置。

2.3 Token授權

代碼token-approve.php演示瞭如何授權Uniswap路由合約代理操作當前賬號的HAPY token和USDT token。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php token-approve.php

執行結果如下:

在這裡插入圖片描述

2.4 ERC20/ERC20交易對添加流動性

代碼add-liquidity.php演示瞭如何為ERC20/ERC20交易對添加流動性。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php add-liquidity.php

執行結果如下:

在這裡插入圖片描述

Uniswap協議約定,第一次添加流動性將自動創建交易對 ,之後再次添加流動性時,演示代碼將首先顯示當前的倉位信息。例如再次執行如下命令:

~/uniswap.php/demo$ php add-liquidity.php

執行結果如下:

在這裡插入圖片描述

2.5 ERC20/ERC20交易對移除流動性

代碼remove-liquidity.php演示瞭如何移除指定的ERC20/ERC20交易對的流動性。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php remove-liquidity.php

執行結果如下:

在這裡插入圖片描述

2.6 ERC20/ERC20兌換:以輸入token數量為基準

代碼swap-exact-tokens-for-tokens.php演示瞭如何實現以輸入token數量為基準的ERC20/ERC20兌換。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php swap-exact-tokens-for-tokens.php

執行結果如下:

在這裡插入圖片描述

2.7 ERC20/ERC20兌換:以輸出token數量為基準

代碼swap-tokens-for-exact-tokens.php演示瞭如何實現以輸出
token數量為基準的ERC20/ERC20兌換。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php swap-tokens-for-exact-tokens.php

執行結果如下:

在這裡插入圖片描述

2.8 ETH/ERC20交易對添加流動性

代碼add-liquidty-eth.php演示瞭如何為ETH/ERC20或ERC20/ETH交易對添加流動性。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php add-liquidity-eth.php

執行結果如下:

在這裡插入圖片描述

第一次添加流動性將自動創建交易對,之後再次添加將首先顯示
當前的持倉信息。例如再次執行如下命令:

~/uniswap.php/demo$ php add-liquidity-eth.php

執行結果如下:
在這裡插入圖片描述

2.9 ETH/ERC20交易對移除流動性

代碼remove-liquidity-eth.php演示瞭如何移除ETH/ERC20或ERC20/ETH
交易對的流動性。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php remove-liquidity-eth.php

執行結果如下:

在這裡插入圖片描述

2.10 ETH/ERC20兌換:以輸入ETH數量為基準

代碼swap-exact-eth-for-tokens.php演示和如何將指定數量的ETH
兌換為ERC20 token。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php swap-exact-eth-for-tokens.php

執行結果如下:

在這裡插入圖片描述

2.11 ETH/ERC20兌換:以輸出token數量為基準

代碼swap-eth-for-exact-tokens.php演示瞭如何將ETH兌換為指定
數量的ERC20 token。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php swap-eth-for-exact-tokens.php

執行結果如下:

在這裡插入圖片描述

2.12 ERC20/ETH兌換:以輸入token數量為基準

代碼swap-exact-tokens-for-eth.php演示瞭如何將指定數量的
ERC20 token兌換為ETH。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php swap-exact-tokens-for-eth.php

執行結果如下:

在這裡插入圖片描述

2.13 ERC20/ETH兌換:以輸出ETH數量為基準

代碼swap-tokens-for-exact-eth.php演示瞭如何將ERC20
token兌換為指定數量的ETH。

在終端進入項目demo目錄,執行如下命令:

~$ cd ~/uniswap.php/demo
~/uniswap.php/demo$ php swap-tokens-for-exact-eth.php

執行結果如下:

在這裡插入圖片描述

3、使用Uniswap.php開發包

SwapKit 是開發包的入口,使用這個類可以快速實現如下功能:

  • 流動性添加與移除:支持ERC20/ERC20、ERC20/ETH、ETH/ERC20等各種交易對
  • 兌換交易的創建與執行:支持ERC20/ERC20、ERC20/ETH、ETH/ERC20等各種交易對,支持以輸入或輸出價格為準
  • 用戶倉位查詢:查詢指定賬號在指定交易對的持倉情況,例如持倉數量、佔比等。

3.1 實例化SwapKit

SwapKit實例化需要傳入三個參數:

  • 以太坊節點URL
  • Uniswap路由合約地址
  • 用於執行合約交互的以太坊賬號,即一個Credential對象。

例如,下面的代碼創建一個接入以太坊主網Uniswap協議的SwapKit實例:

//use Uniswap\SwapKit;
//use Uniswap\Credential;

$kit = new SwapKit(
  'http://localhost:8545',                          //以太坊節點URL
  '0x7a250d5630B4...b4c659F2488D',                  //Uniswap路由合約地址
  Credential::fromKey('0x4f3e...3b1d')              //默認執行賬號,指定私鑰                                 
);

有關Credential的使用說明,詳見本文第3.3部分。

3.2 使用ProtocolMeta(可選)

為了避免混淆各網絡的Uniswap路由地址,Uniswap.php 提供了ProtocolMeta類的靜態方法getPresetAddress()來獲取Uniswap官方在以太坊主網和測試網部署的Uniswap協議合約地址。例如
獲取主網的路由合約:

//use Uniswap\SwapKit;
//use Uniswap\ProtocolMeta;

$routerAddr = ProtocolMeta::getPresetAddress(
  SwapKit::MAINNET,                                  //以太坊網絡  
  SwapKit::ROUTER                                    //Uniswap合約
);
echo $routerAddr . PHP_EOL                           //0x7a250d5630B4...

ProtocolMeta 目前支持的以太坊網絡及標識參見官網說明:http://sc.hubwiz.com/codebag/uniswap-php/

3.3 Credential:以太坊身份與地址表示

在Uniswap.php開發包中,使用 Credential 表徵以太坊區塊鏈中的一個用戶身份,與以太坊地址相比,Credential對象中包含了用戶的私鑰信息,可以用來簽名交易,因此需要保護其不會洩露。

使用Credential類的靜態方法new()創建新賬戶。例如,下面的代碼創建一個新的賬戶並顯示其私鑰、公鑰和地址:

//use Uniswap\Credential;

$alice = Credential::new();                                  //創建新賬號
echo 'private key => ' . $alice->getPrivateKey() . PHP_EOL;  //顯示私鑰
echo 'public key => ' . $alice->getPublicKey() . PHP_EOL;    //顯示公鑰
echo 'address => ' . $alice->getAddress() . PHP_EOL;         //顯示地址

可以使用靜態方法fromKey()導入已有的私鑰來實例化Credential。例如下面的代碼導入已有私鑰並顯示地址:

//use Uniswap\Credential;

$alice = Credential::fromKey('0x7889...023a');              //導入已有私鑰
echo 'address => ' . $alice->getAddress() . PHP_EOL;        //顯示相應地址

3.4 生成流動性添加/移除委託單

由於Uniswap協議中涉及到交易滑點處理以及價格預計算,因此Uniswap.php提供了一個專門的類 OrderBuilder 用於生成流動性添加/移除委託單。OrderBuilder的實現內置了自動價格計算與
滑點計算,因此調用者只需要指定基本的數據即可生成可提交給Uniswap合約的流動性添加/移除委託單。

使用SwapKit對象的getOrderBuilder()方法獲取預創建的OrderBuilder對象,並調用OrderBuilder的build()方法生成委託單。例如:

$order = $kit->getOrderBuilder()           //返回OrderBuilder對象 
             ->....                        //參數設置
             ->build();                    //生成並返回委託單

OrderBuilder對象提供了以下方法用於調整生成器的行為:

  • orderType($type) :設置委託單類型,目前支持兩種:

    • Order::LIQUIDITY_ADD - 流動性添加委託單
    • Order::LIQUIDITY_REMOVE - 流動性移除委託單
  • tokenA($addr)** / **tokenB(\$addr) :交易對的兩個Token地址
    表示交易對之一為以太幣
  • amountA($bn)** / **amountB(\$bn) :兩個token的添加數量,僅在添加流動時需要設置
  • liquidity($bn) :LP token數量,僅在移除流動性時需要設置
  • slippage($bn) :交易滑點設置,默認值為5, 表示0.5%的滑點容忍區間
  • to($addr) :委託單執行結果接收地址

例如,下面的代碼生成一個流動性添加委託單:

use Uniswap\Order;

$order = $kit->getOrderBuilder()                         //獲取委託單生成器對象
             ->orderType(Order::LIQUIDITY_ADD)           //添加流動性
             ->tokenA('0x...')                           //交易對TokenA
             ->tokenB('0x...')                           //交易對TokenB
             ->amountA(bn('100000000000000000000'))      //以TokenA數量為基準按市價自動計算TokenB數量
             ->slippage(bn('10'))                        //滑點容忍範圍1%
             ->to($kit->getCredential())                 //設置LP Token的接收地址
             ->build();                                  //生成委託單 
             
echo 'amountA => ' . $order->amountA . PHP_EOL;          //TokenA設置數量  
echo 'amountB => ' . $order->amountB . PHP_EOL;          //TokenB計算數量 
echo 'amountAMin => ' . $order->amountAMin . PHP_EOL;    //滑點處理後的TokenA最小可接受數量 
echo 'amountBMin => ' . $order->amountAMin . PHP_EOL;    //滑點處理後的TokenB最小可接受數量

注意:

  • 使用特殊的 SwapKit::ETH_TOKEN 表示交易對中的ETH,值為:0x00000000000000000000000000000000000eeeee
  • bn($numstr) 是Uniswap提供的一個創建 BigInteger 對象 的快捷函數,其參數為10進制字符串。
  • token數量均按最小單位指定

類似的,下面的代碼生成一個流動性移除委託單:

$order = $kit->getOrderBuilder()                         //獲取委託單生成器對象
             ->orderType(Order::LIQUIDITY_REMOVE)        //移除流動性  
             ->tokenA('0x...')                           //交易對TokenA地址 
             ->tokenB('0x...')                           //交易對TokenB地址 
             ->liquidity(bn('10000000000000000000'))     //要移除的流動性數量
             ->slippage(bn('10'))                        //滑點容忍範圍1%
             ->to($kit->getCredential())                 //token接收地址
             ->build();                                  //生成委託單 

echo 'amountAMin => ' . $order->amountAMin . PHP_EOL;    //滑點處理後最少應收到的TokenA數量 
echo 'amountBMin => ' . $order->amountAMin . PHP_EOL;    //滑點處理後最少應收到的TokenB數量

Order對象提供的以下值,有助於在執行委託單之前向用戶提供更好的反饋信息:

  • amountA/amountB :市價計算的tokenA或tokenB理想值
  • amountAMin/amountAMax :滑點處理後的tokenA最小值/最大值
  • amountBMin/amountBMax :滑點處理後的tokenB最小值/最大值

3.5 執行流動性委託單

使用SwapKit的 executeOrder() 方法即可執行生成的流動性委託單,最終完成流動性添加/移除交易。例如:

$txid = $kit->executeOrder($trade);                      //執行委託單
echo 'txid => ' . $txid . PHP_EOL;                       //顯示交易ID 

默認情況下,executeOrder()方法自動估算交易所需的gas限額與gas價格,但可以傳入額外的參數手動設置這兩個值。

例如,下面的代碼以指定的gas參數執行流動性維護單:

$opts = [
  'gasLimit' => bn('4000000'),                          //4 million
  'gasPrice' => bn('200000000000')                      //200 gwei
];
$txid = $kit->executeOrder($order, $opts);              //執行委託單

3.6 查詢倉位信息

使用SwapKit的 getLiquidityInfo() 方法可以查詢指定賬號在指定交易對的倉位信息。例如查詢某地址的持倉情況:

$info = $kit->getLiquidityInfo('0x90F8...c9C1');       //查詢持倉信息

echo 'total => ' . $info->totalSupply . PHP_EOL;       //LP總量 
echo 'balance => ' . $info->balance . PHP_EOL;         //持倉數量
echo 'share % => ' . $info->share . PHP_EOL;           //持倉比例

3.7 生成兌換交易對象

類似於流動性的添加與移除,在Uniswap中的交易對兌換也存在價格自動計算與滑點處理問題。為此,Uniswap.php開發包提供了一個專門的類 TradeBuilder用來簡化這一操作。TradeBuilder內置了價格自動計算與滑點處理,因此調用者只需要設置基本的參數即可。

使用SwapKit對象的getTradeBuilder()方法獲取預創建的TradeBuilder對象,例如:

$tb = $kit->getTradeBuilder()              //獲取預創建的兌換交易生成器
          ->...                            //參數設置
          ->build();                       //生成兌換交易對象

TradeBuilder提供了以下方法用於調整生成器的行為:

  • tradeType($type) :兌換類型,可選值為:

    • Trade::EXACT_INPUT - 以tokenIn的數量為基準
    • Trade::EXACT_OUTPUT - 以tokenOut的數量為基準
  • tokenIn($addr) - 輸入Token的地址
  • tokenOut($addr) - 輸出Token的地址
  • amountIn($bn) - 輸入數量,僅在兌換類型為EXACT_INPUT時需要設置
  • amountOut($bn) - 輸出數量,僅在兌換類型為EXACT_OUTPUT時需要設置
  • slippage($bn) - 交易滑點設置,默認值5, 表示允許0.5%的滑點
  • to($addr) - 輸出token接收地址

例如,下面的代碼以輸入token數量為基準生成一個兌換交易對象:

$trade = $kit->getTradeBuilder()                     //獲取兌換交易生成器
             ->tradeType(Trade::EXACT_INPUT)         //以輸入token數量為基準
             ->tokenIn('0x...')                      //輸入token
             ->tokenOut('0x...')                     //輸出token
             ->amountIn(bn('10000000000000000000'))  //輸入token的數量
             ->slippage(bn('10'))                    //滑點容忍範圍1%
             ->to($kit->getCredential())             //輸出token的接收地址
             ->build();                              //生成兌換交易對象
             
echo 'amountIn => ' . $trade->amountIn . PHP_EOL;          //輸入token的設置數量
echo 'amountOut => ' . $trade->amountOut . PHP_EOL;        //自動做市算法得到的輸出token的數量
echo 'amountOutMin => ' . $trade->amountOutMin . PHP_EOL;  //滑點處理後的應收到的輸出token最少數量

3.8 執行兌換交易

使用SwapKit對象的 executeTrade() 方法執行指定的兌換交易對象。例如:

$txid = $kit->executeTrade($trade);                       //執行兌換交易
echo 'txid => ' . $txid . PHP_EOL;                        //顯示交易ID

默認情況下,executeTrade()方法自動估算交易所需的gas限額與gas價格,但可以傳入額外的參數手動設置這兩個值。

例如,下面的代碼使用設定的gas參數執行兌換交易:

$opts = [
  'gasLimit' => bn('4000000'),                            //4 million
  'gasPrice' => bn('200000000000')                        //200 gwei
];
$txid = $kit->executeTrade($trade, $opts);                //執行交易

Uniswap.php官方下載地址:http://sc.hubwiz.com/codebag/uniswap-php/

Leave a Reply

Your email address will not be published. Required fields are marked *