Ethereum Source Code Analysis: Block Synchronization - Downloader Module

Introduction

In this article, we'll analyze the downloader module in Ethereum, which handles block synchronization from peer nodes. The module operates in two modes: full sync and fast sync, differing in the data downloaded and processing methods.

Source Code Directory

The downloader module's code is located in eth/downloader/, with core functionality implemented in:

• downloader.go: Main sync logic
• peer.go: Peer management
• queue.go: Block assembly queue
• statesync.go: State synchronization

Synchronization Modes

Full Mode

• Syncs only block headers and bodies
• Computes state and receipt data locally

Fast Mode

• Downloads headers, bodies, receipts, and state data for pivot blocks
• Uses downloaded pivot state as base for local computation of subsequent blocks

Light Mode

• Only syncs block headers (handled by LES protocol)

Block Download Process

The synchronization workflow involves:

1. Finding common ancestor with findAncestor
2. Downloading headers in "skeleton" groups
3. Filling skeleton segments with headers from peers
4. Downloading bodies and receipts after headers arrive
5. Special handling of pivot blocks in fast mode

The Pivot Concept

• In fast mode, selects a recent block whose state is downloaded
• Blocks before pivot have no state data
• Pivot's state is downloaded from network
• Blocks after pivot compute state locally

👉 [Explore advanced Ethereum concepts](https://www.okx.com/join/BLOCKSTAR)

Key Components

findAncestor

Locates the highest common block with remote peers using:

• Fixed interval method
• Binary search method

Header Synchronization

Uses skeleton framework:

1. Downloads header skeleton (every Nth header)
2. Fills skeleton segments in parallel
3. Handles remaining headers at the end

fetchParts

Generic method for downloading:

• Headers
• Bodies
• Receipts

Manages:

• Peer selection
• Request throttling
• Timeout handling
• Delivery processing

Peer Management

The peerConnection wrapper:

• Tracks idle status per data type
• Calculates peer capacity (items/RTT)
• Marks failed downloads
• Managed by peerSet for idle peer selection

State Synchronization

Special handling for pivot blocks:

1. syncState initiates sync for root hash
2. stateFetcher goroutine manages sync lifecycle
3. Uses trie.Sync to recursively download trie nodes
4. Writes completed state to stateDB

FAQ

What's the difference between full and fast sync?

Full sync computes state locally while fast sync downloads pivot state and receipts.

How are peers selected for downloads?

Idle peers with highest throughput are selected first, tracked via peerSet.

What happens if downloads timeout?

Slow peers are demoted or dropped, requests are reassigned.

Why use skeleton sync?

Skeleton framework prevents downloading too many headers from potentially malicious peers.

Conclusion

The downloader module implements sophisticated synchronization logic with:

• Multiple sync modes
• Skeleton downloading
• Pivot block handling
• Peer capacity management
• State synchronization

Through cooperation between Downloader and queue objects, it efficiently synchronizes blockchain data while maintaining security and performance.