Introduce Dummy Hop support for Blinded Payment Path

[shaavan]

Builds on #4126

This PR adds Dummy Hop support for Blinded Payment Paths, paralleling the dummy-hop feature introduced for Blinded Message Paths in #3726.

By allowing arbitrary dummy hops before the real ReceiveTlvs, the length of a Blinded Payment Path can be increased to create a larger search space for an attacker trying to locate the true recipient. This reduces the risk of timing and position based deanonymization and improves user privacy.

[ldk-reviews-bot]

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

[shaavan]

The implementation is still in progress. The parsing logic that mitigates timing-based attacks is being refined. Once that’s settled, this PR will be ready for review.

[codecov]

Codecov Report

❌ Patch coverage is 89.49153% with 31 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.34%. Comparing base (6d4897c) to head (923982c).
⚠️ Report is 31 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/ln/onion_payment.rs	73.43%	17 Missing ⚠️
lightning/src/blinded_path/payment.rs	92.40%	3 Missing and 3 partials ⚠️
lightning/src/ln/offers_tests.rs	82.60%	4 Missing ⚠️
lightning/src/ln/channelmanager.rs	93.93%	2 Missing ⚠️
lightning/src/ln/msgs.rs	88.88%	1 Missing ⚠️
lightning/src/ln/onion_utils.rs	85.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4152      +/-   ##
==========================================
+ Coverage   89.32%   89.34%   +0.01%     
==========================================
  Files         180      180              
  Lines      138329   138873     +544     
  Branches   138329   138873     +544     
==========================================
+ Hits       123566   124070     +504     
- Misses      12157    12174      +17     
- Partials     2606     2629      +23     

Flag	Coverage Δ
fuzzing	35.88% <9.04%> (-0.01%)	⬇️
tests	88.70% <89.49%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

[TheBlueMatt]

Yay!

[TheBlueMatt]

Can we add a debug-assert that the forward hops and the dummy hops (ie all hops except the last) end up with the same length after padding?

[shaavan]

Good call, I’ll add that in the next update. Thanks for pointing it out!

[shaavan]

Updated: .01 → .02

Summary

This iteration introduces dummy hops before the actual receiver in a blinded path.
The current structure being evaluated is:

forward nodes -> dummy hops -> final receiver

The goal is to defend against potential timing side-channels at the receiver.
The mechanism works like this:

• When the final receiver gets what appears to be the first dummy hop,
  it decodes and stores a new update_add_htlc.
• This stored HTLC is decrypted only in the next background processing cycle,
  preventing immediate timing correlation attacks.

Conceptually this works, but it leads to two concrete issues, surfaced by failing tests.

---

Test Failures

1. rejects_keysend_to_non_static_invoice_path

Scenario:

Alice (Payer) --ss1--> Dummy01 --ss2--> Dummy02 --ss3--> Bob (Payee)

What happens:

• Alice constructs the onion as usual.
  She cannot know which hops are dummy, so she generates a shared secret (ss) for each hop.
• On receiving an invalid keysend, Bob tries to fail the HTLC backwards.
• As expected, Bob encrypts the failure with ss3.

The problem:
Dummy hops are not part of an actual HTLC chain.
They are parsed and consumed in-place, so there is no backward path.

So Bob tries to send an encrypted failure using ss3… but there's nowhere for it to go.
For this to work, Bob would need to remember ss1 (the introduction hop's secret) so he could encrypt the error correctly, but with the current design, that state doesn’t exist anywhere without invasive changes to internal flow structures.

The receiver cannot fail an HTLC backward when dummy hops are present.

---

2. creates_offer_with_blinded_path_using_unannounced_introduction_node

This test explores an Offer scenario with an unannounced introduction node.

Background (pre-dummy-hops):

• Alice creates an Offer.

• Bob tries to pay it.

• Alice and Bob share an unannounced channel.

• Alice constructs a two-hop blinded path to herself, using Bob as the introduction node.

• Bob recognizes himself as the introduction node and categorizes the remainder of blinded path as:

  CandidateRouteHop::OneHopBlinded { ... }
  

  (ref: router.rs L3346–3349

• As per spec logic, this leads Bob to treat the fee as 0:

  (ref: router.rs L1750–1752)

All good.

After dummy hops are introduced before the final receiver:

• Bob no longer sees himself as the sole real hop.
• From his point of view, he looks like an intermediate hop in a multi-hop blinded path.
• Because the hops are blinded, he cannot tell that the extra hops are dummy.
• Consequently, he charges non-zero fees, leading to overpayment, and the test fails.

Also Alice cannot manually set the fee to zero in blinded_payinfo, because any node might be the payer.

This breaks the “one-hop-blinded” assumption used for Offers payable through unannounced nodes.

---

Conclusion

Both failures point to the same root issue:

Inserting dummy hops changes the semantic meaning of the blinded path for both the sender and the introduction node.

• The payee loses the ability to fail an HTLC cleanly.
• The introduction node loses its ability to detect a one-hop blinded path.
• Neither side can special-case dummy hops without undermining the privacy properties dummy hops were meant to introduce.

I'm documenting this here as part of evaluating whether the dummy-hop approach (in this form) is viable, and to surface the structural implications before iterating further.

Feedback and alternative approaches welcome.

[shaavan]

Updated: .02 → .03

Changes

Account for an existing fee-handling trade-off in LDK that leads to a small, intentional overpayment when the payer is the introduction node of a blinded path. This restores the creates_offer_with_blinded_path_using_unannounced_introduction_node test under the new dummy-hop model, without modifying production fee logic.

Details

LDK already has a known quirk in blinded-path handling:

• When the payer is the introduction node, LDK does not subtract the forward fee for the payer -> next_hop channel.
• This keeps the fee logic simpler and results in a small, intentional overpayment by the payer.
• See BlindedPaymentPath::advance_path_by_one for the logic that omits this subtraction.

In the classic two-hop case where (payer as introduction node → payee), this overpayment used to be manually avoided in tests (see router.rs L1754–1756), because the path length was unambiguous and the introduction node could safely treat the effective fee as zero.

With the introduction of dummy hops, that assumption no longer holds:

• Even when there are only two real nodes (payer + payee), the blinded path may contain multiple hops due to dummy entries.
• From the introduction node’s perspective, it no longer appears to be a trivial one-hop-blinded path.
• Consequently, it charges a non-zero fee, and the test now observes an overpayment.

Rather than change LDK’s fee semantics in this PR, I’ve chosen to make this overpayment explicit in the test framework and document the reasoning clearly. Once the underlying fee trade-off is revisited in LDK, this temporary adjustment can be removed with minimal changes.

[shaavan]

Rebased: .03 → .04

[TheBlueMatt]

The receiver cannot fail an HTLC backward when dummy hops are present.

This shouldn't be an issue? We should be failing all blinded path receives with invalid_onion_blinding and we should thus not need the blinding point or shared secret.

Re: the fee issues, yea, its something we'll have to handle, but in practice what should happen is that we pick a route with a non-zero fee, then we go to pay it and when we start unwrapping the onion we notice that the fee is for us, allowing us to reclaim the funds.

Interestingly, this is a bit of a privacy leak - if the sender and the intro node are the same they can intuit that the remaining hops are blinded. Dunno if its worth doing anything about but we could add fees for the blinded hops.

[shaavan]

Updated: .04 → .05

Changes:

• Fixed the third test.

@TheBlueMatt

This shouldn't be an issue? We should be failing all blinded path receives with invalid_onion_blinding and we should thus not need the blinding point or shared secret.

Thanks a lot Matt, that comment really helped clear things up.

I had been assuming the existing test behaviour should stay the same even after introducing dummy hops, but your note made me rethink that.

In rejects_keysend_to_non_static_invoice_path, the original failure happened at the introduction node of the one-hop blinded path, so update_fail_htlc made sense there.

Once dummy hops are in the mix though, the failure no longer originates at the intro node. It surfaces from a deeper BlindedNode, so update_fail_malformed_htlc is indeed the right failure type here.

Updated the test accordingly. Thanks again!

[shaavan]

Updated: .05 → .06

Changes:

Cleaned up the commits for clarity and flow.

Note

With this update, the first full version of Payment Dummy Hops for Blinded Payment Path receive is finally in place.
And it’s now ready for review.

The dummy-hop support for TrampolineBlindedReceive will follow in a separate PR.

[shaavan]

Updated: .06 → .07

Addressed @TheBlueMatt’s comment — updates:

• Added a debug-assert during blinded payment path construction to ensure all hops
  (except the final recipient) serialize to the same length.
• Fixed the introduced test.
• Removed the now-unnecessary PaymentDummyTlv struct as part of a small cleanup.