Add support for "phantom" BOLT 12 offers, up to the invoice_request step by TheBlueMatt · Pull Request #4335 · lightningdevkit/rust-lightning

TheBlueMatt · 2026-01-22T14:54:59Z

In the BOLT 11 world, we have specific support for what we call
"phantom nodes" - creating invoices which can be paid to any one of
a number of nodes by adding route-hints which represent nodes that
do not exist.

In BOLT 12, blinded paths make a similar feature much simpler - we
can simply add blinded paths which terminate at different nodes.
The blinding means that the sender is none the wiser.

Here we add logic to fetch an OfferBuilder which can generate an
offer payable to any one of a set of nodes. We retain the "phantom"
terminology even though there are no longer any "phantom" nodes.

Note that the current logic only supports the invoice_request
message going to any of the participating nodes, it then replies
with a Bolt12Invoice which can only be paid to the responding
node. Future work may relax this restriction.

Also,

Note that we will not yet use the blinded payment path phantom
support which requires additional future work. However, allowing
them to be authenticated in a phantom configuration should allow
for compatibility across versions once the building logic lands.

Progress towards full solution for #4313, but enough to get folks started.

ldk-reviews-bot · 2026-01-22T14:55:03Z

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

joostjager · 2026-01-23T07:22:36Z

lightning/src/crypto/streams.rs

 /// checked, effectively treating the contents as the AAD for the AAD-containing MAC but behaving
 /// like classic ChaCha20Poly1305 for the non-AAD-containing MAC.
-pub(crate) struct ChaChaDualPolyReadAdapter<R: Readable> {
+pub(crate) struct ChaChaTriPolyReadAdapter<R: Readable> {


Would you say there is sufficient test coverage on this? I think there is some higher-level coverage, but no direct unit test.

I think so? I mean if its horribly broken the higher-level code will also break. Its also somewhat indirectly fuzzed through the onion decoding fuzzing.

I think lower level unit tests do have value even if there are higher level tests already.

Not really sure what you'd want to test? That it can decrypt correctly? That's definitely well-covered. The one bug we did have in it was found by our fuzz test. More test coverage is great but more tests to get the same coverage seems like a net-negative.

lightning/src/crypto/streams.rs

joostjager · 2026-01-23T07:34:05Z

lightning/src/blinded_path/payment.rs

-		let ChaChaDualPolyReadAdapter { readable, used_aad } =
-			ChaChaDualPolyReadAdapter::read(&mut reader, (rho, receive_auth_key.0))
-				.map_err(|_| ())?;
+		let ChaChaTriPolyReadAdapter { readable, used_aad_a, used_aad_b } =


Names like used_local and used_phantom could be helpful

Sadly I can't rename the fields since I switched to an enum.

Why not use Local and Phantom in the enum? This adapter isn't used for anything else.

Because that's really confusing when you read the stream type that isn't dedicated to only use in blinded paths. I'm not at all convinced the callsites are unclear, and we also might need to/want to upstream this at some point to rust-bitcoin.

lightning/src/ln/msgs.rs

joostjager · 2026-01-23T07:51:31Z

lightning/src/ln/channelmanager.rs

+						.iter()
+						.filter(|chan| chan.is_usable)
+						.filter_map(|chan| chan.short_channel_id)
+						.min(),


Its the oldest, matching the existing logic we have for the non-phantom case.

Is that to maximize the chances that it still exist? Curious where the existing logic is located also.

Yea, basically. Absent any better criteria we assume that the oldest channel is most likely to stick around. We do it in get_peers_for_blinded_path as well using funded_channel.context.channel_creation_height

Won't an old channel that is spliced recently seem newer? Also, should we use inbound_scid_alias if set as is done in get_peers_for_blinded_path by using FundedChannel::get_inbound_scid?

Won't an old channel that is spliced recently seem newer?

Indeed it will. There's no obvious fix for that AFAICT, but it also shouldn't really matter - we could just pick a random SCID too if we want...

Also, should we use inbound_scid_alias if set as is done in get_peers_for_blinded_path by using FundedChannel::get_inbound_scid?

Oops, right.

Could we expose channel_creation_height in ChannelDetails?

joostjager · 2026-01-23T07:58:05Z

lightning/src/blinded_path/payment.rs

 			node_signer.ecdh(Recipient::Node, &self.inner_path.blinding_point, None)?;
 		let rho = onion_utils::gen_rho_from_shared_secret(&control_tlvs_ss.secret_bytes());
 		let receive_auth_key = node_signer.get_receive_auth_key();
+		let phantom_auth_key = node_signer.get_expanded_key().phantom_node_blinded_path_key;


You could have None here in case the node isn't configured for phantom payments. I think that might help keep that case in mind for readers, and also saves some computation?

Yea, we don't currently have a separate method on the signer that returns None in cases where we aren't doing phantom so we'd have to add a new key-fetcher (or bool-fetcher) to decide whether to do phantom validation. I thought about doing that but it seemed way cleaner to reuse the ExpandedKey (which is already used for all the inbound-payment key logic, including phantom). Its also not very much compute at all to just do one round of poly1305 + the finish logic so I'm not sure its worth the extra work.

lightning/src/ln/offers_tests.rs

lightning/src/ln/channelmanager.rs

ldk-reviews-bot · 2026-01-23T08:13:18Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

codecov · 2026-01-27T01:06:15Z

Codecov Report

❌ Patch coverage is 93.98907% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.02%. Comparing base (4800a47) to head (5a672bd).
⚠️ Report is 20 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/ln/channelmanager.rs	92.68%	2 Missing and 1 partial ⚠️
lightning/src/util/test_utils.rs	76.92%	3 Missing ⚠️
lightning/src/offers/flow.rs	94.28%	1 Missing and 1 partial ⚠️
lightning/src/blinded_path/payment.rs	83.33%	0 Missing and 1 partial ⚠️
lightning/src/ln/msgs.rs	90.90%	0 Missing and 1 partial ⚠️
lightning/src/onion_message/packet.rs	95.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #4335    +/-   ##
========================================
  Coverage   86.01%   86.02%            
========================================
  Files         156      156            
  Lines      102781   102981   +200     
  Branches   102781   102981   +200     
========================================
+ Hits        88409    88588   +179     
- Misses      11864    11881    +17     
- Partials     2508     2512     +4

Flag	Coverage Δ
tests	`86.02% <93.98%> (+<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.

joostjager

No blocking comments. I do think that renaming the enum values would be a good idea. Curious to hear from 2nd reviewer.

joostjager · 2026-01-27T19:41:01Z

lightning/src/crypto/streams.rs

 /// checked, effectively treating the contents as the AAD for the AAD-containing MAC but behaving
 /// like classic ChaCha20Poly1305 for the non-AAD-containing MAC.
-pub(crate) struct ChaChaDualPolyReadAdapter<R: Readable> {
+pub(crate) struct ChaChaTriPolyReadAdapter<R: Readable> {


I think lower level unit tests do have value even if there are higher level tests already.

lightning/src/ln/channelmanager.rs

joostjager · 2026-01-27T19:44:22Z

lightning/src/blinded_path/payment.rs

-		let ChaChaDualPolyReadAdapter { readable, used_aad } =
-			ChaChaDualPolyReadAdapter::read(&mut reader, (rho, receive_auth_key.0))
-				.map_err(|_| ())?;
+		let ChaChaTriPolyReadAdapter { readable, used_aad_a, used_aad_b } =


Why not use Local and Phantom in the enum? This adapter isn't used for anything else.

joostjager · 2026-01-27T19:47:38Z

lightning/src/ln/channelmanager.rs

+						.iter()
+						.filter(|chan| chan.is_usable)
+						.filter_map(|chan| chan.short_channel_id)
+						.min(),


Is that to maximize the chances that it still exist? Curious where the existing logic is located also.

lightning/src/ln/channelmanager.rs

joostjager · 2026-01-27T19:49:37Z

lightning/src/ln/functional_test_utils.rs

-		let keys_manager = if predefined_keys_ids.is_some() {
+		let mut seed = [i as u8; 32];
+		if phantom {
+			// We would ideally randomize keys on every test run, but some tests fail in that case.


I think there are pros and cons. Fully deterministic tests are desirable too sometimes.

lightning/src/ln/offers_tests.rs

ldk-reviews-bot · 2026-01-27T20:18:01Z

✅ Added second reviewer: @jkczyz

ldk-reviews-bot · 2026-01-29T20:18:07Z

🔔 1st Reminder

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

ldk-reviews-bot · 2026-02-02T00:00:51Z

🔔 2nd Reminder

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

It turns out we also switched the key we use to authenticate offers *created* in the 0.2 upgrade and as a result downgrading to 0.2 will break any offers created on 0.2. This wasn't intentional but it doesn't really seem worth fixing at this point, so just document it.

In the coming commits we'll add support for building a blinded path which can be received to any one of several nodes in a "phantom" configuration (terminology we retain from BOLT 11 though there are no longer any phantom nodes in the paths). Here we adda new key in `ExpandedKey` which we can use to authenticate blinded paths as coming from a phantom node participant.

TheBlueMatt · 2026-02-03T14:10:36Z

Rebased without further changes.

lightning/src/ln/inbound_payment.rs

lightning/src/crypto/streams.rs

lightning/src/ln/channelmanager.rs

jkczyz · 2026-02-03T16:57:59Z

lightning/src/ln/channelmanager.rs

+						.iter()
+						.filter(|chan| chan.is_usable)
+						.filter_map(|chan| chan.short_channel_id)
+						.min(),


Won't an old channel that is spliced recently seem newer? Also, should we use inbound_scid_alias if set as is done in get_peers_for_blinded_path by using FundedChannel::get_inbound_scid?

jkczyz · 2026-02-03T17:02:48Z

lightning/src/ln/channelmanager.rs

+	///
+	/// [`ExpandedKey`]: inbound_payment::ExpandedKey
+	pub fn create_phantom_offer_builder(
+		&$self, other_nodes_channels: Vec<(PublicKey, Vec<ChannelDetails>)>,


For BOLT11 phantom, we have the invoice creator pass all the details, even their own. Should we do the same here? More broadly, are we expecting the caller to query all the nodes for the details? Or do we expect them to have some process that periodically does that and they are just looking up the results?

For BOLT11 phantom, we have the invoice creator pass all the details, even their own. Should we do the same here?

I don't really have a strong opinion. For BOLT 11 we use a loose method not on ChannelManager but here I wanted to use the offers flow for simplicity. We could make it a loose method on the flow object and make the dev pass in all nodes' details or we could do so on ChannelManager, it just felt pretty weird to require someone pass in local details directly to the ChannelManager they just queried.

More broadly, are we expecting the caller to query all the nodes for the details? Or do we expect them to have some process that periodically does that and they are just looking up the results?

Probably the second? as long as its relatively often-refreshed.

If the second, then it seems the caller would need to fetch them and then filter their own, though? Unless the request says to filter by some node id.

In the next commit we'll add support for building a BOLT 12 offer which can be paid to any one of a number of participant nodes. Here we add support for validating blinded paths as coming from one of the participating nodes by deriving a new key as a part of the `ExpandedKey`. We keep this separate from the existing `ReceiveAuthKey` which is node-specific to ensure that we only allow this key to be used for blinded payment paths and contexts in `invoice_request` messages. This ensures that normal onion messages are still tied to specific nodes. Note that we will not yet use the blinded payment path phantom support which requires additional future work. However, allowing them to be authenticated in a phantom configuration should allow for compatibility across versions once the building logic lands.

In the BOLT 11 world, we have specific support for what we call "phantom nodes" - creating invoices which can be paid to any one of a number of nodes by adding route-hints which represent nodes that do not exist. In BOLT 12, blinded paths make a similar feature much simpler - we can simply add blinded paths which terminate at different nodes. The blinding means that the sender is none the wiser. Here we add logic to fetch an `OfferBuilder` which can generate an offer payable to any one of a set of nodes. We retain the "phantom" terminology even though there are no longer any "phantom" nodes. Note that the current logic only supports the `invoice_request` message going to any of the participating nodes, it then replies with a `Bolt12Invoice` which can only be paid to the responding node. Future work may relax this restriction.

TheBlueMatt added this to the 0.3 milestone Jan 22, 2026

ldk-reviews-bot requested a review from joostjager January 22, 2026 15:06

TheBlueMatt added this to Weekly Goals Jan 22, 2026

TheBlueMatt self-assigned this Jan 22, 2026

joostjager reviewed Jan 23, 2026

View reviewed changes

TheBlueMatt force-pushed the 2025-01-phantom-bolt12 branch 2 times, most recently from 736cab5 to 5ef29ff Compare January 26, 2026 23:10

TheBlueMatt requested a review from joostjager January 27, 2026 12:17

joostjager previously approved these changes Jan 27, 2026

View reviewed changes

TheBlueMatt dismissed joostjager’s stale review via 6c4d335 January 27, 2026 20:17

ldk-reviews-bot requested a review from jkczyz January 27, 2026 20:18

TheBlueMatt added 2 commits February 3, 2026 14:09

TheBlueMatt force-pushed the 2025-01-phantom-bolt12 branch from 6c4d335 to 7ae896b Compare February 3, 2026 14:10

jkczyz reviewed Feb 3, 2026

View reviewed changes

TheBlueMatt added 8 commits February 5, 2026 12:43

f sp

14a2f6f

f use an enum

bd5088e

f fix fuzz

ff0fbf9

f new names

5bf55b1

f fix offset

1da6959

f cleanup test - make it a loop and remove old XXX

3b7c1e3

TheBlueMatt added 4 commits February 5, 2026 12:43

f add docs on channel_details_to_forward_nodes

ca74056

f sp

dc138af

f rebase

cece94a

f correct scid used

5a672bd

TheBlueMatt force-pushed the 2025-01-phantom-bolt12 branch from 7ae896b to 5a672bd Compare February 5, 2026 12:44

TheBlueMatt requested a review from jkczyz February 6, 2026 01:31

Conversation

TheBlueMatt commented Jan 22, 2026

Uh oh!

ldk-reviews-bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Jan 23, 2026

Uh oh!

codecov bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

joostjager left a comment

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Jan 27, 2026

Uh oh!

ldk-reviews-bot commented Jan 29, 2026

Uh oh!

ldk-reviews-bot commented Feb 2, 2026

Uh oh!

TheBlueMatt commented Feb 3, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Jan 22, 2026 •

edited

Loading

codecov bot commented Jan 27, 2026 •

edited

Loading