Skip to content

Unrelated wallet persists can flush address reveals the pool record does not cover #1213

Open

Description

@jkczyz

At main 9386a1c92bf9515c349fb33ae80496542fdd9ddc, refill_address_pool_inner stages newly revealed addresses into the persister's shared pending change set, then writes the pool record and only afterwards flushes the reveals. When the record write fails the refill deliberately skips the reveal flush so that no index becomes durable without record coverage. But the pending set is the same one every other persist_changeset call flushes, so an unrelated sync or transaction persist that succeeds afterwards makes the reveals durable while the record still omits them. If the process restarts before the next refill rewrites the record, those indices are revealed in the persisted wallet but never pooled or handed out again. Refills only run at startup and after a handout, so the window stays open until the next pop. This does not need a hostile store: a transient failure on the record write followed by a successful sync persist and a restart is enough. Each event burns one or two indices after a pop (up to 16 at startup), and the comment on the refill already notes the window is narrowed rather than closed. Repeated events with no deposit in between accumulate towards the default full-scan stop gap of 20, after which a restore from seed misses later funds.

Keep reveals whose record coverage has not been persisted out of the change set that unrelated persist calls flush. One approach: stage the refill's reveals into a separate pending set that only the refill's own flush, after a successful record write, merges into the one persist_changeset uses. Test by staging a reveal, failing the pool-record write, performing an unrelated persist, reloading the wallet and asserting the reveal was not persisted. Both the test and the fix below were verified at this commit.

Regression test (fails on the current implementation, passes with the fix below):

diff --git a/src/wallet/persist.rs b/src/wallet/persist.rs
index 6384d0fce..d807011de 100644
--- a/src/wallet/persist.rs
+++ b/src/wallet/persist.rs
@@ -308,6 +308,7 @@ impl AsyncWalletPersister for KVStoreWalletPersister {
 #[cfg(test)]
 mod tests {
 	use std::future::Future;
+	use std::sync::atomic::{AtomicBool, Ordering};
 	use std::sync::Arc;
 	use std::time::Duration;
 
@@ -328,6 +329,7 @@ mod tests {
 	struct GatedStore {
 		inner: Arc<InMemoryStore>,
 		write_gate: Arc<tokio::sync::RwLock<()>>,
+		fail_writes: Arc<AtomicBool>,
 	}
 
 	impl KVStore for GatedStore {
@@ -342,10 +344,17 @@ mod tests {
 		) -> impl Future<Output = Result<(), io::Error>> + 'static + Send {
 			let inner = Arc::clone(&self.inner);
 			let write_gate = Arc::clone(&self.write_gate);
+			let fail_writes = Arc::clone(&self.fail_writes);
 			let primary_namespace = primary_namespace.to_string();
 			let secondary_namespace = secondary_namespace.to_string();
 			let key = key.to_string();
 			async move {
+				if fail_writes.load(Ordering::Acquire) {
+					return Err(io::Error::new(
+						io::ErrorKind::Other,
+						"injected write failure",
+					));
+				}
 				let _guard = write_gate.read().await;
 				KVStore::write(&*inner, &primary_namespace, &secondary_namespace, &key, buf).await
 			}
@@ -383,6 +392,7 @@ mod tests {
 		let gated_store = GatedStore {
 			inner: Arc::new(InMemoryStore::new()),
 			write_gate: Arc::new(tokio::sync::RwLock::new(())),
+			fail_writes: Arc::new(AtomicBool::new(false)),
 		};
 		let store: Arc<DynStore> = Arc::new(DynStoreWrapper(gated_store.clone()));
 		let logger = Arc::new(Logger::new_log_facade());
@@ -430,4 +440,50 @@ mod tests {
 		let reloaded = AsyncWalletPersister::initialize(&mut reloaded_persister).await.unwrap();
 		assert_eq!(reloaded.network, Some(Network::Regtest));
 	}
+
+	#[tokio::test]
+	async fn failed_pool_record_prevents_unrelated_flush_of_reveals() {
+		let gated_store = GatedStore {
+			inner: Arc::new(InMemoryStore::new()),
+			write_gate: Arc::new(tokio::sync::RwLock::new(())),
+			fail_writes: Arc::new(AtomicBool::new(false)),
+		};
+		let store: Arc<DynStore> =
+			Arc::new(DynStoreWrapper(gated_store.clone()));
+		let logger = Arc::new(Logger::new_log_facade());
+		let mut persister =
+			KVStoreWalletPersister::new(Arc::clone(&store), Arc::clone(&logger));
+		AsyncWalletPersister::initialize(&mut persister).await.unwrap();
+
+		let mut wallet = BdkWallet::create(EXTERNAL_DESCRIPTOR, INTERNAL_DESCRIPTOR)
+			.network(Network::Regtest)
+			.create_wallet_no_persist()
+			.unwrap();
+		let initial_change_set = wallet.take_staged().unwrap();
+		persister.persist_changeset(initial_change_set).await.unwrap();
+		let baseline = persister.latest_change_set.clone().unwrap();
+
+		let _ = wallet.reveal_next_address(bdk_wallet::KeychainKind::External);
+		let reveal_change_set = wallet.take_staged().unwrap();
+		persister.stage(reveal_change_set);
+
+		gated_store.fail_writes.store(true, Ordering::Release);
+		assert!(
+			persister.persist_address_pool(vec![0]).await.is_err(),
+			"the pool-record write must fail for the regression setup"
+		);
+		gated_store.fail_writes.store(false, Ordering::Release);
+
+		// A sync or transaction operation can persist while a refill retry is pending.
+		// It must not make the reveal durable until the corresponding pool record is covered.
+		let _ = persister.persist_changeset(ChangeSet::default()).await;
+
+		let mut reloaded_persister = KVStoreWalletPersister::new(store, logger);
+		let reloaded =
+			AsyncWalletPersister::initialize(&mut reloaded_persister).await.unwrap();
+		assert_eq!(
+			reloaded.indexer, baseline.indexer,
+			"an unrelated persist made an address reveal durable without pool-record coverage"
+		);
+	}
 }

One verified fix; with it applied the whole wallet:: test module passes:

--- a/src/wallet/persist.rs
+++ b/src/wallet/persist.rs
@@ -46,13 +46,20 @@
 pub(crate) struct KVStoreWalletPersister {
 	latest_change_set: Option<ChangeSet>,
 	pending_change_set: ChangeSet,
+	staged_change_set: ChangeSet,
 	kv_store: Arc<DynStore>,
 	logger: Arc<Logger>,
 }
 
 impl KVStoreWalletPersister {
 	pub(crate) fn new(kv_store: Arc<DynStore>, logger: Arc<Logger>) -> Self {
-		Self { latest_change_set: None, pending_change_set: ChangeSet::default(), kv_store, logger }
+		Self {
+			latest_change_set: None,
+			pending_change_set: ChangeSet::default(),
+			staged_change_set: ChangeSet::default(),
+			kv_store,
+			logger,
+		}
 	}
 
 	async fn initialize_inner(&mut self) -> Result<ChangeSet, std::io::Error> {
@@ -199,22 +206,29 @@
 	pub(super) async fn persist_changeset(
 		&mut self, change_set: ChangeSet,
 	) -> Result<(), std::io::Error> {
-		self.stage(change_set);
-		self.persist_staged().await
+		self.pending_change_set.merge(change_set);
+		self.persist_pending().await
 	}
 
-	/// Merges the given change set into the pending one without persisting it, to be flushed by
-	/// [`Self::persist_staged`] or any later persist call.
+	/// Merges the given change set into the staged one without persisting it, to be flushed by
+	/// [`Self::persist_staged`].
 	///
 	/// Staging is synchronous, letting callers that run as abortable tasks hand a change set
 	/// over without an intervening await point: once staged, an abort leaves it pending for the
-	/// next persist rather than dropping it.
+	/// next [`Self::persist_staged`] rather than dropping it.
 	pub(super) fn stage(&mut self, change_set: ChangeSet) {
-		self.pending_change_set.merge(change_set);
+		self.staged_change_set.merge(change_set);
 	}
 
-	/// Persists the pending change set, retaining it for retry on failure.
+	/// Makes the staged change set eligible for persistence and persists all pending changes,
+	/// retaining them for retry on failure.
 	pub(super) async fn persist_staged(&mut self) -> Result<(), std::io::Error> {
+		let staged_change_set = std::mem::take(&mut self.staged_change_set);
+		self.pending_change_set.merge(staged_change_set);
+		self.persist_pending().await
+	}
+
+	async fn persist_pending(&mut self) -> Result<(), std::io::Error> {
 		Self::persist_inner(
 			&mut self.latest_change_set,
 			&self.kv_store,

This finding was discovered by Project Loupe.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions