Ripple区块链对接PHP开发包【瑞波币/XRP】

时间 2019-11-13

原文原文链接

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

一、开发包概述

XrpTool主要包括如下特性：html

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

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

XrpTool开发包的主要代码文件清单参见官网说明：http://sc.hubwiz.com/codebag/xrp-php-lib/json

二、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交易类型参见官网说明：http://sc.hubwiz.com/codebag/xrp-php-lib/ui

2.3 示例：代币发行与转帐

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

在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转帐。

三、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，就会出现以下异常：

四、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/。