Omni / USDT wallet butt PHP development package

OmniTool development kit for PHP application applies to a rapid increase in the ability to support Omni Layer / USDT digital assets that support the use of scenarios Own Omni Layer node also supports lightweight deployment scenarios based on third party API services and offline transactions bare . Download: Omni / USDT PHP development package .

1, OmniTool Development Kit Introduction

OmniTool Development Kit includes the following main features:

• Omni Layer comprehensive RPC package node
• Support Node using its own or third-party service to obtain a set of specified address utxo
• Support for offline generation omni transfer tokens naked trading
• Support Node using its own or third-party service broadcasting bare transaction

OmniTool support Omnicored local node deployments, and also supports blockchain.info, btc.com other open API provides, to add support for other third-party service is also very simple, only need to refer to code that implements the following interfaces:

• UtxoCollectorInterface: utxo collector
• UtxoSelectorInterface: utxo Filter
• BroadcasterInterface: bare transaction broadcaster
• ExplorerInterface: Data Query Interface

OmniTool package runs at ** Php 7.1 + ** environment, the current version 1.0.0, the main classes / interfaces and relationships as shown below:

The main code file list OmniTool as follows:

Code file	Explanation
omni.php/src/RpcClient.php	Omni Layer RPC protocol package type
omni.php/src/RpcModule.php	Omni Layer RPC protocol sub-module access syntactic sugar
omni.php/src/protocol-spec.json	Omni Layer protocol described in the meta information
omni.php/src/SerializeBuffer.php	Omni Layer protocol sequence of buffer
omni.php/src/PayloadFactory.php	Omni Layer protocol payload factory class
omni.php/src/Utxo.php	Output of consumer transaction categories not
omni.php/src/UtxoBag.php	Utxo collections
omni.php/src/UtxoCollectorInterface.php	Utxo collection interface
omni.php / src / LocalUtxoCollector.php	Utxo collector OmniCore node-based implementation
omni.php/src/CloudUtxoCollector.php	Based on third-party services Utxo collectors achieve
omni.php/src/UtxoSelectorInterface.php	Utxo Filter Interface
omni.php/src/DefaultUtxoSelector.php	The default filters achieve Utxo
omni.php/src/BroadcasterInterface.php	Bare trading Broadcast Interface
omni.php / src / LocalBroadcaster.php	Bare transaction broadcaster OmniCore node-based implementation
omni.php/src/CloudBroadcaster.php	Based on third-party service broadcaster bare transaction realization
omni.php/src/ExplorerInterface.php	Data Query Interface
omni.php/src/CloudExplorer.php	Third-party services-based data query interface
omni.php/src/LocalExplorer.php	Data query node-based interface OmniCore
omni.php/src/Utils.php	Common Helper
omni.php/src/Wallet.php	Offline purse class
demo/rpc-demo.php	RpcClient using the example of a complete implementation of issuance and transfer of tokens OMNI
demo/omni-tx-cloud.php	Create and broadcast Omni transfer tokens naked trading, using third-party cloud services API
demo/omni-tx-local.php	Create and broadcast Omni transfer tokens naked trading, using its own node
demo/btc-tx-cloud.php	Create and broadcast Bitcoin transfers naked trading, using third-party cloud services API
demo/btc-tx-local.php	Create and broadcast Bitcoin transfers naked trading, using its own node
demo/explorer-cloud.php	Query specified address Bitcoin balances / Omni token balance, use a third-party cloud services API
demo/explorer-local.php	Queries the specified address Bitcoin balances / Omni token balance, using its own node
demo/wallet-init.php	Local wallet initialization
demo/wallet-demo.php	Wallet loaded, bare transaction structure and Broadcasting
vendor	Third-party dependencies directory
composer.json	composer Profiles

2, RpcClient class instructions

RpcClient class encapsulates Omni Layer RPC interface protocol. When you create a RpcClient objects need to pass contain valid identity information node RPC URL. For example, assume omnicored node software is installed in the machine is as follows:

• rpcuser：user
• rpcpassword：123456
• rpcport：8332

You can use the following code to instantiate RpcClient:

use \OmniTool\RpcClient;

$client = new RpcClient(
            'http://user:123456@localhost:8332'   /*节点RPC接口的URL*/
          );
复制代码

Omni Core nodes existing outside Bitcoin RPC interface, additional expansion interface for operating the data Omni layer, these extended RPC interface uses omni_a prefix to the original segment in the Bitcoin RPC interface. In order to facilitate the two layers of RPC call segment, we are introduced RpcClient protocol submodule concept, the original Bitcoin RPC interface and Omni extended RPC interface to attach a sub-module and omni btc submodules.

For example, obtaining an address token USDT balance requires Omni layer omni_getbalance call, the RPC call instance corresponding RpcClient omnisubmodule getBalance()method. The following code fetches the address 1EXoDusjGwvnjZUyKkxZ4UHEf77z6A5S4Pof USDT (Asset ID: 31) Balance:

$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(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(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下载地址：sc.hubwiz.com/codebag/omn…

转载于:https://juejin.im/post/5cf91ad46fb9a07eb55f4d28