From 5cf5d162ce2a3adc8ea0e690a7cff396c1b3478e Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Thu, 29 Oct 2026 01:02:57 -0700 Subject: [PATCH 01/20] test(dash-spv): a wallet added below the checkpoint the client anchors on Fails on purpose: the client holds no headers below the checkpoint, so the wallet never sees its history there, at runtime or across a restart, with or without a block mined meanwhile. Co-Authored-By: Claude Opus 5.5 --- dash-spv/tests/dashd_sync/setup.rs | 18 +++-- .../tests/dashd_sync/tests_multi_wallet.rs | 78 ++++++++++++++++++- 2 files changed, 90 insertions(+), 6 deletions(-) diff --git a/dash-spv/tests/dashd_sync/setup.rs b/dash-spv/tests/dashd_sync/setup.rs index 3cccb7c3e..49c8a0a47 100644 --- a/dash-spv/tests/dashd_sync/setup.rs +++ b/dash-spv/tests/dashd_sync/setup.rs @@ -145,14 +145,22 @@ impl TestContext { progress: &SyncProgress, wallet: &Arc>>, wallet_id: &WalletId, + ) { + self.assert_wallet_synced_at(progress, wallet, wallet_id, self.dashd.initial_height).await; + } + + /// [`Self::assert_wallet_synced`] with the chain at `tip`. + pub(super) async fn assert_wallet_synced_at( + &self, + progress: &SyncProgress, + wallet: &Arc>>, + wallet_id: &WalletId, + tip: u32, ) { let header_height = progress.headers().unwrap().current_height(); let filter_header_height = progress.filter_headers().unwrap().current_height(); - assert_eq!(header_height, self.dashd.initial_height, "Header height mismatch"); - assert_eq!( - filter_header_height, self.dashd.initial_height, - "Filter header height mismatch" - ); + assert_eq!(header_height, tip, "Header height mismatch"); + assert_eq!(filter_header_height, tip, "Filter header height mismatch"); let wallet_read = wallet.read().await; let wallet_info = wallet_read.get_wallet_info(wallet_id).expect("Wallet info not found"); diff --git a/dash-spv/tests/dashd_sync/tests_multi_wallet.rs b/dash-spv/tests/dashd_sync/tests_multi_wallet.rs index 3cc6def6f..689272053 100644 --- a/dash-spv/tests/dashd_sync/tests_multi_wallet.rs +++ b/dash-spv/tests/dashd_sync/tests_multi_wallet.rs @@ -5,9 +5,15 @@ use key_wallet_manager::WalletManager; use std::collections::HashSet; use std::sync::Arc; use std::time::Duration; +use test_case::test_case; use tokio::sync::RwLock; -use dash_spv::Network; +use dash_spv::chain::checkpoints::CHECKPOINT_HEADERS; +use dash_spv::test_utils::{BlockHeaderStorage, DashCoreNode, DiskStorageManager, StorageManager}; +use dash_spv::types::HashedBlockHeader; +use dash_spv::{ClientConfig, Network}; +use dashcore::block::Header; +use dashcore::consensus::deserialize; use dashcore::{Address, Amount}; use super::helpers::{ @@ -616,3 +622,73 @@ async fn test_runtime_add_with_tip_advance_during_rescan() { client_handle.stop().await; } + +/// Stores the headers a checkpoint at `height` of `node`'s chain holds, so the +/// client anchors there as on a bundled one. +async fn anchor_at_checkpoint(config: &ClientConfig, node: &DashCoreNode, height: u32) { + let start = height + 1 - CHECKPOINT_HEADERS as u32; + let headers: Vec = (start..=height) + .map(|h| { + let hash = node.get_block_hash(h).to_string(); + let hex = node.try_rpc_call("getblockheader", &[hash.into(), false.into()]).unwrap(); + let bytes = hex_conservative::decode_to_vec(hex.as_str().unwrap()).unwrap(); + deserialize::
(&bytes).unwrap().into() + }) + .collect(); + let mut storage = DiskStorageManager::new(config).await.unwrap(); + storage.store_headers_at_height(&headers, start).await.unwrap(); + storage.stop().await; +} + +/// A wallet born at genesis, added after the client anchored on a checkpoint +/// above it synced one born at the tip, gets its full history, optionally +/// across a restart and a block mined meanwhile. +#[test_case(false, false ; "at runtime")] +#[test_case(false, true ; "at runtime mining")] +#[test_case(true, false ; "across restart")] +#[test_case(true, true ; "across restart mining")] +#[tokio::test] +async fn test_wallet_added_below_synced_wallet(restart: bool, mine: bool) { + let Some(ctx) = TestContext::new(TestChain::Full).await else { + return; + }; + if mine && !ctx.dashd.supports_mining { + return; + } + let height = ctx.dashd.initial_height; + anchor_at_checkpoint(&ctx.client_config, &ctx.dashd.node, height / 2).await; + let wallet = Arc::new(RwLock::new(WalletManager::::new(Network::Regtest))); + let tip_id = wallet + .write() + .await + .create_wallet_from_mnemonic(EMPTY_MNEMONIC, height, default_test_account_options()) + .unwrap(); + let mut handle = create_and_start_client(&ctx.client_config, Arc::clone(&wallet)).await; + wait_for_sync(&mut handle.progress_receiver, height).await; + + if restart { + handle.stop().await; + } + let history_id = wallet + .write() + .await + .create_wallet_from_mnemonic(&ctx.dashd.wallet.mnemonic, 0, default_test_account_options()) + .unwrap(); + if restart { + drop(handle); + handle = create_and_start_client(&ctx.client_config, Arc::clone(&wallet)).await; + } + + let tip = height + mine as u32; + if mine { + let miner = ctx.dashd.node.get_new_address_from_wallet("default"); + ctx.dashd.node.generate_blocks(1, &miner); + } + wait_for_sync(&mut handle.progress_receiver, tip).await; + wait_for_wallet_synced(&wallet, &history_id, tip).await; + wait_for_wallet_synced(&wallet, &tip_id, tip).await; + + ctx.assert_wallet_synced_at(&handle.client.progress().await, &wallet, &history_id, tip).await; + assert_eq!(count_wallet_transactions(&wallet, &tip_id).await, 0); + handle.stop().await; +} From 122bab2f82eeb217bb999cbbe40d9d46ab99bfb7 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Thu, 29 Oct 2026 04:57:31 -0700 Subject: [PATCH 02/20] feat(dash-spv): backfill headers below the checkpoint for a wallet that needs them `FiltersManager` asks for the headers below the stored ones with `HeadersBackfillNeeded` when a wallet's birth height, floored at the network's HD sync floor, is below them, and waits for the filter headers to follow. `BlockHeadersManager` syncs down one checkpoint at a time from a segment kept apart from the forward pipeline, and `FilterHeadersManager` fills the filter headers downwards, each batch checked against the stored one it ends at. Co-Authored-By: Claude Opus 5.5 --- dash-spv/src/client/lifecycle.rs | 1 + dash-spv/src/sync/block_headers/manager.rs | 79 +++++++++++++++++++ dash-spv/src/sync/block_headers/pipeline.rs | 46 ++++++++++- .../src/sync/block_headers/sync_manager.rs | 11 ++- dash-spv/src/sync/events.rs | 13 +++ dash-spv/src/sync/filter_headers/manager.rs | 79 ++++++++++++++++++- dash-spv/src/sync/filter_headers/pipeline.rs | 2 +- .../src/sync/filter_headers/sync_manager.rs | 11 +++ .../filters/coinjoin_gap_discovery_tests.rs | 1 + dash-spv/src/sync/filters/manager.rs | 43 ++++++++-- 10 files changed, 271 insertions(+), 15 deletions(-) diff --git a/dash-spv/src/client/lifecycle.rs b/dash-spv/src/client/lifecycle.rs index 9861260c8..5fbbd4e7a 100644 --- a/dash-spv/src/client/lifecycle.rs +++ b/dash-spv/src/client/lifecycle.rs @@ -142,6 +142,7 @@ impl DashSpvClient { storage.block_headers(), storage.filter_headers(), storage.filters(), + config.network.hd_wallet_sync_floor(), ) .await, ); diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index d2da9ae9c..d311c469e 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -24,6 +24,7 @@ use crate::types::HashedBlockHeader; use crate::validation::{BlockHeaderValidator, Validator}; #[cfg(test)] use dashcore::block::Header; +use dashcore::blockdata::constants::genesis_block; use dashcore::ephemerealdata::chain_lock::ChainLock; use dashcore::network::message_blockdata::Inventory; use dashcore::pow::DGW_PAST_BLOCKS; @@ -55,6 +56,8 @@ pub struct BlockHeadersManager { pub(super) announced_peers: HashSet, /// Network whose difficulty rules new headers are checked against. network: Network, + /// Lowest height a wallet needs, which [`Self::extend_down`] syncs down to. + pub(super) floor: Option, } impl std::fmt::Debug for BlockHeadersManager { @@ -101,6 +104,7 @@ impl BlockHeadersManager { pending_announcements: HashMap::new(), announced_peers: HashSet::new(), network, + floor: None, }) } @@ -113,6 +117,73 @@ impl BlockHeadersManager { .ok_or_else(|| SyncError::MissingDependency("storage not initialized".to_string())) } + /// Sync from the checkpoint below the lowest stored header, or genesis, up to + /// it, once the pipeline runs, one checkpoint at a time down to [`Self::floor`]. + pub(super) async fn extend_down(&mut self) -> SyncResult<()> { + if self.pipeline.is_syncing_below() || !self.pipeline.is_initialized() { + return Ok(()); + } + let Some(floor) = self.floor else { + return Ok(()); + }; + let storage = self.header_storage.read().await; + let Some(start) = storage.get_start_height().await.filter(|start| floor < *start) else { + self.floor = None; + return Ok(()); + }; + let join = storage + .get_header(start) + .await? + .ok_or_else(|| SyncError::MissingDependency(format!("no header at {start}")))? + .header() + .prev_blockhash; + drop(storage); + + let (anchor_start, anchor) = self.anchor_below(start); + let anchor_height = anchor_start + anchor.len() as u32 - 1; + if anchor_height + 1 == start { + return self.store_below(start, &[]).await; + } + tracing::info!("Syncing headers {}..{} below the stored ones", anchor_height + 1, start); + let anchor_hash = *anchor.last().expect("an anchor holds headers").hash(); + self.pipeline.sync_below(anchor_height, anchor_hash, start - 1, join); + self.progress.set_state(SyncState::Syncing); + Ok(()) + } + + /// The checkpoint below `start`, or genesis, as its first height and headers. + fn anchor_below(&self, start: u32) -> (u32, Vec) { + match self.checkpoint_manager.last_checkpoint_before_height(start - 1) { + Some(checkpoint) => (checkpoint.start_height(), checkpoint.headers().to_vec()), + None => (0, vec![genesis_block(self.network).header.into()]), + } + } + + /// Store the anchor below `start` and the `downloaded` headers joining it to `start`. + async fn store_below( + &mut self, + start: u32, + downloaded: &[HashedBlockHeader], + ) -> SyncResult<()> { + let (anchor_start, mut headers) = self.anchor_below(start); + let anchor_height = anchor_start + headers.len() as u32 - 1; + if !downloaded.is_empty() { + let ancestors = headers.iter().map(|header| *header.header()).collect(); + BlockHeaderValidator::new(self.network, ancestors, anchor_height) + .validate(downloaded)?; + } + headers.extend_from_slice(downloaded); + let mut storage = self.header_storage.write().await; + let joins = storage.get_header(start).await?.map(|header| header.header().prev_blockhash) + == headers.last().map(|last| *last.hash()); + if !joins { + return Err(SyncError::Validation(format!("headers below {start} do not join it"))); + } + storage.store_headers_at_height(&headers, anchor_start).await?; + tracing::info!("Headers synced down to {}", anchor_start); + Ok(()) + } + /// Validate and store headers batch. async fn store_headers(&mut self, headers: &[HashedBlockHeader]) -> SyncResult { debug_assert!(!headers.is_empty()); @@ -299,6 +370,14 @@ impl BlockHeadersManager { ) -> SyncResult> { let mut events = Vec::new(); + if let Some(below) = self.pipeline.take_below() { + let start = self.header_storage.read().await.get_start_height().await; + let start = start.ok_or_else(|| { + SyncError::MissingDependency("no headers stored to sync below".to_string()) + })?; + self.store_below(start, &below).await?; + } + for (_start_height, batch_headers) in ready_batches { if !batch_headers.is_empty() { // Validate chain continuity with current tip diff --git a/dash-spv/src/sync/block_headers/pipeline.rs b/dash-spv/src/sync/block_headers/pipeline.rs index b82360330..460f1f825 100644 --- a/dash-spv/src/sync/block_headers/pipeline.rs +++ b/dash-spv/src/sync/block_headers/pipeline.rs @@ -32,6 +32,8 @@ pub struct HeadersPipeline { checkpoint_manager: &'static CheckpointManager, /// Whether the pipeline has been initialized. initialized: bool, + /// Segment syncing below the stored headers, stored whole once complete. + below: Option, } impl std::fmt::Debug for HeadersPipeline { @@ -52,6 +54,7 @@ impl HeadersPipeline { next_to_store: 0, checkpoint_manager, initialized: false, + below: None, } } @@ -60,6 +63,7 @@ impl HeadersPipeline { self.segments.clear(); self.next_to_store = 0; self.initialized = true; + self.below = None; // Find checkpoints between current_height and target_height let mut boundaries: Vec<(u32, BlockHash)> = Vec::new(); @@ -111,6 +115,34 @@ impl HeadersPipeline { ); } + /// Download `(start_height, end_height]` below the stored headers, the + /// block at `end_height` being `end_hash`. + pub(super) fn sync_below( + &mut self, + start_height: u32, + start_hash: BlockHash, + end_height: u32, + end_hash: BlockHash, + ) { + self.below = Some(SegmentState::new( + self.segments.len(), + start_height, + start_hash, + Some(end_height), + Some(end_hash), + )); + } + + /// Whether a [`Self::sync_below`] segment is still to be stored. + pub(super) fn is_syncing_below(&self) -> bool { + self.below.is_some() + } + + /// Headers of the [`Self::sync_below`] segment, once complete. + pub(super) fn take_below(&mut self) -> Option> { + self.below.take_if(|below| below.complete).map(|mut below| below.take_buffered()) + } + /// Get the number of segments in the pipeline. pub fn segment_count(&self) -> usize { self.segments.len() @@ -129,6 +161,10 @@ impl HeadersPipeline { segment.send_request(network).await; sent += 1; } + if let Some(below) = self.below.as_mut().filter(|below| below.can_send()) { + below.send_request(network).await; + sent += 1; + } Ok(sent) } @@ -156,6 +192,13 @@ impl HeadersPipeline { let prev_hash = headers[0].header().prev_blockhash; + if let Some(below) = + self.below.as_mut().filter(|below| !below.complete && below.matches(&prev_hash)) + { + below.receive_headers(headers)?; + return Ok(Some(below.segment_id)); + } + // Find the segment that matches for (idx, segment) in self.segments.iter_mut().enumerate() { if segment.matches(&prev_hash) { @@ -246,7 +289,8 @@ impl HeadersPipeline { /// Check if all segments are complete. pub fn is_complete(&self) -> bool { - self.segments.iter().all(|s| s.complete && s.buffered_headers.is_empty()) + self.below.is_none() + && self.segments.iter().all(|s| s.complete && s.buffered_headers.is_empty()) } /// Get the total number of buffered headers across all segments. diff --git a/dash-spv/src/sync/block_headers/sync_manager.rs b/dash-spv/src/sync/block_headers/sync_manager.rs index d3dccc8bc..d8775f3de 100644 --- a/dash-spv/src/sync/block_headers/sync_manager.rs +++ b/dash-spv/src/sync/block_headers/sync_manager.rs @@ -131,14 +131,21 @@ impl SyncManager for BlockHeadersMana async fn handle_sync_event( &mut self, - _event: &SyncEvent, + event: &SyncEvent, _network: &Arc, ) -> SyncResult> { - // BlockHeadersManager doesn't react to events from other managers + if let SyncEvent::HeadersBackfillNeeded { + height, + } = event + { + self.floor = Some(*height); + self.extend_down().await?; + } Ok(vec![]) } async fn tick(&mut self, network: &Arc) -> SyncResult> { + self.extend_down().await?; if !self.pipeline.is_initialized() { return Ok(vec![]); } diff --git a/dash-spv/src/sync/events.rs b/dash-spv/src/sync/events.rs index 5a04b67d6..4e78b7dfd 100644 --- a/dash-spv/src/sync/events.rs +++ b/dash-spv/src/sync/events.rs @@ -186,6 +186,16 @@ pub enum SyncEvent { fork_height: u32, }, + /// A wallet needs blocks below the lowest stored header. + /// + /// Emitted by: `FiltersManager` + /// Consumed by: `BlockHeadersManager`, which fills them in from the + /// checkpoint at or below `height` + HeadersBackfillNeeded { + /// Lowest height a wallet needs + height: u32, + }, + /// Sync has reached the chain tip (all managers idle). /// /// Emitted on every not-synced to synced transition. Cycle 0 is the @@ -286,6 +296,9 @@ impl fmt::Display for SyncEvent { SyncEvent::ForkDetected { fork_height, } => write!(f, "ForkDetected(height={})", fork_height), + SyncEvent::HeadersBackfillNeeded { + height, + } => write!(f, "HeadersBackfillNeeded(height={})", height), SyncEvent::SyncComplete { header_tip, cycle, diff --git a/dash-spv/src/sync/filter_headers/manager.rs b/dash-spv/src/sync/filter_headers/manager.rs index a67f73d70..c336035ba 100644 --- a/dash-spv/src/sync/filter_headers/manager.rs +++ b/dash-spv/src/sync/filter_headers/manager.rs @@ -5,12 +5,13 @@ use std::sync::Arc; -use dashcore::network::message_filter::CFHeaders; +use dashcore::network::message_filter::{CFHeaders, GetCFHeaders}; +use dashcore::BlockHash; use tokio::sync::RwLock; -use super::pipeline::FilterHeadersPipeline; +use super::pipeline::{FilterHeadersPipeline, FILTER_HEADERS_BATCH_SIZE}; use crate::error::{SyncError, SyncResult}; -use crate::network::NetworkManager; +use crate::network::{NetworkManager, SendRequest}; use crate::storage::{BlockHeaderStorage, FilterHeaderStorage}; use crate::sync::filter_headers::util::compute_filter_headers; use crate::sync::progress::ProgressPercentage; @@ -40,6 +41,8 @@ pub struct FilterHeadersManager /// Whether block header sync has completed. Gates FilterHeadersSyncComplete emission /// to ensure it never fires before BlockHeaderSyncComplete. pub(super) block_headers_synced: bool, + /// Start and stop hash of the batch requested below the stored filter headers. + pub(super) lower_batch: Option<(u32, BlockHash)>, } impl FilterHeadersManager { @@ -101,6 +104,7 @@ impl FilterHeadersManager pipeline: FilterHeadersPipeline::default(), checkpoint_start_height: None, block_headers_synced: false, + lower_batch: None, }) } @@ -184,6 +188,75 @@ impl FilterHeadersManager Ok(count) } + /// Request the batch ending at the lowest stored filter header while block + /// headers reach below it. Each batch is checked against the stored header + /// it ends at, so the range fills downwards without gaps. + pub(super) async fn extend_down( + &mut self, + network: &Arc, + ) -> SyncResult<()> { + let header_storage = self.header_storage.read().await; + let header_start = header_storage.get_start_height().await; + let filter_start = self.filter_header_storage.read().await.get_filter_start_height().await; + // A chain anchored at a checkpoint holds the filter header below it too. + let (Some(header_start), Some(end)) = (header_start, filter_start) else { + return Ok(()); + }; + if end <= header_start.saturating_sub(1) { + return Ok(()); + } + let start = header_start.max(end.saturating_sub(FILTER_HEADERS_BATCH_SIZE - 1)); + let stop_hash = *header_storage + .get_header(end) + .await? + .ok_or_else(|| SyncError::Storage(format!("Missing header at height {end}")))? + .hash(); + drop(header_storage); + + self.lower_batch = Some((start, stop_hash)); + network + .send(GetCFHeaders { + filter_type: 0, + start_height: start, + stop_hash, + }) + .await; + Ok(()) + } + + /// Store a batch [`Self::extend_down`] requested, if it ends at the stored + /// filter header it was requested for. + pub(super) async fn store_lower_batch( + &mut self, + start: u32, + cfheaders: &CFHeaders, + ) -> SyncResult> { + self.lower_batch = None; + let mut headers = compute_filter_headers(cfheaders); + let end = (start + headers.len() as u32).saturating_sub(1); + let mut storage = self.filter_header_storage.write().await; + if headers.is_empty() + || storage.get_filter_start_height().await != Some(end) + || headers.pop() != storage.get_filter_header(end).await? + { + tracing::warn!( + "CFHeaders batch at {} does not end at the stored filter headers", + start + ); + return Ok(vec![]); + } + if start > 0 { + headers.insert(0, cfheaders.previous_filter_header); + } + let first = start.saturating_sub(1); + storage.store_filter_headers_at_height(&headers, first).await?; + Ok(vec![SyncEvent::FilterHeadersStored { + start_height: first, + end_height: end - 1, + tip_height: self.progress.current_height(), + }]) + } + /// Start or resume filter header download. async fn start_download( &mut self, diff --git a/dash-spv/src/sync/filter_headers/pipeline.rs b/dash-spv/src/sync/filter_headers/pipeline.rs index 83d11e080..0679ccfd1 100644 --- a/dash-spv/src/sync/filter_headers/pipeline.rs +++ b/dash-spv/src/sync/filter_headers/pipeline.rs @@ -12,7 +12,7 @@ use crate::network::{NetworkManager, SendRequest}; use crate::storage::BlockHeaderStorage; /// Batch size for filter header requests. -const FILTER_HEADERS_BATCH_SIZE: u32 = 2000; +pub(super) const FILTER_HEADERS_BATCH_SIZE: u32 = 2000; /// Pipeline for downloading compact block filter headers. #[derive(Debug)] diff --git a/dash-spv/src/sync/filter_headers/sync_manager.rs b/dash-spv/src/sync/filter_headers/sync_manager.rs index 73d6c1b5c..d95795dd7 100644 --- a/dash-spv/src/sync/filter_headers/sync_manager.rs +++ b/dash-spv/src/sync/filter_headers/sync_manager.rs @@ -8,6 +8,7 @@ use crate::sync::{ }; use crate::SyncError; use async_trait::async_trait; +use dashcore::network::message::NetworkMessage; use std::net::SocketAddr; use std::sync::Arc; @@ -45,6 +46,15 @@ impl SyncManager for FilterHeade msg: InboundMessage, network: &Arc, ) -> SyncResult> { + if let NetworkMessage::CFHeaders(cfheaders) = &*msg { + if let Some((start, stop_hash)) = + self.lower_batch.filter(|(_, stop_hash)| *stop_hash == cfheaders.stop_hash) + { + network.release_request(RequestKey::CfHeaders(stop_hash)).await; + return self.store_lower_batch(start, cfheaders).await; + } + } + // Match response to get start height let Some((start_height, cfheaders)) = self.pipeline.match_response(&msg) else { if self.pipeline.is_complete() { @@ -141,6 +151,7 @@ impl SyncManager for FilterHeade } async fn tick(&mut self, network: &Arc) -> SyncResult> { + self.extend_down(network).await?; self.pipeline.send_pending(network).await?; // Re-read the block-header tip and extend from here if it moved. diff --git a/dash-spv/src/sync/filters/coinjoin_gap_discovery_tests.rs b/dash-spv/src/sync/filters/coinjoin_gap_discovery_tests.rs index 5e4e75598..0277836b0 100644 --- a/dash-spv/src/sync/filters/coinjoin_gap_discovery_tests.rs +++ b/dash-spv/src/sync/filters/coinjoin_gap_discovery_tests.rs @@ -82,6 +82,7 @@ async fn setup() -> (CjFiltersManager, Arc>, + /// Lowest height a wallet can need, whatever its birth height. + sync_floor: u32, } impl @@ -133,6 +135,7 @@ impl>, filter_header_storage: Arc>, filter_storage: Arc>, + sync_floor: u32, ) -> Self { let committed_height = wallet.read().await.synced_height(); let stored_height = filter_storage.read().await.filter_tip_height().await.unwrap_or(0); @@ -167,6 +170,7 @@ impl 0 { @@ -323,6 +336,14 @@ impl download_start.saturating_sub(1)) { + self.set_state(SyncState::WaitForEvents); + return Ok(vec![]); + } + // Anchor the scan and store frontiers even when we return early below. // A wallet that boots already synced takes the early return, and a // later new block would otherwise create a lookahead batch from a @@ -1244,6 +1265,7 @@ mod tests { storage.block_headers(), storage.filter_headers(), storage.filters(), + 0, ) .await } @@ -1257,6 +1279,7 @@ mod tests { storage.block_headers(), storage.filter_headers(), storage.filters(), + 0, ) .await } @@ -1304,17 +1327,17 @@ mod tests { } } - // Non-zero, since the segment store reads an all-zero filter header - // back as an empty slot. - let prev_filter_header = FilterHeader::from_byte_array([1u8; 32]); + // From the one below the anchor, as a checkpoint sync stores them. Non-zero, + // since the segment store reads an all-zero filter header back as an empty slot. + let mut filter_headers = vec![FilterHeader::from_byte_array([1u8; 32])]; + for _ in anchor..=anchor + span { + filter_headers.push(filter.filter_header(filter_headers.last().unwrap())); + } manager .filter_header_storage .write() .await - .store_filter_headers_at_height( - &[prev_filter_header, filter.filter_header(&prev_filter_header)], - anchor + span, - ) + .store_filter_headers_at_height(&filter_headers, anchor - 1) .await .unwrap(); } @@ -1341,7 +1364,9 @@ mod tests { /// Headers and filters both cover `anchor..=anchor + span`. Filter headers /// are stored so `handle_new_filter_headers` can drive a real download. async fn create_anchored_test_manager(anchor: u32, span: u32) -> TestFiltersManager { - let manager = create_test_manager().await; + let mut manager = create_test_manager().await; + // Floored at the anchor, so a wallet below it needs no backfill. + manager.sync_floor = anchor; seed_anchored_storage(&manager, anchor, span).await; manager } @@ -1467,6 +1492,7 @@ mod tests { storage.block_headers(), storage.filter_headers(), storage.filters(), + 0, ) .await; @@ -3807,6 +3833,7 @@ mod tests { ); let mut manager = create_multi_test_manager(multi.clone()).await; + manager.sync_floor = 200_000; seed_anchored_storage(&manager, 200_000, 10).await; let requests: Arc = Arc::new(MockNetworkManager::new()); From 944195bdeeb971f935763046179e40e82256cbe1 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Thu, 29 Oct 2026 05:01:32 -0700 Subject: [PATCH 03/20] fix(dash-spv): store the forward header batches before the ones below `store_ready_batches` stored the headers below the stored ones first, so a failure there dropped the forward batches, which had already left the pipeline and would never be downloaded again. Co-Authored-By: Claude Opus 5.5 --- dash-spv/src/sync/block_headers/manager.rs | 59 +++++++++++++++++++--- 1 file changed, 51 insertions(+), 8 deletions(-) diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index d311c469e..ed34b5c26 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -370,14 +370,6 @@ impl BlockHeadersManager { ) -> SyncResult> { let mut events = Vec::new(); - if let Some(below) = self.pipeline.take_below() { - let start = self.header_storage.read().await.get_start_height().await; - let start = start.ok_or_else(|| { - SyncError::MissingDependency("no headers stored to sync below".to_string()) - })?; - self.store_below(start, &below).await?; - } - for (_start_height, batch_headers) in ready_batches { if !batch_headers.is_empty() { // Validate chain continuity with current tip @@ -406,6 +398,16 @@ impl BlockHeadersManager { } } + // Last, as the batches above already left the pipeline and a failure + // here would otherwise drop them. + if let Some(below) = self.pipeline.take_below() { + let start = self.header_storage.read().await.get_start_height().await; + let start = start.ok_or_else(|| { + SyncError::MissingDependency("no headers stored to sync below".to_string()) + })?; + self.store_below(start, &below).await?; + } + Ok(events) } @@ -683,6 +685,47 @@ mod tests { ); } + /// Headers below the stored ones that fail to store must not take the + /// forward batches stored alongside them down too: those already left the + /// pipeline, so nothing would download them again. + #[tokio::test] + async fn test_failed_store_below_keeps_forward_batches() { + let storage = DiskStorageManager::with_temp_dir().await.unwrap(); + let stored: Vec = Header::dummy_chain(3, BlockHash::dummy(1)) + .iter() + .map(HashedBlockHeader::from) + .collect(); + storage.block_headers().write().await.store_headers_at_height(&stored, 10).await.unwrap(); + let mut manager = BlockHeadersManager::new( + storage.block_headers(), + storage.metadata(), + create_test_checkpoint_manager(), + Network::Regtest, + ) + .await + .unwrap(); + let tip = manager.tip().await.unwrap(); + manager.pipeline.init(tip.height(), *tip.hash(), tip.height() + 2); + + // Headers below that join neither the anchor nor the stored ones. + let below: Vec = Header::dummy_chain(1, BlockHash::dummy(2)) + .iter() + .map(HashedBlockHeader::from) + .collect(); + manager.pipeline.sync_below(0, BlockHash::dummy(2), 1, *below[0].hash()); + manager.pipeline.receive_headers(&below).unwrap(); + + let forward: Vec = + Header::dummy_chain(2, *tip.hash()).iter().map(HashedBlockHeader::from).collect(); + manager.pipeline.receive_headers(&forward).unwrap(); + let ready = manager.pipeline.take_ready_to_store(); + assert!(!ready.is_empty(), "precondition: the forward batch is ready"); + + let _ = manager.store_ready_batches(ready).await; + + assert_eq!(manager.tip().await.unwrap().height(), tip.height() + 2); + } + #[tokio::test] async fn test_block_headers_manager_new() { let manager = create_test_manager().await; From 6c08b0f107be78237fc16f840af586b78f26da38 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Fri, 30 Oct 2026 05:07:26 -0700 Subject: [PATCH 04/20] test(dash-spv): give wait_for_wallet_synced the full sync timeout A wallet born at genesis rescans the whole chain, which under coverage on CI takes about as long as a full sync and overran the 30s limit. Co-Authored-By: Claude Opus 5.5 --- dash-spv/tests/dashd_sync/helpers.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/dash-spv/tests/dashd_sync/helpers.rs b/dash-spv/tests/dashd_sync/helpers.rs index 24a60416f..ccc509d43 100644 --- a/dash-spv/tests/dashd_sync/helpers.rs +++ b/dash-spv/tests/dashd_sync/helpers.rs @@ -144,12 +144,15 @@ pub(super) async fn wait_for_wallet_synced( if synced >= target { return; } - let deadline = tokio::time::Instant::now() + Duration::from_secs(30); + let deadline = tokio::time::Instant::now() + SYNC_TIMEOUT; loop { let recv = tokio::time::timeout_at(deadline, events.recv()).await; match recv { Err(_) => { - panic!("wallet did not reach synced_height {} within 30s, got {}", target, synced) + panic!( + "wallet did not reach synced_height {} within {:?}, got {}", + target, SYNC_TIMEOUT, synced + ) } Ok(Err(_)) => { panic!("wallet event channel error before reaching synced_height {}", target); From 696dbd2fd8ed55974b4d6789c4c9e7e9dcbf4907 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 2 Nov 2026 08:30:35 -0800 Subject: [PATCH 05/20] fix(dash-spv): stop the backfill at an explicit start height Co-Authored-By: Claude Opus 5.5 --- dash-spv/src/client/lifecycle.rs | 4 ++- dash-spv/src/sync/filters/manager.rs | 3 +- .../tests/dashd_sync/tests_multi_wallet.rs | 31 +++++++++++++++++++ 3 files changed, 36 insertions(+), 2 deletions(-) diff --git a/dash-spv/src/client/lifecycle.rs b/dash-spv/src/client/lifecycle.rs index 5fbbd4e7a..7e41d8039 100644 --- a/dash-spv/src/client/lifecycle.rs +++ b/dash-spv/src/client/lifecycle.rs @@ -142,7 +142,9 @@ impl DashSpvClient { storage.block_headers(), storage.filter_headers(), storage.filters(), - config.network.hd_wallet_sync_floor(), + config + .start_from_height + .unwrap_or_else(|| config.network.hd_wallet_sync_floor()), ) .await, ); diff --git a/dash-spv/src/sync/filters/manager.rs b/dash-spv/src/sync/filters/manager.rs index fe07f8791..8c2e1f5d8 100644 --- a/dash-spv/src/sync/filters/manager.rs +++ b/dash-spv/src/sync/filters/manager.rs @@ -122,7 +122,8 @@ pub struct FiltersManager< pub(super) tracker: BlockMatchTracker, /// Scripts found by processed blocks since the last tick, rescanned together. pub(super) pending_new_scripts: BTreeMap>, - /// Lowest height a wallet can need, whatever its birth height. + /// Lowest height to sync down to, whatever a wallet's birth height: the + /// explicit start height, or else the network's HD sync floor. sync_floor: u32, } diff --git a/dash-spv/tests/dashd_sync/tests_multi_wallet.rs b/dash-spv/tests/dashd_sync/tests_multi_wallet.rs index 689272053..21f51a967 100644 --- a/dash-spv/tests/dashd_sync/tests_multi_wallet.rs +++ b/dash-spv/tests/dashd_sync/tests_multi_wallet.rs @@ -692,3 +692,34 @@ async fn test_wallet_added_below_synced_wallet(restart: bool, mine: bool) { assert_eq!(count_wallet_transactions(&wallet, &tip_id).await, 0); handle.stop().await; } + +/// An explicit `start_from_height` limits how far down the client syncs, even +/// for a wallet born below it. +#[tokio::test] +async fn test_explicit_start_height_limits_backfill() { + let Some(ctx) = TestContext::new(TestChain::Full).await else { + return; + }; + let height = ctx.dashd.initial_height; + let anchor = height / 2; + anchor_at_checkpoint(&ctx.client_config, &ctx.dashd.node, anchor).await; + let mut config = ctx.client_config.clone(); + config.start_from_height = Some(anchor); + + let wallet = Arc::new(RwLock::new(WalletManager::::new(Network::Regtest))); + let wallet_id = wallet + .write() + .await + .create_wallet_from_mnemonic(&ctx.dashd.wallet.mnemonic, 0, default_test_account_options()) + .unwrap(); + let mut handle = create_and_start_client(&config, Arc::clone(&wallet)).await; + wait_for_sync(&mut handle.progress_receiver, height).await; + wait_for_wallet_synced(&wallet, &wallet_id, height).await; + handle.stop().await; + drop(handle); + + let mut storage = DiskStorageManager::new(&config).await.unwrap(); + let start = storage.get_start_height().await; + storage.stop().await; + assert_eq!(start, Some(anchor + 1 - CHECKPOINT_HEADERS as u32)); +} From d691e23637c54765f678c7dab5b60894f3a10a64 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 2 Nov 2026 08:47:14 -0800 Subject: [PATCH 06/20] test(dash-spv): cover the backfill across checkpoints and rejected batches Co-Authored-By: Claude Opus 5.5 --- dash-spv/src/chain/checkpoints.rs | 15 +++++++ dash-spv/src/sync/block_headers/manager.rs | 44 +++++++++++++++++++++ dash-spv/src/sync/filter_headers/manager.rs | 36 +++++++++++++++++ 3 files changed, 95 insertions(+) diff --git a/dash-spv/src/chain/checkpoints.rs b/dash-spv/src/chain/checkpoints.rs index d06a6bfaf..18fd223e5 100644 --- a/dash-spv/src/chain/checkpoints.rs +++ b/dash-spv/src/chain/checkpoints.rs @@ -37,6 +37,21 @@ static NO_CHECKPOINTS: CheckpointManager = CheckpointManager { checkpoints: BTreeMap::new(), }; +#[cfg(any(test, feature = "test-utils"))] +impl CheckpointManager { + /// Checkpoints at every 50th block of `chain`. + pub fn dummy(chain: &[HashedBlockHeader]) -> Self { + let checkpoints = (49..chain.len()) + .step_by(50) + .map(|height| { + let headers = chain[height + 1 - CHECKPOINT_HEADERS..=height].to_vec(); + Checkpoint::new(height as u32, headers).expect("dummy checkpoint must fit") + }) + .collect(); + Self::new(checkpoints) + } +} + /// A known block and the [`CHECKPOINT_HEADERS`] - 1 headers before it. #[derive(Debug, Clone)] pub struct Checkpoint { diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index ed34b5c26..ef3cbd301 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -726,6 +726,50 @@ mod tests { assert_eq!(manager.tip().await.unwrap().height(), tip.height() + 2); } + /// Syncs down one checkpoint at a time: an adjacent one needs no download, + /// a distant one does, and it stops once it reaches the floor, not genesis. + #[tokio::test] + async fn test_extend_down_descends_checkpoints_to_the_floor() { + let chain: Vec = Header::dummy_chain(130, BlockHash::dummy(1)) + .iter() + .map(HashedBlockHeader::from) + .collect(); + + let storage = DiskStorageManager::with_temp_dir().await.unwrap(); + let headers = storage.block_headers(); + headers.write().await.store_headers_at_height(&chain[100..], 100).await.unwrap(); + let mut manager = BlockHeadersManager::new( + headers.clone(), + storage.metadata(), + Box::leak(Box::new(CheckpointManager::dummy(&chain))), + Network::Regtest, + ) + .await + .unwrap(); + manager.pipeline.init(129, *chain[129].hash(), 129); + manager.floor = Some(30); + + manager.extend_down().await.unwrap(); + assert!(!manager.pipeline.is_syncing_below()); + assert_eq!(headers.read().await.get_start_height().await, Some(75)); + + manager.extend_down().await.unwrap(); + assert!(manager.pipeline.is_syncing_below()); + manager.pipeline.receive_headers(&chain[50..75]).unwrap(); + manager.store_ready_batches(Vec::new()).await.unwrap(); + assert!(!manager.pipeline.is_syncing_below()); + assert_eq!(headers.read().await.get_start_height().await, Some(25)); + + manager.extend_down().await.unwrap(); + assert_eq!(manager.floor, None); + assert!(!manager.pipeline.is_syncing_below()); + assert_eq!(headers.read().await.get_start_height().await, Some(25)); + for height in 25..=129u32 { + let stored = headers.read().await.get_header(height).await.unwrap(); + assert_eq!(stored.map(|header| *header.hash()), Some(*chain[height as usize].hash())); + } + } + #[tokio::test] async fn test_block_headers_manager_new() { let manager = create_test_manager().await; diff --git a/dash-spv/src/sync/filter_headers/manager.rs b/dash-spv/src/sync/filter_headers/manager.rs index c336035ba..219587316 100644 --- a/dash-spv/src/sync/filter_headers/manager.rs +++ b/dash-spv/src/sync/filter_headers/manager.rs @@ -388,6 +388,7 @@ mod tests { use dashcore::network::message::NetworkMessage; use dashcore::{block::Version, BlockHash, CompactTarget, Header as BlockHeader}; use dashcore_hashes::Hash; + use test_case::test_case; type TestFilterHeadersManager = FilterHeadersManager; @@ -720,6 +721,41 @@ mod tests { storage.filter_headers().read().await.get_filter_tip_height().await.unwrap() } + /// A batch below the stored filter headers that doesn't end at them stores nothing. + #[test_case(0, b"prev" ; "empty")] + #[test_case(1999, b"prev" ; "wrong end")] + #[test_case(2000, b"other" ; "last header mismatch")] + #[tokio::test] + async fn test_lower_batch_not_ending_at_stored_filter_headers_is_rejected( + count: u32, + previous: &[u8], + ) { + let storage = DiskStorageManager::with_temp_dir().await.unwrap(); + let hashes = store_block_headers(&storage, 0, 2001).await; + let stop_hash = hashes[2000]; + let stored = + compute_filter_headers(&cfheaders(FilterHeader::hash(b"prev"), stop_hash, 2000)); + let filter_headers = storage.filter_headers(); + filter_headers + .write() + .await + .store_filter_headers_at_height(&stored[1999..], 2000) + .await + .unwrap(); + let mut manager = + FilterHeadersManager::new(storage.block_headers(), filter_headers.clone()) + .await + .unwrap(); + manager.lower_batch = Some((1, stop_hash)); + + let batch = cfheaders(FilterHeader::hash(previous), stop_hash, count); + let events = manager.store_lower_batch(1, &batch).await.unwrap(); + + assert!(events.is_empty()); + assert_eq!(manager.lower_batch, None); + assert_eq!(filter_headers.read().await.get_filter_start_height().await, Some(2000)); + } + #[tokio::test] async fn test_cfheaders_batch_not_connecting_to_stored_header_is_requeued() { let storage = DiskStorageManager::with_temp_dir().await.unwrap(); From b6ed9e2cd422d90772d51e4e8a2fbd060ccb187d Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Wed, 4 Nov 2026 05:11:34 -0800 Subject: [PATCH 07/20] fix(dash-spv): count the heights still missing below in the sync progress --- dash-spv/src/sync/block_headers/manager.rs | 2 ++ dash-spv/src/sync/block_headers/progress.rs | 11 +++++++++++ dash-spv/src/sync/filter_headers/manager.rs | 1 + dash-spv/src/sync/filter_headers/progress.rs | 11 +++++++++++ dash-spv/src/sync/progress.rs | 7 ++++++- 5 files changed, 31 insertions(+), 1 deletion(-) diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index ef3cbd301..e524de08e 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -129,8 +129,10 @@ impl BlockHeadersManager { let storage = self.header_storage.read().await; let Some(start) = storage.get_start_height().await.filter(|start| floor < *start) else { self.floor = None; + self.progress.update_missing_below(0); return Ok(()); }; + self.progress.update_missing_below(start - floor); let join = storage .get_header(start) .await? diff --git a/dash-spv/src/sync/block_headers/progress.rs b/dash-spv/src/sync/block_headers/progress.rs index 890936e94..785429081 100644 --- a/dash-spv/src/sync/block_headers/progress.rs +++ b/dash-spv/src/sync/block_headers/progress.rs @@ -14,6 +14,8 @@ pub struct BlockHeadersProgress { target_height: u32, /// Number of block-headers processed (stored) in the current sync session. processed: u32, + /// Number of heights below the stored ones still to sync. + missing_below: u32, /// Number of headers currently buffered in the pipeline (waiting to be stored). buffered: u32, /// The last time a block-header was stored to disk or the last manager state change. @@ -27,6 +29,7 @@ impl Default for BlockHeadersProgress { tip_height: 0, target_height: 0, processed: 0, + missing_below: 0, buffered: 0, last_activity: Instant::now(), } @@ -81,6 +84,11 @@ impl BlockHeadersProgress { pub fn update_buffered(&mut self, count: u32) { self.buffered = count; } + /// Update the number of heights below the stored ones still to sync. + pub fn update_missing_below(&mut self, count: u32) { + self.missing_below = count; + self.bump_last_activity(); + } /// Bump the last activity time. pub fn bump_last_activity(&mut self) { self.last_activity = Instant::now(); @@ -105,6 +113,9 @@ impl fmt::Display for BlockHeadersProgress { } impl ProgressPercentage for BlockHeadersProgress { + fn missing_below(&self) -> u32 { + self.missing_below + } fn target_height(&self) -> u32 { self.target_height } diff --git a/dash-spv/src/sync/filter_headers/manager.rs b/dash-spv/src/sync/filter_headers/manager.rs index 219587316..ba9a2c062 100644 --- a/dash-spv/src/sync/filter_headers/manager.rs +++ b/dash-spv/src/sync/filter_headers/manager.rs @@ -202,6 +202,7 @@ impl FilterHeadersManager let (Some(header_start), Some(end)) = (header_start, filter_start) else { return Ok(()); }; + self.progress.update_missing_below(end.saturating_sub(header_start.saturating_sub(1))); if end <= header_start.saturating_sub(1) { return Ok(()); } diff --git a/dash-spv/src/sync/filter_headers/progress.rs b/dash-spv/src/sync/filter_headers/progress.rs index 1ec82679d..0ac1e30b7 100644 --- a/dash-spv/src/sync/filter_headers/progress.rs +++ b/dash-spv/src/sync/filter_headers/progress.rs @@ -16,6 +16,8 @@ pub struct FilterHeadersProgress { block_header_tip_height: u32, /// Number of filter-headers processed (stored) in the current sync session. processed: u32, + /// Number of heights below the stored ones still to sync. + missing_below: u32, /// The last time a filter-header was stored to disk or the last manager state change. last_activity: Instant, } @@ -28,6 +30,7 @@ impl Default for FilterHeadersProgress { target_height: 0, block_header_tip_height: 0, processed: 0, + missing_below: 0, last_activity: Instant::now(), } } @@ -86,6 +89,11 @@ impl FilterHeadersProgress { self.bump_last_activity(); } + /// Update the number of heights below the stored ones still to sync. + pub fn update_missing_below(&mut self, count: u32) { + self.missing_below = count; + self.bump_last_activity(); + } /// Bump the last activity time. pub fn bump_last_activity(&mut self) { self.last_activity = Instant::now(); @@ -109,6 +117,9 @@ impl fmt::Display for FilterHeadersProgress { } impl ProgressPercentage for FilterHeadersProgress { + fn missing_below(&self) -> u32 { + self.missing_below + } fn target_height(&self) -> u32 { self.target_height } diff --git a/dash-spv/src/sync/progress.rs b/dash-spv/src/sync/progress.rs index 724dc993a..ffa456c77 100644 --- a/dash-spv/src/sync/progress.rs +++ b/dash-spv/src/sync/progress.rs @@ -265,11 +265,16 @@ pub trait ProgressPercentage { fn target_height(&self) -> CoreBlockHeight; /// Get the current height used for calculating progress. fn current_height(&self) -> CoreBlockHeight; + /// Get the number of heights below the stored ones still to sync. + fn missing_below(&self) -> CoreBlockHeight { + 0 + } /// Get completion percentage (0.0 to 1.0). fn percentage(&self) -> f64 { if self.target_height() == 0 { return 0.0; } - (self.current_height() as f64 / self.target_height() as f64).min(1.0) + let done = self.current_height().saturating_sub(self.missing_below()); + (done as f64 / self.target_height() as f64).min(1.0) } } From 502d95ef00b342fedd14bb71d2e6aa7432d33d00 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Wed, 4 Nov 2026 05:35:01 -0800 Subject: [PATCH 08/20] fix(dash-spv): report the filter headers backfill as syncing --- dash-spv/src/sync/filter_headers/manager.rs | 13 +++++- .../tests/dashd_sync/tests_multi_wallet.rs | 42 +++++++++++++++++-- 2 files changed, 50 insertions(+), 5 deletions(-) diff --git a/dash-spv/src/sync/filter_headers/manager.rs b/dash-spv/src/sync/filter_headers/manager.rs index ba9a2c062..9b71b2420 100644 --- a/dash-spv/src/sync/filter_headers/manager.rs +++ b/dash-spv/src/sync/filter_headers/manager.rs @@ -215,6 +215,9 @@ impl FilterHeadersManager drop(header_storage); self.lower_batch = Some((start, stop_hash)); + if self.state() == SyncState::Synced { + self.set_state(SyncState::Syncing); + } network .send(GetCFHeaders { filter_type: 0, @@ -251,11 +254,17 @@ impl FilterHeadersManager } let first = start.saturating_sub(1); storage.store_filter_headers_at_height(&headers, first).await?; - Ok(vec![SyncEvent::FilterHeadersStored { + drop(storage); + let mut events = vec![SyncEvent::FilterHeadersStored { start_height: first, end_height: end - 1, tip_height: self.progress.current_height(), - }]) + }]; + let header_start = self.header_storage.read().await.get_start_height().await.unwrap_or(0); + if first <= header_start.saturating_sub(1) { + events.extend(self.try_complete_sync()); + } + Ok(events) } /// Start or resume filter header download. diff --git a/dash-spv/tests/dashd_sync/tests_multi_wallet.rs b/dash-spv/tests/dashd_sync/tests_multi_wallet.rs index 21f51a967..26ddb9c1a 100644 --- a/dash-spv/tests/dashd_sync/tests_multi_wallet.rs +++ b/dash-spv/tests/dashd_sync/tests_multi_wallet.rs @@ -9,9 +9,11 @@ use test_case::test_case; use tokio::sync::RwLock; use dash_spv::chain::checkpoints::CHECKPOINT_HEADERS; -use dash_spv::test_utils::{BlockHeaderStorage, DashCoreNode, DiskStorageManager, StorageManager}; +use dash_spv::test_utils::{ + BlockHeaderStorage, DashCoreNode, DiskStorageManager, StorageManager, SYNC_TIMEOUT, +}; use dash_spv::types::HashedBlockHeader; -use dash_spv::{ClientConfig, Network}; +use dash_spv::{ClientConfig, Network, ProgressPercentage, SyncState}; use dashcore::block::Header; use dashcore::consensus::deserialize; use dashcore::{Address, Amount}; @@ -684,11 +686,45 @@ async fn test_wallet_added_below_synced_wallet(restart: bool, mine: bool) { let miner = ctx.dashd.node.get_new_address_from_wallet("default"); ctx.dashd.node.generate_blocks(1, &miner); } + + let backfilling = |progress: &dyn ProgressPercentage, state: SyncState| { + progress.missing_below() > 0 && progress.percentage() < 1.0 && state == SyncState::Syncing + }; + let (mut headers_seen, mut filter_headers_seen) = (false, false); + tokio::time::timeout(SYNC_TIMEOUT, async { + while !(headers_seen && filter_headers_seen) { + { + let progress = handle.progress_receiver.borrow_and_update(); + if let Ok(headers) = progress.headers() { + headers_seen |= backfilling(headers, headers.state()); + } + if let Ok(filter_headers) = progress.filter_headers() { + filter_headers_seen |= backfilling(filter_headers, filter_headers.state()); + } + } + handle.progress_receiver.changed().await.unwrap(); + } + }) + .await + .expect("headers and filter headers should report the backfill"); + wait_for_sync(&mut handle.progress_receiver, tip).await; wait_for_wallet_synced(&wallet, &history_id, tip).await; wait_for_wallet_synced(&wallet, &tip_id, tip).await; - ctx.assert_wallet_synced_at(&handle.client.progress().await, &wallet, &history_id, tip).await; + let progress = handle.client.progress().await; + for (part, state) in [ + ( + progress.headers().unwrap() as &dyn ProgressPercentage, + progress.headers().unwrap().state(), + ), + (progress.filter_headers().unwrap(), progress.filter_headers().unwrap().state()), + ] { + assert_eq!(state, SyncState::Synced); + assert_eq!(part.missing_below(), 0); + assert_eq!(part.percentage(), 1.0); + } + ctx.assert_wallet_synced_at(&progress, &wallet, &history_id, tip).await; assert_eq!(count_wallet_transactions(&wallet, &tip_id).await, 0); handle.stop().await; } From 58167cd4aeed04c59a36aaf5bda08040c9b54ab3 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Thu, 5 Nov 2026 04:28:34 -0800 Subject: [PATCH 09/20] fix(dash-spv): stop bumping the activity when setting the heights missing below --- dash-spv/src/sync/block_headers/progress.rs | 1 - dash-spv/src/sync/filter_headers/progress.rs | 1 - 2 files changed, 2 deletions(-) diff --git a/dash-spv/src/sync/block_headers/progress.rs b/dash-spv/src/sync/block_headers/progress.rs index 785429081..77b18c1b6 100644 --- a/dash-spv/src/sync/block_headers/progress.rs +++ b/dash-spv/src/sync/block_headers/progress.rs @@ -87,7 +87,6 @@ impl BlockHeadersProgress { /// Update the number of heights below the stored ones still to sync. pub fn update_missing_below(&mut self, count: u32) { self.missing_below = count; - self.bump_last_activity(); } /// Bump the last activity time. pub fn bump_last_activity(&mut self) { diff --git a/dash-spv/src/sync/filter_headers/progress.rs b/dash-spv/src/sync/filter_headers/progress.rs index 0ac1e30b7..6f1717643 100644 --- a/dash-spv/src/sync/filter_headers/progress.rs +++ b/dash-spv/src/sync/filter_headers/progress.rs @@ -92,7 +92,6 @@ impl FilterHeadersProgress { /// Update the number of heights below the stored ones still to sync. pub fn update_missing_below(&mut self, count: u32) { self.missing_below = count; - self.bump_last_activity(); } /// Bump the last activity time. pub fn bump_last_activity(&mut self) { From 1655598dfdba325029feb2668a4c568a93ae8351 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Thu, 5 Nov 2026 04:32:18 -0800 Subject: [PATCH 10/20] refactor(dash-spv): return the anchor below as a `Checkpoint` --- dash-spv/src/chain/checkpoints.rs | 13 ++++++-- dash-spv/src/sync/block_headers/manager.rs | 37 ++++++++++------------ 2 files changed, 28 insertions(+), 22 deletions(-) diff --git a/dash-spv/src/chain/checkpoints.rs b/dash-spv/src/chain/checkpoints.rs index 18fd223e5..c82b56866 100644 --- a/dash-spv/src/chain/checkpoints.rs +++ b/dash-spv/src/chain/checkpoints.rs @@ -11,6 +11,7 @@ use std::io::{Read, Write}; use std::sync::LazyLock; use dashcore::block::Header; +use dashcore::blockdata::constants::genesis_block; use dashcore::consensus::{encode, Decodable, Encodable}; use dashcore::{BlockHash, Network}; @@ -73,6 +74,14 @@ impl Checkpoint { }) } + /// The genesis block of `network`, alone. + pub fn genesis(network: Network) -> Self { + Self { + height: 0, + headers: vec![genesis_block(network).header.into()], + } + } + /// Height of the checkpoint block. pub fn height(&self) -> u32 { self.height @@ -85,7 +94,7 @@ impl Checkpoint { /// Header of the checkpoint block. pub fn header(&self) -> &HashedBlockHeader { - &self.headers[CHECKPOINT_HEADERS - 1] + self.headers.last().expect("a checkpoint holds headers") } /// All the headers of the checkpoint, oldest first, from [`Self::start_height`]. @@ -95,7 +104,7 @@ impl Checkpoint { /// Height of the first of [`Self::headers`]. pub fn start_height(&self) -> u32 { - self.height - (CHECKPOINT_HEADERS as u32 - 1) + self.height + 1 - self.headers.len() as u32 } } diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index e524de08e..2dcdab782 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -11,7 +11,7 @@ use std::net::SocketAddr; use std::sync::Arc; use std::time::Instant; -use crate::chain::CheckpointManager; +use crate::chain::{Checkpoint, CheckpointManager}; use crate::error::{SyncError, SyncResult}; use crate::network::{NetworkManager, RequestKey}; use crate::storage::{BlockHeaderStorage, BlockHeaderTip, MetadataStorage}; @@ -24,7 +24,6 @@ use crate::types::HashedBlockHeader; use crate::validation::{BlockHeaderValidator, Validator}; #[cfg(test)] use dashcore::block::Header; -use dashcore::blockdata::constants::genesis_block; use dashcore::ephemerealdata::chain_lock::ChainLock; use dashcore::network::message_blockdata::Inventory; use dashcore::pow::DGW_PAST_BLOCKS; @@ -141,24 +140,22 @@ impl BlockHeadersManager { .prev_blockhash; drop(storage); - let (anchor_start, anchor) = self.anchor_below(start); - let anchor_height = anchor_start + anchor.len() as u32 - 1; - if anchor_height + 1 == start { + let anchor = self.anchor_below(start); + if anchor.height() + 1 == start { return self.store_below(start, &[]).await; } - tracing::info!("Syncing headers {}..{} below the stored ones", anchor_height + 1, start); - let anchor_hash = *anchor.last().expect("an anchor holds headers").hash(); - self.pipeline.sync_below(anchor_height, anchor_hash, start - 1, join); + tracing::info!("Syncing headers {}..{} below the stored ones", anchor.height() + 1, start); + self.pipeline.sync_below(anchor.height(), *anchor.hash(), start - 1, join); self.progress.set_state(SyncState::Syncing); Ok(()) } - /// The checkpoint below `start`, or genesis, as its first height and headers. - fn anchor_below(&self, start: u32) -> (u32, Vec) { - match self.checkpoint_manager.last_checkpoint_before_height(start - 1) { - Some(checkpoint) => (checkpoint.start_height(), checkpoint.headers().to_vec()), - None => (0, vec![genesis_block(self.network).header.into()]), - } + /// The checkpoint below `start`, or genesis. + fn anchor_below(&self, start: u32) -> Checkpoint { + self.checkpoint_manager + .last_checkpoint_before_height(start - 1) + .cloned() + .unwrap_or_else(|| Checkpoint::genesis(self.network)) } /// Store the anchor below `start` and the `downloaded` headers joining it to `start`. @@ -167,13 +164,13 @@ impl BlockHeadersManager { start: u32, downloaded: &[HashedBlockHeader], ) -> SyncResult<()> { - let (anchor_start, mut headers) = self.anchor_below(start); - let anchor_height = anchor_start + headers.len() as u32 - 1; + let anchor = self.anchor_below(start); if !downloaded.is_empty() { - let ancestors = headers.iter().map(|header| *header.header()).collect(); - BlockHeaderValidator::new(self.network, ancestors, anchor_height) + let ancestors = anchor.headers().iter().map(|header| *header.header()).collect(); + BlockHeaderValidator::new(self.network, ancestors, anchor.height()) .validate(downloaded)?; } + let mut headers = anchor.headers().to_vec(); headers.extend_from_slice(downloaded); let mut storage = self.header_storage.write().await; let joins = storage.get_header(start).await?.map(|header| header.header().prev_blockhash) @@ -181,8 +178,8 @@ impl BlockHeadersManager { if !joins { return Err(SyncError::Validation(format!("headers below {start} do not join it"))); } - storage.store_headers_at_height(&headers, anchor_start).await?; - tracing::info!("Headers synced down to {}", anchor_start); + storage.store_headers_at_height(&headers, anchor.start_height()).await?; + tracing::info!("Headers synced down to {}", anchor.start_height()); Ok(()) } From 8a04ea2a09e0cb5c04943027af1af059d2389363 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Thu, 5 Nov 2026 04:43:54 -0800 Subject: [PATCH 11/20] test(dash-spv): assert the failed store below ran --- dash-spv/src/sync/block_headers/manager.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index 2dcdab782..5df5b60da 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -720,8 +720,9 @@ mod tests { let ready = manager.pipeline.take_ready_to_store(); assert!(!ready.is_empty(), "precondition: the forward batch is ready"); - let _ = manager.store_ready_batches(ready).await; + assert!(manager.store_ready_batches(ready).await.is_err()); + assert!(!manager.pipeline.is_syncing_below()); assert_eq!(manager.tip().await.unwrap().height(), tip.height() + 2); } From 9c2806e274f894710030815c2b3879c73111f1b8 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Thu, 5 Nov 2026 04:50:43 -0800 Subject: [PATCH 12/20] docs(dash-spv): reword the backfill comments --- dash-spv/src/sync/block_headers/manager.rs | 6 ++++-- dash-spv/src/sync/filters/manager.rs | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index 5df5b60da..1f766684c 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -116,8 +116,10 @@ impl BlockHeadersManager { .ok_or_else(|| SyncError::MissingDependency("storage not initialized".to_string())) } - /// Sync from the checkpoint below the lowest stored header, or genesis, up to - /// it, once the pipeline runs, one checkpoint at a time down to [`Self::floor`]. + /// Sync the headers below the lowest stored one, down to [`Self::floor`]. + /// + /// Each step starts at the checkpoint below the lowest stored header, or at genesis, + /// and syncs up to that header. It waits until the pipeline runs. pub(super) async fn extend_down(&mut self) -> SyncResult<()> { if self.pipeline.is_syncing_below() || !self.pipeline.is_initialized() { return Ok(()); diff --git a/dash-spv/src/sync/filters/manager.rs b/dash-spv/src/sync/filters/manager.rs index 8c2e1f5d8..d9745d4e7 100644 --- a/dash-spv/src/sync/filters/manager.rs +++ b/dash-spv/src/sync/filters/manager.rs @@ -337,7 +337,7 @@ impl download_start.saturating_sub(1)) { From 447808687107bb721f91f8c2f4a428ac9aa9ef64 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Thu, 5 Nov 2026 04:53:53 -0800 Subject: [PATCH 13/20] test(dash-spv): drop the transient backfill check --- .../tests/dashd_sync/tests_multi_wallet.rs | 25 +------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/dash-spv/tests/dashd_sync/tests_multi_wallet.rs b/dash-spv/tests/dashd_sync/tests_multi_wallet.rs index 26ddb9c1a..2ee3c80c7 100644 --- a/dash-spv/tests/dashd_sync/tests_multi_wallet.rs +++ b/dash-spv/tests/dashd_sync/tests_multi_wallet.rs @@ -9,9 +9,7 @@ use test_case::test_case; use tokio::sync::RwLock; use dash_spv::chain::checkpoints::CHECKPOINT_HEADERS; -use dash_spv::test_utils::{ - BlockHeaderStorage, DashCoreNode, DiskStorageManager, StorageManager, SYNC_TIMEOUT, -}; +use dash_spv::test_utils::{BlockHeaderStorage, DashCoreNode, DiskStorageManager, StorageManager}; use dash_spv::types::HashedBlockHeader; use dash_spv::{ClientConfig, Network, ProgressPercentage, SyncState}; use dashcore::block::Header; @@ -687,27 +685,6 @@ async fn test_wallet_added_below_synced_wallet(restart: bool, mine: bool) { ctx.dashd.node.generate_blocks(1, &miner); } - let backfilling = |progress: &dyn ProgressPercentage, state: SyncState| { - progress.missing_below() > 0 && progress.percentage() < 1.0 && state == SyncState::Syncing - }; - let (mut headers_seen, mut filter_headers_seen) = (false, false); - tokio::time::timeout(SYNC_TIMEOUT, async { - while !(headers_seen && filter_headers_seen) { - { - let progress = handle.progress_receiver.borrow_and_update(); - if let Ok(headers) = progress.headers() { - headers_seen |= backfilling(headers, headers.state()); - } - if let Ok(filter_headers) = progress.filter_headers() { - filter_headers_seen |= backfilling(filter_headers, filter_headers.state()); - } - } - handle.progress_receiver.changed().await.unwrap(); - } - }) - .await - .expect("headers and filter headers should report the backfill"); - wait_for_sync(&mut handle.progress_receiver, tip).await; wait_for_wallet_synced(&wallet, &history_id, tip).await; wait_for_wallet_synced(&wallet, &tip_id, tip).await; From f6110c2f85d4ba362623d6e819acd5a3d61916fb Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 9 Nov 2026 04:58:34 -0800 Subject: [PATCH 14/20] fix(dash-spv): keep filter headers syncing while a gap remains below `try_complete_sync` only compared the current height with the target, so a `BlockHeaderSyncComplete` during the backfill flipped `FilterHeadersManager` to `Synced` while a lower batch was still pending. It now refuses while `missing_below` is not zero, and `store_lower_batch` updates `missing_below` before its own completion check. --- dash-spv/src/sync/filter_headers/manager.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dash-spv/src/sync/filter_headers/manager.rs b/dash-spv/src/sync/filter_headers/manager.rs index 645744eb7..3c6442b6c 100644 --- a/dash-spv/src/sync/filter_headers/manager.rs +++ b/dash-spv/src/sync/filter_headers/manager.rs @@ -62,6 +62,7 @@ impl FilterHeadersManager /// `Synced` or conditions are not met. pub(super) fn try_complete_sync(&mut self) -> Option { if self.block_headers_synced + && self.progress.missing_below() == 0 && self.progress.current_height() >= self.progress.target_height() { if self.state() == SyncState::Synced { @@ -261,9 +262,8 @@ impl FilterHeadersManager tip_height: self.progress.current_height(), }]; let header_start = self.header_storage.read().await.get_start_height().await.unwrap_or(0); - if first <= header_start.saturating_sub(1) { - events.extend(self.try_complete_sync()); - } + self.progress.update_missing_below(first.saturating_sub(header_start.saturating_sub(1))); + events.extend(self.try_complete_sync()); Ok(events) } From 10a93125e7c92a804284cfbfa47afda06f6c9719 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 9 Nov 2026 04:58:35 -0800 Subject: [PATCH 15/20] refactor(dash-spv): move `CheckpointManager::dummy` to `test_utils` With `dummy` next to `Checkpoint::dummy` in `test_utils`, `CheckpointManager::new` only needs to be `pub(crate)` and stays hidden outside `dash-spv`. --- dash-spv/src/chain/checkpoints.rs | 17 +---------------- dash-spv/src/test_utils/checkpoint.rs | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/dash-spv/src/chain/checkpoints.rs b/dash-spv/src/chain/checkpoints.rs index c82b56866..c97869a2b 100644 --- a/dash-spv/src/chain/checkpoints.rs +++ b/dash-spv/src/chain/checkpoints.rs @@ -38,21 +38,6 @@ static NO_CHECKPOINTS: CheckpointManager = CheckpointManager { checkpoints: BTreeMap::new(), }; -#[cfg(any(test, feature = "test-utils"))] -impl CheckpointManager { - /// Checkpoints at every 50th block of `chain`. - pub fn dummy(chain: &[HashedBlockHeader]) -> Self { - let checkpoints = (49..chain.len()) - .step_by(50) - .map(|height| { - let headers = chain[height + 1 - CHECKPOINT_HEADERS..=height].to_vec(); - Checkpoint::new(height as u32, headers).expect("dummy checkpoint must fit") - }) - .collect(); - Self::new(checkpoints) - } -} - /// A known block and the [`CHECKPOINT_HEADERS`] - 1 headers before it. #[derive(Debug, Clone)] pub struct Checkpoint { @@ -155,7 +140,7 @@ impl CheckpointManager { } } - fn new(checkpoints: Vec) -> Self { + pub(crate) fn new(checkpoints: Vec) -> Self { Self { checkpoints: checkpoints .into_iter() diff --git a/dash-spv/src/test_utils/checkpoint.rs b/dash-spv/src/test_utils/checkpoint.rs index 0e1e20a6c..8db8e99c0 100644 --- a/dash-spv/src/test_utils/checkpoint.rs +++ b/dash-spv/src/test_utils/checkpoint.rs @@ -1,7 +1,7 @@ use dashcore::Header; use crate::chain::checkpoints::CHECKPOINT_HEADERS; -use crate::chain::Checkpoint; +use crate::chain::{Checkpoint, CheckpointManager}; use crate::types::HashedBlockHeader; impl Checkpoint { @@ -13,3 +13,17 @@ impl Checkpoint { Checkpoint::new(height, headers).expect("dummy checkpoint height must fit its headers") } } + +impl CheckpointManager { + /// Checkpoints at every 50th block of `chain`. + pub fn dummy(chain: &[HashedBlockHeader]) -> Self { + let checkpoints = (49..chain.len()) + .step_by(50) + .map(|height| { + let headers = chain[height + 1 - CHECKPOINT_HEADERS..=height].to_vec(); + Checkpoint::new(height as u32, headers).expect("dummy checkpoint must fit") + }) + .collect(); + Self::new(checkpoints) + } +} From 0ca6e4f8301b24695d3633971009bcb9d6e851e0 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 9 Nov 2026 04:58:36 -0800 Subject: [PATCH 16/20] refactor(dash-spv): make `Checkpoint::genesis` crate-private A genesis checkpoint holds one header, so it cannot be decoded back. Keeping it `pub(crate)` stops code outside `dash-spv` from building one. --- dash-spv/src/chain/checkpoints.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dash-spv/src/chain/checkpoints.rs b/dash-spv/src/chain/checkpoints.rs index c97869a2b..c9c0cf01c 100644 --- a/dash-spv/src/chain/checkpoints.rs +++ b/dash-spv/src/chain/checkpoints.rs @@ -60,7 +60,7 @@ impl Checkpoint { } /// The genesis block of `network`, alone. - pub fn genesis(network: Network) -> Self { + pub(crate) fn genesis(network: Network) -> Self { Self { height: 0, headers: vec![genesis_block(network).header.into()], From 0968693e96dc8dd8b19fe808e29d7b104920d78d Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 9 Nov 2026 05:17:05 -0800 Subject: [PATCH 17/20] perf(dash-spv): sync block headers below in parallel The backfill below the stored headers synced one checkpoint segment at a time, and each step emptied the pipeline, so `BlockHeadersManager` went back to `Synced` and emitted `BlockHeaderSyncComplete` between steps. `extend_down` now creates every segment down to the floor at once, the pipeline downloads them in parallel within `ACTIVE_SEGMENT_WINDOW` and stores them from the highest down. Completion only depends on the sync to the tip, and the backfill reports its progress through `missing_below`. --- dash-spv/src/sync/block_headers/manager.rs | 68 +++++++++++++------ dash-spv/src/sync/block_headers/pipeline.rs | 60 ++++++++++------ .../src/sync/block_headers/sync_manager.rs | 2 + 3 files changed, 88 insertions(+), 42 deletions(-) diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index fa1da8ba2..b9572584d 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -117,8 +117,9 @@ impl BlockHeadersManager { /// Sync the headers below the lowest stored one, down to [`Self::floor`]. /// - /// Each step starts at the checkpoint below the lowest stored header, or at genesis, - /// and syncs up to that header. It waits until the pipeline runs. + /// Splits the range at the checkpoints below the lowest stored header, down to the + /// one that reaches the floor or genesis, and downloads the segments in parallel. + /// It waits until the pipeline runs. pub(super) async fn extend_down(&mut self) -> SyncResult<()> { if self.pipeline.is_syncing_below() || !self.pipeline.is_initialized() { return Ok(()); @@ -133,7 +134,7 @@ impl BlockHeadersManager { return Ok(()); }; self.progress.update_missing_below(start - floor); - let join = storage + let mut join = storage .get_header(start) .await? .ok_or_else(|| SyncError::MissingDependency(format!("no header at {start}")))? @@ -141,14 +142,28 @@ impl BlockHeadersManager { .prev_blockhash; drop(storage); - let anchor = self.anchor_below(start); - if anchor.height() + 1 == start { - return self.store_below(start, &[]).await; + let mut end = start; + loop { + let anchor = self.anchor_below(end); + self.pipeline.sync_below(anchor.height(), *anchor.hash(), end - 1, join); + if anchor.start_height() <= floor { + tracing::info!( + "Syncing headers {}..{} below the stored ones", + anchor.height() + 1, + start + ); + return Ok(()); + } + end = anchor.start_height(); + join = anchor.headers().first().map(|first| first.header().prev_blockhash).ok_or_else( + || { + SyncError::InvalidState(format!( + "checkpoint {} has no headers", + anchor.height() + )) + }, + )?; } - tracing::info!("Syncing headers {}..{} below the stored ones", anchor.height() + 1, start); - self.pipeline.sync_below(anchor.height(), *anchor.hash(), start - 1, join); - self.progress.set_state(SyncState::Syncing); - Ok(()) } /// The checkpoint below `start`, or genesis. @@ -180,6 +195,9 @@ impl BlockHeadersManager { return Err(SyncError::Validation(format!("headers below {start} do not join it"))); } storage.store_headers_at_height(&headers, anchor.start_height()).await?; + if let Some(floor) = self.floor { + self.progress.update_missing_below(anchor.start_height().saturating_sub(floor)); + } tracing::info!("Headers synced down to {}", anchor.start_height()); Ok(()) } @@ -280,6 +298,7 @@ impl BlockHeadersManager { } events.extend(self.store_ready_batches(ready_batches).await?); + self.pipeline.send_below(network).await; // After storing unsolicited post-sync headers, mark the tip complete so the next header goes through // the clean reset path. Don't mark complete during active catch-up. @@ -396,15 +415,25 @@ impl BlockHeadersManager { // Last, as the batches above already left the pipeline and a failure // here would otherwise drop them. - if let Some(below) = self.pipeline.take_below() { + self.store_completed_below().await?; + + Ok(events) + } + + /// Store the segments below that finished downloading, from the highest down. + pub(super) async fn store_completed_below(&mut self) -> SyncResult<()> { + while let Some(below) = self.pipeline.take_below() { let start = self.header_storage.read().await.get_start_height().await; let start = start.ok_or_else(|| { SyncError::MissingDependency("no headers stored to sync below".to_string()) })?; - self.store_below(start, &below).await?; + if let Err(e) = self.store_below(start, &below).await { + // `extend_down` starts the segments again only once none is left. + self.pipeline.clear_below(); + return Err(e); + } } - - Ok(events) + Ok(()) } /// Close out an initial sync whose pipeline has nothing left to download. @@ -723,8 +752,8 @@ mod tests { assert_eq!(manager.tip().await.unwrap().height(), tip.height() + 2); } - /// Syncs down one checkpoint at a time: an adjacent one needs no download, - /// a distant one does, and it stops once it reaches the floor, not genesis. + /// Syncs every checkpoint segment down to the floor at once: one adjacent to its + /// checkpoint needs no download, a distant one does, and it stops at the floor, not genesis. #[tokio::test] async fn test_extend_down_descends_checkpoints_to_the_floor() { let chain: Vec = Header::dummy_chain(130, BlockHash::dummy(1)) @@ -747,13 +776,12 @@ mod tests { manager.floor = Some(30); manager.extend_down().await.unwrap(); - assert!(!manager.pipeline.is_syncing_below()); + manager.store_completed_below().await.unwrap(); + assert!(manager.pipeline.is_syncing_below()); assert_eq!(headers.read().await.get_start_height().await, Some(75)); - manager.extend_down().await.unwrap(); - assert!(manager.pipeline.is_syncing_below()); manager.pipeline.receive_headers(&chain[50..75]).unwrap(); - manager.store_ready_batches(Vec::new()).await.unwrap(); + manager.store_completed_below().await.unwrap(); assert!(!manager.pipeline.is_syncing_below()); assert_eq!(headers.read().await.get_start_height().await, Some(25)); diff --git a/dash-spv/src/sync/block_headers/pipeline.rs b/dash-spv/src/sync/block_headers/pipeline.rs index aee972534..f01085c80 100644 --- a/dash-spv/src/sync/block_headers/pipeline.rs +++ b/dash-spv/src/sync/block_headers/pipeline.rs @@ -32,8 +32,9 @@ pub struct HeadersPipeline { checkpoint_manager: &'static CheckpointManager, /// Whether the pipeline has been initialized. initialized: bool, - /// Segment syncing below the stored headers, stored whole once complete. - below: Option, + /// Segments syncing below the stored headers, highest first, each stored whole + /// once it and the ones above it are. + below: Vec, } impl std::fmt::Debug for HeadersPipeline { @@ -54,7 +55,7 @@ impl HeadersPipeline { next_to_store: 0, checkpoint_manager, initialized: false, - below: None, + below: Vec::new(), } } @@ -63,7 +64,7 @@ impl HeadersPipeline { self.segments.clear(); self.next_to_store = 0; self.initialized = true; - self.below = None; + self.below.clear(); // Find checkpoints between current_height and target_height let mut boundaries: Vec<(u32, BlockHash)> = Vec::new(); @@ -115,8 +116,8 @@ impl HeadersPipeline { ); } - /// Download `(start_height, end_height]` below the stored headers, the - /// block at `end_height` being `end_hash`. + /// Download `(start_height, end_height]` below the stored headers and the segments + /// already added, the block at `end_height` being `end_hash`. pub(super) fn sync_below( &mut self, start_height: u32, @@ -124,23 +125,42 @@ impl HeadersPipeline { end_height: u32, end_hash: BlockHash, ) { - self.below = Some(SegmentState::new( - self.segments.len(), + let mut segment = SegmentState::new( + self.segments.len() + self.below.len(), start_height, start_hash, Some(end_height), Some(end_hash), - )); + ); + segment.complete = start_height == end_height; + self.below.push(segment); } /// Whether a [`Self::sync_below`] segment is still to be stored. pub(super) fn is_syncing_below(&self) -> bool { - self.below.is_some() + !self.below.is_empty() } - /// Headers of the [`Self::sync_below`] segment, once complete. + /// Headers of the highest [`Self::sync_below`] segment, once complete. pub(super) fn take_below(&mut self) -> Option> { - self.below.take_if(|below| below.complete).map(|mut below| below.take_buffered()) + if !self.below.first()?.complete { + return None; + } + Some(self.below.remove(0).buffered_headers) + } + + /// Drop the [`Self::sync_below`] segments, to sync below again from scratch. + pub(super) fn clear_below(&mut self) { + self.below.clear(); + } + + /// Declare the `getheaders` of the highest [`Self::sync_below`] segments still downloading. + pub(super) async fn send_below(&mut self, network: &Arc) { + for below in + self.below.iter_mut().take(ACTIVE_SEGMENT_WINDOW).filter(|below| below.can_send()) + { + below.send_request(network).await; + } } /// Get the number of segments in the pipeline. @@ -162,10 +182,6 @@ impl HeadersPipeline { sent += 1; } } - if let Some(below) = self.below.as_mut().filter(|below| below.can_send()) { - below.send_request(network).await; - sent += 1; - } Ok(sent) } @@ -194,7 +210,7 @@ impl HeadersPipeline { let prev_hash = headers[0].header().prev_blockhash; if let Some(below) = - self.below.as_mut().filter(|below| !below.complete && below.matches(&prev_hash)) + self.below.iter_mut().find(|below| !below.complete && below.matches(&prev_hash)) { below.receive_headers(headers)?; return Ok(Some(below.segment_id)); @@ -290,15 +306,15 @@ impl HeadersPipeline { ready } - /// Check if all segments are complete. + /// Whether all segments above the stored headers are complete. The segments below + /// do not count, so syncing below never holds back the sync to the tip. pub fn is_complete(&self) -> bool { - self.below.is_none() - && self.segments.iter().all(|s| s.complete && s.buffered_headers.is_empty()) + self.segments.iter().all(|s| s.complete && s.buffered_headers.is_empty()) } /// Get the total number of buffered headers across all segments. pub fn total_buffered(&self) -> u32 { - self.segments.iter().map(|s| s.buffered_headers.len() as u32).sum() + self.segments.iter().chain(&self.below).map(|s| s.buffered_headers.len() as u32).sum() } /// Locator of the non-complete tip segment, used to key an empty `headers` response. @@ -337,7 +353,7 @@ impl HeadersPipeline { /// Treats every segment's next request as new, for a sync that starts again after /// losing its peers, when queued requests may have been dropped. pub(super) fn forget_declared(&mut self) { - for segment in &mut self.segments { + for segment in self.segments.iter_mut().chain(&mut self.below) { segment.forget_declared(); } } diff --git a/dash-spv/src/sync/block_headers/sync_manager.rs b/dash-spv/src/sync/block_headers/sync_manager.rs index 60d8ed9b6..8efb16ab7 100644 --- a/dash-spv/src/sync/block_headers/sync_manager.rs +++ b/dash-spv/src/sync/block_headers/sync_manager.rs @@ -149,6 +149,8 @@ impl SyncManager for BlockHeadersMana if !self.pipeline.is_initialized() { return Ok(vec![]); } + self.store_completed_below().await?; + self.pipeline.send_below(network).await; if self.state() == SyncState::Syncing { // Take, refill, then store — the same order `handle_headers_pipeline` From 5f2ff37f3ce2d445b8cd4bace4a04dd90d6410db Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 9 Nov 2026 05:17:06 -0800 Subject: [PATCH 18/20] perf(dash-spv): sync filter headers below in parallel `FilterHeadersManager` requested one batch below the stored filter headers at a time and waited for the next tick to request the next one. `FilterHeadersPipeline` now queues every batch down to the lowest block header, requests them together with the batches above and stores them from the highest down. Each batch keeps the start it was queued with, so a lower block header start no longer makes a request that is rejected on arrival. --- dash-spv/src/sync/filter_headers/manager.rs | 94 +++++++++---------- dash-spv/src/sync/filter_headers/pipeline.rs | 63 ++++++++++++- .../src/sync/filter_headers/sync_manager.rs | 10 +- 3 files changed, 110 insertions(+), 57 deletions(-) diff --git a/dash-spv/src/sync/filter_headers/manager.rs b/dash-spv/src/sync/filter_headers/manager.rs index 3c6442b6c..229f7da03 100644 --- a/dash-spv/src/sync/filter_headers/manager.rs +++ b/dash-spv/src/sync/filter_headers/manager.rs @@ -5,13 +5,12 @@ use std::sync::Arc; -use dashcore::network::message_filter::{CFHeaders, GetCFHeaders}; -use dashcore::BlockHash; +use dashcore::network::message_filter::CFHeaders; use tokio::sync::RwLock; -use super::pipeline::{FilterHeadersPipeline, FILTER_HEADERS_BATCH_SIZE}; +use super::pipeline::FilterHeadersPipeline; use crate::error::{SyncError, SyncResult}; -use crate::network::{NetworkManager, SendRequest}; +use crate::network::NetworkManager; use crate::storage::{BlockHeaderStorage, FilterHeaderStorage}; use crate::sync::filter_headers::util::compute_filter_headers; use crate::sync::progress::ProgressPercentage; @@ -41,8 +40,6 @@ pub struct FilterHeadersManager /// Whether block header sync has completed. Gates FilterHeadersSyncComplete emission /// to ensure it never fires before BlockHeaderSyncComplete. pub(super) block_headers_synced: bool, - /// Start and stop hash of the batch requested below the stored filter headers. - pub(super) lower_batch: Option<(u32, BlockHash)>, } impl FilterHeadersManager { @@ -105,7 +102,6 @@ impl FilterHeadersManager pipeline: FilterHeadersPipeline::default(), checkpoint_start_height: None, block_headers_synced: false, - lower_batch: None, }) } @@ -189,13 +185,9 @@ impl FilterHeadersManager Ok(count) } - /// Request the batch ending at the lowest stored filter header while block - /// headers reach below it. Each batch is checked against the stored header - /// it ends at, so the range fills downwards without gaps. - pub(super) async fn extend_down( - &mut self, - network: &Arc, - ) -> SyncResult<()> { + /// Queue the batches below the lowest stored filter header while block headers + /// reach below it, which the pipeline downloads in parallel. + pub(super) async fn extend_down(&mut self) -> SyncResult<()> { let header_storage = self.header_storage.read().await; let header_start = header_storage.get_start_height().await; let filter_start = self.filter_header_storage.read().await.get_filter_start_height().await; @@ -207,64 +199,74 @@ impl FilterHeadersManager if end <= header_start.saturating_sub(1) { return Ok(()); } - let start = header_start.max(end.saturating_sub(FILTER_HEADERS_BATCH_SIZE - 1)); - let stop_hash = *header_storage - .get_header(end) - .await? - .ok_or_else(|| SyncError::Storage(format!("Missing header at height {end}")))? - .hash(); + self.pipeline.extend_below(&*header_storage, end, header_start).await?; drop(header_storage); - self.lower_batch = Some((start, stop_hash)); if self.state() == SyncState::Synced { self.set_state(SyncState::Syncing); } - network - .send(GetCFHeaders { - filter_type: 0, - start_height: start, - stop_hash, - }) - .await; Ok(()) } - /// Store a batch [`Self::extend_down`] requested, if it ends at the stored - /// filter header it was requested for. + /// Store the received batches below, from the one ending at the lowest stored + /// filter header down. A batch that does not match the header it ends at is + /// requested again. + pub(super) async fn store_lower_batches(&mut self) -> SyncResult> { + let mut events = Vec::new(); + loop { + let Some(end) = self.filter_header_storage.read().await.get_filter_start_height().await + else { + break; + }; + let Some((start, cfheaders)) = self.pipeline.take_below(end) else { + break; + }; + let Some(stored) = self.store_lower_batch(start, end, &cfheaders).await? else { + self.pipeline.want_below(cfheaders.stop_hash, start, end); + break; + }; + events.push(stored); + } + if events.is_empty() { + return Ok(events); + } + let header_start = self.header_storage.read().await.get_start_height().await.unwrap_or(0); + let filter_start = + self.filter_header_storage.read().await.get_filter_start_height().await.unwrap_or(0); + self.progress + .update_missing_below(filter_start.saturating_sub(header_start.saturating_sub(1))); + events.extend(self.try_complete_sync()); + Ok(events) + } + + /// Store the batch `start..=end` below, if it ends at the stored filter header at `end`. pub(super) async fn store_lower_batch( &mut self, start: u32, + end: u32, cfheaders: &CFHeaders, - ) -> SyncResult> { - self.lower_batch = None; + ) -> SyncResult> { let mut headers = compute_filter_headers(cfheaders); - let end = (start + headers.len() as u32).saturating_sub(1); let mut storage = self.filter_header_storage.write().await; - if headers.is_empty() - || storage.get_filter_start_height().await != Some(end) + if start + headers.len() as u32 != end + 1 || headers.pop() != storage.get_filter_header(end).await? { tracing::warn!( "CFHeaders batch at {} does not end at the stored filter headers", start ); - return Ok(vec![]); + return Ok(None); } if start > 0 { headers.insert(0, cfheaders.previous_filter_header); } let first = start.saturating_sub(1); storage.store_filter_headers_at_height(&headers, first).await?; - drop(storage); - let mut events = vec![SyncEvent::FilterHeadersStored { + Ok(Some(SyncEvent::FilterHeadersStored { start_height: first, end_height: end - 1, tip_height: self.progress.current_height(), - }]; - let header_start = self.header_storage.read().await.get_start_height().await.unwrap_or(0); - self.progress.update_missing_below(first.saturating_sub(header_start.saturating_sub(1))); - events.extend(self.try_complete_sync()); - Ok(events) + })) } /// Start or resume filter header download. @@ -761,14 +763,12 @@ mod tests { FilterHeadersManager::new(storage.block_headers(), filter_headers.clone()) .await .unwrap(); - manager.lower_batch = Some((1, stop_hash)); let batch = cfheaders(FilterHeader::from_raw_hash(sha256d::Hash::hash(previous)), stop_hash, count); - let events = manager.store_lower_batch(1, &batch).await.unwrap(); + let stored = manager.store_lower_batch(1, 2000, &batch).await.unwrap(); - assert!(events.is_empty()); - assert_eq!(manager.lower_batch, None); + assert!(stored.is_none()); assert_eq!(filter_headers.read().await.get_filter_start_height().await, Some(2000)); } diff --git a/dash-spv/src/sync/filter_headers/pipeline.rs b/dash-spv/src/sync/filter_headers/pipeline.rs index f8fd6711e..be3162ffa 100644 --- a/dash-spv/src/sync/filter_headers/pipeline.rs +++ b/dash-spv/src/sync/filter_headers/pipeline.rs @@ -28,6 +28,13 @@ pub(super) struct FilterHeadersPipeline { next_expected: u32, /// Target height for sync. target_height: u32, + /// Wanted batches below the stored filter headers (stop_hash -> (start_height, end_height)). + below_batches: HashMap, + /// Received batches below (end_height -> (start_height, data)), kept until the stored + /// filter headers reach down to their end. + below_buffered: HashMap, + /// End height of the next batch to queue below. + below_end: Option, } impl Default for FilterHeadersPipeline { @@ -45,9 +52,54 @@ impl FilterHeadersPipeline { buffered: HashMap::new(), next_expected: 0, target_height: 0, + below_batches: HashMap::new(), + below_buffered: HashMap::new(), + below_end: None, } } + /// Queue the batches below the stored filter headers, from the one ending at `top`, + /// or below the ones queued already, down to the one starting at `lowest`. + pub(super) async fn extend_below( + &mut self, + storage: &impl BlockHeaderStorage, + top: u32, + lowest: u32, + ) -> SyncResult<()> { + let mut end = self.below_end.unwrap_or(top); + while end > lowest.saturating_sub(1) { + let start = lowest.max(end.saturating_sub(FILTER_HEADERS_BATCH_SIZE - 1)); + let stop_hash = + storage.get_header(end).await?.map(|h| *h.hash()).ok_or_else(|| { + SyncError::Storage(format!("Missing header at height {}", end)) + })?; + self.want_below(stop_hash, start, end); + end = start.saturating_sub(1); + } + self.below_end = Some(end); + Ok(()) + } + + /// Buffer `data` if it answers a wanted batch below. Returns whether it does. + pub(super) fn receive_below(&mut self, data: &CFHeaders) -> bool { + let Some((start, end)) = self.below_batches.remove(&data.stop_hash) else { + return false; + }; + self.below_buffered.insert(end, (start, data.clone())); + true + } + + /// Start height and data of the received batch below that ends at `end`. + pub(super) fn take_below(&mut self, end: u32) -> Option<(u32, CFHeaders)> { + self.below_buffered.remove(&end) + } + + /// Want the batch `start..=end` below the stored filter headers, whose block at `end` is `stop_hash`. + pub(super) fn want_below(&mut self, stop_hash: BlockHash, start: u32, end: u32) { + self.below_batches.insert(stop_hash, (start, end)); + self.undeclared = true; + } + /// Extend the pipeline to a new target height. /// /// Queues additional batches from the current target to the new target. @@ -150,13 +202,16 @@ impl FilterHeadersPipeline { &mut self, network: &Arc, ) -> SyncResult { - if self.batch_starts.is_empty() { + let batches: Vec<(BlockHash, u32)> = self + .batch_starts + .iter() + .map(|(stop_hash, start)| (*stop_hash, *start)) + .chain(self.below_batches.iter().map(|(stop_hash, (start, _))| (*stop_hash, *start))) + .collect(); + if batches.is_empty() { return Ok(0); } - let batches: Vec<(BlockHash, u32)> = - self.batch_starts.iter().map(|(stop_hash, start)| (*stop_hash, *start)).collect(); - for (stop_hash, start_height) in &batches { network .send(GetCFHeaders { diff --git a/dash-spv/src/sync/filter_headers/sync_manager.rs b/dash-spv/src/sync/filter_headers/sync_manager.rs index d95795dd7..aaa12346c 100644 --- a/dash-spv/src/sync/filter_headers/sync_manager.rs +++ b/dash-spv/src/sync/filter_headers/sync_manager.rs @@ -47,11 +47,9 @@ impl SyncManager for FilterHeade network: &Arc, ) -> SyncResult> { if let NetworkMessage::CFHeaders(cfheaders) = &*msg { - if let Some((start, stop_hash)) = - self.lower_batch.filter(|(_, stop_hash)| *stop_hash == cfheaders.stop_hash) - { - network.release_request(RequestKey::CfHeaders(stop_hash)).await; - return self.store_lower_batch(start, cfheaders).await; + if self.pipeline.receive_below(cfheaders) { + network.release_request(RequestKey::CfHeaders(cfheaders.stop_hash)).await; + return self.store_lower_batches().await; } } @@ -151,7 +149,7 @@ impl SyncManager for FilterHeade } async fn tick(&mut self, network: &Arc) -> SyncResult> { - self.extend_down(network).await?; + self.extend_down().await?; self.pipeline.send_pending(network).await?; // Re-read the block-header tip and extend from here if it moved. From feda9ed0e96b4acc84d853db373141bcbaee3243 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 9 Nov 2026 05:19:15 -0800 Subject: [PATCH 19/20] fix(dash-spv): keep forward header events when storing below fails A failed `store_below` made `store_ready_batches` return an error after storing the forward batches, so their `BlockHeadersStored` events were dropped and the masternode and ChainLock managers waited for the next block. The backfill error is now logged and the events are returned. The segments below are dropped and `extend_down` starts them again. --- dash-spv/src/sync/block_headers/manager.rs | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index b9572584d..b660d1ebf 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -413,9 +413,11 @@ impl BlockHeadersManager { } } - // Last, as the batches above already left the pipeline and a failure - // here would otherwise drop them. - self.store_completed_below().await?; + // Last, and without failing, as the batches above already left the pipeline + // and their events would otherwise be dropped. + if let Err(e) = self.store_completed_below().await { + tracing::warn!("Failed to store the headers synced below: {}", e); + } Ok(events) } @@ -711,8 +713,8 @@ mod tests { } /// Headers below the stored ones that fail to store must not take the - /// forward batches stored alongside them down too: those already left the - /// pipeline, so nothing would download them again. + /// forward batches stored alongside them down too, nor their events: those + /// already left the pipeline, so nothing would download them again. #[tokio::test] async fn test_failed_store_below_keeps_forward_batches() { let storage = DiskStorageManager::with_temp_dir().await.unwrap(); @@ -746,7 +748,13 @@ mod tests { let ready = manager.pipeline.take_ready_to_store(); assert!(!ready.is_empty(), "precondition: the forward batch is ready"); - assert!(manager.store_ready_batches(ready).await.is_err()); + let events = manager.store_ready_batches(ready).await.unwrap(); + + let stored_tip = tip.height() + 2; + assert!(matches!( + events.as_slice(), + [SyncEvent::BlockHeadersStored { tip_height }] if *tip_height == stored_tip + )); assert!(!manager.pipeline.is_syncing_below()); assert_eq!(manager.tip().await.unwrap().height(), tip.height() + 2); From c71dc6a4812ef633992c94e2d37be9d6dc34e500 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 9 Nov 2026 05:23:46 -0800 Subject: [PATCH 20/20] docs(dash-spv): note the one-header genesis checkpoint The checkpoint docs said every checkpoint holds `CHECKPOINT_HEADERS` headers, but `Checkpoint::genesis` holds one. They now name genesis as the exception, which is never encoded since decoding always reads `CHECKPOINT_HEADERS` headers. --- dash-spv/src/chain/checkpoints.rs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/dash-spv/src/chain/checkpoints.rs b/dash-spv/src/chain/checkpoints.rs index c9c0cf01c..be94b2663 100644 --- a/dash-spv/src/chain/checkpoints.rs +++ b/dash-spv/src/chain/checkpoints.rs @@ -2,7 +2,9 @@ //! //! Each checkpoint holds its block header and the [`CHECKPOINT_HEADERS`] - 1 headers before //! it, so the difficulty of the blocks after it can be checked from the first one on. The -//! checkpoints of mainnet and testnet are generated from the network by the +//! genesis checkpoint is the exception: it holds only the genesis header and is never +//! encoded, as decoding always reads [`CHECKPOINT_HEADERS`] headers. The checkpoints of +//! mainnet and testnet are generated from the network by the //! `generate-checkpoints` binary into `checkpoints/.json`, which `build.rs` encodes //! for embedding. @@ -17,7 +19,7 @@ use dashcore::{BlockHash, Network}; use crate::types::HashedBlockHeader; -/// Headers each checkpoint holds, the checkpoint block last. +/// Headers each checkpoint but genesis holds, the checkpoint block last. pub const CHECKPOINT_HEADERS: usize = 25; const MAINNET_CHECKPOINTS: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/mainnet.checkpoints")); @@ -38,7 +40,7 @@ static NO_CHECKPOINTS: CheckpointManager = CheckpointManager { checkpoints: BTreeMap::new(), }; -/// A known block and the [`CHECKPOINT_HEADERS`] - 1 headers before it. +/// A known block and the [`CHECKPOINT_HEADERS`] - 1 headers before it, or the genesis block alone. #[derive(Debug, Clone)] pub struct Checkpoint { height: u32,