refactor(key-wallet-manager): track wallet heights per wallet (#689)

* refactor(key-wallet-manager): track wallet heights per wallet

Move committed sync height into wallet metadata and expose it through `WalletInfoInterface` so `WalletManager` no longer relies on global cached heights.

Compute manager-level synced_height and tip_height as the minimum across wallet infos, propagate committed sync updates per wallet, and keep tip_height as per-wallet applied chain state.

Update tests and example messaging to match the new aggregation semantics.

* enforce `Send + Sync + 'static` on generic type of the wallet manager

Author: xdustinface

key-wallet-ffi/src/wallet_manager_tests.rs

@@ -442,7 +442,7 @@ mod tests {
         let height = unsafe { wallet_manager::wallet_manager_current_height(manager, error) };
         assert_eq!(height, 0);
 
-        // Update height
+        // Updating last-processed height without wallets is a no-op
         let new_height = 12345;
         unsafe {
             let manager_ref = &*manager;
@@ -455,7 +455,7 @@ mod tests {
         // Get updated height
         let current_height =
             unsafe { wallet_manager::wallet_manager_current_height(manager, error) };
-        assert_eq!(current_height, new_height);
+        assert_eq!(current_height, 0);
 
         // Clean up
         unsafe {

key-wallet-manager/examples/wallet_creation.rs

@@ -142,11 +142,11 @@ fn main() {
     // Example 7: Block height tracking
     println!("\n7. Block height tracking...");
 
-    println!("   Current height (Testnet): {:?}", manager.last_processed_height());
+    println!("   Current last-processed height (Testnet): {:?}", manager.last_processed_height());
 
-    // Update height
+    // Update last-processed height across all managed wallets
     manager.update_last_processed_height(850_000);
-    println!("   Updated height to: {:?}", manager.last_processed_height());
+    println!("   Updated last-processed height to: {:?}", manager.last_processed_height());
 
     println!("\n=== Summary ===");
     println!("Total wallets created: {}", manager.wallet_count());

key-wallet-manager/src/accessors.rs

@@ -9,7 +9,7 @@ use key_wallet::{Account, Address, Network, Utxo, Wallet};
 use std::collections::{BTreeMap, BTreeSet};
 use tokio::sync::broadcast;
 
-impl<T: WalletInfoInterface> WalletManager<T> {
+impl<T: WalletInfoInterface + Send + Sync + 'static> WalletManager<T> {
     /// Get a wallet by ID
     pub fn get_wallet(&self, wallet_id: &WalletId) -> Option<&Wallet> {
         self.wallets.get(wallet_id)

key-wallet-manager/src/lib.rs

@@ -87,13 +87,9 @@ pub struct CheckTransactionsResult {
 /// Each wallet can contain multiple accounts following BIP44 standard.
 /// This is the main entry point for wallet operations.
 #[derive(Debug)]
-pub struct WalletManager<T: WalletInfoInterface = ManagedWalletInfo> {
+pub struct WalletManager<T: WalletInfoInterface + Send + Sync + 'static = ManagedWalletInfo> {
     /// Network the managed wallets are used for
     network: Network,
-    /// Last fully processed block height.
-    last_processed_height: CoreBlockHeight,
-    /// Height at which filter scanning was last committed.
-    synced_height: CoreBlockHeight,
     /// Immutable wallets indexed by wallet ID
     wallets: BTreeMap<WalletId, Wallet>,
     /// Mutable wallet info indexed by wallet ID
@@ -106,13 +102,11 @@ pub struct WalletManager<T: WalletInfoInterface = ManagedWalletInfo> {
     event_sender: broadcast::Sender<WalletEvent>,
 }
 
-impl<T: WalletInfoInterface> WalletManager<T> {
+impl<T: WalletInfoInterface + Send + Sync + 'static> WalletManager<T> {
     /// Create a new wallet manager
     pub fn new(network: Network) -> Self {
         Self {
             network,
-            last_processed_height: 0,
-            synced_height: 0,
             wallets: BTreeMap::new(),
             wallet_infos: BTreeMap::new(),
             structural_revision: 0,
@@ -304,7 +298,7 @@ impl<T: WalletInfoInterface> WalletManager<T> {
 
         // Create managed wallet info
         let mut managed_info = T::from_wallet(&wallet);
-        managed_info.set_birth_height(self.last_processed_height);
+        managed_info.set_birth_height(self.last_processed_height());
         managed_info.set_first_loaded_at(current_timestamp());
 
         self.wallets.insert(wallet_id, wallet);
@@ -345,7 +339,7 @@ impl<T: WalletInfoInterface> WalletManager<T> {
 
         // Create managed wallet info
         let mut managed_info = T::from_wallet(&wallet);
-        managed_info.set_birth_height(self.last_processed_height);
+        managed_info.set_birth_height(self.last_processed_height());
         managed_info.set_first_loaded_at(current_timestamp());
 
         self.wallets.insert(wallet_id, wallet);
@@ -393,7 +387,7 @@ impl<T: WalletInfoInterface> WalletManager<T> {
 
         // Create managed wallet info
         let mut managed_info = T::from_wallet(&wallet);
-        managed_info.set_birth_height(self.last_processed_height);
+        managed_info.set_birth_height(self.last_processed_height());
         managed_info.set_first_loaded_at(current_timestamp());
 
         self.wallets.insert(wallet_id, wallet);
@@ -438,7 +432,7 @@ impl<T: WalletInfoInterface> WalletManager<T> {
         let mut managed_info = T::from_wallet(&wallet);
 
         // Use the current height as the birth height since we don't know when it was originally created
-        managed_info.set_birth_height(self.last_processed_height);
+        managed_info.set_birth_height(self.last_processed_height());
         managed_info.set_first_loaded_at(current_timestamp());
 
         self.wallets.insert(wallet_id, wallet);

key-wallet-manager/src/process_block.rs

@@ -98,12 +98,10 @@ impl<T: WalletInfoInterface + Send + Sync + 'static> WalletInterface for WalletM
     }
 
     fn last_processed_height(&self) -> CoreBlockHeight {
-        self.last_processed_height
+        self.wallet_infos.values().map(|info| info.last_processed_height()).max().unwrap_or(0)
     }
 
     fn update_last_processed_height(&mut self, height: CoreBlockHeight) {
-        self.last_processed_height = height;
-
         let snapshot = self.snapshot_balances();
 
         for (_wallet_id, info) in self.wallet_infos.iter_mut() {
@@ -114,13 +112,12 @@ impl<T: WalletInfoInterface + Send + Sync + 'static> WalletInterface for WalletM
     }
 
     fn synced_height(&self) -> CoreBlockHeight {
-        self.synced_height
+        self.wallet_infos.values().map(|info| info.synced_height()).min().unwrap_or(0)
     }
 
     fn update_synced_height(&mut self, height: CoreBlockHeight) {
-        self.synced_height = height;
-        if height > self.last_processed_height {
-            self.update_last_processed_height(height);
+        for (_wallet_id, info) in self.wallet_infos.iter_mut() {
+            info.update_synced_height(height);
         }
     }
 
@@ -220,15 +217,14 @@ mod tests {
         let mut manager: WalletManager<ManagedWalletInfo> = WalletManager::new(Network::Testnet);
         // Initial state
         assert_eq!(manager.last_processed_height(), 0);
-        // Increase last processed height
+        // Updating last-processed height without wallets is a no-op
         manager.update_last_processed_height(1000);
-        assert_eq!(manager.last_processed_height(), 1000);
-        // Increase last processed height again
+        assert_eq!(manager.last_processed_height(), 0);
+        // Still a no-op without wallets
         manager.update_last_processed_height(5000);
-        assert_eq!(manager.last_processed_height(), 5000);
-        // Decrease last processed height
+        assert_eq!(manager.last_processed_height(), 0);
         manager.update_last_processed_height(10);
-        assert_eq!(manager.last_processed_height(), 10);
+        assert_eq!(manager.last_processed_height(), 0);
     }
 
     #[tokio::test]

key-wallet-manager/tests/integration_test.rs

@@ -164,10 +164,13 @@ fn test_block_height_tracking() {
 
     // Initial state
     assert_eq!(manager.last_processed_height(), 0);
+    assert_eq!(manager.synced_height(), 0);
 
-    // Set height before adding wallets
+    // Updating heights before adding wallets is a no-op
     manager.update_last_processed_height(1000);
-    assert_eq!(manager.last_processed_height(), 1000);
+    manager.update_synced_height(500);
+    assert_eq!(manager.last_processed_height(), 0);
+    assert_eq!(manager.synced_height(), 0);
 
     let mnemonic1 = Mnemonic::generate(12, Language::English).unwrap();
     let wallet_id1 = manager
@@ -191,46 +194,53 @@ fn test_block_height_tracking() {
 
     assert_eq!(manager.wallet_count(), 2);
 
-    // Verify both wallets have last_processed_height of 0 initially
+    // Verify both wallets have last_processed_height and synced_height of 0 initially
     for wallet_info in manager.get_all_wallet_infos().values() {
         assert_eq!(wallet_info.last_processed_height(), 0);
+        assert_eq!(wallet_info.synced_height(), 0);
     }
 
-    // Update height - should propagate to all wallets
+    // Update last-processed height - should propagate to all wallets
     manager.update_last_processed_height(12345);
     assert_eq!(manager.last_processed_height(), 12345);
 
-    // Verify all wallets got updated
+    // Verify all wallets got updated while synced_height stays at 0
     let wallet_info1 = manager.get_wallet_info(&wallet_id1).unwrap();
     let wallet_info2 = manager.get_wallet_info(&wallet_id2).unwrap();
     assert_eq!(wallet_info1.last_processed_height(), 12345);
     assert_eq!(wallet_info2.last_processed_height(), 12345);
+    assert_eq!(wallet_info1.synced_height(), 0);
+    assert_eq!(wallet_info2.synced_height(), 0);
 
-    // Update again - verify subsequent updates work
-    manager.update_last_processed_height(20000);
-    assert_eq!(manager.last_processed_height(), 20000);
+    // Update synced height - should propagate to all wallets without touching last_processed_height
+    manager.update_synced_height(20000);
+    assert_eq!(manager.synced_height(), 20000);
 
     for wallet_info in manager.get_all_wallet_infos().values() {
-        assert_eq!(wallet_info.last_processed_height(), 20000);
+        assert_eq!(wallet_info.last_processed_height(), 12345);
+        assert_eq!(wallet_info.synced_height(), 20000);
     }
 
-    // Update wallets individually to different heights
+    // Update wallets individually to different last-processed heights
     let wallet_info1 = manager.get_wallet_info_mut(&wallet_id1).unwrap();
     wallet_info1.update_last_processed_height(30000);
 
     let wallet_info2 = manager.get_wallet_info_mut(&wallet_id2).unwrap();
     wallet_info2.update_last_processed_height(25000);
 
-    // Verify each wallet has its own last_processed_height
+    // Verify each wallet has its own last_processed_height and manager reports the max
     let wallet_info1 = manager.get_wallet_info(&wallet_id1).unwrap();
     let wallet_info2 = manager.get_wallet_info(&wallet_id2).unwrap();
     assert_eq!(wallet_info1.last_processed_height(), 30000);
     assert_eq!(wallet_info2.last_processed_height(), 25000);
+    assert_eq!(manager.last_processed_height(), 30000);
 
-    // Manager update_height still syncs all wallets
-    manager.update_last_processed_height(40000);
+    // Manager synced-height update syncs across all wallets
+    manager.update_synced_height(40000);
     let wallet_info1 = manager.get_wallet_info(&wallet_id1).unwrap();
     let wallet_info2 = manager.get_wallet_info(&wallet_id2).unwrap();
-    assert_eq!(wallet_info1.last_processed_height(), 40000);
-    assert_eq!(wallet_info2.last_processed_height(), 40000);
+    assert_eq!(wallet_info1.last_processed_height(), 30000);
+    assert_eq!(wallet_info2.last_processed_height(), 25000);
+    assert_eq!(wallet_info1.synced_height(), 40000);
+    assert_eq!(wallet_info2.synced_height(), 40000);
 }

key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs

@@ -89,10 +89,16 @@ pub trait WalletInfoInterface: Sized + WalletTransactionChecker + ManagedAccount
     /// Return the last fully processed height of the wallet.
     fn last_processed_height(&self) -> CoreBlockHeight;
 
+    /// Return the durable wallet sync checkpoint height.
+    fn synced_height(&self) -> CoreBlockHeight;
+
     /// Update chain state and process any matured transactions
     /// This should be called when the chain tip advances to a new height
     fn update_last_processed_height(&mut self, current_height: u32);
 
+    /// Record that the durable wallet sync checkpoint has advanced to `current_height`.
+    fn update_synced_height(&mut self, current_height: u32);
+
     /// Mark UTXOs for a transaction as InstantSend-locked across all accounts
     /// and update the corresponding transaction record context.
     /// Returns `true` if any UTXO was newly marked.
@@ -151,6 +157,10 @@ impl WalletInfoInterface for ManagedWalletInfo {
         self.metadata.last_processed_height
     }
 
+    fn synced_height(&self) -> CoreBlockHeight {
+        self.metadata.synced_height
+    }
+
     fn first_loaded_at(&self) -> u64 {
         self.metadata.first_loaded_at
     }
@@ -245,6 +255,10 @@ impl WalletInfoInterface for ManagedWalletInfo {
         self.update_balance();
     }
 
+    fn update_synced_height(&mut self, current_height: u32) {
+        self.metadata.synced_height = current_height;
+    }
+
     fn mark_instant_send_utxos(&mut self, txid: &Txid, lock: &InstantLock) -> bool {
         if !self.instant_send_locks.insert(*txid) {
             return false;

key-wallet/src/wallet/metadata.rs

@@ -18,6 +18,8 @@ pub struct WalletMetadata {
     pub birth_height: CoreBlockHeight,
     /// Last processed block height
     pub last_processed_height: CoreBlockHeight,
+    /// Sync checkpoint height
+    pub synced_height: CoreBlockHeight,
     /// Last sync timestamp
     pub last_synced: Option<u64>,
     /// Total transactions