Ripple區塊鏈對接PHP開發包【瑞波幣/XRP】

XrpTool能夠幫助PHP應用快速接入瑞波/Ripple區塊鏈， 即支持部署自有Ripple節點的應用場景，也支持利用公開的Ripple節點廣播離線裸交易的輕量級部署場景。XrpTool官方下載地址：http://sc.hubwiz.com/codebag/xrp-php-lib/。

一、開發包概述

XrpTool主要包括如下特性：

• 全功能的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/

二、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/

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轉帳。

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