> ## Documentation Index
> Fetch the complete documentation index at: https://chainstack-docs-polygon-erigon-trace-deprecation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# subscribe ("syncing") | Ethereum

> Monitor Ethereum node sync status in real time with web3.js. Subscribe to syncing updates to track block download progress and chain synchronization.

## 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

<Info>
  Note that ethers.js subscriptions require a WebSocket connection.
</Info>

Use the [provider events](https://docs.ethers.org/v6/api/providers/#ProviderEvent) 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.

<CodeGroup>
  ```javascript index.js theme={null}
  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();
  ```
</CodeGroup>

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

<CodeGroup>
  ```javascript index.js theme={null}
  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();
  ```
</CodeGroup>

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.