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.

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.

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

I've assigned @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.

joostjager · 2026-01-23T07:33:16Z

lightning/src/crypto/streams.rs

 	pub readable: R,
-	pub used_aad: bool,
+	pub used_aad_a: bool,
+	pub used_aad_b: bool,


Both being true is never going to happen. Can you use a data type that has three possible values?

Can also consider using local and phantom here in the names, as this adapter isn't used for anything else.

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

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

lightning/src/ln/msgs.rs

 						}),
-					used_aad,
+					used_aad_a,
+					used_aad_b,


local/phantom in name?

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(),


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?

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

lightning/src/ln/offers_tests.rs

+
+#[test]
+fn creates_and_pays_for_phantom_offer() {
+	// XXX: share expanded key


XXX to be resolved

joostjager · 2026-01-23T08:04:16Z

lightning/src/ln/offers_tests.rs

+	expect_recent_payment!(&nodes[0], RecentPaymentDetails::Pending, payment_id);
+
+	claim_bolt12_payment(&nodes[0], &[&nodes[2]], payment_context, &invoice);
+	expect_recent_payment!(&nodes[0], RecentPaymentDetails::Fulfilled, payment_id);


Can the two payments happen in a loop to avoid duplication?

joostjager · 2026-01-23T08:07:19Z

lightning/src/ln/offers_tests.rs

+	claim_bolt12_payment(&nodes[0], &[&nodes[1]], payment_context, &invoice);
+	expect_recent_payment!(&nodes[0], RecentPaymentDetails::Fulfilled, payment_id);
+
+	// Then pay again via node C


Note that this is the critical part. Node C knows nothing about the offer, but is going to respond to the invoice request. Emphasize the cool part :)

joostjager · 2026-01-23T08:11:56Z

lightning/src/ln/channelmanager.rs

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


Wouldn't passing in MessageForwardNode directly create more flexibility?

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.

TheBlueMatt added 4 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

Uh oh!

TheBlueMatt commented Jan 22, 2026

Uh oh!

ldk-reviews-bot commented Jan 22, 2026 •

edited

Loading

Uh oh!

joostjager Jan 23, 2026

Uh oh!

joostjager Jan 23, 2026

Uh oh!

joostjager Jan 23, 2026

Uh oh!

joostjager Jan 23, 2026

Uh oh!

joostjager Jan 23, 2026

Uh oh!

joostjager Jan 23, 2026

Uh oh!

joostjager Jan 23, 2026

Uh oh!

joostjager Jan 23, 2026

Uh oh!

joostjager Jan 23, 2026

Uh oh!

joostjager Jan 23, 2026

Uh oh!

ldk-reviews-bot commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

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!

ldk-reviews-bot commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ldk-reviews-bot commented Jan 22, 2026 •

edited

Loading