Skip to main content

​
Get your own node endpoint today

Start for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.

​
Parameters

  • string — a keyword identifying the type of event to subscribe to, logs 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

  • object — the following sync object when the node is currently syncing:
    • startingBlock — the block number from which the node began syncing.
    • currentBlock — the latest block number the node has synced to.
    • highestBlock — the estimated highest block number that needs to be synced.
    • pulledStates — the number of state entries that have already been downloaded.
    • knownStates — the estimated number of state entries to be downloaded during the sync.
  • boolean — returns False when the node is already in sync.

​
subscribe("syncing") code example

Note that ethers.js subscriptions require a WebSocket connection.
Use the provider events to attach event listeners to the provider:
  • sync — activates for each new syncing event.
  • error — activates if an error is detected during the subscription.
  • provider.removeAllListeners — removes the listeners and stops the subscription.
const ethers = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_URL";
const provider = new ethers.WebSocketProvider(NODE_URL);

async function subscribeToSync() {
    try {
        // Subscribe to the 'sync' event
        provider.on('sync', handleSync);

        // Attach an error listener to the provider
        provider.on('error', handleError);

        console.log('Subscribed to sync events');

    } catch (error) {
        console.error(`Error subscribing to sync: ${error}`);
    }
}

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

// Event listener that logs the sync status
async function handleSync(sync) {
    console.log(sync);
}

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

subscribeToSync();

​
Use case

A practical use case for subscribe("syncing") is a DApp that continuously listens for the status of a node and notifies the developer if the node falls behind a certain number of blocks. The following is an implementation of this concept using ethers.js subscriptions, this program will leave a notification in the console if the node falls more than 100 blocks behind. 
const ethers = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_URL";
const provider = new ethers.WebSocketProvider(NODE_URL);

async function subscribeToSync() {
    try {
        // Subscribe to the 'sync' event
        provider.on('sync', handleSync);

        // Attach an error listener to the provider
        provider.on('error', handleError);

        console.log('Subscribed to sync events');

    } catch (error) {
        console.error(`Error: ${error}`);
    }
}

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

// Event listener that compares the current and highest blocks
async function handleSync(sync) {
    const currentBlock = sync.currentBlock;
    const highestBlock = sync.highestBlock;

    if (currentBlock !== undefined && highestBlock !== undefined) {
      const blocksBehind = highestBlock - currentBlock;
      console.log(`The node is ${blocksBehind} blocks behind the network.`);

      if (blocksBehind > 1000) {
        alert(`The node is ${blocksBehind} blocks behind the network. Please check your connection.`);
      }
    }
  }

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

subscribeToSync();
This code creates a new subscription to the sync event using the provider.on method on a WebSocketProvider. This method attaches event listeners to the provider for the events you want to track. The code defines two event listener functions that are attached to the provider: handleSync and handleError. The handleSync function is called when a new syncing event is emitted, extracts the currentBlock and the highestBlock fields, and then compares them. If the node is more than 1,000 blocks behind, the user will receive an alert. The handleError function is called when an error occurs, and it logs an error message. Finally, the code calls the subscribeToSync function, which creates the subscription and attaches the event listeners. When a new event is received, the handleSync function is called to extract the data and log it to the console.
Last modified on July 7, 2026