Monero/XMR PHP开发包

MoneroTool是用于对接Monero区块链的PHP开发包，可以快速为PHP应用 添加门罗币/XMR的支持能力。MoneroTool的主要特点如下：

• 支持门罗币的全部RPC API调用接口
• 支持门罗币密钥对与地址的离线创建
• 支持门罗币专有格式助记词的生成与导入

MoneroTool运行于Php7.1+环境，当前版本1.0.0，主要代码文件清单如下：

代码文件	说明
monero.php/src/Gateway.php	Monero对接网关类
monero.php/src/RpcClient.php	Monero Rpc API封装类
monero.php/src/FaceValue.php	门罗币/XMR面值封装及面额转换类
monero.php/src/Mnemonic.php	Monero助记词实现类
monero.php/src/Credential.php	Monero身份凭证类
monero.php/src/Address.php	Monero标准地址类
monero.php/src/SubAddress.php	Monero子地址类
monero.php/src/IntegratedAddress.php	Monero整合地址类
monero.php/src/Utils.php	辅助工具类
demo/GatewayDemo.php	Gateway使用示例代码
demo/RpcClientDemo.php	RpcClient使用示例代码
demo/FaceValueDemo.php	FaceValue使用示例代码
demo/MnemonicDemo.php	Mnemonic使用示例代码
demo/CredentialDemo.php	Credential使用示例代码
demo/AddressDemo.php	Address/SubAddress/IntegratedAddress使用示例代码
vendors	第三方依赖包目录
composer.json	composer配置文件

1、Gateway - Monero对接网关

Gateway是对接Monero区块链的顶层类，适合管理多用户的地址及交易， 主要包括以下方法：

• newAddress()：创建新地址
• balance()：获取指定地址的XMR余额
• transfer()：转账

Gateway的实例化需要指定服务节点和钱包节点的URL，例如下面的代码 使用本机的Monero节点创建一个Gateway实例：

$opts = [
  'daemon_url' => 'http://localhost:28081',         //服务节点URL
  'wallet_url' => 'http://localhost:28083'          //钱包节点URL
];
$gateway = new Gateway($opts);                      //返回Gateway实例

1.1 创建新地址

使用Gateway的newAddress()方法为用户创建一个新的门罗币地址，例如：

$addr = $gateway->newAddress();                     //创建一个新的XMR地址
echo 'new address => ' . $addr . PHP_EOL;

1.2 获取地址余额

使用Gateway的balance()方法获取指定Monero地址的余额，例如：

$balance = $gateway->balance('9wviCeWe2D8XS82k2o....RrAotYPwq9Gm8');
echo 'total => ' . $balance->total . PHP_EOL;          //总余额，单位：piconero
echo 'unlocked => ' . $balance->unlocked . PHP_EOL;    //解冻余额，单位：piconero

balance()方法返回一个对象，total和unlocked字段分别表示 所查询地址的总余额和解锁余额，单位均为：piconero或pico。

1.3 门罗币转账

使用Gateway的transfer()方法在指定地址间转账。例如，下面的代码 从账户from向账户to转1000000 piconero ：

$from = '9wviCeWe2D8XS82k2ovp5...7X1D7Geoo2RrAotYPwq9Gm8';
$to = 'A2GmyHHJ9jtUhPiwoAbR2tX...uzKf6RGGgZTFTpVC4QxAiAX';
$amount = 1000000                                     //单位：piconero
$txid = $gateway->transfer($from,$to,$amount);
echo 'tx hash => ' . $txid . PHP_EOL;

transfer()方法返回转账交易的哈希。

piconero是门罗币最小的单位，1 minero = 10^12 piconero。

2、RpcClient - Rpc Api客户端

RpcClient是对Monero官方RPC协议的封装，用于在PHP应用中访问官方的 服务节点（Daemon）和钱包节点（Wallet），点击这里查看Monero的RPC API 中文文档。

创建一个RpcClient实例很简单，只需要传入节点的RPC API访问URL即可。 例如，下面的代码实例化一个RpcClient对象，这个对象的所有RPC调用请求 都会发往参数URL指定的Monero服务节点：

$daemon = new RpcClient('http://localhost:28081');      //返回客户端实例

2.1 调用JSON RPC API

对于节点中的JSON RPC API，可以直接以方法名进行调用。例如，服务节点提供 get_block_count 方法来获取链上区块的数量，使用RpcClient对象的调用方式如下：

$ret = $daemon->get_block_count();                    //调用同名JSON RPC API
echo 'block count => ' . $ret->count .  PHP_EOL;

如果JSON RPC API方法需要参数，例如服务节点提供的用来获取 区块数据的get_block方法， 就需要传入区块高度或区块哈希，那么将需要的参数组织成关联数组传入即可。 例如查看高度100#区块数据：

$ret = $daemon->get_block(['height'=>100]);
echo 'number of txs => ' . $ret->block_header->num_txes . PHP_EOL;

2.2 调用其他RPC API

Monero的服务节点也提供了非JSON RPC规范的其他访问接口，例如 按交易ID查询交易数据的方法/get_transactions。这些非JSON RPC 采用自己特定的访问端结点，因此我们可以使用RpcClient的post() 方法，来指定访问端结点和请求参数。

例如，下面的代码获取指定哈希a6fa....b8fs的交易数据：

$inputs = [
  'txs_hashes' => ['a6fa97b7c1d7a4f68a8041a2e7ca7a250d01391f14a0d5947b0936dca1f2b8f3']
];
$ret = $daemon->post('/get_transactions',$inputs);   //非JSON RPC APi调用
echo 'number of missed tx => ' . count($ret->missed_tx) . PHP_EOL;
echo 'number of found tx => ' . count($ret->txs) . PHP_EOL;

3、FaceValue - 门罗币面值

门罗币有不同的计量单位，从最小的原子单位piconero到最大的meganero：

FaceValue类封装了门罗币/XMR的面值计算逻辑，可以认为FaceValue 表示了包含计量单位的门罗币数量。因此在实例化一个FaceValue对象时， 需要同时指定数量和单位，例如，创建一个包含20.34个门罗币的FaceValue 对象来表征销售收入：

$sales = FaceValue::parse('20.34 mo');
echo 'sales => ' . $sales . PHP_EOL;                // 20.34 mo

FaceValue封装了门罗币的面值转换逻辑，因此可以得到上面的销售收入 转换为其他单位的数量：

echo 'sales in pico => ' . $sales->pico . PHP_EOL;  // 20.340000000000
echo 'sales in mega => ' . $sales->mega . PHP_EOL;  // 0.00002034

也可以直接更新指定的单位，例如将销售量更新为203.4 mo：

$sales->mo = 203.4; 
echo 'sales in mega => ' . $sales->mega . PHP_EOL;   // 0.0002034

4、Mnemonic - 助记词

使用Mnemonic类来创建Monero专有类型的助记词，或者将助记词转换为 密码学种子。Monero的助记词包含25个单词，词表也不同于比特币。 下面是一个Monero助记词的示例：

vipers opposite alpine debut rebel essential enigma irony 
moon incur fugitive tufts touchy moisture hijack chlorine vivid 
textbook chrome bias nimbly hamburger wayside tarnished tarnished

4.1 生成新的Monero助记词

Mnemonic提供了静态方法new()来生成新的助记词。例如，下面的代码 生成一组随机的新助记词：

$words = Mnemonic::new();
echo 'mnemonic => ' . $words . PHP_EOL;

4.2 将助记词转换为密码学种子

Mnemonic提供了静态方法seed()来将指定的助记词转换为密码学种子， 以便用于密钥对的恢复等操作。例如，下面的代码将助记词转换为密码学种子：

$seed = Mnemonic::seed('vipers opposite alpine debut rebel essential enigma irony moon incur fugitive tufts touchy moisture hijack chlorine vivid textbook chrome bias nimbly hamburger wayside tarnished tarnished');
echo 'seed => ' . $seed . PHP_EOL; //78bf0d6c8e877c8ffbf9701e8063a690a91295d6f3a576e7b61c8c7829d8a7e0

5、Credential

凭证类Crendential用来管理Monero区块链上的个人身份凭证 —— 密钥对：

5.1 生成随机身份

可以生成一个随机凭证，例如：

$credential = Credential::new();    //生成随机密钥对

5.2 重建身份凭证

也可以使用之前保存的助记词重建身份凭证，例如：

$seed = Mnemonic::seed('vipers opposite alpine debut rebel essential enigma irony moon incur fugitive tufts touchy moisture hijack chlorine vivid textbook chrome bias nimbly hamburger wayside tarnished tarnished');
$credential = Credential::infer($seed);  //从种子推导密钥对

5.3 消费密钥与查看密钥

门罗币是一种隐私货币，进入区块链的交易是经过加密混淆的，因此和 其他区块链相比，Monero需要两套密钥：消费密钥（spend key）和查看 密钥（view key），消费密钥类似于其他区块链中的身份标识密钥对，而 查看密钥则用户查看加密混淆的区块链交易，以便钱包跟踪交易输出。

例如，下面的代码查看凭证对象的消费密钥对和查看密钥对：

echo 'secret spend key => ' . $credential->secretSpendKey() . PHP_EOL;  
echo 'public spend key => ' . $credential->publicSendKey() . PHP_EOL;
echo 'secret view key => ' . $credential->secretViewKey() . PHP_EOL;
echo 'public view key => ' . $credential->publicViewKey() . PHP_EOL;

6、Address / SubAddress / IntegratedAddress

• Address：Monero区块链标准地址实现
• SubAddress：Monero区块链中的子地址实现，子地址由标准地址和两级索引序号推导得出
• IntegratedAddress：Monero区块链中的整合地址实现，整合地址由标准地址和支付ID推导得出

6.1 解码标准地址字符串

使用Address类的静态方法decode()解码地址字符串，返回的Address对象中 包含了解码后的信息。

例如，下面的代码解码指定的地址，并显示该地址所属网络、消费公钥和查看公钥：

$addr = Address::decode('9wviCeWe2D8XS82k2ovp5EUYLzBt9pYNW2LXUFsZiv8S3Mt21FZ5qQaAroko1enzw3eGr9qC7X1D7Geoo2RrAotYPwq9Gm8');
echo 'network => ' . $addr->network() . PHP_EOL;
echo 'spend key => ' . $addr->spendKey() . PHP_EOL;
echo 'view  key => ' . $addr->viewKey() . PHP_EOL;

6.2 地址的推导

调用Credential对象的address()方法，可以获得该凭证对象的门罗币地址。例如：

$addressMain = $credential->address('main');    //返回主网地址
echo 'address@mainnet => ' . $addressMain . PHP_EOL;
$addressMain = $credential->address('main');   //返回测试网地址
echo 'address@testnet => ' . $addressTest . PHP_EOL;

address()方法返回的是一个Address对象。

6.3 使用集成地址

使用Address对象的generateIntegratedAddress()方法，可以从标准地址 推导出集成地址IntegratedAddress对象：

$addr = $credential->address('test');
$ia = $addr->generateIntegratedAddress();
echo 'ia => ' . $ia . PHP_EOL;
echo 'ia payment id => ' . $ia->paymentId() . PHP_EOL;

集成地址适合商户的订单收费，通过为每个订单生成不同的支付ID，可以 避免生成大量的Monero凭证和标准地址。