(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

👋 I see @wpaulino was un-assigned.
If you'd like another reviewer assignemnt, please click here.

lightning/src/events/mod.rs

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

Codecov Report

Attention: Patch coverage is 86.67546% with 101 lines in your changes missing coverage. Please review.

Project coverage is 89.09%. Comparing base (83e9e80) to head (2d39ef8).

Files with missing lines	Patch %	Lines
lightning/src/events/mod.rs	8.33%	33 Missing ⚠️
lightning/src/ln/onion_payment.rs	69.49%	16 Missing and 2 partials ⚠️
lightning/src/ln/onion_utils.rs	90.16%	18 Missing ⚠️
lightning/src/ln/channelmanager.rs	90.44%	16 Missing and 1 partial ⚠️
lightning/src/ln/channel.rs	77.55%	9 Missing and 2 partials ⚠️
lightning-liquidity/src/lsps2/service.rs	0.00%	2 Missing ⚠️
lightning/src/ln/functional_test_utils.rs	90.00%	0 Missing and 1 partial ⚠️
lightning/src/ln/monitor_tests.rs	83.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3700      +/-   ##
==========================================
- Coverage   89.12%   89.09%   -0.04%     
==========================================
  Files         156      156              
  Lines      123514   123670     +156     
  Branches   123514   123670     +156     
==========================================
+ Hits       110086   110186     +100     
- Misses      10749    10799      +50     
- Partials     2679     2685       +6

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

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

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 HTLCHandlingType struct to present more consistent API terminology.

This variant of HTLCHandlingType contains infromation about the failure cause along with its type - as an UnknownNextPeer is just an InvalidForward that has the failure type UnknownNextPeer. This commit deprecates the variant's use, while still writing it to disk to allow the option to downgrade.

This struct doesn't just contain a failure reason, it has all the data that's used to construct our failure.

joostjager · 2025-04-18T12:05:36Z

lightning/src/events/mod.rs

@@ -502,7 +502,7 @@ pub enum HTLCHandlingType {
 	/// * The counterparty node modified the HTLC in transit,
 	/// * A probing attack where an intermediary node is trying to detect if we are the ultimate
 	///   recipient for a payment.
-	FailedPayment {
+	ReceiveFailed {


In the context of HTLCHandlingType, this would communicate that receiving the htlc failed. Previously a reference to payment was in the name, but I think that was a layering violation?

This represents all HTLCs that were intended for our node as the final node, but were rejected.

I think that Payment is a bad name here because PaymentFailed could refer to a payment you sent or one you received (it was unclear to me when I first encountered this struct). Receive is less ambiguous.

joostjager · 2025-04-18T12:06:40Z

lightning/src/events/mod.rs

@@ -471,7 +471,7 @@ impl_writeable_tlv_based_enum_upgradable!(ClosureReason,
 pub enum HTLCHandlingType {
 	/// We tried forwarding to a channel but failed to do so. An example of such an instance is when
 	/// there is insufficient capacity in our outbound channel.
-	NextHopChannel {
+	ForwardFailed {


Indeed, it shouldn't be underestimated how much naming helps with understanding code.

joostjager · 2025-04-18T12:07:55Z

lightning/src/events/mod.rs

@@ -525,6 +525,31 @@ impl_writeable_tlv_based_enum_upgradable!(HTLCHandlingType,
 	},
 );

+/// The reason for HTLC failures in [`Event::HTLCHandlingFailed`].
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum HTLCHandlingFailureReason {


This one does remind me of HTLCFailReasonRepr. Isn't there more in that struct that might be useful to expose here such as the failure data or the hold time?

Definitely, this is essentially an external facing version of HTLCFailReasonRepr.

I don't think that we'll ever want to surface the encrypted data blob on the API, which is my main reason for not surfacing HTLCFailReasonRepr.

We're also not going to have tons and tons of fields that we need to translate from one to the other so I think it's nice to have a clean/readable api-facing struct.

joostjager · 2025-04-18T12:11:35Z

lightning/src/events/mod.rs

@@ -466,9 +466,9 @@ impl_writeable_tlv_based_enum_upgradable!(ClosureReason,
 	},
 );

-/// Intended destination of a failed HTLC as indicated in [`Event::HTLCHandlingFailed`].
+/// The type of HTLC that is being handled in [`Event::HTLCHandlingFailed`].


"the type of htlc that is being handled", but isn't it more the outcome of the htlc forward, not saying much about the htlc itself? In particular ForwardFailed doesn't have much to do with the htlc?

"the type of htlc that is being handled", but isn't it more the outcome of the htlc forward, not saying much about the htlc itself?

Would "the handling action taken" be better? Aiming to represent what we were supposed to do to the HTLC we were handed (forward it/ receive it / we don't know because it's invalid).

Open to better naming/wording if you have it, but I do think that outcome is more associated with settle/fail so not a good fit here.

ForwardFailed doesn't have much to do with the htlc?

Do you mean InvalidForward?

joostjager · 2025-04-18T12:18:20Z

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


typo in commit msg 'infromation'

joostjager · 2025-04-18T12:22:56Z

lightning/src/events/mod.rs

+				let downgradable_type = match (handling_type, handling_failure) {
+					(HTLCHandlingType::InvalidForward { requested_forward_scid },
+						Some(HTLCHandlingFailureReason::Local { reason }))
+					if *reason == LocalHTLCFailureReason::UnknownNextPeer =>


I believe you can get rid of the inner if

let downgradable_type = match (handling_type, handling_failure) { ( HTLCHandlingType::InvalidForward { requested_forward_scid }, Some(HTLCHandlingFailureReason::Local { reason: LocalHTLCFailureReason::UnknownNextPeer, }), ) => HTLCHandlingType::UnknownNextHop { requested_forward_scid: *requested_forward_scid, }, _ => handling_type.clone(), };

joostjager · 2025-04-18T12:27:13Z

lightning/src/events/mod.rs

+					// where we have a legacy event
+					match event {
+						Event::HTLCHandlingFailed { ref handling_type, .. } => {
+							if let HTLCHandlingType::UnknownNextHop { requested_forward_scid } = handling_type {


Similar alternative:

match event { Event::HTLCHandlingFailed { handling_type: HTLCHandlingType::UnknownNextHop { requested_forward_scid }, .. } => { event = Event::HTLCHandlingFailed { prev_channel_id, handling_type: HTLCHandlingType::InvalidForward { requested_forward_scid: requested_forward_scid, }, handling_failure: Some(LocalHTLCFailureReason::UnknownNextPeer.into()), }; } _ => panic!("HTLCHandlingFailed wrong type"), }

joostjager · 2025-04-18T12:30:14Z

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 still see one occurrence of HTLCHandlingType::UnknownNextHop in a macro in process_pending_htlc_forwards

joostjager · 2025-04-18T12:32:42Z

lightning/src/ln/onion_utils.rs

 #[derive(Clone)] // See Channel::revoke_and_ack for why, tl;dr: Rust bug
 #[cfg_attr(test, derive(PartialEq))]
-pub(super) struct HTLCFailReason(HTLCFailReasonRepr);
+pub(super) struct HTLCFailurePayload(HTLCFailReasonRepr);


Embedded inside there is still a reason? Payload with a reason repr 🤔

Rename the internal struct as well?

Open to other naming suggestions here, aim is to differentiate this from the HTLCHandlingFailureReason a bit.

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 added 6 commits April 16, 2025 11:21

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

a269f75

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 ForwardFailed

75b8ca5

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

ln+events: add htlc failure reason to HTLCHandlingFailed

d35d35f

lightning/refactor: rename HTLCFailReason to HTLCFailurePayload

cda8de5

This struct doesn't just contain a failure reason, it has all the data that's used to construct our failure.

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

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

joostjager Apr 18, 2025

carlaKC Apr 18, 2025

joostjager Apr 18, 2025

joostjager Apr 18, 2025

carlaKC Apr 18, 2025

joostjager Apr 18, 2025

carlaKC Apr 18, 2025

joostjager Apr 18, 2025

joostjager Apr 18, 2025

carlaKC Apr 18, 2025

joostjager Apr 18, 2025

joostjager Apr 18, 2025

carlaKC Apr 18, 2025

joostjager Apr 18, 2025

carlaKC Apr 18, 2025

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

Are you sure you want to change the base?

(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

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

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

edited

Loading

ldk-reviews-bot commented Apr 2, 2025 •

edited

Loading

codecov bot commented Apr 11, 2025 •

edited

Loading