cover

Uniswap对接PHP开发包

汇智网 / hubwiz.com

为PHP应用快速增加Uniswap协议对接能力。

1、开发包概述

Uniswap.php 开发包适用于为PHP应用快速增加对Uniswap协议的支持能力。 即支持使用自有部署以太坊区块链节点的应用场景,也支持使用第三方节点的 轻量级部署场景。

Uniswap.php开发包主要包含以下特性:

  • 一键部署Uniswap协议,便于快速开发与测试
  • 支持Uniswap协议的全部接口,并提供开发人员友好的API
  • 支持ERC20/ERC20、ETH/ERC20等各种交易对的流动性添加、移除与兑换交易
  • 支持自动做市价格计算与滑点计算
  • 支持以太坊交易gas用量与gas价格的自动估算与手动设定
  • 支持EIP712签名授权,单一交易内完成流动性维护

Uniswap.php开发包运行在 Php 7.1+ 环境下,当前版本1.0.0,主要类/接口及关系如下图所示:

Uniswap.php uml

Uniswap.php开发包的主要代码文件清单如下:

代码文件说明
uniswap.php/src/SwapKit.phpUniswap.php开发包入口类
uniswap.php/src/OrderBuilder.php流动性维护订单构造器
uniswap.php/src/Order.php流动性维护订单类
uniswap.php/src/TradeBuilder.php兑换交易构造器
uniswap.php/src/Trade.php兑换交易类
uniswap.php/src/PermitSigner.phpEIP712签名实现类
uniswap.php/src/SmartContract.php智能合约封装类
uniswap.php/src/Transactor.php以太坊交易执行器
uniswap.php/src/Credential.php以太坊身份标识类
uniswap.php/src/Callback.php回调执行辅助类
uniswap.php/src/helper.php其他辅助函数
demo/config.php演示程序参数配置文件
deploy-contracts.phpUniswap及测试Token合约部署工具,可用于快速开发与测试
demo/add-liquidity.phpERC20/ERC20交易对流动性添加演示
demo/add-liquidity.phpERC20/ERC20交易对流动性添加演示
demo/add-liquidity-eth.phpERC20/ETH交易对流动性添加演示
demo/remove-liquidity.phpERC20/ERC20交易对流动性移除演示
demo/remove-liquidity-eth.phpERC20/ETH交易对流动性移除演示
demo/swap-exact-tokens-for-tokens.phpERC20/ERC20兑换演示,以输入token数量为基准
demo/swap-tokens-for-exact-tokens.phpERC20/ERC20兑换演示,以输出token数量为基准
demo/swap-exact-eth-for-tokens.phpETH/ERC20兑换演示,以输入eth数量为基准
demo/swap-eth-for-exact-tokens.phpETH/ERC20兑换演示,以输出token数量为基准
demo/swap-exact-tokens-for-eth.phpERC20/ETH兑换演示,以输入token数量为基准
demo/swap-tokens-for-exact-eth.phpERC20/ETH兑换演示,以输出eth数量为基准
contract/HappyToken.sol标准ERC20 token实现,开发测试用
contract/TetherToken.solTether/USDT实现,开发测试用
contract/UniswapV2Factory.solUniswap V2工厂合约实现
contract/UniswapV2Router02.solUniswap V2路由合约实现
contract/WETH9.solWETH9合约实现
bin/solc编译器目录
build-contract.sh合约编译脚本
vendor第三方依赖包目录
composer.jsoncomposer配置文件

2、使用示例代码

2.1 编译合约

在终端进入项目目录,执行如下命令编译Uniswap及开发包提供的测试Token合约:

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

执行结果如下:

uniswap.php build contracts

2.2 部署合约

首先在另一个终端启动开发私链:

~$ ganache-cli -d

然后进入项目demo目录,执行如下命令部署合约:

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

执行结果如下:

uniswap.php deploy contracts

注意 :如果需要在以太坊测试链,例如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

执行结果如下:

uniswap.php token approve

2.4 ERC20/ERC20交易对添加流动性

代码add-liquidity.php演示了如何为ERC20/ERC20交易对添加流动性。

在终端进入项目demo目录,执行如下命令:

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

执行结果如下:

uniswap.php add liquidity

Uniswap协议约定,第一次添加流动性将自动创建交易对 ,之后再次添加 流动性时,演示代码将首先显示当前的仓位信息。例如再次执行如下命令:

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

执行结果如下:

uniswap.php add liquidity

2.5 ERC20/ERC20交易对移除流动性

代码remove-liquidity.php演示了如何移除指定的ERC20/ERC20 交易对的流动性。

在终端进入项目demo目录,执行如下命令:

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

执行结果如下:

uniswap.php remove liquidity

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

执行结果如下:

uniswap.php swap exact tokens for tokens

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

执行结果如下:

uniswap.php swap tokens for exact tokens

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 add liquidity

第一次添加流动性将自动创建交易对,之后再次添加将首先显示 当前的持仓信息。例如再次执行如下命令:

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

执行结果如下:

uniswap.php add liquidity

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

执行结果如下:

uniswap.php remove liquidity

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

执行结果如下:

uniswap.php swap exact eth for tokens

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

执行结果如下:

uniswap.php swap eth for exact tokens

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

执行结果如下:

uniswap.php swap exact tokens for eth

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

执行结果如下:

uniswap.php swap tokens for exact eth

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 目前支持的以太坊网络及标识如下:


网络标识(SwapKit:: 合约标识(SwapKit::) 地址 说明
MAINNET FACTORY 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f 以太坊主网工厂合约
ROUTER 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D 以太坊主网路由合约
WETH 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 以太坊主网WETH9合约
ROPSTEN FACTORY 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f Ropsten测试网工厂合约
ROUTER 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D Ropsten测试网路由合约
WETH 0xc778417E063141139Fce010982780140Aa0cD5Ab Ropsten测试网WETH9合约
RINKEBY FACTORY 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f Rinkeby测试网工厂合约
ROUTER 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D Rinkeby测试网路由合约
WETH 0xc778417E063141139Fce010982780140Aa0cD5Ab Rinkeby测试网WETH9合约
GORLI FACTORY 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f Gorli测试网工厂合约
ROUTER 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D Gorli测试网路由合约
WETH 0xB4FBF271143F4FBf7B91A5ded31805e42b2208d6 Gorli测试网WETH9合约
KOVAN FACTORY 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f Kovan测试网工厂合约
ROUTER 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D Kovan测试网路由合约
WETH 0xd0A1E359811322d97991E03f863a0C30C2cF029C Kovan测试网WETH9合约

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);                //执行交易
¥5000.00
查看授权信息
  • 付费成功自动开通下载
  • 三个月内代码免费升级
  • 专业人员在线技术支持
  • 支持按需定制(另付费)
下载代码包
版本发布日期地址
1.0.0 2020-10-28
下载最新版
QQ咨询
2860991437
9+