事件订阅

📘

前置阅读

• 部署节点：仅在自建事件订阅系统时需要

TRON 全节点在运行过程中会持续产生大量链上活动数据，包括区块广播、交易执行和合约日志触发。事件订阅是应用程序接入并消费这股实时数据流的核心机制。具体选用哪种技术方案，主要取决于基础设施维护成本，以及是否需要实时推送之外的历史数据回填（Backfilling）能力。

接入方式对比

前两种方案（TronGrid 与 TronWeb）不需要维护复杂的底层基础设施；后两种方案需要自行搭建并运行 TRON 全节点，但可以避开外部托管服务商的频次限制（Rate Limit），直接高频接入原生事件数据流。

• TronGrid：请参阅按交易 ID 获取事件 API 及 TronGrid V1 API 概览。TronGrid 将底层的事件插件数据格式化封装为扩展 API，并以托管 HTTPS 接口对外开放。
• TronWeb：这是内置了事件订阅辅助方法的 JavaScript SDK，详见 TronWeb 事件 API 文档。适用于主网和测试网，但无法直接订阅本地私链事件。
• 内置 ZeroMQ：TRON 全节点内置的 ZeroMQ 消息发布器（参见 TIP-28），无需额外部署任何插件包。详细配置请参阅 ZeroMQ 事件订阅。
• 自建插件：基于 Kafka 或 MongoDB 的持久化传输方案，这也是本文后续介绍的重点。

事件服务框架

在运行自托管插件时，全节点的**事件服务框架（Event Service Framework）**负责从链上捕获事件、格式化封装并缓存队列，最后异步推送至对应的插件中进行落盘。该框架目前有两个版本，不同版本决定了节点是否具备历史事件回填的能力。

V2.0 框架的设计初衷是为了让下游的索引器能够从特定的历史区块高度开始同步，而不仅限于跟随最新的链头高度。若要深入了解 V2.0 的设计背景与技术选型，请阅读 Event service framework V2.0 introduction。

从 V1.0 迁移至 V2.0 框架

V1.0 与 V2.0 框架共用相同的插件二进制包和订阅过滤器，迁移工作非常简单，主要涉及配置文件的修改：

1. 升级插件包：V2.0 历史同步阶段会引发高吞吐的数据突发，过旧的插件版本可能会引发 JVM 内存溢出（OOM）。请从 event-plugin releases 下载最新版包，或拉取源码重新编译：

   Bash

   git clone https://github.com/tronprotocol/event-plugin.git
   cd event-plugin
   ./gradlew build

2. 在 config.conf 中显式激活 V2.0 框架：

   Text

   event.subscribe.version = 1

3. 保留原有的订阅过滤器配置：topics、filter、path、server 以及 dbconfig 等配置块完全兼容，直接保留即可。

4. （可选）设置历史回填起始区块：

   Text

   event.subscribe.startSyncBlockNum = <block_height>

   • startSyncBlockNum <= 0：不进行历史回填；行为与 V1.0 的纯实时推送一致。
   • startSyncBlockNum > 0：启动历史回填；全节点启动后会从该指定的区块高度开始追溯并向插件投递事件，直至赶上最新区块后转为实时推送。

5. 启动全节点时附加 --es 参数以加载事件模块。

🚧

重要提示：重启全节点前，请核实 startSyncBlockNum 的值。如果配置高度低于消费端已记录的进度，下游会收到重复事件数据；如果配置高度过高，同步会出现数据缺口。这是升级迁移后最常见的数据不一致故障点。

事件类型

TRON 全节点支持投递七种不同类型的事件触发器（Triggers）。可以在配置文件的 topics 数组中针对每种触发器独立选择启用。触发器名（triggerName）是底层固定标识符，只能在消费端自定义主题（Topic）或数据库集合（Collection）的映射名称。

📘

开启过多的事件订阅触发器会显著增加全节点的 CPU 负荷与内存开销。建议遵循“最小化原则”，仅启用业务必需的一到两种类型。

事件载荷结构示例

各类型的触发器投递的 JSON 载荷字段如下：

区块触发器（block / solidity）

timeStamp                     // 区块产生的时间戳
triggerName                   // 触发器类型："blockTrigger" 或 "solidityTrigger"
blockNumber                   // 区块高度
blockHash                     // 区块 ID（Hex 格式字符串）
transactionSize               // 该区块内包含的交易总数
latestSolidifiedBlockNumber   // 当前网络最新的已固化区块高度
transactionList               // 区块内的交易哈希列表

交易触发器（transaction）

blockHash                     // 交易所在区块的 ID
blockNumber                   // 交易所在区块的高度
energyUsage                   // 该笔交易消耗的 Energy 数量
energyFee                     // 交易所消耗的、由 TRX 燃烧转换而来的 Energy 费用
originEnergyUsage             // 由合约部署者承担的 Energy 数量
energyUsageTotal              // 交易消耗的总 Energy（调用者承担 + 部署者承担 + 燃烧 TRX）

合约事件触发器（contractevent / solidityevent）

transactionId                 // 交易哈希
contractAddress               // 合约账户地址
callerAddress                 // 合约调用者（交易发起人）地址
blockNumber                   // 包含该事件的区块高度
blockTimestamp                // 区块时间戳
eventSignature                // Solidity 事件签名定义
topicMap                      // 经过 ABI 解析后的 indexed 参数键值对
data                          // 经过 ABI 解析后的 non-indexed 事件数据字段
removed                       // 布尔值，当发生链分叉回滚（Reorg）导致此日志被撤销时为 true

合约日志触发器（contractlog / soliditylog）

transactionId                 // 交易哈希
contractAddress               // 合约账户地址
callerAddress                 // 合约调用者地址
blockNumber                   // 区块高度
blockTimestamp                // 区块时间戳
contractTopics                // 原始的 32 字节 Topic 列表（Hex 数组）
data                          // 原始的未 indexed 编码事件数据
removed                       // 当由于分叉重组导致日志失效时为 true

关于各触发器字段定义的标准规范，请参阅 TIP-12——事件订阅规范。

过滤语法 (Filter)

可以使用 filter 配置块来缩小合约事件（contractevent）和原始日志（contractlog）的过滤投递范围。该过滤对区块和交易触发器不生效。

自托管插件架构

对于自托管的数据方案，全节点在启动时会在进程内加载一个插件包（标准的 Java .jar 二进制包）。该插件负责将全节点分发的链上事件中继发送至外部的消息中间件或存储引擎中。

┌────────────────┐      事件投递       ┌──────────────┐      网络传输      ┌──────────────┐
│  TRON 全节点   │  ───────────────▶ │   事件插件   │  ────────────────▶  │ 消费订阅程序 │
│  (java-tron)   │   (进程内调用)    │  (.jar 包)   │  (ZMQ/Kafka/Mongo)  │  (业务系统)  │
└────────────────┘                   └──────────────┘                     └──────────────┘

event-plugin 项目提供了两个主要的参考插件实现：

如果不希望运维单独的中间件或插件依赖，全节点内置的 ZeroMQ 消息队列也是一个轻量选择，详情请参阅 ZeroMQ 事件订阅。

此外，也可以基于 java-tron 的事件 SPI 编写自定义中继插件。开发的核心入口是实现 org.tron.common.logsfilter.IPluginEventListener 接口，event-plugin 源码项目可作为开发脚手架和模板。

如何选择合适的方案？

• ZeroMQ：运维复杂度极低，完全无外部依赖，不保存历史状态，适合局域网内单客户端的实时消费或本地测试开发。
• Kafka：支持多分区与偏移量记录，能承载极高的数据吞吐量，支持消息重播和消费进度持久化，是中大型数据中心的首选。
• MongoDB：支持复杂的查询索引。结合 TRON Event Query 查询层服务，可以快速搭建事件查询 HTTP API 服务。

启用事件订阅的通用步骤

无论是哪种插件类型，启用流程都大体相同：

1. 下载或本地编译对应的插件 ZIP 包（解压后为 .jar 依赖包）。
2. 将 JAR 文件存放在全节点进程有读权限的目录中。
3. 在 config.conf 中追加 event.subscribe 块，配置插件文件路径（path）、接收端服务器地址（server）以及对应的触发器过滤规则（topics / filter）。
4. 在全节点的启动命令行中加入 --es 参数，并重新启动全节点。

关于 Kafka 与 MongoDB 插件的具体配置（如身份认证、分片及数据库参数），请阅读各自对应的部署文档。

📘

系统资源提示：事件中继与序列化会为全节点带来额外的 CPU 和内存开销。对于承载关键共识的出块超级代表（SR）节点，强烈建议不要在其上启用事件订阅功能。应当专门额外部署一台只读的同步全节点来承担事件分发任务。

相关资源

• TronGrid V1 API 概览——直接使用现成的 HTTPS 接口查询链上事件
• TronWeb 事件 API——JavaScript SDK 事件消费接口
• ZeroMQ 事件插件——全节点内置的消息队列配置
• Kafka 事件插件——支持高并发与消息重播的 Kafka 接入
• MongoDB 事件插件——适合关系型索引归档与查询的 MongoDB 接入
• Event service framework V2.0 introduction——V2.0 事件框架的更新细节介绍
• TIP-12——事件订阅规范——底层数据交换的标准技术规范
• event-plugin 源码——事件插件开源仓库与 SPI 开发接口
• 监听合约事件——应用层如何捕获智能合约事件的代码示例