OmniTool開發包適用於爲PHP應用快速增加對Omni Layer/USDT數字資產的支持能力,即支持使用自有Omni Layer節點的應用場景,也支持基於第三方API服務和離線裸交易的輕量級部署場景。下載地址:omni/usdt php開發包 。
1、OmniTool開發包簡介
OmniTool開發包主要包含以下特性:
- 完善的Omni Layer節點RPC封裝
- 支持利用自有節點或第三方服務獲取指定地址的utxo集合
- 支持離線生成omni代幣轉賬裸交易
- 支持利用自有節點或第三方服務廣播裸交易
OmniTool支持本地部署的Omnicored節點,也支持blockchain.info、btc.com等提供的開放API,要增加對其他第三方服務的支持也非常簡單,只需要參考代碼實現如下接口:
- UtxoCollectorInterface:utxo收集器
- UtxoSelectorInterface:utxo篩選器
- BroadcasterInterface:裸交易廣播器
- ExplorerInterface:數據查詢接口
OmniTool軟件包運行在Php 7.1+環境下,當前版本1.0.0,主要類/接口及關係如下圖所示:
OmniTool的主要代碼文件清單參見:http://sc.hubwiz.com/codebag/omni-php-lib/
2、RpcClient類使用說明
RpcClient類封裝了Omni Layer的RPC接口協議。創建RpcClient對象時,需要傳入包含有效身份信息的節點RPC URL。例如,假設安裝在本機的omnicored節點軟件配置如下:
- rpcuser:user
- rpcpassword:123456
- rpcport:8332
那麼可以使用如下的代碼來實例化RpcClient:
use \OmniTool\RpcClient;
$client = new RpcClient(
'http://user:123456@localhost:8332' /*節點RPC接口的URL*/
);
Omni Core節點在Bitcoin原有的RPC接口之外,擴充了額外的接口用來操作Omni層的數據,這些擴展的RPC接口採用omni_
前綴以區隔於Bitcoin的原有RPC接口。爲了便於區隔這兩層的RPC調用,RpcClient引入了協議子模塊的概念,將Bitcoin的原始RPC接口和Omni的擴展RPC接口分別掛接到btc子模塊和omni子模塊。
例如,獲取某個地址的USDT代幣餘額需要使用Omni層的omni_getbalance調用,這個RPC調用對應於RpcClient實例的omni
子模塊的getBalance()
方法。下面的代碼獲取地址1EXoDusjGwvnjZUyKkxZ4UHEf77z6A5S4P
的USDT(資產ID:31)餘額:
$ret = $client->omni->getBalance(
'1EXoDusjGwvnjZUyKkxZ4UHEf77z6A5S4P', /*地址*/
31 /*資產ID:USDT*/
);
類似的,可以使用omni_send調用來執行簡單的USDT轉賬,這個調用對應於RpcClient實例的omni子模塊的send()
方法。下面的代碼從地址3M9qvHKtgARhqcMtM5cRT9VaiDJ5PSfQGY
向地址37FaKponF7zqoMLUjEiko25pDiuVH5YLEa
轉入100.0個USDT代幣:
$ret = $client->omni->send(
'3M9qvHKtgARhqcMtM5cRT9VaiDJ5PSfQGY', /*代幣轉出地址*/
'37FaKponF7zqoMLUjEiko25pDiuVH5YLEa', /*代幣轉入地址*/
31, /*代幣ID:USDT*/
"100.00" /*轉移的代幣數量*/
);
原有的bitoin層的RPC接口則可以通過RpcClient的btc子模塊來訪問。例如,使用listunspent調用來獲取本地節點中指定地址的utxo:
$ret = $client->btc->listUnspent(
6, /*最小確認數*/
999999, /*最大確認數*/
['mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe'] /*地址清單*/
);
開發包中的demo/rpc-demo.php
示例代碼使用RpcClient類完整演示了在Omni層的代幣發行與轉賬功能,如果你計劃搭建自己的Omni Core節點,相信這個示例會有很大幫助。
3、Wallet類使用說明
如果不願意搭建自己的Omni Core節點,而是希望基於第三方API爲自己的PHP應用增加對Omni Layer/USDT的支持,那麼最簡單的方法是使用離線交易的入口類Wallet。
Wallet類的主要作用是根據創建並廣播Omni代幣轉賬裸交易或比特幣轉賬裸交易,它的基本使用步驟如下:
- 使用
Wallet::cloud()
靜態方法創建一個支持雲端API服務的Wallet實例 - 使用
addKey()
方法將必要的私鑰加入該Wallet實例,例如轉出地址的私鑰,因爲Wallet需要利用私鑰對裸交易進行簽名 - 使用
omniSendTx()
方法生成Omni代幣轉賬裸交易,或者使用btcSendTx()
方法比特幣轉賬裸交易 - 使用
broadcast()
方法廣播裸交易
3.1 Omni代幣轉賬
使用Wallet實現的Omni代幣轉賬示例代碼如下,說明見註釋:
<?php
require('../vendor/autoload.php');
use OmniTool\Wallet; /*引入開發包*/
$wallet = Wallet::cloud(
'./demo.wallet', /*錢包文件地址,自動創建*/
'testnet' /*網絡ID*/
);
$prvKey = '4aec8e45106....00d5c5af494a4e05b'; /*私鑰:16進制字符串*/
$wallet->addKey($prvKey); /*將私鑰加入錢包,只需加入一次*/
$addressList = $wallet->getAddressList(); /*返回錢包管理的所有地址,數組*/
$rawtx = $wallet->omniSendTx(
$addressList[0], /*發送方地址,私鑰必須已經加入錢包*/
'mgYPLmNuZymK...e2XUNF6VFnT', /*接收方地址*/
2, /*轉賬OMNI代幣ID,2:TOMN*/
'0.000001' /*轉賬OMNI代幣數量*/
);
$ret = $wallet->broadcast($rawtx); /*廣播OMNI裸交易*/
var_dump($ret);
注意:
- Wallet實例利用錢包中的私鑰生成地址列表,並利用這些地址從第三方服務獲取utxo信息。 因此需要錢包中 的私鑰對應地址在鏈上有utxo存在,Wallet對象才能夠成功構造裸交易。
- 轉賬目標地址應當與創建Wallet對象時指定的鏈ID一致,例如mainnet的p2pkh地址,前綴應當爲1
3.2 指定Omni交易的手續費支付地址
在Omni協議層不需要支付交易手續費,但是Omni交易所嵌入的比特幣交易依然需要支付手續費。默認情況下omniSendTx()
方法使用發送方地址支付比特幣交易手續費,但可以傳入額外的參數來指定其他地址支付交易手續費,當你的PHP應用需要實現多賬戶歸集功能時,使用統一的手續費支付地址會更容易管理一些。
例如,下面的代碼使用地址mnRo8JyTHDd5NxRb3UvGbAhCBPQTQ4UZ8W
支付omni交易的手續費:
$rawtx = $wallet->omniSendTx(
$addressList[0], /*發送方地址,私鑰必須已經加入錢包*/
'mgYPLmNuZymK...e2XUNF6VFnT', /*接收方地址*/
2, /*轉賬OMNI代幣ID,2:TOMN*/
'0.000001', /*轉賬OMNI代幣數量*/
'mnRo8JyTHDd5...CBPQTQ4UZ8W' /*交易手續費支付地址*/
);
注意:
- 即使指定了餘額充足的手續費支付地址,Omni交易的發送方依然必須有微量的比特幣 餘額(546 SATOSHI),因爲Omni協議需要交易發送方至少有一個可用UTXO。
- 手續費支付地址同時也是找零地址,多餘的比特幣將返回至該地址
3.3 指定Omni交易的比特幣轉賬數量
由於Omni交易要求發送方必須有可用的UTXO,因此爲了便於接收Omni代幣的地址可以繼續流通所持有的Omni代幣,omniSendTx()
方法在默認情況下將向接收方地址轉入微量的比特幣(546 SATOSHI),可以在調用該方法時修改這個默認數值。
例如,下面的代碼轉入接收方1000個SATOSHI:
$rawtx = $wallet->omniSendTx(
$addressList[0], /*發送方地址,私鑰必須已經加入錢包*/
'mgYPLmNuZymK...e2XUNF6VFnT', /*接收方地址
2, /*轉賬OMNI代幣ID,2:TOMN*/
'0.000001', /*轉賬OMNI代幣數量*/
'mnRo8JyTHDd5...CBPQTQ4UZ8W', /*交易手續費支付地址*/
1000 /*轉賬比特幣數量,單位:SATOSHI*/
);
3.4 比特幣轉賬
OmniTool也支持比特幣轉賬裸交易的生成與廣播。
例如,下面的代碼從錢包的第一個地址向指定接受地址轉入1000個SATOSHI:
<?php
require('../vendor/autoload.php');
use OmniTool\Wallet;
$wallet = Wallet::cloud('./demo.wallet','testnet');
$addressList = $wallet->getAddressList();
$rawtx = $wallet->btcSendTx(
$addressList[0], /*發送方地址*/
'moneyqMan7u...8qVrc9ikLP', /*接收方地址*/
1000, /*轉賬比特幣數量,單位:SATOSHI*/
500 /*手續費,單位:SATOSHI*/
);
echo 'btc rawtx => ' . $rawtx . PHP_EOL;
$ret = $wallet->broadcast($rawtx); /*廣播裸交易*/
默認情況下,btcSendTx()
使用發送方地址作爲找零地址,也可以在調用時指定其他地址作爲找零地址,例如,下面的代碼創建一個新地址接收找零:
$changeAddress = $wallet->getNewAddress(); /*創建新地址*/
$rawtx = $wallet->btcSendTx(
$addressList[0], /*發送方地址*/
'moneyqMan7u...8qVrc9ikLP', /*接收方地址*/
1000, /*轉賬比特幣數量,單位:SATOSHI*/
500, /*手續費,單位:SATOSHI*/
$changeAddress /*找零地址*/
);
4、UTXO收集器
OmniTool使用接口UtxoCollectorInterface
來約定UTXO的收集功能。該接口的實現需要支持獲取指定地址的候選UTXO集合,可指定多個地址。
接口方法:
- collect($addressList):提取並返回候選UTXO集合
參數$addressList
用來聲明要收集UTXO的地址清單,類型爲數組。
當前實現類:
- CloudUtxoCollector:基於blockchain.com的開放API實現的Utxo收集器
- LocalUtxoCollector:基於omnicored節點RPC API實現的Utxo收集器
例如,下面的代碼使用CloudUtxoCollector獲取地址mi8BvbK73nDQfaN3acpaFGYQKhfQ5ysKRn
的UTXO:
use OmniTool\CloudUtxoCollector;
$collector = new CloudUtxoCollector(
'testnet' /*測試網*/
);
$candidateBag = $collector->collect(
['mi8BvbK73nDQ...KhfQ5ysKRn'] /*地址清單*/
);
5、UTXO篩選器
OmniTool使用UtxoSelectorInterface
來約定UTXO篩選功能。該接口的實現需要根據目標金額從候選UTXO中選擇可用UTXO,並返回新的UtxoBag實例。
接口方法:
- select($target,$candidates):選擇可消費UTXO,返回UtxoBag對象
參數$target
聲明要達成的最低金額目標,單位:wei。
參數$candidates
是候選的utxo集合,通常是UtxoCollectorInterface實現對象的collect()調用返回的UtxoBag對象。
當前實現類:
- DefaultUtxoSelector
例如下面的代碼使用DefaultUtxoSelector實例從候選UTXO中刪選出至少100000 wei 的UTXO:
use OmniTool\DefaultUtxoSelector;
$selector = new DefaultUtxoSelector();
$selectedBag = $selector->select(
100000, /*最低目標金額*/
$candidateBag /*候選UTXO集合*/
);
考慮到UTXO的不可分割性,篩選出的若干UTXO的總和,有可能超過目標金額。可以使用UtxoBag實例的getTotal()
方法查看集合中的UTXO總額:
echo 'total wei in bag => ' . $selectedBag->getTotal() . PHP_EOL;
6、裸交易廣播器
OmniTool使用BroadcasterInterface
來約定裸交易廣播的功能。該接口的實現應當將裸交易廣播到Omni網絡中。
接口方法:
- broadcast($rawtx):廣播裸交易
參數$rawtx
用來聲明要廣播的裸交易,類型爲16進制字符串。
當前實現類:
- CloudBroadcaster
- LocalBroadcaster
例如,下面的代碼使用CloudBroadcaster將裸交易碼流廣播到Omni網絡中:
use OmniTool\CloudBroadcaster;
$broadcaster = new CloudBroadcaster(
'testnet' /*測試網*/
);
$ret = $broadcaster->broadcast(
'01000000011da9283b4...59f58488ac00000000' /*裸交易*/
);
7、數據查詢接口
OmniTool使用ExplorerInterface
來約定Omni數據查詢功能。
接口方法:
- getBtcBalance($address):查詢指定地址的比特幣餘額
- getOmniBalance($address,$propertyId):查詢指定地址的Omni代幣餘額
當前實現類:
- CloudBroadcaster
- LocalBroadcaster
例如,下面的代碼使用CloudExplorer查詢地址1Jekm8ZswQmDhLFMp9cuYb1Kcq26riFp6m
的比特幣餘額與USDT代幣餘額:
use OmniTool\CloudExplorer;
$explorer = new CloudExplorer('mainnet');
$address = '1Jekm8ZswQmDhLFMp9cuYb1Kcq26riFp6m';
$balance = $explorer->getBtcBalance($address);
echo 'btc balance => ' . PHP_EOL;
$balance = $explorer->getOmniBalance($address,31);
echo 'usdt balance => ' . $balance['balance']. PHP_EOL;
OmniTool下載地址:http://sc.hubwiz.com/codebag/omni-php-lib/