Ripple协议PHP开发包

电玩女神 2022-08-29 05:48 174阅读 0赞

## 1、开发包概述 ##

XrpTool可以帮助PHP应用快速接入瑞波/Ripple区块链， 即支持部署自有Ripple 节点的应用场景，也支持利用公开的Ripple节点广播离线裸交易的轻量级部署场景。

XrpTool主要包括以下特性：

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

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

![569f9f2eef816db9ba4cf5a730173423.png][]

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

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

## 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余额

### 2.2 支持的交易类型 ###

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

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

### 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');   //使用测试链公开节点

### 3.2 调用RPC API ###

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

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

有的RPC API调用需要传入一些参数，例如查询账户信息的[account\_info][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`，就会出现如下异常：

![15763a2c5bfed7979812aaaa82b2dbf4.png][]

## 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;              //显示身份凭证的地址

[569f9f2eef816db9ba4cf5a730173423.png]: /images/20220829/902051d355f94275bbfe68f3f04e0a3d.png
[server_info]: https://xrpl.org/server_info.html
[account_info]: https://xrpl.org/account_info.html
[submit]: https://xrpl.org/submit.html
[15763a2c5bfed7979812aaaa82b2dbf4.png]: /images/20220829/63bae44e43b8490bbab7a6749976b5d7.png