XrpTool - Ripple区块链对接PHP开发包

XrpTool可以帮助PHP应用快速接入瑞波/Ripple区块链， 即支持部署自有Ripple节点的应用场景，也支持利用公开的Ripple节点广播离线裸交易的轻量级部署场景。XrpTool官方下载地址：http://sc.hubwiz.com/codebag/xrp-php-lib/。

1、开发包概述

XrpTool主要包括以下特性：

• 全功能的Ripple节点客户端，支持完整的RPC API开发接口
• 支持离线生成Ripple密钥对和地址，支持Secp256k1和Ed25519密码学算法
• 支持Ripple交易的离线序列化与离线签名
• 支持瑞波币/XRP和自发行代币的直接转账，支持代币发行、币币交易、支票签发、资金托管等多种Ripple交易

XrpTool开发包运行在PHP 7.1+环境下， 当前版本1.0.0，主要类及关系如下：

XrpTool开发包的主要代码文件清单如下：

代码文件	说明
xrp.php/src/	XrpTool源代码目录
xrp.php/src/RpcClient.php	Ripple节点的RPC协议封装类
xrp.php/src/TxProcessor.php	Ripple交易处理器实现类
xrp.php/src/TxValidator.php	Ripple交易格式验证类
xrp.php/src/BinaryCodec.php	Ripple交易序列化编码器
xrp.php/src/AddressCodec.php	Ripple地址编解码器
xrp.php/src/Decimal.php	任意精度浮点数实现类
xrp.php/src/ExceptionHandler.php	异常处理实现类
xrp.php/src/Utils.php	辅助工具类
xrp.php/src/crypto/crdlFactory.php	Ripple身份凭证工厂类
xrp.php/src/crypto/CrdlSecp256k1.php	基于Secp256k1算法的Ripple身份凭证实现类
xrp.php/src/crypto/CrdlEd25519.php	基于Ed25519算法的Ripple身份凭证实现类
xrp.php/src/types/defintions.json	Ripple交易结构规范文件
xrp.php/src/types/Defintions.php	Ripple交易结构规范解析类
xrp.php/src/types/FieldFactory.php	Ripple交易字段工厂类
xrp.php/src/types/TypeInterface.php	Ripple交易数据类型接口
xrp.php/src/types/TypeBase.php	Ripple交易数据类型基类
xrp.php/src/types/AccountID.php	Ripple交易数据类型 - AccountID
xrp.php/src/types/Amount.php	Ripple交易数据类型 - Amount
xrp.php/src/types/Blob.php	Ripple交易数据类型 - Blob
xrp.php/src/types/Hash.php	Ripple交易数据类型 - Hash
xrp.php/src/types/Hash128.php	Ripple交易数据类型 - Hash128
xrp.php/src/types/Hash160.php	Ripple交易数据类型 - Hash160
xrp.php/src/types/Hash256.php	Ripple交易数据类型 - Hash256
xrp.php/src/types/PathSet.php	Ripple交易数据类型 - PathSet
xrp.php/src/types/STArray.php	Ripple交易数据类型 - STArray
xrp.php/src/types/STObject.php	Ripple交易数据类型 - STObject
xrp.php/src/types/UInt.php	Ripple交易数据类型 - UInt
xrp.php/src/types/UInt8.php	Ripple交易数据类型 - UInt8
xrp.php/src/types/UInt16.php	Ripple交易数据类型 - UInt16
xrp.php/src/types/UInt32.php	Ripple交易数据类型 - UInt32
xrp.php/src/types/UInt64.php	Ripple交易数据类型 - UInt64
demo/	演示代码目录
demo/xrptool-demo.php	XrpTool演示代码
demo/issue-demo.php	代币发行演示代码
demo/rpcclient-demo.php	RpcClient演示代码
demo/credential-demo.php	身份凭证创建/恢复/查询演示代码
demo/txprocessor-demo.php	TxProcessor演示代码
vendor/	第三方依赖包目录
composer.json	composer配置文件

2、XrpTool

XrpTool是开发包的入口类，可以利用它快速组织并广播一个交易，或者访问开发包的其他类的预创建实例对象。

2.1 交易的组织、签名与广播

在XrpTool中，一个Ripple交易的执行包含以下环节：

• 交易数据的组织，使用关联数组来组织交易数据
• 交易数据签名与广播，使用XrpTool实例的transact()方法进行交易 预处理、序列化和签名，最后提交给节点广播到网络中
• 等待交易确认

例如，下面的代码使用XrpTool完成瑞波币/XRP的直接支付交易：

use XrpTool\XrpTool; $tool = new XrpTool('https://s.altnet.rippletest.net:51234'); //使用测试链公开节点 //用密文恢复身份凭证 $credential = $tool->restoreCredential('snT3WxQbGLMAfqPhS9pYHM9gpib79'); //发起账号的身份凭证 //组织交易数据 $tx = [ 'TransactionType' => 'Payment', //交易类型：支付 'Account' => 'rfT5EnW5kfJNyLpUb6X9Do8HoUMvQKDrS8', //发起账号 'Destination' => 'rnU5a7v51BV6znn8kq8jdGtZNDiMJxojcc', //接收账号 'Amount' => '13500' //交易数量，单位：drop ]; //交易序列化、签名、提交 $txid = $tool->transact($tx,$credential); //提交给节点广播 echo "tx hash => " . $txid . PHP_EOL; //显示交易哈希 //等待交易确认 $validated = $tool->waitForTx($txid); //默认超时：5秒 echo "tx validated => " . $validated . PHP_EOL; //显示是否已确认 //查询接收账号的余额 $balance = $tool->getBalance($tx['Destination']); //检查接收账号的余额 echo "xrp balance => " . $balance->xrp . PHP_EOL; //显示XRP余额

XrpTool官方下载地址：http://sc.hubwiz.com/codebag/xrp-php-lib/。

2.2 支持的交易类型

XrpTool目前支持以下类型的Ripple交易：

Ripple交易类型	交易说明
AccountSet	设置账户选项。例如设置账户标志、设置所发行代币转账手续费率等
CheckCreate	创建支票。支票是一种延迟支付方式，接收账户可以将支票兑现
CheckCash	兑现支票。只有支票的接收账户可以将支票兑换为XRP或代币
CheckCancel	取消支票。被取消的支票将不再可兑现
DepositPreauth	充值预授权。当某个账户启用充值授权标志后，只有被预授权的账户才可以向该账户进行支付
EscrowCreate	创建托管支付。托管支付可视为暂时挂起的支付，只有当满足指定条件时，资金才会注入接收账户
EscrowFinish	完成托管支付。完成指定的托管支付，将资金释放给接收账户
EscrowCancel	取消托管支付。取消指定给的托管支付，将资金返还给发送账户
OfferCreate	交易所挂单。在Ripple内置的去中心化交易所中创建一个限价交易单，用于不同币种的兑换
OfferCancel	取消挂单。取消指定的兑换限价单
Payment	转账支付。从一个账户向另一个账户支付XRP或代币
PaymentChannelCreate	创建支付通道并注入XRP。支付通道是两个账户间的单向支付手段
PaymentChannelFund	支付通道充值。向指定的支付通道补充额外的XRP
PaymentChannelClaim	支付通道资金认领。从指定的支付通道提取XRP
SetRegularKey	管理账户的常规密钥对。常规密钥可以用来签名账户交易，减少主密钥的使用
TrustSet	管理账户间信任线。信任线用于Ripple区块链中的代币发行

2.3 示例：代币发行与转账

Ripple区块链支持任何用户发行代币，前提是得到别人的信任，这就是信任线/TrustLine的作用：
Ripple使用信任线来表示一个用户对另一个用户的有限的信任额度。

在Ripple区块链中发行代币有三个步骤：

• 启用发行账户的DefaultRipple标志
• 接收账户设置对发行账户的信任线
• 发行账户向接收账户转账代币

下面代码展示了如何使用XrpTool发行自定义代币，其中issuer表示发行账户，receiver表示代币接收账户：

use XrpTool\XrpTool; $tool = new XrpTool('https://s.altnet.rippletest.net:51234'); //使用测试链公开节点 $issuer_address = 'rfT5EnW5kfJNyLpUb6X9Do8HoUMvQKDrS8'; //发行账户地址 $issuer_secret = 'snT3WxQbGLMAfqPhS9pYHM9gpib79'; //发行账户密文 $receiver_address = 'rnU5a7v51BV6znn8kq8jdGtZNDiMJxojcc'; //接收账户地址 $receiver_secret = 'snfjzzfRtq3hPdZ2msjFUxRN1748B'; //接收账户密文 //启用发行账户的相关标志 $txi = [ 'TransactionType' => 'AccountSet', //交易类型：AccountSet 'Account' => $issuer_address, //交易发起账户 'SetFlag' => 8, //default-ripple //设置DefaultRipple标志 ]; $txid = $tool->transactWithSecret($txi,$issuer_secret); //提交交易 $tool->waitForTx($txid); //等待交易确认 //接收账户设置信任线 $txi = [ 'TransactionType' => 'TrustSet', //交易类型：TrustSet 'Account' => $receiver_address, //交易发起账户 'LimitAmount' => [ 'currency' => 'WIZ', //信任的代币名称：WIZ 'issuer' => $issuer_address, //信任的发行账户 'value' => '1000' //信任额度 ] ]; $txid = $tool->transactWithSecret($txi,$receiver_secret); //提交交易 $tool->waitForTx($txid); //等待交易确认 //发行代币 $txi = [ 'TransactionType' => 'Payment', //交易类型：Payment 'Account' => $issuer_address, //交易发起账户 'Destination' => $receiver_address, //代币接收账户 'Amount' => [ //代币金额 'currency' => 'WIZ', //代币名称 'value' => '15', //代币数量 'issuer' => $issuer_address //代币发行账户 ] ]; $txid = $tool->transactWithSecret($txi,$issuer_secret); //提交交易 $tool->waitForTx($txid); //等待交易确认 //查询代币余额 $balance = $tool->getBalance($receiver_address); //查询接收账户的代币余额 foreach($balance->issued as $issued) { echo "issuer => " . $issued->issuer . PHP_EOL; //代币发行账户 echo "currency => " . $issued->currency . PHP_EOL; //代币名称 echo "balance => " . $issued->balance . PHP_EOL; //代币余额 } 

可以看到，在Ripple中XRP转账和代币转账都使用Payment交易，区别仅在于Amount字段的值类型：如果值是一个关联数组，表示执行代币转账；如果是一个数值字符串，表示执行XRP转账。

3、RpcClient

RpcClient类封装了Ripple节点的RPC API接口协议，XrpTool实例通过rpcClient属性提供了预创建的RpcClient对象，也可以独立创建一个RpcClient实例。

3.1 实例化

实例化RpcClient需要指定节点的RPC API访问URL。例如，下面的代码创建一个连接本地Ripple节点的RpcClient实例，之后的RPC调用都将提交给这个URL对应的节点：

use XrpTool\RpcClient; $client = new RpcClient('http://localhost:51234'); //使用本地节点

注意：Ripple节点的RPC API的访问协议（http | https）与监听端口依赖于 配置文件。上面的代码假设本地Ripple节点RPC API已经配置了http协议访问，并且 在51234端口监听。

你也可以创建一个连接主链公开节点的RpcClient实例，例如：

$client = new RpcClient('https://s1.ripple.com:51234'); //使用主链公开节点

或者创建一个连接测试链公开节点的RpcClient实例，例如：

$client = new RpcClient('https://s.altnet.rippletest.net:51234'); //使用测试链公开节点

XrpTool官方下载地址：http://sc.hubwiz.com/codebag/xrp-php-lib/。

3.2 调用RPC API

RpcClient的方法名直接对应Ripple的RPC API名称，例如，如下的代码调用server_info接口查询Ripple节点信息：

$ret = $client->server_info(); //调用RPC API：server_info echo 'version => ' . $ret->info->build_version . PHP_EOL; //显示节点软件版本信息 

有的RPC API调用需要传入一些参数，例如查询账户信息的account_info调用，这时需要将参数整理为关联数组传入RpcClient对象的同名方法：

$params = [ //使用关联数组声明RPC API参数 'account' => 'rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn' //account: 要查询的账户 ]; $ret = $client->account_info($params); //查询指定Ripple账户的详细信息 echo 'balance => ' . $ret->account_data->Balance . PHP_EOL; //显示账户余额，单位：drop

3.3 示例：使用RPC API转账XRP

如果你使用自己的Ripple节点，可以使用submit调用的Sign-and-Submit模式执行转账等交易。例如，使用下面的代码从Alice的账号向Bob的账号支付0.0123456 XRP：

$alice = "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"; //Alice的账户 $bob = "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX"; //Bob的账户 $amount = "123456"; //单位：drop $params = [ "offline" => false, //需要节点签名 "secret" => "s████████████████████████████", //用于签名的密码 "tx_json" => [ "TransactionType": "Payment", //交易类型：支付 "Account" => $alice, //发起账号 "Destination": $bob, //接收账号 "Amount" => $amount //支付数量，单位：drop ] ]; $ret = $client->submit($params); //签名并广播交易 echo 'tx hash => ' . $ret->tx_json->hash . PHP_EOL; //交易哈希

注意：默认情况下submit调用的sign-and-submit模式只允许在节点管理连接上调用，要正确执行 上面的代码，你需要使用管理连接创建RpcClient实例，或者为该节点启用公共签名支持。如果你 执行demo/rpcclient-demo.php，就会出现如下异常：

4、Credential

和其他区块链一样，Ripple也使用非对称密钥对来标识身份，不过它即支持经典的Secp256k1算法，也支持更新一些的Ed25519算法，XrpTool开发包分别使用CrdlSecp256k1类和CrdlEd25519类来表征这两种算法对应的Ripple身份凭证。

可以使用CrdlFacotry工厂类来离线创建新的Ripple密钥对和地址，或者使用Ripple密文来恢复之前创建的密钥对和地址。XrpTool对象的crdlFactory属性提供了预创建的CrdlFactory对象，也可以用如下的代码直接创建CrdlFactory对象：

use Xrp\Crypto\CrdlFactory; $cf = new CrdlFactory(); //创建身份凭证工厂对象

4.1 创建新的身份凭证

使用generate()方法来创建一个新的随机密钥对并推导出相应的Ripple地址。例如，下面的代码使用Secp256k1算法创建一个Ripple身份凭证：

$credential = $cf->generate(); //使用secp256k1算法创建随机身份凭证 //$credential = $cf->generate('secp256k1'); //同上，默认使用secp256k1算法 echo 'private => ' . $credential->private . PHP_EOL; //显示身份凭证的私钥 echo 'public => ' . $credential->public . PHP_EOL; //显示身份凭证的公钥 echo 'address => ' . $credential->address . PHP_EOL; //显示身份凭证的地址

类似的，下面的代码使用ed25519算法创建身份凭证：

$credential = $cf->generate('ed25519'); //使用ed25519算法创建随机身份凭证 echo 'address => ' . $credential->address . PHP_EOL; //显示身份凭证的地址

4.2 使用Ripple密文恢复身份凭证

如果持有身份凭证密文，那么可以使用fromSecret()方法来恢复对应的Ripple身份凭证。例如：

$secret = 'snfjzzfRtq3hPdZ2msjFUxRN1748B'; //Ripple身份凭证密文 $credential = $cf->fromSecret($secret); //利用密码恢复身份凭证 echo 'address => ' . $credential->address . PHP_EOL; //显示身份凭证的地址

XrpTool官方下载地址：http://sc.hubwiz.com/codebag/xrp-php-lib/。