The eth_syncing method allows you to check whether your Ethereum node is currently synchronizing with the network and, if it is, track the progress of the synchronization process. This simple yet powerful method helps you monitor your node's catch-up status.

Use Cases

Monitoring node synchronization status in infrastructure setups
Tracking sync progress in block explorers and dashboards
Determining when a node is ready to process transactions
Building health monitoring systems for Ethereum infrastructure
Calculating estimated time until full sync is complete
Displaying sync status in wallet applications
Verifying that a node is fully synchronized before critical operations
Diagnosing networking or blockchain synchronization issues
Checking if a node can reliably process requests
Monitoring initial sync for resource-intensive archive nodes

Method Details

Paramètres:

Les paramètres sont vides

Retours:

syncingboolean | object

When the node is not syncing, returns `false`. When syncing, returns an object with sync status data.

Response Examples

When Not Syncing

If the node is fully synchronized with the network, the method returns false:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": false
}

When Syncing

If the node is currently synchronizing, the method returns an object with sync status information:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "currentBlock": "0x3b0bc5",
    "highestBlock": "0x3b7698",
    "knownStates": "0x21a679",
    "pulledStates": "0x21a679",
    "startingBlock": "0x3ad7a2"
  }
}

Understanding the Sync Status Fields

Standard Fields

startingBlock: Hexadecimal block number where the sync started
currentBlock: Hexadecimal block number the node is currently processing
highestBlock: Hexadecimal block number of the highest known block in the network
knownStates: Number of state entries known to exist (from peer information)
pulledStates: Number of state entries already downloaded

Additional Client-Specific Fields

Different Ethereum clients may include additional sync information:

Geth

healedBytecodeBytes: Bytes of code restored during snap sync
healedBytecodes: Number of bytecodes recovered during snap sync
healedTrienodeBytes: Bytes of trie nodes recovered during healing
healedTrienodes: Number of trie nodes recovered during healing
syncedAccountBytes: Size of account data downloaded
syncedAccounts: Number of accounts downloaded
syncedBytecodeBytes: Size of bytecode downloaded
syncedBytecodes: Number of bytecodes downloaded
syncedStorage: Number of storage slots synced
syncedStorageBytes: Size of storage data downloaded

Erigon

syncStage: Current sync stage name (Headers, Bodies, Execution, etc.)
syncProgress: Percentage of current stage completion (0-100)

Example Data Interpretation

Given this sync status:

{
  "currentBlock": "0x3b0bc5",
  "highestBlock": "0x3b7698",
  "startingBlock": "0x3ad7a2"
}

We can interpret it as follows:

Starting block: 3,840,930 (decimal of 0x3ad7a2)
Current block: 3,872,709 (decimal of 0x3b0bc5)
Highest block: 3,897,000 (decimal of 0x3b7698)
Progress: ~31,779 blocks synced out of ~56,070 total (56.7% complete)

Sync Types and Phases

Ethereum nodes can sync using different strategies, each affecting what the eth_syncing response will show:

Full Sync

Downloads all blocks and executes all transactions from the genesis block.

Slow but most secure
Can take days or weeks depending on hardware
Provides full historical data

Fast Sync

Downloads blocks but pulls only recent state without re-executing historical transactions.

Much faster than full sync
May take hours to days
Reduces storage requirements
eth_syncing will show state sync progress

Snap Sync (Geth)

Directly downloads state snapshots rather than reconstructing state from transactions.

Fastest sync method for Geth
Can complete in hours on good hardware
Additional fields in sync status show snapshot progress

Beam Sync (Nethermind)

Allows querying chain data before full sync completes.

Begins processing requests before fully synchronized
May show as not syncing even while backfilling data

Common Sync Phases

Header Sync: Download block headers (fastest phase)
Block Sync: Download block bodies
Receipt Sync: Download transaction receipts
State Sync: Download or build account and contract state (slowest phase)
Healing: Verify data integrity and fix any issues

Synchronization Issues

When monitoring with eth_syncing, these patterns may indicate problems:

Stuck Sync: No change in currentBlock for extended periods
Slow Progress: Very low blocks-per-minute rate
Repeated Blocks: Current block number decreases or fluctuates
Disconnect/Reconnect: Sync restarts with a new startingBlock

Sync Status Dashboard

For applications that need to display sync status, consider showing:

Visual progress bar based on currentBlock vs highestBlock
Numeric percentage of completion
Current block vs highest block
Estimated time remaining
Current sync stage (if available)
Historical sync speed chart
Network health indicators

Important Notes

False Negatives: Some clients return false during certain sync types or stages even when not fully synced
Consensus Layer: This method only reports execution layer sync status, not consensus layer (post-merge)
Peers Required: Nodes need peers to accurately determine the highest block
Client Variations: Different clients (Geth, Erigon, Nethermind, etc.) provide different sync information
Archive Nodes: Full archive nodes take significantly longer to sync than full nodes with pruning
Disk IO: Sync speed is often limited by disk I/O performance rather than network
Memory Requirements: Syncing requires significant RAM, especially during state sync phases
Multiple Sync Methods: Clients often switch between sync methods during the process

eth_syncing