将以太坊合约迁移到 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.6'
  }
}

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

🚧

强烈建议锁定编译器版本

在代码中请强制使用精确的 pragma solidity X.Y.Z; 声明（务必移除波浪号 ~ 或脱字号 ^）。这能够确保您在本地测试时所采用的编译器版本与上链编译版本高度一致，彻底杜绝编译器微版本升级所带来的隐性执行差异。具体开发规范请参考 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 源码。 TRON 专用的 solc 编译器会自动在底层将其编译为适配 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：使用 Assembly 底层显式计算或推导 CREATE2 地址。如果您的代码中为了省 gas 或兼容前端，复制并使用了 OpenZeppelin 的 Create2.computeAddress 或自定义的 inline assembly 来手动对 keccak256 进行哈希计算和地址推导，您必须手动将前导校验字节从 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 官方未经修改的二进制库，请务必将其替换为替换为适配 TRON 的分支版本，或者使用包装帮助方法将生成算法中的前缀字节强制重写为 0x41。

第四步：重新换算原生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 并非硬编码的静态整数：如果您的合约在以太坊中使用 block.chainid 来防范 EIP-712 签名重放，请务必注意：在 TRON 网络中，该变量在运行时的返回值是创世区块哈希的最后 4 个字节，它并不是某个预先约定的常量（如 1）。因此在需要使用时，应始终在运行时通过 block.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 底层的交易费用模型