将以太坊合约迁移到 TRON

📘

前置阅读

• TVM 与 EVM 的区别
• TRON 上的 Solidity

如果您手头已有运行在以太坊或任何其他 EVM 兼容链上的 Solidity 智能合约，本文将为您提供一份将其移植至 TRON 网络的分步实操迁移指南。本文旨在提供具体的迁移工程步骤与实操技巧，而非单纯的底层指令罗列；有关虚拟机指令（Opcode）与预编译合约的完整技术对照清册，请参阅参考文档 TVM 与 EVM 的区别。

若您需要对 Truffle 或 Hardhat 工程进行项目级别的代码结构与自动化框架整体迁移（如目录适配、网络配置、测试框架重构等），请参阅 Truffle 项目迁移至 TronBox 指南。

核心差异一览

第一步：使用 TRON 专用的 Solidity 编译器（solc）进行重新编译

TRON 网络的 Solidity 编译器基于以太坊官方 solc 分支定制开发，内置了对 TRON 特有语法扩展的支持（如代表 TRC-10 Token的 trcToken 类型、用于Token转账的 transferToken 方法、以及 trx 和小写 sun Token基本单位字面量）。绝大多数在以太坊上运行的合约都可以在 TRON 编译器下直接完成编译，但前提是必须使用 TRON 专属的发布版本。

如果您选择使用 TronBox 框架（推荐），它已经默认集成了合适版本的 TRON solc 编译器。您仅需在 tronbox-config.js 配置文件中，将 compilers.solc.version 调整为您合约所声明的精确锁定版本即可：

compilers: {
  solc: {
    version: '0.8.20'
  }
}

若您选择在本地手动构建编译链，或是直接使用浏览器集成开发环境 TronIDE，请从官方仓库 github.com/tronprotocol/solidity 的 Release 页面获取对应的 TRON solc 编译器版本。

🚧

强烈建议锁定编译器版本

为保证构建结果可复现，请在 tronbox-config.js 中固定 TRON solc 的精确版本，并锁定依赖版本和 lockfile。项目自有合约可以使用精确的 pragma solidity X.Y.Z;；第三方依赖可能使用兼容版本范围，请确保所配置的编译器满足所有依赖的 pragma，不要直接修改已安装的依赖源码。具体开发规范请参考 TRON 上的 Solidity 章节。

第二步：排查合约底层的操作码（Opcode）执行差异

有极少数的操作码（Opcode）在 TVM 虚拟机中的执行行为与 EVM 存在微小差别。绝大多数常规智能合约的业务代码不会受到这些细微差异的影响，但是如果您的合约业务逻辑中涉及了以下敏感的操作，则必须在迁移前完成适配修正：

完整的操作码对照细则请参阅参考文档 TVM 与 EVM 的区别。

第三步：妥善适配 CREATE2 地址推导逻辑

TRON 虚拟机在计算 CREATE2 所生成的合约地址时，采用的前导字节为 TRON 网络的 0x41；而以太坊 EVM 采用的是 0xff。迁移时应根据地址的计算方式进行处理。

情况 A：使用 Solidity 原生的 new {salt: ...} 语法。如果合约通过 Solidity 高层语法（如 new Token1{salt: _salt}(_x)）创建子合约，无需修改 Solidity 源码。编译器会将该语法编译为 CREATE2 指令；TVM 执行该指令时，会按照 TRON 的 0x41 地址推导规则计算合约地址：

pragma solidity 0.8.20;

contract Token1 {
    uint256 public value;
    constructor(uint256 _value) {
        value = _value;
    }
}

contract Factory {
    event ContractCreated(address);

    function createContract(bytes32 _salt, uint256 _x) external {
        Token1 newToken = new Token1{salt: _salt}(_x);
        emit ContractCreated(address(newToken));
    }
}

情况 B：使用 OpenZeppelin 的 Create2 库。请改用官方的 OpenZeppelin Contracts for TRON。其中的 Create2.computeAddress 已按 TRON 规则使用 0x41 前缀，无需自行 fork 或包装：

import {Create2} from "@openzeppelin/tron-contracts/utils/Create2.sol";

function computeAddress(bytes32 salt, bytes32 bytecodeHash, address deployer)
    internal pure returns (address)
{
    return Create2.computeAddress(salt, bytecodeHash, deployer);
}

安装包时建议固定经过验证的版本，例如 npm install --save-exact @openzeppelin/[email protected]。该包与以太坊版 @openzeppelin/contracts 的补丁版本独立发布，不应直接套用后者的版本号。

情况 C：自行使用 Assembly 计算 CREATE2 地址。如果代码保留了自定义的 inline assembly 地址推导逻辑，必须将前导字节从以太坊的 0xff 改为 TRON 的 0x41：

function computeAddress(bytes32 salt, bytes32 bytecodeHash, address deployer)
    internal pure returns (address addr)
{
    assembly {
        let ptr := mload(0x40)
        mstore(add(ptr, 0x40), bytecodeHash)
        mstore(add(ptr, 0x20), salt)
        mstore(ptr, deployer)
        let start := add(ptr, 0x0b)
        mstore8(start, 0x41)  // <-- TRON 网络中必须修改为 0x41，以太坊中为 0xff
        addr := keccak256(start, 85)
    }
}

不要使用以太坊版 @openzeppelin/contracts/utils/Create2.sol 计算 TRON 的 CREATE2 地址，否则预测地址将与 TVM 实际部署地址不一致。

第四步：重新换算原生Token（TRX）的最小单位精度

以太坊的原生Token ETH 最小单位为 wei（即小数点后 18 位精度，1 ETH = 10¹⁸ wei）；而 TRON 原生Token TRX 的最小单位为小写 sun（即小数点后 6 位精度，1 TRX = 10⁶ sun）。如果您的合约逻辑中存在任何涉及原生Token基本计算单位的逻辑（例如判定交易额是否大于硬编码的某常量），您必须进行精度的重新换算。

• 在以太坊中声明 1 ether 或 1e18 的代码，在 TRON 中应当重写为 1 trx 或 1e6。
• 如果原逻辑是将价格或其他资产以 10¹⁸ 的比例进行缩放计算，在 TRON 中需统一调整为以 10⁶ 比例缩放。

TRON 专用 Solidity 编译器完全接受原生字面量 trx 和小写 sun 作为单位修饰符，详情请参阅 TRON 上的 Solidity 章节。

第五步：替换链下交互所使用的开发工具包（SDK）

若要在链下与新部署的 TRON 合约进行交互，需要对客户端代码中的依赖库进行替换：

虽然这些 TRON SDK 提供的合约实例化形式与以太坊高度相似（例如都支持 contract(abi).at(address) 这种优雅的链式结构），但是在底层的网络连接端点、交易签名流程以及地址格式校验上存在明显差异。具体客户端集成交互指南请参考 与智能合约交互 章节。

第六步：切换开发端点至 TRON 测试网（Shasta）

在测试阶段，您需要将原本指向 Goerli 或 Sepolia 的以太坊测试网连接端点，整体切换为 TRON 的主要公共测试网 —— Shasta：

如果您使用 TronBox 工具进行管理，需要在 tronbox-config.js 配置文件中声明 shasta 网络配置参数：

networks: {
  shasta: {
    privateKey: process.env.PRIVATE_KEY,
    userFeePercentage: 50,
    feeLimit: 100 * 1e6,                     // 100 TRX，单位为 sun
    fullHost: 'https://api.shasta.trongrid.io',
    network_id: '2'
  }
}

完整的工程部署范例说明请参考 快速入门 章节。

第七步：发布部署与合约源码验证

通过 TronBox 框架（执行 tronbox migrate --network shasta）或者 TronIDE 编译器将合约部署上链。关于部署的具体步骤与底层 API 配置，请参考 智能合约部署 章节。在交易发送后，建议使用 /walletsolidity/gettransactioninfobyid 携带交易哈希查询已固化区块中的交易回执，并确认部署交易执行成功。

当您的项目最终成功发布到 TRON 主网后，请务必第一时间在浏览器 TRONSCAN 上完成源码验证，实现代码的公开透明，以供社区审计。TRONSCAN 上的开源验证流程和以太坊的 Etherscan 高度契合，步骤详情请参考 合约验证 章节。

经典迁移误区与深度避坑指南

• 转账 TRX 不一定会如预期触发接收合约的 fallback 回调：在以太坊中，任何以合约作为目的地的以太币划转都会无条件执行该合约的 receive 或 fallback 回调。而在 TRON 中，原生Token的转移存在两种完全不同的底层系统交易机制：
  1. TransferContract：属于系统级的普通转账（通过 /wallet/createtransaction 触发）。此类交易在底层会直接绕过 TVM 虚拟机，完全不会触发接收合约的 receive 或 fallback 逻辑。
  2. 带 callValue 的 TriggerSmartContract：这属于虚拟机层面的智能合约调用交易。只有此类交易才会正常执行合约的 payable 回调函数。
  如果您的以太坊合约极度依赖于“每一次资金转入都必须触发 fallback 逻辑”（例如用于记账、触发内部事件或实现基于余额的防重入机制），请务必排查调用方的实现。在以太坊中可行但在 TRON 中会直接失效的模式包括：通过 fallback 里的 Event 监控资金存入、在 fallback 中依靠账户余额变动计算防重入锁，以及依靠接收 ETH 自动重新计算余额分红的特种Token合约。
• 链边界处的地址编码与格式差异：在 TRON 网络底层，外部公开可读的地址以 21 字节的十六进制（包含前导 0x41 网络前缀）或经 Base58Check 编码后的 34 位字符（以字母 T 开头）表示。而在 TVM 虚拟机内部执行时，地址与以太坊一样同为 20 字节。如果在 VM 之外与外部接口（如链下签名验证、RPC 参数传递、跨链网关推导）进行交互，必须注意按规则添加或截取 0x41 前缀字节，并进行 Base58Check 的编解码转换。详情请参考 TVM 与 EVM 的区别 —— 地址表示 章节。
• CHAINID 的数值来源与 EVM 不同：EVM 使用网络预先设定的 Chain ID，TVM 的返回规则则受链参数控制。第 71 号链参数（getAllowOptimizedReturnValueOfChainId）用于启用优化后的 Chain ID 返回规则。目前，TRON 主网以及 Shasta、Nile 测试网均已启用该参数，因此它们的 Chain ID 均为创世区块 ID 最后 4 个字节所表示的十进制整数（主网为 728126428），与 JSON-RPC eth_chainId 返回的十六进制值表示同一数值。在 TIP-712 等将 Chain ID 纳入签名域的场景中，客户端与合约使用不同的 Chain ID 会导致验签失败。如果多个网络复用相同的签名域，且缺少其他网络隔离条件，同一签名可能被跨网络接受，形成重放风险。合约应通过 block.chainid 获取当前网络的 Chain ID，客户端和后端应通过 eth_chainId 查询，并在部署和启动时确认各端使用同一数值。详情请参考 TVM 与 EVM 的区别 —— CHAINID 语义 章节。
• SELFDESTRUCT 自毁指令已被强力限制：在当前 TRON 主网开启自毁限制的机制下，如果对当前交易发生前就已经存在于链上的历史智能合约触发 SELFDESTRUCT 指令，该操作仅能将合约当前的 TRX 余额、TRC-10 Token和质押资产划转给接收地址，而绝不会清除该地址处的合约字节码或存储状态。这一点与以太坊 EIP-6780 提案的思路相近，但 TRON 的限制更为严格：如果该合约正在执行解质押等待期（Stake 2.0），或拥有尚未撤销的外部资源代理（Stake 1.0/2.0），自毁操作会直接报错 revert——这一约束在 EVM 中没有等价物。请切勿再将自毁指令作为合约升级或重构的原语使用。详情请参考 TVM 与 EVM 的区别 —— SELFDESTRUCT 限制行为 章节。
• 单元测试能耗不代表生产能耗：在一两个简单模拟账户下测试可能仅消耗 50,000 能量的方法，在生产环境面对真实海量用户状态时可能会因状态槽数量激增而消耗 500,000 能量。测试期间请务必调用 /wallet/triggerconstantcontract 接口，并导入逼真的生产级数据量进行高保真能耗估算。
• 动态能量模型（DEM）对热门合约能耗的推高作用：如果您的合约在部署上线后成为了主网高频访问的热门合约，系统会动态调高其 energy_factor 惩罚系数，导致后续的每一次交易能耗翻倍。请在部署前合理规划您及用户的质押策略与交易 fee_limit 熔断阀值。详情请参考 FeeLimit 与能量成本 章节。

相关资源

• TVM 与 EVM 的区别 —— 详细对比底层的操作码与内置预编译合约的实现细节
• TRON 上的 Solidity —— 梳理 TRON 网络对 Solidity 的专属语言级扩展
• 将 Truffle 项目迁移至 TronBox —— 自动化工程项目级迁移步骤说明
• 快速入门 —— 基于 TronBox 部署合约的完整开发流程示例
• 合约验证 —— 详述如何在 TRONSCAN 上完成智能合约的验证与开源
• FeeLimit 与能量成本 —— 探讨如何估算能耗并适配 TRON 底层的交易费用模型