Add support for "phantom" BOLT 12 offers, up to the invoice_request step #4335

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.

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.

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.

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

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

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

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.

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.

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

Codecov Report

❌ Patch coverage is 94.05405% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.08%. Comparing base (7785360) to head (6c4d335).
⚠️ Report is 17 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.59%	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.53%   86.08%   -0.45%     
==========================================
  Files         158      156       -2     
  Lines      103188   102554     -634     
  Branches   103188   102554     -634     
==========================================
- Hits        89292    88287    -1005     
- Misses      11471    11772     +301     
- Partials     2425     2495      +70

Flag	Coverage Δ
fuzzing	`?`
tests	`86.08% <94.05%> (+0.26%)`	⬆️

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

TheBlueMatt added 3 commits January 22, 2026 12:16

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

f use an enum

2d92f16

TheBlueMatt force-pushed the 2025-01-phantom-bolt12 branch from 8bbc7b1 to 736cab5 Compare January 26, 2026 21:09

TheBlueMatt added 4 commits January 26, 2026 23:10

f fix fuzz

73a0ba6

f fix offset

9c6c534

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

5ef29ff

TheBlueMatt force-pushed the 2025-01-phantom-bolt12 branch 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

f add docs on channel_details_to_forward_nodes

6c4d335

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

Add support for "phantom" BOLT 12 offers, up to the invoice_request step #4335

Are you sure you want to change the base?

Add support for "phantom" BOLT 12 offers, up to the invoice_request step #4335

Uh oh!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ldk-reviews-bot commented Jan 22, 2026 •

edited

Loading

codecov bot commented Jan 27, 2026 •

edited

Loading