diff --git a/packages/rs-platform-wallet-ffi/src/shielded_sync.rs b/packages/rs-platform-wallet-ffi/src/shielded_sync.rs index 95f4b94f037..1371dfaabd1 100644 --- a/packages/rs-platform-wallet-ffi/src/shielded_sync.rs +++ b/packages/rs-platform-wallet-ffi/src/shielded_sync.rs @@ -697,7 +697,10 @@ pub unsafe extern "C" fn platform_wallet_manager_shielded_default_address( /// you want to avoid concurrent passes. Returns an error if the /// wallet doesn't exist or the sync itself fails. Wallets with no /// bound shielded sub-wallet succeed silently with no observable -/// state change. +/// state change, and so does a pass whose scan a concurrent +/// [`platform_wallet_manager_shielded_sync_stop`] cut short: it +/// published nothing, and the next pass re-walks from the last +/// completed watermark. /// /// # Safety /// - `wallet_id_bytes` must point at 32 readable bytes. 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 c337fdd3426..e8fd82a64a4 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; @@ -138,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 @@ -160,6 +162,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 +187,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. @@ -286,15 +306,29 @@ 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: a scan cut + /// short keeps the commitments it appended to the local tree and + /// publishes nothing else, a scan that had completed still flushes + /// its result, then the pass 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 release. 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); } @@ -395,6 +429,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(); // A drained timeout latch is cleared here as well as in `start()`: // with no loop running, a one-shot pass after a timed-out drain // would otherwise bail on the stale latch until something @@ -436,11 +481,21 @@ 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 whose scan was cut short is not a completed pass: no + // timestamp, no completion event (same as losing the slot CAS). + // The coordinator returns the empty summary for exactly that case; + // a pass stopped only after its scan completed has flushed the + // scan 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; + } + let now = SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_secs()) @@ -478,13 +533,21 @@ 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's scan + /// was cut short by [`stop`](Self::stop) (the coordinator then + /// reports no wallets). pub async fn sync_wallet( &self, wallet_id: &WalletId, force: bool, ) -> Result, crate::error::PlatformWalletError> { + // Token first — before the coordinator read below as well as the + // slot CAS and the gate check (see `sync_now` for the ordering): + // a `stop()` that lands while this waits for the coordinator lock + // must still cancel this pass, not hand it a child of the rotated, + // uncancelled parent. + let pass_cancel = self.pass_token(); let coordinator_snapshot: Option> = { let slot = self.coordinator_slot.read().await; slot.as_ref().map(Arc::clone) @@ -492,7 +555,6 @@ impl ShieldedSyncManager { let Some(coordinator) = coordinator_snapshot else { return Ok(None); }; - // 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 @@ -522,7 +584,7 @@ impl ShieldedSyncManager { 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 @@ -703,4 +765,55 @@ mod tests { "the direct pass cleared the latch" ); } + + /// `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 { + // Token before the slot, as the production entry points do: + // taken after, a quiesce that saw the occupied slot first + // would have rotated the parent and this task would wait on + // a fresh, uncancelled lineage. + let pass_cancel = holder.pass_token(); + wedge_sync_slot(&holder); + let _slot = SyncSlotGuard(&holder.is_syncing); + pass_cancel.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..03adbe56175 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/balance_tests.rs @@ -15,6 +15,7 @@ use crate::changeset::{ShieldedSubwalletStartState, ShieldedSyncStartState}; use crate::error::PlatformWalletError; use crate::wallet::persister::{NoPlatformPersistence, WalletPersister}; use drive_proof_verifier::types::{ShieldedEncryptedNotes, ShieldedEncryptedNotesQuery}; +use tokio_util::sync::CancellationToken; fn tree_path() -> PathBuf { // Clock resolution alone does not distinguish parallel test invocations. @@ -222,7 +223,7 @@ 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, &CancellationToken::new()).await; assert_eq!( outcome.success_count(), 1, @@ -249,7 +250,7 @@ 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, &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 +301,7 @@ 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, &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/cancelled_scan_tests.rs b/packages/rs-platform-wallet/src/wallet/shielded/cancelled_scan_tests.rs new file mode 100644 index 00000000000..e81c06b7bfa --- /dev/null +++ b/packages/rs-platform-wallet/src/wallet/shielded/cancelled_scan_tests.rs @@ -0,0 +1,640 @@ +//! A cancelled scan pass publishes nothing (dashpay/platform#5200 review). +//! +//! Drives the real coordinator against a mock Platform whose pool spans +//! two fetch chunks, each holding one owned note, and cancels the pass +//! from the tree-progress callback after the first chunk lands. The +//! appended commitments stay in the local tree; no note, spent mark, +//! watermark, activity entry or completion leaves the scan, and the +//! ledger stays unavailable. The next pass re-walks from the completed +//! watermark and yields exactly what an uninterrupted scan yields — one +//! entry carrying both notes. +//! +//! The host side is checked through a recording persister: nothing +//! reaches the host on a cancelled pass, and a restart restored from +//! what the host recorded carries no scan coverage until a pass +//! completes. + +use std::collections::BTreeMap; +use std::path::PathBuf; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Arc, Mutex}; + +use dash_sdk::Sdk; +use drive_proof_verifier::types::{ + ShieldedEncryptedNote, ShieldedEncryptedNotes, ShieldedEncryptedNotesQuery, +}; +use grovedb_commitment_tree::{ + DashMemo, Domain, ExtractedNoteCommitment, Note, NoteValue, Nullifier, OrchardDomain, + OrchardNoteEncryption, RandomSeed, Rho, ValueCommitTrapdoor, ValueCommitment, +}; +use rand::{rngs::OsRng, RngCore}; +use tokio_util::sync::CancellationToken; + +use super::activity::ShieldedActivityEntry; +use super::balance::{ShieldedBalanceSource, ShieldedLocalBalanceState}; +use super::keys::AccountViewingKeys; +use super::{ + FileBackedShieldedStore, NetworkShieldedCoordinator, OrchardKeySet, ShieldedStore, SubwalletId, +}; +use crate::changeset::{ + ClientStartState, PersistenceError, PlatformWalletChangeSet, PlatformWalletPersistence, + ShieldedChangeSet, ShieldedSubwalletStartState, ShieldedSyncStartState, +}; +use crate::wallet::persister::WalletPersister; +use crate::wallet::platform_wallet::WalletId; + +const WALLET: [u8; 32] = [7; 32]; +const FIRST_VALUE: u64 = 100; +const SECOND_VALUE: u64 = 200; + +/// A host persister that keeps every shielded changeset it was handed, +/// and can hand them back as the start state a cold bind would restore. +#[derive(Default)] +struct RecordingPersistence { + changesets: Mutex>, +} + +impl PlatformWalletPersistence for RecordingPersistence { + fn store( + &self, + _wallet_id: WalletId, + changeset: PlatformWalletChangeSet, + ) -> Result<(), PersistenceError> { + if let Some(shielded) = changeset.shielded { + self.changesets.lock().expect("recorder").push(shielded); + } + Ok(()) + } + + fn flush(&self, _wallet_id: WalletId) -> Result<(), PersistenceError> { + Ok(()) + } + + fn load(&self) -> Result { + Ok(ClientStartState::default()) + } +} + +impl RecordingPersistence { + fn recorded(&self) -> Vec { + self.changesets.lock().expect("recorder").clone() + } + + /// Fold the recorded changesets the way a host snapshot does: notes + /// accumulate, a spent nullifier marks its note spent, the watermark + /// is the highest one received, and sync state exists only if a + /// watermark was ever received. + fn start_state(&self) -> ShieldedSyncStartState { + let mut per_subwallet: BTreeMap = BTreeMap::new(); + for changeset in self.recorded() { + for (id, notes) in changeset.notes_saved { + per_subwallet.entry(id).or_default().notes.extend(notes); + } + for (id, nullifiers) in changeset.nullifiers_spent { + for note in &mut per_subwallet.entry(id).or_default().notes { + if nullifiers.contains(¬e.nullifier) { + note.is_spent = true; + } + } + } + for (id, index) in changeset.synced_indices { + let sub = per_subwallet.entry(id).or_default(); + sub.has_sync_state = true; + sub.last_synced_index = sub.last_synced_index.max(index); + } + for (id, entries) in changeset.activity_entries { + per_subwallet + .entry(id) + .or_default() + .activity + .extend(entries); + } + } + ShieldedSyncStartState { + per_subwallet, + ..Default::default() + } + } +} + +fn tree_path() -> PathBuf { + static NEXT_PATH: AtomicU64 = AtomicU64::new(0); + let sequence = NEXT_PATH.fetch_add(1, Ordering::Relaxed); + let nonce = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .expect("clock") + .as_nanos(); + std::env::temp_dir().join(format!( + "shielded_cancelled_scan_{}_{nonce}_{sequence}.sqlite", + std::process::id() + )) +} + +fn viewing_keys() -> AccountViewingKeys { + OrchardKeySet::from_seed(&[42; 64], dashcore::Network::Testnet, 0) + .expect("test viewing key") + .viewing_keys() +} + +/// A note of `value` sent to the test account by someone else, as the +/// network serves it. Real IVK encryption so the SDK's driver decryption +/// finds it; no OVK, so it is a plain receipt and not a self-send; no +/// proof, since nothing here is admitted to consensus. +fn owned_note(keys: &AccountViewingKeys, value: u64) -> ShieldedEncryptedNote { + owned_note_with_nullifier(keys, value).0 +} + +/// [`owned_note`] plus the nullifier the account derives for it: the +/// value a later action carries when it spends this note. +fn owned_note_with_nullifier( + keys: &AccountViewingKeys, + value: u64, +) -> (ShieldedEncryptedNote, [u8; 32]) { + let mut rng = OsRng; + let (nf, rho) = loop { + let mut b = [0u8; 32]; + rng.fill_bytes(&mut b); + if let (Some(nf), Some(rho)) = ( + Nullifier::from_bytes(&b).into_option(), + Rho::from_bytes(&b).into_option(), + ) { + break (nf, rho); + } + }; + let rseed = loop { + let mut b = [0u8; 32]; + rng.fill_bytes(&mut b); + if let Some(rseed) = RandomSeed::from_bytes(b, &rho).into_option() { + break rseed; + } + }; + let value = NoteValue::from_raw(value); + let note = Note::from_parts(keys.default_address, value, rho, rseed) + .into_option() + .expect("valid note parts"); + let cmx = ExtractedNoteCommitment::from(note.commitment()); + let rcv = loop { + let mut b = [0u8; 32]; + rng.fill_bytes(&mut b); + if let Some(rcv) = ValueCommitTrapdoor::from_bytes(b).into_option() { + break rcv; + } + }; + let cv = ValueCommitment::derive(value - NoteValue::from_raw(0), rcv); + let ne = OrchardNoteEncryption::::new(None, note, [0; 36]); + let epk = OrchardDomain::::epk_bytes(ne.epk()); + let enc = ne.encrypt_note_plaintext(); + let out = ne.encrypt_outgoing_plaintext(&cv, &cmx, &mut rng); + let mut encrypted_note = Vec::with_capacity(216); + encrypted_note.extend_from_slice(&epk.0); + encrypted_note.extend_from_slice(enc.as_ref()); + encrypted_note.extend_from_slice(&out); + let own_nullifier = note.nullifier(&keys.full_viewing_key).to_bytes(); + ( + ShieldedEncryptedNote { + cmx: cmx.to_bytes().to_vec(), + nullifier: nf.to_bytes().to_vec(), + cv_net: cv.to_bytes().to_vec(), + encrypted_note, + }, + own_nullifier, + ) +} + +/// A note nobody owns at tree position `pos`: an empty ciphertext never +/// decrypts or OVK-recovers, and a distinct small commitment is a valid +/// Pallas element the tree can append. +fn opaque_note(pos: u64) -> ShieldedEncryptedNote { + let mut cmx = [0u8; 32]; + cmx[0] = pos as u8; + cmx[1] = (pos >> 8) as u8; + cmx[2] = 1; + ShieldedEncryptedNote { + cmx: cmx.to_vec(), + nullifier: vec![0xAA; 32], + cv_net: vec![], + encrypted_note: vec![], + } +} + +/// A pool that spans two fetch chunks: the first is full and opens with +/// the first owned note, the second holds only the second owned note. +/// Both chunks are proven at the mock's one block height, so the two +/// receipts fall into the same activity cluster. +async fn two_chunk_pool( + first: &ShieldedEncryptedNote, + second: &ShieldedEncryptedNote, +) -> (Arc, u64) { + chunked_pool(&[vec![first.clone()], vec![second.clone()]]).await +} + +/// A pool of full chunks, each opening with the given notes and padded +/// with opaque ones, except the last chunk, which holds its notes alone +/// and so ends the pool. Returns the SDK and the chunk size. +async fn chunked_pool(leading: &[Vec]) -> (Arc, u64) { + let mut sdk = Sdk::new_mock(); + let count = 2048 + * u64::from( + sdk.version() + .drive_abci + .query + .shielded_queries + .max_query_chunks, + ); + let last = leading.len() as u64 - 1; + let total_count = count * last + leading[last as usize].len() as u64; + // Full chunks let the stream's 16-wide speculative window slide past + // them before the short last chunk ends the pool: cover every chunk + // it may still request. + for chunk in 0..(48 + 16 * last) { + let notes: Vec = match leading.get(chunk as usize) { + Some(notes) if chunk == last => notes.clone(), + Some(notes) => notes + .iter() + .cloned() + .chain((notes.len() as u64..count).map(|i| opaque_note(count * chunk + i))) + .collect(), + None => Vec::new(), + }; + sdk.mock() + .expect_fetch( + ShieldedEncryptedNotesQuery { + start_index: count * chunk, + count: count as u32, + }, + Some(ShieldedEncryptedNotes { notes, total_count }), + ) + .await + .expect("mock pool chunk"); + } + (Arc::new(sdk), count) +} + +async fn coordinator_at( + sdk: Arc, + path: &std::path::Path, + keys: &AccountViewingKeys, + host: Arc, +) -> NetworkShieldedCoordinator { + let coordinator = NetworkShieldedCoordinator::new( + sdk, + dashcore::Network::Testnet, + path.to_path_buf(), + FileBackedShieldedStore::open_path(path, 100).expect("open test store"), + ); + coordinator + .register_wallet( + WALLET, + [(0, keys.clone())].into_iter().collect(), + WalletPersister::new(WALLET, host), + ) + .await + .expect("register test wallet"); + coordinator +} + +async fn coordinator_over( + sdk: Arc, + keys: &AccountViewingKeys, +) -> (NetworkShieldedCoordinator, Arc) { + let host = Arc::new(RecordingPersistence::default()); + let coordinator = coordinator_at(sdk, &tree_path(), keys, Arc::clone(&host)).await; + (coordinator, host) +} + +/// Cancel once the `after`-th chunk has been committed to the tree. +fn cancel_after(cancel: &CancellationToken, after: u64) -> Arc { + let stop = cancel.clone(); + let committed = Arc::new(AtomicU64::new(0)); + Arc::new(move |_, _| { + if committed.fetch_add(1, Ordering::SeqCst) + 1 >= after { + stop.cancel(); + } + }) +} + +/// Run one pass that is stopped after `after` chunks, bounded in time. +async fn cancelled_pass( + coordinator: &NetworkShieldedCoordinator, + after: u64, +) -> crate::manager::shielded_sync::ShieldedSyncPassSummary { + let cancel = CancellationToken::new(); + coordinator.install_tree_progress_handler(Some(cancel_after(&cancel, after))); + let summary = tokio::time::timeout( + std::time::Duration::from_secs(60), + coordinator.sync(true, &cancel), + ) + .await + .expect("a cancelled pass returns"); + coordinator.install_tree_progress_handler(None); + summary +} + +fn host_synced_index(host: &RecordingPersistence, sub: SubwalletId) -> Option { + host.recorded() + .iter() + .filter_map(|changeset| changeset.synced_indices.get(&sub).copied()) + .max() +} + +fn host_note_values(host: &RecordingPersistence, sub: SubwalletId) -> Vec { + let mut values: Vec = host + .recorded() + .iter() + .flat_map(|changeset| changeset.notes_saved.get(&sub).cloned().unwrap_or_default()) + .map(|note| note.value) + .collect(); + values.sort_unstable(); + values +} + +async fn activity(coordinator: &NetworkShieldedCoordinator) -> Vec { + let mut entries = coordinator + .store() + .read() + .await + .get_activity(SubwalletId::new(WALLET, 0), 0, usize::MAX) + .expect("read activity"); + for entry in &mut entries { + entry.note_cmxs.sort(); + } + entries.sort_by_key(|entry| entry.id); + entries +} + +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn should_publish_nothing_when_cancelled_and_match_an_uninterrupted_scan_after() { + let keys = viewing_keys(); + let sub = SubwalletId::new(WALLET, 0); + let first = owned_note(&keys, FIRST_VALUE); + let second = owned_note(&keys, SECOND_VALUE); + + // The same pool, scanned in one go: the reference history. + let (baseline_sdk, _) = two_chunk_pool(&first, &second).await; + let (baseline, _) = coordinator_over(baseline_sdk, &keys).await; + let summary = baseline.sync(true, &CancellationToken::new()).await; + assert_eq!( + baseline + .store() + .read() + .await + .get_all_notes(sub) + .expect("notes") + .len(), + 2, + "the uninterrupted scan finds both receipts: {summary:?}" + ); + let expected = activity(&baseline).await; + assert_eq!(expected.len(), 1, "both receipts share one cluster"); + assert_eq!(expected[0].amount, FIRST_VALUE + SECOND_VALUE); + assert_eq!(expected[0].note_cmxs.len(), 2); + + // Pass 1: the stop lands after the first chunk is committed. + let (sdk, count) = two_chunk_pool(&first, &second).await; + let (coordinator, host) = coordinator_over(sdk, &keys).await; + let summary = cancelled_pass(&coordinator, 1).await; + assert!( + summary.wallet_results.is_empty(), + "a cut-short pass reports no completion: {summary:?}" + ); + { + let store = coordinator.store().read().await; + assert_eq!( + store.tree_size().expect("tree"), + count, + "the first chunk's commitments stay appended" + ); + assert!( + store.get_all_notes(sub).expect("notes").is_empty(), + "a receipt from a consumed prefix does not enter the ledger" + ); + assert_eq!( + store.last_synced_note_index(sub).expect("watermark"), + 0, + "the watermark only moves when a pass reaches the tip" + ); + let balance = store.local_account_balance(sub).expect("balance"); + assert_eq!(balance.source, ShieldedBalanceSource::NoHistory); + assert_eq!(balance.last_scanned_index, None); + } + assert!(activity(&coordinator).await.is_empty()); + assert!(host.recorded().is_empty(), "nothing reaches the host"); + assert_eq!( + coordinator + .local_balance_snapshot(WALLET) + .await + .expect("snapshot"), + ShieldedLocalBalanceState::RestoreIncomplete, + "an unhydrated account must not read as ready after a cut-short pass" + ); + + // Pass 2: re-walks from the completed watermark (appends are skipped + // by the tree size) and reaches the tip. + let summary = coordinator.sync(true, &CancellationToken::new()).await; + assert_eq!(summary.success_count(), 1); + { + let store = coordinator.store().read().await; + assert_eq!(store.tree_size().expect("tree"), count + 1); + assert_eq!(store.get_all_notes(sub).expect("notes").len(), 2); + let balance = store.local_account_balance(sub).expect("balance"); + assert_eq!(balance.source, ShieldedBalanceSource::ScannedThisSession); + assert_eq!(balance.last_scanned_index, Some(count + 1)); + assert_eq!(balance.spendable_credits, FIRST_VALUE + SECOND_VALUE); + } + assert_eq!( + activity(&coordinator).await, + expected, + "cancel + re-walk must derive the same history as one uninterrupted scan" + ); + assert_eq!( + host_note_values(&host, sub), + vec![FIRST_VALUE, SECOND_VALUE] + ); + assert_eq!( + host_synced_index(&host, sub), + Some(count + 1), + "the completed pass is the first thing the host sees" + ); + match coordinator + .local_balance_snapshot(WALLET) + .await + .expect("snapshot") + { + ShieldedLocalBalanceState::Ready(snapshot) => { + assert_eq!( + snapshot.accounts[&0].spendable_credits, + FIRST_VALUE + SECOND_VALUE + ); + } + other => panic!("expected a ready ledger, got {other:?}"), + } +} + +/// Cancel → persist → restart → restore, with no owned note in the +/// cancelled prefix (the worst case: a restored account that reads as +/// covered would read as an empty, finished scan). The host has nothing +/// to restore, the reopened tree still holds the appended prefix, and +/// the first pass after the restart finds the receipt the cancelled +/// pass never reached. +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn should_not_restore_scan_coverage_from_a_cancelled_prefix() { + let keys = viewing_keys(); + let sub = SubwalletId::new(WALLET, 0); + // No receipt in the first chunk: make the "first" note someone else's + // by encrypting it to a different account. + let foreign = OrchardKeySet::from_seed(&[43; 64], dashcore::Network::Testnet, 0) + .expect("foreign viewing key") + .viewing_keys(); + let first = owned_note(&foreign, FIRST_VALUE); + let second = owned_note(&keys, SECOND_VALUE); + let path = tree_path(); + + // Session 1: the pass is stopped after the first (foreign-only) chunk. + let host = Arc::new(RecordingPersistence::default()); + { + let (sdk, count) = two_chunk_pool(&first, &second).await; + let coordinator = coordinator_at(sdk, &path, &keys, Arc::clone(&host)).await; + cancelled_pass(&coordinator, 1).await; + let store = coordinator.store().read().await; + assert_eq!(store.tree_size().expect("tree"), count); + assert_eq!(store.last_synced_note_index(sub).expect("cursor"), 0); + assert!(store.get_all_notes(sub).expect("notes").is_empty()); + } + assert!(host.recorded().is_empty()); + + // Session 2: reopen the same tree file, restore what the host kept, + // and read the ledger offline as a cold bind does. + let (sdk, count) = two_chunk_pool(&first, &second).await; + let coordinator = coordinator_at(sdk, &path, &keys, Arc::clone(&host)).await; + coordinator + .restore_for_wallet(WALLET, &host.start_state()) + .await + .expect("restore"); + coordinator.mark_hydrated(WALLET, true).await; + match coordinator + .local_balance_snapshot(WALLET) + .await + .expect("snapshot") + { + ShieldedLocalBalanceState::Ready(snapshot) => { + let account = snapshot.accounts[&0]; + assert_eq!(account.spendable_credits, 0); + assert_eq!( + account.last_scanned_index, None, + "a cancelled prefix must not come back as scan coverage" + ); + assert_eq!(account.source, ShieldedBalanceSource::NoHistory); + } + other => panic!("expected the hydrated ledger, got {other:?}"), + } + { + let store = coordinator.store().read().await; + assert_eq!( + store.tree_size().expect("tree"), + count, + "the reopened tree keeps the appended prefix" + ); + assert_eq!(store.last_synced_note_index(sub).expect("cursor"), 0); + } + + // The first pass after the restart re-walks the prefix (gate-skipped + // by the persisted tree) and reaches the receipt. + let summary = coordinator.sync(true, &CancellationToken::new()).await; + assert_eq!(summary.success_count(), 1); + let store = coordinator.store().read().await; + let balance = store.local_account_balance(sub).expect("balance"); + assert_eq!(balance.spendable_credits, SECOND_VALUE); + assert_eq!(balance.last_scanned_index, Some(count + 1)); + assert_eq!(balance.source, ShieldedBalanceSource::ScannedThisSession); + drop(store); + assert_eq!(host_note_values(&host, sub), vec![SECOND_VALUE]); + assert_eq!(host_synced_index(&host, sub), Some(count + 1)); + let _ = std::fs::remove_file(&path); +} + +/// The receipt is in chunk 0 and the action that spends it in chunk 1. +/// Session 1 is cancelled after chunk 1 and session 2, after a restart, +/// after chunk 0 — the one order in which a published prefix would have +/// shown the receipt as spendable (receipt in, spend not yet replayed). +/// Neither stop publishes anything, so the receipt never appears +/// unspent in the ledger, in a balance or at the host; the pass that +/// reaches the tip records it spent from the start. +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn should_never_show_a_spent_receipt_as_spendable_across_cancelled_restarts() { + let keys = viewing_keys(); + let sub = SubwalletId::new(WALLET, 0); + let (receipt, own_nullifier) = owned_note_with_nullifier(&keys, FIRST_VALUE); + let mut spend = opaque_note(u64::MAX); + spend.nullifier = own_nullifier.to_vec(); + let tail = owned_note(&keys, SECOND_VALUE); + let layout = [vec![receipt], vec![spend], vec![tail]]; + let path = tree_path(); + + // Session 1: receipt and its spend consumed, then stopped. + let host = Arc::new(RecordingPersistence::default()); + { + let (sdk, count) = chunked_pool(&layout).await; + let coordinator = coordinator_at(sdk, &path, &keys, Arc::clone(&host)).await; + cancelled_pass(&coordinator, 2).await; + let store = coordinator.store().read().await; + assert_eq!(store.tree_size().expect("tree"), 2 * count); + assert!(store.get_all_notes(sub).expect("notes").is_empty()); + assert_eq!(store.spendable_balance(sub).expect("balance"), 0); + } + assert!(host.recorded().is_empty()); + + // Session 2: restart, re-walk chunk 0 only, stop again. + let (sdk, count) = chunked_pool(&layout).await; + let coordinator = coordinator_at(sdk, &path, &keys, Arc::clone(&host)).await; + coordinator + .restore_for_wallet(WALLET, &host.start_state()) + .await + .expect("restore"); + coordinator.mark_hydrated(WALLET, true).await; + cancelled_pass(&coordinator, 1).await; + { + let store = coordinator.store().read().await; + assert!( + store.get_all_notes(sub).expect("notes").is_empty(), + "a receipt whose spend was not replayed must not enter the ledger" + ); + assert_eq!(store.spendable_balance(sub).expect("balance"), 0); + assert_eq!(store.last_synced_note_index(sub).expect("cursor"), 0); + assert_eq!(store.tree_size().expect("tree"), 2 * count); + } + assert!(host.recorded().is_empty(), "nothing reaches the host"); + match coordinator + .local_balance_snapshot(WALLET) + .await + .expect("snapshot") + { + ShieldedLocalBalanceState::Ready(snapshot) => { + assert_eq!(snapshot.accounts[&0].spendable_credits, 0); + } + other => panic!("expected the hydrated ledger, got {other:?}"), + } + + // The pass that reaches the tip records the receipt spent from the + // start and finds the tail. + coordinator.sync(true, &CancellationToken::new()).await; + let store = coordinator.store().read().await; + let mut values: Vec<(u64, bool)> = store + .get_all_notes(sub) + .expect("notes") + .iter() + .map(|note| (note.value, note.is_spent)) + .collect(); + values.sort_unstable(); + assert_eq!(values, vec![(FIRST_VALUE, true), (SECOND_VALUE, false)]); + assert_eq!(store.spendable_balance(sub).expect("balance"), SECOND_VALUE); + drop(store); + assert_eq!( + host_note_values(&host, sub), + vec![FIRST_VALUE, SECOND_VALUE] + ); + assert!(host.recorded().iter().any(|changeset| changeset + .nullifiers_spent + .get(&sub) + .is_some_and(|nfs| nfs.contains(&own_nullifier)))); + let _ = std::fs::remove_file(&path); +} diff --git a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs index 731b35e51ad..884f44d8dda 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/coordinator.rs @@ -55,6 +55,10 @@ use std::collections::{BTreeMap, HashSet}; use std::path::PathBuf; use std::sync::Arc; +use tokio_util::sync::CancellationToken; + +use crate::changeset::merge::Merge; + /// Callback fired once per chunk during a coordinator sync pass — /// the **"downloaded"** progress signal. /// Arguments: `(cumulative_scanned, latest_block_height)`. Forwarded @@ -1311,10 +1315,31 @@ impl NetworkShieldedCoordinator { /// per-[`WalletId`] and queued through each registered /// [`WalletPersister`]. /// + /// Cancellation: `cancel` is checked before every network step and + /// between note batches. A scan cut short keeps the commitments it + /// appended to the local tree and publishes nothing else (see + /// [`sync_notes_across`]): the pass then returns the empty summary, + /// so the manager reports no completion and the host sees no + /// partial ledger. A stop that lands after the scan completed skips + /// the remaining network work (spend re-drives, stranded releases, + /// identity-shield re-drives) but still runs the store-only steps + /// and flushes the completed scan to the host persisters. The + /// caught-up cooldown is never stamped by a cancelled pass. + /// /// [`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 { + // 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 @@ -1366,7 +1391,13 @@ 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 = cancel + .run_until_cancelled(self.prefetch_stranded_release(&subwallets)) + .await + .flatten(); // ONE SDK call covers every registered IVK on the network. // Snapshot the optional progress handler installed by the @@ -1384,12 +1415,38 @@ 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 a + // COMPLETED scan still run (see the method docs). + // + // Snapshotted here on purpose: the cooldown decision below is + // about whether the 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 scan cut short publishes nothing (`sync_notes_across` returns + // the empty result whether the stop landed in the prefetch, before + // the store lock or between batches): 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 && Merge::is_empty(¬es.changeset) { + // The scan may have appended new leaves before the stop, so the + // chain has moved past whatever the last completed pass saw: + // drop the caught-up stamp so the next pass walks Platform at + // once instead of taking the cooldown skip. + if let Ok(mut guard) = self.last_caught_up_at.lock() { + *guard = None; + } + tracing::debug!("Coordinator sync cancelled; the scan published nothing"); + 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 @@ -1413,8 +1470,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: the re-drive + // broadcasts, 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 @@ -1428,6 +1486,12 @@ impl NetworkShieldedCoordinator { .collect() }; for (id, persister) in &subwallet_persisters { + // Network broadcasts: a stop that lands after the scan's + // snapshot above stops the loop here, and the helper + // checks the token before each request it starts. + if cancel.is_cancelled() { + break; + } super::operations::redrive_pending_spends( &self.sdk, &self.store, @@ -1435,10 +1499,13 @@ impl NetworkShieldedCoordinator { id.wallet_id, *id, &recorded, + cancel, ) .await; } - self.release_stranded_spends(snapshot, &recorded).await; + if !cancel.is_cancelled() { + self.release_stranded_spends(snapshot, &recorded).await; + } } let balances_per_sub = match super::sync::balances_across(&self.store, &subwallets).await { @@ -1454,6 +1521,13 @@ impl NetworkShieldedCoordinator { // id a live entry already owns, and `save_activity` upserts by // id, so re-running is idempotent. Failures are logged and // swallowed: a derivation miss must never fail a sync pass. + // + // Only a completed scan reaches this point (a cut-short one + // returned above), which matters here: derived entries are + // immutable clusters keyed by the discovering chunk's proof + // height, so deriving over a consumed prefix would freeze a + // cluster that a later note at the same height could only + // confirm, never extend. let mut notes = notes; if let Err(e) = self .derive_activity_into_changeset(&subwallets, &mut notes.changeset) @@ -1470,8 +1544,19 @@ 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 { - super::operations::redrive_pending_identity_shields(&self.sdk, &self.store, wallet_id) - .await; + // Network requests: stop between wallets once cancelled; the + // helper also checks the token between records and before + // each request it starts. + if cancel.is_cancelled() { + break; + } + super::operations::redrive_pending_identity_shields( + &self.sdk, + &self.store, + wallet_id, + cancel, + ) + .await; } // The note-side changeset already carries saves, synced @@ -1479,7 +1564,7 @@ impl NetworkShieldedCoordinator { // WalletId directly — each per-wallet `WalletPersister.store` // only sees its own wallet's deltas. let consolidated = notes.changeset.clone(); - if !crate::changeset::merge::Merge::is_empty(&consolidated) { + if !Merge::is_empty(&consolidated) { let per_wallet = consolidated.split_by_wallet_id(); let persisters = self.persisters.read().await; for (wallet_id, cs) in per_wallet { @@ -1507,15 +1592,23 @@ 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. Only a NEW stamp + // needs an uncancelled pass: a stop after a complete scan that + // found nothing proves nothing about staying caught up, so the + // next pass walks Platform again right away. 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 { + } else if !cancelled { *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 +3796,51 @@ 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); + } + + /// 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/mod.rs b/packages/rs-platform-wallet/src/wallet/shielded/mod.rs index 3b986f0b770..e5c92c28be6 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/mod.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/mod.rs @@ -38,6 +38,8 @@ pub mod activity_recorder; pub mod balance; #[cfg(test)] mod balance_tests; +#[cfg(test)] +mod cancelled_scan_tests; pub mod coordinator; pub mod file_store; pub mod fund_from_asset_lock; diff --git a/packages/rs-platform-wallet/src/wallet/shielded/operations.rs b/packages/rs-platform-wallet/src/wallet/shielded/operations.rs index ea864889a3f..8a8f8a4b39b 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/operations.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/operations.rs @@ -73,6 +73,7 @@ use dpp::withdrawal::Pooling; use dpp::ProtocolError; use grovedb_commitment_tree::{Anchor, PaymentAddress}; use tokio::sync::RwLock; +use tokio_util::sync::CancellationToken; use tracing::{debug, info, trace, warn}; /// Number of Orchard actions in a `Shield` (Type 15) bundle. @@ -3118,6 +3119,7 @@ pub(super) async fn redrive_pending_identity_shields( sdk: &Arc, store: &Arc>, wallet_id: WalletId, + cancel: &CancellationToken, ) { use dpp::serialization::PlatformDeserializableTrusted; use dpp::state_transition::shield_from_identity_transition::accessors::ShieldFromIdentityTransitionAccessorsV0; @@ -3130,6 +3132,13 @@ pub(super) async fn redrive_pending_identity_shields( } }; for (id, redrive) in redrives { + // A stop ends the pass between records: no new request starts + // once cancelled. A request already on the wire is left to + // finish on its own (its outcome is handled conservatively). + if cancel.is_cancelled() { + debug!("identity redrive: pass cancelled; remaining guards wait for the next pass"); + return; + } if !redrive.nullifiers.is_empty() || redrive.identity_nonce_finalized || redrive.identity_user_abandoned @@ -3147,9 +3156,19 @@ pub(super) async fn redrive_pending_identity_shields( let StateTransition::ShieldFromIdentity(identity_transition) = &state_transition else { continue; }; - if let Ok(fetched) = - IdentityNonceFetcher::fetch(sdk, identity_transition.identity_id()).await - { + // The nonce read is the one wait here a stop can cut short: it + // is read-only, so dropping it mid-flight loses nothing. + let Some(fetched) = cancel + .run_until_cancelled(IdentityNonceFetcher::fetch( + sdk, + identity_transition.identity_id(), + )) + .await + else { + debug!("identity redrive: pass cancelled during the nonce read"); + return; + }; + if let Ok(fetched) = fetched { let result = { let mut store = store.write().await; reconcile_identity_shield_nonce( @@ -3188,6 +3207,12 @@ pub(super) async fn redrive_pending_identity_shields( if !still_active { continue; } + // Last check before a broadcast starts; a broadcast already + // submitted cannot be cancelled by this check. + if cancel.is_cancelled() { + debug!("identity redrive: pass cancelled before the re-broadcast"); + return; + } // Unused or unverified state permits only the original signed bytes. // Even an apparently definitive rejection cannot release the guard: // this request, or an earlier relay, may deliver the debit afterward. @@ -3223,6 +3248,7 @@ pub(super) async fn redrive_pending_spends( wallet_id: WalletId, id: SubwalletId, recorded: &std::collections::HashSet<[u8; 32]>, + cancel: &CancellationToken, ) { use dpp::serialization::PlatformDeserializableTrusted; @@ -3237,6 +3263,13 @@ pub(super) async fn redrive_pending_spends( } }; for redrive in redrives { + // A stop ends the pass between records: no new re-broadcast starts + // once cancelled. One already submitted is left to finish and is + // classified as usual — its outcome handling stays conservative. + if cancel.is_cancelled() { + debug!("redrive: pass cancelled; remaining records wait for the next pass"); + return; + } // Empty-nullifier identity debits are wallet-wide and are driven by // `redrive_pending_identity_shields`, independently of spending anchors. if redrive.nullifiers.is_empty() { @@ -3646,8 +3679,13 @@ mod redrive_tests { assert!(!has_unresolved_identity_shield(&store, wallet_id, identity_id).unwrap()); let store = Arc::new(RwLock::new(store)); // No mock nonce responses: accidentally retrying would reach an unconfigured SDK. - redrive_pending_identity_shields(&Arc::new(dash_sdk::Sdk::new_mock()), &store, wallet_id) - .await; + redrive_pending_identity_shields( + &Arc::new(dash_sdk::Sdk::new_mock()), + &store, + wallet_id, + &CancellationToken::new(), + ) + .await; assert_eq!( store.read().await.pending_redrives(id).unwrap(), vec![archived.clone()] @@ -3711,7 +3749,7 @@ mod redrive_tests { assert!(store.pending_redrives(id).unwrap()[0].identity_nonce_finalized); let store = Arc::new(RwLock::new(store)); let sdk = Arc::new(dash_sdk::Sdk::new_mock()); - redrive_pending_identity_shields(&sdk, &store, wallet_id).await; + redrive_pending_identity_shields(&sdk, &store, wallet_id, &CancellationToken::new()).await; assert_eq!( store.read().await.pending_redrives(id).unwrap()[0].attempts, 0, @@ -3900,7 +3938,7 @@ mod redrive_tests { ) .expect("arm identity guard"); - redrive_pending_identity_shields(&sdk, &store, wallet_id).await; + redrive_pending_identity_shields(&sdk, &store, wallet_id, &CancellationToken::new()).await; let retained = store .read() @@ -3947,7 +3985,16 @@ mod redrive_tests { .expect("arm identity guard"); let recorded = [anchor].into_iter().collect(); - redrive_pending_spends(&sdk, &store, None, wallet_id, id, &recorded).await; + redrive_pending_spends( + &sdk, + &store, + None, + wallet_id, + id, + &recorded, + &CancellationToken::new(), + ) + .await; let retained = store.read().await.pending_redrives(id).expect("guard"); assert_eq!(retained.len(), 1); @@ -3993,7 +4040,16 @@ mod redrive_tests { let recorded: std::collections::HashSet<[u8; 32]> = [[11u8; 32], [12u8; 32]].into_iter().collect(); - redrive_pending_spends(&sdk, &store, None, wallet_id, id, &recorded).await; + redrive_pending_spends( + &sdk, + &store, + None, + wallet_id, + id, + &recorded, + &CancellationToken::new(), + ) + .await; let left = store.read().await.pending_redrives(id).unwrap(); let ids: Vec<[u8; 32]> = left.iter().map(|r| r.activity_id).collect(); diff --git a/packages/rs-platform-wallet/src/wallet/shielded/store.rs b/packages/rs-platform-wallet/src/wallet/shielded/store.rs index 6e20a0ae1fc..8efd0acfdcb 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/store.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/store.rs @@ -469,7 +469,10 @@ pub trait ShieldedStore: Send + Sync { /// (scanning through position `N-1` sets this to `N`). fn last_synced_note_index(&self, id: SubwalletId) -> Result; - /// Persist the sync watermark (next index to scan) for `id`. + /// Persist the sync watermark (next index to scan) for `id`. Only a + /// pass that reached the tip calls this: the setter also records the + /// scan coverage and the `ScannedThisSession` balance source behind + /// [`local_account_balance`](Self::local_account_balance). fn set_last_synced_note_index( &mut self, id: SubwalletId, diff --git a/packages/rs-platform-wallet/src/wallet/shielded/sync.rs b/packages/rs-platform-wallet/src/wallet/shielded/sync.rs index cddaed6718d..7d4cb149951 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; @@ -193,21 +195,126 @@ 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), checkpoints the commitments it +/// appended to the local tree, and publishes NOTHING else: no notes, no +/// spent marks, no watermark, an empty result. A consumed prefix is not +/// a complete scan — a receipt in it may already be spent by an action +/// in a chunk it never reached, and the ledger has no way to hold such a +/// note without offering it for selection. The next pass re-walks from +/// the last completed watermark; the appended leaves make that re-walk +/// skip every append and checkpoint it already made, so what a stop +/// costs is the download and decryption of the chunks it had consumed. +/// 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: MAX_CONCURRENT_CHUNK_FETCHES, + ..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()); + } + + // 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()); + } + // Keep the snapshot and streamed consume under one write guard so another // sync cannot append between them and leave this pass using stale gates. - // SDK fetches never access the store, so the stream can run under this lock. - let mut store = store.write().await; + // This is the only writer during a pass, so holding it across + // `stream.next().await` is safe: the stream's producer side is the + // SDK's network fetch loop, which never touches the store, so there + // is no lock-ordering deadlock. Backpressure is pull-based — a slow + // append simply polls the stream less often, capping in-flight + // network fetches at `max_concurrent`. + // + // The wait for the guard observes the token too: a pass queued behind + // another writer (a spend flow, a concurrent scan in tests) has made + // no mutation yet, so a stop that lands here returns at once instead + // of after the unrelated holder is done. + let Some(mut store) = cancel.run_until_cancelled(store.write()).await else { + debug!("Shielded note sync cancelled while waiting for the store lock"); + return Ok(MultiSyncNotesResult::default()); + }; // Snapshot each subwallet's watermark and the shared tree's // current leaf count. Two distinct quantities drive the rest @@ -268,49 +375,9 @@ 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: MAX_CONCURRENT_CHUNK_FETCHES, - ..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); - })); - } - - let stream = sync_shielded_notes_stream(sdk, &driver_ivk, aligned_start, Some(sync_config)); - futures::pin_mut!(stream); + // The FIRST subwallet drives the stream (see `sync_notes_across`); + // its hits arrive pre-decrypted in `batch.decrypted`. + let (driver_id, _) = &subwallets[0]; // Route decryptions to the subwallet that owns the IVK, accumulated // across every batch. @@ -401,125 +468,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 the tree one checkpoint + // further along and nothing else to publish. `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; committing tree progress only" + ); + 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: @@ -542,6 +636,7 @@ pub(super) async fn sync_notes_across( .map(|v| v.len()) .unwrap_or(0), next_start_index, + cancelled, "SDK stream consumed" ); @@ -575,6 +670,20 @@ pub(super) async fn sync_notes_across( .map_err(|e| PlatformWalletError::ShieldedTreeUpdateFailed(e.to_string()))?; } + // A cancelled pass ends here: the appended leaves are checkpointed + // (the next pass skips them), and nothing the prefix decrypted is + // saved, replayed, watermarked or handed to the caller. See the + // cancellation note on `sync_notes_across` for why a consumed prefix + // must not reach the ledger. + if cancelled { + drop(store); + info!( + total_scanned = total_notes_scanned, + appended, "Shielded note sync stopped; tree progress kept, nothing published" + ); + return Ok(MultiSyncNotesResult::default()); + } + // Save decrypted notes per subwallet; count new notes per // subwallet; build a single consolidated changeset. let mut per_subwallet_new_notes: BTreeMap = BTreeMap::new(); @@ -688,12 +797,23 @@ pub(super) async fn sync_notes_across( // 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 that re-walks a lagging subwallet's range can + // end below a subwallet that was already further along; a completed + // pass reaches the tip, which is at or past every watermark. Only a + // completed pass gets here (a cancelled one returned above), so the + // write is unconditional: the setter also stamps the scan coverage + // and the `ScannedThisSession` balance source, which is exactly what + // reaching the tip means. 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); 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 @@ -1073,5 +1193,11 @@ mod ovk_builder_roundtrip_tests; #[cfg(test)] mod memo_roundtrip_tests; +/// Cancellation of a note-sync pass: a scan cut short keeps only its tree +/// progress and publishes nothing, a pre-scan cancel touches nothing, and +/// a later pass re-walks the prefix without re-appending it. +#[cfg(test)] +mod cancel_tests; + #[cfg(test)] mod concurrent_sync_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..a683da2d53c --- /dev/null +++ b/packages/rs-platform-wallet/src/wallet/shielded/sync/cancel_tests.rs @@ -0,0 +1,353 @@ +//! Cancellation of a note-sync pass (dashpay/platform#5200). +//! +//! Feeds `sync_notes_from_stream` a synthetic batch stream so the +//! cancel path runs 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. +//! A cut-short pass keeps the tree progress it made and publishes +//! nothing else; the next pass re-walks from the completed watermark. + +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::balance::ShieldedBalanceSource; +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 subwallet(account: u32) -> (SubwalletId, AccountViewingKeys) { + let views = OrchardKeySet::from_seed(&[0x42u8; 64], dashcore::Network::Testnet, account) + .expect("derive viewing keys") + .viewing_keys(); + (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 +/// 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_keep_tree_progress_and_publish_nothing_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 appended leaves stay, checkpointed; nothing else is published. + assert_eq!(result.total_scanned, 0, "a cut-short pass reports no scan"); + assert!(crate::changeset::merge::Merge::is_empty(&result.changeset)); + let store = store.read().await; + assert_eq!(store.tree_size().unwrap(), 8, "both batches appended"); + assert!( + store.witness(7).unwrap().is_some(), + "a checkpoint covers the appended leaves" + ); + assert_eq!( + store.last_synced_note_index(sub).unwrap(), + 0, + "the watermark only moves when a pass reaches the tip" + ); + let balance = store.local_account_balance(sub).unwrap(); + assert_eq!(balance.last_scanned_index, None); + assert_eq!(balance.source, ShieldedBalanceSource::NoHistory); + + 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_rewalk_the_appended_prefix_without_reappending_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(), 0); + assert_eq!(store.read().await.tree_size().unwrap(), 8); + + // Pass 2: re-walks from the completed watermark (0), 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, 12, + "the whole range from the completed watermark is scanned" + ); + 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 balance = store.local_account_balance(sub).unwrap(); + assert_eq!(balance.last_scanned_index, Some(12)); + assert_eq!( + balance.source, + ShieldedBalanceSource::ScannedThisSession, + "the completed pass certifies the scan" + ); + + 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: neither watermark moves, and the +/// changeset carries nothing to the host. +#[tokio::test] +async fn should_leave_every_watermark_alone_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.tree_size().unwrap(), 8); + assert_eq!(store.last_synced_note_index(lagging).unwrap(), 0); + assert_eq!( + store.last_synced_note_index(advanced).unwrap(), + 12, + "a partial prefix below a subwallet's watermark must not rewind it" + ); + assert!( + crate::changeset::merge::Merge::is_empty(&result.changeset), + "a cancelled pass sends nothing to the host" + ); + + 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. +#[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" + ); + 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); +} + +/// Cancelled while another writer holds the store: the pass has touched +/// nothing yet, so it must return without waiting for that writer. +#[tokio::test] +async fn should_return_while_waiting_for_the_store_lock_when_cancelled() { + let path = temp_tree_path("lock_wait"); + 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 held = store.write().await; + let pass = sync_notes_from_stream(&store, &subwallets, None, &cancel, |_, _| { + futures::stream::iter(vec![batch(0, 4, 4)].into_iter().map(Ok)) + }); + futures::pin_mut!(pass); + assert!( + futures::poll!(pass.as_mut()).is_pending(), + "the pass is queued behind the held guard" + ); + + cancel.cancel(); + let result = tokio::time::timeout(std::time::Duration::from_secs(2), pass.as_mut()) + .await + .expect("a cancelled pass returns without the guard") + .expect("pass must succeed"); + assert_eq!(result.total_scanned, 0); + assert!(crate::changeset::merge::Merge::is_empty(&result.changeset)); + + drop(held); + let store = store.read().await; + assert_eq!(store.tree_size().unwrap(), 0, "nothing was appended"); + assert_eq!(store.last_synced_note_index(sub).unwrap(), 0); + + let _ = std::fs::remove_file(&path); +} diff --git a/packages/rs-platform-wallet/src/wallet/shielded/sync/concurrent_sync_tests.rs b/packages/rs-platform-wallet/src/wallet/shielded/sync/concurrent_sync_tests.rs index ace5a8c37e6..1a5486fc4ee 100644 --- a/packages/rs-platform-wallet/src/wallet/shielded/sync/concurrent_sync_tests.rs +++ b/packages/rs-platform-wallet/src/wallet/shielded/sync/concurrent_sync_tests.rs @@ -6,6 +6,7 @@ use drive_proof_verifier::types::{ ShieldedEncryptedNote, ShieldedEncryptedNotes, ShieldedEncryptedNotesQuery, }; use tokio::sync::RwLock; +use tokio_util::sync::CancellationToken; use super::{sync_notes_across, MAX_CONCURRENT_CHUNK_FETCHES}; use crate::wallet::shielded::keys::{AccountViewingKeys, OrchardKeySet}; @@ -76,15 +77,16 @@ async fn assert_concurrent_sync_matches_sequential(initial_size: u8) { .collect(); let sequential = seeded_store(initial_size, subwallets[0].0); let concurrent = seeded_store(initial_size, subwallets[0].0); + let never = CancellationToken::new(); let baseline_sdk = pool_sdk(4).await; - sync_notes_across(&baseline_sdk, &sequential, &subwallets, None, None) + sync_notes_across(&baseline_sdk, &sequential, &subwallets, None, None, &never) .await .unwrap(); let first_sdk = pool_sdk(4).await; let second_sdk = pool_sdk(4).await; - let first = sync_notes_across(&first_sdk, &concurrent, &subwallets, None, None); - let second = sync_notes_across(&second_sdk, &concurrent, &subwallets, None, None); + let first = sync_notes_across(&first_sdk, &concurrent, &subwallets, None, None, &never); + let second = sync_notes_across(&second_sdk, &concurrent, &subwallets, None, None, &never); futures::pin_mut!(first, second); // Queue both at their first store lock, without sleeps or scheduler races. @@ -118,7 +120,7 @@ async fn assert_concurrent_sync_matches_sequential(initial_size: u8) { // A later real position must remain appendable after the overlapping scans. let next_sdk = pool_sdk(5).await; - sync_notes_across(&next_sdk, &concurrent, &subwallets, None, None) + sync_notes_across(&next_sdk, &concurrent, &subwallets, None, None, &never) .await .unwrap(); let actual = concurrent.read().await; diff --git a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift index 97d86c8dfb9..617c00d1160 100644 --- a/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift +++ b/packages/swift-sdk/Sources/SwiftDashSDK/PlatformWallet/PlatformWalletManagerShieldedSync.swift @@ -321,11 +321,15 @@ extension PlatformWalletManager { /// Stop the shielded sync loop, waiting on the calling thread. /// - /// The native stop cancels the loop, then waits up to 10 s (the Rust - /// coordinator's drain budget) for a pass in flight to finish. On the - /// main actor that freezes the UI for as long; the async overload runs - /// the same stop off the main thread. If the pass does not drain in time - /// this throws `shutdownIncomplete`, before bumping the generation. + /// The native stop cancels the loop and the pass in flight, then waits + /// up to 10 s (the Rust coordinator's drain budget) for that pass to + /// stop at its next checkpoint; a scan cut short publishes nothing and + /// the next pass re-walks from the last completed watermark. On the + /// main actor the wait freezes the UI for as long; the async overload + /// runs the same stop off the main thread. If the pass does not drain + /// in time (it is wedged in a host persister, or in a broadcast the + /// SDK is still retrying) this throws `shutdownIncomplete`, before + /// bumping the generation. /// /// Throws `walletOperation` while an async [`stopShieldedSync()`] is in /// flight: this stop would wait on the same drain on the calling thread. @@ -348,11 +352,13 @@ extension PlatformWalletManager { /// context overload resolution prefers this variant; sync contexts keep /// the blocking one. /// - /// The native stop cancels the loop at once, so no new pass starts, then - /// waits up to 10 s for a pass in flight to finish; a running pass cannot - /// be interrupted. If it does not drain in time this throws - /// `shutdownIncomplete`, and the pass keeps running: it can still persist - /// what it finds and deliver its events after this returns. + /// The native stop cancels the loop at once, so no new pass starts, and + /// cancels the pass in flight, which stops at its next checkpoint and + /// publishes nothing; the stop waits up to 10 s for it to do so. If it + /// does not drain in time (wedged in a host persister, or in a broadcast + /// the SDK is still retrying) this throws `shutdownIncomplete`, and the + /// pass keeps running: it can still persist what it finds and deliver + /// its events after this returns. /// /// Events: while the stop is in flight, progress events that reach the /// main actor are dropped, and a completion is held