eth_newFilter

The eth_newFilter method creates a filter object to notify when new logs (events) matching the given filter criteria are included in the blockchain. This method is crucial for monitoring smart contract events and is one of the fundamental building blocks for reactive dApp architectures.

Use Cases

• Monitoring smart contract events in real-time applications
• Tracking token transfers (ERC-20, ERC-721, ERC-1155) for wallets
• Detecting state changes in DeFi protocols and liquidity pools
• Building event-driven blockchain applications with high responsiveness
• Implementing real-time notifications for user activities
• Historical data aggregation from contract events for analytics
• Automatic UI updates based on blockchain events in dApps
• Monitoring NFT marketplace activities (listings, sales, bids)
• Tracking governance votes and proposal executions
• Creating activity feeds for blockchain applications

Method Details

This method takes a filter object as a parameter and returns a filter ID that can be used with eth_getFilterChanges and eth_getFilterLogs.

Response Example

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

Understanding Topics and Event Signatures

The topics array is one of the most powerful features of Ethereum log filtering. It allows you to match specific indexed event parameters:

1. Topic[0]: Usually the event signature hash (keccak256 of the event name and parameter types)
2. Topic[1]: First indexed parameter
3. Topic[2]: Second indexed parameter
4. Topic[3]: Third indexed parameter

How Event Signatures Work

Event signatures are created by taking the keccak256 hash of the event name and its parameter types:

// Solidity event definition
event Transfer(address indexed from, address indexed to, uint256 value);

// Event signature is calculated as:
keccak256("Transfer(address,address,uint256)")
// Which equals:
// 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef

Ethereum events can have up to 4 topics (1 event signature + 3 indexed parameters).

Topic Matching Rules:

• Null: Matches any value in that position
• String: Matches exact value in that position
• Array of strings: Matches any value in the array (logical OR)

Common Event Signatures

Using the Filter ID

After creating a filter, you'll receive a filter ID that can be used with:

1. eth_getFilterChanges - To poll for new logs since the last poll
2. eth_getFilterLogs - To get all logs matching the filter criteria
3. eth_uninstallFilter - To remove the filter when no longer needed

Important Notes and Best Practices

1. Filter Expiration: Filters expire after a period of inactivity (typically around 5 minutes)
2. Topic Padding: Address topics must be padded to 32 bytes (zero-padded on the left)
3. Performance: Wide filters (e.g., many addresses or blocks) can be resource-intensive
4. Rate Limits: Excessive polling can lead to rate limiting from RPC providers
5. Block Range: Very large block ranges may cause timeouts or be rejected
6. Filter Limits: Some providers limit the number of active filters per connection
7. Alternative: Consider using WebSocket subscriptions for real-time events when available
8. Indexed vs Non-indexed: Only indexed parameters appear in topics; non-indexed are in data field
9. Data Field: For complex events, the data field needs ABI decoding to extract values
10. Topic Order: Topic order is critical and must match the order of indexed parameters

See also

• eth_getFilterChanges - Retrieve new logs since last poll
• eth_getFilterLogs - Get all logs matching filter criteria
• eth_uninstallFilter - Remove a filter when no longer needed
• eth_getLogs - Query logs without filter persistence
• eth_newBlockFilter - Create filter for new blocks
• eth_newPendingTransactionFilter - Create filter for pending transactions