智能合约异常排查

📘

前置阅读

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

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

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

---

OUT_OF_TIME —— CPU 时间超限或协议检查失败

根本原因

OUT_OF_TIME 不一定表示实际执行时间超过了 CPU 时间限制。除了合约执行超时，java-tron 也会在部分协议检查失败时直接返回该结果。排查时应结合交易的具体错误消息判断原因。

无论由实际超时还是协议检查触发，OUT_OF_TIME 都会耗尽本次合约执行可使用的 Energy 额度；失败时尚未使用的部分也会记为已消耗，不能按普通 REVERT 的结算方式理解。

目前主网单笔 CPU 时间预算为 80 毫秒，由链参数 #13（getMaxCpuTimeOfOneTx）控制。可通过 wallet/getchainparameters 查询当前值。超级代表（SR）委员会可发起治理提议调整该值，因此切勿在代码中硬编码 80 毫秒。

📘

说明

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

由协议检查直接触发的 OUT_OF_TIME

除实际执行超过 CPU 时间限制外，部分协议检查也会直接触发 OUT_OF_TIME。排查时应以交易返回的具体错误消息为准。

其中，SELFDESTRUCT 标记只存在于当前交易的执行上下文中，不表示该账户以后永久不能质押。

尚未启用当前 TVM 规则的私链或测试环境，还可能返回 CPU timeout for create2 executing 或 CPU timeout for modExp executing。在当前主网规则下，对应边界条件改为操作失败，不再直接产生 OUT_OF_TIME。详见 TVM 操作码。

以下优化仅适用于合约实际执行时间超过限制的情况。

针对实际执行超时的优化方案

• 拆分为多笔交易：将高开销操作设计为可分批执行的流程，由多笔独立交易依次处理，并在合约中记录执行进度。部署大型合约时，应减少构造函数中的初始化工作，改为部署后分批初始化。仅将代码拆分为多个合约并在同一笔交易中跨合约调用，不会重置该交易的 CPU 执行时间预算。
• 以迭代替代递归:在编写 Solidity 逻辑时，尽量使用 for 迭代循环代替递归函数，因为迭代在资源开销和 CPU 耗时上都更为廉价。
• 避免对存储数组进行无界循环：这是导致超时最常见的设计失误。请避免直接对未设上限的动态数组执行遍历。建议对数据进行链下缓存、在合约端采用分页查询，或者将复杂的统计计算工作转移至链下处理。
• 真实数据测试:在 Shasta 或 Nile 测试网中部署并使用与生产环境同等规模的数据集进行耗时预估，避免仅使用轻量级 Mock 数据测试。
• 合理设定 fee_limit:根据合约的实际最大开销设置调用方预算。该值过高会扩大 OUT_OF_TIME 时可能被耗尽的 Energy 额度；最终燃烧的 TRX 还取决于调用方可用的质押 Energy 和余额。

关于如何在隔离测试环境中临时绕过交易执行时间限制，请参阅节点运维常见故障——在隔离测试环境中绕过交易执行时间限制。

---

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

根本原因

合约执行中触发了 require 或 revert 校验，按业务逻辑主动中止并回滚状态。REVERT 只结算失败前实际消耗的 Energy，未使用的 Energy 额度不会计费。

推荐的诊断排查流

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。自建 FullNode 默认不开放 estimateenergy，必须同时启用 vm.estimateEnergy = true 和 vm.supportConstant = true；公共 RPC 是否支持取决于运营方配置。不支持时应回退到 triggerconstantcontract。详细逻辑见 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. 停止节点并完整备份当前数据目录；不要让其他节点进程继续写入该目录。
  2. 将节点程序升级到当前最新的 java-tron 版本。不要继续使用由高版本节点写入、又被低版本节点打开过的原数据目录。
  3. 从与目标版本和 storage.db.engine 匹配的可信快照恢复，或使用空数据目录从创世区块重新同步。
  4. 节点追平后，通过 /wallet/getnowblock 和 /wallet/triggerconstantcontract 验证区块高度与只读调用结果，再恢复对外服务；确认恢复成功前保留原备份。

  旧版 DBRepair.jar 指南和下载入口已从当前 java-tron 仓库移除。不要从第三方来源下载同名 JAR；无法验证工具来源时，使用“升级节点 + 从可信快照恢复或重新同步”的流程。

• DApp 开发者:
  这是节点底层的数据库异常,不是合约代码的漏洞。把开发端 RPC Endpoint 切换到健康的公共节点网关(如 TronGrid)。

---

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

根本原因

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

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

许多 TRC-20 合约使用映射（mapping）保存账户余额。对于这类实现，向接收方余额槽位写入数据时会执行 SSTORE：

• 槽位由零变为非零时，该次 SSTORE 消耗 20,000 Energy。
• 更新已经为非零的槽位时，该次 SSTORE 消耗 5,000 Energy。

两种写入相差 15,000 Energy，但这只是整笔转账中的一次存储操作。转账还可能更新发送方余额、写入其他状态并触发合约自身逻辑，因此整笔交易的 Energy 差异不等于 4 倍。TRC-20 标准也不规定余额必须采用这种存储布局；实际开销应以目标合约的实现和能耗估算结果为准。

2. 动态 Energy 模型参数变动

全网调用量极大的高热度 TRC-20 合约，动态 Energy 模型按维护周期统计使用量。维护处理会推进周期编号；合约在新维护周期首次执行或查询时，系统再根据上一周期的使用量补算惩罚因子。因此，即使对同一地址执行相同转账，不同时段的 Energy 消耗也可能不同。

TRC-20 转账 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 —— 汇总自社区开发者的常见问题与技术解答