Add custom TLV support to PendingOutboundPayment for Bolt12 flows

Bolt11 payments now allow attaching custom TLVs to the onion packet,
giving payers a way to pass metadata ranging from descriptions to
custom authentication. Bolt12 lacked an equivalent path, leaving its
outbound flow less extensible.

This commit adds a `custom_tlvs` field to the Bolt12-related
`PendingOutboundPayment` variants, bringing the internal Bolt12
payment state in line with the Bolt11 changes and preparing the
ground for user-facing API support.

A follow-up commit will expose a way for users to set these TLVs.

Author: shaavan

lightning/src/ln/channelmanager.rs

@@ -12874,7 +12874,8 @@ macro_rules! create_refund_builder { ($self: ident, $builder: ty) => {
 	/// [Avoiding Duplicate Payments]: #avoiding-duplicate-payments
 	pub fn create_refund_builder(
 		&$self, amount_msats: u64, absolute_expiry: Duration, payment_id: PaymentId,
-		retry_strategy: Retry, route_params_config: RouteParametersConfig
+		custom_tlvs: Vec<(u64, Vec<u8>)>, retry_strategy: Retry,
+		route_params_config: RouteParametersConfig
 	) -> Result<$builder, Bolt12SemanticError> {
 		let entropy = &*$self.entropy_source;
 
@@ -12888,7 +12889,7 @@ macro_rules! create_refund_builder { ($self: ident, $builder: ty) => {
 		let expiration = StaleExpiration::AbsoluteTimeout(absolute_expiry);
 		$self.pending_outbound_payments
 			.add_new_awaiting_invoice(
-				payment_id, expiration, retry_strategy, route_params_config, None,
+				payment_id, custom_tlvs, expiration, retry_strategy, route_params_config, None,
 			)
 			.map_err(|_| Bolt12SemanticError::DuplicatePaymentId)?;
 
@@ -12915,7 +12916,7 @@ macro_rules! create_refund_builder { ($self: ident, $builder: ty) => {
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 	pub fn create_refund_builder_using_router<ME: Deref>(
 		&$self, router: ME, amount_msats: u64, absolute_expiry: Duration, payment_id: PaymentId,
-		retry_strategy: Retry, route_params_config: RouteParametersConfig
+		custom_tlvs: Vec<(u64, Vec<u8>)>, retry_strategy: Retry, route_params_config: RouteParametersConfig
 	) -> Result<$builder, Bolt12SemanticError>
 	where
 		ME::Target: MessageRouter,
@@ -12932,7 +12933,7 @@ macro_rules! create_refund_builder { ($self: ident, $builder: ty) => {
 		let expiration = StaleExpiration::AbsoluteTimeout(absolute_expiry);
 		$self.pending_outbound_payments
 			.add_new_awaiting_invoice(
-				payment_id, expiration, retry_strategy, route_params_config, None,
+				payment_id, custom_tlvs, expiration, retry_strategy, route_params_config, None,
 			)
 			.map_err(|_| Bolt12SemanticError::DuplicatePaymentId)?;
 
@@ -13054,6 +13055,7 @@ where
 			self.pending_outbound_payments
 				.add_new_awaiting_invoice(
 					payment_id,
+					vec![],
 					StaleExpiration::TimerTicks(1),
 					optional_params.retry_strategy,
 					optional_params.route_params_config,
@@ -13083,6 +13085,7 @@ where
 			self.pending_outbound_payments
 				.add_new_awaiting_invoice(
 					payment_id,
+					vec![],
 					StaleExpiration::TimerTicks(1),
 					optional_params.retry_strategy,
 					optional_params.route_params_config,
@@ -13125,6 +13128,7 @@ where
 			self.pending_outbound_payments
 				.add_new_awaiting_invoice(
 					payment_id,
+					vec![],
 					StaleExpiration::TimerTicks(1),
 					optional_params.retry_strategy,
 					optional_params.route_params_config,
@@ -15778,7 +15782,7 @@ where
 						self.pay_for_offer_intern(&offer, None, Some(amt_msats), payer_note, payment_id, Some(name),
 							|retryable_invoice_request| {
 								self.pending_outbound_payments
-									.received_offer(payment_id, Some(retryable_invoice_request))
+									.received_offer(payment_id, vec![], Some(retryable_invoice_request))
 									.map_err(|_| Bolt12SemanticError::DuplicatePaymentId)
 						});
 					if offer_pay_res.is_err() {

lightning/src/ln/outbound_payment.rs

@@ -82,6 +82,7 @@ pub(crate) enum PendingOutboundPayment {
 		retry_strategy: Retry,
 		route_params_config: RouteParametersConfig,
 		retryable_invoice_request: Option<RetryableInvoiceRequest>,
+		custom_tlvs: Vec<(u64, Vec<u8>)>,
 	},
 	// Represents the state after the invoice has been received, transitioning from the corresponding
 	// `AwaitingInvoice` state.
@@ -93,6 +94,7 @@ pub(crate) enum PendingOutboundPayment {
 		// race conditions where this field might be missing upon reload. It may be required
 		// for future retries.
 		route_params_config: RouteParametersConfig,
+		custom_tlvs: Vec<(u64, Vec<u8>)>,
 	},
 	// This state applies when we are paying an often-offline recipient and another node on the
 	// network served us a static invoice on the recipient's behalf in response to our invoice
@@ -986,7 +988,7 @@ where
 		SP: Fn(SendAlongPathArgs) -> Result<(), APIError>,
 	{
 
-		let (payment_hash, retry_strategy, params_config, _) = self
+		let (payment_hash, retry_strategy, params_config, custom_tlvs, _) = self
 			.mark_invoice_received_and_get_details(invoice, payment_id)?;
 
 		if invoice.invoice_features().requires_unknown_bits_from(&features) {
@@ -1004,10 +1006,16 @@ where
 			route_params.max_total_routing_fee_msat = Some(max_fee_msat);
 		}
 		let invoice = PaidBolt12Invoice::Bolt12Invoice(invoice.clone());
+
+		let recipient_onion = RecipientOnionFields::spontaneous_empty()
+			.with_custom_tlvs(custom_tlvs)
+			.map_err(|_| Bolt12PaymentError::SendingFailed(RetryableSendFailure::InvalidCustomTlvs))?;
+
 		self.send_payment_for_bolt12_invoice_internal(
-			payment_id, payment_hash, None, None, invoice, route_params, retry_strategy, false, router,
-			first_hops, inflight_htlcs, entropy_source, node_signer, node_id_lookup, secp_ctx,
-			best_block_height, pending_events, send_payment_along_path
+			payment_id, payment_hash, None, None, invoice, recipient_onion,
+			route_params, retry_strategy, false, router, first_hops, inflight_htlcs,
+			entropy_source, node_signer, node_id_lookup, secp_ctx, best_block_height, pending_events,
+			send_payment_along_path
 		)
 	}
 
@@ -1017,7 +1025,7 @@ where
 	>(
 		&self, payment_id: PaymentId, payment_hash: PaymentHash,
 		keysend_preimage: Option<PaymentPreimage>, invoice_request: Option<&InvoiceRequest>,
-		bolt12_invoice: PaidBolt12Invoice,
+		bolt12_invoice: PaidBolt12Invoice, recipient_onion: RecipientOnionFields,
 		mut route_params: RouteParameters, retry_strategy: Retry, hold_htlcs_at_next_hop: bool, router: &R,
 		first_hops: Vec<ChannelDetails>, inflight_htlcs: IH, entropy_source: &ES, node_signer: &NS,
 		node_id_lookup: &NL, secp_ctx: &Secp256k1<secp256k1::All>, best_block_height: u32,
@@ -1050,11 +1058,6 @@ where
 			}
 		}
 
-		let recipient_onion = RecipientOnionFields {
-			payment_secret: None,
-			payment_metadata: None,
-			custom_tlvs: vec![],
-		};
 		let route = match self.find_initial_route(
 			payment_id, payment_hash, &recipient_onion, keysend_preimage, invoice_request,
 			&mut route_params, router, &first_hops, &inflight_htlcs, node_signer, best_block_height,
@@ -1289,13 +1292,16 @@ where
 			retry_strategy = Retry::Attempts(0);
 		}
 
+		let recipient_onion = RecipientOnionFields::spontaneous_empty();
+
 		let invoice = PaidBolt12Invoice::StaticInvoice(invoice);
 		self.send_payment_for_bolt12_invoice_internal(
 			payment_id,
 			payment_hash,
 			Some(keysend_preimage),
 			Some(&invoice_request),
 			invoice,
+			recipient_onion,
 			route_params,
 			retry_strategy,
 			hold_htlcs_at_next_hop,
@@ -1980,7 +1986,8 @@ where
 	#[cfg(feature = "dnssec")]
 	#[rustfmt::skip]
 	pub(super) fn received_offer(
-		&self, payment_id: PaymentId, retryable_invoice_request: Option<RetryableInvoiceRequest>,
+		&self, payment_id: PaymentId, custom_tlvs: Vec<(u64, Vec<u8>)>,
+		retryable_invoice_request: Option<RetryableInvoiceRequest>,
 	) -> Result<(), ()> {
 		match self.pending_outbound_payments.lock().unwrap().entry(payment_id) {
 			hash_map::Entry::Occupied(entry) => match entry.get() {
@@ -1992,6 +1999,7 @@ where
 						retry_strategy: *retry_strategy,
 						route_params_config: *route_params_config,
 						retryable_invoice_request,
+						custom_tlvs,
 					};
 					core::mem::swap(&mut new_val, entry.into_mut());
 					Ok(())
@@ -2003,7 +2011,8 @@ where
 	}
 
 	pub(super) fn add_new_awaiting_invoice(
-		&self, payment_id: PaymentId, expiration: StaleExpiration, retry_strategy: Retry,
+		&self, payment_id: PaymentId, custom_tlvs: Vec<(u64, Vec<u8>)>,
+		expiration: StaleExpiration, retry_strategy: Retry,
 		route_params_config: RouteParametersConfig,
 		retryable_invoice_request: Option<RetryableInvoiceRequest>,
 	) -> Result<(), ()> {
@@ -2019,6 +2028,7 @@ where
 					retry_strategy,
 					route_params_config,
 					retryable_invoice_request,
+					custom_tlvs,
 				});
 
 				Ok(())
@@ -2031,7 +2041,7 @@ where
 		&self, invoice: &Bolt12Invoice, payment_id: PaymentId
 	) -> Result<(), Bolt12PaymentError> {
 		self.mark_invoice_received_and_get_details(invoice, payment_id)
-			.and_then(|(_, _, _, is_newly_marked)| {
+			.and_then(|(_, _, _, _, is_newly_marked)| {
 				is_newly_marked
 					.then_some(())
 					.ok_or(Bolt12PaymentError::DuplicateInvoice)
@@ -2040,32 +2050,34 @@ where
 
 	#[rustfmt::skip]
 	fn mark_invoice_received_and_get_details(
-		&self, invoice: &Bolt12Invoice, payment_id: PaymentId
-	) -> Result<(PaymentHash, Retry, RouteParametersConfig, bool), Bolt12PaymentError> {
+		&self, invoice: &Bolt12Invoice, payment_id: PaymentId,
+	) -> Result<(PaymentHash, Retry, RouteParametersConfig, Vec<(u64, Vec<u8>)>, bool), Bolt12PaymentError> {
 		match self.pending_outbound_payments.lock().unwrap().entry(payment_id) {
-			hash_map::Entry::Occupied(entry) => match entry.get() {
+			hash_map::Entry::Occupied(mut entry) => match entry.get_mut() {
 				PendingOutboundPayment::AwaitingInvoice {
-					retry_strategy: retry, route_params_config, ..
+					retry_strategy: retry, route_params_config, custom_tlvs, ..
 				} => {
 					let payment_hash = invoice.payment_hash();
 					let retry = *retry;
 					let config = *route_params_config;
-					*entry.into_mut() = PendingOutboundPayment::InvoiceReceived {
+					let custom = core::mem::take(custom_tlvs);
+					*entry.get_mut() = PendingOutboundPayment::InvoiceReceived {
 						payment_hash,
 						retry_strategy: retry,
 						route_params_config: config,
+						custom_tlvs: custom.clone(),
 					};
 
-					Ok((payment_hash, retry, config, true))
+					Ok((payment_hash, retry, config, custom, true))
 				},
 				// When manual invoice handling is enabled, the corresponding `PendingOutboundPayment` entry
 				// is already updated at the time the invoice is received. This ensures that `InvoiceReceived`
 				// event generation remains idempotent, even if the same invoice is received again before the
 				// event is handled by the user.
 				PendingOutboundPayment::InvoiceReceived {
-					retry_strategy, route_params_config, ..
+					retry_strategy, route_params_config, custom_tlvs, ..
 				} => {
-					Ok((invoice.payment_hash(), *retry_strategy, *route_params_config, false))
+					Ok((invoice.payment_hash(), *retry_strategy, *route_params_config, custom_tlvs.clone(), false))
 				},
 				_ => Err(Bolt12PaymentError::DuplicateInvoice),
 			},
@@ -2757,6 +2769,7 @@ impl_writeable_tlv_based_enum_upgradable!(PendingOutboundPayment,
 				|fee_msat| RouteParametersConfig::default().with_max_total_routing_fee_msat(fee_msat)
 			)
 		))),
+		(9, custom_tlvs, optional_vec),
 	},
 	(7, InvoiceReceived) => {
 		(0, payment_hash, required),
@@ -2773,6 +2786,7 @@ impl_writeable_tlv_based_enum_upgradable!(PendingOutboundPayment,
 				|fee_msat| RouteParametersConfig::default().with_max_total_routing_fee_msat(fee_msat)
 			)
 		))),
+		(7, custom_tlvs, optional_vec),
 	},
 	// Added in 0.1. Prior versions will drop these outbounds on downgrade, which is safe because no
 	// HTLCs are in-flight.
@@ -3053,7 +3067,7 @@ mod tests {
 		assert!(!outbound_payments.has_pending_payments());
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
+				payment_id, vec![], expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
 			).is_ok()
 		);
 		assert!(outbound_payments.has_pending_payments());
@@ -3083,14 +3097,14 @@ mod tests {
 
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
+				payment_id, vec![], expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
 			).is_ok()
 		);
 		assert!(outbound_payments.has_pending_payments());
 
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
+				payment_id, vec![], expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
 			).is_err()
 		);
 	}
@@ -3108,7 +3122,7 @@ mod tests {
 		assert!(!outbound_payments.has_pending_payments());
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
+				payment_id, vec![], expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
 			).is_ok()
 		);
 		assert!(outbound_payments.has_pending_payments());
@@ -3138,14 +3152,14 @@ mod tests {
 
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
+				payment_id, vec![], expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
 			).is_ok()
 		);
 		assert!(outbound_payments.has_pending_payments());
 
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
+				payment_id, vec![], expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
 			).is_err()
 		);
 	}
@@ -3162,7 +3176,7 @@ mod tests {
 		assert!(!outbound_payments.has_pending_payments());
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
+				payment_id, vec![], expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
 			).is_ok()
 		);
 		assert!(outbound_payments.has_pending_payments());
@@ -3201,7 +3215,7 @@ mod tests {
 
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
+				payment_id, vec![], expiration, Retry::Attempts(0), RouteParametersConfig::default(), None,
 			).is_ok()
 		);
 		assert!(outbound_payments.has_pending_payments());
@@ -3267,7 +3281,7 @@ mod tests {
 
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0),
+				payment_id, vec![], expiration, Retry::Attempts(0),
 				route_params_config, None,
 			).is_ok()
 		);
@@ -3370,7 +3384,7 @@ mod tests {
 
 		assert!(
 			outbound_payments.add_new_awaiting_invoice(
-				payment_id, expiration, Retry::Attempts(0), route_params_config, None,
+				payment_id, vec![], expiration, Retry::Attempts(0), route_params_config, None,
 			).is_ok()
 		);
 		assert!(outbound_payments.has_pending_payments());