(3/3) Add Failure Reason to HTLCHandlingFailed #3700

carlaKC · 2025-04-02T20:35:45Z

This PR surfaces a failure reason in HTLCHandlingFailed events. Opening up early to add some context to the prefactor PR #3601.

The heart of the PR is in d35d35f, and it could probably be reduced to just this commit. I've made some quite opinionated renaming / deprecation decisions in the other commits which aren't required for this change, but I think make for a more readable API overall - happy to drop them if it ain't broke, don't fix it applies.

Fixes: #3561
Fixes: #3541

ldk-reviews-bot · 2025-04-02T20:35:48Z

👋 Thanks for assigning @joostjager 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/events/mod.rs

codecov · 2025-04-11T21:52:28Z

Codecov Report

Attention: Patch coverage is 86.55462% with 32 lines in your changes missing coverage. Please review.

Project coverage is 89.60%. Comparing base (0ee1def) to head (5badb5e).
Report is 23 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/events/mod.rs	10.71%	25 Missing ⚠️
lightning/src/ln/channelmanager.rs	90.24%	4 Missing ⚠️
lightning-liquidity/src/lsps2/service.rs	0.00%	2 Missing ⚠️
lightning/src/ln/monitor_tests.rs	83.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3700      +/-   ##
==========================================
+ Coverage   89.13%   89.60%   +0.46%     
==========================================
  Files         156      158       +2     
  Lines      123600   127663    +4063     
  Branches   123600   127663    +4063     
==========================================
+ Hits       110176   114390    +4214     
+ Misses      10757    10640     -117     
+ Partials     2667     2633      -34

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

valentinewallace · 2025-04-16T14:32:19Z

Needs rebase 🥳

lightning/src/events/mod.rs

lightning/src/ln/onion_utils.rs

ldk-reviews-bot · 2025-04-21T00:00:38Z

🔔 1st Reminder

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

carlaKC · 2025-04-21T13:40:48Z

Pushed suggested comment/style changes + rename of HTLCFailReasonRepr to go with outer struct rename.

Happy to drop the last two commits as discussed here if the renames aren't strong enough to justify the change!

valentinewallace · 2025-04-22T22:20:22Z

lightning/src/events/mod.rs

+	Downstream,
+	/// The HTLC was failed locally by our node.
+	Local {
+		/// The reason that our node chose to fail the HTLC.
+		reason: LocalHTLCFailureReason,
+	},


I'm wondering if it would be nicer to avoid this outer enum and just document on the field "Will be None if the HTLC failed downstream or this event was created prior to 0.2." Seems simpler, loses a bit of information for a period of time though.

I think that it would be nice to surface hold_time along with Downstream in future (nice thing to put on a dashboard IMO) so tend towards keeping the enum for the sake of being able to easily add that.

Opinion not very strongly held though.

Oh, I didn't realize that was a potential goal but that makes sense! We may want to document this on the attributable failures issue, if there is one.

@joostjager do we have a tracking issue for follow-ups for attributable failures? IIRC we still need to support the hold_times part of the spec?

Noted in #3753.

lightning/src/events/mod.rs

valentinewallace · 2025-04-22T23:14:37Z

lightning/src/events/mod.rs

@@ -480,12 +480,16 @@ pub enum HTLCHandlingType {
 		channel_id: ChannelId,
 	},
 	/// Scenario where we are unsure of the next node to forward the HTLC to.
+	///
+	/// Deprecated: will only be used in versions before LDK v0.2.0.


I think you can use the official deprecated attribute on this: https://doc.rust-lang.org/reference/attributes/diagnostics.html#r-attributes.diagnostics.deprecated

TIL this exists!

Struggling to #[allow(deprecated)] for the impl_writeable_tlv_based_enum_upgradable invocation to silence the cargo warning though..

carlaKC · 2025-04-23T17:36:35Z

Removed the last 2 rename commits (I don't think they're that much of an improvement) + fixed up comment.

Couldn't find a way to use deprecation attribute without making changes to the serialization macro so left it out.

lightning/src/events/mod.rs

valentinewallace

Nothing blocking if we want to Just Land and save the ser tweak for follow-up

lightning/src/events/mod.rs

valentinewallace · 2025-04-25T23:35:20Z

lightning/src/events/mod.rs

+				let downgradable_type = match (failure_type, failure_reason) {
+					(HTLCHandlingFailureType::InvalidForward { requested_forward_scid },
+						Some(HTLCHandlingFailureReason::Local {
+							reason: LocalHTLCFailureReason::UnknownNextPeer
+						}))
+						=> HTLCHandlingFailureType::UnknownNextHop {
+							requested_forward_scid: *requested_forward_scid,
+						},
+					_ => failure_type.clone()
+				};


Apologies if I signed off on this previously, but I think it would make more sense to always write the non-deprecated type and then include a release note that downgrades will result in reading the deprecated type as ::InvalidForward, since it'll save some complexity here and keep the door open for us to delete the variant in the future.

Having done it this way, I think it looks much better 👍 doesn't seem like that much of a loss to have less information on downgrade in comparison

Are there no functional consequences after the downgrade for this loss of information?

afaik no, HTLCHandlingFailed is a "read-only" event - it doesn't require any action from an end user.

So worst case it's a few wrong entries in a tracking dashboard, but I think the release note is sufficient to highlight that (so that downgraders are aware).

lightning/src/events/mod.rs

joostjager

LGTM

joostjager · 2025-04-28T14:55:11Z

lightning/src/events/mod.rs

+}
+
+impl_writeable_tlv_based_enum!(HTLCHandlingFailureReason,
+	(1, Downstream) => {},


Shouldn't those be even because it is a completely new type? I somehow feel that we've been here before, but maybe it was another PR. Enum always odd regardless, was that the outcome? Doesn't seem to matter all that much though.

Odd/even enum variant types only have different behavior in impl_writeable_tlv_based_enum_upgradable :) We could use that macro instead if we think we'll want to add more odd variants in the future, though I don't feel strongly about that because that doesn't seem likely IMO.

lightning/src/events/mod.rs

pending_changelog/3700-reason-in-handling-failed.txt

valentinewallace · 2025-04-28T19:36:57Z

LGTM, feel free to squash IMO

HTLCDestination currently contains a combination of information about the type of HTLC we handled to fail (a payment, a forward etc) and error information for a select set of cases (unknown next peer, for example). In preparation for a refactor that will split the failure reason out into its own enum, this commit renames HTLCDestination to HTLCHandlingFailureType.

Rename variant to be more specific to the current context - a FailedPayment could be a payment that we failed to dispatch or one that we rejected on receive.

Standardize naming within the HTLCHandlingFailureType struct to present more consistent API terminology.

This variant of HTLCHandlingFailureType contains information about the failure cause along with its type - as an UnknownNextPeer is just an InvalidForward that has the failure type UnknownNextPeer. Use of the variant is deprecated, and any old events are upgraded to the new representation. As a result, downgrading nodes will get an InvalidForward where they otherwise would have had an UnknownNextPeer. The alternative would be to continue to write the old representation to prevent this information loss on downgrade, but it comes at the cost of not being able to remove the UnknownNextPeer variant in future (and some extra handling code). The deprecated attribute is not used because it cannot be silenced in impl_writeable_tlv_based_enum, which uses UnknownNextPeer to remain downgradable.

carlaKC · 2025-04-28T19:46:37Z

Squashed + fixed up some commit messages that still said HtlcHandlingType instead of HTLCHandlingFailureType, no code diff.

carlaKC · 2025-04-29T13:03:30Z

Taking a look at fuzzing failure!

carlaKC · 2025-04-29T14:39:54Z

Pretty sure that fuzzing failure is unrelated because:

Input fails on main as well as feature branch
Channel monitor isn't touched in this PR + error looks totally unrelated

Details of failure in #3756, would appreciate a second set of eyes to confirm 🙏

valentinewallace · 2025-04-29T18:19:42Z

Landing because per #3756 (comment) the fuzz failure is unrelated

carlaKC mentioned this pull request Apr 2, 2025

(2/3) Add Enum for HTLCHandlingFailed Reasons #3601

Merged

carlaKC changed the title ~~Add Failure Reason to HTLCHandlingFailed~~ (3/3) Add Failure Reason to HTLCHandlingFailed Apr 2, 2025

carlaKC force-pushed the 3541-api-changes branch 2 times, most recently from d049301 to 6138779 Compare April 4, 2025 20:36

valentinewallace reviewed Apr 4, 2025

View reviewed changes

lightning/src/events/mod.rs Show resolved Hide resolved

valentinewallace mentioned this pull request Apr 10, 2025

WIP: Trampoline forwarding #3711

Open

4 tasks

carlaKC force-pushed the 3541-api-changes branch from 6138779 to 2d39ef8 Compare April 11, 2025 21:43

carlaKC force-pushed the 3541-api-changes branch from 2d39ef8 to b48c6ce Compare April 15, 2025 18:51

carlaKC force-pushed the 3541-api-changes branch from b48c6ce to cda8de5 Compare April 17, 2025 18:07

carlaKC marked this pull request as ready for review April 17, 2025 19:24

ldk-reviews-bot requested a review from wpaulino April 17, 2025 19:24

carlaKC requested a review from valentinewallace April 17, 2025 19:25

joostjager requested review from joostjager and removed request for wpaulino April 17, 2025 19:53

joostjager reviewed Apr 18, 2025

View reviewed changes

carlaKC force-pushed the 3541-api-changes branch from cda8de5 to 6638118 Compare April 21, 2025 13:37

valentinewallace reviewed Apr 22, 2025

View reviewed changes

carlaKC force-pushed the 3541-api-changes branch from 6638118 to c78304f Compare April 23, 2025 17:35

carlaKC requested a review from joostjager April 24, 2025 12:35

valentinewallace reviewed Apr 25, 2025

View reviewed changes

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

carlaKC force-pushed the 3541-api-changes branch from c78304f to 51eb743 Compare April 25, 2025 20:46

valentinewallace previously approved these changes Apr 25, 2025

View reviewed changes

valentinewallace reviewed Apr 25, 2025

View reviewed changes

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

carlaKC dismissed valentinewallace’s stale review via 322fa64 April 26, 2025 13:45

carlaKC added a commit to carlaKC/rust-lightning that referenced this pull request Apr 26, 2025

pending_changelog: add notes for lightningdevkit#3700

5badb5e

carlaKC added a commit to carlaKC/rust-lightning that referenced this pull request Apr 26, 2025

pending_changelog: add notes for lightningdevkit#3700

a195aab

carlaKC requested a review from valentinewallace April 28, 2025 13:04

joostjager previously approved these changes Apr 28, 2025

View reviewed changes

valentinewallace reviewed Apr 28, 2025

View reviewed changes

pending_changelog/3700-reason-in-handling-failed.txt Show resolved Hide resolved

carlaKC dismissed joostjager’s stale review via ed5210d April 28, 2025 19:33

carlaKC force-pushed the 3541-api-changes branch from 5badb5e to ed5210d Compare April 28, 2025 19:33

carlaKC added 6 commits April 28, 2025 15:43

ln+events+liquidity/refactor: rename FailedPayment to Receive

d98a254

Rename variant to be more specific to the current context - a FailedPayment could be a payment that we failed to dispatch or one that we rejected on receive.

ln+events+liquidity/refactor: NextHopChannel renamed Forward

99bcd69

Standardize naming within the HTLCHandlingFailureType struct to present more consistent API terminology.

ln+events: add htlc failure reason to HTLCHandlingFailed

d1289ce

pending_changelog: release notes for HTLCHandlingFailure changes

af301f4

carlaKC force-pushed the 3541-api-changes branch from ed5210d to af301f4 Compare April 28, 2025 19:45

valentinewallace approved these changes Apr 28, 2025

View reviewed changes

carlaKC requested a review from joostjager April 28, 2025 20:09

carlaKC mentioned this pull request Apr 28, 2025

Enhancements for LocalHTLCFailureReason #3753

Open

joostjager approved these changes Apr 28, 2025

View reviewed changes

valentinewallace merged commit 6f065ba into lightningdevkit:main Apr 29, 2025
25 of 27 checks passed

valentinewallace mentioned this pull request Apr 29, 2025

Run rustfmt on payment_tests and functional_tests and split up the latter #3751

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(3/3) Add Failure Reason to HTLCHandlingFailed #3700

(3/3) Add Failure Reason to HTLCHandlingFailed #3700

carlaKC commented Apr 2, 2025 •

edited

Loading

ldk-reviews-bot commented Apr 2, 2025 •

edited

Loading

codecov bot commented Apr 11, 2025 •

edited

Loading

valentinewallace commented Apr 16, 2025

ldk-reviews-bot commented Apr 21, 2025

carlaKC commented Apr 21, 2025

valentinewallace Apr 22, 2025

carlaKC Apr 23, 2025

valentinewallace Apr 23, 2025

valentinewallace Apr 28, 2025

carlaKC Apr 28, 2025

valentinewallace Apr 22, 2025

carlaKC Apr 23, 2025

carlaKC commented Apr 23, 2025

valentinewallace left a comment

valentinewallace Apr 25, 2025

carlaKC Apr 26, 2025

joostjager Apr 26, 2025

carlaKC Apr 28, 2025

joostjager left a comment

joostjager Apr 28, 2025

valentinewallace Apr 28, 2025

valentinewallace commented Apr 28, 2025

carlaKC commented Apr 28, 2025

carlaKC commented Apr 29, 2025

carlaKC commented Apr 29, 2025

valentinewallace commented Apr 29, 2025

(3/3) Add Failure Reason to HTLCHandlingFailed #3700

(3/3) Add Failure Reason to HTLCHandlingFailed #3700

Conversation

carlaKC commented Apr 2, 2025 • edited Loading

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

codecov bot commented Apr 11, 2025 • edited Loading

Codecov Report

valentinewallace commented Apr 16, 2025

ldk-reviews-bot commented Apr 21, 2025

carlaKC commented Apr 21, 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

Choose a reason for hiding this comment

carlaKC commented Apr 23, 2025

valentinewallace 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

joostjager left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

valentinewallace commented Apr 28, 2025

carlaKC commented Apr 28, 2025

carlaKC commented Apr 29, 2025

carlaKC commented Apr 29, 2025

valentinewallace commented Apr 29, 2025

carlaKC commented Apr 2, 2025 •

edited

Loading

ldk-reviews-bot commented Apr 2, 2025 •

edited

Loading

codecov bot commented Apr 11, 2025 •

edited

Loading