Owner: @Youngjoon Lee

Reviewers: 🟢@David Rusu 🟢@Giacomo Pasini 🟢@Álvaro Castro-Castilla 🟢@Daniel Sanchez Quiros

Introduction

When a new node joins the network or a previously-bootstrapped node has been offline for a while, it cannot follow the most recent honest chain solely by receiving only new blocks because those new blocks cannot be added to the block tree that does not have their parent block. These nodes must first catch up with the most recent honest chain by fetching missing blocks from their peers before they start listening for new blocks.

This document specifies a protocol for nodes to bootstrap with the honest chain efficiently while mitigating long range attacks. It also defines how to handle the case which the node falls behind after the bootstrapping is complete.

This protocol adheres to the key invariant: We never roll back blocks that are deeper than the latest immutable block $B_\text{imm}$ in the local chain $c_{loc}$, as defined in Cryptarchia v1 Protocol Specification .

Overview

This protocol defines the bootstrapping mechanism that covers all of the following cases:

• From the genesis block
• From the checkpoint block obtained from a trusted checkpoint provider
• From the local block tree (with $B_\text{imm}$ newer than the genesis and the checkpoint)

Additionally, the protocol defines the synchronization mechanism that handles orphan blocks while listening for new blocks after the bootstrapping is completed.

The protocol consists of the following key components:

• Determining the fork choice rule (Bootstrap or Online) at startup
• Switching the fork choice rule from Bootstrap to Online
• Downloading blocks from peers

The details are described in the Protocol. This section provides only a high-level overview.

flowchart TD
	Start@{shape: circle, label: "Start"} --> SettingForkChoice
	subgraph SettingForkChoice[Setting Fork Choice]
		subgraph CheckBoostrap[Any condition true?]
			direction TB
			Cond1{{LIB is set to Genesis or Checkpoint?}}
			Cond2{{Restarting after long offline?}}
			Cond3{{Bootstrap flag enabled?}}
		end
	CheckBoostrap -->|Yes| SetBootstrap[ForkChoice=BOOTSTRAP]
	CheckBoostrap -->|No| SetOnline[ForkChoice=ONLINE]
	end
	
	SetBootstrap --> IBD
	SetOnline --> IBD
	subgraph IBD[Initial Block Download]
	  IBDPeersConfigured{{IBD peers configured?}} --> |Yes|DownloadUpToTips
		DownloadUpToTips[Download all blocks up to peers' tip] --> |No peer available| Terminate@{shape: circle, label: "Terminate"}
	  DownloadUpToTips -->|Completed|IsBootstrapRule
	  IsBootstrapRule{{ForkChoice==BOOTSTRAP?}}
	end
	IBDPeersConfigured --> |No|StartBootstrapPeriod
	IsBootstrapRule -->|Yes|StartBootstrapPeriod
	DownloadUpToTips -->|Completed|NewBlocks
	subgraph Prolonged Bootstrap Period
		StartBootstrapPeriod[Start ProlongedBootstrapPeriod timer: 24h] --> |Expired|SetOnlineAfterBootstrap[ForkChoice=ONLINE]
	end
	subgraph ListenNewBlocks[Listen for New Blocks]
		NewBlocks[Listen/Process a new block] --> CheckOrphan{{Is orphan?}}
		CheckOrphan -->|Yes| HandleOrphan[Download ancestors]
		CheckOrphan -->|No| NewBlocks
		HandleOrphan --> |Completed|NewBlocks
	end
	

Upon startup, a node determines the fork choice rule, as defined in ****Setting the Fork Choice Rule. If the Bootstrap rule is selected, it is maintained for the Prolonged Bootstrap Period, after which the node switches to the Online rule.

Using the fork choice rule chosen, the node downloads blocks to catch up with the tip of the local chain $c_{loc}$ of each peer.