Skip to main content

​
Purpose and Scope

This document describes the event filtering and subscription system designed to allow clients to efficiently query blockchain data and receive real-time notifications for new blocks, transactions, and logs.
The system provides both traditional polling-based filters and WebSocket-based subscription mechanisms, supporting a wide range of client environments and usage patterns. For information on the general RPC API structure and namespaces, refer to API Services and Namespaces.

​
Overview

Through the filtering and subscription system, clients can use the following features:
  • Query historical logs that match specific conditions (contract addresses, topics, block ranges)
  • Receive real-time events for new blocks, pending transactions, and logs
  • Efficiently match logs over large block ranges using Bloom filters
  • Poll for changes using filter IDs
  • Use server-push–based subscriptions via WebSocket
The implementation is primarily located in the eth/filters package and is tightly integrated with the blockchain event feed system.

​
Filter API Methods

FilterAPI provides RPC endpoints for creating, querying, and removing filters.
This API supports both polling-based filters and WebSocket-based subscriptions.

​
Core RPC Methods

MethodDescriptionReturn Type
eth_newFilterCreate a condition-based log filterFilter ID
eth_newBlockFilterCreate a new block hash filterFilter ID
eth_newPendingTransactionFilterCreate a pending transaction filterFilter ID
eth_getFilterChangesRetrieve changes since the last callLogs / Hashes
eth_getFilterLogsRetrieve all logs matching the filter criteriaLogs array
eth_getLogsOne-off log queryLogs array
eth_uninstallFilterRemove a filterBoolean

​
Subscription Methods (WebSocket)

MethodDescriptionEvent Type
eth_subscribe("newHeads")Subscribe to new block headersHeader
eth_subscribe("logs", criteria)Subscribe to logs matching criteriaLog
eth_subscribe("newPendingTransactions")Subscribe to pending transactionsTx hash / object
eth_unsubscribeUnsubscribeBoolean

​
System Architecture

​
Component Overview

The event filtering system is composed of two main components: FilterSystem and EventSystem.

​
FilterSystem

FilterSystem manages resources shared by all filter instances and serves as the entry point for filter creation. Key Fields:
  • backend Backend – Interface for accessing blockchain data
  • logsCache *lru.Cache[common.Hash, *logCacheElem] – Cache of recent block logs
  • cfg *Config – Cache size and timeout configuration
The log cache stores logs from recently accessed blocks, reducing repeated database access and minimizing response latency.

​
EventSystem

EventSystem is a central event dispatcher that manages all active subscriptions and delivers blockchain events to the appropriate subscribers.
It receives events from multiple event feeds and filters them according to subscription criteria before delivery.

​
Filter Types and Execution

​
Log Filters

Log filters search for log events that match specified criteria within a given block range or within a single block. FilterCriteria Structure:
FieldTypeDescription
FromBlock*big.IntStarting block (nil means latest)
ToBlock*big.IntEnding block (nil means latest)
BlockHash*common.HashTarget a single block
Addresses[]common.AddressList of contract addresses
Topics[][]common.HashTopic filters
Topic Matching Rules:
  • Each position may contain multiple topics (OR condition)
  • If a position is nil, it always matches
  • AND conditions apply across positions
  • A maximum of 4 topic positions is supported

​
Bloom Filter Optimization

To improve performance when searching large log ranges, a two-stage Bloom filtering approach is used.
  1. Block Header Bloom – A 2048-bit Bloom filter included in each block header
  2. Section Bloom Index – Groups blocks into sections to support bit-level searching
Bloom Filter Algorithm Overview: 
Hash = Keccak256(data)
For i in [0, 2, 4]:
  BitIndex  = (Uint16(Hash[i:i+2]) & 0x7FF) >> 3
  BitOffset = Hash[i+1] & 0x7
  Bloom[BitIndex] |= (1 << BitOffset)

​
Subscription Lifecycle

​
Polling-Based Filters

In environments where WebSocket is not available, the server maintains filter state and clients periodically poll for changes. Filter Timeout Management:
  • The default timeout is 5 minutes
  • The timer is refreshed on each eth_getFilterChanges call
  • Filters are automatically removed after a period of inactivity
This mechanism prevents resource leaks caused by long-abandoned filters.

​
Event Delivery and Filtering

​
Chain Reorganization Handling

When a chain reorganization occurs, the system generates a RemovedLogsEvent and delivers it to subscribers. The processing flow is as follows:
  1. Detect a chain reorganization during block insertion
  2. Generate events with logs from removed blocks
  3. Set the Removed: true flag on log objects
  4. Clients adjust their state based on the removed logs

​
Backend Integration

The filter system abstracts blockchain data access through the Backend interface.
This allows the same filter logic to be reused without being tightly coupled to a specific full node implementation. Key backend implementations delegate responsibilities to the following components:
  • Historical block data – BlockChain
  • Pending transactions – TxPool
  • Pending block construction – Miner
  • Bloom bit searching – BloomIndexer

​
Error Handling and Edge Cases

ErrorCauseHandling
errInvalidBlockRangeStart block is greater than end blockReject filter creation
errFilterNotFoundFilter ID does not existReturn empty result
errExceedMaxTopicsExceeded maximum topic positionsReject filter creation
unknown blockBlock hash not foundReturn error
Context cancelConnection closedAbort query
Through this error-handling logic, the system ensures stable and reliable event delivery.