PHP应用对接Justswap专用开发包【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 uml

JustSwap.php开发包的主要代码文件清单参见官网说明。

2、使用示例代码

2.1 编译合约

在终端进入项目目录，执行如下命令编译开发包提供的JustSwap协议及测试用Token合约：

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

执行结果如下：

justswap.php build contracts

2.2 部署合约

进入项目demo目录，执行如下命令部署合约：

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

上述命令将部署完整的JustSwap协议和测试用的HubToken与WizToken，并将合约部署地址记录在项目demo目录下的 addresses.json 文件中。

合约部署脚本的执行结果如下：

justswap.php deploy contracts

注意：部署前需要先设置demo/config.php中的部署账号。

2.3 创建流动池

代码create-exchange.php演示了如何创建TRX/TRC20流动池。

在终端进入项目demo目录，执行如下命令：

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

执行结果如下：

justswap.php add liquidity

2.4 Token授权

代码approve-token.php演示了如何授权justswap Exchange合约代理操作当前账号的HUB token和WIZ token。

在终端进入项目demo目录，执行如下命令：

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

执行结果如下：

justswap.php token approve

2.5 添加流动性

代码add-liquidity.php演示了如何为流动池添加流动性。

在终端进入项目demo目录，执行如下命令为Hub token添加流动性：

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

如果是流动池创建后第一次执行php add-liuqidity.php hub，那么为TRX/HUB池将添加初始的流动性将决定初始兑换比例（10 TRX/10 HUB）。其执行结果如下：

justswap.php add liquidity first time

如果是流动池已经存在初始流动性后执行php add-liquidity.php hub，那么将按照TRX/HUB当前的兑换比例添加流动性，其执行结果如下：

justswap.php add liquidity

用同样的方法为TRX/WIZ池添加初始流动性（10 TRX/10 WIZ）：

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

执行结果如下：

justswap.php add liquidity

2.6 移除流动性

代码remove-liquidity.php演示了如何移除指定流动池的流动性。可以使用参数hub或wiz指定要移除流动性的池。

在终端进入项目demo目录，执行如下命令从TRX/HUB池溢出25%流动性：

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

执行结果如下：

justswap.php remove liquidity

2.7 TRX/TRC20兑换：以输入TRX数量为基准

代码swap-exact-trx-for-tokens.php演示和如何将指定数量的TRX兑换为TRC20 token。可以使用参数hub或wiz指定要兑换的token。

在终端进入项目demo目录，执行如下命令将0.1 TRX兑换为相应数量的HubToken：

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

执行结果如下：

justswap.php swap exact trx for tokens

2.8 TRX/TRC20兑换：以输出token数量为基准

代码swap-trx-for-exact-tokens.php演示了如何将TRX兑换为指定数量的TRC20 token。可以使用参数hub或wiz指定要兑换的token。

在终端进入项目demo目录，执行如下命令用TRX兑换回0.1 HUB：

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

执行结果如下：

justswap.php swap trx for exact tokens

2.9 TRC20/TRX兑换：以输入token数量为基准

代码swap-exact-tokens-for-trx.php演示了如何将指定数量的TRC20 token兑换为TRX。可以使用参数hub或wiz指定要兑换的token。

在终端进入项目demo目录，执行如下命令将1 HUB兑换为相应数量的TRX：

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

执行结果如下：

justswap.php swap exact tokens for trx

2.10 TRC20/TRX兑换：以输出TRX数量为基准

代码swap-tokens-for-exact-trx.php演示了如何将ERC20token兑换为指定数量的ETH。可以使用参数hub或wiz指定要兑换的token。

在终端进入项目demo目录，执行如下命令用HUB兑换回1 TRX：

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

执行结果如下：

justswap.php swap tokens for exact trx

2.11 TRC20/TRC20兑换：以输入token数量为基准

代码swap-exact-tokens-for-tokens.php演示了如何实现以输入token数量为基准的TRC20/TRC20兑换。

在终端进入项目demo目录，执行如下命令将1 HUB兑换为相应数量的WIZ：

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

执行结果如下：

justswap.php swap exact tokens for tokens

2.12 TRC20/TRC20兑换：以输出token数量为基准

代码swap-tokens-for-exact-tokens.php演示了如何实现以输出token数量为基准的TRC20/TRC20兑换。

在终端进入项目demo目录，执行如下命令用HUB兑换回1 WIZ：

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

执行结果如下：

justswap.php swap tokens for exact tokens

3、使用justswap.php开发包

SwapKit 是开发包的入口，使用SwapKit类可以快速实现如下功能：

流动性管理：支持TRX/TRC20流动池的创建、添加与删除
兑换交易的创建与执行：支持TRC20/TRC20、TRC20/TRX、TRX/TRC20等各种交易对，支持以输入或输出价格为准
用户仓位查询：查询指定账号在指定交易对的持仓情况，例如持仓数量、占比等。

3.1 实例化SwapKit

SwapKit实例化需要传入三个参数：

TronApi实例
用于执行合约交互的Tron身份凭证对象，即一个Credential对象
JustSwap协议的工厂合约地址

例如，下面的代码创建一个接入Tron主网justswap协议的SwapKit实例：

1//use JustSwap\TronApi;
2//use JustSwap\Credential;
3//use JustSwap\SwapKit;
4
5$kit = new SwapKit(
6  TronApi::mainNet(),                               //Tron主网
7  Credential::fromPrivateKey('4f3e...3b1d'),        //默认执行账号，指定私钥                                 
8  'TXk8rQSAvPvBBNtqSoY6nCfsXWCSSpTVQF',             //justswap工厂合约地址
9);

3.2 Credential：Tron身份与地址表示

在justswap.php开发包中，使用 Credential 表征Tron区块链中的一个用户身份，与地址相比，Credential对象中包含了用户的私钥信息，可以用来签名交易，因此需要保护其不会泄露。

使用Credential类的静态方法create()创建新账户。例如，下面的代码创建一个新的账户并显示其私钥、公钥和地址：

1//use JustSwap\Credential;
2
3$alice = Credential::create();                                  //创建新账号
4echo 'private key => ' . $alice->privateKey() . PHP_EOL;        //显示私钥
5echo 'public key => ' . $alice->publicKey() . PHP_EOL;          //显示公钥
6echo 'address => ' . $alice->address()->base58() . PHP_EOL;     //显示地址

可以使用静态方法fromPrivateKey()导入已有的私钥来实例化Credential。例如下面的代码导入已有私钥并显示地址：

1//use JustSwap\Credential;
2
3$alice = Credential::fromPrivateKey('7889...023a');              //导入已有私钥
4echo 'address => ' . $alice->address()->base58() . PHP_EOL;      //显示相应地址

3.3 创建流动池

使用JustSwap工厂实例的createExchange()方法创建流动池，例如：

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

3.4 生成流动性添加/移除委托单

由于justswap协议中涉及到交易滑点处理以及价格预计算，因此justswap.php提供了一个专门的类 OrderBuilder 用于生成流动性添加/移除委托单。OrderBuilder的实现内置了自动价格计算与滑点计算，因此调用者只需要指定基本的数据即可生成可提交给justswap合约的流动性添加/移除委托单。

使用SwapKit对象的getOrderBuilder()方法获取预创建的OrderBuilder对象，并调用OrderBuilder的build()方法生成委托单。例如：

1$order = $kit->getOrderBuilder()           //返回OrderBuilder对象 
2             ->....                        //参数设置
3             ->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%的滑点容忍区间

例如，下面的代码生成一个流动性添加委托单：

1use justswap\Order;
2
3$order = $kit->getOrderBuilder()                         //获取委托单生成器对象
4             ->orderType(Order::LIQUIDITY_ADD)           //添加流动性
5             ->tokenA(SwapKit::TRX_TOKEN)                //交易对TokenA，必须为TRX
6             ->tokenB('0x...')                           //交易对TokenB
7             ->amountA(bn('100000000000000000000'))      //以TokenA数量为基准按市价自动计算TokenB数量
8             ->slippage(bn('10'))                        //滑点容忍范围1%
9             ->build();                                  //生成委托单 
10             
11echo 'amountA => ' . $order->amountA . PHP_EOL;          //TokenA设置数量  
12echo 'amountB => ' . $order->amountB . PHP_EOL;          //TokenB计算数量 
13echo 'amountAMin => ' . $order->amountAMin . PHP_EOL;    //滑点处理后的TokenA最小可接受数量 
14echo 'amountBMin => ' . $order->amountAMin . PHP_EOL;    //滑点处理后的TokenB最小可接受数量

注意：

使用特殊的 SwapKit::TRX_TOKEN 表示交易对中的TRX，值为：T9yD14Nj9j7xAB4dbGeiX9h8vMa2GfnLve
bn($numstr) 是justswap提供的一个创建 BigInteger 对象的快捷函数，其参数为10进制字符串。
token数量均按最小单位指定

类似的，下面的代码生成一个流动性移除委托单：

1$order = $kit->getOrderBuilder()                         //获取委托单生成器对象
2             ->orderType(Order::LIQUIDITY_REMOVE)        //移除流动性  
3             ->tokenA('0x...')                           //交易对TokenA地址 
4             ->tokenB('0x...')                           //交易对TokenB地址 
5             ->liquidity(bn('10000000000000000000'))     //要移除的流动性数量
6             ->slippage(bn('10'))                        //滑点容忍范围1%
7             ->build();                                  //生成委托单 
8
9echo 'amountAMin => ' . $order->amountAMin . PHP_EOL;    //滑点处理后最少应收到的TokenA数量 
10echo 'amountBMin => ' . $order->amountAMin . PHP_EOL;    //滑点处理后最少应收到的TokenB数量

Order对象提供的以下值，有助于在执行委托单之前向用户提供更好的反馈信息：

amountA/amountB ：市价计算的tokenA或tokenB理想值
amountAMin/amountAMax ：滑点处理后的tokenA最小值/最大值
amountBMin/amountBMax ：滑点处理后的tokenB最小值/最大值

3.5 执行流动性委托单

使用SwapKit的 executeOrder() 方法即可执行生成的流动性委托单，最终完成流动性添加/移除交易。例如：

1$txid = $kit->executeOrder($trade);                      //执行委托单
2echo 'txid => ' . $txid . PHP_EOL;                       //显示交易ID

可以使用SwapKit对象的waitForConfirmation()方法等待交易确认，该方法在交易确认后返回true或false，分别表示交易成功执行或交易回滚。

例如：

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

3.6 查询仓位信息

使用SwapKit的 getExchangeLiquidityInfoForToken() 方法可以查询指定账号在指定token的流动池的仓位信息。例如查询某地址的持仓情况：

1$info = $kit->getExchangeLiquidityInfoForToken(        //查询持仓信息
2  $kit->getCredential()->address()->base58(),          //当前账号
3  'TENh4XGvTPEdceEVxiXoEfH9ufxyjYrSwn'                 //token地址
4);       
5
6echo 'total => ' . $info->totalSupply . PHP_EOL;       //LP总量 
7echo 'balance => ' . $info->balance . PHP_EOL;         //持仓数量
8echo 'share % => ' . $info->share . PHP_EOL;           //持仓比例

3.7 生成兑换交易对象

类似于流动性的添加与移除，在justswap中的交易对兑换也存在价格自动计算与滑点处理问题。为此，justswap.php开发包提供了一个专门的类 TradeBuilder用来简化这一操作。TradeBuilder内置了价格自动计算与滑点处理，因此调用者只需要设置基本的参数即可。

使用SwapKit对象的getTradeBuilder()方法获取预创建的TradeBuilder对象，例如：

1$tb = $kit->getTradeBuilder()              //获取预创建的兑换交易生成器
2          ->...                            //参数设置
3          ->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数量为基准生成一个兑换交易对象：

1$trade = $kit->getTradeBuilder()                     //获取兑换交易生成器
2             ->tradeType(Trade::EXACT_INPUT)         //以输入token数量为基准
3             ->tokenIn('0x...')                      //输入token
4             ->tokenOut('0x...')                     //输出token
5             ->amountIn(bn('10000000000000000000'))  //输入token的数量
6             ->slippage(bn('10'))                    //滑点容忍范围1%
7             ->to($kit->getDefaultAddress())         //输出token的接收地址
8             ->build();                              //生成兑换交易对象
9             
10echo 'amountIn => ' . $trade->amountIn . PHP_EOL;          //输入token的设置数量
11echo 'amountOut => ' . $trade->amountOut . PHP_EOL;        //自动做市算法得到的输出token的数量
12echo 'amountOutMin => ' . $trade->amountOutMin . PHP_EOL;  //滑点处理后的应收到的输出token最少数量

3.8 执行兑换交易

使用SwapKit对象的 executeTrade() 方法执行指定的兑换交易对象。例如：

1$txid = $kit->executeTrade($trade);                       //执行兑换交易
2echo 'txid => ' . $txid . PHP_EOL;                        //显示交易ID

可以使用SwapKit对象的waitForConfirmation()方法等待交易确认，该方法在交易确认后返回true或false，分别表示交易成功执行或交易回滚。

例如：

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

JustSwap.php官方下载地址：http://sc.hubwiz.com/codebag/justswap-php/

PHP应用对接Justswap专用开发包【JustSwap.PHP】

1、开发包概述

2、使用示例代码

2.1 编译合约

2.2 部署合约

2.3 创建流动池

2.4 Token授权

2.5 添加流动性

2.6 移除流动性

2.7 TRX/TRC20兑换：以输入TRX数量为基准

2.8 TRX/TRC20兑换：以输出token数量为基准

2.9 TRC20/TRX兑换：以输入token数量为基准

2.10 TRC20/TRX兑换：以输出TRX数量为基准

2.11 TRC20/TRC20兑换：以输入token数量为基准

2.12 TRC20/TRC20兑换：以输出token数量为基准

3、使用justswap.php开发包

3.1 实例化SwapKit

3.2 Credential：Tron身份与地址表示

3.3 创建流动池

3.4 生成流动性添加/移除委托单

3.5 执行流动性委托单

3.6 查询仓位信息

3.7 生成兑换交易对象

3.8 执行兑换交易

评论区

相关推荐