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開發包的主要程式碼檔案清單參見官網說明：http://sc.hubwiz.com/codebag/xrp-php-lib/

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交易型別參見官網說明：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轉賬。

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/