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.

Because a lightning implementation may fail receiving a payment due to
not being able to deserialize an onion payload's TLV stream, we also
only allow a user to add custom TLVs if they provide a valid TLV stream
using `RecipientOnionFields::with_custom_tlvs`.

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

@@ -13,10 +13,12 @@ use bitcoin::hashes::Hash;
 use bitcoin::hashes::sha256::Hash as Sha256;
 use bitcoin::secp256k1::{self, Secp256k1, SecretKey};
 
+use crate::offers::TlvStream;
 use crate::sign::{EntropySource, NodeSigner, Recipient};
 use crate::events::{self, PaymentFailureReason};
 use crate::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
 use crate::ln::channelmanager::{ChannelDetails, EventCompletionAction, HTLCSource, IDEMPOTENCY_TIMEOUT_TICKS, PaymentId};
+use crate::ln::msgs::DecodeError;
 use crate::ln::onion_utils::HTLCFailReason;
 use crate::routing::router::{InFlightHtlcs, Path, PaymentParameters, Route, RouteParameters, Router};
 use crate::util::errors::APIError;
@@ -431,10 +433,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 a properly serialized TLV stream,
+	/// otherwise we will fail to serialize and send the payment. This can be easily done using
+	/// [`encode_tlv_stream`], and is validated with [`Self::with_custom_tlvs`].
+	pub(super) custom_tlvs: Option<Vec<u8>>,
 }
 
 impl_writeable_tlv_based!(RecipientOnionFields, {
 	(0, payment_secret, option),
+	(1, custom_tlvs, option),
 	(2, payment_metadata, option),
 });
 
@@ -443,7 +455,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 +464,20 @@ 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`], settting `custom_tlvs` if the provided bytes can
+	/// deserialized properly into TLVs, otherwise returns the error faced while decoding. This
+	/// will also reject TLVs with type numbers outside the range reserved for custom types, i.e.
+	/// <2^16.
+	pub fn with_custom_tlvs(mut self, custom_tlvs: Vec<u8>) -> Result<Self, DecodeError> {
+		let tlv_stream = TlvStream::try_new(&custom_tlvs)?;
+		for tlv in tlv_stream.into_iter() {
+			if tlv.get_type() < 1 << 16 { return Err(DecodeError::InvalidValue); }
+		}
+		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 +790,7 @@ impl OutboundPayments {
 							(*total_msat, RecipientOnionFields {
 									payment_secret: *payment_secret,
 									payment_metadata: payment_metadata.clone(),
+									custom_tlvs: None,
 								}, *keysend_preimage)
 						},
 						PendingOutboundPayment::Legacy { .. } => {
@@ -1444,6 +1470,26 @@ mod tests {
 
 	use alloc::collections::VecDeque;
 
+	#[test]
+	fn test_recipient_onion_fields_with_custom_tlvs() {
+		let onion_fields = RecipientOnionFields::spontaneous_empty();
+
+		let bad_tlvs = vec![42; 32];
+		assert!(onion_fields.clone().with_custom_tlvs(bad_tlvs).is_err());
+
+		let bad_type_range_tlvs = _get_encoded_tlv_stream!({
+			(0, 42, required),
+			(1, Some(vec![42; 32]), option),
+		});
+		assert!(onion_fields.clone().with_custom_tlvs(bad_type_range_tlvs).is_err());
+
+		let good_tlvs = _get_encoded_tlv_stream!({
+			((1 << 16) + 1, 42, required),
+			((1 << 16) + 3, Some(vec![42; 32]), option),
+		});
+		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);
 

lightning/src/offers/merkle.rs

@@ -13,6 +13,7 @@ use bitcoin::hashes::{Hash, HashEngine, sha256};
 use bitcoin::secp256k1::{Message, PublicKey, Secp256k1, self};
 use bitcoin::secp256k1::schnorr::Signature;
 use crate::io;
+use crate::ln::msgs::DecodeError;
 use crate::util::ser::{BigSize, Readable, Writeable, Writer};
 
 use crate::prelude::*;
@@ -155,6 +156,23 @@ impl<'a> TlvStream<'a> {
 		}
 	}
 
+	/// Checks if `data` is a valid TLV stream before returning a new [`TlvStream`].
+	pub fn try_new(data: &'a [u8]) -> Result<Self, DecodeError> {
+		let mut cursor = io::Cursor::new(data);
+		let len = cursor.get_ref().len() as u64;
+		while cursor.position() < len {
+			<BigSize as Readable>::read(&mut cursor)?;
+			let length = <BigSize as Readable>::read(&mut cursor)?.0;
+			let offset = cursor.position();
+			cursor.set_position(offset + length);
+		}
+		if cursor.position() > len {
+			Err(DecodeError::ShortRead)
+		} else {
+			Ok(Self::new(data))
+		}
+	}
+
 	pub fn range<T>(self, types: T) -> impl core::iter::Iterator<Item = TlvRecord<'a>>
 	where
 		T: core::ops::RangeBounds<u64> + Clone,