refactor: introduce ProgressPercentage trait (#431)

- add the `ProgressPercentage` trait
- implement the trait for all progress structs where its relevant
- adjust the default value (target_height == 0) for percentage from 1.0 to 0.0 because its more reasonable.

Author: xdustinface

dash-spv-ffi/include/dash_spv_ffi.h

@@ -59,7 +59,7 @@ typedef struct FFIClientConfig {
  */
 typedef struct FFIBlockHeadersProgress {
   enum FFISyncState state;
-  uint32_t current_height;
+  uint32_t tip_height;
   uint32_t target_height;
   uint32_t processed;
   uint32_t buffered;

dash-spv-ffi/src/bin/ffi_cli.rs

@@ -213,7 +213,7 @@ extern "C" fn on_progress_update(progress: *const FFISyncProgress, _user_data: *
 
     if !p.headers.is_null() {
         let h = unsafe { &*p.headers };
-        print!("headers:{}/{} ", h.current_height + h.buffered, h.target_height);
+        print!("headers:{}/{} ", h.tip_height + h.buffered, h.target_height);
     }
     if !p.filter_headers.is_null() {
         let fh = unsafe { &*p.filter_headers };

dash-spv-ffi/src/types.rs

@@ -1,7 +1,8 @@
 use dash_spv::client::config::MempoolStrategy;
 use dash_spv::sync::{
     BlockHeadersProgress, BlocksProgress, ChainLockProgress, FilterHeadersProgress,
-    FiltersProgress, InstantSendProgress, MasternodesProgress, SyncProgress, SyncState,
+    FiltersProgress, InstantSendProgress, MasternodesProgress, ProgressPercentage, SyncProgress,
+    SyncState,
 };
 use dash_spv::types::MempoolRemovalReason;
 use std::ffi::{CStr, CString};
@@ -76,7 +77,7 @@ impl From<SyncState> for FFISyncState {
 #[derive(Debug, Clone, Default)]
 pub struct FFIBlockHeadersProgress {
     pub state: FFISyncState,
-    pub current_height: u32,
+    pub tip_height: u32,
     pub target_height: u32,
     pub processed: u32,
     pub buffered: u32,
@@ -88,7 +89,7 @@ impl From<&BlockHeadersProgress> for FFIBlockHeadersProgress {
     fn from(progress: &BlockHeadersProgress) -> Self {
         FFIBlockHeadersProgress {
             state: progress.state().into(),
-            current_height: progress.current_height(),
+            tip_height: progress.tip_height(),
             target_height: progress.target_height(),
             processed: progress.processed(),
             buffered: progress.buffered(),

dash-spv-ffi/tests/test_types.rs

@@ -49,7 +49,7 @@ mod tests {
 
         let mut headers = BlockHeadersProgress::default();
         headers.set_state(SyncState::Syncing);
-        headers.update_current_height(100);
+        headers.update_tip_height(100);
         headers.update_target_height(200);
         headers.add_processed(20);
         headers.update_buffered(5);
@@ -116,7 +116,7 @@ mod tests {
         unsafe {
             let headers = &*ffi_progress.headers;
             assert_eq!(headers.state, FFISyncState::Syncing);
-            assert_eq!(headers.current_height, 100);
+            assert_eq!(headers.tip_height, 100);
             assert_eq!(headers.target_height, 200);
             assert_eq!(headers.processed, 20);
             assert_eq!(headers.buffered, 5);

dash-spv-ffi/tests/unit/test_client_lifecycle.rs

@@ -198,7 +198,7 @@ mod tests {
 
             // Basic consistency checks
             assert!(
-                headers.current_height <= filter_headers.target_height
+                headers.tip_height <= filter_headers.target_height
                     || filter_headers.current_height == 0
             );
             // headers_downloaded is u64, always >= 0

dash-spv/src/sync/block_headers/manager.rs

@@ -15,7 +15,7 @@ use crate::error::{SyncError, SyncResult};
 use crate::network::RequestSender;
 use crate::storage::{BlockHeaderStorage, BlockHeaderTip};
 use crate::sync::block_headers::HeadersPipeline;
-use crate::sync::{BlockHeadersProgress, SyncEvent, SyncManager, SyncState};
+use crate::sync::{BlockHeadersProgress, ProgressPercentage, SyncEvent, SyncManager, SyncState};
 use crate::types::HashedBlockHeader;
 use crate::validation::{BlockHeaderValidator, Validator};
 use dashcore::block::Header;
@@ -83,7 +83,7 @@ impl<H: BlockHeaderStorage> BlockHeadersManager<H> {
         let tip = self.tip().await?;
 
         // Update state
-        self.progress.update_current_height(tip.height());
+        self.progress.update_tip_height(tip.height());
         self.progress.add_processed(headers.len() as u32);
 
         Ok(tip)
@@ -243,14 +243,14 @@ mod tests {
     #[tokio::test]
     async fn test_headers_manager_progress() {
         let mut manager = create_test_manager().await;
-        manager.progress.update_current_height(100);
+        manager.progress.update_tip_height(100);
         manager.progress.update_target_height(200);
         manager.progress.add_processed(50);
 
         let progress = manager.progress();
         if let SyncManagerProgress::BlockHeaders(progress) = progress {
             assert_eq!(progress.state(), SyncState::Initializing);
-            assert_eq!(progress.current_height(), 100);
+            assert_eq!(progress.tip_height(), 100);
             assert_eq!(progress.target_height(), 200);
             assert_eq!(progress.processed(), 50);
             assert!(progress.last_activity().elapsed().as_secs() < 1);

dash-spv/src/sync/block_headers/progress.rs

@@ -1,3 +1,4 @@
+use crate::sync::progress::ProgressPercentage;
 use crate::sync::SyncState;
 use std::fmt;
 use std::time::Instant;
@@ -8,7 +9,7 @@ pub struct BlockHeadersProgress {
     /// Current sync state.
     state: SyncState,
     /// The tip height of the block-header storage.
-    current_height: u32,
+    tip_height: u32,
     /// Equals to current_height (blockchain tip) when synced and to the best height of connected peers during initial sync.
     target_height: u32,
     /// Number of block-headers processed (stored) in the current sync session.
@@ -23,7 +24,7 @@ impl Default for BlockHeadersProgress {
     fn default() -> Self {
         Self {
             state: SyncState::default(),
-            current_height: 0,
+            tip_height: 0,
             target_height: 0,
             processed: 0,
             buffered: 0,
@@ -33,35 +34,18 @@ impl Default for BlockHeadersProgress {
 }
 
 impl BlockHeadersProgress {
-    /// Get completion percentage (0.0 to 1.0).
-    /// Includes buffered headers for more accurate progress during parallel sync.
-    pub fn percentage(&self) -> f64 {
-        if self.target_height == 0 {
-            return 1.0;
-        }
-        // Include buffered headers in progress calculation
-        (self.effective_height() as f64 / self.target_height as f64).min(1.0)
-    }
     /// Get the current sync state.
     pub fn state(&self) -> SyncState {
         self.state
     }
     /// Get the current height (last successfully processed height).
-    pub fn current_height(&self) -> u32 {
-        self.current_height
-    }
-    /// Get the target height (the best height of the connected peers)
-    pub fn target_height(&self) -> u32 {
-        self.target_height
+    pub fn tip_height(&self) -> u32 {
+        self.tip_height
     }
     /// Number of block-headers processed (stored) in the current sync session.
     pub fn processed(&self) -> u32 {
         self.processed
     }
-    /// Get the effective height (current_height + buffered).
-    pub fn effective_height(&self) -> u32 {
-        self.current_height + self.buffered
-    }
     /// The last time a block-header was stored to disk or the last manager state change.
     pub fn last_activity(&self) -> Instant {
         self.last_activity
@@ -71,9 +55,9 @@ impl BlockHeadersProgress {
         self.state = state;
         self.bump_last_activity();
     }
-    /// Update the current height (last successfully processed height).
-    pub fn update_current_height(&mut self, height: u32) {
-        self.current_height = height;
+    /// Update the tip height (last successfully processed height).
+    pub fn update_tip_height(&mut self, height: u32) {
+        self.tip_height = height;
         self.bump_last_activity();
     }
     /// Update the target height (the best height of the connected peers).
@@ -110,7 +94,7 @@ impl fmt::Display for BlockHeadersProgress {
             f,
             "{:?} {}/{} ({:.1}%) processed: {}, buffered: {}, last_activity: {}s",
             self.state,
-            self.effective_height(),
+            self.current_height(),
             self.target_height,
             pct,
             self.processed,
@@ -119,3 +103,14 @@ impl fmt::Display for BlockHeadersProgress {
         )
     }
 }
+
+impl ProgressPercentage for BlockHeadersProgress {
+    fn target_height(&self) -> u32 {
+        self.target_height
+    }
+    fn current_height(&self) -> u32 {
+        // Use the effective height here for the progress to show more realistic values since
+        // we download headers in parallel and the tip height is only updated when sequential segments complete.
+        self.tip_height + self.buffered
+    }
+}

dash-spv/src/sync/block_headers/sync_manager.rs

@@ -2,7 +2,8 @@ use crate::error::SyncResult;
 use crate::network::{Message, MessageType, NetworkEvent, RequestSender};
 use crate::storage::BlockHeaderStorage;
 use crate::sync::{
-    BlockHeadersManager, ManagerIdentifier, SyncEvent, SyncManager, SyncManagerProgress, SyncState,
+    BlockHeadersManager, ManagerIdentifier, ProgressPercentage, SyncEvent, SyncManager,
+    SyncManagerProgress, SyncState,
 };
 use crate::SyncError;
 use async_trait::async_trait;
@@ -45,7 +46,7 @@ impl<H: BlockHeaderStorage> SyncManager for BlockHeadersManager<H> {
             .ok_or_else(|| SyncError::MissingDependency("No tip in storage".to_string()))?;
 
         self.progress.set_state(SyncState::WaitingForConnections);
-        self.progress.update_current_height(tip.height());
+        self.progress.update_tip_height(tip.height());
         self.progress.update_target_height(tip.height());
 
         tracing::info!("BlockHeadersManager initialized at height {}", tip.height());
@@ -182,13 +183,13 @@ impl<H: BlockHeaderStorage> SyncManager for BlockHeadersManager<H> {
                 // When already synced but behind peer height, request missing headers
                 if self.state() == SyncState::Synced {
                     if let Some(best_height) = best_height {
-                        if *best_height > self.progress.current_height()
+                        if *best_height > self.progress.tip_height()
                             && !self.pipeline.tip_segment_has_pending_request()
                         {
                             tracing::info!(
                                 "Peer height {} > our height {}, requesting headers to catch up",
                                 best_height,
-                                self.progress.current_height()
+                                self.progress.tip_height()
                             );
                             // Reset tip segment and send requests via pipeline
                             self.pipeline.reset_tip_segment();

dash-spv/src/sync/filter_headers/manager.rs

@@ -13,6 +13,7 @@ use crate::error::SyncResult;
 use crate::network::RequestSender;
 use crate::storage::{BlockHeaderStorage, FilterHeaderStorage};
 use crate::sync::filter_headers::util::compute_filter_headers;
+use crate::sync::progress::ProgressPercentage;
 use crate::sync::{FilterHeadersProgress, SyncEvent, SyncManager, SyncState};
 
 /// Filter headers manager for downloading compact block filter headers.

dash-spv/src/sync/filter_headers/progress.rs

@@ -1,8 +1,8 @@
+use crate::sync::progress::ProgressPercentage;
+use crate::sync::SyncState;
 use std::fmt;
 use std::time::Instant;
 
-use crate::sync::SyncState;
-
 /// Progress for filter-header synchronization.
 #[derive(Debug, Clone, PartialEq)]
 pub struct FilterHeadersProgress {
@@ -34,30 +34,10 @@ impl Default for FilterHeadersProgress {
 }
 
 impl FilterHeadersProgress {
-    /// Get completion percentage (0.0 to 1.0).
-    /// Uses target_height (peer's best height) for accurate progress display.
-    pub fn percentage(&self) -> f64 {
-        if self.target_height == 0 {
-            return 1.0;
-        }
-        (self.current_height as f64 / self.target_height as f64).min(1.0)
-    }
-
     /// Get the current sync state.
     pub fn state(&self) -> SyncState {
         self.state
     }
-
-    /// Get the current height (last successfully processed filter-header height).
-    pub fn current_height(&self) -> u32 {
-        self.current_height
-    }
-
-    /// Get the target height (peer's best height, for progress display).
-    pub fn target_height(&self) -> u32 {
-        self.target_height
-    }
-
     /// Get the block-header tip height (the download limit for filter headers).
     pub fn block_header_tip_height(&self) -> u32 {
         self.block_header_tip_height
@@ -127,3 +107,12 @@ impl fmt::Display for FilterHeadersProgress {
         )
     }
 }
+
+impl ProgressPercentage for FilterHeadersProgress {
+    fn target_height(&self) -> u32 {
+        self.target_height
+    }
+    fn current_height(&self) -> u32 {
+        self.current_height
+    }
+}