eth_newBlockFilter

The eth_newBlockFilter method creates a filter in the node to notify when a new block arrives. This is a simpler and more efficient alternative to polling eth_blockNumber repeatedly, as it allows you to receive notifications only when new blocks are detected.

Use Cases

• Block synchronization for applications and explorers
• Triggering block-based actions in automated systems
• Confirmation tracking for transactions in wallets
• Chain reorganization detection for data integrity
• Real-time blockchain monitoring for analytics
• Gas price trend monitoring for fee optimization
• Mining/validation tracking in network analysis
• Detecting network stalls when blocks stop arriving
• Alerting systems for blockchain infrastructure
• Maintaining cache consistency with blockchain state

Method Details

This method takes no parameters and returns a filter ID that can be used with eth_getFilterChanges to poll for new blocks.

Response Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x3a85885a2facbe4b9c99d543b3e42359"
}

How Block Filters Work

1. When you create a block filter, the Ethereum node assigns it a unique ID
2. The node keeps track of the latest block it has shown to your filter
3. When you poll using eth_getFilterChanges, it returns block hashes for any new blocks since your last poll
4. If no new blocks have been produced, it returns an empty array

Return Value Format

When polling with eth_getFilterChanges, this filter returns an array of block hashes:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "0x1a4b5aad3a859c5c6cbbdab46f565475c5c61c163a45e0c2cb732e7221efbe77",
    "0x2573c838b310ca595c83c20ee437139f96658f596afe8a0f726d82db3d9647c2"
  ]
}

Block Data Retrieval

The filter only returns block hashes. To get the full block data, you must make additional calls using:

• eth_getBlockByHash - Get a block's details using its hash

Important Considerations

1. Filter Expiration: Filters expire after a period of inactivity (typically around 5 minutes)
2. Polling Frequency: Balance between timely updates and RPC call limits
3. Block Reorganizations: Be aware that blocks can be reorganized, especially recent ones
4. Chain Consistency: Block filters help maintain application state in sync with the blockchain
5. Alternative Approaches:
   • WebSocket eth_subscribe for real-time push notifications
   • Polling eth_blockNumber directly (less efficient)
6. Rate Limits: Excessive polling can lead to rate limiting from RPC providers
7. Missing Blocks: If poll intervals are too large, you might need to handle multiple blocks at once
8. Filter Management: Always uninstall filters when no longer needed
9. Error Handling: Implement retry logic for temporary network issues
10. Block Processing: Consider processing blocks sequentially to maintain data consistency

Comparison with Other Notification Methods

See also

• eth_getFilterChanges - Retrieve new block hashes since last poll
• eth_uninstallFilter - Remove a filter when no longer needed
• eth_getBlockByHash - Get block details by hash
• eth_newFilter - Create a filter for event logs
• eth_newPendingTransactionFilter - Create filter for pending transactions