eth_getFilterChanges

The eth_getFilterChanges method returns an array of logs which occurred since the last poll for the specified filter. This powerful subscription method works with filters created by eth_newFilter, eth_newBlockFilter, and eth_newPendingTransactionFilter, allowing efficient monitoring of blockchain activity without constantly rescanning historical data.

Use Cases

Efficient event monitoring with minimal resource usage
Real-time dApp updates and notifications
Smart contract state tracking and synchronization
Transaction confirmation monitoring
Token transfer detection and wallet updates
Protocol activity analytics and metrics dashboards
Batch processing of blockchain events
Resource-efficient blockchain monitoring at scale
Log-based automation and triggers
Trading bot notifications and market monitoring

Method Details

This method takes a filter ID and returns any new logs that match the filter criteria since the last poll, providing the foundation for event-driven blockchain applications.

Response Example

1{
2  "jsonrpc": "2.0",
3  "id": 1,
4  "result": [
5    {
6      "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
7      "topics": [
8        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
9        "0x000000000000000000000000a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
10        "0x00000000000000000000000023a6b9c321aba35d18ca26e66824e917778d9d2b"
11      ],
12      "data": "0x0000000000000000000000000000000000000000000000003635c9adc5dea00000",
13      "blockNumber": "0x10892bc",
14      "transactionHash": "0x56b28388cadcf4da8cbd30aa3c3f126e0513550e6fab6fc20992f3e1435846c8",
15      "transactionIndex": "0x3",
16      "blockHash": "0x6b092af2e8fbe2ceba2034ef4f334f3274a1cce5ffe955fa1895565d9278dac7",
17      "logIndex": "0x7",
18      "removed": false
19    }
20  ]
21}

Understanding Log Objects

Each log object contains the following fields that provide comprehensive event information:

address: Contract address that generated the event
topics: Array of 0-4 32-byte topics (indexed parameters)
- First topic is typically the event signature hash (keccak256 of the event name and parameters)
- Subsequent topics are indexed event parameters (limited to 32 bytes each)
data: Contains the non-indexed event parameters (hex string)
blockNumber: Block number where the log was created
transactionHash: Transaction hash that generated the log
transactionIndex: Transaction's index position in the block
blockHash: Hash of the block where the log was created
logIndex: Log index position in the block
removed: true if the log was removed due to a chain reorganization (reorg)

Common Event Signatures

Some frequently monitored event signatures (first topic):

ERC-20 Transfer: 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
ERC-20 Approval: 0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925
ERC-721 Transfer: 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef (same as ERC-20)
Uniswap V2 Swap: 0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822

Complete Polling Implementation

Here's a complete pattern for effective event polling:

1// 1. Create a filter for a specific event
2async function monitorTokenTransfers(tokenAddress, fromBlock = 'latest') {
3  // ERC-20 Transfer event signature
4  const transferEventSignature = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
5  
6  // Create the filter
7  const filterId = await provider.send('eth_newFilter', [{
8    address: tokenAddress,
9    topics: [transferEventSignature],
10    fromBlock,
11    toBlock: 'latest'
12  }]);
13  
14  console.log(`Created filter: ${filterId}`);
15  return filterId;
16}
17 
18// 2. Poll for changes
19async function pollForTransfers(filterId, interval = 10000) {
20  setInterval(async () => {
21    try {
22      const logs = await provider.send('eth_getFilterChanges', [filterId]);
23      
24      if (logs.length > 0) {
25        console.log(`Found ${logs.length} new transfers`);
26        
27        logs.forEach(log => {
28          // Decode transfer event data
29          const from = '0x' + log.topics[1].slice(26);
30          const to = '0x' + log.topics[2].slice(26);
31          const value = BigInt(log.data);
32          
33          console.log(`Transfer: ${from} → ${to}: ${value}`);
34        });
35      }
36    } catch (error) {
37      console.error('Filter may have expired:', error);
38      // Recreate the filter if needed
39    }
40  }, interval);
41}
42 
43// 3. Clean up when done
44async function stopMonitoring(filterId) {
45  await provider.send('eth_uninstallFilter', [filterId]);
46  console.log(`Filter ${filterId} uninstalled`);
47}

Return Values for Different Filter Types

The response format varies depending on the original filter type:

Log Filter (created with eth_newFilter):
- Returns log objects as shown in the example above
- Contains full event data with all parameters
Block Filter (created with eth_newBlockFilter):
- Returns block hashes as an array of strings
- Example: ["0x4b7", "0x4b8", "0x4b9"]
Pending Transaction Filter (created with eth_newPendingTransactionFilter):
- Returns pending transaction hashes as an array of strings
- Example: ["0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b"]

Important Notes and Best Practices

Filter Expiration: Filters expire after a period of inactivity (typically 5 minutes)
Polling Frequency:
- Too frequent: May cause rate limiting from the provider
- Too infrequent: Risk filter expiration or missing events during reorgs
- Recommended: 10-30 seconds for most applications
Error Handling: Always implement robust error handling for filter expiration
Alternatives: For persistent connections, WebSocket subscriptions are more efficient
Filter Recreation: Be prepared to recreate filters if they expire
Log Processing: Always completely process all returned logs before the next poll
Chain Reorgs: Check the removed flag to handle reorged events properly
Large Responses: Be prepared to handle potentially large batches of logs