Zhifu Tron API

基于 iexbase/tron-api 二次开发的增强版波场（TRON）API接口库。提供更完善的功能和更稳定的表现，简化TRON区块链应用开发。

功能特性

完整的波场API支持 - 支持波场网络上的所有主要操作
增强的代币支持 - 全面支持TRC10和TRC20代币操作
能量和带宽管理 - 质押TRX获取能量和带宽的完整解决方案
高级交易功能 - 支持批量转账、能量估算等高级功能
钱包管理工具 - 提供完整的钱包创建、导入和验证功能
交易监控机制 - 实现自动充值检测和通知
完善的错误处理 - 提供更详细的错误信息和异常处理
丰富的示例代码 - 提供多种场景的实际应用示例
内存优化管理 - 自动清理缓存，适合高频调用和长时间运行的应用
底层库优化 - 自动修补底层库的内存泄漏问题

安装

# 标准安装
composer require zhifu/tron-api

# 如果安装过程中遇到扩展或PHP版本兼容性问题，可以使用以下命令忽略平台要求
composer require zhifu/tron-api --ignore-platform-reqs

底层库内存优化

从v1.0.6版本开始，我们添加了自动修补脚本来解决底层iexbase/tron-api库的内存泄漏问题：

安装或更新时会自动修补底层库
如果没有自动修补，可以手动运行修补脚本：
```
php vendor/zhifu/tron-api/scripts/patch-vendor.php
```
如果仍然遇到内存问题，可以尝试增加PHP内存限制：
```
ini_set('memory_limit', '2G');
```

如果遇到依赖问题，有以下几种解决方案：

GMP扩展问题

方案1：安装GMP扩展（推荐）

这是最佳方案，可以使用所有功能：

# Ubuntu/Debian
sudo apt-get install php7.4-gmp
sudo service apache2 restart

# CentOS/RHEL
sudo yum install php-gmp
sudo systemctl restart httpd

# macOS (使用Homebrew)
brew install php@7.4-gmp

方案2：在项目中绕过GMP扩展检查

如果无法安装GMP扩展，可以在项目的composer.json中添加如下配置：

{
    "config": {
        "platform": {
            "ext-gmp": "1.0.0"
        }
    }
}

PHP版本兼容性问题

本库支持PHP 7.4及以上版本。对于底层依赖iexbase/tron-api，我们兼容3.x, 4.x和5.x版本：

使用PHP 7.4：会自动选择兼容的3.x或4.x版本
使用PHP 8.0+：会优先使用最新的5.x版本

如果安装时遇到PHP版本兼容性问题，可以尝试以下方案：

# 方案1：在安装时忽略平台要求（不推荐）
composer require zhifu/tron-api --ignore-platform-reqs

# 方案2：在项目的composer.json中设置platform配置（推荐）
# 在composer.json中添加：
{
    "config": {
        "platform": {
            "php": "7.4.33"
        }
    }
}

注意：方案2会影响所有依赖的安装，确保这符合您的项目需求。

要求

支持以下PHP版本：

PHP 7.4 及以上
必须安装BCMath扩展（用于高精度计算）
使用钱包功能时需要安装GMP扩展（用于私钥生成和地址验证）

安装GMP扩展（可选，仅用于钱包功能）

如果您需要使用钱包创建、导入和验证功能，则需要安装GMP扩展：

对于Ubuntu/Debian：

sudo apt-get install php7.4-gmp
sudo service apache2 restart  # 或 php-fpm

对于CentOS/RHEL：

sudo yum install php-gmp
sudo systemctl restart httpd  # 或 php-fpm

对于macOS (使用Homebrew)：

brew install php@7.4-gmp

跳过GMP扩展检查（不推荐）

如果您确定不会使用钱包功能，可以在composer.json中添加以下配置来绕过GMP扩展检查：

{
    "config": {
        "platform": {
            "ext-gmp": "1.0.0"
        }
    }
}

内存优化和性能管理

本库针对高频调用和长时间运行的场景进行了内存优化，特别是TRC20合约操作。

自动缓存清理

从v1.0.5版本开始，TRC20合约转账操作会自动清理不需要的缓存数据：

// 无需手动管理缓存，转账后会自动清理
$contract = $tron->contract('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t');
$result = $contract->transfer('接收方地址', 10.5);
// 此时已自动清理缓存，释放内存

禁用自动清理

在某些特殊场景下，您可能希望禁用自动清理功能：

// 禁用自动清理功能
\Zhifu\TronAPI\TRC20Contract::setAutoCleaning(false);

// 执行多次操作...

// 操作完成后手动清理
\Zhifu\TronAPI\TRC20Contract::clearCache();

分批处理大批量操作

对于大批量转账或查询，库已内置分批处理机制：

// 批量转账时可以控制每批大小，默认为5
$contract = $tron->contract($usdtContract);
$results = $contract->batchTransfer($transfers, 3); // 每批处理3个转账

// 批量查询余额时也可以控制每批大小，默认为20
$balances = $contract->batchBalanceOf($addresses, true, 10); // 每批处理10个地址

长时间运行的应用

对于长时间运行的脚本或应用（如充值监控服务），建议定期手动清理：

// 每处理100个区块后清理一次
if ($blockCount % 100 === 0) {
    \Zhifu\TronAPI\TRC20Contract::clearCache();
}

基本用法

use Zhifu\TronAPI\Tron;

// 初始化节点提供者
$fullNode = 'https://api.trongrid.io';
$solidityNode = 'https://api.trongrid.io';
$eventServer = 'https://api.trongrid.io';

try {
    $tron = new Tron($fullNode, $solidityNode, $eventServer);
    
    // 设置地址
    $tron->setAddress('您的钱包地址');
    
    // 查询余额（以TRX为单位）
    $balance = $tron->getBalance(null, true);
    echo "余额: " . $balance . " TRX\n";
    
    // 查询USDT余额
    $usdtBalance = $tron->getUsdtBalance();
    echo "USDT余额: " . $usdtBalance . " USDT\n";
} catch (Exception $e) {
    echo "错误: " . $e->getMessage();
}

API密钥支持

当使用公共节点进行大量请求时，您可能需要使用API密钥来避免请求限制。

获取API密钥

在 TRON Grid 官网注册账户并获取API密钥。

设置API密钥

// 在创建Tron实例时设置API密钥
$apiKey = '您的TRON API密钥';
$tron = new Tron($fullNode, $solidityNode, $eventServer, null, $apiKey);

// 或者在实例创建后设置
$tron->setApiKey('您的TRON API密钥');

详细示例请参考 examples/api_key_demo.php。

钱包管理

创建新钱包

// 生成新钱包
$wallet = $tron->generateWallet();
echo "私钥: " . $wallet['privateKey'] . "\n";
echo "地址: " . $wallet['address'] . "\n";

从私钥导入钱包

// 从私钥获取地址
$privateKey = "您的私钥";
$addressInfo = $tron->getAddressFromPrivateKey($privateKey);
echo "地址: " . $addressInfo['address'] . "\n";

验证私钥与地址

// 验证私钥与地址是否匹配
$isValid = $tron->validatePrivateKey($privateKey, '地址');
echo "验证结果: " . ($isValid ? '匹配' : '不匹配') . "\n";

详细示例请参考 examples/wallet_demo.php。

TRC20代币操作

查询代币余额

// 查询USDT余额
$usdtBalance = $tron->getUsdtBalance('钱包地址');
echo "USDT余额: " . $usdtBalance . " USDT\n";

// 查询其他TRC20代币
$tokenContract = '代币合约地址';
$tokenBalance = $tron->getTokenBalance($tokenContract, '钱包地址');
echo "代币余额: " . $tokenBalance . "\n";

转账TRC20代币

// 设置发送方地址和私钥
$tron->setAddress('发送方地址');
$tron->setPrivateKey('私钥');

// 获取合约对象
$contract = $tron->contract('代币合约地址');

// 转账 - 自动设置安全的费用限制
$result = $contract->transfer('接收方地址', '金额');

// 检查结果
if (isset($result['result']) && $result['result'] === true) {
    echo "转账成功，交易ID: " . $result['txid'] . "\n";
} else {
    echo "转账失败\n";
}

详细转账示例请参考 examples/transfer_demo.php。

查询TRC20代币交易历史

// 设置API版本
$tron->setApiVersion('v1');

// 查询USDT交易记录
$usdtContract = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'; // USDT合约地址
$transactions = $tron->getTrc20TransactionsByAccount(
    '钱包地址',
    $usdtContract,
    20 // 查询条数
);

// 显示交易记录
foreach ($transactions['data'] as $tx) {
    echo "交易ID: " . $tx['transaction_id'] . "\n";
    echo "金额: " . $tx['value'] . "\n";
}

详细示例请参考 examples/trc20_transactions_demo.php。

自动充值检测

// 已处理的交易ID列表
$processedTxIds = [
    // 从数据库中获取已处理的交易ID
];

// 检查是否收到指定金额的USDT付款
$payment = $tron->checkTrc20Payment(
    '接收地址',
    'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // USDT合约地址
    100.00, // 预期金额
    3600000, // 检查最近1小时内的交易
    $processedTxIds
);

if ($payment) {
    echo "收到匹配的充值，金额: " . $payment['amount'] . " USDT\n";
}

质押TRX获取资源

波场网络上的交易需要消耗能量和带宽资源，可以通过质押TRX获取这些资源。

质押获取能量

// 设置钱包地址和私钥
$tron->setAddress('钱包地址');
$tron->setPrivateKey('私钥');

// 质押10个TRX获取能量
$result = $tron->freezeBalanceForEnergyV2(10);

if (isset($result['result']) && $result['result'] === true) {
    echo "质押成功，交易ID: " . $result['txid'] . "\n";
} else {
    echo "质押失败\n";
}

质押获取带宽

// 质押5个TRX获取带宽
$result = $tron->freezeBalanceForBandwidthV2(5);

解除质押

// 解除质押 (10 TRX, 能量)
$result = $tron->unfreezeBalanceV2(10, 1);

详细质押示例请参考 examples/stake_energy_demo.php。

能量估算

在转账前，可以估算交易所需的能量，避免因能量不足导致交易失败。

// 估算TRC20转账所需能量
$energyEstimate = $tron->estimateTrc20TransferEnergy(
    'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // USDT合约地址
    '接收方地址',
    10.5, // 转账金额
    '发送方地址'
);

echo "预估所需能量: " . $energyEstimate['energy_used'] . "\n";
echo "建议费用限制: " . $energyEstimate['suggested_fee_limit_trx'] . " TRX\n";

查询账户资源

// 查询账户的资源情况
$resources = $tron->getAccountResources('钱包地址');

echo "能量上限: " . ($resources['EnergyLimit'] ?? 0) . "\n";
echo "已使用能量: " . ($resources['EnergyUsed'] ?? 0) . "\n";
echo "带宽上限: " . ($resources['NetLimit'] ?? 0) . "\n";
echo "已使用带宽: " . ($resources['NetUsed'] ?? 0) . "\n";

批量操作

批量查询余额

// 批量查询USDT余额
$contract = $tron->contract('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t');
$balances = $contract->batchBalanceOf([
    'TJoq53NiXhrgC9G2KNvpKv2s6UkcdNRgFP',
    'TFpS9NJ4Djm29RTmax3VonXL8HumgrC4zW'
]);

foreach ($balances as $address => $balance) {
    echo $address . ": " . $balance . " USDT\n";
}

批量转账TRC20代币

// 设置发送方地址和私钥
$tron->setAddress('发送方地址');
$tron->setPrivateKey('私钥');

// 获取合约对象
$contract = $tron->contract('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t');

// 批量转账
$transfers = [
    ['to' => '接收方地址1', 'amount' => 1.5],
    ['to' => '接收方地址2', 'amount' => 2.3]
];

$results = $contract->batchTransfer($transfers);

foreach ($results as $result) {
    echo ($result['success'] ? "成功" : "失败") . "\n";
}

详细的批量转账示例请参考 examples/batch_transfer_usdt_demo.php。

示例文件说明

本库提供了多个示例文件，位于 examples/ 目录下：

basic_usage.php - 基本用法示例
wallet_demo.php - 钱包管理示例
balance_demo.php - 余额查询示例
transfer_demo.php - TRC20代币转账示例
batch_transfer_usdt_demo.php - TRC20代币批量转账示例
trc20_transactions_demo.php - TRC20交易记录查询示例
api_key_demo.php - API密钥使用示例
stake_energy_demo.php - 质押TRX获取能量示例
energy_guide.php - 能量使用指南
staking_guide.md - 质押指南文档
check_balance.php - 余额检查工具
trx_balance.php - TRX余额查询工具
production_balance.php - 生产环境余额查询示例

错误处理

本库提供了详细的错误信息和异常处理，使用 try-catch 捕获异常：

try {
    $result = $tron->send('接收方地址', 100);
} catch (TronException $e) {
    echo "Tron错误: " . $e->getMessage() . "\n";
    echo "错误代码: " . $e->getCode() . "\n";
} catch (Exception $e) {
    echo "一般错误: " . $e->getMessage() . "\n";
}

注意事项

节点选择 - 建议使用私有节点或付费API服务，公共节点可能会有请求限制和稳定性问题
费用设置 - TRC20转账时，确保设置适当的费用限制，避免因能量不足导致交易失败
API密钥 - 在生产环境中，强烈建议使用API密钥
质押操作 - 质押和解除质押操作在某些公共节点上可能受限，建议使用私有节点
能量管理 - 在进行TRC20交易前，确保账户有足够的能量或TRX余额

赞助

如果您觉得这个项目有帮助，可以给予赞助：

Tron(TRX): TJoq53NiXhrgC9G2KNvpKv2s6UkcdNRgFP

许可证

本项目采用 MIT 许可证

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LIB_INTEGRATION.md		LIB_INTEGRATION.md
LICENSE		LICENSE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
composer.json		composer.json
phpunit.xml.dist		phpunit.xml.dist

License

PandaTwo/tron-api

Folders and files

Latest commit

History

Repository files navigation