> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# subscribe ("syncing") | Arbitrum
> Monitor Arbitrum node sync status in real time with ethers.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
Note that ethers.js subscriptions require a WebSocket connection.
Use a `WebSocketProvider` and the provider event listeners to react to sync status updates:
* `provider.send("eth_syncing", [])` — queries the current sync status on demand.
* `provider.on("block", ...)` — activates for each new block, so you can re-check the sync status in real time.
* `provider.on("error", ...)` — activates if an error is detected on the connection.
* `provider.destroy()` — closes the connection and removes all listeners.
```javascript index.js theme={"system"}
const { ethers } = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_URL";
const provider = new ethers.WebSocketProvider(NODE_URL);
async function subscribeToSync() {
try {
// Log the initial sync status on connection
const status = await provider.send("eth_syncing", []);
handleConnected(status);
// Re-check the sync status on every new block
provider.on("block", handleSync);
// React to connection errors
provider.on("error", handleError);
} catch (error) {
console.error(`Error subscribing to sync: ${error}`);
}
}
/* Fallback functions to react to the different events */
// Event listener that logs the initial sync status
function handleConnected(status) {
console.log(`Initial sync status: ${JSON.stringify(status)}`);
}
// Event listener that logs the current sync status
async function handleSync() {
const status = await provider.send("eth_syncing", []);
console.log(status);
}
// 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.
```javascript index.js theme={"system"}
const { ethers } = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_URL";
const provider = new ethers.WebSocketProvider(NODE_URL);
async function subscribeToSync() {
try {
// Log the initial sync status on connection
handleConnected();
// Re-check the sync status on every new block
provider.on("block", handleSync);
// React to connection errors
provider.on("error", handleError);
} catch (error) {
console.error(`Error: ${error}`);
}
}
/* Fallback functions to react to the different events */
// Event listener that logs a message when the connection is ready
function handleConnected() {
console.log("Subscribed to sync status updates.");
}
// Event listener that compares the current and highest blocks
async function handleSync() {
const status = await provider.send("eth_syncing", []);
// eth_syncing returns false when the node is already in sync
if (status === false) {
console.log("The node is in sync with the network.");
return;
}
const currentBlock = Number(status.currentBlock);
const highestBlock = Number(status.highestBlock);
if (!Number.isNaN(currentBlock) && !Number.isNaN(highestBlock)) {
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 monitors the sync status over a WebSocket connection using a `WebSocketProvider`. It listens for new blocks with `provider.on("block", ...)` and queries the current sync status on each block with `provider.send("eth_syncing", [])`.
The code defines three event listener functions that are attached to the provider: `handleConnected`, `handleSync`, and `handleError`. The `handleConnected` function is called when the connection is ready, and it logs a message. The `handleSync` function is called on every new block, reads the `currentBlock` and the `highestBlock` fields from the `eth_syncing` result, 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 attaches the event listeners. When a new block is received, the `handleSync` function is called to query the sync status and log it to the console.