比特币（BTC）作为最知名的加密货币，其钱包开发一直是开发者关注的焦点，在 PHP 环境下，如何与比特币核心客户端（或兼容的比特币节点）进行交互，从而实现一个基础的 BTC 钱包功能呢？JSON-RPC（Remote Procedure Call）提供了一种轻量级、高效的解决方案，本文将详细介绍如何利用 PHP 通过 JSON-RPC 协议开发 BTC 钱包的核心功能。

准备工作

在开始之前,你需要确保以下环境已经准备就绪：

1. 比特币核心客户端：在你的服务器或本地机器上安装并运行比特币核心客户端，首次运行会同步整个比特币区块链，这可能需要较长时间和大量磁盘空间，同步完成后，比特币核心会通过 JSON-RPC 接口提供服务。
2. 启用 JSON-RPC 接口：
   • 关闭比特币核心客户端。
   • 找到配置文件 bitcoin.conf（通常位于比特币数据目录下，如 ~/.bitcoin/bitcoin.conf 在 Linux/Mac，或 %APPDATA%\Bitcoin\ 在 Windows）。
   • 在配置文件中添加或修改以下内容：

     server=1  # 启用 JSON-RPC 服务器
     rpcuser=your_rpc_username  # 设置 RPC 用户名
     rpcpassword=your_rpc_password  # 设置 RPC 密码，务必复杂
     rpcallowip=127.0.0.1 
          # 允许连接的 IP 地址，开发时可设为 127.0.0.1，生产环境需谨慎设置
     # 可选：指定 RPC 端口，默认为 8332
     # rpcport=8332

   • 保存配置文件并重新启动比特币核心客户端。
3. PHP 环境：确保你的系统已安装 PHP，并且支持 cURL 扩展（用于发送 HTTP 请求），可以通过 php -m | grep curl 检查。

PHP 与 JSON-RPC 交互基础

比特币核心的 JSON-RPC 接口允许我们发送特定的命令（如获取余额、转账等）并接收 JSON 格式的响应，PHP 中，我们可以使用 cURL 库来发送这些请求。

我们可以封装一个发送 JSON-RPC 请求的函数，提高代码复用性：

<?php
/**
 * 发送 JSON-RPC 请求到比特币核心
 * @param string $method RPC 方法名
 * @param array $params 方法参数
 * @return array|false 响应数据或失败时返回 false
 */
function btcRpcCall($method, $params = []) {
    $rpcUrl = 'http://127.0.0.1:8332/'; // Bitcoin RPC URL
    $rpcUser = 'your_rpc_username';    // bitcoin.conf 中设置的 rpcuser
    $rpcPass = 'your_rpc_password';    // bitcoin.conf 中设置的 rpcpassword
    $data = [
        'jsonrpc' => '2.0',
        'method' => $method,
        'params' => $params,
        'id' => uniqid(), // 请求 ID，用于匹配响应
    ];
    $options = [
        CURLOPT_URL => $rpcUrl,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($data),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'Authorization: Basic ' . base64_encode($rpcUser . ':' . $rpcPass),
        ],
        CURLOPT_TIMEOUT => 10, // 超时时间，秒
    ];
    $ch = curl_init();
    curl_setopt_array($ch, $options);
    $response = curl_exec($ch);
    if (curl_errno($ch)) {
        error_log('cURL Error: ' . curl_error($ch));
        curl_close($ch);
        return false;
    }
    curl_close($ch);
    $result = json_decode($response, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        error_log('JSON Decode Error: ' . json_last_error_msg());
        return false;
    }
    // 检查 RPC 响应中是否有错误
    if (isset($result['error'])) {
        error_log('Bitcoin RPC Error: ' . $result['error']['message'] . ' (' . $result['error']['code'] . ')');
        return false;
    }
    return $result['result'] ?? false;
}
?>

开发 BTC 钱包核心功能

有了 btcRpcCall 函数，我们就可以开始实现 BTC 钱包的一些基本功能了。

1. 获取钱包信息

   • 功能：获取钱包的基本信息，如版本、余额、区块高度等。
   • RPC 方法：getwalletinfo
   • PHP 实现：

     $walletInfo = btcRpcCall('getwalletinfo');
     if ($walletInfo) {
         echo "钱包余额 (BTC): " . $walletInfo['balance'] . "\n";
         echo "钱包余额 (未确认): " . $walletInfo['unconfirmed_balance'] . "\n";
         echo "当前区块高度: " . $walletInfo['block_height'] . "\n";
         print_r($walletInfo);
     }

2. 生成新地址

   • 功能：在钱包中生成一个新的 BTC 地址，用于接收比特币。
   • RPC 方法：getnewaddress [可选参数：标签]
   • PHP 实现：

     $newAddress = btcRpcCall('getnewaddress', ['my_new_address']);
     if ($newAddress) {
         echo "新生成的 BTC 地址: " . $newAddress . "\n";
     }

3. 查询地址余额

   • 功能：查询指定 BTC 地址的余额。
   • RPC 方法：getaddressinfo [参数：地址]
   • PHP 实现：

     $addressToCheck = '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'; // 示例地址
     $addressInfo = btcRpcCall('getaddressinfo', [$addressToCheck]);
     if ($addressInfo && isset($addressInfo['balance'])) {
         echo "地址 {$addressToCheck} 的余额: " . $addressInfo['balance'] . " BTC\n";
     }

4. 发送比特币

   • 功能：从钱包向指定地址发送比特币。

   • RPC 方法：sendtoaddress [参数：地址，数量，可选：注释，可选：注释到，可选：替代费率]

   • PHP 实现：

     $toAddress = '1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2'; // 示例接收地址
     $amount = 0.01; // 发送数量 (BTC)
     $comment = 'PHP 测试转账';
     $txid = btcRpcCall('sendtoaddress', [$toAddress, $amount, $comment]);
     if ($txid) {
         echo "转账成功！交易ID: " . $txid . "\n";
         // 可以通过交易ID查询交易详情
         // $txDetails = btcRpcCall('gettransaction', [$txid]);
         // print_r($txDetails);
     }

5. 查询交易详情

   • 功能：根据交易ID（TXID）查询交易的详细信息。
   • RPC 方法：gettransaction [参数：交易ID]
   • PHP 实现：

     $txid = '你的交易ID'; // 替换为实际的交易ID
     $transactionDetails = btcRpcCall('gettransaction', [$txid]);
     if ($transactionDetails) {
         echo "交易详情:\n";
         print_r($transactionDetails);
     }

6. 列出交易

   • 功能：列出钱包中的最近交易。
   • RPC 方法：listtransactions [可选：参数，可选：计数，可选：从]
   • PHP 实现：

     $transactions = btcRpcCall('listtransactions', ['', 10, 0]); // 最近10笔交易
     if ($transactions) {
         echo "最近交易列表:\n";
         foreach ($transactions as $tx) {
             echo "ID: " . $tx['txid'] . ", 金额: " . $tx['amount'] . ", 分类: " . $tx['category'] . ", 时间: " . date('Y-m-d H:i:s', $tx['time']) . "\n";
         }
     }

安全注意事项

1. RPC 凭据安全：rpcuser 和 rpcpassword 是极其敏感