Ripple區塊鏈對接PHP開發包【瑞波幣/XRP】
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/