为PHP应用快速增加Uniswap协议对接能力。
JustSwap.php 开发包适用于为PHP应用快速增加对JustSwap协议的支持能力。 即支持使用自有部署Tron区块链节点的应用场景,也支持使用第三方节点的 轻量级部署场景。
JustSwap.php开发包主要包含以下特性:
JustSwap.php开发包运行在 Php 7.1+ 环境下,当前版本1.0.0,主要类/接口及关系如下图所示:
JustSwap.php开发包的主要代码文件清单如下:
代码文件 | 说明 |
---|---|
justswap.php/src/SwapKit.php | JustSwap.php开发包入口类 |
justswap.php/src/OrderBuilder.php | JustSwap流动性订单构造器 |
justswap.php/src/Order.php | JustSwap流动性订单类 |
justswap.php/src/TradeBuilder.php | JustSwap兑换交易构造器 |
justswap.php/src/Trade.php | JustSwap兑换交易类 |
justswap.php/src/Contract.php | Tron智能合约类 |
justswap.php/src/TronApi.php | Tron多节点API封装 |
justswap.php/src/NodeClient.php | Tron节点客户端 |
justswap.php/src/Credential.php | Tron身份标识类 |
justswap.php/src/Address.php | Tron地址类 |
justswap.php/src/helper.php | 其他辅助函数 |
demo/config.php | JustSwap.php开发包演示程序参数配置文件 |
demo/deploy-contracts.php | justswap协议及测试Token合约部署工具,可用于快速开发与测试 |
demo/create-exchange.php | justswap流动池创建演示 |
demo/approve-token.php | TRC20 token授权演示 |
demo/add-liquidity.php | justswap流动性添加演示 |
demo/remove-liquidity.php | justswap流动性移除演示 |
demo/swap-exact-tokens-for-tokens.php | TRC20/TRC20兑换演示,以输入token数量为基准 |
demo/swap-tokens-for-exact-tokens.php | TRC20/TRC20兑换演示,以输出token数量为基准 |
demo/swap-exact-eth-for-tokens.php | TRX/TRC20兑换演示,以输入trx数量为基准 |
demo/swap-eth-for-exact-tokens.php | TRX/TRC20兑换演示,以输出token数量为基准 |
demo/swap-exact-tokens-for-eth.php | TRC20/TRX兑换演示,以输入token数量为基准 |
demo/swap-tokens-for-exact-eth.php | TRC20/TRX兑换演示,以输出trx数量为基准 |
contract/HubToken.sol | 标准TRC20 token实现,开发测试用 |
contract/WizToken.sol | 标准TRC20RC20 token实现,开发测试用 |
contract/JustswapFactory.sol | justswap工厂合约实现 |
contract/JustswapExchange.sol | justswap交易合约实现 |
bin/build-contract | 合约编译脚本 |
vendor | 第三方依赖包目录 |
composer.json | composer配置文件 |
在终端进入项目目录,执行如下命令编译开发包提供的JustSwap协议及测试用Token合约:
~$ cd ~/justswap.php
~/justswap.php$ ./bin/build-contracts
执行结果如下:
进入项目demo目录,执行如下命令部署合约:
~/justswap.php/demo$ php deploy-contracts.php
上述命令将部署完整的JustSwap协议和测试用的HubToken 与WizToken,并将合约部署地址记录在项目demo目录下的 addresses.json 文件中。
合约部署脚本的执行结果如下:
注意 :部署前需要先设置demo/config.php中的部署账号。
代码create-exchange.php
演示了如何创建TRX/TRC20流动池。
在终端进入项目demo目录,执行如下命令:
~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php create-exchange.php
执行结果如下:
代码approve-token.php
演示了如何授权justswap Exchange合约代理操作
当前账号的HUB token和WIZ token。
在终端进入项目demo目录,执行如下命令:
~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php approve-token.php
执行结果如下:
代码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
执行结果如下:
代码remove-liquidity.php
演示了如何移除指定流动池的流动性。
可以使用参数hub或wiz指定要移除流动性的池。
在终端进入项目demo目录,执行如下命令从TRX/HUB池溢出25%流动性:
~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php remove-liquidity.php hub
执行结果如下:
代码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
执行结果如下:
代码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
执行结果如下:
代码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
执行结果如下:
代码swap-tokens-for-exact-trx.php
演示了如何将ERC20
token兑换为指定数量的ETH。可以使用参数hub或wiz指定要兑换的token。
在终端进入项目demo目录,执行如下命令用HUB兑换回1 TRX:
~$ cd ~/justswap.php/demo
~/justswap.php/demo$ php swap-tokens-for-exact-trx.php hub
执行结果如下:
代码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
执行结果如下:
代码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
执行结果如下:
SwapKit 是开发包的入口,使用SwapKit类可以快速实现如下功能:
SwapKit实例化需要传入三个参数:
Credential
对象例如,下面的代码创建一个接入Tron主网justswap协议的SwapKit实例:
//use JustSwap\TronApi;
//use JustSwap\Credential;
//use JustSwap\SwapKit;
$kit = new SwapKit(
TronApi::mainNet(), //Tron主网
Credential::fromPrivateKey('4f3e...3b1d'), //默认执行账号,指定私钥
'TXk8rQSAvPvBBNtqSoY6nCfsXWCSSpTVQF', //justswap工厂合约地址
);
在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; //显示相应地址
使用JustSwap工厂实例的createExchange()
方法创建流动池,例如:
$tokenAddr='TRbojfoxNQ2HcJPM85rY5N34aQFafEXZMA'; //代币地址
$txid = $kit->getFactory()->createExchange($tokenAddr, []);
echo 'txid => ' . $txid . PHP_EOL;
由于justswap协议中涉及到交易滑点处理以及价格预计算,因此 justswap.php提供了一个专门的类 OrderBuilder 用于生成 流动性添加/移除委托单。OrderBuilder的实现内置了自动价格计算与 滑点计算,因此调用者只需要指定基本的数据即可生成可提交给 justswap合约的流动性添加/移除委托单。
使用SwapKit对象的getOrderBuilder()
方法获取预创建
的OrderBuilder对象,并调用OrderBuilder的build()
方法生成委托单。例如:
$order = $kit->getOrderBuilder() //返回OrderBuilder对象
->.... //参数设置
->build(); //生成并返回委托单
OrderBuilder对象提供了以下方法用于调整生成器的行为:
Order::LIQUIDITY_ADD
- 流动性添加委托单Order::LIQUIDITY_REMOVE
- 流动性移除委托单SwapKit::TRX_TOKEN
表示TRX,并且对justswap协议来说tokenA
必须设置为TRX,即SwapKit::TRX_TOKEN例如,下面的代码生成一个流动性添加委托单:
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最小可接受数量
注意:
T9yD14Nj9j7xAB4dbGeiX9h8vMa2GfnLve
bn($numstr)
是justswap提供的一个创建 BigInteger 对象
的快捷函数,其参数为10进制字符串。类似的,下面的代码生成一个流动性移除委托单:
$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对象提供的以下值,有助于在执行委托单之前向用户提供更好的 反馈信息:
使用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;
使用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; //持仓比例
类似于流动性的添加与移除,在justswap中的交易对兑换也存在价格自动计算与滑点 处理问题。为此,justswap.php开发包提供了一个专门的类 TradeBuilder 用来简化这一操作。TradeBuilder内置了价格自动计算与滑点处理,因此 调用者只需要设置基本的参数即可。
使用SwapKit对象的getTradeBuilder()
方法获取预创建的TradeBuilder
对象,例如:
$tb = $kit->getTradeBuilder() //获取预创建的兑换交易生成器
->... //参数设置
->build(); //生成兑换交易对象
TradeBuilder提供了以下方法用于调整生成器的行为:
Trade::EXACT_INPUT
- 以tokenIn的数量为基准Trade::EXACT_OUTPUT
- 以tokenOut的数量为基准EXACT_INPUT
时需要设置EXACT_OUTPUT
时需要设置 例如,下面的代码以输入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最少数量
使用SwapKit对象的 executeTrade() 方法执行指定的兑换交易对象。 例如:
$txid = $kit->executeTrade($trade); //执行兑换交易
echo 'txid => ' . $txid . PHP_EOL; //显示交易ID
可以使用SwapKit对象的waitForConfirmation()
方法等待交易确认,
该方法在交易确认后返回true或false,分别表示交易成功执行或交易回滚。
例如:
$success = $kit->waitForConfirmation($txid);
echo 'success => ' . $success . PHP_EOL;
本站所提供软件包仅用于学习和研究,请依法合规使用。
本站所提供软件包均提供完整源码,使用前请认真阅读源代码和文档以确保充分理解软件包的设计与功能实现,本站不承担 因不当使用本站所提供软件包而造成的任何法律风险或财产损失责任。