TRON JustSwap快速對接PHP開發包

JustSwap.php 開發包适用于為PHP應用快速增加對JustSwap協定的支援能力。即支援使用自有部署Tron區塊鍊節點的應用場景，也支援使用第三方節點的輕量級部署場景，官方下載下傳位址： JustSwap對接PHP開發包 。

1、開發包概述

JustSwap.php開發包主要包含以下特性：

• 一鍵部署JustSwap協定，便于快速開發與測試
• 支援JustSwap協定的全部接口，并提供開發人員友好的API
• 支援TRX/TRC20流動性的建立、添加與移除
• 支援TRX/TRC20、TRC20/TRX、TRC20/TRC20交易對的兌換交易
• 支援自動做市價格計算與滑點計算

JustSwap.php開發包運作在 Php 7.1+ 環境下，目前版本1.0.0，主要類/接口及關系如下圖所示：

JustSwap.php開發包的主要代碼檔案清單參見

官網說明

2、使用示例代碼

2.1 編譯合約

在終端進入項目目錄，執行如下指令編譯開發包提供的JustSwap協定及測試用Token合約：

~$ cd ~/justswap.php
~/justswap.php$ ./bin/build-contracts           

執行結果如下：

2.2 部署合約

進入項目demo目錄，執行如下指令部署合約：

~/justswap.php/demo$ php deploy-contracts.php           

上述指令将部署完整的JustSwap協定和測試用的HubToken與WizToken，并将合約部署位址記錄在項目demo目錄下的 addresses.json 檔案中。

合約部署腳本的執行結果如下：

注意 ：部署前需要先設定demo/config.php中的部署賬号。

2.3 建立流動池

代碼

create-exchange.php

示範了如何建立TRX/TRC20流動池。

在終端進入項目demo目錄，執行如下指令：

~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php create-exchange.php           

2.4 Token授權

approve-token.php

示範了如何授權justswap Exchange合約代理操作目前賬号的HUB token和WIZ token。

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

2.5 添加流動性

add-liquidity.php

示範了如何為流動池添加流動性。

在終端進入項目demo目錄，執行如下指令為Hub token添加流動性：

~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php add-liquidity.php hub           

如果是流動池建立後第一次執行

php add-liuqidity.php hub

，那麼為TRX/HUB池将添加初始的流動性将決定初始兌換比例（10 TRX/10 HUB）。其執行結果如下：

如果是流動池已經存在初始流動性後執行

php add-liquidity.php hub

，那麼将按照TRX/HUB目前的兌換比例添加流動性，其執行結果如下：

用同樣的方法為TRX/WIZ池添加初始流動性（10 TRX/10 WIZ）：

~/justswap.php/demo$ php add-liquidity.php wiz           

2.6 移除流動性

remove-liquidity.php

示範了如何移除指定流動池的流動性。可以使用參數hub或wiz指定要移除流動性的池。

在終端進入項目demo目錄，執行如下指令從TRX/HUB池溢出25%流動性：

~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php remove-liquidity.php hub           

2.7 TRX/TRC20兌換：以輸入TRX數量為基準

swap-exact-trx-for-tokens.php

示範和如何将指定數量的TRX兌換為TRC20 token。可以使用參數hub或wiz指定要兌換的token。

在終端進入項目demo目錄，執行如下指令将0.1 TRX兌換為相應數量的HubToken：

~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php swap-exact-trx-for-tokens.php hub           

2.8 TRX/TRC20兌換：以輸出token數量為基準

swap-trx-for-exact-tokens.php

示範了如何将TRX兌換為指定數量的TRC20 token。可以使用參數hub或wiz指定要兌換的token。

在終端進入項目demo目錄，執行如下指令用TRX兌換回0.1 HUB：

~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php swap-trx-for-exact-tokens.php hub           

2.9 TRC20/TRX兌換：以輸入token數量為基準

swap-exact-tokens-for-trx.php

示範了如何将指定數量的TRC20 token兌換為TRX。可以使用參數hub或wiz指定要兌換的token。

在終端進入項目demo目錄，執行如下指令将1 HUB兌換為相應數量的TRX：

~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php swap-exact-tokens-for-trx.php hub           

2.10 TRC20/TRX兌換：以輸出TRX數量為基準

swap-tokens-for-exact-trx.php

示範了如何将ERC20token兌換為指定數量的ETH。可以使用參數hub或wiz指定要兌換的token。

在終端進入項目demo目錄，執行如下指令用HUB兌換回1 TRX：

~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php swap-tokens-for-exact-trx.php hub           

2.11 TRC20/TRC20兌換：以輸入token數量為基準

swap-exact-tokens-for-tokens.php

示範了如何實作以輸入token數量為基準的TRC20/TRC20兌換。

在終端進入項目demo目錄，執行如下指令将1 HUB兌換為相應數量的WIZ：

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

2.12 TRC20/TRC20兌換：以輸出token數量為基準

swap-tokens-for-exact-tokens.php

示範了如何實作以輸出token數量為基準的TRC20/TRC20兌換。

在終端進入項目demo目錄，執行如下指令用HUB兌換回1 WIZ：

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

3、使用justswap.php開發包

SwapKit 是開發包的入口，使用SwapKit類可以快速實作如下功能：

• 流動性管理：支援TRX/TRC20流動池的建立、添加與删除
• 兌換交易的建立與執行：支援TRC20/TRC20、TRC20/TRX、TRX/TRC20等各種交易對，支援以輸入或輸出價格為準
• 使用者倉位查詢：查詢指定賬号在指定交易對的持倉情況，例如持倉數量、占比等。

3.1 執行個體化SwapKit

SwapKit執行個體化需要傳入三個參數：

• TronApi執行個體
• 用于執行合約互動的Tron身份憑證對象，即一個

  Credential

  對象
• JustSwap協定的工廠合約位址

例如，下面的代碼建立一個接入Tron主網justswap協定的SwapKit執行個體：

//use JustSwap\TronApi;
//use JustSwap\Credential;
//use JustSwap\SwapKit;

$kit = new SwapKit(
  TronApi::mainNet(),                               //Tron主網
  Credential::fromPrivateKey('4f3e...3b1d'),        //預設執行賬号，指定私鑰                                 
  'TXk8rQSAvPvBBNtqSoY6nCfsXWCSSpTVQF',             //justswap工廠合約位址
);           

3.2 Credential：Tron身份與位址表示

在justswap.php開發包中，使用 Credential 表征Tron區塊鍊中的一個使用者身份，與位址相比，Credential對象中包含了使用者的私鑰資訊，可以用來簽名交易，是以需要保護其不會洩露。

使用Credential類的靜态方法

create()

建立新賬戶。例如，下面的代碼建立一個新的賬戶并顯示其私鑰、公鑰和位址：

//use JustSwap\Credential;

$alice = Credential::create();                                  //建立新賬号
echo 'private key => ' . $alice->privateKey() . PHP_EOL;        //顯示私鑰
echo 'public key => ' . $alice->publicKey() . PHP_EOL;          //顯示公鑰
echo 'address => ' . $alice->address()->base58() . PHP_EOL;     //顯示位址           

可以使用靜态方法

fromPrivateKey()

導入已有的私鑰來執行個體化Credential。

例如下面的代碼導入已有私鑰并顯示位址：

//use JustSwap\Credential;

$alice = Credential::fromPrivateKey('7889...023a');              //導入已有私鑰
echo 'address => ' . $alice->address()->base58() . PHP_EOL;      //顯示相應位址           

3.3 建立流動池

使用JustSwap工廠執行個體的

createExchange()

方法建立流動池，例如：

$tokenAddr='TRbojfoxNQ2HcJPM85rY5N34aQFafEXZMA';                 //代币位址
$txid = $kit->getFactory()->createExchange($tokenAddr, []);
echo 'txid => ' . $txid . PHP_EOL;           

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

由于justswap協定中涉及到交易滑點處理以及價格預計算，是以justswap.php提供了一個專門的類 OrderBuilder 用于生成流動性添加/移除委托單。OrderBuilder的實作内置了自動價格計算與滑點計算，是以調用者隻需要指定基本的資料即可生成可送出給justswap合約的流動性添加/移除委托單。

使用SwapKit對象的

getOrderBuilder()

方法擷取預建立的OrderBuilder對象，并調用OrderBuilder的

build()

方法生成委托單。例如：

$order = $kit->getOrderBuilder()           //傳回OrderBuilder對象 
             ->....                        //參數設定
             ->build();                    //生成并傳回委托單           

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

• orderType($type) ：設定委托單類型，目前支援兩種：

  • Order::LIQUIDITY_ADD

    - 流動性添加委托單

  • Order::LIQUIDITY_REMOVE

    - 流動性移除委托單
• tokenA($addr)** / **tokenB($addr) ：交易對的兩個Token位址。 使用特殊的

  SwapKit::TRX_TOKEN

  表示TRX，并且對justswap協定來說tokenA 必須設定為TRX，即

  SwapKit::TRX_TOKEN

• amountA($bn)** / **amountB($bn) ：兩個token的添加數量，僅在添加流動時需要設定
• liquidity($bn) ：LP token數量，僅在移除流動性時需要設定
• slippage($bn) ：交易滑點設定，預設值為5， 表示0.5%的滑點容忍區間

例如，下面的代碼生成一個流動性添加委托單：

use justswap\Order;

$order = $kit->getOrderBuilder()                         //擷取委托單生成器對象
             ->orderType(Order::LIQUIDITY_ADD)           //添加流動性
             ->tokenA(SwapKit::TRX_TOKEN)                //交易對TokenA，必須為TRX
             ->tokenB('0x...')                           //交易對TokenB
             ->amountA(bn('100000000000000000000'))      //以TokenA數量為基準按市價自動計算TokenB數量
             ->slippage(bn('10'))                        //滑點容忍範圍1%
             ->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::TRX_TOKEN 表示交易對中的TRX，值為：

  T9yD14Nj9j7xAB4dbGeiX9h8vMa2GfnLve

• bn($numstr)

  是justswap提供的一個建立 BigInteger 對象 的快捷函數，其參數為10進制字元串。
• token數量均按最小機關指定

類似的，下面的代碼生成一個流動性移除委托單：

$order = $kit->getOrderBuilder()                         //擷取委托單生成器對象
             ->orderType(Order::LIQUIDITY_REMOVE)        //移除流動性  
             ->tokenA('0x...')                           //交易對TokenA位址 
             ->tokenB('0x...')                           //交易對TokenB位址 
             ->liquidity(bn('10000000000000000000'))     //要移除的流動性數量
             ->slippage(bn('10'))                        //滑點容忍範圍1%
             ->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            

可以使用SwapKit對象的

waitForConfirmation()

方法等待交易确認，

該方法在交易确認後傳回true或false，分别表示交易成功執行或交易復原。

例如：

$success = $kit->waitForConfirmation($txid);
echo 'success => ' . $success . PHP_EOL;           

3.6 查詢倉位資訊

使用SwapKit的 getExchangeLiquidityInfoForToken() 方法可以查詢指定賬号在指定token的流動池的倉位資訊。例如查詢某位址的持倉情況：

$info = $kit->getExchangeLiquidityInfoForToken(        //查詢持倉資訊
  $kit->getCredential()->address()->base58(),          //目前賬号
  'TENh4XGvTPEdceEVxiXoEfH9ufxyjYrSwn'                 //token位址
);       

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

3.7 生成兌換交易對象

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

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->getDefaultAddress())         //輸出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           

waitForConfirmation()

方法等待交易确認，該方法在交易确認後傳回true或false，分别表示交易成功執行或交易復原。

$success = $kit->waitForConfirmation($txid);
echo 'success => ' . $success . PHP_EOL;           

JustSwap.php官方下載下傳位址：

http://sc.hubwiz.com/codebag/justswap-php/