Add a payment_metadata map in blinded payment path contexts

Similar to how BOLT 11 payments can use a `payment_metadata` to
provide arbitrary bytes in the invoice to be communicated back to
them when receiving, its useful to be able to provide some bytes
which are communicated back upon receiving a payment.

Here we do so in the BOLT 12 blinded path contexts, offering a
`BTreeMap<u64, Vec<u8>>` instead to enable more easily including
multiple sets of data.

Also note that a `Router` building a blinded path is allowed to
modify the `payment_metadata` without breaking the payment.

Tests by claude

Author: TheBlueMatt

fuzz/src/invoice_request_deser.rs

@@ -104,6 +104,7 @@ fn build_response<T: secp256k1::Signing + secp256k1::Verification>(
 	let payment_context = PaymentContext::Bolt12Offer(Bolt12OfferContext {
 		offer_id: OfferId([42; 32]),
 		invoice_request: invoice_request_fields,
+		payment_metadata: None,
 	});
 	let payee_tlvs = ReceiveTlvs {
 		payment_secret: PaymentSecret([42; 32]),

fuzz/src/refund_deser.rs

@@ -69,7 +69,8 @@ fn build_response<T: secp256k1::Signing + secp256k1::Verification>(
 ) -> Result<UnsignedBolt12Invoice, Bolt12SemanticError> {
 	let entropy_source = Randomness {};
 	let receive_auth_key = ReceiveAuthKey([41; 32]);
-	let payment_context = PaymentContext::Bolt12Refund(Bolt12RefundContext {});
+	let payment_context =
+		PaymentContext::Bolt12Refund(Bolt12RefundContext { payment_metadata: None });
 	let payee_tlvs = ReceiveTlvs {
 		payment_secret: PaymentSecret([42; 32]),
 		payment_constraints: PaymentConstraints {

lightning/src/blinded_path/payment.rs

@@ -9,6 +9,8 @@
 
 //! Data structures and methods for constructing [`BlindedPaymentPath`]s to send a payment over.
 
+use alloc::collections::BTreeMap;
+
 use bitcoin::secp256k1::ecdh::SharedSecret;
 use bitcoin::secp256k1::{self, PublicKey, Secp256k1, SecretKey};
 
@@ -29,8 +31,8 @@ use crate::types::features::BlindedHopFeatures;
 use crate::types::payment::PaymentSecret;
 use crate::types::routing::RoutingFees;
 use crate::util::ser::{
-	FixedLengthReader, HighZeroBytesDroppedBigSize, LengthReadableArgs, Readable, WithoutLength,
-	Writeable, Writer,
+	BigSizeKeyedMap, FixedLengthReader, HighZeroBytesDroppedBigSize, LengthReadableArgs, Readable,
+	WithoutLength, Writeable, Writer,
 };
 
 #[allow(unused_imports)]
@@ -572,6 +574,20 @@ pub enum PaymentContext {
 	/// [`Refund`]: crate::offers::refund::Refund
 	Bolt12Refund(Bolt12RefundContext),
 }
+impl PaymentContext {
+	/// Returns the additional payment metadata stored alongside this payment context, if any.
+	///
+	/// Payment metadata is stored as a map from a numeric key to an arbitrary byte array value.
+	/// This allows for several types of metadata to be stored attached to a single payment. In the
+	/// future some optional features of LDK may use some keys.
+	pub fn payment_metadata(&self) -> Option<&BTreeMap<u64, Vec<u8>>> {
+		match self {
+			Self::Bolt12Offer(Bolt12OfferContext { payment_metadata, .. })
+			| Self::AsyncBolt12Offer(AsyncBolt12OfferContext { payment_metadata, .. })
+			| Self::Bolt12Refund(Bolt12RefundContext { payment_metadata, .. }) => payment_metadata.as_ref(),
+		}
+	}
+}
 
 // Used when writing PaymentContext in Event::PaymentClaimable to avoid cloning.
 pub(crate) enum PaymentContextRef<'a> {
@@ -594,6 +610,27 @@ pub struct Bolt12OfferContext {
 	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 	pub invoice_request: InvoiceRequestFields,
+
+	/// Additional data about this payment which is not used in LDK and can be used for any
+	/// purpose.
+	///
+	/// This is analogous to the BOLT 11 [`RecipientOnionFields::payment_metadata`] (which is
+	/// provided to payers via [`Bolt11Invoice::payment_metadata`]) and can be used any time data
+	/// needs to be "stored" by a payment recipient for their own internal use, provided back to
+	/// them with the payment.
+	///
+	/// Payment metadata is stored as a map from a numeric key to an arbitrary byte array value.
+	/// This allows for several types of metadata to be stored attached to a single payment. In the
+	/// future some optional features of LDK may use some keys. For the sake of conflict
+	/// reduction, those features will attempt to use keys in the range 128-256.
+	///
+	/// Note that because this is included in the payment onion, its size must be tightly
+	/// constrained. More than a few hundred bytes and the payment will be entirely unpayable (with
+	/// limited routing options as size increases).
+	///
+	/// [`RecipientOnionFields::payment_metadata`]: crate::ln::outbound_payment::RecipientOnionFields::payment_metadata
+	/// [`Bolt11Invoice::payment_metadata`]: lightning_invoice::Bolt11Invoice::payment_metadata
+	pub payment_metadata: Option<BTreeMap<u64, Vec<u8>>>,
 }
 
 /// The context of a payment made for a static invoice requested from a BOLT 12 [`Offer`].
@@ -606,13 +643,55 @@ pub struct AsyncBolt12OfferContext {
 	///
 	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 	pub offer_nonce: Nonce,
+
+	/// Additional data about this payment which is not used in LDK and can be used for any
+	/// purpose.
+	///
+	/// This is analogous to the BOLT 11 [`RecipientOnionFields::payment_metadata`] (which is
+	/// provided to payers via [`Bolt11Invoice::payment_metadata`]) and can be used any time data
+	/// needs to be "stored" by a payment recipient for their own internal use, provided back to
+	/// them with the payment.
+	///
+	/// Payment metadata is stored as a map from a numeric key to an arbitrary byte array value.
+	/// This allows for several types of metadata to be stored attached to a single payment. In the
+	/// future some optional features of LDK may use some keys. For the sake of conflict
+	/// reduction, those features will attempt to use keys in the range 128-256.
+	///
+	/// Note that because this is included in the payment onion, its size must be tightly
+	/// constrained. More than a few hundred bytes and the payment will be entirely unpayable (with
+	/// limited routing options as size increases).
+	///
+	/// [`RecipientOnionFields::payment_metadata`]: crate::ln::outbound_payment::RecipientOnionFields::payment_metadata
+	/// [`Bolt11Invoice::payment_metadata`]: lightning_invoice::Bolt11Invoice::payment_metadata
+	pub payment_metadata: Option<BTreeMap<u64, Vec<u8>>>,
 }
 
 /// The context of a payment made for an invoice sent for a BOLT 12 [`Refund`].
 ///
 /// [`Refund`]: crate::offers::refund::Refund
 #[derive(Clone, Debug, Eq, PartialEq)]
-pub struct Bolt12RefundContext {}
+pub struct Bolt12RefundContext {
+	/// Additional data about this payment which is not used in LDK and can be used for any
+	/// purpose.
+	///
+	/// This is analogous to the BOLT 11 [`RecipientOnionFields::payment_metadata`] (which is
+	/// provided to payers via [`Bolt11Invoice::payment_metadata`]) and can be used any time data
+	/// needs to be "stored" by a payment recipient for their own internal use, provided back to
+	/// them with the payment.
+	///
+	/// Payment metadata is stored as a map from a numeric key to an arbitrary byte array value.
+	/// This allows for several types of metadata to be stored attached to a single payment. In the
+	/// future some optional features of LDK may use some keys. For the sake of conflict
+	/// reduction, those features will attempt to use keys in the range 128-256.
+	///
+	/// Note that because this is included in the payment onion, its size must be tightly
+	/// constrained. More than a few hundred bytes and the payment will be entirely unpayable (with
+	/// limited routing options as size increases).
+	///
+	/// [`RecipientOnionFields::payment_metadata`]: crate::ln::outbound_payment::RecipientOnionFields::payment_metadata
+	/// [`Bolt11Invoice::payment_metadata`]: lightning_invoice::Bolt11Invoice::payment_metadata
+	pub payment_metadata: Option<BTreeMap<u64, Vec<u8>>>,
+}
 
 impl TryFrom<CounterpartyForwardingInfo> for PaymentRelay {
 	type Error = ();
@@ -1031,14 +1110,18 @@ impl<'a> Writeable for PaymentContextRef<'a> {
 
 impl_writeable_tlv_based!(Bolt12OfferContext, {
 	(0, offer_id, required),
+	(1, payment_metadata, (option, encoding: (BTreeMap<u64, Vec<u8>>, BigSizeKeyedMap))),
 	(2, invoice_request, required),
 });
 
 impl_writeable_tlv_based!(AsyncBolt12OfferContext, {
 	(0, offer_nonce, required),
+	(1, payment_metadata, (option, encoding: (BTreeMap<u64, Vec<u8>>, BigSizeKeyedMap))),
 });
 
-impl_writeable_tlv_based!(Bolt12RefundContext, {});
+impl_writeable_tlv_based!(Bolt12RefundContext, {
+	(1, payment_metadata, (option, encoding: (BTreeMap<u64, Vec<u8>>, BigSizeKeyedMap))),
+});
 
 #[cfg(test)]
 mod tests {
@@ -1097,7 +1180,9 @@ mod tests {
 		let recv_tlvs = ReceiveTlvs {
 			payment_secret: PaymentSecret([0; 32]),
 			payment_constraints: PaymentConstraints { max_cltv_expiry: 0, htlc_minimum_msat: 1 },
-			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
+			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {
+				payment_metadata: None,
+			}),
 		};
 		let htlc_maximum_msat = 100_000;
 		let blinded_payinfo =
@@ -1115,7 +1200,9 @@ mod tests {
 		let recv_tlvs = ReceiveTlvs {
 			payment_secret: PaymentSecret([0; 32]),
 			payment_constraints: PaymentConstraints { max_cltv_expiry: 0, htlc_minimum_msat: 1 },
-			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
+			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {
+				payment_metadata: None,
+			}),
 		};
 		let blinded_payinfo = super::compute_payinfo::<ForwardTlvs>(
 			&[],
@@ -1178,7 +1265,9 @@ mod tests {
 		let recv_tlvs = ReceiveTlvs {
 			payment_secret: PaymentSecret([0; 32]),
 			payment_constraints: PaymentConstraints { max_cltv_expiry: 0, htlc_minimum_msat: 3 },
-			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
+			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {
+				payment_metadata: None,
+			}),
 		};
 		let htlc_maximum_msat = 100_000;
 		let blinded_payinfo = super::compute_payinfo(
@@ -1238,7 +1327,9 @@ mod tests {
 		let recv_tlvs = ReceiveTlvs {
 			payment_secret: PaymentSecret([0; 32]),
 			payment_constraints: PaymentConstraints { max_cltv_expiry: 0, htlc_minimum_msat: 1 },
-			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
+			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {
+				payment_metadata: None,
+			}),
 		};
 		let htlc_minimum_msat = 3798;
 		assert!(super::compute_payinfo(
@@ -1309,7 +1400,9 @@ mod tests {
 		let recv_tlvs = ReceiveTlvs {
 			payment_secret: PaymentSecret([0; 32]),
 			payment_constraints: PaymentConstraints { max_cltv_expiry: 0, htlc_minimum_msat: 1 },
-			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
+			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {
+				payment_metadata: None,
+			}),
 		};
 
 		let blinded_payinfo = super::compute_payinfo(

lightning/src/ln/async_payments_tests.rs

@@ -7,6 +7,8 @@
 // You may not use this file except in accordance with one or both of these
 // licenses.
 
+use alloc::collections::BTreeMap;
+
 use crate::blinded_path::message::{
 	BlindedMessagePath, MessageContext, NextMessageHop, OffersContext,
 };
@@ -299,6 +301,7 @@ fn create_static_invoice_builder<'a>(
 			relative_expiry_secs,
 			recipient.node.list_usable_channels(),
 			recipient.node.test_get_peers_for_blinded_path(),
+			None,
 		)
 		.unwrap()
 }
@@ -1150,6 +1153,88 @@ fn async_receive_flow_success() {
 	assert_eq!(res, Some(PaidBolt12Invoice::StaticInvoice(static_invoice)));
 }
 
+#[test]
+fn async_payment_delivers_payment_metadata() {
+	// Test that `payment_metadata` set in the `AsyncBolt12OfferContext` of a static invoice's
+	// blinded payment paths is surfaced via `Event::PaymentClaimable` when the async recipient
+	// receives the keysend payment.
+	let chanmon_cfgs = create_chanmon_cfgs(3);
+	let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
+
+	let mut allow_priv_chan_fwds_cfg = test_default_channel_config();
+	allow_priv_chan_fwds_cfg.accept_forwards_to_priv_channels = true;
+	let node_chanmgrs =
+		create_node_chanmgrs(3, &node_cfgs, &[None, Some(allow_priv_chan_fwds_cfg), None]);
+
+	let nodes = create_network(3, &node_cfgs, &node_chanmgrs);
+	create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0);
+	create_unannounced_chan_between_nodes_with_value(&nodes, 1, 2, 1_000_000, 0);
+
+	let recipient_id = vec![42; 32];
+	let inv_server_paths =
+		nodes[1].node.blinded_paths_for_async_recipient(recipient_id.clone(), None).unwrap();
+	nodes[2].node.set_paths_to_static_invoice_server(inv_server_paths).unwrap();
+	expect_offer_paths_requests(&nodes[2], &[&nodes[0], &nodes[1]]);
+
+	// Configure the recipient's router to inject `payment_metadata` into the
+	// `AsyncBolt12OfferContext` of the static invoice's blinded payment paths. The
+	// `pass_static_invoice_server_messages` flow below builds the static invoice via this router,
+	// at which point the override is consumed.
+	let mut expected_metadata = BTreeMap::new();
+	expected_metadata.insert(0u64, vec![1, 2, 3, 4]);
+	expected_metadata.insert(7u64, vec![0xab, 0xcd]);
+	nodes[2].router.set_next_payment_context_metadata(expected_metadata.clone());
+
+	let invoice_flow_res =
+		pass_static_invoice_server_messages(&nodes[1], &nodes[2], recipient_id.clone());
+	let static_invoice = invoice_flow_res.invoice;
+	let offer = nodes[2].node.get_async_receive_offer().unwrap();
+	let amt_msat = 5000;
+	let payment_id = PaymentId([1; 32]);
+	nodes[0].node.pay_for_offer(&offer, Some(amt_msat), payment_id, Default::default()).unwrap();
+	let release_held_htlc_om = pass_async_payments_oms(
+		static_invoice.clone(),
+		&nodes[0],
+		&nodes[1],
+		&nodes[2],
+		recipient_id,
+		invoice_flow_res.invoice_request_path,
+	)
+	.1;
+	nodes[0]
+		.onion_messenger
+		.handle_onion_message(nodes[2].node.get_our_node_id(), &release_held_htlc_om);
+
+	let mut events = nodes[0].node.get_and_clear_pending_msg_events();
+	assert_eq!(events.len(), 1);
+	let ev = remove_first_msg_event_to_node(&nodes[1].node.get_our_node_id(), &mut events);
+	let payment_hash = extract_payment_hash(&ev);
+	check_added_monitors(&nodes[0], 1);
+
+	let route: &[&[&Node]] = &[&[&nodes[1], &nodes[2]]];
+	let args = PassAlongPathArgs::new(&nodes[0], route[0], amt_msat, payment_hash, ev)
+		.with_dummy_tlvs(&[DummyTlvs::default(); DEFAULT_PAYMENT_DUMMY_HOPS]);
+	let claimable_ev = do_pass_along_path(args).unwrap();
+
+	// Verify the `payment_metadata` we injected is surfaced via the `Bolt12OfferContext` of
+	// the `PaymentPurpose`. The recipient converts `AsyncBolt12OfferContext` to
+	// `Bolt12OfferContext` when constructing the `PaymentPurpose` for keysend payments.
+	match &claimable_ev {
+		Event::PaymentClaimable {
+			purpose: PaymentPurpose::Bolt12OfferPayment { payment_context, .. },
+			..
+		} => {
+			assert_eq!(payment_context.payment_metadata.as_ref(), Some(&expected_metadata));
+		},
+		_ => panic!("Unexpected event: {:?}", claimable_ev),
+	}
+
+	let keysend_preimage = extract_payment_preimage(&claimable_ev);
+	let (res, _) =
+		claim_payment_along_route(ClaimAlongRouteArgs::new(&nodes[0], route, keysend_preimage));
+	assert_eq!(res, Some(PaidBolt12Invoice::StaticInvoice(static_invoice)));
+}
+
 #[cfg_attr(feature = "std", ignore)]
 #[test]
 fn expired_static_invoice_fail() {
@@ -1591,6 +1676,7 @@ fn reject_bad_payment_secret() {
 						PaymentContext::AsyncBolt12Offer(AsyncBolt12OfferContext {
 							// We don't reach the point of checking the invreq nonce due to the invalid payment secret
 							offer_nonce: Nonce([i; Nonce::LENGTH]),
+							payment_metadata: None,
 						}),
 						u32::MAX,
 					)
@@ -3123,7 +3209,10 @@ fn intercepted_hold_htlc() {
 	.unwrap();
 	let mut offer_nonce = Nonce([0; Nonce::LENGTH]);
 	offer_nonce.0.copy_from_slice(&hardcoded_random_bytes[..Nonce::LENGTH]);
-	let payment_context = PaymentContext::AsyncBolt12Offer(AsyncBolt12OfferContext { offer_nonce });
+	let payment_context = PaymentContext::AsyncBolt12Offer(AsyncBolt12OfferContext {
+		offer_nonce,
+		payment_metadata: None,
+	});
 	let blinded_payment_path_with_jit_channel_scid = recipient
 		.node
 		.flow