eth_subscribe
eth_subscribe 方法创建对以太坊区块链上特定事件的订阅。它需要 WebSocket 连接，允许客户端接收关于新区块、待处理交易、日志和同步状态的实时通知。
使用场景
- 构建实时区块链浏览器和仪表板
- 监控智能合约事件而无需持续轮询
- 创建在状态变化时即时更新的响应式 dApp
- 跟踪待处理交易以检测它们何时被挖矿
- 在付款到达时立即接收通知
- 为区块链应用程序实现高效的事件驱动架构
- 以最小的服务器负载监控智能合约活动
- 构建需要实时数据的高性能交易系统
- 实时跟踪节点同步
- 为区块链事件实现 webhook
方法详情
参数:
订阅类型："newHeads", "logs", "newPendingTransactions" 或 "syncing"
可选过滤对象（"logs" 订阅需要）
过滤日志的合约地址（用于日志订阅）
过滤日志的主题（用于日志订阅）
返回值:
订阅 ID，可用于识别订阅并在以后取消订阅
订阅类型
newHeads
订阅接收有关添加到区块链的新区块的信息。这对需要对新区块做出反应或监控链进度的应用程序很有用。
请求
{
"id": 1,
"jsonrpc": "2.0",
"method": "eth_subscribe",
"params": ["newHeads"]
}
响应
带有订阅 ID 的初始响应：
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x9cef478923ff08bf67fde6c64013158d"
}
添加新区块时的后续通知：
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0x9cef478923ff08bf67fde6c64013158d",
"result": {
"difficulty": "0x0",
"extraData": "0xd883010b05846765746888676f312e32302e35856c696e7578",
"gasLimit": "0x1c9c380",
"gasUsed": "0xe8c35a",
"logsBloom": "0x24a0a00e2800a84002408401021c8200410a40340440800900000820804830202d00004204204804800900110314a0088ac11a0a402809a044404a943d0812ce408101342401004a6080490900245000240140901901124288a20d840008200014150600a2080832000220250912a0400124009c00202430c00298b0a8d0822d1a10188080000c0124203a041100601880308406a2600d0420a140801000a4c80a2a0080a5108042302008080a0050a000a44214011610400002090000170003800020d0c1840022008408a4810401d881002202a2100a00204244120200000000810600da940000a0018a40406100006100c044a0202400200420000200211000880",
"miner": "0x86c501ed1cb7123feb9db41f10eca511fb3e1416",
"mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"nonce": "0x0000000000000000",
"number": "0x1b4",
"parentHash": "0x3863a513b3d30160cf76cefee31652f188ddd2e2c9b169bc7d35e324f99cd24e",
"receiptsRoot": "0x28d996993bebb61fb8056d9938f148c3c683e772ae5d53b63ef9bcc601072a66",
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"size": "0x973",
"stateRoot": "0xb9c737605971351a00b9a978b72271874ef3cf0a2dc87a7c4325993ddf84e83f",
"timestamp": "0x64",
"transactionsRoot": "0xf25ff1909e48c93a122b52d9c576b62c141a2f51f3d9b7c53afa7cdb2eec62b2",
"baseFeePerGas": "0x42214d6b"
}
}
}
区块头关键字段
通知包含完整的区块头，具有以下关键字段：
- number：区块高度（十六进制）
- hash：区块哈希（如果仍在待处理状态可能为 null）
- parentHash：父区块的哈希
- timestamp：区块被挖矿时的 Unix 时间戳
- gasUsed：区块中所有交易使用的总燃气量
- gasLimit：区块中允许的最大燃气量
- baseFeePerGas：每单位燃气的基础费用（EIP-1559 后）
- miner：产生区块的矿工/验证者地址
- difficulty：区块难度（合并后为 0）
- size：区块大小（字节）
logs
订阅接收符合特定过滤条件的日志。这对跟踪智能合约发出的事件特别有用。
带过滤选项的请求
{
"id": 1,
"jsonrpc": "2.0",
"method": "eth_subscribe",
"params": [
"logs",
{
"address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
"topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]
}
]
}
过滤选项说明
第二个参数是一个过滤对象，可以包括：
- address（可选）：过滤日志的地址字符串或字符串数组
- topics（可选）：主题过滤器数组，支持 null 作为通配符
- fromBlock（可选）：开始获取日志的区块高度（十六进制）
- toBlock（可选）：获取日志的区块高度（十六进制）
主题数组格式
主题按顺序排列，对应事件签名和索引参数：
- 第一个主题：事件签名的 keccak256 哈希（例如
Transfer(address,address,uint256)） - 第二个主题：第一个索引参数
- 第三个主题：第二个索引参数（如果存在）
- 第四个主题：第三个索引参数（如果存在）
主题可以是：
- 单个主题：需要精确匹配
- Null：接受任何值（通配符）
- 主题数组：数组中的任何主题都将匹配（OR 条件）
响应
带有订阅 ID 的初始响应：
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x4a8a4c0517381924f9838102c5a4dcb7"
}
发出匹配日志时的后续通知：
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0x4a8a4c0517381924f9838102c5a4dcb7",
"result": {
"address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
"blockHash": "0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
"blockNumber": "0x29e87",
"data": "0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
"logIndex": "0x0",
"removed": false,
"topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],
"transactionHash": "0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
"transactionIndex": "0x0"
}
}
}
日志对象字段
每个日志通知包含：
- address：发出日志的合约地址
- topics：包含 0-4 个 32 字节主题的数组，即事件的索引参数
- data：包含日志的非索引参数
- blockNumber：包含交易的区块
- transactionHash：交易的哈希
- transactionIndex：交易在区块中的位置索引
- blockHash：区块的哈希
- logIndex：日志在区块中的索引位置
- removed：当由于链重组而移除日志时为
true，如果是有效日志则为false
newPendingTransactions
订阅接收新待处理交易被添加到交易池时的通知。
请求
{
"id": 1,
"jsonrpc": "2.0",
"method": "eth_subscribe",
"params": ["newPendingTransactions"]
}
响应
带有订阅 ID 的初始响应：
{
"jsonrpc": "2.0",
"id": 1,
"result": "0xc3b33aa549fb9a60e95d21862596617c"
}
添加新的待处理交易时的后续通知：
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0xc3b33aa549fb9a60e95d21862596617c",
"result": "0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc8f1c857"
}
}
重要说明
- 需要 WebSocket：
eth_subscribe仅通过 WebSocket 连接可用，不支持 HTTP - 订阅限制：许多提供者限制每个连接的活动订阅数量
- 遗漏事件：如果连接断开，在断开期间发生的事件会被遗漏
- 链重组：在链重组期间，事件可能被标记为已移除
- 客户端支持：并非所有以太坊客户端都支持所有订阅类型
- 公共节点限制：像 Infura 这样的公共节点可能对订阅进行限流
- 过滤精度：更具体的过滤器可以提高性能并减少数据量
- 安全考虑：WebSocket 具有与 HTTP 不同的安全要求
- 保证交付：与消息队列不同，WebSocket 不保证交付
- 连接稳定性：长时间运行的订阅应实现重连逻辑
另请参阅
- eth_unsubscribe - 取消活动订阅
- eth_newFilter - 基于 HTTP 的日志过滤替代方法
- eth_getLogs - 查询历史事件
- eth_getFilterChanges - 基于轮询的日志替代方法
- eth_newBlockFilter - 新区块的基于 HTTP 的替代方法
- eth_newPendingTransactionFilter - 待处理交易的基于 HTTP 的替代方法
- WebSockets 指南 - WebSocket 连接的综合指南
- 事件日志指南 - 合约事件和日志指南
帮助我们变得更好！
分享此页面并帮助我们为您创建更好的产品。