智能合约异常排查

📘

前置阅读

• 智能合约开发简介
• 虚拟机 TVM 异常处理机制

本文汇总在 TRON 上编写或调用智能合约时最常遇到的运行时（Runtime）错误。每个错误板块按**“根本原因 → 现象确认 → 修复步骤”**三段式归纳。

若要查阅 TRON 协议底层的完整异常分类体系，请参阅虚拟机 TVM 异常处理机制。

---

OUT_OF_TIME —— 合约执行超过 80 毫秒限制

根本原因

合约函数的 CPU 计算时间超出了单笔交易的系统执行时间预算。一旦触发 OUT_OF_TIME，系统会将其判定为类似于 assert 的故障，导致发起本次交易所设定的 fee_limit 额度被全额扣光。
目前主网单笔 CPU 时间预算为 80 毫秒(对应动态链参数 #13,调用 getMaxCpuTimeOfOneTx 查询)。超级代表(SR)委员会可发起治理提议动态调整该值,因此切勿在代码中硬编码 80 毫秒。

📘

说明

相同的合约调用在不同时间或不同节点下时而触发 OUT_OF_TIME、时而通过,说明执行耗时处于临界边界：不同超级代表(SR)主机的 CPU 性能有微弱差异,部分调用越界、另一些恰好通过。

推荐的开发优化方案

• 合约拆分：将高开销合约拆分为多个较小的子合约，并通过跨合约调用（Cross-contract Call）进行业务流转。每次发生跨合约调用时，虚拟机会重新分配 80 毫秒的 CPU 执行时间预算。
• 以迭代替代递归:在编写 Solidity 逻辑时，尽量使用 for 迭代循环代替递归函数，因为迭代在资源开销和 CPU 耗时上都更为廉价。
• 避免对存储数组进行无界循环：这是导致超时最常见的设计失误。请避免直接对未设上限的动态数组执行遍历。建议对数据进行链下缓存、在合约端采用分页查询，或者将复杂的统计计算工作转移至链下处理。
• 真实数据测试:在 Shasta 或 Nile 测试网中部署并使用与生产环境同等规模的数据集进行耗时预估，避免仅使用轻量级 Mock 数据测试。
• 合理设定 fee_limit:根据合约的实际最大开销上限来科学设定 fee_limit 参数，设置过高的 fee_limit 会导致单次 OUT_OF_TIME 发生时损失不必要的 TRX。

关于本地私网环境如何临时放开 80 毫秒超时限制，请参阅节点运维常见故障——调试模式绕过 CPU 执行限制。

---

REVERT —— 合约逻辑主动中止与回滚

根本原因

合约执行中触发了 require 或 revert 断言校验，按业务逻辑主动中止并回滚状态。与扣光预算的错误不同，触发 REVERT 只扣除已产生的实际 Energy，未使用的 fee_limit 余额全额退还给调用账户。

推荐的诊断排查流

1. 查验交易回执的 contractResult 字段:
   通过调用 /wallet/gettransactioninfobyid 接口检查交易收据。接口返回的十六进制编码错误原因排布在标准的 Error(string) 函数选择器（即 0x08c379a0 字符）之后。

   • 示例响应:
     JSON

     "contractResult": [
       "08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001e536166654d6174683a207375627472616374696f6e206f766572666c6f770000"
     ]

     剔除偏移量与长度字节码，将剩余十六进制 1e536166654d6174683a207375627472616374696f6e206f766572666c6f77 解码为 UTF-8 字符串，即可还原出失败原因：SafeMath: subtraction overflow（安全数学计算减法溢出，通常因为发送方余额不足以扣减）。

2. contractResult 字段为空:
   通常是合约触发了未定义报错字符串的原始 require(condition)。此时需审阅对应合约方法的源码,排查哪种入参会导致条件判断不通过。

3. 核对调用前置条件:
   检查调用方账户 TRX 余额是否足够、TRC-20 转账的 allowance 授权额度是否充足、交易截止期限(Deadline)是否过期、目标合约是否被管理员暂停(Pause)。

4. 底层外部调用(Low-level Call)失败:
   用 addr.call(...) 发起底层调用时,执行失败只返回 false,不抛 Revert 中断。需在合约代码中正确判断该返回值(如 require(success)),把异常向上传递并回滚外部状态。

Solidity 0.8.4+ 引入的自定义错误(Custom Errors),函数选择器是 keccak256("ErrorName(types)") 的前 4 字节,需根据合约编译生成的 ABI 文件结构化解码。

---

OUT_OF_ENERGY —— 虚拟机执行过程中 Energy 耗尽

根本原因

交易执行所需的 Energy 超出了这笔交易可使用的 Energy 上限。该上限由调用方可用的质押 Energy、合约部署者可代付的 Energy（如有）以及 fee_limit 可换算出的燃烧 TRX 部分共同决定。虚拟机已经完成的计算不会回退资源消耗，已消耗的 Energy 不予退还。

推荐的修复与优化步骤

1. 高精度预估 Energy:
   用与生产环境数据特征一致的参数，调用 /wallet/triggerconstantcontract 静态执行接口或 /wallet/estimateenergy 预测 Energy。详细逻辑见 FeeLimit 与 Energy 成本。
2. 调高 fee_limit 预算上限:
   构建交易时传入更大的 fee_limit。目前主网单笔交易的硬性上限为 15,000 TRX。合约单次消耗超过该限制,说明结构过于臃肿,必须拆分。
3. 核算合约的付费分配参数:
   检查合约的 consume_user_resource_percent,防止设置不合理让调用者承担超预期的资源成本份额、因余额不足中断。
4. 计入动态 Energy 模型（Dynamic Energy Model）的惩罚乘数:
   高频热门合约（如 USDT）在基础 Energy 消耗之上，会叠加针对该合约当前周期的 energy_factor 惩罚系数。调用 /wallet/getcontractinfo 可实时查看该合约的最新惩罚情况。
5. 质押 TRX 或租借 Energy:
   调用账户没有足够 TRX 燃烧支付 Energy 时，交易会失败。调用频次高、吞吐量大的 DApp，可以通过 Stake 2.0 机制质押 TRX 获取资源，或在 JustLend Energy 租赁市场租用 Energy，降低运营成本。

---

调用 view 或 pure 方法时 constant_result 为空

现象与根本原因

客户端调用 /wallet/triggerconstantcontract 测试只读的 view 或 pure 方法时,接口正常返回 result: true,但 constant_result 数组为空。调用既没抛异常,也没返回预期的状态值。
这通常出现在自建全节点从 GreatVoyage-v4.2.2 或更高版本强行降级到 v4.2.1/v4.2.0 后。降级后的底层数据库缺失高版本只读查询路径所需的字段。

解决方案

• 节点运维方:
  1. 在受影响的节点服务器上停止进程，并运行 DBRepair.jar 数据库修复工具。
  2. 将节点程序的二进制版本升级为 GreatVoyage-v4.2.2.1 或更新版本后重新拉起同步。
  3. 具体操作流程请参阅 DBRepair.jar 使用指南。
• DApp 开发者:
  这是节点底层的数据库异常,不是合约代码的漏洞。把开发端 RPC Endpoint 切换到健康的公共节点网关(如 TronGrid)。

---

同一 TRC-20 Token 在不同转账场景下 Energy 开销不同

根本原因

这种现象并非由 Bug 引起，主要源于底层以太坊虚拟机（TVM 兼容）的 SSTORE 操作码存储状态定价，以及 TRON 的动态 Energy 模型。

1. SSTORE 操作码的存储开销差异

TVM 虚拟机使用 SSTORE 指令来修改或写入合约的状态数据。更新 TRC-20 Token 合约中用户的余额时，其收费标准如下：

• 接收方此前账户余额为 0（槽位数值由 0 变更为大于 0 的数）：虚拟机判定为分配新存储空间，消耗 20,000 Energy。
• 接收方此前余额不为 0（槽位数值本就不为 0）：虚拟机判定为对现有存储更新，仅消耗 5,000 Energy。

因此向任意地址第一次转账(底层开辟新槽位)消耗的 Energy,通常是后续转账的 4 倍左右。这是底层协议定义的首次开槽成本,无法在应用层优化掉。

2. 动态 Energy 模型参数变动

全网调用量极大的高热度 TRC-20 合约,动态 Energy 模型按当前周期计算惩罚乘数,并在每个维护周期(约 6 小时)重置。所以对同一地址做完全相同的转账,不同时间执行也会有微弱的 Energy 起伏。

实际转账消耗对比示例

• USDT 资产（高频交易，受动态 Energy 模型影响严重）：

  • 向已有 USDT 余额的地址转账：通常扣除约 64,000 Energy。典型链上交易示例
  • 向零余额地址转账（首次开槽）：通常扣除约 130,000 Energy。典型链上交易示例

• BTT 资产（低频资产，无动态 Energy 模型附加罚息）：

  • 向已有 BTT 余额的地址转账：约扣除 13,253 Energy。典型链上交易示例
  • 向零余额地址转账（首次开槽）:约扣除 28,253 Energy。典型链上交易示例

为保证资金与成本稳定,建议每笔交易发送前在客户端实时调预估接口做 Energy 预算,并乘上适当的缓冲系数(如按合约的 max_factor 设定单笔 fee_limit 上限)。详细策略见 FeeLimit 设定与 Energy 成本。

---

多重签名（账户权限管理）执行 Stake 2.0 交易时报错 "Permission denied"

根本原因

这通常出现在 Stake 2.0 升级提议正式生效(主网委员会治理提议 #84)前就创建并激活多重签名配置的早期账户上。
旧账户的 Active 权限 operations(操作权限位图)里,没有 Stake 2.0 新引入的合约操作类型 ID,所以共同签名者代签调用时被拒绝权限。

解决方案

更新多重签名发起账户的 Active 权限位图,把以下 Stake 2.0 新定义的合约类型操作 ID(对应 Tron.proto 底层定义)加进去:

💡

提示

operations 是 32 字节的权限位图,第 n 位表示是否授权第 n 号合约类型操作。为防手动计算位图出错,建议用 TronWeb 或 Trident SDK 的工具方法生成多重签名更新交易,或直接在 TronLink 钱包的账户权限设置界面可视化勾选。

---

相关资源

• 虚拟机 TVM 异常处理机制 —— 了解 TRON 虚拟机协议底层的各类异常表现
• 广播与 RPC 错误诊断 —— 详细诊断交易广播接口错误与 TronGrid 托管网关报错
• 节点运维常见故障排查 —— 诊断与解决自建全节点区块同步缓慢及 different resultCode 共识冲突
• FeeLimit 与 Energy 成本 —— 正确配置客户端的 fee_limit 预算参数
• 多重签名机制指南 —— 深入理解账户权限管理与多重签名流程
• 问答中心 FAQ —— 汇总自社区开发者的常见问题与技术解答