subscribe("pendingTransactions") | Ethereum

web3.js subscription equivalent to eth_newPendingTransactionFilter. subscribe("pendingTransactions") allows developers to subscribe to real-time updates about pending transactions on the Ethereum blockchain; the application will receive notifications whenever a pending transaction appears on the blockchain.

Parameters

  • string β€” a keyword identifying the type of event to subscribe to, pendingTransactions in this case.
  • 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

  • string β€” the hash identifying the pending transaction.

subscribe("pendingTransactions") 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);

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

        // Attach event listeners to the subscription object
        subscription.on('connected', handleConnected);
        subscription.on('data', handleNewPending);
        subscription.on('error', handleError);
    } catch (error) {
        console.error(`Error subscribing to new pending transactions: ${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 received pendingTransactions
function handleNewPending(transactions) {
    console.log(transactions);
}

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

subscribeToPendingTransactions();

Use case

A practical use case for subscribe("pendingTransactions") is a DApp that continuously listens for new pending transactions, then isolates the from, to, and value fields for analytics purposes. This is useful, for example, to only track transactions that move at least a certain amount of ETH.

The following is an implementation of this concept using web3.js subscriptions:

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

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

        // Attach event listeners to the subscription object
        subscription.on('connected', handleConnected);
        subscription.on('data', handleNewPending);
        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 received pendingTransactions and extracts from, to, and value fields
async function handleNewPending(transactionHash) {
    try {
        const transaction = await web3.eth.getTransaction(transactionHash);
        const from = transaction.from;
        const to = transaction.to;
        const value = transaction.value;
        if (value >= 100000000000000000000) { // 100 ETH in Wei
            console.log(`----- New pending transaction ------`);
            console.log(`From: ${from}`)
            console.log(`To: ${to}`)
            console.log(`Value: ${Number(web3.utils.fromWei(value, 'ether')).toFixed(2)} ETH \n`)
        }
    } catch (error) {
        console.error(`Error getting transaction: ${error}`);
    }
}

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

subscribeTopendingTransactions();

This code creates a new subscription to the pendingTransactions 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, handleNewPending, and handleError. The handleConnected function is called when the subscription is connected, and it logs a message with the subscription ID. The handleNewPending function is called when a new pending transaction is received; it runs the eth_getTransactionByHash method and extracts the from, to, and value fields. If the value transferred is above 100 ETH, the data is logged.

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

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

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