(3/3) Add Failure Reason to HTLCHandlingFailed by carlaKC · Pull Request #3700 · lightningdevkit/rust-lightning

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.

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 🥳

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

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

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

 	},
 	/// 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.

valentinewallace

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

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

+ 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).

joostjager

LGTM

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

+}
+
+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.

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 HTLCHandlingFailedApr 2, 2025

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

valentinewallace reviewed Apr 4, 2025
View reviewed changes

Comment threadlightning/src/events/mod.rs

valentinewallace mentioned this pull request Apr 10, 2025
WIP: Trampoline forwarding #3711
Closed
4 tasks

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

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

carlaKC force-pushed the 3541-api-changes branch from b48c6ce to cda8de5Compare 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 6638118Compare April 21, 2025 13:37

valentinewallace reviewed Apr 22, 2025
View reviewed changes

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

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

valentinewallace reviewed Apr 25, 2025
View reviewed changes

Comment threadlightning/src/events/mod.rs Outdated

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

valentinewallace previously approved these changes Apr 25, 2025
View reviewed changes

valentinewallace reviewed Apr 25, 2025
View reviewed changes

Comment threadlightning/src/events/mod.rs Outdated

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

carlaKC added a commit to carlaKC/rust-lightning that referenced this pull request Apr 26, 2025
pending_changelog: add notes forlightningdevkit#3700
5badb5e

carlaKC added a commit to carlaKC/rust-lightning that referenced this pull request Apr 26, 2025
pending_changelog: add notes forlightningdevkit#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

Comment threadpending_changelog/3700-reason-in-handling-failed.txt

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

carlaKC force-pushed the 3541-api-changes branch from 5badb5e to ed5210dCompare 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 af301f4Compare 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:mainApr 29, 2025

valentinewallace mentioned this pull request Apr 29, 2025
Run rustfmt on payment_tests and functional_tests and split up the latter #3751
Merged

Uh oh!

Conversation

carlaKC commented Apr 2, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

codecovBot commented Apr 11, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

valentinewallace commented Apr 16, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Apr 21, 2025

Uh oh!

carlaKC commented Apr 21, 2025

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carlaKC commented Apr 23, 2025

Uh oh!

Uh oh!

valentinewallace left a comment

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

joostjager 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!

valentinewallace commented Apr 28, 2025

Uh oh!

carlaKC commented Apr 28, 2025

Uh oh!

carlaKC commented Apr 29, 2025

Uh oh!

carlaKC commented Apr 29, 2025

Uh oh!

valentinewallace commented Apr 29, 2025

Uh oh!

Reviewers

Assignees

carlaKC commented Apr 2, 2025•
edited
Loading

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

codecovBot commented Apr 11, 2025•
edited
Loading