subscribe("logs") | Gnosis

web3.js subscription equivalent to eth_newFilter. subscribe("logs") allows developers to subscribe to real-time updates about new event logs on the Gnosis Chain; the application will receive notifications whenever new logs matching the filter are emitted.


  • string β€” a keyword identifying the type of event to subscribe to, logs in this case.
  • object β€” (optional) The subscription options:
    • fromBlock β€” an integer that specifies the starting block number from which the logs should be fetched. null by default.
    • address β€” the contract address from which the logs should be fetched. It can be a single address or an array of addresses.
    • topics β€” an array of DATA topics. The event topics for which the logs should be fetched. It can be a single topic or an array of topics.
  • function β€” (optional) a callback function that will be called every time a new event of the specified type is received. This function takes two parameters: error and result. The error parameter contains any error that occurred while subscribing to the event, and the result parameter contains the data for the event that was received.


  • array β€” an array of log objects that match the specified filter:
    • address β€” the contract address from which the event originated.
    • topics β€” an array of 32-byte data fields containing indexed event parameters.
    • data β€” the non-indexed data that was emitted along with the event.
    • blocknumber β€” the block number in which the event was included. null if it is pending.
    • transactionhash β€” the hash of the transaction that triggered the event. null if pending.
    • transactionindex β€” the integer index of the transaction within the block's list of transactions. null if it is pending.
    • blockhash β€” the hash of the block in which the event was included. null if it is pending.
    • logindex β€” the integer identifying the index of the event within the block's list of events. null if pending.
    • removed β€” the boolean value indicating if the event was removed from the blockchain due to a chain reorganization. True if the log was removed. False if it is a valid log.

subscribe("logs") code example


Note that web3.js subscriptions require a WebSocket connection.

Use the event emitter instances to attach event listeners to the subscription object:

  • data β€” activates for each new syncing event.
  • error β€” activates if an error is detected during the subscription.
  • connected β€” activates after the subscription is successfully connected and returns the subscription ID.
  • unsubscribe β€” unsubscribes the subscription and returns true if successful.
const Web3 = require("web3");
const web3 = new Web3(NODE_URL);

// Only log transfer events from the WMATIC smart contract.
const logsFilter = {
    address: '0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270',
    topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']

async function subscribeToLogs() {
    try {
        // Create a new subscription to the 'pendingTransactions' event
        const subscription = await web3.eth.subscribe('logs', logsFilter);

        // Attach event listeners to the subscription object
        subscription.on('connected', handleConnected);
        subscription.on('data', handleLogs);
        subscription.on('error', handleError);
    } catch (error) {
        console.error(`Error subscribing to new sync: ${error}`);

/* Fallback functions to react to the different events */

// Event listener that logs a message when the subscription is connected
function handleConnected(subscriptionId) {
    console.log(`New subscription: ${subscriptionId}`);

// Event listener that logs the filtered events
async function handleLogs(logs) {

// Event listener that logs any errors that occur
function handleError(error) {
    console.error(`Error receiving new blocks: ${error}`);


Use case

A practical use case for subscribe("logs") is a DApp that continuously listens for new specific event logs and isolates certain fields for analytics purposes. This is useful, for example, to track events about a specific ERC-721 token.