Hold times for successful payments #3801

joostjager · 2025-05-26T11:55:36Z

Apply the hold time reporting mechanism as implemented in #2256 to the success case. Spec in lightning/bolts#1044

ldk-reviews-bot · 2025-05-26T11:55:39Z

👋 Thanks for assigning @tnull 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.

codecov · 2025-05-27T12:02:51Z

Codecov Report

Attention: Patch coverage is 90.03378% with 177 lines in your changes missing coverage. Please review.

Project coverage is 89.13%. Comparing base (9863f29) to head (1994550).
Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/ln/channelmanager.rs	90.43%	86 Missing and 3 partials ⚠️
lightning/src/ln/channel.rs	86.69%	73 Missing and 14 partials ⚠️
lightning/src/ln/payment_tests.rs	97.43%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3801      +/-   ##
==========================================
+ Coverage   88.82%   89.13%   +0.31%     
==========================================
  Files         166      166              
  Lines      119487   123678    +4191     
  Branches   119487   123678    +4191     
==========================================
+ Hits       106136   110246    +4110     
- Misses      11021    11104      +83     
+ Partials     2330     2328       -2

☔ 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.

ldk-reviews-bot · 2025-07-16T09:53:47Z

🔔 1st Reminder

Hey @valentinewallace @carlaKC! 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.

TheBlueMatt

Not super happy with how much this ended up touching but the hold times parts LGTM. The rustfmt part needs rebase, though, and I'm kinda skeptical of starting a PR with 1423 insertions(+), 570 deletions(-) when the rest of the PR is only 625 insertions(+), 196 deletions(-), seems like the rustfmt part should be separated out if you want to do it first.

TheBlueMatt · 2025-07-16T20:15:58Z

lightning/src/ln/channelmanager.rs

+				let attribution_data = process_fulfill_attribution_data(
+					attribution_data.as_ref(),
+					&htlc.prev_hop.incoming_packet_shared_secret,
+					0,


Ha, saved by the rounding :). Without the rounding this will clearly give away that we're a phantom node. As-is it instead can also be a peer that is within 100ms of us :)

I am so happy 😅

TheBlueMatt · 2025-07-16T20:20:20Z

lightning/src/events/mod.rs

@@ -1102,6 +1102,8 @@ pub enum Event {
 		///
 		/// May contain a closed channel if the HTLC sent along the path was fulfilled on chain.
 		path: Path,
+		/// The hold times as reported by each hop.


If we're going to expose this we really need to document in more detail what the values represent (100ms chunks where previous hops should encompass later hops' hold times) and how to use it (for deciding which node is slow in scoring, noting that our current scorer does not do this). Also, we should probably include it in PaymentPathFailed too?

Docs added and hold_times exposed outside of tests in PaymentPathFailed.

tnull

Needs a rebase now that #3937 landed.

Preparation for reuse of the logic.

Need to store AttributionData as part of the inbound HTLC removal reason so that it can be used in the upstream UpdateFulfillHTLC message.

Necessary to preserve attribution data when the HTLC is in the holding cell.

Adds hold time reporting for the final and intermediate nodes.

AttributionData is needed as part of the outbound HTLC outcome when revoke_and_ack has happened and the AttributionData is decoded to get the hold times for inclusion in the PaymentPathSuccessful event.

Prepare for inspecting hold times in PaymentPathSuccessful.

joostjager · 2025-07-17T11:14:38Z

Comments addressed diff

Hold times are surfaced via the PaymentPathSuccessful event.

Now that fulfill hold times are surfaced in the event always, this commit follow ups with the failure hold times.

TheBlueMatt

LGTM. A few nits but I'm happy to address them post-merge, there's probably a few other things I want to tweak post-merge (at least making the fulfill message passed in owned instead of reference to remove some clones).

TheBlueMatt · 2025-07-18T14:22:06Z

lightning/src/ln/channel.rs

@@ -13526,7 +13573,7 @@ where
 	}
 }

-fn duration_since_epoch() -> Option<Duration> {
+pub(crate) fn duration_since_epoch() -> Option<Duration> {


Its a bit confusing to use this in channelmanager.rs - we already have a ChannelManager::duration_since_epoch that uses the block time if we're built without time access, but also every call to hold_time takes the result of this call as the second argument, so it seems like this should just be inlined into hold_time (dunno if you'd want to rename it after doing so).

TheBlueMatt · 2025-07-18T14:37:40Z

lightning/src/ln/channel.rs

 			(58, self.interactive_tx_signing_session, option), // Added in 0.2
 			(59, self.funding.minimum_depth_override, option), // Added in 0.2
 			(60, self.context.historical_scids, optional_vec), // Added in 0.2
+			(61, fulfill_attribution_data, optional_vec),


Needs an Added in tag.

TheBlueMatt · 2025-07-18T14:37:52Z

lightning/src/ln/channel.rs

 			(58, interactive_tx_signing_session, option), // Added in 0.2
 			(59, minimum_depth_override, option), // Added in 0.2
 			(60, historical_scids, optional_vec), // Added in 0.2
+			(61, fulfill_attribution_data, optional_vec),


Needs an Added in tag.

TheBlueMatt · 2025-07-18T14:37:56Z

lightning/src/ln/channel.rs

+			(55, removed_htlc_attribution_data, optional_vec),
+			(57, holding_cell_attribution_data, optional_vec),


These could get the added-in tag that exists on the write side too, while we're here.

valentinewallace

Mainly reviewed the diffs since my last LGTM. Nothing blocking 👍

valentinewallace · 2025-07-17T20:59:29Z

lightning/src/ln/chanmon_update_fail_tests.rs

@@ -2901,6 +2901,8 @@ fn do_test_reconnect_dup_htlc_claims(htlc_status: HTLCStatusAtDupClaim, second_f
 		);
 		check_added_monitors!(nodes[2], 1);
 		get_htlc_update_msgs!(nodes[2], node_b_id);
+	// Note that we don't populate fulfill_msg.attribution_data here, which will lead to hold times being


I think it's putting the comment on the else, we could move it up a line?

valentinewallace · 2025-07-18T13:59:08Z

lightning/src/events/mod.rs

+		/// milliseconds. So a hop reporting 2 is a hold time that corresponds to roughly 200 milliseconds. As earlier
+		/// hops hold on to an HTLC for longer, the hold times in the list are expected to decrease. When our peer
+		/// didn't provide attribution data, the list is empty. The same applies to HTLCs that were resolved onchain.
+		/// Because of unavailability of hold times, the list may be shorter than the number of hops in the path.


I think it might be useful to clarify that the hold time at idx 0 corresponds to the hop at path.hops[0], etc

joostjager changed the title ~~Successful payment hold times~~ Hold times for successful payments May 26, 2025

joostjager force-pushed the fulfill-hold-times branch 7 times, most recently from badc803 to e913312 Compare May 27, 2025 09:52

joostjager mentioned this pull request May 27, 2025

Simplify UpdateFulfillFetch::NewClaim #3803

Merged

joostjager force-pushed the fulfill-hold-times branch from e913312 to 69a99b4 Compare May 27, 2025 11:53

joostjager force-pushed the fulfill-hold-times branch from 69a99b4 to 1f56e04 Compare May 27, 2025 12:24

joostjager mentioned this pull request May 27, 2025

Success hold times lightning/bolts#1261

Closed

joostjager mentioned this pull request Jun 5, 2025

Attribution data (feature 36/37) lightning/bolts#1044

Open

joostjager force-pushed the fulfill-hold-times branch 8 times, most recently from bace463 to 1c64a50 Compare June 26, 2025 13:52

joostjager marked this pull request as ready for review June 26, 2025 14:16

joostjager marked this pull request as draft June 26, 2025 14:17

joostjager added this to Weekly Goals Jun 26, 2025

joostjager self-assigned this Jun 26, 2025

joostjager force-pushed the fulfill-hold-times branch 2 times, most recently from 233cbfc to f5668f5 Compare June 30, 2025 09:36

TheBlueMatt self-requested a review July 16, 2025 16:20

TheBlueMatt reviewed Jul 16, 2025

View reviewed changes

joostjager force-pushed the fulfill-hold-times branch from 741ee1e to bca896a Compare July 17, 2025 08:25

joostjager mentioned this pull request Jul 17, 2025

Fulfill hold times rustfmt #3937

Merged

tnull reviewed Jul 17, 2025

View reviewed changes

joostjager added 9 commits July 17, 2025 12:59

Small refactors in onion_utils

47ce774

Extract hold time calculation

5eecba3

Preparation for reuse of the logic.

Add AttributionData to UpdateFulfillHTLC message

5938a99

Add AttributionData to InboundHTLCRemovalReason::Fulfill

f212530

Need to store AttributionData as part of the inbound HTLC removal reason so that it can be used in the upstream UpdateFulfillHTLC message.

Add AttributionData to HTLCUpdateAwaitingACK::ClaimHTLC

ba7deab

Necessary to preserve attribution data when the HTLC is in the holding cell.

Hold time reporting

72414f2

Adds hold time reporting for the final and intermediate nodes.

Remove code duplication in FundedChannel::read

348ba4b

Add AttributionData to OutboundHTLCOutcome::Success

418b353

AttributionData is needed as part of the outbound HTLC outcome when revoke_and_ack has happened and the AttributionData is decoded to get the hold times for inclusion in the PaymentPathSuccessful event.

Return path events from expect_payment_sent

bed274f

Prepare for inspecting hold times in PaymentPathSuccessful.

joostjager force-pushed the fulfill-hold-times branch 2 times, most recently from a6c8603 to 4831900 Compare July 17, 2025 11:14

joostjager added 2 commits July 17, 2025 13:15

Decode hold times as a sender

4674ddd

Hold times are surfaced via the PaymentPathSuccessful event.

Surface failure hold times

ba52885

Now that fulfill hold times are surfaced in the event always, this commit follow ups with the failure hold times.

joostjager force-pushed the fulfill-hold-times branch from 4831900 to ba52885 Compare July 17, 2025 11:16

joostjager added the weekly goal Someone wants to land this this week label Jul 17, 2025

joostjager requested review from TheBlueMatt and removed request for carlaKC July 17, 2025 11:50

TheBlueMatt requested a review from tnull July 18, 2025 13:25

TheBlueMatt approved these changes Jul 18, 2025

View reviewed changes

valentinewallace approved these changes Jul 18, 2025

View reviewed changes

TheBlueMatt merged commit 9367528 into lightningdevkit:main Jul 18, 2025
27 of 28 checks passed

github-project-automation bot moved this to Done in Weekly Goals Jul 18, 2025

TheBlueMatt mentioned this pull request Jul 18, 2025

Misc Followups #3942

Merged

		(55, removed_htlc_attribution_data, optional_vec),
		(57, holding_cell_attribution_data, optional_vec),

Hold times for successful payments #3801

Hold times for successful payments #3801

Conversation

joostjager commented May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ldk-reviews-bot commented Jul 16, 2025

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

joostjager commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

valentinewallace left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

joostjager commented May 26, 2025 •

edited

Loading

ldk-reviews-bot commented May 26, 2025 •

edited

Loading

codecov bot commented May 27, 2025 •

edited

Loading

joostjager commented Jul 17, 2025 •

edited

Loading