Ethereum logs tutorial series: Logs and filters

• Explains how Ethereum logs provide an immutable record of on-chain events, while filters allow targeted retrieval of these logs based on addresses, topics, or block ranges.
• Demonstrates retrieving historical logs with getPastLogs for one-time queries, and real-time subscription to new logs with eth_subscribe for reactive DApps.
• Highlights best practices such as indexing event parameters, breaking large block ranges, caching, and throttling requests.
• Concludes that logs + filters combine to power event-driven, scalable Ethereum applications.

​

Introduction

​

Analyzing Ethereum logs

/**
 * @dev Emitted when `value` tokens are moved from one account (`from`)
 * to another (`to`).
 * Note that `value` may be zero.
 */
event Transfer(address indexed from, address indexed to, uint256 value);

{
    address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    topics: [
      '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
      '0x00000000000000000000000037b2b98ea5d620a4064fc954e9f374c8a28e2125',
      '0x000000000000000000000000dc412bbc1875e588166211defa9c84ac195094cf'
    ],
    data: '0x0000000000000000000000000000000000000000000000000000000047868c00',
    blockNumber: 14673517,
    transactionHash: '0x63aff25171e502638926200a480fbd0365ca0c76d036acaa866f8af5d26e9a61',
    transactionIndex: 311,
    blockHash: '0xfa470ae2ccbe4d1a83b2ab039e300b4fc6d2904db80f8f8a0f4ab890f4240a09',
    logIndex: 531,
    removed: false,
    id: 'log_3cd63a01'
  }

1. address — the address of the contract that generated this log.
2. topics — an array of topics associated with the log. Topics are indexed event parameters that can be used to filter logs.
3. data — the log data as a hexadecimal string. This contains the non-indexed event parameters.
4. blockNumber — the number of the block in which the log was created.
5. transactionHash — the hash of the transaction that generated this log.
6. transactionIndex — the index of the transaction within the block.
7. blockHash — the hash of the block that contains this log.
8. logIndex — the index of the log within the block. In this case, the log index is 531.
9. removed — a boolean value that indicates whether the log was removed due to a chain reorganization.
10. id — a unique identifier for this log entry.

​

Understanding filters

​

Log filters

• Contract address: Monitor events emitted by a specific smart contract.
• Event signature: Filter logs by the event’s unique signature, which is the Keccak-256 hash of the event definition (e.g., Transfer(address,address,uint256)).
• Block range: Limit the logs fetched to a specific range of blocks.
• Indexed event parameters: Filter logs based on specific indexed event parameters, which are used to narrow down the logs relevant to the application’s needs.

​

Block filters

• Fetching the latest gas prices
• Verifying transactions included in a block
• Analyzing block data, such as miner rewards, difficulty, and uncle blocks

​

Pending transaction filters

• Displaying pending transactions in a user’s wallet
• Analyzing transaction behavior, like gas price bidding or transaction propagation
• Estimating transaction confirmation times

​

Accessing logs using filters

​

Prerequisites

1. Head over to Chainstack and create an account.
2. Deploy an Ethereum Mainnet node in Chainstack.

1. Install the following dependencies in your system:
   • Node (version ≥ 16) and the corresponding npm
   • A code editor (VS Code, preferably)
   Once you have everything, the next step is to set up a Node project and install the web.js library.
2. Create a new directory.
3. Open a terminal in the directory.
4. Use the following command to initialize a Node project:
   Shell

   Copy

   npm init -y
   

5. Once the project is initialized, use the following command to install the web.js package:
   Shell

   Copy

   npm install web3
   

6. Within the project, create a new JavaScript file, fetchLogs.js, and add the following lines of code:
   fetchLogs.js

   Copy

   const Web3 = require('web3');
   
   // Add your Chainstack node endpoint (HTTPS)
   const chainstackRpcUrl = 'YOUR_CHAINSTACK_ENDPOINT';
   const web3 = new Web3(new Web3.providers.HttpProvider(chainstackRpcUrl));
   
   // USDC token contract address on Ethereum mainnet
   const usdcContractAddress = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
   
   // The Transfer event signature for ERC20 tokens (keccak256 hash of "Transfer(address,address,uint256)")
   const transferEventSignature = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
   
   // Define the filter options for fetching USDC transfer logs
   const filterOptions = {
     fromBlock: 'latest', // Start from the genesis block
     address: usdcContractAddress,
     topics: [transferEventSignature],
   };
   
   // Fetch logs using the filter options
   web3.eth.getPastLogs(filterOptions).then(logs => {
     // Define the Transfer event ABI
     const transferEventInputs = [
       { type: 'address', name: 'from', indexed: true },
       { type: 'address', name: 'to', indexed: true },
       { type: 'uint256', name: 'value', indexed: false },
     ];
   
     // Process each log
     logs.forEach(log => {
       // Decode the log data
       const decodedLog = web3.eth.abi.decodeLog(transferEventInputs, log.data, log.topics.slice(1));
   
       // Log the decoded transfer event data
       console.log('USDC Transfer:');
       console.log('  From:', decodedLog.from);
       console.log('  To:', decodedLog.to);
   		console.log('  Value (in USDC):', parseInt(decodedLog.value) / 1e6);
     });
   }).catch(error => {
     console.error('Error:', error);
   });
   

   In this code example, we demonstrate how to fetch USDC token transfer event logs using log filters in web3.js. The purpose of this code is to provide a clear and concise example for developers to understand how to interact with the Ethereum blockchain and obtain event logs, specifically for the USDC stablecoin. This information can be useful for applications that need to track token transfers or analyze token transaction history.

​

Subscribing to logs

const Web3 = require('web3');

// Add your Chainstack node endpoint (WSS)
const chainstackRpcUrl = 'YOUR_CHAINSTACK_ENDPOINT';

// Configure reconnect options for WebsocketProvider
const websocketOptions = {
  clientConfig: {
    reconnect: {
      auto: true, // Automatically attempt to reconnect
      delay: 5000, // Reconnect after 5 seconds
      maxRetries: 10, // Max number of retries
    },
  },
};

const web3 = new Web3(new Web3.providers.WebsocketProvider(chainstackRpcUrl, websocketOptions));

// USDC token contract address on Ethereum mainnet
const usdcContractAddress = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';

// The Transfer event signature for ERC20 tokens (keccak256 hash of "Transfer(address,address,uint256)")
const transferEventSignature = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';

// Define the filter options for fetching USDC transfer logs
const filterOptions = {
  address: usdcContractAddress,
  topics: [transferEventSignature],
};

// Subscribe to logs and process USDC transfer events
web3.eth.subscribe('logs', filterOptions, (error, log) => {
  if (error) {
    console.error('Error:', error);
    return;
  }

  // Define the Transfer event ABI
  const transferEventInputs = [
    { type: 'address', name: 'from', indexed: true },
    { type: 'address', name: 'to', indexed: true },
    { type: 'uint256', name: 'value', indexed: false },
  ];

  // Decode the log data
  const decodedLog = web3.eth.abi.decodeLog(transferEventInputs, log.data, log.topics.slice(1));

  // Log the decoded transfer event data
  console.log('USDC Transfer:');
  console.log('  From:', decodedLog.from);
  console.log('  To:', decodedLog.to);
  console.log('  Value (in USDC):', parseInt(decodedLog.value) / 1e6);
});

​

Making the best out of Ethereum logs and filters

1. Use the latest version of web3.js. Make sure to always use the most recent version of the web3.js library, as it includes the latest features, optimizations, and security fixes.
2. Choose a safe block range. When retrieving event logs, it is essential to choose a reasonable block range. Requesting too large a range may lead to timeouts and slow response times. If you need to retrieve logs from a wide range, consider breaking the request into smaller chunks. Chainstack does not impose strict limitations on the block range you can query. However, for optimal performance, on the Ethereum network, we suggest keeping the block range within 5,000 blocks.
3. Filter events by indexed parameters. Using indexed parameters in your event filters can significantly improve efficiency by allowing you to target specific logs. Make use of indexed event parameters whenever possible.
4. Monitor for new events. Use the web3.js library’s built-in event subscription feature to monitor new events in real-time. This can help you avoid the need to constantly poll for updates.
5. Throttle your requests. To avoid overwhelming your Ethereum provider, throttle your requests to a reasonable rate. You can use libraries like lodash to implement request throttling easily.
6. Use the fromBlock parameter wisely. When retrieving historical event logs, be mindful of the fromBlock parameter. It is often more efficient to start from a block that you know contains relevant events rather than querying from the genesis block.
7. Cache logs locally. Cache event logs locally to minimize the need for frequent API calls. This can improve your application’s performance and reduce the load on your Ethereum provider.
8. Monitor gas usage. Keep track of gas usage for your contract interactions. Optimizing your contract’s gas consumption can save your users money and improve the overall user experience.
9. Secure your Ethereum provider. For higher security, ensure that you use properly secure connections with API keys and other security measures in your Chainstack nodes.

​

Conclusion

​

About the author

Sethu Raman Omanakuttan

Developer Advocate @ Chainstack BUIDLs on Ethereum, NEAR , Graph Protocol and Oasis. Majored in computer science and technology.