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

2、XrpTool

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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余额

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 表示代币接收账户:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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 对应的节点:

1
2
3
use XrpTool\RpcClient;

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

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

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

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

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

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

3.2 调用RPC API

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

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

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

1
2
3
4
5
$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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$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对象:

1
2
3
use Xrp\Crypto\CrdlFactory;

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

4.1 创建新的身份凭证

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

1
2
3
4
5
$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算法创建身份凭证:

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

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

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

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