路线 4：智能合约进阶开发者

本路线可以作为从普通合约开发走向工程化发布的起点，适合已经能够编写、测试和部署 Solidity 合约，希望进一步了解 TVM 执行、资源成本、安全检查和发布验收的开发者。

可以从这条路线了解什么

这条路线从可重复构建开始，依次介绍 TVM 与资源语义、合约逻辑复核、正常与异常测试、 Energy 与安全评估，以及 Shasta 部署和发布记录。

路线以一个定时付款合约为贯穿示例。付款方存入测试 TRX，并指定收款方和领取时间；到期后，只有指定收款方可以领取。各阶段将围绕同一份源码和测试记录，把一个能够运行的合约逐步整理为可审查、可复现的发布候选版本。

如果希望一边阅读一边实践，可以将定时付款合约示例加入已有的 Solidity 合约工程（例如 TronBox 工程），再按阶段补充构建配置、测试、成本基线和部署记录。也可以将相同方法用于自己的合约，并用该合约的主要执行路径替换文中的“创建付款”和“领取”。这里的“发布候选”表示合约已经具备明确的版本与验收记录，不代表它已经完成生产环境所需的独立安全审计。

开始前不必一次掌握所有 TVM 和资源细节。可以先通过下方概览了解各阶段的重点，再按照文档逐步复核当前合约；遇到执行、Energy 或部署问题时，再回到推荐阅读补充所需信息。

路线概览

阶段	主要内容	定时付款合约中的任务
1. 建立可重复构建基线	固定源码、依赖、编译器和优化配置	保存可重复生成的 ABI、创建字节码和运行时字节码
2. 校准执行与资源语义	了解 TVM、Energy、动态能量、异常记账和 EVM 差异	记录创建付款和领取路径的执行与资源特征
3. 复核合约逻辑	检查状态、权限、时间、资金转移、ABI 和事件	明确定时付款的状态约束与安全不变量
4. 补齐测试	覆盖正常流程、边界条件和失败路径	测试创建、到期领取及主要无效操作
5. 评估成本与安全	建立 Energy 基线、`fee_limit` 策略和安全检查记录	测量部署与主要调用，并检查资金和权限风险
6. 完成部署与发布记录	部署、验证源码、检查行为和保存版本证据	在 Shasta 发布并记录合约地址、交易和验证结果

开始前

建议先具备普通 Solidity 合约的编写、测试和部署经验，并了解账户、交易、资源和 Shasta 测试网。如果尚未走通合约的编译、部署与调用流程，可以先从智能合约快速通道 — 安装 TronBox 读到“从控制台调用合约”。完成阶段实践还需要一个使用 TronBox 或同类工具管理的合约工程，以及持有测试 TRX 的 Shasta 部署账户。如果尚未准备工程，可先按快速通道完成基础配置，再加入配套 Recipe 中的合约源码。

本路线主要梳理从合约源码到发布候选版本的知识与验收链路。具体编译和部署方法可以先参考编写与编译 — 编译合约和部署 — 准备工作，再按各阶段推荐阅读下钻到对应章节。

所有公共测试网实践都使用 Shasta；自动化测试可以在隔离的本地测试网络中完成。所有实践都应使用测试源码、测试账户和测试 TRX。私钥只提供给本地部署工具或受控签名环境，不应写入源码、配置文件、日志或版本库。

路线阶段

1. 建立可重复构建基线

合约能够编译，不代表任何环境都能得到相同产物。编译器精确版本、优化开关与 runs、依赖版本、源码路径和链接库配置都可能改变 ABI、创建字节码或运行时字节码。发布前需要先固定这些输入，避免测试、部署和源码验证使用不同产物。

可重复构建还需要明确当前候选版本对应的源码提交和配置。ABI 与字节码应由构建流程生成，而不是手工修改；依赖锁文件、编译警告和构建命令也应纳入记录。后续所有测试、Energy 测量和 Shasta 部署都继续使用这条基线。

阶段实践

先准备后续阶段共用的合约工程。使用贯穿示例时，将定时付款合约示例加入工程；使用自己的合约时，先选定后续阶段要复核的主要执行路径。然后固定源码提交、依赖锁文件和 Solidity 编译器精确版本；在项目配置中明确记录优化器是否启用，启用时还需固定 runs 参数。清理已有构建产物后重新编译，保存 ABI、创建字节码、运行时字节码、编译警告和构建命令。

在另一份干净工作目录或 CI 环境中使用同一配置重新构建，并比较生成的产物。若结果不同，应先找出环境、依赖或配置差异，不要继续进入测试和部署阶段。比较时应分别核对 ABI、创建字节码和运行时字节码，不要只比较包含路径或时间信息的完整工具 artifact。

校准执行语义前：确认同一源码和配置能够重复生成一致的 ABI 与字节码，并记录对应的源码提交和构建环境。下一阶段将以这组产物为基础分析 TVM 执行和资源成本。

2. 校准执行与资源语义

TRON 智能合约由 TVM 执行。TVM 与 EVM 在字节码和 Solidity 兼容性上较为接近，但 Energy 计量、地址处理、执行时间限制、部分 opcode 和链上上下文存在差异。已有以太坊开发经验不能代替对这些边界的核对。

合约部署和写入调用会消耗 Energy，实际成本取决于执行路径、状态读写和调用参数。热门合约还可能受到动态能量模型影响，因此一次测试结果不能自动成为长期不变的成本。资源不足或执行异常时，还需要结合 receipt 判断状态是否回滚、Energy 如何记录以及调用方实际承担了什么成本。

对于定时付款合约，创建付款会写入付款方、收款方、金额和领取时间；领取则需要检查权限和时间条件、更新领取状态并转移 TRX。这两条路径涉及的状态读写和外部转账不同，应分别理解和测量。

还需要区分 TRX 到达合约的两条路径：通过 payable 方法携带 callValue 会执行合约，普通 TransferContract 直接向合约地址转账则不会触发 receive() 或 fallback()。如果合约维护内部付款记录，不应只用 address(this).balance 代替业务账本。

阶段实践

根据当前 ABI 和源码，画出创建付款与领取两条执行路径，标出每条路径读取和修改的状态、发出的事件以及可能发生的外部转账。对每个失败条件记录预期的回滚行为和 receipt 结果。

在本地隔离测试环境中分别执行一次正常创建、正常领取和一个主动回滚场景，保存交易收据与 Energy 数据。此时重点是确认实际执行语义与预期一致，不急于制定最终 fee_limit。

复核合约逻辑前：确认能够说明创建付款和领取各自修改什么状态、消耗什么资源，以及主要异常如何反映在 receipt 中。下一阶段将根据这些执行路径检查业务规则和安全不变量。

3. 复核合约逻辑

定时付款合约需要明确一组始终成立的规则：付款金额有效，收款地址有效，领取时间符合约定；领取前资金仍由合约托管；只有指定收款方能够在到期后领取；一笔付款不能被重复领取。

复核时需要把状态变化、权限检查、时间条件和资金转移放在同一条执行路径中检查。涉及外部转账时，应先完成必要检查和状态更新，再进行交互，并明确转账失败时如何处理。block.timestamp 可以用于时间条件，但边界值和业务允许的时间误差需要写入测试与说明。

ABI 和事件也应与业务语义一致。公开方法的参数、可见性和 payable 属性需要符合预期。创建事件应记录付款标识、付款方、收款方、金额和领取时间；领取事件应包含付款标识，以及核对领取操作所需的收款方和金额。两个事件都只在相应状态变化成功后发出。

如果收款方可能是合约，还应把拒收 TRX 和重入纳入威胁模型。具体选择 transfer、send 或 call 时，需要同时核对失败语义、返回值处理和检查—生效—交互顺序，不能只替换一个转账方法就视为完成安全处理。

阶段实践

为定时付款合约整理一份逻辑检查表，逐项记录状态变量、创建条件、领取条件、资金去向、外部调用、事件和失败结果。把每条业务规则写成可以通过测试验证的不变量，避免只依赖代码阅读得出结论。

完成一次独立代码复核，确认源码、ABI 和事件定义表达的是同一套业务规则。发现需要修改的逻辑时，先更新源码和测试，再重新生成阶段 1 的构建产物。

补齐测试前：确认创建和领取路径的状态、权限、时间、资金转移、ABI 与事件保持一致，并把主要规则整理为可验证的不变量。下一阶段将用正常和失败场景验证这些规则。

4. 补齐测试

正常流程只能证明合约在一组理想输入下能够运行。发布候选版本还需要覆盖边界条件和失败路径，并确认失败不会留下部分状态、错误事件或可被再次利用的资金状态。

定时付款的正常测试至少包含成功创建和到期领取。失败测试应覆盖以下情况：使用零金额、零地址收款方或不晚于当前区块时间的领取时间创建付款；领取不存在或尚未到期的付款；由非指定收款方领取；重复领取。每个测试不仅要检查调用是否失败，还要核对余额、状态和事件是否保持预期。

与时间有关的测试可以在隔离的本地测试网络中进行。TRON 区块接口返回的 block_header.raw_data.timestamp 以毫秒为单位，而合约中的 block.timestamp 和 releaseTime 以秒为单位。读取当前区块后，应先使用 Math.floor(block.block_header.raw_data.timestamp / 1000) 转换为秒，再加上一个较短间隔得到 releaseTime。使用 TRE 时，等待时间应略长于该间隔，然后调用 tronWrap.send('tre_mine', [{ blocks: 1 }]) 生成新区块；确认新区块时间达到 releaseTime 后，再验证到期领取。每次测试前应恢复相同的初始状态，并固定测试账户、金额和相对时间间隔。Shasta 用于验收真实网络、资源和固化语义，不替代本地自动化测试。

阶段实践

为定时付款合约补齐以下测试：

使用有效金额、收款方和未来领取时间成功创建付款。
到达领取时间后，由指定收款方成功领取，并核对余额、状态和事件。
使用零金额创建付款时失败。
使用零地址收款方创建付款时失败。
将 releaseTime 设置为当前区块时间或更早时间，创建付款时失败。
对不存在的 paymentId 调用 claim() 时失败。
在领取时间前调用领取时失败。
由非指定收款方调用领取时失败。
对已经领取的付款再次调用领取时失败。

对每个失败场景检查状态没有发生非预期变化、资金没有错误转移、成功事件没有发出，并记录实际错误结果。测试完成后，在干净环境或 CI 中运行完整测试集。

如果领取路径会向可能为合约的地址转账，再补充接收方拒收和尝试重入的负向测试；如果产品允许普通 TRX 直接转入合约，还应确认这类余额不会自动生成付款记录或改变已有付款的可领取金额。

评估成本与安全前：确认正常创建与领取可以重复通过，所有规定的失败路径也按预期停止，并且余额、状态和事件断言完整。下一阶段将基于这些固定场景建立成本和安全基线。

5. 评估成本与安全

Energy 评估需要基于真实执行路径，而不是只记录单次平均值。部署、创建付款和领取的状态读写不同，首次写入、后续更新、成功和失败路径也可能产生不同成本。测量记录应包含输入、前置状态、执行结果和查询时间，便于解释结果差异。

fee_limit 限制调用方侧一次合约执行可使用的 Energy 总预算，不是固定手续费，也不是合约安全保证。策略需要结合实测 Energy、动态能量、链参数和失败影响制定，并在调用前重新估算或保留合理余量。历史测量可以作为基线，但不能永久代替当前估算。

安全检查需要继续覆盖权限、时间、重入、外部转账失败、意外 TRX、资金无法领取和管理员能力等风险。静态分析工具可以辅助发现问题，但不能完全理解 TVM 专有行为，也不能替代与合约资金规模相匹配的人工审计。

阶段实践

在 Shasta 上分别测量合约部署、创建付款、到期领取和主要失败路径。记录交易类型、输入、前置状态、估算结果、已固化 receipt 中的 Energy 与 Bandwidth、执行结果和使用的 fee_limit。

根据测量结果形成 Energy 基线和 fee_limit 策略，说明估算来源、余量、重新估算时机和异常处理。同时完成安全检查表，对每项风险记录检查方法、结果、尚未解决的问题和是否阻止发布。

进入部署与发布阶段前：确认主要调用已有可解释的 Energy 基线和 fee_limit 策略，安全检查没有未处理的发布阻断项。下一阶段将使用同一源码和配置完成 Shasta 发布验收。

6. 完成部署与发布记录

发布候选版本应由前面验证过的源码、依赖和编译配置直接生成。部署前再次核对源码提交、构建产物、目标网络、部署账户、构造参数和资源准备，避免临时修改后跳过测试与成本评估。

部署交易成功广播后，还需要检查执行结果、保存合约地址，并完成基本读写检查。广播接收不等于执行成功；发布记录应保存原 txID，并等待已固化 receipt 后再判断部署结果。源码验证必须使用与部署完全一致的源码、编译器和优化配置；验证通过只说明公开源码与链上字节码匹配，不代表合约已经通过安全审计。

完整发布记录应能把链上合约追溯到源码和测试证据，包括版本或提交、构建配置、ABI 与字节码、测试结果、Energy 基线、安全检查、部署 txID、合约地址、源码验证状态和已知限制。

阶段实践

从已经完成测试和安全检查的源码提交重新构建合约，并部署到 Shasta。保存部署账户、目标网络、构造参数、部署 txID、合约地址、已固化交易收据和资源消耗，再使用该地址完成一次创建付款和一次到期领取。

使用阶段 1 固定的源码和编译配置完成合约源码验证。最后整理发布记录，把源码版本、构建产物、测试结果、Energy 基线、安全检查、部署证据、验证结果和已知限制放在同一份候选版本记录中。

验证发布结果：Shasta 上的合约能够完成正常创建和领取，并按预期拒绝主要无效操作。合约地址可以追溯到对应的源码、构建配置、测试、安全检查、成本基线和源码验证记录。

后续实践与扩展

完成这条路线后，应得到一个可重复构建的定时付款合约工程，以及正常与异常测试、Energy 基线、安全检查、Shasta 合约地址和源码验证记录。这些材料共同说明当前版本具备进入进一步评审的条件，但不能代替独立安全审计和生产发布决策。

如果合约需要升级、长期运维或管理多个版本，可以继续阅读升级智能合约 — 引入合约升级的架构弊端和最佳实践 — 部署后的运维保障，补充升级权限、迁移、监控和应急处理方案。

如果只完成了其中一部分，可以保留当前源码提交、构建产物、测试结果和测量记录，之后再从相应阶段继续。任何源码或配置变化都应重新执行受影响的构建、测试、成本和发布检查。

如果某个阶段仍然无法继续，请提交路线反馈，注明“路线 4”、当前阶段、工具版本、Shasta Endpoint、已经完成的步骤和实际错误信息；不要提交私钥、助记词、API Key、未公开漏洞细节或生产账户信息。