Sweeper async change destination source fetching #3734

joostjager · 2025-04-14T11:30:11Z

This PR converts OutputSweeper to take an async ChangeDestinationSource implementation. This allows a (remote) address fetch call to run without blocking chain notifications.

Furthermore the changes demonstrates how LDK could be written in a natively async way, and still allow usage from a sync context using wrappers.

Part of #3540

ldk-reviews-bot · 2025-04-14T11:30:15Z

👋 Thanks for assigning @TheBlueMatt as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

lightning/src/sign/mod.rs

joostjager · 2025-04-14T11:32:13Z

lightning/src/util/sweep.rs

 		}
-
-		Ok(())
+		self.persist_state(&*state_lock).map_err(|e| {


No more sweeping in this method, all moved to a timer.

joostjager · 2025-04-14T11:32:31Z

lightning/src/util/sweep.rs

-		if let Some(spending_tx) = spending_tx_opt {
-			self.broadcaster.broadcast_transactions(&[&spending_tx]);
-		}
+		let _ = self.persist_state(&*state_lock).map_err(|e| {


No more sweeping in this event handler.

lightning/src/util/sweep.rs

lightning-background-processor/src/lib.rs

joostjager · 2025-04-14T19:11:20Z

lightning/src/util/sweep.rs

-		if respend_descriptors.is_empty() {
-			// Nothing to do.
-			return None;
+			let change_destination_script = change_destination_script_result?;


Todo: address risk of getting a tx with a new address every block.

Todo: investigate what BDK does here?

Traced through BDK a bit. It seems that there is only inflation if we actually use the address in a tx. It won't blindly regenerate addresses when called. But will double check this.

It seems that there is only inflation if we actually use the address in a tx. It won't blindly regenerate addresses when called. But will double check this.

This mostly depends on the API used.

lightning-background-processor/src/lib.rs

lightning/src/util/sweep.rs

lightning/src/lib.rs

lightning/src/util/sweep.rs

joostjager · 2025-04-16T16:33:56Z

lightning/src/util/sweep.rs

+	sweeper: OutputSweeper<B, D, E, F, K, L, O>,
+}
+
+impl<B: Deref, D: Deref, E: Deref, F: Deref, K: Deref, L: Deref, O: Deref>


What might be good about this wrapper is that it eliminates the possibility of someone implementing async logic in combination with future poll/ready checking. This wrapper only accepts a sync trait.

lightning/src/util/sweep.rs

codecov · 2025-04-21T09:07:47Z

Codecov Report

Attention: Patch coverage is 81.65939% with 42 lines in your changes missing coverage. Please review.

Project coverage is 90.60%. Comparing base (f507778) to head (129d0f1).
Report is 62 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/util/sweep.rs	77.16%	25 Missing and 12 partials ⚠️
lightning/src/util/async_poll.rs	57.14%	3 Missing ⚠️
lightning-background-processor/src/lib.rs	96.22%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3734      +/-   ##
==========================================
+ Coverage   89.13%   90.60%   +1.46%     
==========================================
  Files         157      157              
  Lines      123851   134752   +10901     
  Branches   123851   134752   +10901     
==========================================
+ Hits       110395   122092   +11697     
+ Misses      10779    10016     -763     
+ Partials     2677     2644      -33

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

joostjager · 2025-04-24T14:08:44Z

Rebased after merge of #3509

Copilot

Pull Request Overview

This PR refactors the OutputSweeper logic to support asynchronous change destination source fetching while still enabling synchronous usage via a new wrapper. Key changes include:

Converting OutputSweeper to use an async implementation for fetching change addresses.
Introducing a RuntimeSweeperState to support concurrent sweeper operations.
Adding an OutputSweeperSync wrapper to allow synchronous usage of the async API.

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
lightning/src/util/sweep.rs	Refactored OutputSweeper APIs to support async operations and state management.
lightning/src/util/async_poll.rs	Updated dummy_waker implementation to work with a complete Waker vtable.
lightning/src/sign/mod.rs	Introduced async alias and a synchronous wrapper (ChangeDestinationSourceSyncWrapper) for change destination fetching.
lightning/src/lib.rs	Removed the forbid(unsafe_code) attribute.
lightning-background-processor/src/lib.rs	Integrated the new sweeper APIs into background processing flows.

Comments suppressed due to low confidence (1)

lightning/src/lib.rs:32

The removal of the 'forbid(unsafe_code)' attribute now permits unsafe code in production. If this removal was not intentional, consider re-enabling it or ensuring that any introduced unsafe code is thoroughly reviewed.

#![cfg_attr(not(any(test, fuzzing, feature = "_test_utils")), forbid(unsafe_code))]

Copilot · 2025-04-25T06:22:46Z

lightning/src/util/sweep.rs

+				// In a sync context, we can't wait for the future to complete.
+				panic!("task not ready");


[nitpick] Using a panic in the synchronous wrapper when the future is not immediately ready may lead to abrupt termination. Consider returning an error or implementing a blocking wait so that the caller can handle the situation gracefully.

Suggested change

// In a sync context, we can't wait for the future to complete.

panic!("task not ready");

// In a sync context, block until the future is ready.

return futures::executor::block_on(fut);

I think we want to be not tolerant in this case, because everything lives in the wrapper.

Hmm, I'm a bit on the fence about this. But if we indeed want to panic here, using the unreachable! macro would be the most idiomatic way to do it.

Made it unreachable!

We absolutely don't want to take a dependency to seek to run a future in a fresh executor in cases where its unreachable :)

AI is going to AI

ldk-reviews-bot · 2025-04-26T00:00:49Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-04-28T00:01:22Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Pretty much LGTM, mod some comments.

I think the main think I'd prefer to be changed is the (rather ugly) RuntimeSweperState wrapping.

lightning-background-processor/src/lib.rs

tnull · 2025-04-29T12:43:10Z

lightning-background-processor/src/lib.rs

 ) -> Result<(), lightning::io::Error>
 where
 	UL::Target: 'static + UtxoLookup,
-	CF::Target: 'static + chain::Filter,
+	CF::Target: 'static + chain::Filter + Sync + Send,


Still not quite sure why/whether these bounds are necessary now?

Tried to remove them, but that gives me a compiler error

<CF as Deref>::Target cannot be shared between threads safely
the trait std::marker::Sync is not implemented for <CF as Deref>::Target

On the OS: 'static + Deref<Target = OutputSweeper<T, D, F, CF, K, L, O>> bound.

tnull · 2025-04-29T12:43:37Z

lightning-background-processor/src/lib.rs

@@ -1269,7 +1322,7 @@ mod tests {
 				Arc<test_utils::TestBroadcaster>,
 				Arc<TestWallet>,
 				Arc<test_utils::TestFeeEstimator>,
-				Arc<dyn Filter + Sync + Send>,
+				Arc<test_utils::TestChainSource>,


Why do we need this change?

This was so much fighting and trying. If I revert I am getting:

type mismatch resolving <Arc<OutputSweeper<Arc, Arc, Arc, Arc<dyn Filter + Send + Sync>, Arc<...>, ..., ...>> as Deref>::Target == OutputSweeper<Arc, Arc, Arc, Arc, , Arc<...>, ...>expected structOutputSweeper<, _, _, Arc, _, _, >found structOutputSweeper<, _, _, Arc<dyn lightning::chain::Filter + Send + std::marker::Sync>, Arc, _, Arc> TestChainSourceimplementsFilterso you could change the expected type toBox``

lightning-background-processor/src/lib.rs

tnull · 2025-04-29T12:51:54Z

lightning/src/util/sweep.rs

@@ -755,6 +782,11 @@ where
 	}
 }

+struct RuntimeSweeperState {


Tbh. I'm not quite sure why sweep_pending can't just be an AtomicBool that lives in OutputSweeper directly? That would also allow us to check whether we're pending without acquiring (and potentially blocking on) the state mutex?

tnull · 2025-04-29T12:57:14Z

lightning/src/sign/mod.rs

@@ -975,17 +978,56 @@ pub trait SignerProvider {
 	fn get_shutdown_scriptpubkey(&self) -> Result<ShutdownScript, ()>;
 }

+/// A type alias for a future that returns a result of type T.
+pub type AsyncResult<'a, T> = Pin<Box<dyn Future<Output = Result<T, ()>> + 'a + Send>>;


This seems a more general type related to future-polling. I wonder if it should rather live in utils/wakers.rs or async_poll.rs?

Moved to async_poll.rs

tnull · 2025-04-29T13:06:43Z

lightning/src/util/sweep.rs

+				// In a sync context, we can't wait for the future to complete.
+				panic!("task not ready");


Hmm, I'm a bit on the fence about this. But if we indeed want to panic here, using the unreachable! macro would be the most idiomatic way to do it.

tnull · 2025-04-29T13:12:36Z

lightning/src/util/sweep.rs

+	pub fn sweeper_async(
+		&self,
+	) -> Arc<OutputSweeper<B, Arc<ChangeDestinationSourceSyncWrapper<D>>, E, F, K, L, O>> {
+		self.sweeper.clone()


If this is only necessary for tests, we could just also feature-gate the Arc-wrapping in on _test_utils, no? This way we could use the approach you proposed in test, while not actually doing it in production?

To prepare for asynchronous processing of the sweep, we need to decouple the spending from the chain notifications. These notifications run in a sync context and wouldn't allow calls into an async trait. Instead we now periodically call into the sweeper, to open up the possibility to do so from an async context if desired.

joostjager · 2025-05-01T10:32:43Z

~~Futures flag removed~~

Changed my mind. Will do in a follow up.

ldk-reviews-bot · 2025-05-03T12:33:22Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-05-05T12:33:45Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-05-07T12:34:08Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-05-10T00:00:41Z

🔔 4th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-05-12T00:01:12Z

🔔 5th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Excuse the delay here!

Mostly looks good from my side I think, just a few minor comments/nits. Will to another final thorough pass after.

lightning/src/util/sweep.rs

tnull · 2025-05-12T13:49:35Z

lightning/src/util/sweep.rs


+use crate::sync::Arc;


nit: Let's move this to the other crate imports

It's cleaner, but also I have to say I never look at these imports. But may be different for others. Moved.

tnull · 2025-05-12T13:52:36Z

lightning/src/util/sweep.rs

@@ -567,16 +623,15 @@ where
 	}

 	fn spend_outputs(
-		&self, sweeper_state: &SweeperState, descriptors: Vec<&SpendableOutputDescriptor>,
+		&self, sweeper_state: &SweeperState, descriptors: &Vec<&SpendableOutputDescriptor>,


nit: Mhh, &Vec<&..> looks funny. I guess the signature from spend_spendable_outputs would be preferable: &[&SpendableOutputDescriptor].

Out of curiosity, what is funny about it? Or how is &[&..] less funny? Fixed.

Usually we try to create the least-strict API if there is no reason to. In this case, the prior API would enforce a reference to an allocated Vec, while, if we just require the slice in the API, we might (easier) be able to drop the allocation if it's not necessary.

tnull

LGTM, mod one question and a few final nits.

lightning/src/util/sweep.rs

tnull · 2025-05-13T08:20:27Z

lightning/src/util/sweep.rs

+				},
+				Err(e) => {
+					log_error!(self.logger, "Error spending outputs: {:?}", e);
+					return Ok(());


Why are we ignoring the error here instead of propagating it up? (If we'd want to ignore it for some reason, can we just have spend_outputs not return a Result and move this match / logging into it?)

I think it was pre-existing to not do anything with that error other than log:

rust-lightning/lightning/src/util/sweep.rs

Line 507 in 5316257

Err(e) => {

I am not sure if the caller can do something more with the error. I do see that there non-happy flow error cases in spend_spendable_outputs, so might be better to at least give the users the choice. Added map_err.

lightning/src/util/sweep.rs

tnull

LGTM, feel free to squash.

One outstanding nit, non-blocking though. If you want, feel free to address while squashing also.

lightning/src/util/sweep.rs

synchronous wrappers for usage in a sync context.

joostjager commented Apr 14, 2025

View reviewed changes

lightning/src/sign/mod.rs Outdated Show resolved Hide resolved

joostjager commented Apr 14, 2025

View reviewed changes

lightning/src/util/sweep.rs Outdated Show resolved Hide resolved

joostjager commented Apr 14, 2025

View reviewed changes

lightning/src/util/sweep.rs Outdated Show resolved Hide resolved

joostjager commented Apr 14, 2025

View reviewed changes

lightning-background-processor/src/lib.rs Outdated Show resolved Hide resolved

joostjager commented Apr 14, 2025

View reviewed changes

lightning-background-processor/src/lib.rs Outdated Show resolved Hide resolved

joostjager commented Apr 14, 2025

View reviewed changes

joostjager force-pushed the async-sweep branch 2 times, most recently from c3420ab to d6051d9 Compare April 16, 2025 09:28

tnull reviewed Apr 16, 2025

View reviewed changes

joostjager commented Apr 16, 2025

View reviewed changes

lightning/src/util/sweep.rs Outdated Show resolved Hide resolved

joostjager force-pushed the async-sweep branch 2 times, most recently from 90d7104 to 370d677 Compare April 16, 2025 16:32

joostjager commented Apr 16, 2025

View reviewed changes

lightning/src/util/sweep.rs Outdated Show resolved Hide resolved

joostjager commented Apr 16, 2025

View reviewed changes

lightning/src/util/sweep.rs Outdated Show resolved Hide resolved

joostjager commented Apr 16, 2025

View reviewed changes

lightning/src/util/sweep.rs Outdated Show resolved Hide resolved

joostjager force-pushed the async-sweep branch 4 times, most recently from a9812ea to df47e8d Compare April 18, 2025 10:23

joostjager force-pushed the async-sweep branch 6 times, most recently from f3e911e to 6cd735c Compare April 21, 2025 11:35

joostjager mentioned this pull request Apr 24, 2025

Make BumpTransactionEventHandler async-optional #3540

Open

joostjager requested a review from Copilot April 25, 2025 06:22

Copilot AI reviewed Apr 25, 2025

View reviewed changes

tnull reviewed Apr 29, 2025

View reviewed changes

joostjager force-pushed the async-sweep branch from 0fe2fac to 87e4bc6 Compare April 29, 2025 13:55

Prepare sweeper filter fn for reuse

b5ec74a

joostjager force-pushed the async-sweep branch from 17a5449 to 493b686 Compare May 1, 2025 10:22

joostjager force-pushed the async-sweep branch 2 times, most recently from d317ae3 to 493b686 Compare May 1, 2025 10:48

joostjager requested a review from tnull May 1, 2025 12:32

tnull reviewed May 12, 2025

View reviewed changes

joostjager force-pushed the async-sweep branch from 493b686 to d1d63fc Compare May 12, 2025 14:31

joostjager requested a review from tnull May 12, 2025 14:32

tnull reviewed May 13, 2025

View reviewed changes

joostjager requested a review from tnull May 13, 2025 11:00

tnull reviewed May 13, 2025

View reviewed changes

lightning/src/util/sweep.rs Outdated Show resolved Hide resolved

Convert sweeper to use an async ChangeDestinationSource and provide

129d0f1

synchronous wrappers for usage in a sync context.

joostjager force-pushed the async-sweep branch from 2bf309d to 129d0f1 Compare May 13, 2025 11:28

tnull approved these changes May 13, 2025

View reviewed changes

joostjager requested a review from TheBlueMatt May 13, 2025 11:43

		// In a sync context, we can't wait for the future to complete.
		panic!("task not ready");

Sweeper async change destination source fetching #3734

Are you sure you want to change the base?

Sweeper async change destination source fetching #3734

Conversation

joostjager commented Apr 14, 2025 • edited Loading

ldk-reviews-bot commented Apr 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joostjager Apr 16, 2025 • edited Loading

Choose a reason for hiding this comment

codecov bot commented Apr 21, 2025 • edited Loading

Codecov Report

joostjager commented Apr 24, 2025

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Copilot AI Apr 25, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ldk-reviews-bot commented Apr 26, 2025

ldk-reviews-bot commented Apr 28, 2025

tnull left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joostjager commented May 1, 2025 • edited Loading

ldk-reviews-bot commented May 3, 2025

ldk-reviews-bot commented May 5, 2025

ldk-reviews-bot commented May 7, 2025

ldk-reviews-bot commented May 10, 2025

ldk-reviews-bot commented May 12, 2025

tnull left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tnull left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tnull left a comment

Choose a reason for hiding this comment

joostjager commented Apr 14, 2025 •

edited

Loading

ldk-reviews-bot commented Apr 14, 2025 •

edited

Loading

joostjager Apr 16, 2025 •

edited

Loading

codecov bot commented Apr 21, 2025 •

edited

Loading

joostjager commented May 1, 2025 •

edited

Loading

tnull left a comment •

edited

Loading