From 07ae5566b5fd0f8648e081d85141e986ff56ebfa Mon Sep 17 00:00:00 2001 From: Bartosz Rozwarski Date: Thu, 29 Oct 2026 12:16:43 +0100 Subject: [PATCH 1/3] fix(platform-wallet): let a shielded sync pass observe cancellation A shielded sync pass had no cancellation point: only the loop's sleep between passes watched the registry token, so `stop()` returned at once but `quiesce()` waited for the whole pass (10 s, then code 27) and `destroy` for up to 37 s on measured iOS teardowns. The manager now owns a pass-cancellation token that `stop()` cancels and rotates, so passes dispatched from host threads (`sync_now(true)`, `sync_wallet`) are cancellable too. The coordinator checks it before every network step, and the note scan selects on it between batches. A cancelled scan drops its in-flight fetches and then finalizes the prefix it consumed exactly as a completed pass would (checkpoint, note saves, spend replay, watermark) and flushes that to the persisters, so the store and the host mirror stay consistent; `quiesce` keeps its barrier by waiting for that finalize. The caught-up cooldown is not stamped for a cancelled pass. Closes #5200. Co-Authored-By: Claude Fable 5.1 --- .../examples/shielded_sync.rs | 4 +- .../examples/shielded_sync_paloma.rs | 4 +- .../src/manager/shielded_sync.rs | 115 +++++- .../src/wallet/shielded/balance_tests.rs | 12 +- .../src/wallet/shielded/coordinator.rs | 82 +++- .../src/wallet/shielded/sync.rs | 386 +++++++++++------- .../src/wallet/shielded/sync/cancel_tests.rs | 217 ++++++++++ 7 files changed, 645 insertions(+), 175 deletions(-) create mode 100644 packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs diff --git a/packages/rs-platform-wallet/examples/shielded_sync.rs b/packages/rs-platform-wallet/examples/shielded_sync.rs index d4e84f45234..5abfc7d8706 100644 --- a/packages/rs-platform-wallet/examples/shielded_sync.rs +++ b/packages/rs-platform-wallet/examples/shielded_sync.rs @@ -267,7 +267,9 @@ async fn run_wallet_sync_test(wallet: WalletIndex) { // --- 6. Run a single sync pass through the coordinator. `force = true` // skips the cooldown gate so the example runs immediately after // the chain comes up. --- - let summary = coordinator.sync(true).await; + let summary = coordinator + .sync(true, &tokio_util::sync::CancellationToken::new()) + .await; eprintln!("{:?}: sync summary: {:?}", wallet, summary); // --- 7. Assert the pass completed cleanly for our wallet: a genuine diff --git a/packages/rs-platform-wallet/examples/shielded_sync_paloma.rs b/packages/rs-platform-wallet/examples/shielded_sync_paloma.rs index 762280b0eb0..364569a58fa 100644 --- a/packages/rs-platform-wallet/examples/shielded_sync_paloma.rs +++ b/packages/rs-platform-wallet/examples/shielded_sync_paloma.rs @@ -258,7 +258,9 @@ async fn main() { .expect("bind_shielded"); // --- 5. Run one sync pass with cooldown bypassed. --- - let summary = coordinator.sync(true).await; + let summary = coordinator + .sync(true, &tokio_util::sync::CancellationToken::new()) + .await; eprintln!("sync summary: {:?}", summary); // --- 6. Assert the pass ran cleanly and actually walked the diff --git a/packages/rs-platform-wallet/src/manager/shielded_sync.rs b/packages/rs-platform-wallet/src/manager/shielded_sync.rs index be4ece5856a..1a998a06070 100644 --- a/packages/rs-platform-wallet/src/manager/shielded_sync.rs +++ b/packages/rs-platform-wallet/src/manager/shielded_sync.rs @@ -33,6 +33,7 @@ use std::sync::{ use std::time::{Duration, SystemTime, UNIX_EPOCH}; use tokio::sync::RwLock; +use tokio_util::sync::CancellationToken; use dash_async::ThreadRegistry; @@ -160,6 +161,14 @@ pub struct ShieldedSyncManager { /// giving Clear / stop a real "no more host-visible mutations" /// barrier that cancel-only [`stop`](Self::stop) does not provide. quiescing: QuiesceGate, + /// Parent of the cancellation token every pass runs under. The + /// manager owns it rather than reusing the loop's registry token so a + /// pass dispatched directly from a host thread (`sync_now(true)`, + /// `sync_wallet`) is cancellable too: [`stop`](Self::stop) cancels the + /// current parent and rotates in a fresh one, so passes started after + /// the stop are not born cancelled. Held only for a handful of + /// instructions, never across an `.await`. + pass_cancel: std::sync::Mutex, /// Unix seconds of the last completed pass. `0` = never. last_sync_unix: AtomicU64, } @@ -177,10 +186,20 @@ impl ShieldedSyncManager { interval_secs: AtomicU64::new(DEFAULT_SYNC_INTERVAL_SECS), is_syncing: AtomicBool::new(false), quiescing: QuiesceGate::default(), + pass_cancel: std::sync::Mutex::new(CancellationToken::new()), last_sync_unix: AtomicU64::new(0), } } + /// A child of the current pass-cancellation parent. Fires when + /// [`stop`](Self::stop) runs before the pass that took it finishes. + pub(crate) fn pass_token(&self) -> CancellationToken { + self.pass_cancel + .lock() + .expect("shielded pass-cancel mutex poisoned") + .child_token() + } + /// Set the polling interval. Clamped to a minimum of 1s. /// /// The running loop picks this up on its next sleep. @@ -277,15 +296,28 @@ impl ShieldedSyncManager { ); } - /// Stop the background sync loop. No-op if not running. + /// Stop the background sync loop and cancel the in-flight pass, if + /// any. Returns immediately. /// - /// **Cancel-only**: this requests cancellation and returns - /// immediately. A pass already inside `sync_now` / - /// `coordinator.sync()` keeps running to completion (including its - /// persister-callback fan-out). For a real "nothing is running and - /// nothing more will be persisted" barrier — required by Clear, - /// unregister, and rebind — use [`quiesce`](Self::quiesce). + /// A pass already inside `coordinator.sync()` observes the + /// cancellation at its next batch or network boundary, finalizes the + /// prefix it consumed and flushes that to the persisters, then + /// releases `is_syncing`. So this is **not** a barrier: for a real + /// "nothing is running and nothing more will be persisted" guarantee + /// — required by Clear, unregister, and rebind — use + /// [`quiesce`](Self::quiesce), which calls this first and then waits + /// for that finalize. pub fn stop(&self) { + // Cancel the current pass parent and rotate in a fresh one, so a + // pass that starts after this stop runs under an uncancelled token. + let previous = { + let mut parent = self + .pass_cancel + .lock() + .expect("shielded pass-cancel mutex poisoned"); + std::mem::replace(&mut *parent, CancellationToken::new()) + }; + previous.cancel(); self.registry.cancel(WalletWorker::ShieldedSync); } @@ -396,6 +428,13 @@ impl ShieldedSyncManager { // so a failed pass can never wedge `quiesce()`'s drain. let _slot = SyncSlotGuard(&self.is_syncing); + // Take the pass token BEFORE the gate check. `drain_pass` takes its + // hold (closing the gate) and only then calls `stop()` (rotating + // the token), so a pass that took its token before the rotation + // is on the cancelled lineage, and one that took it after sees the + // closed gate below. Either way no pass runs past a drain. + let pass_cancel = self.pass_token(); + // A `quiesce()` may have raised the gate between our CAS and // here; if so, release the slot and bail without running a pass // so the drain can complete and Clear/stop get a true barrier. @@ -419,11 +458,20 @@ impl ShieldedSyncManager { }; let mut summary = if let Some(coordinator) = coordinator_snapshot { - coordinator.sync(force).await + coordinator.sync(force, &pass_cancel).await } else { ShieldedSyncPassSummary::default() }; + // A pass cancelled before it did anything is not a completed pass: + // no timestamp, no completion event (same as losing the slot CAS). + // A cancelled pass that did consume batches has flushed them to the + // persisters, so it is reported like any other so the host applies + // the deltas. + if pass_cancel.is_cancelled() && summary.is_empty() { + return summary; + } + let now = SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_secs()) @@ -492,13 +540,16 @@ impl ShieldedSyncManager { // so a failed pass can never wedge `quiesce()`'s drain. let _slot = SyncSlotGuard(&self.is_syncing); + // Token before the gate check — see `sync_now` for the ordering. + let pass_cancel = self.pass_token(); + // Bail if a `quiesce()` raised the gate after our CAS (see // `sync_now`) so the drain barrier holds. if self.quiescing.is_closed() { return Ok(None); } - let pass = coordinator.sync(force).await; + let pass = coordinator.sync(force, &pass_cancel).await; // Extract this wallet's slice from the network-wide pass // summary. If the wallet is registered, we'll get back an @@ -670,4 +721,50 @@ mod tests { "a direct pass leaves the latch alone" ); } + + /// `stop()` cancels the token the in-flight pass runs under and + /// rotates in a fresh one, so a pass started after the stop is not + /// born cancelled (dashpay/platform#5200). + #[tokio::test] + async fn should_cancel_current_pass_token_on_stop_and_rotate() { + let (mgr, _counter) = make_manager(); + + let in_flight = mgr.pass_token(); + assert!(!in_flight.is_cancelled()); + + mgr.stop(); + assert!(in_flight.is_cancelled(), "stop cancels the running pass"); + assert!( + !mgr.pass_token().is_cancelled(), + "a pass after the stop runs under a fresh token" + ); + } + + /// A pass that observes its token lets `quiesce()` drain right away, + /// instead of after the whole pass or the drain budget: the stop + /// inside the drain cancels the pass, the pass releases the slot, the + /// drain sees the falling edge. + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn should_quiesce_promptly_when_pass_observes_cancellation() { + let (mgr, _counter) = make_manager(); + + // Stand-in for a pass parked in a network await that checks its + // token: holds the slot until the manager cancels it. + let holder = Arc::clone(&mgr); + let pass = tokio::spawn(async move { + wedge_sync_slot(&holder); + let _slot = SyncSlotGuard(&holder.is_syncing); + holder.pass_token().cancelled().await; + }); + while !mgr.is_syncing() { + tokio::time::sleep(Duration::from_millis(5)).await; + } + + let drained = tokio::time::timeout(Duration::from_secs(2), mgr.quiesce()) + .await + .expect("quiesce must not wait out the drain budget"); + assert!(drained, "the cancelled pass must drain"); + assert!(!mgr.is_syncing()); + pass.await.expect("pass task"); + } } diff --git a/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs b/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs index 30a459ce40f..b39ec66673e 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs @@ -222,7 +222,9 @@ async fn local_balance_successful_empty_scan_marks_known_zero() { ready(&coordinator, wallet).await.accounts[&0].source, ShieldedBalanceSource::NoHistory ); - let outcome = coordinator.sync(true).await; + let outcome = coordinator + .sync(true, &tokio_util::sync::CancellationToken::new()) + .await; assert_eq!( outcome.success_count(), 1, @@ -249,7 +251,9 @@ async fn local_balance_successful_scan_covers_unhydrated_registration() { coordinator.local_balance_snapshot(wallet).await.unwrap(), ShieldedLocalBalanceState::RestoreIncomplete ); - let outcome = coordinator.sync(true).await; + let outcome = coordinator + .sync(true, &tokio_util::sync::CancellationToken::new()) + .await; assert_eq!(outcome.success_count(), 1, "{outcome:?}"); let account = ready(&coordinator, wallet).await.accounts[&0]; assert_eq!(account.spendable_credits, 0); @@ -300,7 +304,9 @@ async fn local_balance_recovers_after_failed_clear_and_completed_scan() { coordinator.local_balance_snapshot(wallet).await.unwrap(), ShieldedLocalBalanceState::RestoreIncomplete ); - let outcome = coordinator.sync(true).await; + let outcome = coordinator + .sync(true, &tokio_util::sync::CancellationToken::new()) + .await; assert_eq!(outcome.success_count(), 1, "{outcome:?}"); let account = ready(&coordinator, wallet).await.accounts[&0]; assert_eq!(account.spendable_credits, 900); diff --git a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs index 731b35e51ad..90c6d0f7219 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs @@ -55,6 +55,8 @@ use std::collections::{BTreeMap, HashSet}; use std::path::PathBuf; use std::sync::Arc; +use tokio_util::sync::CancellationToken; + /// Callback fired once per chunk during a coordinator sync pass — /// the **"downloaded"** progress signal. /// Arguments: `(cumulative_scanned, latest_block_height)`. Forwarded @@ -1311,10 +1313,20 @@ impl NetworkShieldedCoordinator { /// per-[`WalletId`] and queued through each registered /// [`WalletPersister`]. /// + /// Cancellation: `cancel` is checked before every network step and + /// between note batches. Once it fires, the pass skips what is left + /// of the network work (the rest of the scan, spend re-drives and + /// stranded-reservation releases) but still finalizes and flushes to + /// the host persisters whatever the scan had consumed: a note saved + /// in the store under an advanced watermark is never re-emitted, so + /// an unflushed changeset would leave the host mirror permanently + /// behind. The caught-up cooldown is not stamped for a cancelled + /// pass, so the next pass walks Platform again right away. + /// /// [`sync_notes_across`]: super::sync::sync_notes_across /// [`PlatformEventManager::on_shielded_sync_completed`]: /// crate::events::PlatformEventManager::on_shielded_sync_completed - pub async fn sync(&self, force: bool) -> ShieldedSyncPassSummary { + pub async fn sync(&self, force: bool, cancel: &CancellationToken) -> ShieldedSyncPassSummary { // Network-wide cooldown gate. Snapshot the remaining // window into a local before any await — `std::sync::Mutex` // is `!Send` across await points (clippy's @@ -1353,6 +1365,14 @@ impl NetworkShieldedCoordinator { return summary; } + // A stop that landed before any network work: nothing to finalize, + // so return the empty summary without touching Platform or the + // store (the manager then skips the completion event). + if cancel.is_cancelled() { + tracing::debug!("Coordinator sync cancelled before it started"); + return summary; + } + // Snapshot armed reservations and prefetch Platform's recorded // anchor set BEFORE the note scan. The release pass after the scan // may only act on this pre-scan pair: an anchor already absent from @@ -1384,12 +1404,17 @@ impl NetworkShieldedCoordinator { &subwallets, on_progress.as_ref(), on_tree_progress.as_ref(), + cancel, ) .await { Ok(r) => r, Err(e) => return self.fail_all_wallets(&subwallets, &e), }; + // Everything below that talks to the network is skipped once the + // pass is cancelled; the store-only steps and the host flush of + // what the scan consumed still run (see the method docs). + let cancelled = cancel.is_cancelled(); // Scan-based spend detection now happens INSIDE // `sync_notes_across`: every scanned action's nullifier is // replayed against each subwallet's store as part of the note @@ -1413,8 +1438,9 @@ impl NetworkShieldedCoordinator { // never execute). // // Runs before the balance read so freed notes are reflected in - // this pass's balances. - if let Some((snapshot, recorded)) = stranded_release { + // this pass's balances. Skipped on a cancelled pass: both halves + // broadcast, and a skipped release simply waits for the next pass. + if let Some((snapshot, recorded)) = stranded_release.filter(|_| !cancelled) { // Snapshot the per-wallet persisters BEFORE the loop and drop // the read guard: `redrive_pending_spends` performs network // broadcasts, and holding the persisters lock across those @@ -1470,6 +1496,10 @@ impl NetworkShieldedCoordinator { // enumeration includes guards rehydrated from the durable store. let wallet_ids: HashSet = subwallets.iter().map(|(id, _)| id.wallet_id).collect(); for wallet_id in wallet_ids { + // Network broadcasts: stop between wallets once cancelled. + if cancel.is_cancelled() { + break; + } super::operations::redrive_pending_identity_shields(&self.sdk, &self.store, wallet_id) .await; } @@ -1507,15 +1537,24 @@ impl NetworkShieldedCoordinator { // Cooldown decision based on aggregate activity across // every subwallet — any new commitment scanned or // newly-spent nullifier anywhere on the network clears - // the stamp so the next pass runs immediately. + // the stamp so the next pass runs immediately. A cancelled + // pass proves nothing about being caught up (it may have + // stopped before its first batch), so it leaves the stamp alone. let any_activity = notes.total_scanned > 0 || newly_spent_per_sub.values().any(|&n| n > 0); - if let Ok(mut guard) = self.last_caught_up_at.lock() { - if any_activity { - *guard = None; - } else { - *guard = Some(Instant::now()); + if !cancelled { + if let Ok(mut guard) = self.last_caught_up_at.lock() { + if any_activity { + *guard = None; + } else { + *guard = Some(Instant::now()); + } } } + tracing::debug!( + cancelled, + total_scanned = notes.total_scanned, + "Coordinator sync pass finished" + ); // Demux multi-subwallet results into the per-wallet // `ShieldedSyncSummary` shape that @@ -3703,4 +3742,29 @@ mod tests { let _ = std::fs::remove_dir_all(&dir); } + + /// A token cancelled before the pass starts: no network call (the + /// mock SDK would otherwise fail every wallet), no store change and + /// no caught-up cooldown stamp (dashpay/platform#5200). + #[tokio::test] + async fn should_skip_network_and_cooldown_when_cancelled_before_scan() { + let dir = temp_dir("cancel_before_scan"); + let coordinator = coordinator_with_one_wallet(&dir).await; + let cancel = CancellationToken::new(); + cancel.cancel(); + + let summary = coordinator.sync(true, &cancel).await; + + assert!( + summary.is_empty(), + "a pass cancelled before it started reports nothing" + ); + assert!( + coordinator.last_caught_up_at.lock().unwrap().is_none(), + "a cancelled pass must not stamp the cooldown" + ); + assert_eq!(coordinator.store().read().await.tree_size().unwrap(), 0); + + let _ = std::fs::remove_dir_all(&dir); + } } diff --git a/packages/rs-platform-wallet/src/wallet/shielded/sync.rs b/packages/rs-platform-wallet/src/wallet/shielded/sync.rs index 4f01ea876ef..a984b319335 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/sync.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/sync.rs @@ -29,12 +29,14 @@ use std::collections::BTreeMap; use std::sync::Arc; +use dash_sdk::platform::shielded::notes_sync::types::ShieldedChunkBatch; use dash_sdk::platform::shielded::{ sync_shielded_notes_stream, try_decrypt_note, try_recover_outgoing_note, }; -use futures::StreamExt; +use futures::{Stream, StreamExt}; use grovedb_commitment_tree::{ExtractedNoteCommitment, Note as OrchardNote, PaymentAddress}; use tokio::sync::RwLock; +use tokio_util::sync::CancellationToken; use tracing::{debug, info}; use super::keys::AccountViewingKeys; @@ -190,17 +192,97 @@ impl MultiSyncNotesResult { /// (FVK for nullifier derivation, IVK for trial decryption). /// No `SpendAuthorizingKey` is needed by sync — the spend /// surface re-attaches it at call time. +/// +/// Cancellation: `cancel` is observed before the store is locked and +/// between batches. A cancelled pass stops pulling batches (dropping +/// the in-flight network fetches) and then finalizes the prefix it +/// consumed exactly as a completed pass would — checkpoint, note saves, +/// spend replay, watermark — so the store and the returned changeset +/// stay consistent with each other. It is a clean early stop, not an +/// error. pub(super) async fn sync_notes_across( sdk: &Arc, store: &Arc>, subwallets: &[(SubwalletId, AccountViewingKeys)], on_progress: Option<&super::coordinator::ShieldedProgressCallback>, on_tree_progress: Option<&super::coordinator::ShieldedTreeProgressCallback>, + cancel: &CancellationToken, ) -> Result { if subwallets.is_empty() { return Ok(MultiSyncNotesResult::default()); } + // Drive the FIRST subwallet's IVK as the streaming driver. Its hits + // come back per batch as `batch.decrypted`; every other subwallet's + // are produced by local trial-decryption against `batch.notes`. + let driver_ivk = subwallets[0].1.prepared_ivk.clone(); + + // Builds the SDK stream once the consumer has snapshotted its start + // position and the pre-stream tree size (both feed the config). + let make_stream = |aligned_start: u64, tree_size: u64| { + // Network-only config carrying the caller's "downloaded" progress + // callback; the SDK fires it once per completed network chunk inside + // the stream. The tree-progress ("checked") callback is owned by + // the consumer and fired there — it never travels through the SDK + // config (the SDK doesn't append to a tree). + // Fetch up to 16 chunks concurrently (default is 4) to parallelize + // across the network's ~13 nodes. The per-chunk cost is dominated by + // server-side proof generation, so more in-flight requests is the main + // client-side lever; the pull-based stream still caps in-flight fetches + // at this bound and keeps memory bounded. + let mut sync_config = dash_sdk::platform::shielded::notes_sync::types::ShieldedSyncConfig { + max_concurrent: 16, + ..Default::default() + }; + if let Some(cb) = on_progress { + // Clamp the SDK's "downloaded" value up to the pre-stream tree leaf + // count before forwarding it to the host. The SDK reports downloaded + // as `aligned_start + scanned`, where `aligned_start` is the rewound + // MIN watermark across subwallets and can sit far below `tree_size` + // (a second subwallet binding at watermark 0 collapses it to 0; a + // partial-chunk-tail resume rewinds it below the tail). The "checked" + // signal is the absolute tree size, so over the gate-skipped re-scan + // region (`global_pos < tree_size`, no new appends) the unclamped + // download value reads *below* checked and breaks the advertised + // `Checked ≤ Downloaded ≤ total` invariant. Everything already in the + // tree was necessarily downloaded on a prior pass, so counting it as + // downloaded is accurate; the clamp is a no-op once the stream + // advances past `tree_size`, and the cold-sync case (tree_size == 0) + // is entirely unaffected. + let cb = cb.clone(); + let tree_baseline = tree_size; + sync_config.on_chunk_completed = Some(Arc::new(move |downloaded: u64, height: u64| { + cb(downloaded.max(tree_baseline), height); + })); + } + sync_shielded_notes_stream(sdk, &driver_ivk, aligned_start, Some(sync_config)) + }; + + sync_notes_from_stream(store, subwallets, on_tree_progress, cancel, make_stream).await +} + +/// The consumer half of [`sync_notes_across`]: snapshots the watermarks, +/// takes the store write lock, drains the batch stream `make_stream` +/// builds for `(aligned_start, tree_size)`, and finalizes the store. +/// +/// Split out so a test can feed a synthetic stream and exercise the +/// cancellation and finalize paths without a network. +pub(super) async fn sync_notes_from_stream( + store: &Arc>, + subwallets: &[(SubwalletId, AccountViewingKeys)], + on_tree_progress: Option<&super::coordinator::ShieldedTreeProgressCallback>, + cancel: &CancellationToken, + make_stream: F, +) -> Result +where + S: ShieldedStore, + St: Stream>, + F: FnOnce(u64, u64) -> St, +{ + if subwallets.is_empty() { + return Ok(MultiSyncNotesResult::default()); + } + // Snapshot each subwallet's watermark and the shared tree's // current leaf count. Two distinct quantities drive the rest // of this pass: @@ -261,45 +343,15 @@ pub(super) async fn sync_notes_across( // (total 0) until the first batch lands. let mut total_target: u64 = tree_size; - // Drive the FIRST subwallet's IVK as the streaming driver. Its hits - // come back per batch as `batch.decrypted`; every other subwallet's - // are produced by local trial-decryption against `batch.notes`. - let (driver_id, driver_views) = &subwallets[0]; - let driver_ivk = driver_views.prepared_ivk.clone(); - // Network-only config carrying the caller's "downloaded" progress - // callback; the SDK fires it once per completed network chunk inside - // the stream. The tree-progress ("checked") callback is owned by - // this consumer and fired below — it never travels through the SDK - // config (the SDK doesn't append to a tree). - // Fetch up to 16 chunks concurrently (default is 4) to parallelize - // across the network's ~13 nodes. The per-chunk cost is dominated by - // server-side proof generation, so more in-flight requests is the main - // client-side lever; the pull-based stream still caps in-flight fetches - // at this bound and keeps memory bounded. - let mut sync_config = dash_sdk::platform::shielded::notes_sync::types::ShieldedSyncConfig { - max_concurrent: 16, - ..Default::default() - }; - if let Some(cb) = on_progress { - // Clamp the SDK's "downloaded" value up to the pre-stream tree leaf - // count before forwarding it to the host. The SDK reports downloaded - // as `aligned_start + scanned`, where `aligned_start` is the rewound - // MIN watermark across subwallets and can sit far below `tree_size` - // (a second subwallet binding at watermark 0 collapses it to 0; a - // partial-chunk-tail resume rewinds it below the tail). The "checked" - // signal is the absolute tree size, so over the gate-skipped re-scan - // region (`global_pos < tree_size`, no new appends) the unclamped - // download value reads *below* checked and breaks the advertised - // `Checked ≤ Downloaded ≤ total` invariant. Everything already in the - // tree was necessarily downloaded on a prior pass, so counting it as - // downloaded is accurate; the clamp is a no-op once the stream - // advances past `tree_size`, and the cold-sync case (tree_size == 0) - // is entirely unaffected. - let cb = cb.clone(); - let tree_baseline = tree_size; - sync_config.on_chunk_completed = Some(Arc::new(move |downloaded: u64, height: u64| { - cb(downloaded.max(tree_baseline), height); - })); + // The FIRST subwallet drives the stream (see `sync_notes_across`); + // its hits arrive pre-decrypted in `batch.decrypted`. + let (driver_id, _) = &subwallets[0]; + + // Nothing has been touched yet, so a stop that landed before the scan + // costs nothing: skip the lock and the fetch entirely. + if cancel.is_cancelled() { + debug!("Shielded note sync cancelled before the scan started"); + return Ok(MultiSyncNotesResult::default()); } // Acquire the store write lock for the whole interleaved consume. @@ -311,9 +363,6 @@ pub(super) async fn sync_notes_across( // network fetches at `max_concurrent`. let mut store = store.write().await; - let stream = sync_shielded_notes_stream(sdk, &driver_ivk, aligned_start, Some(sync_config)); - futures::pin_mut!(stream); - // Route decryptions to the subwallet that owns the IVK, accumulated // across every batch. let mut decrypted_by_subwallet: BTreeMap> = BTreeMap::new(); @@ -403,125 +452,152 @@ pub(super) async fn sync_notes_across( // so `mark_spent`'s by-nullifier lookup still resolves. let mut scanned_nullifiers: Vec<[u8; 32]> = Vec::new(); - while let Some(item) = stream.next().await { - let batch = item.map_err(|e| PlatformWalletError::ShieldedSyncFailed(e.to_string()))?; - // The denominator arrives with the batch (extracted from the - // note-fetch proof). It is stable across a sync; take the max-seen - // so a late chunk proven at a slightly higher block never lowers - // it. Stays 0 (indeterminate) only if no batch is ever produced. - total_target = total_target.max(batch.total_count); - total_notes_scanned += batch.notes.len() as u64; - if !batch.notes.is_empty() { - last_nonempty = Some((batch.start_index, batch.is_partial)); - } + // The stream lives in this block so it — and the up-to-`max_concurrent` + // network fetches it holds in flight — is dropped before the finalize + // below runs, whether the loop ran to the end or was cancelled. + let cancelled = { + let stream = make_stream(aligned_start, tree_size); + futures::pin_mut!(stream); + + loop { + // Batches arrive in tree order as a contiguous prefix, so + // stopping between two of them leaves a shorter but valid scan: + // the finalize checkpoints and watermarks exactly what was + // consumed. `biased` so a pending stop wins over a ready batch. + let item = tokio::select! { + biased; + _ = cancel.cancelled() => { + debug!( + total_scanned = total_notes_scanned, + "Shielded note sync cancelled; finalizing the consumed prefix" + ); + break true; + } + next = stream.next() => match next { + Some(item) => item, + None => break false, + }, + }; + let batch = item.map_err(|e| PlatformWalletError::ShieldedSyncFailed(e.to_string()))?; + // The denominator arrives with the batch (extracted from the + // note-fetch proof). It is stable across a sync; take the max-seen + // so a late chunk proven at a slightly higher block never lowers + // it. Stays 0 (indeterminate) only if no batch is ever produced. + total_target = total_target.max(batch.total_count); + total_notes_scanned += batch.notes.len() as u64; + if !batch.notes.is_empty() { + last_nonempty = Some((batch.start_index, batch.is_partial)); + } - // 1. Append commitments for THIS batch, applying the same - // idempotency gate against the pre-stream `tree_size` - // snapshot. `batch.start_index + i` is the global tree - // position. Each action's `nullifier` is the nullifier of - // the note that action SPENT — collect every one across the - // whole scan for the spend-match replay after receipts are - // persisted. These are collected for ALL positions (even - // those gate-skipped for tree append: a re-fetched chunk can - // still surface a spend whose receipt only persisted on a - // later pass), since `mark_spent` is an idempotent no-op for - // nullifiers the wallet doesn't own or already marked spent. - for (i, raw_note) in batch.notes.iter().enumerate() { - // A malformed nullifier length means the proven note item is corrupt; - // fail fast (consistent with the cmx check below) rather than silently - // dropping it — a dropped nullifier would leave a spent note marked - // unspent. - let nf_bytes = <[u8; 32]>::try_from(raw_note.nullifier.as_slice()).map_err(|_| { - PlatformWalletError::ShieldedSyncFailed("Invalid nullifier length".into()) - })?; - scanned_nullifiers.push(nf_bytes); - let global_pos = batch.start_index + i as u64; - if global_pos < tree_size { - continue; + // 1. Append commitments for THIS batch, applying the same + // idempotency gate against the pre-stream `tree_size` + // snapshot. `batch.start_index + i` is the global tree + // position. Each action's `nullifier` is the nullifier of + // the note that action SPENT — collect every one across the + // whole scan for the spend-match replay after receipts are + // persisted. These are collected for ALL positions (even + // those gate-skipped for tree append: a re-fetched chunk can + // still surface a spend whose receipt only persisted on a + // later pass), since `mark_spent` is an idempotent no-op for + // nullifiers the wallet doesn't own or already marked spent. + for (i, raw_note) in batch.notes.iter().enumerate() { + // A malformed nullifier length means the proven note item is corrupt; + // fail fast (consistent with the cmx check below) rather than silently + // dropping it — a dropped nullifier would leave a spent note marked + // unspent. + let nf_bytes = + <[u8; 32]>::try_from(raw_note.nullifier.as_slice()).map_err(|_| { + PlatformWalletError::ShieldedSyncFailed("Invalid nullifier length".into()) + })?; + scanned_nullifiers.push(nf_bytes); + let global_pos = batch.start_index + i as u64; + if global_pos < tree_size { + continue; + } + let cmx_bytes: [u8; 32] = raw_note.cmx.as_slice().try_into().map_err(|_| { + PlatformWalletError::ShieldedSyncFailed("Invalid cmx length".into()) + })?; + store + .append_commitment(&cmx_bytes, true) + .map_err(|e| PlatformWalletError::ShieldedTreeUpdateFailed(e.to_string()))?; + appended += 1; + leaves_committed += 1; } - let cmx_bytes: [u8; 32] = raw_note.cmx.as_slice().try_into().map_err(|_| { - PlatformWalletError::ShieldedSyncFailed("Invalid cmx length".into()) - })?; - store - .append_commitment(&cmx_bytes, true) - .map_err(|e| PlatformWalletError::ShieldedTreeUpdateFailed(e.to_string()))?; - appended += 1; - leaves_committed += 1; - } - // 2. Fire the tree-progress ("checked") callback once per batch - // (already coarse at ~8192-note batches). `total_target` is - // sourced from this batch's proof above; it is set by the first - // batch and stable thereafter. It is 0 (indeterminate on the - // host) only before any batch lands — which can't happen inside - // this loop since we're holding a batch. - if let Some(cb) = on_tree_progress { - cb(leaves_committed, total_target); - } + // 2. Fire the tree-progress ("checked") callback once per batch + // (already coarse at ~8192-note batches). `total_target` is + // sourced from this batch's proof above; it is set by the first + // batch and stable thereafter. It is 0 (indeterminate on the + // host) only before any batch lands — which can't happen inside + // this loop since we're holding a batch. + if let Some(cb) = on_tree_progress { + cb(leaves_committed, total_target); + } - // 3. Trial-decrypt THIS batch. Driver hits come pre-decrypted - // in `batch.decrypted`; other subwallets via local - // trial-decryption over `batch.notes`. - for dn in batch.decrypted { - decrypted_by_subwallet - .entry(*driver_id) - .or_default() - .push(DiscoveredNote { - position: dn.position, - cmx: dn.cmx, - note: dn.note, - block_height: batch.block_height, - }); - } - for (id, views) in subwallets.iter().skip(1) { - for (i, raw_note) in batch.notes.iter().enumerate() { - let position = batch.start_index + i as u64; - if let Some((note, _addr)) = try_decrypt_note(&views.prepared_ivk, raw_note) { - let cmx_bytes: [u8; 32] = match raw_note.cmx.as_slice().try_into() { - Ok(b) => b, - Err(_) => continue, - }; - decrypted_by_subwallet - .entry(*id) - .or_default() - .push(DiscoveredNote { - position, - cmx: cmx_bytes, - note, - block_height: batch.block_height, - }); + // 3. Trial-decrypt THIS batch. Driver hits come pre-decrypted + // in `batch.decrypted`; other subwallets via local + // trial-decryption over `batch.notes`. + for dn in batch.decrypted { + decrypted_by_subwallet + .entry(*driver_id) + .or_default() + .push(DiscoveredNote { + position: dn.position, + cmx: dn.cmx, + note: dn.note, + block_height: batch.block_height, + }); + } + for (id, views) in subwallets.iter().skip(1) { + for (i, raw_note) in batch.notes.iter().enumerate() { + let position = batch.start_index + i as u64; + if let Some((note, _addr)) = try_decrypt_note(&views.prepared_ivk, raw_note) { + let cmx_bytes: [u8; 32] = match raw_note.cmx.as_slice().try_into() { + Ok(b) => b, + Err(_) => continue, + }; + decrypted_by_subwallet + .entry(*id) + .or_default() + .push(DiscoveredNote { + position, + cmx: cmx_bytes, + note, + block_height: batch.block_height, + }); + } } } - } - // 4. OVK recovery (outgoing/SENT notes). Attempt to open each - // scanned note's `out_ciphertext` with EVERY subwallet's OVK - // (driver included — unlike IVK trial-decrypt, the driver's - // sent notes are NOT pre-recovered by the SDK). A note only - // recovers under the OVK of the wallet that sent it, so this - // is precisely each subwallet's own send history; a received - // note (or another wallet's send, or a dummy output) yields - // `None` and is skipped. Recovered notes are accumulated and - // recorded after this pass's incoming receipts persist (the - // record is `cmx`-idempotent at the store). - for (id, views) in subwallets.iter() { - for raw_note in batch.notes.iter() { - if let Some((note, recipient, memo)) = - try_recover_outgoing_note(&views.outgoing_viewing_key, raw_note) - { - recovered_outgoing_by_subwallet - .entry(*id) - .or_default() - .push(RecoveredOutgoing { - note, - recipient, - memo, - block_height: batch.block_height, - }); + // 4. OVK recovery (outgoing/SENT notes). Attempt to open each + // scanned note's `out_ciphertext` with EVERY subwallet's OVK + // (driver included — unlike IVK trial-decrypt, the driver's + // sent notes are NOT pre-recovered by the SDK). A note only + // recovers under the OVK of the wallet that sent it, so this + // is precisely each subwallet's own send history; a received + // note (or another wallet's send, or a dummy output) yields + // `None` and is skipped. Recovered notes are accumulated and + // recorded after this pass's incoming receipts persist (the + // record is `cmx`-idempotent at the store). + for (id, views) in subwallets.iter() { + for raw_note in batch.notes.iter() { + if let Some((note, recipient, memo)) = + try_recover_outgoing_note(&views.outgoing_viewing_key, raw_note) + { + recovered_outgoing_by_subwallet + .entry(*id) + .or_default() + .push(RecoveredOutgoing { + note, + recipient, + memo, + block_height: batch.block_height, + }); + } } } } - } + }; // Diagnostic mirror of the SDK's one-shot `next_start_index` // (rewinds to the last partial chunk's start). NOT the watermark: @@ -544,6 +620,7 @@ pub(super) async fn sync_notes_across( .map(|v| v.len()) .unwrap_or(0), next_start_index, + cancelled, "SDK stream consumed" ); @@ -1074,3 +1151,8 @@ mod ovk_builder_roundtrip_tests; /// full-decryption and the OVK send-history recovery primitives. #[cfg(test)] mod memo_roundtrip_tests; + +/// Cancellation of a note-sync pass: the consumed prefix is finalized, +/// a pre-scan cancel touches nothing, and a later pass resumes cleanly. +#[cfg(test)] +mod cancel_tests; diff --git a/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs b/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs new file mode 100644 index 00000000000..72958029a46 --- /dev/null +++ b/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs @@ -0,0 +1,217 @@ +//! Cancellation of a note-sync pass (dashpay/platform#5200). +//! +//! Feeds `sync_notes_from_stream` a synthetic batch stream so the +//! cancel and finalize paths run without a network. The stream yields +//! real-shaped batches, then a tail future that cancels the token and +//! pends forever — exactly the moment a stop would land between two +//! chunk fetches. + +use std::sync::Arc; + +use dash_sdk::platform::shielded::notes_sync::types::ShieldedChunkBatch; +use drive_proof_verifier::types::ShieldedEncryptedNote; +use futures::{Stream, StreamExt}; +use tokio::sync::RwLock; +use tokio_util::sync::CancellationToken; + +use super::{sync_notes_from_stream, MultiSyncNotesResult}; +use crate::wallet::shielded::file_store::FileBackedShieldedStore; +use crate::wallet::shielded::keys::{AccountViewingKeys, OrchardKeySet}; +use crate::wallet::shielded::store::{ShieldedStore, SubwalletId}; + +type BatchItem = Result; + +fn temp_tree_path(tag: &str) -> std::path::PathBuf { + let nanos = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos(); + std::env::temp_dir().join(format!("shielded_sync_cancel_{tag}_{nanos}.sqlite")) +} + +fn one_subwallet() -> Vec<(SubwalletId, AccountViewingKeys)> { + let views = OrchardKeySet::from_seed(&[0x42u8; 64], dashcore::Network::Testnet, 0) + .expect("derive viewing keys") + .viewing_keys(); + vec![(SubwalletId::new([0x11; 32], 0), views)] +} + +/// A batch of `len` notes at `start_index`. The notes are opaque to the +/// scanner: an empty ciphertext never OVK-recovers, the single subwallet +/// is the stream driver so no IVK trial-decryption runs, and a nullifier +/// nobody owns is a no-op in the spend replay. Only the commitment is +/// load-bearing — a distinct small value is a valid Pallas element. +fn batch(start_index: u64, len: u64, total_count: u64) -> ShieldedChunkBatch { + let notes = (0..len) + .map(|i| { + let mut cmx = [0u8; 32]; + let pos = start_index + i; + cmx[0] = (pos as u8) + 1; + cmx[1] = (pos >> 8) as u8; + ShieldedEncryptedNote { + cmx: cmx.to_vec(), + nullifier: vec![0xAA; 32], + cv_net: vec![], + encrypted_note: vec![], + } + }) + .collect(); + ShieldedChunkBatch { + start_index, + notes, + decrypted: vec![], + block_height: 1_000 + start_index, + is_partial: false, + total_count, + } +} + +/// `batches`, then a tail that fires `cancel` when first polled and never +/// yields: the consumer sees the cancellation exactly between batches. +fn batches_then_cancel( + batches: Vec, + cancel: CancellationToken, +) -> impl Stream { + futures::stream::iter(batches.into_iter().map(Ok)).chain(futures::stream::once(async move { + cancel.cancel(); + futures::future::pending::().await + })) +} + +async fn run( + store: &Arc>, + subwallets: &[(SubwalletId, AccountViewingKeys)], + cancel: &CancellationToken, + stream: impl Stream, +) -> MultiSyncNotesResult { + tokio::time::timeout( + std::time::Duration::from_secs(5), + sync_notes_from_stream(store, subwallets, None, cancel, move |_, _| stream), + ) + .await + .expect("a cancelled pass must return promptly") + .expect("pass must succeed") +} + +#[tokio::test] +async fn should_finalize_consumed_prefix_when_cancelled_mid_stream() { + let path = temp_tree_path("prefix"); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(&path, 100).expect("open store"), + )); + let subwallets = one_subwallet(); + let sub = subwallets[0].0; + let cancel = CancellationToken::new(); + + let result = run( + &store, + &subwallets, + &cancel, + batches_then_cancel(vec![batch(0, 4, 12), batch(4, 4, 12)], cancel.clone()), + ) + .await; + + // The prefix the pass consumed is finalized like a completed pass. + assert_eq!(result.total_scanned, 8); + let store = store.read().await; + assert_eq!(store.tree_size().unwrap(), 8, "both batches appended"); + assert_eq!( + store.last_synced_note_index(sub).unwrap(), + 8, + "watermark covers exactly the consumed batches" + ); + assert!( + store.witness(7).unwrap().is_some(), + "a checkpoint covers the appended leaves" + ); + + let _ = std::fs::remove_file(&path); +} + +#[tokio::test] +async fn should_return_empty_without_touching_store_when_cancelled_before_scan() { + let path = temp_tree_path("before"); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(&path, 100).expect("open store"), + )); + let subwallets = one_subwallet(); + let sub = subwallets[0].0; + let cancel = CancellationToken::new(); + cancel.cancel(); + + let result = sync_notes_from_stream( + &store, + &subwallets, + None, + &cancel, + |_, _| -> futures::stream::Pending { + panic!("a pass cancelled before the scan must not build the stream") + }, + ) + .await + .expect("pass must succeed"); + + assert_eq!(result.total_scanned, 0); + assert!(result.per_subwallet_new_notes.is_empty()); + let store = store.read().await; + assert_eq!(store.tree_size().unwrap(), 0); + assert_eq!(store.last_synced_note_index(sub).unwrap(), 0); + + let _ = std::fs::remove_file(&path); +} + +#[tokio::test] +async fn should_resume_from_partial_watermark_on_next_pass() { + let path = temp_tree_path("resume"); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(&path, 100).expect("open store"), + )); + let subwallets = one_subwallet(); + let sub = subwallets[0].0; + + // Pass 1: cancelled after two batches. + let cancel = CancellationToken::new(); + run( + &store, + &subwallets, + &cancel, + batches_then_cancel(vec![batch(0, 4, 12), batch(4, 4, 12)], cancel.clone()), + ) + .await; + assert_eq!(store.read().await.last_synced_note_index(sub).unwrap(), 8); + + // Pass 2: the SDK re-fetches from the chunk-aligned start (0 here), so + // the stream re-delivers the first two batches — gate-skipped by the + // tree-size snapshot — and then the new one. Runs to completion. + let cancel = CancellationToken::new(); + let result = run( + &store, + &subwallets, + &cancel, + futures::stream::iter( + vec![batch(0, 4, 12), batch(4, 4, 12), batch(8, 4, 12)] + .into_iter() + .map(Ok), + ), + ) + .await; + + assert_eq!( + result.total_scanned, 4, + "only the new notes count as scan volume" + ); + let store = store.read().await; + assert_eq!( + store.tree_size().unwrap(), + 12, + "re-delivered positions are not re-appended" + ); + assert_eq!(store.last_synced_note_index(sub).unwrap(), 12); + assert!( + store.witness(11).unwrap().is_some(), + "the second pass checkpoints past the partial one" + ); + assert!(store.witness(7).unwrap().is_some()); + + let _ = std::fs::remove_file(&path); +} From 7e1fac2ae567ff17bd5338e78853f299afaa45e0 Mon Sep 17 00:00:00 2001 From: Bartosz Rozwarski Date: Thu, 29 Oct 2026 14:40:36 +0100 Subject: [PATCH 2/3] fix(platform-wallet): report nothing for a cancelled pass that scanned nothing `build_per_wallet_summary` mints an all-zero `Ok` for every registered wallet, so the manager's `is_empty()` check could not tell a pass cancelled before its scan from a completed one and still stamped the timestamp and emitted a completion event. The coordinator now hands back the empty summary when a cancelled pass consumed nothing, and the stranded-release prefetch (a read-only RPC) is selected against the token so a stop that lands during it does not wait the request out. Co-Authored-By: Claude Fable 5.1 --- .../src/manager/shielded_sync.rs | 7 ++--- .../src/wallet/shielded/coordinator.rs | 27 ++++++++++++++++++- 2 files changed, 30 insertions(+), 4 deletions(-) diff --git a/packages/rs-platform-wallet/src/manager/shielded_sync.rs b/packages/rs-platform-wallet/src/manager/shielded_sync.rs index 1a998a06070..25e925cbda2 100644 --- a/packages/rs-platform-wallet/src/manager/shielded_sync.rs +++ b/packages/rs-platform-wallet/src/manager/shielded_sync.rs @@ -465,9 +465,10 @@ impl ShieldedSyncManager { // A pass cancelled before it did anything is not a completed pass: // no timestamp, no completion event (same as losing the slot CAS). - // A cancelled pass that did consume batches has flushed them to the - // persisters, so it is reported like any other so the host applies - // the deltas. + // The coordinator returns the empty summary for exactly that case + // (a cancelled scan that consumed nothing); one that did consume + // batches has flushed them to the persisters, so it is reported + // like any other pass and the host applies the deltas. if pass_cancel.is_cancelled() && summary.is_empty() { return summary; } diff --git a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs index 90c6d0f7219..430b9f02b1e 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs @@ -1386,7 +1386,14 @@ impl NetworkShieldedCoordinator { // scan are deliberately absent from the snapshot — their anchors // may be newer than this set — and get checked next pass. Skips the // network call entirely when nothing is armed (the common case). - let stranded_release = self.prefetch_stranded_release(&subwallets).await; + // The prefetch is a read-only RPC, so a stop that lands while it is + // in flight simply drops it: the release pass is skipped on a + // cancelled pass anyway, and the scan below bails before locking. + let stranded_release = tokio::select! { + biased; + _ = cancel.cancelled() => None, + prefetched = self.prefetch_stranded_release(&subwallets) => prefetched, + }; // ONE SDK call covers every registered IVK on the network. // Snapshot the optional progress handler installed by the @@ -1414,7 +1421,25 @@ impl NetworkShieldedCoordinator { // Everything below that talks to the network is skipped once the // pass is cancelled; the store-only steps and the host flush of // what the scan consumed still run (see the method docs). + // + // Snapshotted here on purpose: the scan is the step that was or + // was not cut short, and the cooldown decision below is about + // whether that scan reached the tip. A stop that lands during the + // store-only steps after a complete scan does not change that. let cancelled = cancel.is_cancelled(); + // A pass cut short before the scan consumed anything (the stop + // landed in the prefetch, or before the store lock) has nothing to + // flush and nothing to report: hand back the empty summary so the + // manager treats it as "no pass ran" — `build_per_wallet_summary` + // would otherwise mint an all-zero `Ok` for every registered + // wallet, and the host would see a completion event for no work. + if cancelled + && notes.total_scanned == 0 + && crate::changeset::merge::Merge::is_empty(¬es.changeset) + { + tracing::debug!("Coordinator sync cancelled before the scan consumed anything"); + return summary; + } // Scan-based spend detection now happens INSIDE // `sync_notes_across`: every scanned action's nullifier is // replayed against each subwallet's store as part of the note From 26593f7bf5f91235b7b5bbc808f5e89cab73042b Mon Sep 17 00:00:00 2001 From: Bartosz Rozwarski Date: Thu, 29 Oct 2026 16:54:41 +0100 Subject: [PATCH 3/3] fix(platform-wallet): never rewind a subwallet watermark on a cancelled pass A cancelled pass finalizes `aligned_start + scanned`, and `aligned_start` is the union MIN watermark, so a subwallet that was already further along could be written backwards. Finalize `max(prior, new)` and leave an uncovered subwallet's row alone on a cancelled pass; a completed pass keeps the unconditional write (its `ScannedThisSession` stamp feeds the restore gate). A pass cancelled before its first batch now records nothing, so the coordinator's empty-pass gate fires. Take the pass token before the `is_syncing` CAS in both entry points: a `stop()` between the CAS and `pass_token()` rotated the parent and handed the admitted pass an uncancelled child. Check cancellation ahead of the cooldown fast path, whose skip summary reported one caught-up wallet for a pass that never ran. Co-Authored-By: Claude Fable 5.1 --- .../src/manager/shielded_sync.rs | 33 ++++--- .../src/wallet/shielded/coordinator.rs | 40 ++++++-- .../src/wallet/shielded/sync.rs | 19 +++- .../src/wallet/shielded/sync/cancel_tests.rs | 94 ++++++++++++++++++- 4 files changed, 160 insertions(+), 26 deletions(-) diff --git a/packages/rs-platform-wallet/src/manager/shielded_sync.rs b/packages/rs-platform-wallet/src/manager/shielded_sync.rs index 25e925cbda2..ae1cd2cfe53 100644 --- a/packages/rs-platform-wallet/src/manager/shielded_sync.rs +++ b/packages/rs-platform-wallet/src/manager/shielded_sync.rs @@ -139,7 +139,8 @@ pub struct ShieldedSyncManager { event_manager: Arc, /// Network-scoped shielded coordinator slot, shared with the /// owning `PlatformWalletManager`. Sync passes route through - /// `coordinator.sync(force)` whenever the slot is populated; + /// `coordinator.sync(force, &pass_cancel)` — under the + /// manager-owned pass token — whenever the slot is populated; /// an empty slot returns an empty pass summary (no wallets /// can be shielded-bound without `configure_shielded` having /// run first, so an empty slot guarantees no shielded state @@ -417,6 +418,17 @@ impl ShieldedSyncManager { /// If a pass is already in flight, returns an empty summary and /// skips — the caller can inspect [`is_syncing`] to distinguish. pub async fn sync_now(&self, force: bool) -> ShieldedSyncPassSummary { + // Take the pass token BEFORE claiming the slot. A `stop()` that + // lands after the token is taken cancels this lineage, whichever + // side of the CAS it falls on; taken after the CAS, a stop that + // slipped in between would rotate the parent first and hand this + // pass a fresh, uncancelled child. Losing the CAS just drops the + // token. It is also before the gate check: `drain_pass` takes its + // hold (closing the gate) and only then calls `stop()`, so a pass + // that took its token before the rotation is on the cancelled + // lineage, and one that took it after sees the closed gate below. + // Either way no pass runs past a drain. + let pass_cancel = self.pass_token(); if self .is_syncing .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire) @@ -428,13 +440,6 @@ impl ShieldedSyncManager { // so a failed pass can never wedge `quiesce()`'s drain. let _slot = SyncSlotGuard(&self.is_syncing); - // Take the pass token BEFORE the gate check. `drain_pass` takes its - // hold (closing the gate) and only then calls `stop()` (rotating - // the token), so a pass that took its token before the rotation - // is on the cancelled lineage, and one that took it after sees the - // closed gate below. Either way no pass runs past a drain. - let pass_cancel = self.pass_token(); - // A `quiesce()` may have raised the gate between our CAS and // here; if so, release the slot and bail without running a pass // so the drain can complete and Clear/stop get a true barrier. @@ -510,8 +515,10 @@ impl ShieldedSyncManager { /// /// Returns `Ok(None)` if `wallet_id` isn't registered on the /// coordinator (e.g. shielded support hasn't been configured, - /// or the wallet has never called `bind_shielded`), or if - /// another sync pass was already in flight. + /// or the wallet has never called `bind_shielded`), if + /// another sync pass was already in flight, or if the pass was + /// cancelled by [`stop`](Self::stop) before it consumed any + /// scan data (the coordinator then reports no wallets). pub async fn sync_wallet( &self, wallet_id: &WalletId, @@ -525,6 +532,9 @@ impl ShieldedSyncManager { return Ok(None); }; + // Token before the slot CAS and the gate check — see `sync_now` + // for the ordering. + let pass_cancel = self.pass_token(); // Reuse the manager-wide `is_syncing` flag so a per-wallet // `sync_wallet()` can't race the periodic `sync_now()` // against the same store — both go through @@ -541,9 +551,6 @@ impl ShieldedSyncManager { // so a failed pass can never wedge `quiesce()`'s drain. let _slot = SyncSlotGuard(&self.is_syncing); - // Token before the gate check — see `sync_now` for the ordering. - let pass_cancel = self.pass_token(); - // Bail if a `quiesce()` raised the gate after our CAS (see // `sync_now`) so the drain barrier holds. if self.quiescing.is_closed() { diff --git a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs index 430b9f02b1e..ac00f9158a7 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs @@ -1327,6 +1327,16 @@ impl NetworkShieldedCoordinator { /// [`PlatformEventManager::on_shielded_sync_completed`]: /// crate::events::PlatformEventManager::on_shielded_sync_completed pub async fn sync(&self, force: bool, cancel: &CancellationToken) -> ShieldedSyncPassSummary { + // A stop that landed before any work: nothing to finalize, so + // return the empty summary without touching Platform or the + // store (the manager then skips the completion event). Checked + // ahead of the cooldown gate, whose skip summary would otherwise + // report one caught-up wallet each for a pass that never ran. + if cancel.is_cancelled() { + tracing::debug!("Coordinator sync cancelled before it started"); + return ShieldedSyncPassSummary::default(); + } + // Network-wide cooldown gate. Snapshot the remaining // window into a local before any await — `std::sync::Mutex` // is `!Send` across await points (clippy's @@ -1365,14 +1375,6 @@ impl NetworkShieldedCoordinator { return summary; } - // A stop that landed before any network work: nothing to finalize, - // so return the empty summary without touching Platform or the - // store (the manager then skips the completion event). - if cancel.is_cancelled() { - tracing::debug!("Coordinator sync cancelled before it started"); - return summary; - } - // Snapshot armed reservations and prefetch Platform's recorded // anchor set BEFORE the note scan. The release pass after the scan // may only act on this pre-scan pair: an anchor already absent from @@ -3792,4 +3794,26 @@ mod tests { let _ = std::fs::remove_dir_all(&dir); } + + /// Cancelled while inside the caught-up cooldown: the cooldown's + /// skip summary would report one caught-up wallet, which the + /// manager would stamp and announce as a completed pass. The + /// cancellation check runs first, so the pass reports nothing. + #[tokio::test] + async fn should_report_nothing_when_cancelled_inside_cooldown() { + let dir = temp_dir("cancel_inside_cooldown"); + let coordinator = coordinator_with_one_wallet(&dir).await; + *coordinator.last_caught_up_at.lock().unwrap() = Some(std::time::Instant::now()); + let cancel = CancellationToken::new(); + cancel.cancel(); + + let summary = coordinator.sync(false, &cancel).await; + + assert!( + summary.is_empty(), + "a cancelled pass must not borrow the cooldown's caught-up summary" + ); + + let _ = std::fs::remove_dir_all(&dir); + } } diff --git a/packages/rs-platform-wallet/src/wallet/shielded/sync.rs b/packages/rs-platform-wallet/src/wallet/shielded/sync.rs index a984b319335..a84763a3fc7 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/sync.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/sync.rs @@ -767,12 +767,27 @@ where // the union. `total_notes_scanned` is accumulated from every // streamed batch's note count — identical to the one-shot path's // `result.total_notes_scanned`. + // + // Never rewind. `aligned_start` is the MIN watermark across the + // union, so a pass cut short after a few batches can end below a + // subwallet that was already further along; a completed pass + // always reaches the tip, which is at or past every watermark. + // A cancelled pass leaves such a subwallet's row alone entirely: + // its consumed prefix never covered that subwallet, so neither + // the watermark nor the `ScannedThisSession` stamp the setter + // applies belongs to it. A completed pass keeps the unconditional + // write, so a caught-up subwallet still gets its stamp. let new_index = aligned_start + total_notes_scanned; for (id, _) in subwallets { + let prior = watermarks.get(id).copied().unwrap_or(0); + let advanced = prior.max(new_index); + if cancelled && advanced == prior { + continue; + } store - .set_last_synced_note_index(*id, new_index) + .set_last_synced_note_index(*id, advanced) .map_err(|e| PlatformWalletError::ShieldedStoreError(e.to_string()))?; - changeset.record_synced_index(*id, new_index); + changeset.record_synced_index(*id, advanced); } // Drop the write lock before returning so the caller's // persister queue (which may take its own synchronous diff --git a/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs b/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs index 72958029a46..4492256eb12 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs @@ -29,11 +29,15 @@ fn temp_tree_path(tag: &str) -> std::path::PathBuf { std::env::temp_dir().join(format!("shielded_sync_cancel_{tag}_{nanos}.sqlite")) } -fn one_subwallet() -> Vec<(SubwalletId, AccountViewingKeys)> { - let views = OrchardKeySet::from_seed(&[0x42u8; 64], dashcore::Network::Testnet, 0) +fn subwallet(account: u32) -> (SubwalletId, AccountViewingKeys) { + let views = OrchardKeySet::from_seed(&[0x42u8; 64], dashcore::Network::Testnet, account) .expect("derive viewing keys") .viewing_keys(); - vec![(SubwalletId::new([0x11; 32], 0), views)] + (SubwalletId::new([0x11; 32], account), views) +} + +fn one_subwallet() -> Vec<(SubwalletId, AccountViewingKeys)> { + vec![subwallet(0)] } /// A batch of `len` notes at `start_index`. The notes are opaque to the @@ -215,3 +219,87 @@ async fn should_resume_from_partial_watermark_on_next_pass() { let _ = std::fs::remove_file(&path); } + +/// Two subwallets, one already past where the cancelled prefix ends. +/// `aligned_start` is the union MIN, so the pass walks 0..8 while the +/// second subwallet sits at 12: its watermark must not move backwards, +/// and the changeset must not carry a rewound value to the host. +#[tokio::test] +async fn should_not_rewind_a_more_advanced_subwallet_when_cancelled() { + let path = temp_tree_path("no_rewind"); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(&path, 100).expect("open store"), + )); + let subwallets = vec![subwallet(0), subwallet(1)]; + let (lagging, advanced) = (subwallets[0].0, subwallets[1].0); + store + .write() + .await + .set_last_synced_note_index(advanced, 12) + .expect("seed the advanced watermark"); + let cancel = CancellationToken::new(); + + let result = run( + &store, + &subwallets, + &cancel, + batches_then_cancel(vec![batch(0, 4, 12), batch(4, 4, 12)], cancel.clone()), + ) + .await; + + let store = store.read().await; + assert_eq!(store.last_synced_note_index(lagging).unwrap(), 8); + assert_eq!( + store.last_synced_note_index(advanced).unwrap(), + 12, + "a partial prefix below a subwallet's watermark must not rewind it" + ); + assert_eq!( + result.changeset.synced_indices.get(&lagging).copied(), + Some(8) + ); + assert!( + !result.changeset.synced_indices.contains_key(&advanced), + "no rewound watermark may reach the host persister" + ); + + let _ = std::fs::remove_file(&path); +} + +/// Cancelled after the store lock but before the first batch: nothing +/// was consumed, so the store and the changeset stay untouched and the +/// coordinator's empty-pass gate can fire. +#[tokio::test] +async fn should_leave_store_and_changeset_empty_when_cancelled_before_first_batch() { + let path = temp_tree_path("first_batch"); + let store = Arc::new(RwLock::new( + FileBackedShieldedStore::open_path(&path, 100).expect("open store"), + )); + let subwallets = one_subwallet(); + let sub = subwallets[0].0; + store + .write() + .await + .set_last_synced_note_index(sub, 4) + .expect("seed the watermark"); + let cancel = CancellationToken::new(); + + let result = run( + &store, + &subwallets, + &cancel, + batches_then_cancel(vec![], cancel.clone()), + ) + .await; + + assert_eq!(result.total_scanned, 0); + assert!( + crate::changeset::merge::Merge::is_empty(&result.changeset), + "a pass that consumed nothing records nothing, not even its own watermark" + ); + let store = store.read().await; + assert_eq!(store.tree_size().unwrap(), 0); + assert_eq!(store.last_synced_note_index(sub).unwrap(), 4); + + let _ = std::fs::remove_file(&path); +}