VM 异常处理

📘
前置阅读

TVM 虚拟机原理

TRON 上的 Solidity

在智能合约开发中，错误处理与异常管理是保证资产安全及交易可预测性的核心环节。本文将从两个维度展开：一是 TVM 虚拟机在合约底层执行时如何识别并处理各类异常；二是如何在 Solidity 代码层级优雅地进行错误管理与防御性编程。文章前半部分适用于诊断链上交易失败的原因，后半部分则为编写稳健、安全的合约代码提供开发指南。

TVM 底层异常分类

在 TVM 虚拟机执行合约指令的过程中，可能会触发四类不同的异常。各类异常在触发后，对已消耗能量的结算规则以及交易在链上的存储可见性各有差异：

1. 会耗尽 Energy 额度的运行时异常

合约因 OUT_OF_ENERGY、OUT_OF_TIME、invalid opcode、虚拟机栈溢出或内存超限等 TVM 运行时异常而终止后，TVM 会调用 spendAllEnergy()，按执行前计算出的 Energy 上限记账：失败前已实际使用和尚未使用的 Energy 都会记为已消耗。

以下是可能进入这类处理的常见场景。由 Solidity 编译器生成的语言层检查会随编译器版本采用不同的错误处理方式；Solidity 0.8+ 中的多种检查失败会返回 Panic(uint256) 并通过 REVERT 终止，其 Energy 记账见下一节。

数组索引越界：例如在执行 x[i] 时，索引 i 大于等于数组长度或小于 0。
固定长度字节数组访问越界：访问固定长度 bytesN 类型变量时索引越界。
除零错误：执行除以零或对零取模的操作（如 5 / 0，23 % 0）。
负数位移：执行位移操作时位移位数为负数。
类型转换越界：将超出枚举定义范围的数值（或负数值）强行转换为枚举（Enum）类型。
空指针变量调用：尝试调用一个未被初始化赋值的内部函数类型变量。
不变量断言失败：调用内置的 assert(expression) 函数，且传入的表达式计算结果为 false。
合约执行超时：智能合约执行超时（超出了单笔交易虚拟机允许的最长执行时长限制，即链参数 getMaxCpuTimeOfOneTx，当前通常为 80ms）。
虚拟机栈溢出：TVM 触发了虚拟机底层的调用栈溢出异常（JVMStackOverFlowException）。
内存溢出：发生内存超限异常（OutOfMem，单个调用帧分配的内存使用量超过了 3 MB 上限。同一笔交易可包含多个嵌套调用帧，每帧各自享有 3 MB 配额）。

2. `REVERT`

REVERT 可由 require、revert、Solidity 0.8+ Panic(uint256) 等情况触发。此时系统仅结算从交易开始到错误发生时实际消耗的 Energy，未使用的 Energy 额度不会计费。链上常见的报错摘要为 REVERT opcode executed。

以下场景会触发 REVERT：

前置校验失败：调用 require(expression)，且传入的表达式判定结果为 false。
外部调用级联失败：通过消息调用（Message Call）触发的被调函数未能正常结束（如遭遇内部能耗耗尽或抛出二级异常）。如果调用时未显式限制转发能耗，所有的可用能量将被全部传递；仅根据外层返回结果，调用方可能无法判断被调合约是耗尽了 Energy 额度，还是通过 REVERT 终止。需要说明的是，此异常传递规则不适用于 call、send、delegatecall 和 callcode 等底层原生操作指令，因为这些底层指令在子上下文失败时会以返回 false 作为代替，而不会自动向外层抛出 revert 中断。
构造器初始化失败：使用 new 关键字动态创建新合约时，被建合约的构造函数执行失败（由于无法为部署指定精细能耗，导致看起来消耗了所有传递的能量）。
向非 Payable 函数转账：向未声明 payable 修饰符的公共函数（含构造函数、fallback 或其他 public 方法）发送 TRX。
转账失败：通过代码执行 transfer() 转账 TRX 失败。
显式 Revert：显式调用了内置的 revert() 函数。
Solidity 0.8+ Panic：assert 失败、算术溢出或下溢、除零、数组越界等语言层检查失败会返回 Panic(uint256)。
栈层数溢出：交易执行触发了 TVM 最大函数调用栈深度的 64 层限制。

📘
状态回滚与 Energy 记账
合约进入 TVM 执行后，无论最终因 OUT_OF_TIME、invalid opcode 等运行时异常终止，还是通过 REVERT 终止，执行期间产生的状态变更都会回滚，以保证交易的原子性（Atomicity）和数据一致性。
Energy 记账取决于终止方式：

调用 spendAllEnergy() 的运行时异常：按执行前计算出的 Energy 上限记账，未使用的剩余额度也会记为已消耗。

REVERT：仅结算错误发生前实际消耗的 Energy，未使用的额度不会计费。

无论采用哪种记账方式，已消耗的 Energy 都不会退还。

3. 校验风格异常（验证前置拦截）

这类异常在交易试图进入 TVM 解释执行前，就被全节点（FullNode）的前置校验过滤器直接拦截并捕获。因此，该交易绝不会记录在区块链的历史区块中，也不会产生任何实际的能量或带宽消耗。

以下场景会触发这类前置拦截异常：

功能特性不兼容：目标网络当前激活的 TVM 虚拟机版本不支持合约编译版本所要求的某项特异功能。
名称超限：部署创建的智能合约其名称长度超出了 32 字节。
分摊比例越界：部署合约时指定的 consume_user_resource_percent 分摊比率超出了 [0, 100] 的合法整数区间。
地址哈希冲突：部署合约时算出的新合约地址与链上已存在的合约地址发生了极罕见的哈希冲突。
资产余额不足：交易携带的 call_value（发送的 TRX）超出了当前发起账户的实际余额。
FeeLimit 数值非法：传入的 fee_limit 费用上限超出了网络要求的有效数字范围。
不支持的只读节点：将只读的常量调用（triggerconstantcontract）发送到了未配置启用此功能的全节点。
交互地址不存在：欲交互的目标合约地址在区块链账本数据库中不存在。

4. 非法虚拟机操作异常

此类异常不仅不会被链上区块记录，而且广播此交易的 TRON 全节点将在网络层被判定为传播了垃圾交易，从而面临短暂被封禁/惩罚的风险：

部署发起人不匹配：在创建和部署合约交易中，指定的 OwnerAddress（合约创建者）与 OriginAddress（交易实际签名发起者）账户地址不匹配。
恶意传播 Constant 请求：错误地将只读常量请求（Constant Call）向全网广播传播。

调用栈深度与递归深度限制

TVM 虚拟机对底层的执行调用栈（Call Stack）深度设置了 64 层的硬性上限。此深度限制对跨合约的外部方法调用、嵌套调用以及合约自身的递归自调用均统一适用。一旦执行深度超过了 64 层，虚拟机将立即抛出 require 风格的 Revert 异常并终止执行。

另一个与之独立但常常引起开发者混淆的则是 Solidity 编译器的 “Stack too deep”（栈过深） 编译报错。该错误属于编译时限制，通常是因为在单个 Solidity 函数中声明了过多的局部变量或临时计算中间件，超出了虚拟机寄存器在单帧内的寻址空间。虽然它与运行时的递归调用没有直接的关联，但它是在提醒我们应当合理重构并拆分过于臃肿的复杂函数、减少局部变量的定义数量，或者使用块级作用域来手动释放栈空间。

在设计含有递归逻辑的合约时，建议遵循以下安全规范：

显式增加深度限额校验：在代码中显式加入递归计数器，并在触达安全阈值前主动 revert，防止失控递归触发虚拟机异常。
精准计量每次调用的能耗：确保深层递归产生的能耗累加值不会超出交易设定的 fee_limit 费用额度。
优先选用迭代循环：在大多数场景下，使用 for 或 while 循环来实现业务逻辑不仅更易于推理，而且在 TVM 中燃烧的能量开销通常比等效的递归结构要低得多。

Solidity 中的错误处理语法工具

在 Solidity 语言中，主要提供了四种内置语法来管理错误和捕获异常：assert、require、revert 以及自定义错误（Custom Errors，于 Solidity v0.8.4 版本及以上支持）。

assert 断言

assert 专为测试和验证内部不变量（Invariants）设计——即在代码逻辑正确的前提下不应被违反的状态条件。它应用于检测内部 Bug 和不变量破坏，不应代替 require 执行输入或权限校验。assert 失败后的错误格式和 Energy 记账取决于 Solidity 编译器版本：旧版本通常生成 invalid opcode，Solidity 0.8+ 则返回 Panic(uint256) 并通过 REVERT 终止。

assert(x == y);

自 Solidity 0.8.0 版本起，assert 失败在编译后会自动附带 Panic(uint256) 错误选择器。

require 校验

require 则是针对外部数据输入边界、方法执行前置条件（如权限认证）进行防御性校验的推荐工具。require 的判定失败将以 revert 的形式结束，仅扣除执行到当前行已产生的能耗，并安全退还其余资金。

require(msg.sender == owner, "Not the owner");

传入的报错原因说明字符串（例如 "Not the owner"）会被附加到报错数据流中，帮助前端和集成方明确交易失败的原因。

revert 显式回滚

revert 提供了更具表达性且更加灵活的流程控制能力。它可以在任意控制流分支中随时被抛出，并支持回滚交易状态与退还能耗。当条件分支结构比较复杂、使用 require 显得晦涩难懂时，revert 是最佳选择：

if (someCondition) {
    revert("Condition not met");
}

自定义错误（Solidity 0.8.4+）

与基于超长说明字符串的 revert 相比，使用自定义错误（Custom Errors）带来了以下两项质的提升：

极致压缩的能耗开销：自定义错误编译后仅生成 4 字节的哈希选择器（Selector），相较于在链上存取和搬运冗长的原因字符串，能够大幅度节约交易所花费的能量。
丰富的结构化数据传参：开发者可以向自定义错误中传递类型化的参数（如当前调用者地址、数值等），便于链下应用对报错上下文进行极其精细的可视化解析。

pragma solidity 0.8.6;

// 声明自定义错误
error Unauthorized(address caller);

contract MyContract {
    address public owner;

    constructor() {
        owner = msg.sender;
    }

    // 触发执行
    function doSomething() external view {
        if (msg.sender != owner) {
            revert Unauthorized(msg.sender);
        }
        // 其他业务逻辑
    }
}

一旦 Unauthorized(msg.sender) 触发，TVM 会安全回滚状态，并回收退还交易未使用的能量费用。外部 SDK（如 TronWeb、Trident）在获取到合约 ABI 的情况下，会自动对该 4 字节的错误签名与入参数据进行反序列化，帮助用户获取精确的错误详情。

异常管理的最佳实践

优化异常消耗的能量成本

不同的异常拦截语法对能耗费用的影响存在天壤之别：

assert 抛出故障将消耗全额的可用能量上限。在生产环境中，请仅将 assert 局限在检测绝对不可能失败的合约核心不变量上。
require 与 revert 在逻辑失败时仅扣除已发生的实际能耗。正常的业务状态校验务必选择这两者。
相较于基于原因字符串的 revert，自 Solidity 0.8.4 版本引入的自定义错误在虚拟机层面开销显著降低。对于包含高频逻辑防御校验的复杂合约，应强制采用自定义错误。

在编写涉及复杂能耗运算的函数时，应当将成本较低的前置条件检验（如权限和入参边界校验）尽可能置于函数最顶端执行，避免在逻辑中途遭遇 revert 导致白白浪费在前期计算中消耗的能量。

绝不要将 `assert` 错用于输入校验

如果您发现在合约中使用 assert 去验证用户的入参数据或执行权限，请立即将其替换为 require 或 revert。assert 的失败意味着合约在设计逻辑或底层状态中出现了崩塌式 Bug，绝不应当被用作面向用户的日常业务约束。

高频使用 `require` 与自定义错误校验边界

对于以下经典的系统条件判定，require 或是附带自定义错误的 revert 是绝对唯一正确的选择：

权限管理与访问控制（如 require(msg.sender == owner, ...)）
入参数值区间与边界防卫（如 require(amount > 0, ...)）
合约当前生命周期与状态判定（如 require(state == State.Open, ...)）

合理规避深度递归结构

由于 TVM 调用栈深度被强行限制在 64 层，且深度执行会急剧拉高交易的能量消耗，应尽量避免使用深度递归。绝大多数递归算法都可以使用平稳的 for/while 迭代循环进行重写，这不仅有利于能耗的精准控制，也有利于逻辑的推理与审计。

重入漏洞防御

在触发外部跨合约调用（包括合约间调用以及向外部发送自调用）时，当前的交易执行控制权会临时让渡给外部目标合约。如果外部被调合约在我们的函数执行完结前再次反向调用（重入）我们的合约，如果状态变更未被锁止，将可能遭遇“重入攻击”，导致重大的资金损失（最著名的先例是早期以太坊生态的 The DAO 攻击案）。

在设计跨合约调用时，建议严格遵循以下安全防线：

“检查-生效-交互”（Checks-Effects-Interactions）模式：在函数最顶部检查前置条件；中段完成所有内部状态变量的修改与写盘；最后在最底部执行外部调用交互。
对于高价值、高风险的资金调度方法，必须搭配使用 OpenZeppelin 的 ReentrancyGuard 防重入锁或等效锁逻辑。详情请查阅智能合约安全最佳实践章节。

前置阅读