subscribe("logs") | Polygon

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

Parameters

  • 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.

Response

  • 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 NODE_URL = "CHAINSTACK_WSS_URL";
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 logs: ${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) {
    console.log(logs)
}

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

subscribeToLogs();

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 only track events about a specific ERC-721 token.

The following is an implementation of this concept using web3.js subscriptions, this program will only track the PunkTransfer event from the PolygonPunks collection smart contract.

The PunkTransfer event looks like this in the smart contract:

event PunkTransfer(address indexed from, address indexed to, uint256 punkIndex);

The following code will log all of the new PunkTransfer events and extract the block number. This can be useful to analyze when tokens are moved.

const Web3 = require("web3");
const NODE_URL = "CHAINSTACK_WSS_URL";
const web3 = new Web3(NODE_URL);

// Only log PunkTransfer events from the Polygon Punks smart contract.
const logsFilter = {
    address: '0x9498274B8C82B4a3127D67839F2127F2Ae9753f4',
    topics: ['0x05af636b70da6819000c49f85b21fa82081c632069bb626f30932034099107d8']
}

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 blocks: ${error}`);
    }
}

// Use this function to unsuscribe and exit the program
function unsubscribe() {
    subscription.unsubscribe(function(error, success) {
        if (success) console.log("Successfully unsubscribed!");
        return process.exit(1)
    });
}

/* 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) {
    const block = logs.blockNumber
    console.log(`A Polygon Punk was transferred in this block: ${block}`)
}

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

subscribeToLogs();

This code creates a new subscription to the logs event using the web3.eth.subscribe method. This method returns a subscription object that can be used to attach event listeners to the subscription.

The code defines three event listener functions that are attached to the subscription object: handleConnected, handleLogs, and handleError. The handleConnected function is called when the subscription is connected, and it logs a message with the subscription ID. The handleLogs function is called when a new log matching the filter is emitted, then extracts the block number field and logs it to the console.

The handleError function is called when an error occurs, and it logs an error message.

The code includes the unsubscribe function that can be implemented in the logic to unsubscribe and exit the program when a condition is met.

Finally, the code calls the subscribeToLogs function, which creates the subscription and attaches the event listeners. When a new event log is received, the handleLogs function is called to extract the data and log it to the console.

Try the subscribe("logs") RPC method yourself