Allow users to provide custom TLVs through RecipientOnionFields

Custom TLVs allow users to send extra application-specific data with
a payment. These have the additional flexibility compared to
`payment_metadata` that they don't have to reflect recipient generated
data provided in an invoice, in which `payment_metadata` could be
reused.

We ensure provided type numbers are unique, increasing, and within the
experimental range with the `RecipientOnionFields::with_custom_tlvs`
method.

This begins sender-side support for custom TLVs.

Author: alecchendev

lightning-invoice/src/payment.rs

@@ -145,10 +145,8 @@ fn pay_invoice_using_amount<P: Deref>(
 	payer: P
 ) -> Result<(), PaymentError> where P::Target: Payer {
 	let payment_hash = PaymentHash((*invoice.payment_hash()).into_inner());
-	let recipient_onion = RecipientOnionFields {
-		payment_secret: Some(*invoice.payment_secret()),
-		payment_metadata: invoice.payment_metadata().map(|v| v.clone()),
-	};
+	let mut recipient_onion = RecipientOnionFields::secret_only(*invoice.payment_secret());
+	recipient_onion.payment_metadata = invoice.payment_metadata().map(|v| v.clone());
 	let mut payment_params = PaymentParameters::from_node_id(invoice.recover_payee_pub_key(),
 		invoice.min_final_cltv_expiry_delta() as u32)
 		.with_expiry_time(expiry_time_from_unix_epoch(invoice).as_secs())

lightning/src/ln/channelmanager.rs

@@ -3487,13 +3487,13 @@ where
 								let (cltv_expiry, onion_payload, payment_data, phantom_shared_secret, mut onion_fields) = match routing {
 									PendingHTLCRouting::Receive { payment_data, payment_metadata, incoming_cltv_expiry, phantom_shared_secret } => {
 										let _legacy_hop_data = Some(payment_data.clone());
-										let onion_fields =
-											RecipientOnionFields { payment_secret: Some(payment_data.payment_secret), payment_metadata };
+										let onion_fields = RecipientOnionFields { payment_secret: Some(payment_data.payment_secret),
+												payment_metadata, custom_tlvs: None };
 										(incoming_cltv_expiry, OnionPayload::Invoice { _legacy_hop_data },
 											Some(payment_data), phantom_shared_secret, onion_fields)
 									},
 									PendingHTLCRouting::ReceiveKeysend { payment_preimage, payment_metadata, incoming_cltv_expiry } => {
-										let onion_fields = RecipientOnionFields { payment_secret: None, payment_metadata };
+										let onion_fields = RecipientOnionFields { payment_secret: None, payment_metadata, custom_tlvs: None };
 										(incoming_cltv_expiry, OnionPayload::Spontaneous(payment_preimage),
 											None, None, onion_fields)
 									},

lightning/src/ln/outbound_payment.rs

@@ -431,10 +431,20 @@ pub struct RecipientOnionFields {
 	/// [`Self::payment_secret`] and while nearly all lightning senders support secrets, metadata
 	/// may not be supported as universally.
 	pub payment_metadata: Option<Vec<u8>>,
+	/// Custom TLVs allow sending extra application-specific data with a payment. They provide
+	/// additional flexibility on top of payment metadata, as while other implementations may
+	/// require payment metadata to reflect metadata provided in an invoice, custom TLVs
+	/// do not have this restriction.
+	///
+	/// Note that the if this field is `Some`, it will contain properly ordered TLVs, each
+	/// represented by a `(u64, Vec<u8>)` for its type number and serialized value respectively.
+	/// This is validated when setting this field using [`Self::with_custom_tlvs`].
+	pub(super) custom_tlvs: Option<Vec<(u64, Vec<u8>)>>,
 }
 
 impl_writeable_tlv_based!(RecipientOnionFields, {
 	(0, payment_secret, option),
+	(1, custom_tlvs, option),
 	(2, payment_metadata, option),
 });
 
@@ -443,7 +453,7 @@ impl RecipientOnionFields {
 	/// set of onion fields for today's BOLT11 invoices - most nodes require a [`PaymentSecret`]
 	/// but do not require or provide any further data.
 	pub fn secret_only(payment_secret: PaymentSecret) -> Self {
-		Self { payment_secret: Some(payment_secret), payment_metadata: None }
+		Self { payment_secret: Some(payment_secret), payment_metadata: None, custom_tlvs: None }
 	}
 
 	/// Creates a new [`RecipientOnionFields`] with no fields. This generally does not create
@@ -452,7 +462,25 @@ impl RecipientOnionFields {
 	///
 	/// [`ChannelManager::send_spontaneous_payment`]: super::channelmanager::ChannelManager::send_spontaneous_payment
 	pub fn spontaneous_empty() -> Self {
-		Self { payment_secret: None, payment_metadata: None }
+		Self { payment_secret: None, payment_metadata: None, custom_tlvs: None }
+	}
+
+	/// Creates a new [`RecipientOnionFields`], setting `custom_tlvs`. Each TLV is provided as a
+	/// `(u64, Vec<u8>)` for the type number and serialized value respectively. TLV type numbers
+	/// must be unique, in increasing order, and within the range reserved for custom types, i.e.
+	/// >= 2^16, otherwise this method will return `Err(())`.
+	pub fn with_custom_tlvs(mut self, custom_tlvs: Vec<(u64, Vec<u8>)>) -> Result<Self, ()> {
+		let mut prev_type = None;
+		for (typ, _) in custom_tlvs.iter() {
+			if *typ < 1 << 16 { return Err(()); }
+			match prev_type {
+				Some(prev) if prev >= *typ => return Err(()),
+				_ => {},
+			}
+			prev_type = Some(*typ);
+		}
+		self.custom_tlvs = Some(custom_tlvs);
+		Ok(self)
 	}
 
 	/// When we have received some HTLC(s) towards an MPP payment, as we receive further HTLC(s) we
@@ -765,6 +793,7 @@ impl OutboundPayments {
 							(*total_msat, RecipientOnionFields {
 									payment_secret: *payment_secret,
 									payment_metadata: payment_metadata.clone(),
+									custom_tlvs: None,
 								}, *keysend_preimage)
 						},
 						PendingOutboundPayment::Legacy { .. } => {
@@ -1444,6 +1473,23 @@ mod tests {
 
 	use alloc::collections::VecDeque;
 
+	#[test]
+	fn test_recipient_onion_fields_with_custom_tlvs() {
+		let onion_fields = RecipientOnionFields::spontaneous_empty();
+
+		let bad_type_range_tlvs = vec![
+			(0, vec![42]),
+			(1, vec![42; 32]),
+		];
+		assert!(onion_fields.clone().with_custom_tlvs(bad_type_range_tlvs).is_err());
+
+		let good_tlvs = vec![
+			((1 << 16) + 1, vec![42]),
+			((1 << 16) + 3, vec![42; 32]),
+		];
+		assert!(onion_fields.with_custom_tlvs(good_tlvs).is_ok());
+	}
+
 	#[test]
 	#[cfg(feature = "std")]
 	fn fails_paying_after_expiration() {

lightning/src/ln/payment_tests.rs

@@ -3050,7 +3050,7 @@ fn do_test_payment_metadata_consistency(do_reload: bool, do_modify: bool) {
 
 	// Send the MPP payment, delivering the updated commitment state to nodes[1].
 	nodes[0].node.send_payment(payment_hash, RecipientOnionFields {
-			payment_secret: Some(payment_secret), payment_metadata: Some(payment_metadata),
+			payment_secret: Some(payment_secret), payment_metadata: Some(payment_metadata), custom_tlvs: None,
 		}, payment_id, route_params.clone(), Retry::Attempts(1)).unwrap();
 	check_added_monitors!(nodes[0], 2);