Event Filtering and Subscriptions

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

Method	Description	Return Type
eth_newFilter	Create a condition-based log filter	Filter ID
eth_newBlockFilter	Create a new block hash filter	Filter ID
eth_newPendingTransactionFilter	Create a pending transaction filter	Filter ID
eth_getFilterChanges	Retrieve changes since the last call	Logs / Hashes
eth_getFilterLogs	Retrieve all logs matching the filter criteria	Logs array
eth_getLogs	One-off log query	Logs array
eth_uninstallFilter	Remove a filter	Boolean

Subscription Methods (WebSocket)

Method	Description	Event Type
eth_subscribe("newHeads")	Subscribe to new block headers	Header
eth_subscribe("logs", criteria)	Subscribe to logs matching criteria	Log
eth_subscribe("newPendingTransactions")	Subscribe to pending transactions	Tx hash / object
eth_unsubscribe	Unsubscribe	Boolean

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:

Field	Type	Description
FromBlock	*big.Int	Starting block (nil means latest)
ToBlock	*big.Int	Ending block (nil means latest)
BlockHash	*common.Hash	Target a single block
Addresses	[]common.Address	List of contract addresses
Topics	[][]common.Hash	Topic 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

Error	Cause	Handling
errInvalidBlockRange	Start block is greater than end block	Reject filter creation
errFilterNotFound	Filter ID does not exist	Return empty result
errExceedMaxTopics	Exceeded maximum topic positions	Reject filter creation
unknown block	Block hash not found	Return error
Context cancel	Connection closed	Abort query

Through this error-handling logic, the system ensures stable and reliable event delivery.