ZeroMQ 事件插件

📘
前置阅读

事件订阅概述

部署节点

java-tron 全节点内置了 ZeroMQ 事件发布器（设计规范见 TIP-28）。与 Kafka 或 MongoDB 等插件方案不同，使用 ZeroMQ 机制时，全节点进程无需加载任何额外的外部插件 JAR 包——全节点会自动监听指定的 TCP 端口以提供发布-订阅（Pub-Sub）套接字，任何 ZeroMQ 客户端都可以直接建立连接。

这是维护和配置成本最低的事件接入方案。它不会在本地持久化保留事件数据，属于纯实时流；若客户端与全节点断开连接，将丢失离线期间发布的所有消息。如果需要在局域网内快速集成、用于开发调试或短期实时订阅，ZeroMQ 是轻量选择。需要高可靠性持久化和消息重播时，请参阅 Kafka 插件部署指南；需要基于条件搜索历史事件时，请参阅 MongoDB 插件部署指南。

节点配置

在 config.conf 的 event.subscribe 节点下配置并启用原生消息队列：

event.subscribe = {
  native = {
    useNativeQueue = true     // 设为 true 启用内置 ZeroMQ，为 false 时则路由至外部插件
    bindport = 5555           // ZeroMQ 发布器监听的 TCP 端口
    sendqueuelength = 1000    // 消息缓存队列的最大容量，超出时将通过背压丢弃新事件
  }

  // ...

  topics = [
    {
      triggerName = "block"   // 触发器标识符——完整列表参见事件订阅概述
      enable = true
      topic = "block"         // 映射出的 ZeroMQ 订阅主题（Topic）名称
    },
    // 更多触发器配置...
  ]
}

各配置字段说明：

字段名	核心含义
`native.useNativeQueue`	设为 `true` 以激活内置 ZeroMQ。若设为 `false`，全节点将通过外部插件（如 Kafka/MongoDB）分发事件。
`native.bindport`	发布服务绑定的 TCP 端口。客户端需要连接至 `tcp://<节点 IP>:<bindport>`。
`native.sendqueuelength`	缓存队列的最大条数。如果消费端的消费速率过慢导致队列积压已满，新产生的事件将被丢弃。请结合业务吞吐量合理配置此阈值。
`topics`	过滤订阅配置。定义需要发布哪些类型的事件，以及各自映射为 ZeroMQ 客户端订阅的主题（Topic）名。可选的 `triggerName` 标识符请参阅事件订阅概述。

启动节点

全节点的事件订阅模块默认关闭。启动命令中必须显式附加 --es 参数来激活：

java -jar FullNode.jar --es -c config.conf

节点启动后会监听配置好的端口。此时，任何 ZeroMQ 订阅客户端均可连接并开始实时接收数据。

使用 Node.js 客户端订阅示例

首先，在 Node.js 项目中安装 ZeroMQ 客户端依赖库。新项目推荐使用最新版 zeromq（支持 TypeScript 及原生绑定）：

npm install zeromq

注：如果维护的是老旧项目，也可以安装早期版本 npm install zeromq@5。以下示例以 v5 的 CommonJS 接口形式演示：

编写客户端订阅脚本，连接到全节点并监听 block 主题：

// subscriber.js (支持 zeromq v5 接口)
const zmq = require("zeromq");
const sock = zmq.socket("sub");

sock.connect("tcp://127.0.0.1:5555");
sock.subscribe("block");
console.log("ZeroMQ 订阅客户端已成功连接至端口 5555");

sock.on("message", function (topic, message) {
    console.log(
        "收到订阅事件，主题:",
        Buffer.from(topic).toString(),
        "| 事件载荷:",
        Buffer.from(message).toString()
    );
});

运行订阅脚本：

node subscriber.js
# ZeroMQ 订阅客户端已成功连接至端口 5555

当全节点打包并生产新区块时，客户端将实时收到如下区块事件推送：

收到订阅事件，主题: block | 事件载荷: {"timeStamp":1678343709000,"triggerName":"blockTrigger","blockNumber":1361,"blockHash":"00000000000005519b3995cd638753a862c812d1bda11de14bbfaa5ad3383280","transactionSize":0,"latestSolidifiedBlockNumber":1361,"transactionList":[]}
收到订阅事件，主题: block | 事件载荷: {"timeStamp":1678343712000,"triggerName":"blockTrigger","blockNumber":1362,"blockHash":"0000000000000552d53d1bdd9929e4533a983f14df8931ee9b3bf6d6c74a47b0","transactionSize":0,"latestSolidifiedBlockNumber":1362,"transactionList":[]}

对于其他语言的 ZeroMQ SDK（如 Python 的 pyzmq、Go 的 pebbe/zmq4、Java 的 jeromq），调用原理完全一致：连接对应的 TCP 端口，订阅指定的 Topic 名称，并将接收到的字节流按照 UTF-8 格式解析为 JSON 即可。

前置阅读

节点配置

启动节点

使用 Node.js 客户端订阅示例

相关资源