> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Chain Synchronization

## Purpose and Scope

Chain synchronization is the process of downloading and validating blockchain data (blocks, headers, receipts, and state) from network peers in order to bring a node up to the latest chain head.\
This document explains the synchronization architecture and internal workflow used in StableNet.

Core components:

* **`downloader.Downloader`** – Main synchronization engine
* **`chainSyncer`** – Orchestrates synchronization tasks
* **`queue`** – Schedules parallel downloads and caches results
* **`peerSet`** – Manages peers participating in synchronization

This document covers synchronization modes, common ancestor discovery, parallel download of headers/bodies/receipts, Snap-based state synchronization, queue limits, and peer management flows.

For peer discovery, see [Discovery Mechanisms](/en/networking/7.2-discovery-mechanisms).\
For block insertion and chain management logic, see [Blockchain Management](/en/core-architecture/3.2-blockchain-management).

## Synchronization Modes

StableNet supports three `SyncMode` values.

| Mode        | Value | Behavior                                                            |
| ----------- | ----- | ------------------------------------------------------------------- |
| `FullSync`  | 0     | Download all blocks and execute all transactions                    |
| `SnapSync`  | 1     | Download headers and a recent state snapshot, then backfill history |
| `LightSync` | 2     | Download headers only, minimal validation                           |

The current mode is stored atomically in `Downloader.mode`.

### Mode Selection Logic

`chainSyncer.modeAndLocalHead()` determines the synchronization mode using the following rules:

* If the SnapSync flag is enabled, select SnapSync
* If there is no local head state, force SnapSync
* If the chain has rewound below the SnapSync pivot, re-enable SnapSync
* Otherwise, use FullSync

## Downloader Architecture

`Downloader` is the central component of the synchronization pipeline.

| Field        | Type            | Purpose                        |
| ------------ | --------------- | ------------------------------ |
| `mode`       | `atomic.Uint32` | Current synchronization mode   |
| `queue`      | `*queue`        | Download task scheduler        |
| `peers`      | `*peerSet`      | Peer tracking and selection    |
| `blockchain` | `BlockChain`    | Target for FullSync            |
| `lightchain` | `LightChain`    | Target for LightSync           |
| `SnapSyncer` | `*snap.Syncer`  | State snapshot synchronization |
| `skeleton`   | `*skeleton`     | Beacon header backfill         |
| `cancelCh`   | `chan struct{}` | Cancellation signal            |

`Downloader` is created by the `eth` protocol handler and controlled by `chainSyncer`.

## Synchronization Orchestration

### chainSyncer Control Loop

`chainSyncer.loop()` operates as a state machine and repeatedly performs the following:

* Evaluate the current local head and remote peer states
* Decide the next synchronization action
* Execute synchronization and process results
* Retry or switch modes on errors

### Synchronization Execution

`doSync()` executes one of the following based on the selected mode:

* FullSync – Full header, body, and receipt download
* SnapSync – State snapshot download followed by history backfill

## Finding the Common Ancestor

Synchronization begins by finding the common ancestor between the local chain and the remote chain.

### Two-Phase Ancestor Search

1. **Span Search**\
   Request headers at intervals to quickly narrow down the fork range.

2. **Binary Search**\
   Perform a binary search within the candidate range to find the exact common ancestor.

### Fork Protection

To prevent deep chain reorganizations, a protective floor is applied, limiting ancestor searches below a certain depth.

## Header Synchronization

Headers are synchronized before bodies and receipts.

### Header Fetch Modes

* **Legacy mode** – Request headers directly from network peers

### Header Processing

Downloaded headers are verified and ordered in parallel across multiple goroutines, while reorganization protection constants ensure chain stability.

## Downloading Bodies and Receipts

Once headers are ready, bodies and receipts are downloaded in parallel via the `queue`.

* Bodies and receipts maintain independent task queues and pending pools
* Tasks are dynamically assigned based on peer capacity
* Peers that fail validation are penalized or dropped

## State Synchronization (Snap Sync)

Snap synchronization accelerates initial sync by skipping full transaction execution and downloading a state snapshot.

### Snap Sync Stages

1. Select a pivot block
2. Download the state snapshot
3. Fill missing trie nodes and code
4. Commit the pivot
5. Process subsequent blocks using FullSync

### Pivot Block

The pivot block serves as the state root reference point.

* Legacy mode – Request the latest head from peers

The pivot number is persisted in the database.

### SnapSyncer Responsibilities

SnapSyncer downloads the following data:

* Account trie segments
* Contract storage data
* Contract bytecode
* Missing trie nodes

### Ancient Store Handling

During SnapSync, older blocks may be moved directly into the ancient store.

* Threshold is finalized blocks or `head - 90000`
* Blocks below the threshold are immediately frozen
* Recent blocks remain in the active database

## Queue Task Scheduling

`queue` controls parallel downloads and caches results.

| Field              | Purpose                          |
| ------------------ | -------------------------------- |
| `blockTaskPool`    | Pending body tasks               |
| `blockTaskQueue`   | Priority queue for body tasks    |
| `blockPendPool`    | In-progress body requests        |
| `receiptTaskPool`  | Pending receipt tasks            |
| `receiptTaskQueue` | Priority queue for receipt tasks |
| `resultCache`      | Completed result cache           |

### Cache Limits

The result cache is throttled when any of the following conditions are exceeded:

* Item count limit
* Total memory usage limit

In this case, fetchers wait until processors consume cached results.

## Peer Management

### peerConnection

Each peer tracks throughput and response latency.

* Capacity estimates for headers, bodies, and receipts
* Performance estimation based on exponential moving averages

### peerSet

`peerSet` manages the set of peers eligible for synchronization.

### Peer Registration

New peers are registered via `RegisterPeer()` after completing the synchronization handshake.

### Error Handling and Dropping

* Missing data is marked via `MarkLacking()`
* Repeated errors, timeouts, or invalid responses result in peer drops
* In legacy sync paths, errors may cause immediate drops

## Synchronization Workflow Summary

1. Select peers and determine synchronization mode
2. Find the common ancestor
3. Download and validate headers
4. Download bodies and receipts in parallel
5. Perform SnapSync state synchronization if required
6. Commit the pivot and switch to FullSync
7. Reach the chain head and enter normal operation

This workflow represents the full synchronization lifecycle from the moment a node joins the network until it reaches the latest chain state.