From 1e9c8869ea596925ea978cdbbf3e22a0a4488f7b Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Mon, 5 Oct 2026 16:19:23 +0000 Subject: [PATCH 1/7] feat(wallet): drop what the wallet recorded above a fork After a fork, the client truncates its storage at the fork height and syncs the new branch, but the wallets kept everything they recorded from the dropped blocks: their transactions and UTXOs stayed confirmed, and their synced height stayed above the fork, so the filters of the new branch below it were never scanned for them. `WalletInfoInterface::truncate_above` removes the transactions recorded in blocks above the height, with the UTXOs they created, the spends observed in them, and lowers the synced and last-processed heights to it. The coins those transactions spent are unspent again: each funds account keeps the UTXOs removed by spends not yet chainlocked, pruned once the spend is chainlocked, since a fork never goes below a ChainLock and the funding record of a chainlocked transaction is dropped. `WalletInterface::truncate_above` applies it to every wallet and emits a `WalletEvent::ChainTruncated` per wallet with the removed txids and the restored outpoints, so a persister can drop the rows above the fork. The FFI forwards it through `on_chain_truncated`. The client calls it when it handles a fork. Truncating a storage below its start height now drops everything instead of failing. The block storage starts at its first stored block, so a fork right below it made the recovery fail with the client stopped. `test_sync_follows_reorg` replaces a block that pays a coinbase to the wallet and spends a wallet coin: afterwards only the funding coin is left, unspent, and the event names what to drop and restore. Co-Authored-By: Claude Opus 5.5 --- dash-spv-ffi/src/bin/ffi_cli.rs | 25 +++++ dash-spv-ffi/src/callbacks.rs | 82 ++++++++++++++ dash-spv-ffi/tests/dashd_sync/callbacks.rs | 1 + dash-spv/src/client/lifecycle.rs | 7 +- dash-spv/src/storage/block_headers.rs | 2 +- dash-spv/src/storage/blocks.rs | 2 +- dash-spv/src/storage/filter_headers.rs | 2 +- dash-spv/src/storage/filters.rs | 2 +- dash-spv/src/storage/segments.rs | 21 ++-- dash-spv/tests/dashd_sync/helpers.rs | 34 +++++- dash-spv/tests/dashd_sync/tests_fork.rs | 105 ++++++++++++++++-- .../tests/dashd_sync/tests_transaction.rs | 36 +----- key-wallet-manager/src/event_tests.rs | 39 +++++++ key-wallet-manager/src/events.rs | 43 +++++++ key-wallet-manager/src/process_block.rs | 19 ++++ .../src/test_utils/mock_wallet.rs | 14 +++ key-wallet-manager/src/wallet_interface.rs | 6 + .../managed_core_funds_account.rs | 75 ++++++++++++- key-wallet/src/tests/mod.rs | 2 + .../tests/observed_spent_outpoints_tests.rs | 30 +++++ key-wallet/src/tests/truncate_above_tests.rs | 79 +++++++++++++ .../src/wallet/managed_wallet_info/mod.rs | 16 +-- .../wallet_info_interface.rs | 57 ++++++++++ 23 files changed, 624 insertions(+), 75 deletions(-) create mode 100644 key-wallet/src/tests/truncate_above_tests.rs diff --git a/dash-spv-ffi/src/bin/ffi_cli.rs b/dash-spv-ffi/src/bin/ffi_cli.rs index 26cfde573..7812ee9cc 100644 --- a/dash-spv-ffi/src/bin/ffi_cli.rs +++ b/dash-spv-ffi/src/bin/ffi_cli.rs @@ -266,6 +266,30 @@ extern "C" fn on_transactions_swept( ); } +extern "C" fn on_chain_truncated( + wallet_id: *const c_char, + height: u32, + _txids: *const [u8; 32], + txids_count: usize, + _restored_outpoints: *const dash_spv_ffi::FFIOutPoint, + restored_outpoints_count: usize, + balance: *const FFIBalance, + _account_balances: *const dash_spv_ffi::FFIAccountBalance, + _account_balances_count: u32, + _user_data: *mut c_void, +) { + let b = read_balance(balance); + println!( + "[Wallet] Chain truncated: wallet={}..., height={}, removed={}, restored={}, balance[confirmed={}, unconfirmed={}]", + short_wallet(wallet_id), + height, + txids_count, + restored_outpoints_count, + b.confirmed, + b.unconfirmed, + ); +} + extern "C" fn on_transaction_instant_locked( wallet_id: *const c_char, txid: *const [u8; 32], @@ -592,6 +616,7 @@ fn main() { on_block_processed: Some(on_wallet_block_processed), on_sync_height_advanced: Some(on_sync_height_advanced), on_chain_lock_processed: Some(on_wallet_chain_lock_processed), + on_chain_truncated: Some(on_chain_truncated), user_data: ptr::null_mut(), }, error: FFIClientErrorCallback { diff --git a/dash-spv-ffi/src/callbacks.rs b/dash-spv-ffi/src/callbacks.rs index daa30940c..cee81796d 100644 --- a/dash-spv-ffi/src/callbacks.rs +++ b/dash-spv-ffi/src/callbacks.rs @@ -827,6 +827,34 @@ pub type OnTransactionsSweptCallback = Option< ), >; +/// Callback for `WalletEvent::ChainTruncated`. +/// +/// Fires once per wallet when a fork replaced the chain above `height` and the +/// wallet dropped what it recorded from the blocks above it. A consumer +/// mirroring wallet state to disk must delete the `txids_count` transactions +/// at `txids` with any UTXO they created, mark the `restored_outpoints_count` +/// coins at `restored_outpoints` unspent, and lower its synced height to +/// `height`. `txids` and `restored_outpoints` are null when their count is 0. +/// +/// All pointer parameters are borrowed and only valid for the duration of the +/// callback. `balance` is the wallet's balance *after* the truncation; +/// `account_balances` follows the same contract as on +/// [`OnTransactionDetectedCallback`]. +pub type OnChainTruncatedCallback = Option< + extern "C" fn( + wallet_id: *const c_char, + height: u32, + txids: *const [u8; 32], + txids_count: usize, + restored_outpoints: *const FFIOutPoint, + restored_outpoints_count: usize, + balance: *const FFIBalance, + account_balances: *const FFIAccountBalance, + account_balances_count: u32, + user_data: *mut c_void, + ), +>; + /// Callback for `WalletEvent::TransactionInstantLocked`. /// /// Fires when an InstantSend lock is applied to a previously-seen off-chain @@ -988,6 +1016,7 @@ pub struct FFIWalletEventCallbacks { pub on_block_processed: OnWalletBlockProcessedCallback, pub on_sync_height_advanced: OnSyncHeightAdvancedCallback, pub on_chain_lock_processed: OnWalletChainLockProcessedCallback, + pub on_chain_truncated: OnChainTruncatedCallback, pub user_data: *mut c_void, } @@ -1004,6 +1033,7 @@ impl Default for FFIWalletEventCallbacks { on_block_processed: None, on_sync_height_advanced: None, on_chain_lock_processed: None, + on_chain_truncated: None, user_data: std::ptr::null_mut(), } } @@ -1164,6 +1194,58 @@ impl FFIWalletEventCallbacks { ); } } + WalletEvent::ChainTruncated { + wallet_id, + height, + txids, + restored_outpoints, + balance, + account_balances, + } => { + if let Some(cb) = self.on_chain_truncated { + let c_wallet_id = CString::new(hex::encode(wallet_id)).unwrap_or_default(); + let raw_txids: Vec<[u8; 32]> = + txids.iter().map(|t| t.to_byte_array()).collect(); + let txids_ptr = if raw_txids.is_empty() { + ptr::null() + } else { + raw_txids.as_ptr() + }; + let ffi_restored_outpoints = FFIOutPoint::from_slice(restored_outpoints); + let restored_outpoints_ptr = if ffi_restored_outpoints.is_empty() { + ptr::null() + } else { + ffi_restored_outpoints.as_ptr() + }; + let ffi_balance = FFIBalance::from(*balance); + let ffi_account_balances = FFIAccountBalance::from_map(account_balances); + let account_balances_ptr = if ffi_account_balances.is_empty() { + ptr::null() + } else { + ffi_account_balances.as_ptr() + }; + + cb( + c_wallet_id.as_ptr(), + *height, + txids_ptr, + raw_txids.len(), + restored_outpoints_ptr, + ffi_restored_outpoints.len(), + &ffi_balance as *const FFIBalance, + account_balances_ptr, + ffi_account_balances.len() as u32, + self.user_data, + ); + } else { + tracing::warn!( + wallet_id = %hex::encode(wallet_id), + height, + "no on_chain_truncated callback set; the consumer will keep \ + mirroring transactions the wallet dropped after a fork" + ); + } + } WalletEvent::TransactionDetected { wallet_id, record, diff --git a/dash-spv-ffi/tests/dashd_sync/callbacks.rs b/dash-spv-ffi/tests/dashd_sync/callbacks.rs index c9e58b108..b33f78cb1 100644 --- a/dash-spv-ffi/tests/dashd_sync/callbacks.rs +++ b/dash-spv-ffi/tests/dashd_sync/callbacks.rs @@ -624,6 +624,7 @@ pub(super) fn create_wallet_callbacks(tracker: &Arc) -> FFIWall on_chain_lock_processed: None, // Not exercised by these tests: they never build a conflicting spend. on_transactions_swept: None, + on_chain_truncated: None, user_data: Arc::as_ptr(tracker) as *mut c_void, } } diff --git a/dash-spv/src/client/lifecycle.rs b/dash-spv/src/client/lifecycle.rs index da498ac9f..b7a8d87e4 100644 --- a/dash-spv/src/client/lifecycle.rs +++ b/dash-spv/src/client/lifecycle.rs @@ -254,9 +254,9 @@ impl DashSpvClient DashSpvClient target_height`. /// /// Truncating above the current tip is a no-op, truncating below - /// `start_height` returns an error. Changes are applied in-memory and + /// `start_height` drops everything. Changes are applied in-memory and /// flushed on the next `persist`. /// /// The truncation is not durable until the next successful `persist` call. diff --git a/dash-spv/src/storage/blocks.rs b/dash-spv/src/storage/blocks.rs index 27324d5c9..5b09d3a01 100644 --- a/dash-spv/src/storage/blocks.rs +++ b/dash-spv/src/storage/blocks.rs @@ -26,7 +26,7 @@ pub trait BlockStorage: Send + Sync + 'static { /// Drop all blocks with `height > target_height`. /// /// Truncating above the current tip is a no-op, truncating below - /// `start_height` returns an error. Changes are applied in-memory and + /// `start_height` drops everything. Changes are applied in-memory and /// flushed on the next `persist`. /// /// The truncation is not durable until the next successful `persist` call. diff --git a/dash-spv/src/storage/filter_headers.rs b/dash-spv/src/storage/filter_headers.rs index 869a82f16..e94995588 100644 --- a/dash-spv/src/storage/filter_headers.rs +++ b/dash-spv/src/storage/filter_headers.rs @@ -51,7 +51,7 @@ pub trait FilterHeaderStorage: Send + Sync + 'static { /// Drop all filter headers with `height > target_height`. /// /// Truncating above the current tip is a no-op, truncating below - /// `start_height` returns an error. Changes are applied in-memory and + /// `start_height` drops everything. Changes are applied in-memory and /// flushed on the next `persist`. /// /// The truncation is not durable until the next successful `persist` call. diff --git a/dash-spv/src/storage/filters.rs b/dash-spv/src/storage/filters.rs index 864161772..2d78c079f 100644 --- a/dash-spv/src/storage/filters.rs +++ b/dash-spv/src/storage/filters.rs @@ -44,7 +44,7 @@ pub trait FilterStorage: Send + Sync + 'static { /// Drop all filters with `height > target_height`. /// /// Truncating above the current tip is a no-op, truncating below - /// `start_height` returns an error. Changes are applied in-memory and + /// `start_height` drops everything. Changes are applied in-memory and /// flushed on the next `persist`. /// /// The truncation is not durable until the next successful `persist` call. diff --git a/dash-spv/src/storage/segments.rs b/dash-spv/src/storage/segments.rs index 15b93e0d5..fdd1427e0 100644 --- a/dash-spv/src/storage/segments.rs +++ b/dash-spv/src/storage/segments.rs @@ -397,9 +397,8 @@ impl SegmentCache { /// has its tail slots reset to `I::sentinel()` so subsequent `Segment::insert` /// calls into the same range remain sound. /// - /// Returns an error if `target_height` is below `start_height`, since the - /// resulting cache would have a hole below its origin. Callers must guard - /// against truncating an empty cache except as a no-op (no error). + /// A `target_height` below `start_height` drops every item, as + /// [`Self::clear`] does. /// /// The reset of the boundary segment is not durable until the next /// successful `persist` call. A crash in between reopens the cache with the @@ -414,12 +413,8 @@ impl SegmentCache { return Ok(()); } - if let Some(start) = self.start_height { - if target_height < start { - return Err(StorageError::InvalidArgument(format!( - "truncate_above({target_height}) below start_height ({start})" - ))); - } + if self.start_height.is_some_and(|start| target_height < start) { + return self.clear().await; } let boundary_segment_id = Self::height_to_segment_id(target_height); @@ -1065,7 +1060,7 @@ mod tests { } #[tokio::test] - async fn test_truncate_below_start_errors() { + async fn test_truncate_below_start_clears() { let tmp_dir = TempDir::new().unwrap(); let items = FilterHeader::dummy_batch(0..5); @@ -1074,9 +1069,9 @@ mod tests { cache.store_items_at_height(&items, 10).await.unwrap(); assert_eq!(cache.start_height(), Some(10)); - assert!(cache.truncate_above(5).await.is_err()); - assert_eq!(cache.tip_height(), Some(14)); - assert_eq!(cache.start_height(), Some(10)); + cache.truncate_above(5).await.unwrap(); + assert_eq!(cache.tip_height(), None); + assert_eq!(cache.start_height(), None); } #[tokio::test] diff --git a/dash-spv/tests/dashd_sync/helpers.rs b/dash-spv/tests/dashd_sync/helpers.rs index 2ca9e5ce6..3258bb860 100644 --- a/dash-spv/tests/dashd_sync/helpers.rs +++ b/dash-spv/tests/dashd_sync/helpers.rs @@ -1,8 +1,13 @@ use dash_spv::network::NetworkEvent; use dash_spv::sync::{ProgressPercentage, SyncEvent, SyncProgress, SyncState}; use dash_spv::test_utils::DashCoreNode; -use dashcore::Txid; +use dashcore::address::NetworkUnchecked; +use dashcore::{Address, Txid}; +use key_wallet::account::ManagedAccountTrait; use key_wallet::transaction_checking::TransactionContext; +use key_wallet::wallet::managed_wallet_info::transaction_builder::{ + BuilderError, TransactionBuilder, +}; use key_wallet::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface; use key_wallet::wallet::managed_wallet_info::ManagedWalletInfo; use key_wallet_manager::WalletEvent; @@ -474,3 +479,30 @@ pub(super) async fn wait_for_network_event_both( ); r_a && r_b } + +/// Build and sign a payment of `amount` to `destination` from account 0. +pub(super) async fn build_and_sign( + wallet: &Arc>>, + wallet_id: &WalletId, + destination: &Address, + amount: u64, +) -> Result<(dashcore::Transaction, u64), BuilderError> { + let dest_unchecked: Address = + destination.to_string().parse().expect("destination address"); + + let mut wallet_lock = wallet.write().await; + let (w, info) = wallet_lock.get_wallet_and_info_mut(wallet_id).expect("wallet present"); + + let height = info.last_processed_height(); + let network = w.network; + let account = w.get_bip44_account(0).expect("account 0").clone(); + let funds_account = info.accounts.standard_bip44_accounts.get_mut(&0).expect("account 0"); + let dest = dest_unchecked.require_network(network).expect("destination network"); + + TransactionBuilder::new() + .set_current_height(height) + .add_funding(funds_account, &account) + .add_output(&dest, amount) + .build_signed(w, |a| funds_account.address_derivation_path(&a)) + .await +} diff --git a/dash-spv/tests/dashd_sync/tests_fork.rs b/dash-spv/tests/dashd_sync/tests_fork.rs index 13394096b..6db2f055c 100644 --- a/dash-spv/tests/dashd_sync/tests_fork.rs +++ b/dash-spv/tests/dashd_sync/tests_fork.rs @@ -1,11 +1,20 @@ use std::time::Duration; -use super::helpers::wait_for_sync; -use super::setup::TestContext; -use dash_spv::test_utils::TestChain; +use dash_spv::test_utils::{create_test_wallet, next_unused_receive_address, TestChain}; +use dash_spv::Network; +use dashcore::{Address, Amount}; +use key_wallet_manager::WalletEvent; +use serde_json::json; + +use super::helpers::{ + build_and_sign, count_wallet_transactions, wait_for_sync, wait_for_wallet_synced, + EMPTY_MNEMONIC, +}; +use super::setup::{create_and_start_client, TestContext}; /// Verify a synced client follows the network onto a longer branch that -/// replaces its last blocks. +/// replaces its last block, and that its wallet drops the coinbase it received +/// there and holds again the coin it spent there. #[tokio::test] async fn test_sync_follows_reorg() { let Some(ctx) = TestContext::new(TestChain::Minimal).await else { @@ -15,15 +24,55 @@ async fn test_sync_follows_reorg() { eprintln!("Skipping test (dashd RPC miner not available)"); return; } - let mut client_handle = ctx.spawn_new_client().await; + // Without mempool tracking the spend, back in dashd's mempool after the + // reorg, is not seen again: only the chain decides what the wallet holds. + let mut config = ctx.client_config.clone(); + config.enable_mempool_tracking = false; + let (wallet, wallet_id) = create_test_wallet(EMPTY_MNEMONIC, Network::Regtest); + let mut client_handle = create_and_start_client(&config, wallet.clone()).await; wait_for_sync(&mut client_handle.progress_receiver, ctx.dashd.initial_height).await; - // Replace the last 3 blocks with a branch of 5. - let fork_height = ctx.dashd.initial_height - 3; let node = &ctx.dashd.node; - node.invalidate_block(&node.get_block_hash(fork_height + 1)); - node.generate_blocks(5, &node.get_new_address()); - let new_tip = fork_height + 5; + let miner_address = node.get_new_address(); + let funding_amount = 500_000_000; + let address = next_unused_receive_address(&wallet, &wallet_id).await; + let funding_txid = node.send_to_address(&address, Amount::from_sat(funding_amount)); + node.generate_blocks(1, &miner_address); + let fork_height = ctx.dashd.initial_height + 1; + wait_for_sync(&mut client_handle.progress_receiver, fork_height).await; + wait_for_wallet_synced(&wallet, &wallet_id, fork_height).await; + + let destination = Address::dummy(Network::Regtest, 1); + let (spend, _) = + build_and_sign(&wallet, &wallet_id, &destination, 100_000_000).await.expect("build spend"); + client_handle.client.broadcast_transaction(&spend).await.expect("broadcast spend"); + tokio::time::timeout(Duration::from_secs(30), async { + while !node + .try_rpc_call("getrawmempool", &[]) + .is_some_and(|mempool| mempool.to_string().contains(&spend.txid().to_string())) + { + tokio::time::sleep(Duration::from_millis(100)).await; + } + }) + .await + .expect("spend did not reach dashd's mempool"); + + // The block the reorg replaces carries the spend and pays its coinbase to + // the wallet. A coinbase cannot go back to the mempool, so no branch has it. + let address = next_unused_receive_address(&wallet, &wallet_id).await; + let replaced_block = node.generate_blocks(1, &address)[0]; + wait_for_sync(&mut client_handle.progress_receiver, fork_height + 1).await; + wait_for_wallet_synced(&wallet, &wallet_id, fork_height + 1).await; + assert_eq!(count_wallet_transactions(&wallet, &wallet_id).await, 3); + + // Replace it with a branch of 3 blocks that leave the spend out. + let mut events = wallet.read().await.subscribe_events(); + node.invalidate_block(&replaced_block); + for _ in 0..3 { + node.try_rpc_call("generateblock", &[json!(miner_address.to_string()), json!([])]) + .expect("generateblock failed"); + } + let new_tip = fork_height + 3; tokio::time::timeout( Duration::from_secs(60), @@ -31,9 +80,43 @@ async fn test_sync_follows_reorg() { ) .await .expect("client did not follow the reorg"); - + wait_for_wallet_synced(&wallet, &wallet_id, new_tip).await; assert_eq!(client_handle.client.tip_height().await, new_tip); assert_eq!(client_handle.client.tip_hash().await, Some(node.get_best_block_hash())); + let balance = wallet.read().await.get_wallet_balance(&wallet_id).unwrap(); + assert_eq!(balance.total(), funding_amount, "only the funding coin is left, unspent"); + assert_eq!(balance.confirmed(), funding_amount); + assert_eq!(count_wallet_transactions(&wallet, &wallet_id).await, 1); + + let funding_outpoint = spend + .input + .iter() + .map(|input| input.previous_output) + .find(|outpoint| outpoint.txid == funding_txid) + .expect("the spend takes the funding output"); + let mut truncations = Vec::new(); + while let Ok(event) = events.try_recv() { + if let WalletEvent::ChainTruncated { + height, + txids, + restored_outpoints, + .. + } = event + { + truncations.push(( + height, + txids.len(), + txids.contains(&spend.txid()), + restored_outpoints, + )); + } + } + assert_eq!( + truncations, + vec![(fork_height, 2, true, vec![funding_outpoint])], + "the persister is told what to drop and what to restore" + ); + client_handle.stop().await; } diff --git a/dash-spv/tests/dashd_sync/tests_transaction.rs b/dash-spv/tests/dashd_sync/tests_transaction.rs index cc203bacd..8d14e2e55 100644 --- a/dash-spv/tests/dashd_sync/tests_transaction.rs +++ b/dash-spv/tests/dashd_sync/tests_transaction.rs @@ -6,12 +6,11 @@ use std::time::Duration; use tokio::sync::RwLock; use super::helpers::{ - count_wallet_transactions, get_spendable_balance, wait_for_mempool_tx, wait_for_sync, - wait_for_wallet_synced, EMPTY_MNEMONIC, SECONDARY_MNEMONIC, + build_and_sign, count_wallet_transactions, get_spendable_balance, wait_for_mempool_tx, + wait_for_sync, wait_for_wallet_synced, EMPTY_MNEMONIC, SECONDARY_MNEMONIC, }; use super::setup::{create_and_start_client, ClientHandle, TestContext}; use dash_spv::test_utils::{create_test_wallet, TestChain}; -use dashcore::address::NetworkUnchecked; use dashcore::PublicKey; use key_wallet::account::ManagedAccountTrait; use key_wallet::bip32::{ChildNumber, ExtendedPrivKey}; @@ -21,14 +20,11 @@ use key_wallet::wallet::balance::WalletCoreBalance; use key_wallet::wallet::initialization::WalletAccountCreationOptions; use key_wallet::wallet::managed_wallet_info::coin_selection::SelectionStrategy; use key_wallet::wallet::managed_wallet_info::fee::FeeRate; -use key_wallet::wallet::managed_wallet_info::transaction_builder::{ - BuilderError, TransactionBuilder, -}; use key_wallet::wallet::managed_wallet_info::transaction_building::AccountTypePreference; use key_wallet::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface; use key_wallet::wallet::ManagedWalletInfo; use key_wallet::ManagedAccountType; -use key_wallet_manager::{WalletId, WalletManager}; +use key_wallet_manager::WalletManager; use std::collections::BTreeSet; /// Verify incremental sync works by generating blocks after initial sync. @@ -349,32 +345,6 @@ async fn reserve_first_address(mnemonic: &str) -> Address { external_addresses.unused_addresses().into_iter().next().expect("unused address") } -async fn build_and_sign( - wallet: &Arc>>, - wallet_id: &WalletId, - destination: &Address, - amount: u64, -) -> Result<(dashcore::Transaction, u64), BuilderError> { - let dest_unchecked: Address = - destination.to_string().parse().expect("destination address"); - - let mut wallet_lock = wallet.write().await; - let (w, info) = wallet_lock.get_wallet_and_info_mut(wallet_id).expect("wallet present"); - - let height = info.last_processed_height(); - let network = w.network; - let account = w.get_bip44_account(0).expect("account 0").clone(); - let funds_account = info.accounts.standard_bip44_accounts.get_mut(&0).expect("account 0"); - let dest = dest_unchecked.require_network(network).expect("destination network"); - - TransactionBuilder::new() - .set_current_height(height) - .add_funding(funds_account, &account) - .add_output(&dest, amount) - .build_signed(w, |a| funds_account.address_derivation_path(&a)) - .await -} - /// Build, sign and broadcast a tx via `TransactionBuilder`, then re-spend /// the resulting mempool change UTXO before its parent confirms. #[tokio::test] diff --git a/key-wallet-manager/src/event_tests.rs b/key-wallet-manager/src/event_tests.rs index afccc35ae..23e272ac1 100644 --- a/key-wallet-manager/src/event_tests.rs +++ b/key-wallet-manager/src/event_tests.rs @@ -1243,6 +1243,45 @@ async fn test_update_wallet_synced_height_emits_event_per_wallet() { assert_eq!(synced_events, vec![(wallet_id, 1000)]); } +#[tokio::test] +async fn test_truncate_above_emits_chain_truncated_per_wallet() { + let (mut manager, wallet_id, addr) = setup_manager_with_wallet(); + let wallets = BTreeSet::from([wallet_id]); + let funding = create_tx_paying_to(&addr, 0xcc); + let block = make_block(vec![funding.clone()], 0xcc, 1000); + manager.process_block_for_wallets(&block, block.block_hash(), 100, &wallets).await; + + let mut spend = create_tx_paying_to(&addr, 0xdd); + spend.input[0].previous_output = OutPoint::new(funding.txid(), 0); + spend.output[0].value = TX_AMOUNT - 1_000; + let block = make_block(vec![spend.clone()], 0xdd, 1001); + manager.process_block_for_wallets(&block, block.block_hash(), 101, &wallets).await; + + let mut rx = manager.subscribe_events(); + manager.truncate_above(100); + + let events = drain_events(&mut rx); + assert_eq!(events.len(), 1, "one event per wallet expected, got {:?}", events); + match &events[0] { + WalletEvent::ChainTruncated { + wallet_id: wid, + height, + txids, + restored_outpoints, + balance, + account_balances, + } => { + assert_eq!(*wid, wallet_id); + assert_eq!(*height, 100); + assert_eq!(txids, &vec![spend.txid()]); + assert_eq!(restored_outpoints, &vec![OutPoint::new(funding.txid(), 0)]); + assert_eq!(balance.total(), TX_AMOUNT); + assert_eq!(account_balances.values().map(|b| b.total()).sum::(), TX_AMOUNT); + } + other => panic!("expected ChainTruncated, got {:?}", other), + } +} + #[tokio::test] async fn test_update_wallet_synced_height_does_not_re_emit_when_unchanged() { let (mut manager, wallet_id, _addr) = setup_manager_with_wallet(); diff --git a/key-wallet-manager/src/events.rs b/key-wallet-manager/src/events.rs index e044f0796..c8883946d 100644 --- a/key-wallet-manager/src/events.rs +++ b/key-wallet-manager/src/events.rs @@ -298,6 +298,29 @@ pub enum WalletEvent { /// full balance after the change — not a delta. account_balances: BTreeMap, }, + /// A fork replaced the chain above `height`, and the wallet dropped what it + /// recorded from the blocks above it, as if they were never processed. The + /// new branch is then processed from `height`. + /// + /// A consumer mirroring wallet state to disk must delete the removed + /// transactions with any UTXO they created, mark the restored coins unspent, + /// and lower its synced height to `height`. + ChainTruncated { + /// ID of the affected wallet. + wallet_id: WalletId, + /// Height of the last block the fork keeps. + height: CoreBlockHeight, + /// Transactions removed: they were recorded in blocks above `height`. + txids: Vec, + /// Coins the removed transactions spent, unspent again. + restored_outpoints: Vec, + /// Wallet balance after the truncation. + balance: WalletCoreBalance, + /// Post-event balance **snapshots** for accounts whose balance + /// changed as a result of this event. Each value is the account's + /// full balance after the change — not a delta. + account_balances: BTreeMap, + }, /// A block was processed for a wallet. Carries records bucketed by what /// happened to them in this block, plus the post-block balance. /// `inserted` is records first stored in this block, `updated` is @@ -412,6 +435,10 @@ impl WalletEvent { wallet_id, .. } + | WalletEvent::ChainTruncated { + wallet_id, + .. + } | WalletEvent::TransactionInstantLocked { wallet_id, .. @@ -480,6 +507,22 @@ impl fmt::Display for WalletEvent { balance, format_account_balances(account_balances), ), + WalletEvent::ChainTruncated { + height, + txids, + restored_outpoints, + balance, + account_balances, + .. + } => write!( + f, + "ChainTruncated(height={}, removed={}, restored={}, balance={}, account_balances={})", + height, + txids.len(), + restored_outpoints.len(), + balance, + format_account_balances(account_balances), + ), WalletEvent::BlockProcessed { height, chain_lock, diff --git a/key-wallet-manager/src/process_block.rs b/key-wallet-manager/src/process_block.rs index 5d9b61092..0211b36a5 100644 --- a/key-wallet-manager/src/process_block.rs +++ b/key-wallet-manager/src/process_block.rs @@ -381,6 +381,25 @@ impl WalletInterface for WalletM } } + fn truncate_above(&mut self, height: CoreBlockHeight) { + let mut events = Vec::new(); + for (wallet_id, info) in self.wallet_infos.iter_mut() { + let prior = info.account_balances(); + let truncation = info.truncate_above(height); + events.push(WalletEvent::ChainTruncated { + wallet_id: *wallet_id, + height, + txids: truncation.txids, + restored_outpoints: truncation.restored_outpoints, + balance: info.balance(), + account_balances: diff_account_balances(&prior, &info.account_balances()), + }); + } + for event in events { + self.emit_event(event); + } + } + fn update_wallet_last_processed_height( &mut self, wallet_id: &WalletId, diff --git a/key-wallet-manager/src/test_utils/mock_wallet.rs b/key-wallet-manager/src/test_utils/mock_wallet.rs index dfbcf6e29..a9569f0a8 100644 --- a/key-wallet-manager/src/test_utils/mock_wallet.rs +++ b/key-wallet-manager/src/test_utils/mock_wallet.rs @@ -234,6 +234,10 @@ impl WalletInterface for MockWallet { } } + fn truncate_above(&mut self, height: CoreBlockHeight) { + self.synced_height = self.synced_height.min(height); + } + fn update_wallet_last_processed_height( &mut self, wallet_id: &WalletId, @@ -362,6 +366,10 @@ impl WalletInterface for NonMatchingMockWallet { } } + fn truncate_above(&mut self, height: CoreBlockHeight) { + self.synced_height = self.synced_height.min(height); + } + fn update_wallet_last_processed_height( &mut self, wallet_id: &WalletId, @@ -537,6 +545,12 @@ impl WalletInterface for MultiMockWallet { } } + fn truncate_above(&mut self, height: CoreBlockHeight) { + for state in self.wallets.values_mut() { + state.synced_height = state.synced_height.min(height); + } + } + fn update_wallet_last_processed_height( &mut self, wallet_id: &WalletId, diff --git a/key-wallet-manager/src/wallet_interface.rs b/key-wallet-manager/src/wallet_interface.rs index 50fbecefb..287de3109 100644 --- a/key-wallet-manager/src/wallet_interface.rs +++ b/key-wallet-manager/src/wallet_interface.rs @@ -166,6 +166,12 @@ pub trait WalletInterface: Send + Sync + 'static { /// only advance forward (a value below the current is silently ignored). fn update_wallet_synced_height(&mut self, wallet_id: &WalletId, height: CoreBlockHeight); + /// Drop what every wallet recorded from blocks above `height`, including + /// their sync heights, so blocks above it are processed again, and emit a + /// [`WalletEvent::ChainTruncated`] per wallet. Called when a fork replaces + /// the chain above `height`. + fn truncate_above(&mut self, height: CoreBlockHeight); + /// Advance one wallet's last-processed height after a block has been applied /// to its state. Implementations must only advance forward. fn update_wallet_last_processed_height( diff --git a/key-wallet/src/managed_account/managed_core_funds_account.rs b/key-wallet/src/managed_account/managed_core_funds_account.rs index e075f977c..d690d8952 100644 --- a/key-wallet/src/managed_account/managed_core_funds_account.rs +++ b/key-wallet/src/managed_account/managed_core_funds_account.rs @@ -27,6 +27,7 @@ use crate::transaction_checking::transaction_router::TransactionType; use crate::transaction_checking::{AccountMatch, TransactionContext}; use crate::utxo::Utxo; use crate::wallet::balance::WalletCoreBalance; +use crate::wallet::managed_wallet_info::wallet_info_interface::Truncation; use crate::{ExtendedPubKey, Network}; use dashcore::blockdata::transaction::OutPoint; use dashcore::prelude::CoreBlockHeight; @@ -65,6 +66,9 @@ pub struct ManagedCoreFundsAccount { /// Ours, but spent before the funding arrived, so never in `utxos` (#649). /// Input matching falls back to these. pub(crate) spent_before_funded: BTreeMap, + /// The UTXOs removed by each spend not yet chainlocked, so a fork that drops + /// the spend can put them back. + unsettled_spends: BTreeMap>, /// Outpoints reserved by in-flight transaction builds so concurrent builds /// do not select the same UTXO before the first build's transaction is /// processed. Empty after a restart, where chain and mempool sync @@ -107,6 +111,7 @@ impl ManagedCoreFundsAccount { utxos: BTreeMap::new(), spent_outpoints: HashSet::new(), spent_before_funded: BTreeMap::new(), + unsettled_spends: BTreeMap::new(), reservations: ReservationSet::default(), } } @@ -135,6 +140,7 @@ impl ManagedCoreFundsAccount { utxos: BTreeMap::new(), spent_outpoints: HashSet::new(), spent_before_funded: BTreeMap::new(), + unsettled_spends: BTreeMap::new(), reservations: ReservationSet::default(), } } @@ -402,15 +408,19 @@ impl ManagedCoreFundsAccount { self.spent_outpoints.insert(input.previous_output); self.spent_before_funded.remove(&input.previous_output); - if self.utxos.remove(&input.previous_output).is_some() { + if let Some(spent) = self.utxos.remove(&input.previous_output) { tracing::debug!( outpoint = %input.previous_output, txid = %tx.txid(), "Removed spent UTXO" ); + self.unsettled_spends.entry(txid).or_default().push(spent); utxos_changed = true; } } + if context.is_chain_locked() { + self.unsettled_spends.remove(&txid); + } if utxos_changed { self.keys.bump_monitor_revision(); @@ -491,6 +501,7 @@ impl ManagedCoreFundsAccount { let mut records = 0; let mut freed: HashSet = HashSet::new(); for txid in abandoned { + self.unsettled_spends.remove(txid); if let Some(record) = self.keys.transactions_mut().remove(txid) { records += 1; freed.extend(record.transaction.input.iter().map(|input| input.previous_output)); @@ -509,6 +520,58 @@ impl ManagedCoreFundsAccount { } } + /// Drop the transactions recorded in blocks above `height`, like + /// [`Self::apply_abandon`], and put back the coins they spent from + /// transactions the fork keeps, along with the ones held in + /// `spent_before_funded` for a spend in `dropped_spends`, the spends observed + /// above `height`. + pub(crate) fn truncate_above( + &mut self, + height: CoreBlockHeight, + dropped_spends: &BTreeSet, + ) -> Truncation { + let dropped: BTreeSet = self + .keys + .transactions() + .values() + .filter(|record| record.height().is_some_and(|block| block > height)) + .map(|record| record.txid) + .collect(); + let mut spent: Vec = dropped + .iter() + .filter_map(|txid| self.unsettled_spends.remove(txid)) + .flatten() + .collect(); + self.apply_abandon(&dropped); + spent.extend( + dropped_spends.iter().filter_map(|outpoint| self.spent_before_funded.remove(outpoint)), + ); + + let mut restored = Vec::new(); + for mut utxo in spent { + let outpoint = utxo.outpoint; + if dropped.contains(&outpoint.txid) || self.spent_outpoints.contains(&outpoint) { + continue; + } + // Spent in a block, so funded in one the fork keeps. + utxo.is_confirmed = true; + if let Some(height) = + self.keys.transactions().get(&outpoint.txid).and_then(|parent| parent.height()) + { + utxo.height = height; + } + self.utxos.insert(outpoint, utxo); + restored.push(outpoint); + } + if !restored.is_empty() { + self.keys.bump_monitor_revision(); + } + Truncation { + txids: dropped.into_iter().collect(), + restored_outpoints: restored, + } + } + /// Drop the outputs of any recorded unconfirmed transaction that `tx` /// provably beat to one of its inputs. /// @@ -655,6 +718,7 @@ impl ManagedCoreFundsAccount { changed = true; } self.spent_before_funded.retain(|outpoint, _| outpoint.txid != *loser); + self.unsettled_spends.remove(loser); if let Some(record) = self.keys.transactions_mut().remove(loser) { freed.extend(record.transaction.input.iter().map(|input| input.previous_output)); } @@ -968,7 +1032,11 @@ impl ManagedCoreFundsAccount { /// spentness or maturity, only the certainty of its parent /// transaction. pub(crate) fn apply_chain_lock(&mut self, cl_height: CoreBlockHeight) -> Vec { - self.keys.apply_chain_lock(cl_height) + let promoted = self.keys.apply_chain_lock(cl_height); + for txid in &promoted { + self.unsettled_spends.remove(txid); + } + promoted } /// Update the account balance. @@ -1324,6 +1392,8 @@ impl<'de> Deserialize<'de> for ManagedCoreFundsAccount { utxos: BTreeMap, #[serde(default)] spent_before_funded: BTreeMap, + #[serde(default)] + unsettled_spends: BTreeMap>, } let helper = Helper::deserialize(deserializer)?; @@ -1336,6 +1406,7 @@ impl<'de> Deserialize<'de> for ManagedCoreFundsAccount { utxos: helper.utxos, spent_outpoints, spent_before_funded: helper.spent_before_funded, + unsettled_spends: helper.unsettled_spends, reservations: ReservationSet::default(), }) } diff --git a/key-wallet/src/tests/mod.rs b/key-wallet/src/tests/mod.rs index 6b490d4ab..bcc1f4cda 100644 --- a/key-wallet/src/tests/mod.rs +++ b/key-wallet/src/tests/mod.rs @@ -36,6 +36,8 @@ mod special_transaction_tests; mod transaction_tests; +mod truncate_above_tests; + mod spent_outpoints_tests; mod unit_variant_wallet_tests; diff --git a/key-wallet/src/tests/observed_spent_outpoints_tests.rs b/key-wallet/src/tests/observed_spent_outpoints_tests.rs index ee6e00bcc..ff539c253 100644 --- a/key-wallet/src/tests/observed_spent_outpoints_tests.rs +++ b/key-wallet/src/tests/observed_spent_outpoints_tests.rs @@ -30,6 +30,7 @@ use crate::managed_account::transaction_record::TransactionDirection; use crate::test_utils::TestWalletContext; use crate::transaction_checking::{BlockInfo, TransactionContext}; use crate::wallet::managed_wallet_info::managed_account_operations::ManagedAccountOperations; +use crate::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface; use crate::wallet::ManagedWalletInfo; use crate::AccountType; @@ -653,3 +654,32 @@ async fn recording_observed_spend_reports_state_modified() { let result = ctx.check_transaction(&mempool_spend, TransactionContext::Mempool).await; assert!(!result.state_modified, "a mempool spend records nothing"); } + +#[test] +fn truncate_above_drops_spends_observed_above_the_fork() { + let mut info = ManagedWalletInfo::dummy(9); + let op_kept = OutPoint::new(Txid::from([0x01; 32]), 0); + let op_dropped = OutPoint::new(Txid::from([0x02; 32]), 0); + info.record_observed_spends(&spending_tx(&[op_kept]), 100); + info.record_observed_spends(&spending_tx(&[op_dropped]), 101); + + info.truncate_above(100); + + assert!(info.observed_spent_outpoints().contains_key(&op_kept)); + assert!(!info.observed_spent_outpoints().contains_key(&op_dropped)); +} + +#[tokio::test] +async fn truncate_above_restores_a_held_output_whose_spend_it_drops() { + let (mut ctx, funding, _spend) = spend_first_context(in_block(100, 1)).await; + let outpoint = OutPoint::new(funding.txid(), 0); + + let truncation = ctx.managed_wallet.truncate_above(150); + + assert_eq!(truncation.restored_outpoints, vec![outpoint]); + let account = ctx.managed_wallet.first_bip44_managed_account().expect("BIP44 account"); + assert!(account.spent_before_funded.is_empty()); + let utxo = account.utxos.get(&outpoint).expect("the held output is a UTXO again"); + assert!(utxo.is_confirmed); + assert_eq!(ctx.managed_wallet.balance.total(), SPEND_FIRST_FUNDING_VALUE); +} diff --git a/key-wallet/src/tests/truncate_above_tests.rs b/key-wallet/src/tests/truncate_above_tests.rs new file mode 100644 index 000000000..b1239b9cb --- /dev/null +++ b/key-wallet/src/tests/truncate_above_tests.rs @@ -0,0 +1,79 @@ +//! `WalletInfoInterface::truncate_above`: what a fork drops from the wallet and +//! what it gives back. + +use dashcore::blockdata::script::ScriptBuf; +use dashcore::hashes::Hash; +use dashcore::{BlockHash, OutPoint, Transaction, TxIn, TxOut}; + +use crate::test_utils::TestWalletContext; +use crate::transaction_checking::{BlockInfo, TransactionContext}; +use crate::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface; + +const FUNDING_VALUE: u64 = 1_000_000; + +fn in_block(height: u32) -> BlockInfo { + BlockInfo::new(height, BlockHash::from_byte_array([height as u8; 32]), 1_650_000_000 + height) +} + +fn spend_to_external(funding: &Transaction) -> Transaction { + let external = dashcore::Address::p2pkh( + &dashcore::PublicKey::from_slice(&[0x02; 33]).expect("pubkey"), + dashcore::Network::Testnet, + ); + Transaction { + version: 2, + lock_time: 0, + input: vec![TxIn { + previous_output: OutPoint::new(funding.txid(), 0), + script_sig: ScriptBuf::new(), + sequence: 0xffffffff, + witness: dashcore::Witness::new(), + }], + output: vec![TxOut { + value: FUNDING_VALUE - 1_000, + script_pubkey: external.script_pubkey(), + }], + special_transaction_payload: None, + } +} + +/// Funds the wallet at `fund_ctx` and spends the coin in a block at 101. +async fn fund_and_spend( + fund_ctx: TransactionContext, +) -> (TestWalletContext, Transaction, Transaction) { + let mut ctx = TestWalletContext::new_random(); + let funding = Transaction::dummy(&ctx.receive_address, 0..1, &[FUNDING_VALUE]); + let spend = spend_to_external(&funding); + assert!(ctx.check_transaction(&funding, fund_ctx).await.is_relevant); + assert!( + ctx.check_transaction(&spend, TransactionContext::InBlock(in_block(101))).await.is_relevant + ); + assert_eq!(ctx.managed_wallet.balance.total(), 0); + (ctx, funding, spend) +} + +#[tokio::test] +async fn truncate_above_restores_a_coin_from_a_chainlocked_funding() { + let (mut ctx, funding, _spend) = + fund_and_spend(TransactionContext::InChainLockedBlock(in_block(100))).await; + + let truncation = ctx.managed_wallet.truncate_above(100); + + assert_eq!(truncation.restored_outpoints, vec![OutPoint::new(funding.txid(), 0)]); + assert_eq!(ctx.managed_wallet.balance.confirmed(), FUNDING_VALUE); +} + +#[tokio::test] +async fn truncate_above_restores_nothing_the_fork_drops_too() { + let (mut ctx, funding, spend) = + fund_and_spend(TransactionContext::InBlock(in_block(100))).await; + + let truncation = ctx.managed_wallet.truncate_above(99); + + assert_eq!(truncation.txids.len(), 2); + assert!(truncation.txids.contains(&funding.txid())); + assert!(truncation.txids.contains(&spend.txid())); + assert!(truncation.restored_outpoints.is_empty()); + assert!(ctx.bip44_account().utxos.is_empty()); + assert_eq!(ctx.managed_wallet.balance.total(), 0); +} diff --git a/key-wallet/src/wallet/managed_wallet_info/mod.rs b/key-wallet/src/wallet/managed_wallet_info/mod.rs index 0d288e35f..9d1d32744 100644 --- a/key-wallet/src/wallet/managed_wallet_info/mod.rs +++ b/key-wallet/src/wallet/managed_wallet_info/mod.rs @@ -74,17 +74,17 @@ pub struct ManagedWalletInfo { /// /// Membership is bounded-permanent: an entry is retained until its spend /// height is provably final, then evicted by - /// [`Self::prune_finalized_observed_spends`]. Until then it is only ever - /// added, never removed, and reorg rollback does NOT retract it — treating a - /// coin as spendable again after a spend was observed is the failure this - /// set exists to prevent. Only spends seen in a block (`InBlock` / - /// `InChainLockedBlock`) are recorded; mempool-context spends are never - /// recorded, so an unconfirmed spend can never wrongly invalidate a coin. + /// [`Self::prune_finalized_observed_spends`], or dropped by `truncate_above` + /// when a fork replaces the block that spent it: the wallet then scans the + /// new branch from the fork and observes again any spend it still contains. + /// Only spends seen in a block (`InBlock` / `InChainLockedBlock`) are + /// recorded; mempool-context spends are never recorded, so an unconfirmed + /// spend can never wrongly invalidate a coin. /// /// # Bounded permanence /// - /// An entry `(outpoint, height)` is removed only when `height` is at or - /// below both `synced_height` and the highest chainlock applied or noted + /// An entry `(outpoint, height)` is pruned as final only when `height` is at + /// or below both `synced_height` and the highest chainlock applied or noted /// (`note_chain_lock_height`) — the finality boundary. At that boundary the /// spend is chain-locked (it can never be reorged out) and any funding /// transaction for the outpoint has been delivered (BIP158 filters have no diff --git a/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs b/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs index 1dabac23d..41d5fc8f5 100644 --- a/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs +++ b/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs @@ -45,6 +45,15 @@ pub struct ApplyChainLockOutcome { pub metadata_advanced: bool, } +/// What [`WalletInfoInterface::truncate_above`] changed. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Truncation { + /// Transactions removed: they were recorded in blocks above the height. + pub txids: Vec, + /// Coins those transactions spent, unspent again. + pub restored_outpoints: Vec, +} + /// Trait that wallet info types must implement to work with WalletManager pub trait WalletInfoInterface: Sized + WalletTransactionChecker + ManagedAccountOperations { /// Create a wallet info from an existing wallet, seeding the sync checkpoint at @@ -255,6 +264,13 @@ pub trait WalletInfoInterface: Sized + WalletTransactionChecker + ManagedAccount /// Record that the durable wallet sync checkpoint has advanced to `current_height`. fn update_synced_height(&mut self, current_height: u32); + /// Drop what the wallet recorded from blocks above `height`, as if they were + /// never processed: their transactions, the UTXOs they created, the spends + /// observed in them, and the sync heights past `height`. The coins those + /// transactions spent are unspent again. Used when a fork replaces the chain + /// above `height`. + fn truncate_above(&mut self, height: CoreBlockHeight) -> Truncation; + /// Records whose coinbase maturity threshold lies in /// `(old_height, new_height]`, i.e. coinbase records that just matured /// during the height advance from `old_height` to `new_height`. @@ -545,6 +561,47 @@ impl WalletInfoInterface for ManagedWalletInfo { self.prune_finalized_observed_spends(); } + fn truncate_above(&mut self, height: CoreBlockHeight) -> Truncation { + let dropped_spends: BTreeSet = self + .observed_spent_outpoints + .iter() + .filter(|(_, spent_at)| **spent_at > height) + .map(|(outpoint, _)| *outpoint) + .collect(); + self.observed_spent_outpoints.retain(|outpoint, _| !dropped_spends.contains(outpoint)); + + let mut txids = BTreeSet::new(); + let mut restored_outpoints = Vec::new(); + for account in self.accounts.all_accounts_mut() { + match account { + ManagedAccountRefMut::Funds(funds) => { + let truncation = funds.truncate_above(height, &dropped_spends); + txids.extend(truncation.txids); + restored_outpoints.extend(truncation.restored_outpoints); + } + ManagedAccountRefMut::Keys(keys) => { + keys.transactions_mut().retain(|txid, record| { + let dropped = record.height().is_some_and(|block| block > height); + if dropped { + txids.insert(*txid); + } + !dropped + }); + } + } + } + + self.metadata.synced_height = self.metadata.synced_height.min(height); + self.metadata.last_processed_height = self.metadata.last_processed_height.min(height); + self.update_balance(); + + restored_outpoints.sort_unstable(); + Truncation { + txids: txids.into_iter().collect(), + restored_outpoints, + } + } + fn matured_coinbase_records( &self, old_height: CoreBlockHeight, From 9730ff66bdafe91183acd57a7a230579026b966d Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Tue, 6 Oct 2026 09:03:33 -0700 Subject: [PATCH 2/7] fix(dash-spv): do not follow a fork below the best ChainLock A branch off below the best persisted ChainLock is no fork: the blocks it locks are final, so storage and wallets are left as they are. `MetadataStorage::load_metadata` now deserializes the stored JSON value. Co-Authored-By: Claude Opus 5.5 --- dash-spv/src/storage/metadata.rs | 38 ++++++------ dash-spv/src/storage/mod.rs | 6 +- dash-spv/src/sync/block_headers/manager.rs | 71 +++++++++++++++++++++- dash-spv/src/sync/chainlock/manager.rs | 33 +++++----- dash-spv/src/sync/mod.rs | 2 + 5 files changed, 109 insertions(+), 41 deletions(-) diff --git a/dash-spv/src/storage/metadata.rs b/dash-spv/src/storage/metadata.rs index e534dbaf1..d32a1d73d 100644 --- a/dash-spv/src/storage/metadata.rs +++ b/dash-spv/src/storage/metadata.rs @@ -7,6 +7,7 @@ use crate::{ }; use async_trait::async_trait; use dashcore::prelude::CoreBlockHeight; +use serde::de::DeserializeOwned; /// Metadata key for persisting the best known peer height. const LAST_TARGET_HEIGHT_KEY: &str = "last_target_height"; @@ -15,7 +16,11 @@ const LAST_TARGET_HEIGHT_KEY: &str = "last_target_height"; pub trait MetadataStorage: Send + Sync + 'static { async fn store_metadata(&mut self, key: &str, value: &[u8]) -> StorageResult<()>; - async fn load_metadata(&self, key: &str) -> StorageResult>>; + /// The JSON value stored under `key`, `None` when nothing is. + async fn load_metadata( + &self, + key: &str, + ) -> StorageResult>; /// Persist the last target height to metadata storage. async fn store_last_target_height(&mut self, height: CoreBlockHeight) -> StorageResult<()>; /// Load the last target height from metadata storage. @@ -57,7 +62,10 @@ impl MetadataStorage for PersistentMetadataStorage { Ok(()) } - async fn load_metadata(&self, key: &str) -> StorageResult>> { + async fn load_metadata( + &self, + key: &str, + ) -> StorageResult> { let path = self.storage_path.join(Self::FOLDER_NAME).join(format!("{key}.dat")); if !path.exists() { @@ -65,7 +73,9 @@ impl MetadataStorage for PersistentMetadataStorage { } let data = tokio::fs::read(path).await?; - Ok(Some(data)) + serde_json::from_slice(&data).map(Some).map_err(|e| { + StorageError::Serialization(format!("Failed to deserialize metadata {key}: {e}")) + }) } /// Persist the last target height to metadata storage. @@ -83,27 +93,19 @@ impl MetadataStorage for PersistentMetadataStorage { /// Load the last target height from metadata storage. Used by the block headers manager to /// restore progress after restart. async fn load_last_target_height(&self) -> StorageResult { - match self.load_metadata(LAST_TARGET_HEIGHT_KEY).await { - Ok(Some(bytes)) => match serde_json::from_slice::(&bytes) { - Ok(last_target_height) => { - tracing::debug!("Restored last target height {}", last_target_height); - Ok(last_target_height) - } - Err(e) => { - let error = format!("Failed to deserialize last target height: {}", e); - tracing::warn!(error); - Err(StorageError::Serialization(error)) - } - }, + match self.load_metadata::(LAST_TARGET_HEIGHT_KEY).await { + Ok(Some(last_target_height)) => { + tracing::debug!("Restored last target height {}", last_target_height); + Ok(last_target_height) + } Ok(None) => { let error = "No last target height found (fresh start)".to_string(); tracing::debug!(error); Err(StorageError::NotFound(error)) } Err(e) => { - let error = format!("Failed to load last target height: {}", e); - tracing::warn!(error); - Err(StorageError::Corruption(error)) + tracing::warn!("Failed to load last target height: {}", e); + Err(e) } } } diff --git a/dash-spv/src/storage/mod.rs b/dash-spv/src/storage/mod.rs index 9c9d0ca8e..07966c2ea 100644 --- a/dash-spv/src/storage/mod.rs +++ b/dash-spv/src/storage/mod.rs @@ -25,6 +25,7 @@ use dashcore::network::message_sml::MnListDiff; use dashcore::prelude::CoreBlockHeight; use dashcore::sml::masternode_list_engine::MasternodeListEngine; use dashcore::Network; +use serde::de::DeserializeOwned; use std::ops::Range; use std::path::{Path, PathBuf}; use std::sync::Arc; @@ -450,7 +451,10 @@ impl metadata::MetadataStorage for DiskStorageManager { self.metadata.write().await.store_metadata(key, value).await } - async fn load_metadata(&self, key: &str) -> StorageResult>> { + async fn load_metadata( + &self, + key: &str, + ) -> StorageResult> { self.metadata.read().await.load_metadata(key).await } diff --git a/dash-spv/src/sync/block_headers/manager.rs b/dash-spv/src/sync/block_headers/manager.rs index d6f8f4795..c232f0e0e 100644 --- a/dash-spv/src/sync/block_headers/manager.rs +++ b/dash-spv/src/sync/block_headers/manager.rs @@ -16,11 +16,15 @@ use crate::error::{SyncError, SyncResult}; use crate::network::RequestSender; use crate::storage::{BlockHeaderStorage, BlockHeaderTip, MetadataStorage}; use crate::sync::block_headers::HeadersPipeline; -use crate::sync::{BlockHeadersProgress, ProgressPercentage, SyncEvent, SyncManager, SyncState}; +use crate::sync::{ + BlockHeadersProgress, ProgressPercentage, SyncEvent, SyncManager, SyncState, + BEST_CHAINLOCK_METADATA_STORAGE_KEY, +}; use crate::types::HashedBlockHeader; use crate::validation::{BlockHeaderValidator, Validator}; #[cfg(test)] use dashcore::block::Header; +use dashcore::ephemerealdata::chain_lock::ChainLock; use dashcore::network::message_blockdata::Inventory; use dashcore::BlockHash; use tokio::sync::RwLock; @@ -181,7 +185,9 @@ impl BlockHeadersManager { Ok(events) } - /// Height where `headers` branch off the stored chain below its tip, if they do. + /// Height where `headers` branch off the stored chain below its tip, if they + /// do. A branch off below the best ChainLock is not followed: the blocks it + /// locks are final. async fn fork_height(&self, headers: &[HashedBlockHeader]) -> SyncResult> { let storage = self.header_storage.read().await; @@ -193,8 +199,27 @@ impl BlockHeadersManager { let parent = storage.get_header_height_by_hash(&header.header().prev_blockhash).await?; let tip = storage.get_tip_height().await; + let Some(fork_height) = parent.filter(|&parent| tip.is_some_and(|tip| parent < tip)) + else { + return Ok(None); + }; + + let chain_lock = self + .metadata_storage + .read() + .await + .load_metadata::(BEST_CHAINLOCK_METADATA_STORAGE_KEY) + .await?; + if let Some(chain_lock) = chain_lock.filter(|cl| fork_height < cl.block_height) { + tracing::warn!( + "Ignoring a fork at height {}, below the ChainLock at {}", + fork_height, + chain_lock.block_height + ); + return Ok(None); + } - return Ok(parent.filter(|&parent| tip.is_some_and(|tip| parent < tip))); + return Ok(Some(fork_height)); } Ok(None) @@ -335,6 +360,7 @@ mod tests { use crate::sync::block_headers::segment_state::SegmentState; use crate::sync::{ManagerIdentifier, SyncManager, SyncManagerProgress}; use dashcore::network::message::NetworkMessage; + use test_case::test_case; use tokio::sync::mpsc::unbounded_channel; type TestBlockHeadersManager = @@ -360,6 +386,45 @@ mod tests { .expect("Failed to create BlockHeadersManager") } + #[test_case(None, 5, Some(5); "no ChainLock")] + #[test_case(Some(6), 5, None; "below the ChainLock")] + #[test_case(Some(5), 5, Some(5); "at the ChainLock")] + #[test_case(Some(3), 5, Some(5); "above the ChainLock")] + #[tokio::test] + async fn a_branch_off_below_the_best_chain_lock_is_no_fork( + chain_locked: Option, + branch_off: u32, + expected: Option, + ) { + let mut storage = DiskStorageManager::with_temp_dir().await.unwrap(); + let stored = Header::dummy_batch(0..10); + storage + .store_headers(&stored.iter().map(HashedBlockHeader::from).collect::>()) + .await + .unwrap(); + if let Some(height) = chain_locked { + let bytes = serde_json::to_vec(&ChainLock::dummy(height)).unwrap(); + storage.store_metadata(BEST_CHAINLOCK_METADATA_STORAGE_KEY, &bytes).await.unwrap(); + } + let manager = BlockHeadersManager::new( + storage.block_headers(), + storage.metadata(), + create_test_checkpoint_manager(), + ) + .await + .unwrap(); + + let branch = Header { + prev_blockhash: stored[branch_off as usize].block_hash(), + ..Header::dummy(1_000) + }; + + assert_eq!( + manager.fork_height(&[HashedBlockHeader::from(&branch)]).await.unwrap(), + expected + ); + } + /// Create a manager in synced state with an initialized pipeline. async fn create_synced_manager() -> TestBlockHeadersManager { let mut manager = create_test_manager().await; diff --git a/dash-spv/src/sync/chainlock/manager.rs b/dash-spv/src/sync/chainlock/manager.rs index a2ba8c6b1..d9a68faeb 100644 --- a/dash-spv/src/sync/chainlock/manager.rs +++ b/dash-spv/src/sync/chainlock/manager.rs @@ -15,10 +15,7 @@ use tokio::sync::RwLock; use crate::error::SyncResult; use crate::storage::{BlockHeaderStorage, MetadataStorage}; -use crate::sync::{ChainLockProgress, SyncEvent}; - -/// Metadata key for persisting the best validated ChainLock. -const BEST_CHAINLOCK_KEY: &str = "best_chainlock"; +use crate::sync::{ChainLockProgress, SyncEvent, BEST_CHAINLOCK_METADATA_STORAGE_KEY}; /// ChainLock manager for the parallel sync coordinator. /// @@ -226,7 +223,9 @@ impl ChainLockManager { match serde_json::to_vec(chainlock) { Ok(bytes) => { let mut storage = self.metadata_storage.write().await; - if let Err(e) = storage.store_metadata(BEST_CHAINLOCK_KEY, &bytes).await { + if let Err(e) = + storage.store_metadata(BEST_CHAINLOCK_METADATA_STORAGE_KEY, &bytes).await + { tracing::warn!("Failed to persist best chainlock: {}", e); } } @@ -239,18 +238,13 @@ impl ChainLockManager { /// Load the best chainlock from metadata storage and restore progress. pub(super) async fn load_best_chainlock(&mut self) { let storage = self.metadata_storage.read().await; - match storage.load_metadata(BEST_CHAINLOCK_KEY).await { - Ok(Some(bytes)) => match serde_json::from_slice::(&bytes) { - Ok(chainlock) => { - let height = chainlock.block_height; - tracing::info!("Restored persisted ChainLock at height {}", height); - self.progress.update_best_validated_height(height); - self.best_chainlock = Some(chainlock); - } - Err(e) => { - tracing::warn!("Failed to deserialize persisted chainlock: {}", e); - } - }, + match storage.load_metadata::(BEST_CHAINLOCK_METADATA_STORAGE_KEY).await { + Ok(Some(chainlock)) => { + let height = chainlock.block_height; + tracing::info!("Restored persisted ChainLock at height {}", height); + self.progress.update_best_validated_height(height); + self.best_chainlock = Some(chainlock); + } Ok(None) => { tracing::debug!("No persisted chainlock found (fresh start)"); } @@ -679,7 +673,7 @@ mod tests { let bytes = serde_json::to_vec(&chainlock).unwrap(); let meta_storage = storage.metadata(); let mut meta = meta_storage.write().await; - meta.store_metadata(BEST_CHAINLOCK_KEY, &bytes).await.unwrap(); + meta.store_metadata(BEST_CHAINLOCK_METADATA_STORAGE_KEY, &bytes).await.unwrap(); } // Create a new manager and call initialize (the SyncManager trait method) @@ -706,7 +700,8 @@ mod tests { { let meta_storage = storage.metadata(); let meta = meta_storage.read().await; - let loaded = meta.load_metadata(BEST_CHAINLOCK_KEY).await.unwrap(); + let loaded = + meta.load_metadata::(BEST_CHAINLOCK_METADATA_STORAGE_KEY).await.unwrap(); assert!(loaded.is_none()); } } diff --git a/dash-spv/src/sync/mod.rs b/dash-spv/src/sync/mod.rs index f059ebc09..5be093ff9 100644 --- a/dash-spv/src/sync/mod.rs +++ b/dash-spv/src/sync/mod.rs @@ -30,3 +30,5 @@ pub use identifier::ManagerIdentifier; pub use progress::{ProgressPercentage, SyncProgress, SyncState}; pub use sync_coordinator::{Managers, SyncCoordinator}; pub use sync_manager::{SyncManager, SyncManagerProgress, SyncManagerTaskContext}; + +const BEST_CHAINLOCK_METADATA_STORAGE_KEY: &str = "best_chainlock"; From da5b1f401e5f5bbe9ce7584cc624dfb06e65dfef Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Tue, 6 Oct 2026 09:44:14 -0700 Subject: [PATCH 3/7] fix(wallet)!: refuse a truncation below the applied ChainLock `truncate_above` fails and changes nothing when the height is below a wallet's applied ChainLock; `WalletManager` checks every wallet first, so a refused truncation leaves all of them as they are. A fork now truncates the wallets before storage and always restarts the client, so a storage failure keeps the fork unstored and it is detected and retried. Co-Authored-By: Claude Opus 5.5 --- dash-spv/src/client/lifecycle.rs | 13 ++++++- key-wallet-ffi/src/error.rs | 8 +++- key-wallet-manager/src/error.rs | 24 ++++++++++++ key-wallet-manager/src/event_tests.rs | 37 ++++++++++++++++++- key-wallet-manager/src/process_block.rs | 20 ++++++++-- .../src/test_utils/mock_wallet.rs | 12 ++++-- key-wallet-manager/src/wallet_interface.rs | 7 +++- key-wallet/src/error.rs | 15 ++++++++ .../tests/observed_spent_outpoints_tests.rs | 4 +- key-wallet/src/tests/truncate_above_tests.rs | 35 +++++++++++++++++- .../wallet_info_interface.rs | 22 ++++++++--- 11 files changed, 175 insertions(+), 22 deletions(-) diff --git a/dash-spv/src/client/lifecycle.rs b/dash-spv/src/client/lifecycle.rs index b7a8d87e4..ff6325993 100644 --- a/dash-spv/src/client/lifecycle.rs +++ b/dash-spv/src/client/lifecycle.rs @@ -271,14 +271,23 @@ impl DashSpvClient>(()) + } + .await; + + if let Err(e) = truncated { + tracing::warn!("Fork at height {} not followed: {}", fork_height, e); } - self.wallet.write().await.truncate_above(fork_height); self.run_locked(&mut sync_loop).await }) diff --git a/key-wallet-ffi/src/error.rs b/key-wallet-ffi/src/error.rs index db38bf4d1..24721f98d 100644 --- a/key-wallet-ffi/src/error.rs +++ b/key-wallet-ffi/src/error.rs @@ -256,6 +256,9 @@ impl From for FFIError { | Error::NoKeySource | Error::KeylessWalletRequiresAccountKey { .. + } + | Error::TruncateBelowChainLock { + .. } => FFIErrorCode::InvalidState, Error::Bip32(_) | Error::Slip10(_) @@ -305,7 +308,10 @@ impl From for FFIError { WalletError::InvalidNetwork => FFIErrorCode::InvalidNetwork, WalletError::InvalidParameter(_) => FFIErrorCode::InvalidInput, WalletError::TransactionBuild(_) => FFIErrorCode::InvalidTransaction, - WalletError::InsufficientFunds => FFIErrorCode::InvalidState, + WalletError::InsufficientFunds + | WalletError::TruncateBelowChainLock { + .. + } => FFIErrorCode::InvalidState, }; FFIError { diff --git a/key-wallet-manager/src/error.rs b/key-wallet-manager/src/error.rs index e4dbd35e1..cc1d9b0c6 100644 --- a/key-wallet-manager/src/error.rs +++ b/key-wallet-manager/src/error.rs @@ -28,6 +28,15 @@ pub enum WalletError { TransactionBuild(String), /// Insufficient funds InsufficientFunds, + /// A truncation below a wallet's applied ChainLock, whose blocks are final + TruncateBelowChainLock { + /// The wallet that refused the truncation + wallet_id: WalletId, + /// The height asked to truncate above + height: u32, + /// The height of the wallet's applied ChainLock + chain_locked: u32, + }, } impl core::fmt::Display for WalletError { @@ -56,6 +65,21 @@ impl core::fmt::Display for WalletError { WalletError::InvalidParameter(msg) => write!(f, "Invalid parameter: {}", msg), WalletError::TransactionBuild(err) => write!(f, "Transaction build failed: {}", err), WalletError::InsufficientFunds => write!(f, "Insufficient funds"), + WalletError::TruncateBelowChainLock { + wallet_id, + height, + chain_locked, + } => { + write!(f, "Cannot truncate wallet ")?; + for byte in wallet_id.iter() { + write!(f, "{:02x}", byte)?; + } + write!( + f, + " above {}: blocks up to the ChainLock at {} are final", + height, chain_locked + ) + } } } } diff --git a/key-wallet-manager/src/event_tests.rs b/key-wallet-manager/src/event_tests.rs index 23e272ac1..23b2f6422 100644 --- a/key-wallet-manager/src/event_tests.rs +++ b/key-wallet-manager/src/event_tests.rs @@ -1258,7 +1258,7 @@ async fn test_truncate_above_emits_chain_truncated_per_wallet() { manager.process_block_for_wallets(&block, block.block_hash(), 101, &wallets).await; let mut rx = manager.subscribe_events(); - manager.truncate_above(100); + manager.truncate_above(100).expect("truncates"); let events = drain_events(&mut rx); assert_eq!(events.len(), 1, "one event per wallet expected, got {:?}", events); @@ -1282,6 +1282,41 @@ async fn test_truncate_above_emits_chain_truncated_per_wallet() { } } +#[tokio::test] +async fn test_truncate_above_below_a_chain_lock_changes_no_wallet() { + let (mut manager, locked_id, _addr) = setup_manager_with_wallet(); + manager.update_wallet_synced_height(&locked_id, 200); + manager.apply_chain_lock(ChainLock::dummy(100)); + // Created after the ChainLock, so only `locked_id` refuses. + let other_id = manager + .create_wallet_from_mnemonic( + "legal winner thank year wave sausage worth useful legal winner thank yellow", + 0, + key_wallet::wallet::initialization::WalletAccountCreationOptions::Default, + ) + .unwrap(); + manager.update_wallet_synced_height(&other_id, 200); + let mut rx = manager.subscribe_events(); + + match manager.truncate_above(99) { + Err(WalletError::TruncateBelowChainLock { + wallet_id, + height: 99, + chain_locked: 100, + }) => assert_eq!(wallet_id, locked_id), + other => panic!("expected TruncateBelowChainLock, got {:?}", other), + } + assert!(drain_events(&mut rx).is_empty(), "a refused truncation emits nothing"); + for wallet_id in [locked_id, other_id] { + assert_eq!(manager.get_wallet_info(&wallet_id).unwrap().synced_height(), 200); + } + + manager.truncate_above(100).expect("truncates at the ChainLock"); + for wallet_id in [locked_id, other_id] { + assert_eq!(manager.get_wallet_info(&wallet_id).unwrap().synced_height(), 100); + } +} + #[tokio::test] async fn test_update_wallet_synced_height_does_not_re_emit_when_unchanged() { let (mut manager, wallet_id, _addr) = setup_manager_with_wallet(); diff --git a/key-wallet-manager/src/process_block.rs b/key-wallet-manager/src/process_block.rs index 0211b36a5..5a607832d 100644 --- a/key-wallet-manager/src/process_block.rs +++ b/key-wallet-manager/src/process_block.rs @@ -1,6 +1,6 @@ use crate::events::{diff_account_balances, project_derived_addresses, DerivedAddress}; use crate::wallet_interface::{BlockProcessingResult, MempoolTransactionResult, WalletInterface}; -use crate::{WalletEvent, WalletId, WalletManager}; +use crate::{WalletError, WalletEvent, WalletId, WalletManager}; use async_trait::async_trait; use core::fmt::Write as _; use dashcore::ephemerealdata::chain_lock::ChainLock; @@ -381,11 +381,24 @@ impl WalletInterface for WalletM } } - fn truncate_above(&mut self, height: CoreBlockHeight) { + fn truncate_above(&mut self, height: CoreBlockHeight) -> Result<(), WalletError> { + // Every wallet is checked first, so a refused truncation changes none. + for (wallet_id, info) in &self.wallet_infos { + if let Some(chain_lock) = + info.last_applied_chain_lock().filter(|chain_lock| height < chain_lock.block_height) + { + return Err(WalletError::TruncateBelowChainLock { + wallet_id: *wallet_id, + height, + chain_locked: chain_lock.block_height, + }); + } + } + let mut events = Vec::new(); for (wallet_id, info) in self.wallet_infos.iter_mut() { let prior = info.account_balances(); - let truncation = info.truncate_above(height); + let truncation = info.truncate_above(height)?; events.push(WalletEvent::ChainTruncated { wallet_id: *wallet_id, height, @@ -398,6 +411,7 @@ impl WalletInterface for WalletM for event in events { self.emit_event(event); } + Ok(()) } fn update_wallet_last_processed_height( diff --git a/key-wallet-manager/src/test_utils/mock_wallet.rs b/key-wallet-manager/src/test_utils/mock_wallet.rs index a9569f0a8..8d96358a6 100644 --- a/key-wallet-manager/src/test_utils/mock_wallet.rs +++ b/key-wallet-manager/src/test_utils/mock_wallet.rs @@ -1,5 +1,6 @@ use crate::{ - BlockProcessingResult, MempoolTransactionResult, WalletEvent, WalletId, WalletInterface, + BlockProcessingResult, MempoolTransactionResult, WalletError, WalletEvent, WalletId, + WalletInterface, }; use dashcore::ephemerealdata::chain_lock::ChainLock; use dashcore::ephemerealdata::instant_lock::InstantLock; @@ -234,8 +235,9 @@ impl WalletInterface for MockWallet { } } - fn truncate_above(&mut self, height: CoreBlockHeight) { + fn truncate_above(&mut self, height: CoreBlockHeight) -> Result<(), WalletError> { self.synced_height = self.synced_height.min(height); + Ok(()) } fn update_wallet_last_processed_height( @@ -366,8 +368,9 @@ impl WalletInterface for NonMatchingMockWallet { } } - fn truncate_above(&mut self, height: CoreBlockHeight) { + fn truncate_above(&mut self, height: CoreBlockHeight) -> Result<(), WalletError> { self.synced_height = self.synced_height.min(height); + Ok(()) } fn update_wallet_last_processed_height( @@ -545,10 +548,11 @@ impl WalletInterface for MultiMockWallet { } } - fn truncate_above(&mut self, height: CoreBlockHeight) { + fn truncate_above(&mut self, height: CoreBlockHeight) -> Result<(), WalletError> { for state in self.wallets.values_mut() { state.synced_height = state.synced_height.min(height); } + Ok(()) } fn update_wallet_last_processed_height( diff --git a/key-wallet-manager/src/wallet_interface.rs b/key-wallet-manager/src/wallet_interface.rs index 287de3109..9c85bc310 100644 --- a/key-wallet-manager/src/wallet_interface.rs +++ b/key-wallet-manager/src/wallet_interface.rs @@ -2,7 +2,7 @@ //! //! This module defines the trait that SPV clients use to interact with wallets. -use crate::{WalletEvent, WalletId}; +use crate::{WalletError, WalletEvent, WalletId}; use async_trait::async_trait; use dashcore::ephemerealdata::chain_lock::ChainLock; use dashcore::ephemerealdata::instant_lock::InstantLock; @@ -170,7 +170,10 @@ pub trait WalletInterface: Send + Sync + 'static { /// their sync heights, so blocks above it are processed again, and emit a /// [`WalletEvent::ChainTruncated`] per wallet. Called when a fork replaces /// the chain above `height`. - fn truncate_above(&mut self, height: CoreBlockHeight); + /// + /// Fails with [`WalletError::TruncateBelowChainLock`] and changes no wallet + /// when `height` is below any wallet's applied ChainLock. + fn truncate_above(&mut self, height: CoreBlockHeight) -> Result<(), WalletError>; /// Advance one wallet's last-processed height after a block has been applied /// to its state. Implementations must only advance forward. diff --git a/key-wallet/src/error.rs b/key-wallet/src/error.rs index 797a3ff2a..3c5e0d0a2 100644 --- a/key-wallet/src/error.rs +++ b/key-wallet/src/error.rs @@ -53,6 +53,13 @@ pub enum Error { /// What must be supplied instead, e.g. `"extended public key (xpub)"`. required_key: &'static str, }, + /// A truncation below the wallet's applied ChainLock, whose blocks are final. + TruncateBelowChainLock { + /// The height asked to truncate above. + height: u32, + /// The height of the wallet's applied ChainLock. + chain_locked: u32, + }, } impl fmt::Display for Error { @@ -86,6 +93,14 @@ impl fmt::Display for Error { Some(..) argument of the add_*account method.", account_type, required_key ), + Error::TruncateBelowChainLock { + height, + chain_locked, + } => write!( + f, + "Cannot truncate above {}: blocks up to the ChainLock at {} are final", + height, chain_locked + ), } } } diff --git a/key-wallet/src/tests/observed_spent_outpoints_tests.rs b/key-wallet/src/tests/observed_spent_outpoints_tests.rs index ff539c253..faab6e9e9 100644 --- a/key-wallet/src/tests/observed_spent_outpoints_tests.rs +++ b/key-wallet/src/tests/observed_spent_outpoints_tests.rs @@ -663,7 +663,7 @@ fn truncate_above_drops_spends_observed_above_the_fork() { info.record_observed_spends(&spending_tx(&[op_kept]), 100); info.record_observed_spends(&spending_tx(&[op_dropped]), 101); - info.truncate_above(100); + info.truncate_above(100).expect("truncates"); assert!(info.observed_spent_outpoints().contains_key(&op_kept)); assert!(!info.observed_spent_outpoints().contains_key(&op_dropped)); @@ -674,7 +674,7 @@ async fn truncate_above_restores_a_held_output_whose_spend_it_drops() { let (mut ctx, funding, _spend) = spend_first_context(in_block(100, 1)).await; let outpoint = OutPoint::new(funding.txid(), 0); - let truncation = ctx.managed_wallet.truncate_above(150); + let truncation = ctx.managed_wallet.truncate_above(150).expect("truncates"); assert_eq!(truncation.restored_outpoints, vec![outpoint]); let account = ctx.managed_wallet.first_bip44_managed_account().expect("BIP44 account"); diff --git a/key-wallet/src/tests/truncate_above_tests.rs b/key-wallet/src/tests/truncate_above_tests.rs index b1239b9cb..8b661610e 100644 --- a/key-wallet/src/tests/truncate_above_tests.rs +++ b/key-wallet/src/tests/truncate_above_tests.rs @@ -2,12 +2,16 @@ //! what it gives back. use dashcore::blockdata::script::ScriptBuf; +use dashcore::ephemerealdata::chain_lock::ChainLock; use dashcore::hashes::Hash; use dashcore::{BlockHash, OutPoint, Transaction, TxIn, TxOut}; +use test_case::test_case; +use crate::account::ManagedAccountTrait; use crate::test_utils::TestWalletContext; use crate::transaction_checking::{BlockInfo, TransactionContext}; use crate::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface; +use crate::Error; const FUNDING_VALUE: u64 = 1_000_000; @@ -57,7 +61,7 @@ async fn truncate_above_restores_a_coin_from_a_chainlocked_funding() { let (mut ctx, funding, _spend) = fund_and_spend(TransactionContext::InChainLockedBlock(in_block(100))).await; - let truncation = ctx.managed_wallet.truncate_above(100); + let truncation = ctx.managed_wallet.truncate_above(100).expect("truncates"); assert_eq!(truncation.restored_outpoints, vec![OutPoint::new(funding.txid(), 0)]); assert_eq!(ctx.managed_wallet.balance.confirmed(), FUNDING_VALUE); @@ -68,7 +72,7 @@ async fn truncate_above_restores_nothing_the_fork_drops_too() { let (mut ctx, funding, spend) = fund_and_spend(TransactionContext::InBlock(in_block(100))).await; - let truncation = ctx.managed_wallet.truncate_above(99); + let truncation = ctx.managed_wallet.truncate_above(99).expect("truncates"); assert_eq!(truncation.txids.len(), 2); assert!(truncation.txids.contains(&funding.txid())); @@ -77,3 +81,30 @@ async fn truncate_above_restores_nothing_the_fork_drops_too() { assert!(ctx.bip44_account().utxos.is_empty()); assert_eq!(ctx.managed_wallet.balance.total(), 0); } + +#[test_case(99, false; "below the ChainLock")] +#[test_case(100, true; "at the ChainLock")] +#[tokio::test] +async fn truncate_above_never_drops_a_chain_locked_block(height: u32, truncates: bool) { + let (mut ctx, _funding, spend) = + fund_and_spend(TransactionContext::InBlock(in_block(100))).await; + ctx.managed_wallet.update_synced_height(101); + ctx.managed_wallet.metadata.last_applied_chain_lock = Some(ChainLock::dummy(100)); + + let result = ctx.managed_wallet.truncate_above(height); + + if truncates { + assert_eq!(result.expect("truncates").txids, vec![spend.txid()]); + assert_eq!(ctx.managed_wallet.synced_height(), height); + } else { + assert_eq!( + result.expect_err("refuses"), + Error::TruncateBelowChainLock { + height, + chain_locked: 100, + } + ); + assert_eq!(ctx.bip44_account().transactions().len(), 2, "nothing is dropped"); + assert_eq!(ctx.managed_wallet.synced_height(), 101); + } +} diff --git a/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs b/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs index 41d5fc8f5..d2b3e137e 100644 --- a/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs +++ b/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs @@ -15,7 +15,7 @@ use crate::transaction_checking::WalletTransactionChecker; use crate::wallet::managed_wallet_info::transaction_building::AccountTypePreference; use crate::wallet::managed_wallet_info::TransactionRecord; use crate::wallet::ManagedWalletInfo; -use crate::{Network, Utxo, Wallet, WalletCoreBalance}; +use crate::{Error, Network, Utxo, Wallet, WalletCoreBalance}; use dashcore::address::Payload; use dashcore::ephemerealdata::chain_lock::ChainLock; use dashcore::ephemerealdata::instant_lock::InstantLock; @@ -269,7 +269,10 @@ pub trait WalletInfoInterface: Sized + WalletTransactionChecker + ManagedAccount /// observed in them, and the sync heights past `height`. The coins those /// transactions spent are unspent again. Used when a fork replaces the chain /// above `height`. - fn truncate_above(&mut self, height: CoreBlockHeight) -> Truncation; + /// + /// Fails with [`Error::TruncateBelowChainLock`] and changes nothing when + /// `height` is below the applied ChainLock, whose blocks are final. + fn truncate_above(&mut self, height: CoreBlockHeight) -> Result; /// Records whose coinbase maturity threshold lies in /// `(old_height, new_height]`, i.e. coinbase records that just matured @@ -561,7 +564,16 @@ impl WalletInfoInterface for ManagedWalletInfo { self.prune_finalized_observed_spends(); } - fn truncate_above(&mut self, height: CoreBlockHeight) -> Truncation { + fn truncate_above(&mut self, height: CoreBlockHeight) -> Result { + if let Some(chain_lock) = + self.last_applied_chain_lock().filter(|chain_lock| height < chain_lock.block_height) + { + return Err(Error::TruncateBelowChainLock { + height, + chain_locked: chain_lock.block_height, + }); + } + let dropped_spends: BTreeSet = self .observed_spent_outpoints .iter() @@ -596,10 +608,10 @@ impl WalletInfoInterface for ManagedWalletInfo { self.update_balance(); restored_outpoints.sort_unstable(); - Truncation { + Ok(Truncation { txids: txids.into_iter().collect(), restored_outpoints, - } + }) } fn matured_coinbase_records( From dfd062b0d9504d38de0d07695c1aea2c8b02baea Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Tue, 6 Oct 2026 09:50:57 -0700 Subject: [PATCH 4/7] fix(wallet): truncate only the wallets that processed a block above the fork A wallet behind the fork has nothing to drop, so it is left as it is and gets no `ChainTruncated`. The event docs now lower a synced height to the fork height only when it is above it. Co-Authored-By: Claude Opus 5.5 --- dash-spv-ffi/src/callbacks.rs | 12 ++++++------ key-wallet-manager/src/event_tests.rs | 20 ++++++++++++++++++++ key-wallet-manager/src/events.rs | 5 +++-- key-wallet-manager/src/process_block.rs | 4 ++++ key-wallet-manager/src/wallet_interface.rs | 3 ++- 5 files changed, 35 insertions(+), 9 deletions(-) diff --git a/dash-spv-ffi/src/callbacks.rs b/dash-spv-ffi/src/callbacks.rs index cee81796d..d33c1b5c1 100644 --- a/dash-spv-ffi/src/callbacks.rs +++ b/dash-spv-ffi/src/callbacks.rs @@ -829,12 +829,12 @@ pub type OnTransactionsSweptCallback = Option< /// Callback for `WalletEvent::ChainTruncated`. /// -/// Fires once per wallet when a fork replaced the chain above `height` and the -/// wallet dropped what it recorded from the blocks above it. A consumer -/// mirroring wallet state to disk must delete the `txids_count` transactions -/// at `txids` with any UTXO they created, mark the `restored_outpoints_count` -/// coins at `restored_outpoints` unspent, and lower its synced height to -/// `height`. `txids` and `restored_outpoints` are null when their count is 0. +/// Fires once per wallet that processed a block above `height` when a fork +/// replaced the chain above it, and the wallet dropped what it recorded from +/// those blocks. A consumer mirroring wallet state to disk must delete the +/// `txids_count` transactions at `txids` with any UTXO they created, mark the +/// `restored_outpoints_count` coins at `restored_outpoints` unspent, and lower +/// its synced height to `height` when it is above it. `txids` and `restored_outpoints` are null when their count is 0. /// /// All pointer parameters are borrowed and only valid for the duration of the /// callback. `balance` is the wallet's balance *after* the truncation; diff --git a/key-wallet-manager/src/event_tests.rs b/key-wallet-manager/src/event_tests.rs index 23b2f6422..8cf1ff8f5 100644 --- a/key-wallet-manager/src/event_tests.rs +++ b/key-wallet-manager/src/event_tests.rs @@ -1282,9 +1282,28 @@ async fn test_truncate_above_emits_chain_truncated_per_wallet() { } } +#[tokio::test] +async fn test_truncate_above_leaves_a_wallet_behind_the_fork_as_it_is() { + let (mut manager, wallet_id, addr) = setup_manager_with_wallet(); + let wallets = BTreeSet::from([wallet_id]); + let funding = create_tx_paying_to(&addr, 0xcc); + let block = make_block(vec![funding], 0xcc, 1000); + manager.process_block_for_wallets(&block, block.block_hash(), 100, &wallets).await; + manager.update_wallet_synced_height(&wallet_id, 100); + let mut rx = manager.subscribe_events(); + + manager.truncate_above(150).expect("truncates"); + + assert!(drain_events(&mut rx).is_empty(), "no ChainTruncated for a wallet behind the fork"); + let info = manager.get_wallet_info(&wallet_id).unwrap(); + assert_eq!(info.synced_height(), 100); + assert_eq!(info.balance().total(), TX_AMOUNT); +} + #[tokio::test] async fn test_truncate_above_below_a_chain_lock_changes_no_wallet() { let (mut manager, locked_id, _addr) = setup_manager_with_wallet(); + manager.update_wallet_last_processed_height(&locked_id, 200); manager.update_wallet_synced_height(&locked_id, 200); manager.apply_chain_lock(ChainLock::dummy(100)); // Created after the ChainLock, so only `locked_id` refuses. @@ -1295,6 +1314,7 @@ async fn test_truncate_above_below_a_chain_lock_changes_no_wallet() { key_wallet::wallet::initialization::WalletAccountCreationOptions::Default, ) .unwrap(); + manager.update_wallet_last_processed_height(&other_id, 200); manager.update_wallet_synced_height(&other_id, 200); let mut rx = manager.subscribe_events(); diff --git a/key-wallet-manager/src/events.rs b/key-wallet-manager/src/events.rs index c8883946d..8664f7b65 100644 --- a/key-wallet-manager/src/events.rs +++ b/key-wallet-manager/src/events.rs @@ -300,11 +300,12 @@ pub enum WalletEvent { }, /// A fork replaced the chain above `height`, and the wallet dropped what it /// recorded from the blocks above it, as if they were never processed. The - /// new branch is then processed from `height`. + /// new branch is then processed from `height`. Only a wallet that processed + /// a block above `height` gets it. /// /// A consumer mirroring wallet state to disk must delete the removed /// transactions with any UTXO they created, mark the restored coins unspent, - /// and lower its synced height to `height`. + /// and lower its synced height to `height` when it is above it. ChainTruncated { /// ID of the affected wallet. wallet_id: WalletId, diff --git a/key-wallet-manager/src/process_block.rs b/key-wallet-manager/src/process_block.rs index 5a607832d..602f58edc 100644 --- a/key-wallet-manager/src/process_block.rs +++ b/key-wallet-manager/src/process_block.rs @@ -397,6 +397,10 @@ impl WalletInterface for WalletM let mut events = Vec::new(); for (wallet_id, info) in self.wallet_infos.iter_mut() { + // A wallet that processed no block above `height` has nothing to drop. + if info.last_processed_height() <= height { + continue; + } let prior = info.account_balances(); let truncation = info.truncate_above(height)?; events.push(WalletEvent::ChainTruncated { diff --git a/key-wallet-manager/src/wallet_interface.rs b/key-wallet-manager/src/wallet_interface.rs index 9c85bc310..538aa334c 100644 --- a/key-wallet-manager/src/wallet_interface.rs +++ b/key-wallet-manager/src/wallet_interface.rs @@ -168,7 +168,8 @@ pub trait WalletInterface: Send + Sync + 'static { /// Drop what every wallet recorded from blocks above `height`, including /// their sync heights, so blocks above it are processed again, and emit a - /// [`WalletEvent::ChainTruncated`] per wallet. Called when a fork replaces + /// [`WalletEvent::ChainTruncated`] per wallet that processed a block above + /// it. A wallet that did not is left as it is. Called when a fork replaces /// the chain above `height`. /// /// Fails with [`WalletError::TruncateBelowChainLock`] and changes no wallet From ca75f531de92ef1bb7ac7ca957f8c9131aaf206a Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Tue, 6 Oct 2026 09:55:30 -0700 Subject: [PATCH 5/7] fix(wallet): settle a spend promoted into a chainlocked block A spend first seen in the mempool and then in a chainlocked block is final, so its `unsettled_spends` entry is dropped instead of kept forever. Co-Authored-By: Claude Opus 5.5 --- .../managed_core_funds_account.rs | 11 ++++++++++ key-wallet/src/tests/truncate_above_tests.rs | 20 +++++++++++++++++++ .../transaction_checking/wallet_checker.rs | 6 ++++++ 3 files changed, 37 insertions(+) diff --git a/key-wallet/src/managed_account/managed_core_funds_account.rs b/key-wallet/src/managed_account/managed_core_funds_account.rs index d690d8952..ef594b7aa 100644 --- a/key-wallet/src/managed_account/managed_core_funds_account.rs +++ b/key-wallet/src/managed_account/managed_core_funds_account.rs @@ -1020,6 +1020,17 @@ impl ManagedCoreFundsAccount { self.utxos.values().filter(|utxo| utxo.is_spendable(last_processed_height)).collect() } + /// Forget the UTXOs `txid` spent: a chainlocked spend is final, so no fork + /// gives them back. + pub(crate) fn settle_spend(&mut self, txid: &Txid) { + self.unsettled_spends.remove(txid); + } + + #[cfg(test)] + pub(crate) fn unsettled_spends(&self) -> &BTreeMap> { + &self.unsettled_spends + } + /// Promote any `InBlock` records at height `<= cl_height` to /// [`TransactionContext::InChainLockedBlock`] and return the /// promoted txids. diff --git a/key-wallet/src/tests/truncate_above_tests.rs b/key-wallet/src/tests/truncate_above_tests.rs index 8b661610e..6c5442f19 100644 --- a/key-wallet/src/tests/truncate_above_tests.rs +++ b/key-wallet/src/tests/truncate_above_tests.rs @@ -108,3 +108,23 @@ async fn truncate_above_never_drops_a_chain_locked_block(height: u32, truncates: assert_eq!(ctx.managed_wallet.synced_height(), 101); } } + +/// A spend that reaches a chainlocked block after the mempool is final, so +/// nothing is kept to give its coins back. +#[tokio::test] +async fn a_mempool_spend_mined_in_a_chain_locked_block_is_settled() { + let mut ctx = TestWalletContext::new_random(); + let funding = Transaction::dummy(&ctx.receive_address, 0..1, &[FUNDING_VALUE]); + let spend = spend_to_external(&funding); + assert!( + ctx.check_transaction(&funding, TransactionContext::InBlock(in_block(100))) + .await + .is_relevant + ); + assert!(ctx.check_transaction(&spend, TransactionContext::Mempool).await.is_relevant); + assert!(ctx.bip44_account().unsettled_spends().contains_key(&spend.txid())); + + ctx.check_transaction(&spend, TransactionContext::InChainLockedBlock(in_block(101))).await; + + assert!(ctx.bip44_account().unsettled_spends().is_empty()); +} diff --git a/key-wallet/src/transaction_checking/wallet_checker.rs b/key-wallet/src/transaction_checking/wallet_checker.rs index 81f1adf1b..26bee90a6 100644 --- a/key-wallet/src/transaction_checking/wallet_checker.rs +++ b/key-wallet/src/transaction_checking/wallet_checker.rs @@ -78,6 +78,12 @@ impl ManagedWalletInfo { record.update_context(context.clone()); let updated = record.clone(); + if context.is_chain_locked() { + if let crate::managed_account::ManagedAccountRefMut::Funds(funds) = &mut account { + funds.settle_spend(txid); + } + } + // Match the existing finalized-record retention policy after the // event payload has captured the promoted context. #[cfg(not(feature = "keep-finalized-transactions"))] From 392fec37db5098fa3e47f560b802374edd42e003 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Tue, 6 Oct 2026 10:16:31 -0700 Subject: [PATCH 6/7] fix(wallet): keep an InstantSend-locked spend unconfirmed when a fork drops its block An InstantSend lock is final for the txid and the network mines it again, so its record goes back to the mempool, its outputs stay InstantSend-locked and the coins it spent stay spent instead of becoming selectable. `ChainTruncated` reports such transactions in `unconfirmed_txids`. Co-Authored-By: Claude Opus 5.5 --- dash-spv-ffi/src/bin/ffi_cli.rs | 5 +- dash-spv-ffi/src/callbacks.rs | 19 +++++- key-wallet-manager/src/event_tests.rs | 2 + key-wallet-manager/src/events.rs | 13 +++- key-wallet-manager/src/process_block.rs | 1 + .../managed_core_funds_account.rs | 35 ++++++++--- key-wallet/src/tests/truncate_above_tests.rs | 59 +++++++++++++++++++ key-wallet/src/utxo.rs | 8 +++ .../wallet_info_interface.rs | 25 ++++++-- 9 files changed, 147 insertions(+), 20 deletions(-) diff --git a/dash-spv-ffi/src/bin/ffi_cli.rs b/dash-spv-ffi/src/bin/ffi_cli.rs index 7812ee9cc..1fc860cc2 100644 --- a/dash-spv-ffi/src/bin/ffi_cli.rs +++ b/dash-spv-ffi/src/bin/ffi_cli.rs @@ -271,6 +271,8 @@ extern "C" fn on_chain_truncated( height: u32, _txids: *const [u8; 32], txids_count: usize, + _unconfirmed_txids: *const [u8; 32], + unconfirmed_txids_count: usize, _restored_outpoints: *const dash_spv_ffi::FFIOutPoint, restored_outpoints_count: usize, balance: *const FFIBalance, @@ -280,10 +282,11 @@ extern "C" fn on_chain_truncated( ) { let b = read_balance(balance); println!( - "[Wallet] Chain truncated: wallet={}..., height={}, removed={}, restored={}, balance[confirmed={}, unconfirmed={}]", + "[Wallet] Chain truncated: wallet={}..., height={}, removed={}, unconfirmed={}, restored={}, balance[confirmed={}, unconfirmed={}]", short_wallet(wallet_id), height, txids_count, + unconfirmed_txids_count, restored_outpoints_count, b.confirmed, b.unconfirmed, diff --git a/dash-spv-ffi/src/callbacks.rs b/dash-spv-ffi/src/callbacks.rs index d33c1b5c1..bb643bbf7 100644 --- a/dash-spv-ffi/src/callbacks.rs +++ b/dash-spv-ffi/src/callbacks.rs @@ -832,9 +832,12 @@ pub type OnTransactionsSweptCallback = Option< /// Fires once per wallet that processed a block above `height` when a fork /// replaced the chain above it, and the wallet dropped what it recorded from /// those blocks. A consumer mirroring wallet state to disk must delete the -/// `txids_count` transactions at `txids` with any UTXO they created, mark the +/// `txids_count` transactions at `txids` with any UTXO they created, move the +/// `unconfirmed_txids_count` InstantSend-locked transactions at +/// `unconfirmed_txids` back to the mempool with their UTXOs, mark the /// `restored_outpoints_count` coins at `restored_outpoints` unspent, and lower -/// its synced height to `height` when it is above it. `txids` and `restored_outpoints` are null when their count is 0. +/// its synced height to `height` when it is above it. `txids`, +/// `unconfirmed_txids` and `restored_outpoints` are null when their count is 0. /// /// All pointer parameters are borrowed and only valid for the duration of the /// callback. `balance` is the wallet's balance *after* the truncation; @@ -846,6 +849,8 @@ pub type OnChainTruncatedCallback = Option< height: u32, txids: *const [u8; 32], txids_count: usize, + unconfirmed_txids: *const [u8; 32], + unconfirmed_txids_count: usize, restored_outpoints: *const FFIOutPoint, restored_outpoints_count: usize, balance: *const FFIBalance, @@ -1198,6 +1203,7 @@ impl FFIWalletEventCallbacks { wallet_id, height, txids, + unconfirmed_txids, restored_outpoints, balance, account_balances, @@ -1211,6 +1217,13 @@ impl FFIWalletEventCallbacks { } else { raw_txids.as_ptr() }; + let raw_unconfirmed_txids: Vec<[u8; 32]> = + unconfirmed_txids.iter().map(|t| t.to_byte_array()).collect(); + let unconfirmed_txids_ptr = if raw_unconfirmed_txids.is_empty() { + ptr::null() + } else { + raw_unconfirmed_txids.as_ptr() + }; let ffi_restored_outpoints = FFIOutPoint::from_slice(restored_outpoints); let restored_outpoints_ptr = if ffi_restored_outpoints.is_empty() { ptr::null() @@ -1230,6 +1243,8 @@ impl FFIWalletEventCallbacks { *height, txids_ptr, raw_txids.len(), + unconfirmed_txids_ptr, + raw_unconfirmed_txids.len(), restored_outpoints_ptr, ffi_restored_outpoints.len(), &ffi_balance as *const FFIBalance, diff --git a/key-wallet-manager/src/event_tests.rs b/key-wallet-manager/src/event_tests.rs index 8cf1ff8f5..6cb5aa0de 100644 --- a/key-wallet-manager/src/event_tests.rs +++ b/key-wallet-manager/src/event_tests.rs @@ -1267,6 +1267,7 @@ async fn test_truncate_above_emits_chain_truncated_per_wallet() { wallet_id: wid, height, txids, + unconfirmed_txids, restored_outpoints, balance, account_balances, @@ -1274,6 +1275,7 @@ async fn test_truncate_above_emits_chain_truncated_per_wallet() { assert_eq!(*wid, wallet_id); assert_eq!(*height, 100); assert_eq!(txids, &vec![spend.txid()]); + assert!(unconfirmed_txids.is_empty()); assert_eq!(restored_outpoints, &vec![OutPoint::new(funding.txid(), 0)]); assert_eq!(balance.total(), TX_AMOUNT); assert_eq!(account_balances.values().map(|b| b.total()).sum::(), TX_AMOUNT); diff --git a/key-wallet-manager/src/events.rs b/key-wallet-manager/src/events.rs index 8664f7b65..9c965f2cb 100644 --- a/key-wallet-manager/src/events.rs +++ b/key-wallet-manager/src/events.rs @@ -304,8 +304,9 @@ pub enum WalletEvent { /// a block above `height` gets it. /// /// A consumer mirroring wallet state to disk must delete the removed - /// transactions with any UTXO they created, mark the restored coins unspent, - /// and lower its synced height to `height` when it is above it. + /// transactions with any UTXO they created, move the unconfirmed ones back + /// to the mempool with their UTXOs, mark the restored coins unspent, and + /// lower its synced height to `height` when it is above it. ChainTruncated { /// ID of the affected wallet. wallet_id: WalletId, @@ -313,6 +314,10 @@ pub enum WalletEvent { height: CoreBlockHeight, /// Transactions removed: they were recorded in blocks above `height`. txids: Vec, + /// InstantSend-locked transactions recorded in blocks above `height`, + /// kept as unconfirmed: the network mines them again, so the coins they + /// spent stay spent and their outputs stay InstantSend-locked. + unconfirmed_txids: Vec, /// Coins the removed transactions spent, unspent again. restored_outpoints: Vec, /// Wallet balance after the truncation. @@ -511,15 +516,17 @@ impl fmt::Display for WalletEvent { WalletEvent::ChainTruncated { height, txids, + unconfirmed_txids, restored_outpoints, balance, account_balances, .. } => write!( f, - "ChainTruncated(height={}, removed={}, restored={}, balance={}, account_balances={})", + "ChainTruncated(height={}, removed={}, unconfirmed={}, restored={}, balance={}, account_balances={})", height, txids.len(), + unconfirmed_txids.len(), restored_outpoints.len(), balance, format_account_balances(account_balances), diff --git a/key-wallet-manager/src/process_block.rs b/key-wallet-manager/src/process_block.rs index 602f58edc..987792c7d 100644 --- a/key-wallet-manager/src/process_block.rs +++ b/key-wallet-manager/src/process_block.rs @@ -407,6 +407,7 @@ impl WalletInterface for WalletM wallet_id: *wallet_id, height, txids: truncation.txids, + unconfirmed_txids: truncation.unconfirmed_txids, restored_outpoints: truncation.restored_outpoints, balance: info.balance(), account_balances: diff_account_balances(&prior, &info.account_balances()), diff --git a/key-wallet/src/managed_account/managed_core_funds_account.rs b/key-wallet/src/managed_account/managed_core_funds_account.rs index ef594b7aa..985bd3fec 100644 --- a/key-wallet/src/managed_account/managed_core_funds_account.rs +++ b/key-wallet/src/managed_account/managed_core_funds_account.rs @@ -525,18 +525,32 @@ impl ManagedCoreFundsAccount { /// transactions the fork keeps, along with the ones held in /// `spent_before_funded` for a spend in `dropped_spends`, the spends observed /// above `height`. + /// + /// A transaction in `instant_locked` is final for its txid and is mined + /// again, so it is kept as unconfirmed instead: its outputs stay, and the + /// coins it spent stay spent. pub(crate) fn truncate_above( &mut self, height: CoreBlockHeight, dropped_spends: &BTreeSet, + instant_locked: &HashSet, ) -> Truncation { - let dropped: BTreeSet = self + let (unconfirmed, dropped): (BTreeSet, BTreeSet) = self .keys .transactions() .values() .filter(|record| record.height().is_some_and(|block| block > height)) .map(|record| record.txid) - .collect(); + .partition(|txid| instant_locked.contains(txid)); + for txid in &unconfirmed { + if let Some(record) = self.keys.transactions_mut().get_mut(txid) { + record.update_context(TransactionContext::Mempool); + } + } + for utxo in self.utxos.values_mut().filter(|utxo| unconfirmed.contains(&utxo.outpoint.txid)) + { + utxo.mark_unconfirmed_instant_locked(); + } let mut spent: Vec = dropped .iter() .filter_map(|txid| self.unsettled_spends.remove(txid)) @@ -553,12 +567,16 @@ impl ManagedCoreFundsAccount { if dropped.contains(&outpoint.txid) || self.spent_outpoints.contains(&outpoint) { continue; } - // Spent in a block, so funded in one the fork keeps. - utxo.is_confirmed = true; - if let Some(height) = - self.keys.transactions().get(&outpoint.txid).and_then(|parent| parent.height()) - { - utxo.height = height; + if unconfirmed.contains(&outpoint.txid) { + utxo.mark_unconfirmed_instant_locked(); + } else { + // Spent in a block, so funded in one the fork keeps. + utxo.is_confirmed = true; + if let Some(height) = + self.keys.transactions().get(&outpoint.txid).and_then(|parent| parent.height()) + { + utxo.height = height; + } } self.utxos.insert(outpoint, utxo); restored.push(outpoint); @@ -568,6 +586,7 @@ impl ManagedCoreFundsAccount { } Truncation { txids: dropped.into_iter().collect(), + unconfirmed_txids: unconfirmed.into_iter().collect(), restored_outpoints: restored, } } diff --git a/key-wallet/src/tests/truncate_above_tests.rs b/key-wallet/src/tests/truncate_above_tests.rs index 6c5442f19..b62cfc8e4 100644 --- a/key-wallet/src/tests/truncate_above_tests.rs +++ b/key-wallet/src/tests/truncate_above_tests.rs @@ -3,6 +3,7 @@ use dashcore::blockdata::script::ScriptBuf; use dashcore::ephemerealdata::chain_lock::ChainLock; +use dashcore::ephemerealdata::instant_lock::InstantLock; use dashcore::hashes::Hash; use dashcore::{BlockHash, OutPoint, Transaction, TxIn, TxOut}; use test_case::test_case; @@ -128,3 +129,61 @@ async fn a_mempool_spend_mined_in_a_chain_locked_block_is_settled() { assert!(ctx.bip44_account().unsettled_spends().is_empty()); } + +/// An InstantSend-locked spend is final for its txid and the network mines it +/// again, so a fork dropping its block keeps it as unconfirmed: the coin it +/// spent is not handed back for coin selection, and its change stays. +#[test_case(true; "InstantSend-locked")] +#[test_case(false; "not locked")] +#[tokio::test] +async fn truncate_above_keeps_an_instant_locked_spend_unconfirmed(instant_locked: bool) { + const CHANGE_VALUE: u64 = 400_000; + let mut ctx = TestWalletContext::new_random(); + let funding = Transaction::dummy(&ctx.receive_address, 0..1, &[FUNDING_VALUE]); + let mut spend = spend_to_external(&funding); + spend.output[0].value -= CHANGE_VALUE; + spend.output.push(TxOut { + value: CHANGE_VALUE, + script_pubkey: ctx.receive_address.script_pubkey(), + }); + let funding_outpoint = OutPoint::new(funding.txid(), 0); + let change_outpoint = OutPoint::new(spend.txid(), 1); + assert!( + ctx.check_transaction(&funding, TransactionContext::InBlock(in_block(100))) + .await + .is_relevant + ); + if instant_locked { + let lock = InstantLock { + txid: spend.txid(), + ..InstantLock::dummy(0..1) + }; + ctx.check_transaction(&spend, TransactionContext::InstantSend(lock)).await; + } + ctx.check_transaction(&spend, TransactionContext::InBlock(in_block(101))).await; + + let truncation = ctx.managed_wallet.truncate_above(100).expect("truncates"); + + let account = ctx.bip44_account(); + if instant_locked { + assert!(truncation.txids.is_empty()); + assert_eq!(truncation.unconfirmed_txids, vec![spend.txid()]); + assert!(truncation.restored_outpoints.is_empty()); + assert!(!account.utxos.contains_key(&funding_outpoint), "the spent coin stays spent"); + let record = &account.transactions()[&spend.txid()]; + assert!(matches!(record.context, TransactionContext::Mempool)); + let change = &account.utxos[&change_outpoint]; + assert!(change.is_instantlocked && !change.is_confirmed); + + // Mined again on the new branch, it confirms as any mempool transaction. + ctx.check_transaction(&spend, TransactionContext::InBlock(in_block(102))).await; + let account = ctx.bip44_account(); + assert_eq!(account.transactions()[&spend.txid()].height(), Some(102)); + assert!(account.utxos[&change_outpoint].is_confirmed); + } else { + assert_eq!(truncation.txids, vec![spend.txid()]); + assert!(truncation.unconfirmed_txids.is_empty()); + assert_eq!(truncation.restored_outpoints, vec![funding_outpoint]); + assert!(!account.utxos.contains_key(&change_outpoint)); + } +} diff --git a/key-wallet/src/utxo.rs b/key-wallet/src/utxo.rs index 5672f85be..879813d08 100644 --- a/key-wallet/src/utxo.rs +++ b/key-wallet/src/utxo.rs @@ -63,6 +63,14 @@ impl Utxo { } } + /// Back to an InstantSend-locked output of a transaction not in a block, + /// as when a fork drops the block of an InstantSend-locked transaction. + pub(crate) fn mark_unconfirmed_instant_locked(&mut self) { + self.is_confirmed = false; + self.is_instantlocked = true; + self.height = 0; + } + /// Get the value of this UTXO in satoshis pub fn value(&self) -> u64 { self.txout.value diff --git a/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs b/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs index d2b3e137e..f46864206 100644 --- a/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs +++ b/key-wallet/src/wallet/managed_wallet_info/wallet_info_interface.rs @@ -50,7 +50,11 @@ pub struct ApplyChainLockOutcome { pub struct Truncation { /// Transactions removed: they were recorded in blocks above the height. pub txids: Vec, - /// Coins those transactions spent, unspent again. + /// InstantSend-locked transactions recorded in blocks above the height, + /// kept as unconfirmed: the network mines them again, so the coins they + /// spent stay spent. + pub unconfirmed_txids: Vec, + /// Coins the removed transactions spent, unspent again. pub restored_outpoints: Vec, } @@ -583,21 +587,29 @@ impl WalletInfoInterface for ManagedWalletInfo { self.observed_spent_outpoints.retain(|outpoint, _| !dropped_spends.contains(outpoint)); let mut txids = BTreeSet::new(); + let mut unconfirmed_txids = BTreeSet::new(); let mut restored_outpoints = Vec::new(); for account in self.accounts.all_accounts_mut() { match account { ManagedAccountRefMut::Funds(funds) => { - let truncation = funds.truncate_above(height, &dropped_spends); + let truncation = + funds.truncate_above(height, &dropped_spends, &self.instant_send_locks); txids.extend(truncation.txids); + unconfirmed_txids.extend(truncation.unconfirmed_txids); restored_outpoints.extend(truncation.restored_outpoints); } ManagedAccountRefMut::Keys(keys) => { keys.transactions_mut().retain(|txid, record| { - let dropped = record.height().is_some_and(|block| block > height); - if dropped { - txids.insert(*txid); + if record.height().is_none_or(|block| block <= height) { + return true; } - !dropped + if self.instant_send_locks.contains(txid) { + record.update_context(TransactionContext::Mempool); + unconfirmed_txids.insert(*txid); + return true; + } + txids.insert(*txid); + false }); } } @@ -610,6 +622,7 @@ impl WalletInfoInterface for ManagedWalletInfo { restored_outpoints.sort_unstable(); Ok(Truncation { txids: txids.into_iter().collect(), + unconfirmed_txids: unconfirmed_txids.into_iter().collect(), restored_outpoints, }) } From 3c0da64d3112069d9f78deeaba99b1d23470e756 Mon Sep 17 00:00:00 2001 From: Borja Castellano Date: Tue, 6 Oct 2026 10:34:01 -0700 Subject: [PATCH 7/7] fix(wallet): restore a spent-first output when a fork drops its spend An output spent before it was funded, whether held in `spent_before_funded` or spent by a transaction the account recorded first, is now kept in `unsettled_spends` under its spend, so a fork dropping the spend gives it back. Co-Authored-By: Claude Opus 5.5 --- .../managed_core_funds_account.rs | 32 +++++++++++- .../tests/observed_spent_outpoints_tests.rs | 51 ++++++++++++++++++- 2 files changed, 80 insertions(+), 3 deletions(-) diff --git a/key-wallet/src/managed_account/managed_core_funds_account.rs b/key-wallet/src/managed_account/managed_core_funds_account.rs index 985bd3fec..ece767eb3 100644 --- a/key-wallet/src/managed_account/managed_core_funds_account.rs +++ b/key-wallet/src/managed_account/managed_core_funds_account.rs @@ -200,6 +200,19 @@ impl ManagedCoreFundsAccount { self.spent_outpoints.contains(outpoint) } + /// The recorded transaction spending `outpoint`, unless a ChainLock made it + /// final and no fork can drop it. + fn unsettled_spender_of(&self, outpoint: &OutPoint) -> Option { + self.keys + .transactions() + .values() + .find(|record| { + record.transaction.input.iter().any(|input| input.previous_output == *outpoint) + }) + .filter(|record| !record.context.is_chain_locked()) + .map(|record| record.txid) + } + /// Collect the outpoints among `tx`'s inputs that this account holds as a /// final UTXO — confirmed, InstantSend-locked, or trusted. /// @@ -335,6 +348,19 @@ impl ManagedCoreFundsAccount { outpoint = %outpoint, "Skipping UTXO already spent by previously processed transaction" ); + // Held under its spend, so a fork dropping the spend + // gives it back. + if let Some(spender) = self.unsettled_spender_of(&outpoint) { + self.unsettled_spends.entry(spender).or_default().push( + Utxo::new( + outpoint, + output.clone(), + addr.clone(), + context.block_info().map_or(0, |i| i.height), + tx.is_coin_base(), + ), + ); + } continue; } @@ -406,7 +432,11 @@ impl ManagedCoreFundsAccount { self.reservations.release(tx.input.iter().map(|input| &input.previous_output)); for input in &tx.input { self.spent_outpoints.insert(input.previous_output); - self.spent_before_funded.remove(&input.previous_output); + // An output held as spent before it was funded is spent here + // too, so a fork dropping this spend gives it back as well. + if let Some(held) = self.spent_before_funded.remove(&input.previous_output) { + self.unsettled_spends.entry(txid).or_default().push(held); + } if let Some(spent) = self.utxos.remove(&input.previous_output) { tracing::debug!( diff --git a/key-wallet/src/tests/observed_spent_outpoints_tests.rs b/key-wallet/src/tests/observed_spent_outpoints_tests.rs index faab6e9e9..1dd8d42b0 100644 --- a/key-wallet/src/tests/observed_spent_outpoints_tests.rs +++ b/key-wallet/src/tests/observed_spent_outpoints_tests.rs @@ -33,6 +33,7 @@ use crate::wallet::managed_wallet_info::managed_account_operations::ManagedAccou use crate::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface; use crate::wallet::ManagedWalletInfo; use crate::AccountType; +use test_case::test_case; /// A transaction whose inputs spend exactly `spent`, with no outputs. Enough to /// drive `record_observed_spends` (reads inputs) and the removal guard. @@ -669,10 +670,16 @@ fn truncate_above_drops_spends_observed_above_the_fork() { assert!(!info.observed_spent_outpoints().contains_key(&op_dropped)); } +#[test_case(false; "held")] +#[test_case(true; "spend replayed after the funding")] #[tokio::test] -async fn truncate_above_restores_a_held_output_whose_spend_it_drops() { - let (mut ctx, funding, _spend) = spend_first_context(in_block(100, 1)).await; +async fn truncate_above_restores_a_held_output_whose_spend_it_drops(replay_spend: bool) { + let (mut ctx, funding, spend) = spend_first_context(in_block(100, 1)).await; let outpoint = OutPoint::new(funding.txid(), 0); + if replay_spend { + // As `reapply_heights` does once the funding is known. + assert!(ctx.check_transaction(&spend, in_block(200, 2)).await.is_relevant); + } let truncation = ctx.managed_wallet.truncate_above(150).expect("truncates"); @@ -683,3 +690,43 @@ async fn truncate_above_restores_a_held_output_whose_spend_it_drops() { assert!(utxo.is_confirmed); assert_eq!(ctx.managed_wallet.balance.total(), SPEND_FIRST_FUNDING_VALUE); } + +/// A spend this account recorded before its funding, through a change output, +/// leaves the funding output out of `utxos`. A fork dropping the spend gives +/// it back. +#[tokio::test] +async fn truncate_above_restores_an_output_the_account_saw_spent_first() { + use dashcore::blockdata::script::ScriptBuf; + use dashcore::TxOut; + + const CHANGE_VALUE: u64 = 100_000; + let mut ctx = TestWalletContext::new_random(); + let funding = Transaction::dummy(&ctx.receive_address, 0..1, &[SPEND_FIRST_FUNDING_VALUE]); + let outpoint = OutPoint::new(funding.txid(), 0); + let spend = Transaction { + version: 2, + lock_time: 0, + input: vec![TxIn { + previous_output: outpoint, + script_sig: ScriptBuf::new(), + sequence: 0xffffffff, + witness: dashcore::Witness::new(), + }], + output: vec![TxOut { + value: CHANGE_VALUE, + script_pubkey: ctx.receive_address.script_pubkey(), + }], + special_transaction_payload: None, + }; + assert!(ctx.check_transaction(&spend, in_block(200, 2)).await.is_relevant); + assert!(ctx.check_transaction(&funding, in_block(100, 1)).await.is_relevant); + let account = ctx.managed_wallet.first_bip44_managed_account().expect("BIP44 account"); + assert!(!account.utxos.contains_key(&outpoint), "the funding output is spent"); + + let truncation = ctx.managed_wallet.truncate_above(150).expect("truncates"); + + assert_eq!(truncation.restored_outpoints, vec![outpoint]); + let account = ctx.managed_wallet.first_bip44_managed_account().expect("BIP44 account"); + assert!(account.utxos.get(&outpoint).expect("a UTXO again").is_confirmed); + assert_eq!(ctx.managed_wallet.balance.total(), SPEND_FIRST_FUNDING_VALUE); +}