Sync and Network Consensus

Nimiq implements a two-phase synchronization architecture that separates epoch-level state synchronization from real-time block processing. This design enables efficient sync strategies tailored to different node capabilities.

All nodes follow a two-phase synchronization pattern: macro sync followed by live sync. During macro sync, nodes download and verify macro blocks (checkpoints/epochs) to reach the current network state efficiently. Once macro sync completes, nodes transition to live sync to receive and validate the latest micro blocks in real-time. This modular approach allows each node type to optimize for its specific use case.

Sync Comparison Table

History Nodes

• Complete blockchain history from genesis
• Deep chain queries, historical analysis, and serving data to other nodes
• Can act as validators and provide historical data to the network
• Serve data to other nodes, validate transactions and produce blocks (if validator)
• Rely on other history nodes for initial sync

Full Nodes

• Complete current state with pruned history - maintains full validation capability
• Serve data to other nodes, validate transactions and produce blocks (if validator)
• Rely on full or history nodes for initial sync

Light Nodes

• Election block headers (verified via validator BLS signatures) and subsequent micro block headers only
• Transaction verification and sending with cryptographic security guarantees
• Browser/mobile deployment, web client integration (WASM support)
• Rely on full or history nodes for data availability

Pico Nodes

• Sync with the latest election block only (no historical data; trust-based)
• Ultra-fast startup with trust-based consensus and automatic fallback to trustless sync
• Development environments, testing, and trusted network scenarios
• Rely on full or history nodes for data availability and fallback verification

Service Nodes

Validator Nodes: Produce blocks and participate in consensus. Any node with a minimum of 100'000 NIM deposit that runs a full or history client can become a validator.

Architecture Components

Coordination Layer: Consensus and Syncer components manage sync lifecycle and peer relationships, enabling seamless transitions between sync phases.

Pluggable Strategies: MacroSync and LiveSync trait implementations allow optimization for different resource constraints.

Network Layer: Request/response and gossip protocols with async streams for efficient concurrent peer processing.

Queue Architecture: Automatic peer rotation, retry logic, and backpressure control ensure reliable data retrieval.

Further Reading

Understanding the System

• Architecture - Core components, data flow, and design patterns
• Node Sync System - Node lifecycles and sync mode selection

Implementation Details

• Traits and Abstractions - System design and component coordination
• Network Protocol - Message specifications and communication patterns

Sync Strategy Deep Dives

Macro Sync Strategies:

• History Macro Sync - Full chain download for history nodes
• Light Macro Sync - Trustless macro sync for full and light nodes
• Pico Macro Sync - Optimistic sync with automatic fallback

Live Sync Strategies:

• Block Live Sync - Real-time block synchronization
• State Live Sync - Complete state maintenance for full nodes

Sync Lifecycle

When a node starts, it follows this coordination pattern:

1. Peer Discovery through the network layer
2. Macro Sync Strategy Sync based on node configuration
3. Live Sync Transition to maintain real-time synchronization
4. Consensus Detection through peer agreement analysis

The Consensus component orchestrates this process, while the Syncer manages strategy-specific implementations through pluggable trait interfaces.