路线 1：交易所与托管钱包集成

本路线可以作为交易所、支付平台和托管钱包接入 TRON 的起点，适合需要代用户管理充值地址、提现签名和内部账务的团队。

可以从这条路线了解什么

这条路线从账户与资产模型出发，依次介绍数据入口、充值识别、幂等入账、提现处理，以及对账与故障恢复。

路线以一个支持 TRX 和一种测试 TRC-20 Token 的最小充提闭环为贯穿任务。各阶段围绕同一组 Shasta 测试账户，逐步形成充值候选记录、幂等账务、提现链上结果和对账记录。

如果希望一边阅读一边实践，可以按照各阶段逐步补齐这些能力。本路线完成的是用于验证数据与账务流程的测试服务，不代表已经满足真实资金托管所需的密钥基础设施、审批制度、合规、安全审计、容量或可用性要求。

开始前不必一次掌握全部节点接口和账务规则。可以先通过下方概览了解各阶段的重点，再围绕同一笔充值和提现逐步建立闭环；遇到确认、事件解析或广播问题时，再回到推荐阅读补充所需信息。

路线概览

阶段	主要内容	最小充提闭环中的任务
1. 定义账户与资产模型	明确网络、地址、资产标识、金额精度和密钥职责	建立测试账户、资产注册表和职责边界
2. 确定数据入口	区分充值发现、固化确认、提现广播和余额对账的数据来源	形成接口与数据语义映射表
3. 识别充值	从已固化数据识别 TRX 转账和 TRC-20 `Transfer` Event	为两种测试充值生成候选记录
4. 实现幂等入账	使用交易、事件和区块位置建立稳定唯一键	使同一区块范围可以安全重扫而不重复记账
5. 实现提现	完成审核、资源准备、构建、本地签名、广播和状态跟踪	完成 TRX 与测试 TRC-20 提现
6. 对账与恢复	验证游标回退、查询超时、重复广播和账实核对	形成恢复演练与对账记录

开始前

建议先了解后端服务、数据库事务、HTTP API 和基本账务概念，并熟悉 TRON 的账户与地址、交易结构、已固化状态和 TRC-20 。如果尚不清楚交易所接入的整体边界，可以先阅读交易所及托管钱包集成 — 集成核心工作清单。

完成阶段实践需要一个 Shasta HTTP Endpoint 、一个能够查询已固化数据的接口、至少两个只用于测试的账户，以及一种可验证的测试 TRC-20 Token。如果还没有测试 Token，可以参考用 TronWeb 部署 TRC-20 Token ；该 Recipe 需要先准备实际编译得到的 ABI 与字节码。

所有金额都应以整数最小单位存储：TRX 使用 sun ，TRC-20 使用目标合约声明的 decimals 解释展示精度。测试密钥不得用于真实资产，也不能进入充值扫描器、日志或普通业务数据库。

本路线主要梳理充值、提现和对账如何使用 TRON 数据。具体节点部署、API 参数、Event 解码和签名代码请参考各阶段链接的文档。生产系统还需要另行设计冷热钱包、HSM 或其他隔离签名环境、多级审批、合规审查和应急处置。

路线阶段

1. 定义账户与资产模型

托管系统首先需要明确自己管理哪些账户和资产。充值地址、归集地址、提现热钱包和冷钱包承担不同职责，即使最小原型暂时复用少量测试账户，也应在数据模型中区分这些角色，避免把地址所有权、用户归属和签名权限混在一起。

充值地址还需要记录链上账户是否已经激活。向未激活地址发送首笔 TRX 会创建账户状态，并由发送方承担账户创建费用及相关 Bandwidth 成本；系统不能把“尚无账户状态”与“已激活但余额为零”视为同一种情况。

网络和资产都需要稳定标识。TRON 当前不同网络使用相同的地址前缀，不能只凭地址判断 Mainnet 或 Shasta；网络必须进入配置和业务唯一键。TRX 可以使用网络与原生资产类型标识，TRC-20 则应使用网络与合约地址标识，不能只依赖可能重复或发生变化的 Token symbol。

金额应以整数最小单位记录。TRX 的最小单位是 sun，TRC-20 的 decimals 由目标合约定义；decimals 和 symbol 用于展示，不应改变账本中保存的原始整数。资产注册表还需要记录允许的合约地址、充值状态、提现状态和最小业务金额等策略。

密钥职责也需要在第一阶段划开。充值扫描和余额查询只需要地址；交易构建可以在不接触私钥的服务中完成；只有受控 signer 能够签署经过审核的提现交易。测试原型可以使用隔离的测试 signer，但不能把签名能力放入对外 API 或扫描进程。

阶段实践

建立一份账户表，记录测试地址、网络、业务角色、用户归属、是否允许充值、是否允许提现和签名方式。再建立资产注册表，分别记录 Shasta TRX 和一种测试 TRC-20 Token 的资产 ID、合约地址、symbol、decimals、最小单位与充提状态。

绘制扫描器、充值服务、账本、提现审核、交易构建、signer 和广播服务之间的职责图。明确哪些模块只读取地址，哪些模块可以生成待签交易，哪个模块能够访问测试密钥，以及各模块允许写入的数据。

确定数据入口前：确认网络、账户角色、资产标识、金额精度和密钥职责都有固定定义，并且 TRC-20 资产不会仅凭名称或 symbol 识别。

2. 确定数据入口

充值、提现和对账使用的数据语义不同，不能全部依赖同一个“交易查询”接口。充值发现可以扫描 SolidityNode 的已固化区块，也可以使用带有已确认过滤条件的索引接口；关键入账仍需要保留已固化区块或收据证据。提现构建与广播需要 FullNode，最终提现状态则需要 SolidityNode。

索引服务适合按账户查询 TRX 和 TRC-20 历史，但需要处理分页、限流、重试和索引延迟。自建区块扫描可以控制游标与解析过程，却需要自行维护节点、逐块读取并解析 receipt。最小原型可以选择其中一种作为主要充值入口，同时保留能够按 txID 和区块高度复核结果的固化查询。

对账需要记录明确的数据截止点。标准余额接口不能按任意历史高度返回快照，因此最小原型可以在余额查询前后读取同一 SolidityNode 的最新已固化高度；高度变化时重新查询，或把变化区间中的充提列为在途项。需要严格重建历史高度余额时，应另行验证归档查询能力，或通过本地资产流水回放。

每个接口都应记录网络、Endpoint、数据来源、观察到的区块高度、是否为索引数据和失败时的重试方式。

阶段实践

建立接口映射表，分别列出 TRX 充值发现、TRC-20 充值发现、固化复核、提现构建、提现广播、提现结果查询、TRX 余额和 TRC-20 余额所使用的 Endpoint、接口类型、数据来源、观察高度和超时策略。

调用最新区块、最新已固化区块和一种索引查询，保存返回高度与时间。确认充值和最终提现状态不会从未固化链头直接得出，并为索引结果定义“候选发现后如何回到固化数据复核”的路径。

识别充值前：确认每项业务都连接到符合其语义的数据入口，索引结果不会被直接等同于节点原生状态，并且对账使用的观察高度与在途区间可以被记录和复现。

3. 识别充值

充值扫描应从已经固化的数据中识别平台控制地址收到的资产。对普通 TRX 转账，需要解析 TransferContract 的发送方、接收方和 sun 金额，并核对接收方是否映射到平台账户。只有网络、资产、目标地址和金额都符合规则时，才能形成充值候选。

TRC-20 充值需要解析执行成功交易 receipt 中的 Transfer(address,address,uint256) Event 。事件发出方必须等于资产注册表中的 Token 合约地址，Event 的接收地址必须属于平台，金额则按 uint256 原始整数记录。只看 TriggerSmartContract 的调用 selector 或参数会遗漏由其他合约路径触发的转账，也不能证明合约执行成功。

充值候选记录需要保留足够的链上证据，包括网络、资产 ID、txID、区块高度与哈希、交易位置、合约或 Event 位置、发送方、接收方、原始金额、执行结果和发现来源。低于最小充值金额或资产尚未开放时，也应形成可审计的拒绝或待处理记录，而不是静默丢弃。

最小原型可以只支持顶层 TransferContract 形式的 TRX 充值。如果产品允许通过合约路径接收 TRX，生产前还需要解析 receipt 中的 internal_transactions[] ，排除 rejected = true 的记录，并把内部转账位置纳入唯一键和测试范围。

阶段实践

向平台测试地址发送一笔小额 Shasta TRX 和一笔允许列表内的测试 TRC-20 Token。通过已固化区块扫描或已确认索引接口发现交易，再用固化数据复核，为两笔充值生成包含完整链上位置与原始整数金额的候选记录。

继续准备错误 Token 合约、非平台接收地址、失败的合约调用和低于最小金额等样本，确认它们不会进入可入账状态。若最小原型不支持合约内部 TRX 转账，应在服务说明和测试记录中明确这一限制。

实现幂等入账前：确认 TRX 与 TRC-20 候选都来自已固化数据，TRC-20 记录经过合约地址、Event 和执行结果核对，并且每条候选都能定位到具体区块、交易和事件位置。

4. 实现幂等入账

充值扫描会因为程序重启、分页重试、游标回退或人工复核而重复看到同一笔链上转账。安全重扫的关键不是避免重复读取，而是让同一链上动作无论被处理多少次，都只能产生一次有效账务变化。

不同资产需要不同的事件级位置。顶层 TRX 转账可以使用网络、资产 ID 和 txID 组成业务唯一键。TRC-20 转账则使用网络、Token 合约地址、txID 和事件位置：节点 receipt 使用 log[] 数组位置，TronGrid Event 使用 event_index。区块高度、区块哈希和交易索引用于恢复与审计，但不应单独代替稳定的交易或事件身份。

候选写入、唯一键检查和账本入账应在同一个数据库事务中完成，并由数据库唯一约束承担最后一道防线。账务状态可以区分已发现、已验证、已入账、待人工处理和已拒绝，但状态重试不能再次增加用户余额。账本应保留不可变流水，不以直接覆盖余额代替入账记录。

阶段实践

为 TRX 和 TRC-20 充值分别建立业务唯一键与数据库唯一约束。按照幂等入账 Recipe 把上一阶段的候选记录映射到测试账户，在同一事务中写入充值记录和账本流水，再更新已处理区块与扫描游标。

对同一区块范围连续扫描两次，并模拟重复分页、两个 worker 同时处理同一 Event，以及写入过程中断后重试。每个场景都应得到相同的最终账本余额，且每个链上转账只有一条有效入账流水。

实现提现前：确认充值扫描可以重复执行，数据库唯一约束和事务能够阻止重复余额变化，并且账本流水仍保留原始 txID、事件位置和固化区块证据。

5. 实现提现

提现需要把业务请求与链上交易分开管理。业务提现 ID 用于接收请求、执行风控和审批，txID 则对应一次已经构建的链上交易尝试。两者不能互相替代，因为交易过期后可能需要重新构建新的 txID，而同一业务请求仍然只能支付一次。

审核通过后，需要核对网络、资产、目标地址、原始整数金额、提现限额和账户余额。TRX 提现需要准备 Bandwidth 或可支付费用的 TRX；TRC-20 提现还需要准备 Energy、Token 余额和合理的 fee_limit 。交易应在接近签名和广播时构建，避免 TAPOS 引用或 expiration 在审批等待期间失效。

签名必须在受控环境中完成。signer 只接受已经审核且符合地址、金额和资产策略的待签数据，并返回能够在广播前本地验证的签名。普通业务服务不持有私钥，也不能修改签名后的 raw_data。

广播后应持续跟踪原 txID。节点接收不等于提现完成，只有执行成功并固化后才能进入最终成功状态。广播超时或重复交易错误时，先查询并重播同一笔已签名交易；只有确认原交易未上链且已过期后，才能在同一业务提现记录下创建新的交易尝试。

阶段实践

分别创建一笔 Shasta TRX 提现和一笔测试 TRC-20 提现。记录业务提现 ID、审核结果、资源与费用检查、待签交易、签名验证和首次 txID，再广播并查询交易本体、执行收据和已固化结果。

模拟一次广播响应超时，确认服务继续查询并重播原 txID，不会生成第二笔付款。再模拟一笔已过期且确认未上链的交易，验证新交易尝试会获得新的 txID，同时仍受原业务提现 ID 的单次支付约束。

进行对账与恢复前：确认提现审核、签名和广播职责已经分离，TRX 与 TRC-20 费用准备充分，链上状态使用原 txID 跟踪，并且业务幂等不会因重建交易而失效。

6. 对账与恢复

充提服务需要能够从重复数据、暂时失败和进程中断中恢复。扫描游标只能在一个区块中的候选与账务全部提交后前移；服务重启或数据存疑时，应能够回退到更早的已固化高度重新扫描。查询超时表示结果未知，不能直接解释为没有充值或提现失败。

恢复测试还需要覆盖广播。相同已签名交易可以按原 txID 重播，但已经过期的交易必须重新构建并重新签名。系统应保留每次交易尝试与同一业务提现 ID 的关系，使任何时刻都能判断是否已经存在可能上链的付款。

对账应按网络、资产和托管地址设置明确的固化数据截止点。最小原型可以在余额查询前后读取同一 SolidityNode 的最新已固化高度：高度不变时记录该高度与查询结果；高度变化时重新查询，或把区间内新增的充提列为在途项。然后分别比较 TRX 与每个 TRC-20 合约的链上余额和内部账本，并单独列出待处理项目、费用和调整项。标准余额接口不能被当作任意历史高度快照接口。

阶段实践

依次执行以下恢复场景：重复扫描同一区块范围；将游标回退若干已固化区块；在分页中途停止并重启扫描器；使充值或余额查询超时；重复广播同一笔已签名提现交易。记录每个场景的发现方式、恢复动作和最终账务结果。

最后生成一份 Shasta 对账表，分别列出 TRX 和测试 TRC-20 的固化数据截止点、余额查询前后观察到的固化高度、链上余额、内部账本余额、待处理项目、费用或调整项、计算差异和处理结论。任何无法解释的差异都应保留为未通过项，不能通过修改余额直接消除。

验证最小充提闭环：确认充值可以从固化数据安全重扫，提现能够按业务 ID 和原 txID 恢复，TRX 与 TRC-20 在明确的数据截止点完成对账，所有差异都有证据与处理结论。

后续实践与扩展

完成这条路线后，应得到一个最小充提闭环服务、一组可重扫的充值账务记录、TRX 与测试 TRC-20 提现的链上结果、幂等规则、恢复演练和对账记录。

进入生产准备前，还需要补充冷热钱包和归集策略、HSM 或其他隔离签名环境、多级审核、提现限额、地址风险控制、密钥备份与轮换、数据库灾难恢复、监控告警、容量测试和安全审计，并根据所在地和业务范围完成相应合规流程。

如果后续支持 TRC-10、NFT、合约内部 TRX 转账、批量提现、Active 权限或多签，应为每种资产和交易路径分别定义识别规则、事件级唯一键、费用模型、签名权限和对账方法，不能直接复用 TRX 或单一 TRC-20 的假设。

如果某个阶段仍然无法继续，请提交路线反馈，注明“路线 1”、当前阶段、使用的数据入口、已经完成的步骤和实际错误信息；不要提交私钥、助记词、API Key 或生产账户信息。