Expose withheld amount for underpaying HTLCs in PaymentForwarded

[tnull]

We generally allow routing nodes to forward less than the expected HTLC amount, if the receiver knowingly accepts this and claims the underpaying HTLC (see ChannelConfig::accept_underpaying_htlcs). This is in particular useful for the LSPS2/JIT use case where the intial underpaying HTLC pays for the channel open (see lightning/blips#25).

While we previously exposed the withheld amount as PaymentClaimable::counterparty_skimmed_fee_msat on the receiver side, we did not individually provide it on the forwarding node's side. Here, we therefore expose this additionally withheld amount via PaymentForwarded::skimmed_fee_msat.

(cc @johncantrell97 @valentinewallace)

[coderabbitai]

Note

Reviews Paused

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Walkthrough

The recent updates introduce a new skimmed_fee_msat field to the Event enum, enhancing the handling of fees in payment forwarding and settlement processes. Modifications in function parameters and return types across several files support this addition. Tests are adjusted with a focus on payment forwarding, incorporating changes in expectations and assertions to align with the new fee management strategy.

Changes

Files	Changes
.../src/events/mod.rs, .../src/ln/channelmanager.rs	Added skimmed_fee_msat to Event enum; updated claim_funds_internal and internal_update_fulfill_htlc functions to handle new parameter.
.../src/ln/chanmon_update_fail_tests.rs, .../src/ln/payment_tests.rs, .../src/ln/reload_tests.rs, .../src/ln/shutdown_tests.rs	Updated expect_payment_forwarded! macro calls from false to None.
.../src/ln/channel.rs	Updated update_fulfill_htlc to return Result with a new Option<u64> element.
.../src/ln/functional_test_utils.rs	Modified expect_payment_forwarded to include expected_extra_fee_limit_msat parameter; updated macro and assertion logic.
.../src/ln/functional_tests.rs	Adjusted Event::PaymentForwarded struct patterns and assertions in test functions.
.../src/ln/reorg_tests.rs	Changed parameter in expect_payment_forwarded call to None.

Poem

In the digital burrows where the lightning flows,
A tiny fee was skimmed, as the clever rabbit knows.
With hops and leaps through the code, it goes,
🐰💨 Celebrating the change, in verse, it chose.

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

Share

• X
• Mastodon
• Reddit
• LinkedIn

---

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit-tests for this file.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit tests for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository from git and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit tests.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger a review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• The JSON schema for the configuration file is available here.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/coderabbit-overrides.v2.json

CodeRabbit Discord Community

Join our Discord Community to get help, request features, and share feedback.

[coderabbitai]

Review Status

Actionable comments generated: 0

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 51d9ee3 and 9901a4b.

Files selected for processing (10)

• lightning/src/events/mod.rs (5 hunks)
• lightning/src/ln/chanmon_update_fail_tests.rs (8 hunks)
• lightning/src/ln/channel.rs (1 hunks)
• lightning/src/ln/channelmanager.rs (6 hunks)
• lightning/src/ln/functional_test_utils.rs (3 hunks)
• lightning/src/ln/functional_tests.rs (5 hunks)
• lightning/src/ln/payment_tests.rs (3 hunks)
• lightning/src/ln/reload_tests.rs (2 hunks)
• lightning/src/ln/reorg_tests.rs (1 hunks)
• lightning/src/ln/shutdown_tests.rs (3 hunks)

Files not reviewed due to errors (2)

• lightning/src/ln/functional_test_utils.rs (Error: unable to parse review)
• lightning/src/ln/payment_tests.rs (Error: unable to parse review)

Files skipped from review due to trivial changes (2)

• lightning/src/ln/chanmon_update_fail_tests.rs
• lightning/src/ln/shutdown_tests.rs

Additional comments: 14

lightning/src/ln/reorg_tests.rs (1)

• 128-128: The expect_payment_forwarded call now includes a None parameter for skimmed_fee_msat, aligning with the PR's objective to handle underpaid HTLCs. This change is consistent with the PR's goal to enhance visibility and traceability of withheld amounts in HTLC forwarding scenarios.

lightning/src/ln/reload_tests.rs (2)

• 931-931: The line expect_payment_forwarded!(nodes[2], nodes[0], nodes[3], Some(1000), None, false, false); has been replaced with None as the third argument in the expect_payment_forwarded! macro call. This change seems to align with the PR's objective to enhance the handling of underpaid HTLCs by introducing more explicit control over the fee skimming behavior. However, it's crucial to ensure that this change does not inadvertently affect the logic for forwarding payments, especially in scenarios where underpayment is not a factor.

Ensure that the updated macro call with None correctly handles all scenarios, including those not involving underpaid HTLCs. It's important to verify that this change does not introduce any regressions in payment forwarding behavior.

• 1081-1081: The line expect_payment_forwarded!(nodes[1], nodes[0], nodes[2], Some(1000), None, false, true); has been replaced with None as the third argument in the expect_payment_forwarded! macro call. Similar to the previous comment, this modification is presumably aimed at refining the handling of fees for underpaid HTLCs. It's essential to validate that this adjustment does not negatively impact the payment forwarding process, particularly in standard payment scenarios.

Confirm that the change to the expect_payment_forwarded! macro call with None accurately processes all relevant cases, including those not related to underpayment. This verification is crucial to prevent any unintended consequences on the payment forwarding mechanism.

lightning/src/events/mod.rs (1)

• 797-812: > 📝 NOTE

This review was outside the diff hunks and was mapped to the diff hunk with the greatest overlap. Original lines [786-809]

The addition of skimmed_fee_msat to the PaymentForwarded event is correctly implemented. This field provides forwarding nodes with detailed information about the fees they withhold when processing underpaid HTLCs, aligning with the PR's objectives. The optional nature of skimmed_fee_msat ensures compatibility with scenarios where an intercepted HTLC is forwarded with the expected amount, making the field unnecessary. The implementation also correctly handles the potential for duplicate PaymentForwarded events when fee_earned_msat is None, indicating that the final fee calculation is pending due to on-chain transactions. This change enhances transparency and decision-making for nodes in the forwarding and settlement of HTLCs.

lightning/src/ln/functional_tests.rs (2)

• 5100-5100: The change in the value for outbound_amount_forwarded_msat from Some(196) to None in the expect_payment_forwarded! macro call is a significant alteration. This change likely reflects a specific test scenario adjustment. It's important to ensure that this change accurately represents the intended test conditions and outcomes, especially in the context of underpaid HTLCs. The PR description does not explicitly mention this adjustment, so it's crucial to verify its alignment with the overall objectives.
• 8822-8822: This modification in the expect_payment_forwarded! macro call, specifically the conditional value for outbound_amount_forwarded_msat, demonstrates flexibility in testing different scenarios of HTLC forwarding and settlement. It's a good practice to cover various cases, including on-chain and off-chain settlements. Ensuring that these test modifications align with the intended scenarios described in the PR objectives is important for the accuracy and comprehensiveness of the test suite.

lightning/src/ln/channel.rs (1)

• 3307-3315: The modification to update_fulfill_htlc's return type to include Option<u64> as the third element in the tuple is a significant change. This addition likely represents the skimmed_fee_msat and is a crucial part of enhancing transparency for forwarding nodes regarding withheld fees in underpaid HTLCs. Ensure that all calls to this function across the codebase have been updated to handle the new tuple structure. Additionally, consider adding documentation comments to explain the significance of each element in the returned tuple, especially the Option<u64> element, to improve code readability and maintainability.

lightning/src/ln/channelmanager.rs (7)

• 5671-5673: The addition of skimmed_fee_msat as a parameter to claim_funds_internal is consistent with the PR's objective to enhance visibility of withheld amounts in underpaid HTLCs. Ensure that all calls to this function have been updated to include this new parameter.
• 5771-5772: The debug_assert! ensures that skimmed_fee_msat is always less than or equal to fee_earned_msat, which is a logical check to maintain data integrity. This is a good practice for catching potential logic errors during development.
• 5771-5780: The inclusion of skimmed_fee_msat in the PaymentForwarded event aligns with the PR's goal to provide detailed information about fees withheld from underpaid HTLCs. This change enhances transparency for forwarding nodes.
• 6719-6719: The tuple unpacking for htlc_source, forwarded_htlc_value, and skimmed_fee_msat within internal_update_fulfill_htlc introduces the handling of the new skimmed_fee_msat parameter. This change is necessary for processing the updated event structure.
• 6757-6760: The call to claim_funds_internal within internal_update_fulfill_htlc has been correctly updated to include the skimmed_fee_msat parameter. This ensures that the function aligns with the updated signature and supports the new functionality.
• 7257-7257: In the context of claiming HTLCs from the monitor, skimmed_fee_msat is passed as None since this scenario does not involve skimming fees from underpaid HTLCs. This usage is appropriate given the context and maintains the flexibility of the claim_funds_internal function.
• 11130-11130: The call to claim_funds_internal from within the channel monitor's handling logic correctly passes None for skimmed_fee_msat when claiming funds. This is consistent with the expected behavior when the source of the preimage is not directly related to an underpaid HTLC forwarding event.

[tnull]

@coderabbitai pause

[codecov-commenter]

Codecov Report

Attention: 2 lines in your changes are missing coverage. Please review.

Comparison is base (5bf58f0) 89.14% compared to head (9644588) 89.35%.
Report is 2 commits behind head on main.

Files	Patch %	Lines
lightning/src/events/mod.rs	80.00%	2 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2858      +/-   ##
==========================================
+ Coverage   89.14%   89.35%   +0.20%     
==========================================
  Files         116      116              
  Lines       93205    95035    +1830     
  Branches    93205    95035    +1830     
==========================================
+ Hits        83089    84914    +1825     
- Misses       7583     7643      +60     
+ Partials     2533     2478      -55     

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

[valentinewallace]

LGTM! Pretty trivially exposes a new event field with test coverage, so I don't think a 2nd reviewer is needed, but I'll give it a day or so before merging just in case.

[valentinewallace]

I realized that one weird thing about this is that min HTLC overpayment may occur for any hop, not just the penultimate hop (unlike skimmed fees). Pre-existing though.

[tnull]

Amended the last commit to include the following changes:

> git diff-tree -U2 c5bb00a0a 96445880f
diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index 15bf220cf..801e8695c 100644
--- a/lightning/src/events/mod.rs
+++ b/lightning/src/events/mod.rs
@@ -804,5 +804,7 @@ pub enum Event {
                /// expected amount. This means our counterparty accepted to receive less than the invoice
                /// amount, e.g., by claiming the payment featuring a corresponding
-               /// [`PaymentClaimable::counterparty_skimmed_fee_msat`]
+               /// [`PaymentClaimable::counterparty_skimmed_fee_msat`].
+               ///
+               /// Will also always be `None` for events serialized with LDK prior to version 0.0.122.
                ///
                /// The caveat described above the `total_fee_earned_msat` field applies here as well.
diff --git a/lightning/src/ln/chanmon_update_fail_tests.rs b/lightning/src/ln/chanmon_update_fail_tests.rs
index a8154a621..5f7c72be1 100644
--- a/lightning/src/ln/chanmon_update_fail_tests.rs
+++ b/lightning/src/ln/chanmon_update_fail_tests.rs
@@ -14,5 +14,6 @@

 use bitcoin::blockdata::constants::genesis_block;
-use bitcoin::hash_types::BlockHash; use bitcoin::network::constants::Network;
+use bitcoin::hash_types::BlockHash;
+use bitcoin::network::constants::Network;
 use crate::chain::channelmonitor::{ANTI_REORG_DELAY, ChannelMonitor};
 use crate::chain::transaction::OutPoint;
diff --git a/lightning/src/ln/functional_test_utils.rs b/lightning/src/ln/functional_test_utils.rs
index b91d255fc..e53fd6b0c 100644
--- a/lightning/src/ln/functional_test_utils.rs
+++ b/lightning/src/ln/functional_test_utils.rs
@@ -2237,7 +2237,8 @@ macro_rules! expect_payment_forwarded {
                let mut events = $node.node.get_and_clear_pending_events();
                assert_eq!(events.len(), 1);
-               $crate::ln::functional_test_utils::expect_payment_forwarded( events.pop().unwrap(), &$node,
-                       &$prev_node, &$next_node, $expected_fee, None, $upstream_force_closed,
-                       $downstream_force_closed);
+               $crate::ln::functional_test_utils::expect_payment_forwarded(
+                       events.pop().unwrap(), &$node, &$prev_node, &$next_node, $expected_fee, None,
+                       $upstream_force_closed, $downstream_force_closed
+               );
        }
 }