Distinguish Between Sender and User Custom TLVs

- This update introduces a clear separation between two types
  of custom TLVs: those sent by the sender for the user, and
  those added by the user to the reply path, which are expected
  to return with the response.
- This commit establishes this distinction in the codebase at
  relevant points.
- The next commit will build on this by providing an interface for
  users to add their own custom TLVs to the reply path, allowing
  them to receive specific data back in the response.

Note:
1. Similar to keysend, for serialization purposes, user_custom_tlv
   are assigned a specific TLV number.
2. For uniformity, user_custom_tlv are assigned the lowest possible
   odd number after (1 << 16), which is 65537.

Author: shaavan

lightning/src/ln/blinded_payment_tests.rs

@@ -1389,7 +1389,7 @@ fn custom_tlvs_to_blinded_path() {
 	);
 
 	let recipient_onion_fields = RecipientOnionFields::spontaneous_empty()
-		.with_custom_tlvs(vec![((1 << 16) + 1, vec![42, 42])])
+		.with_sender_custom_tlvs(vec![((1 << 16) + 3, vec![42, 42])])
 		.unwrap();
 	nodes[0].node.send_payment(payment_hash, recipient_onion_fields.clone(),
 		PaymentId(payment_hash.0), route_params, Retry::Attempts(0)).unwrap();
@@ -1402,11 +1402,11 @@ fn custom_tlvs_to_blinded_path() {
 	let path = &[&nodes[1]];
 	let args = PassAlongPathArgs::new(&nodes[0], path, amt_msat, payment_hash, ev)
 		.with_payment_secret(payment_secret)
-		.with_custom_tlvs(recipient_onion_fields.custom_tlvs.clone());
+		.with_sender_custom_tlvs(recipient_onion_fields.sender_custom_tlvs.clone());
 	do_pass_along_path(args);
 	claim_payment_along_route(
 		ClaimAlongRouteArgs::new(&nodes[0], &[&[&nodes[1]]], payment_preimage)
-			.with_custom_tlvs(recipient_onion_fields.custom_tlvs.clone())
+			.with_sender_custom_tlvs(recipient_onion_fields.sender_custom_tlvs.clone())
 	);
 }
 

lightning/src/ln/channelmanager.rs

@@ -193,8 +193,14 @@ pub enum PendingHTLCRouting {
 		///
 		/// For HTLCs received by LDK, this will ultimately be exposed in
 		/// [`Event::PaymentClaimable::onion_fields`] as
-		/// [`RecipientOnionFields::custom_tlvs`].
-		custom_tlvs: Vec<(u64, Vec<u8>)>,
+		/// [`RecipientOnionFields::sender_custom_tlvs`].
+		sender_custom_tlvs: Vec<(u64, Vec<u8>)>,
+		/// Custom TLVs set by the receiver in the blinded path used to reach them.
+		///
+		/// For HTLCs received by LDK, this will be exposed in
+		/// [`Event::PaymentClaimable::onion_fields`] as
+		/// [`RecipientOnionFields::user_custom_tlvs`].
+		user_custom_tlvs: Vec<u8>,
 		/// Set if this HTLC is the final hop in a multi-hop blinded path.
 		requires_blinded_error: bool,
 	},
@@ -223,8 +229,13 @@ pub enum PendingHTLCRouting {
 		/// Custom TLVs which were set by the sender.
 		///
 		/// For HTLCs received by LDK, these will ultimately bubble back up as
-		/// [`RecipientOnionFields::custom_tlvs`].
-		custom_tlvs: Vec<(u64, Vec<u8>)>,
+		/// [`RecipientOnionFields::sender_custom_tlvs`].
+		sender_custom_tlvs: Vec<(u64, Vec<u8>)>,
+		/// Custom TLVs set by the receiver in the blinded path used to reach them.
+		///
+		/// For HTLCs received by LDK, these will ultimately bubble back up as
+		/// [`RecipientOnionFields::user_custom_tlvs`].
+		user_custom_tlvs: Vec<u8>,
 		/// Set if this HTLC is the final hop in a multi-hop blinded path.
 		requires_blinded_error: bool,
 		/// Set if we are receiving a keysend to a blinded path, meaning we created the
@@ -939,10 +950,10 @@ impl ClaimablePayments {
 					}
 				}
 
-				if let Some(RecipientOnionFields { custom_tlvs, .. }) = &payment.onion_fields {
-					if !custom_tlvs_known && custom_tlvs.iter().any(|(typ, _)| typ % 2 == 0) {
+				if let Some(RecipientOnionFields { sender_custom_tlvs, .. }) = &payment.onion_fields {
+					if !custom_tlvs_known && sender_custom_tlvs.iter().any(|(typ, _)| typ % 2 == 0) {
 						log_info!(logger, "Rejecting payment with payment hash {} as we cannot accept payment with unknown even TLVs: {}",
-							&payment_hash, log_iter!(custom_tlvs.iter().map(|(typ, _)| typ).filter(|typ| *typ % 2 == 0)));
+							&payment_hash, log_iter!(sender_custom_tlvs.iter().map(|(typ, _)| typ).filter(|typ| *typ % 2 == 0)));
 						return Err(payment.htlcs);
 					}
 				}
@@ -6051,25 +6062,26 @@ where
 								) = match routing {
 									PendingHTLCRouting::Receive {
 										payment_data, payment_metadata, payment_context,
-										incoming_cltv_expiry, phantom_shared_secret, custom_tlvs,
+										incoming_cltv_expiry, phantom_shared_secret, sender_custom_tlvs, user_custom_tlvs,
 										requires_blinded_error: _
 									} => {
 										let _legacy_hop_data = Some(payment_data.clone());
 										let onion_fields = RecipientOnionFields { payment_secret: Some(payment_data.payment_secret),
-												payment_metadata, custom_tlvs };
+												payment_metadata, sender_custom_tlvs, user_custom_tlvs };
 										(incoming_cltv_expiry, OnionPayload::Invoice { _legacy_hop_data },
 											Some(payment_data), payment_context, phantom_shared_secret, onion_fields,
 											true)
 									},
 									PendingHTLCRouting::ReceiveKeysend {
 										payment_data, payment_preimage, payment_metadata,
-										incoming_cltv_expiry, custom_tlvs, requires_blinded_error: _,
+										incoming_cltv_expiry, sender_custom_tlvs, user_custom_tlvs, requires_blinded_error: _,
 										has_recipient_created_payment_secret,
 									} => {
 										let onion_fields = RecipientOnionFields {
 											payment_secret: payment_data.as_ref().map(|data| data.payment_secret),
 											payment_metadata,
-											custom_tlvs,
+											sender_custom_tlvs,
+											user_custom_tlvs,
 										};
 										(incoming_cltv_expiry, OnionPayload::Spontaneous(payment_preimage),
 											payment_data, None, None, onion_fields, has_recipient_created_payment_secret)
@@ -12385,18 +12397,20 @@ impl_writeable_tlv_based_enum!(PendingHTLCRouting,
 		(1, phantom_shared_secret, option),
 		(2, incoming_cltv_expiry, required),
 		(3, payment_metadata, option),
-		(5, custom_tlvs, optional_vec),
+		(5, sender_custom_tlvs, optional_vec),
 		(7, requires_blinded_error, (default_value, false)),
 		(9, payment_context, option),
+		(11, user_custom_tlvs, optional_vec),
 	},
 	(2, ReceiveKeysend) => {
 		(0, payment_preimage, required),
 		(1, requires_blinded_error, (default_value, false)),
 		(2, incoming_cltv_expiry, required),
 		(3, payment_metadata, option),
 		(4, payment_data, option), // Added in 0.0.116
-		(5, custom_tlvs, optional_vec),
+		(5, sender_custom_tlvs, optional_vec),
 		(7, has_recipient_created_payment_secret, (default_value, false)),
+		(9, user_custom_tlvs, optional_vec),
 	},
 );
 
@@ -15361,7 +15375,8 @@ mod tests {
 			payment_data: Some(msgs::FinalOnionHopData {
 				payment_secret: PaymentSecret([0; 32]), total_msat: sender_intended_amt_msat,
 			}),
-			custom_tlvs: Vec::new(),
+			sender_custom_tlvs: Vec::new(),
+			user_custom_tlvs: Vec::new(),
 		};
 		// Check that if the amount we received + the penultimate hop extra fee is less than the sender
 		// intended amount, we fail the payment.
@@ -15383,7 +15398,8 @@ mod tests {
 			payment_data: Some(msgs::FinalOnionHopData {
 				payment_secret: PaymentSecret([0; 32]), total_msat: sender_intended_amt_msat,
 			}),
-			custom_tlvs: Vec::new(),
+			sender_custom_tlvs: Vec::new(),
+			user_custom_tlvs: Vec::new(),
 		};
 		let current_height: u32 = node[0].node.best_block.read().unwrap().height;
 		assert!(create_recv_pending_htlc_info(hop_data, [0; 32], PaymentHash([0; 32]),
@@ -15407,7 +15423,8 @@ mod tests {
 			payment_data: Some(msgs::FinalOnionHopData {
 				payment_secret: PaymentSecret([0; 32]), total_msat: 100,
 			}),
-			custom_tlvs: Vec::new(),
+			sender_custom_tlvs: Vec::new(),
+			user_custom_tlvs: Vec::new(),
 		}, [0; 32], PaymentHash([0; 32]), 100, 23, None, true, None, current_height);
 
 		// Should not return an error as this condition:

lightning/src/ln/functional_test_utils.rs

@@ -2633,7 +2633,8 @@ pub struct PassAlongPathArgs<'a, 'b, 'c, 'd> {
 	pub clear_recipient_events: bool,
 	pub expected_preimage: Option<PaymentPreimage>,
 	pub is_probe: bool,
-	pub custom_tlvs: Vec<(u64, Vec<u8>)>,
+	pub sender_custom_tlvs: Vec<(u64, Vec<u8>)>,
+	pub user_custom_tlvs: Vec<u8>,
 	pub payment_metadata: Option<Vec<u8>>,
 	pub expected_failure: Option<HTLCDestination>,
 }
@@ -2646,7 +2647,7 @@ impl<'a, 'b, 'c, 'd> PassAlongPathArgs<'a, 'b, 'c, 'd> {
 		Self {
 			origin_node, expected_path, recv_value, payment_hash, payment_secret: None, event,
 			payment_claimable_expected: true, clear_recipient_events: true, expected_preimage: None,
-			is_probe: false, custom_tlvs: Vec::new(), payment_metadata: None, expected_failure: None,
+			is_probe: false, sender_custom_tlvs: Vec::new(), user_custom_tlvs: Vec::new(), payment_metadata: None, expected_failure: None,
 		}
 	}
 	pub fn without_clearing_recipient_events(mut self) -> Self {
@@ -2670,8 +2671,12 @@ impl<'a, 'b, 'c, 'd> PassAlongPathArgs<'a, 'b, 'c, 'd> {
 		self.expected_preimage = Some(payment_preimage);
 		self
 	}
-	pub fn with_custom_tlvs(mut self, custom_tlvs: Vec<(u64, Vec<u8>)>) -> Self {
-		self.custom_tlvs = custom_tlvs;
+	pub fn with_sender_custom_tlvs(mut self, custom_tlvs: Vec<(u64, Vec<u8>)>) -> Self {
+		self.sender_custom_tlvs = custom_tlvs;
+		self
+	}
+	pub fn with_user_custom_tlvs(mut self, custom_tlvs: Vec<u8>) -> Self {
+		self.user_custom_tlvs = custom_tlvs;
 		self
 	}
 	pub fn with_payment_metadata(mut self, payment_metadata: Vec<u8>) -> Self {
@@ -2689,8 +2694,8 @@ pub fn do_pass_along_path<'a, 'b, 'c>(args: PassAlongPathArgs) -> Option<Event>
 	let PassAlongPathArgs {
 		origin_node, expected_path, recv_value, payment_hash: our_payment_hash,
 		payment_secret: our_payment_secret, event: ev, payment_claimable_expected,
-		clear_recipient_events, expected_preimage, is_probe, custom_tlvs, payment_metadata,
-		expected_failure
+		clear_recipient_events, expected_preimage, is_probe, sender_custom_tlvs, user_custom_tlvs,
+		payment_metadata, expected_failure
 	} = args;
 
 	let mut payment_event = SendEvent::from_event(ev);
@@ -2723,7 +2728,8 @@ pub fn do_pass_along_path<'a, 'b, 'c>(args: PassAlongPathArgs) -> Option<Event>
 						assert_eq!(our_payment_hash, *payment_hash);
 						assert_eq!(node.node.get_our_node_id(), receiver_node_id.unwrap());
 						assert!(onion_fields.is_some());
-						assert_eq!(onion_fields.as_ref().unwrap().custom_tlvs, custom_tlvs);
+						assert_eq!(onion_fields.as_ref().unwrap().sender_custom_tlvs, sender_custom_tlvs);
+						assert_eq!(onion_fields.as_ref().unwrap().user_custom_tlvs, user_custom_tlvs);
 						assert_eq!(onion_fields.as_ref().unwrap().payment_metadata, payment_metadata);
 						match &purpose {
 							PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
@@ -2842,7 +2848,8 @@ pub struct ClaimAlongRouteArgs<'a, 'b, 'c, 'd> {
 	pub expected_min_htlc_overpay: Vec<u32>,
 	pub skip_last: bool,
 	pub payment_preimage: PaymentPreimage,
-	pub custom_tlvs: Vec<(u64, Vec<u8>)>,
+	pub sender_custom_tlvs: Vec<(u64, Vec<u8>)>,
+	pub user_custom_tlvs: Vec<u8>,
 	// Allow forwarding nodes to have taken 1 msat more fee than expected based on the downstream
 	// fulfill amount.
 	//
@@ -2861,7 +2868,7 @@ impl<'a, 'b, 'c, 'd> ClaimAlongRouteArgs<'a, 'b, 'c, 'd> {
 		Self {
 			origin_node, expected_paths, expected_extra_fees: vec![0; expected_paths.len()],
 			expected_min_htlc_overpay: vec![0; expected_paths.len()], skip_last: false, payment_preimage,
-			allow_1_msat_fee_overpay: false, custom_tlvs: vec![],
+			allow_1_msat_fee_overpay: false, sender_custom_tlvs: vec![], user_custom_tlvs: vec![],
 		}
 	}
 	pub fn skip_last(mut self, skip_last: bool) -> Self {
@@ -2880,16 +2887,16 @@ impl<'a, 'b, 'c, 'd> ClaimAlongRouteArgs<'a, 'b, 'c, 'd> {
 		self.allow_1_msat_fee_overpay = true;
 		self
 	}
-	pub fn with_custom_tlvs(mut self, custom_tlvs: Vec<(u64, Vec<u8>)>) -> Self {
-		self.custom_tlvs = custom_tlvs;
+	pub fn with_sender_custom_tlvs(mut self, custom_tlvs: Vec<(u64, Vec<u8>)>) -> Self {
+		self.sender_custom_tlvs = custom_tlvs;
 		self
 	}
 }
 
 pub fn pass_claimed_payment_along_route(args: ClaimAlongRouteArgs) -> u64 {
 	let ClaimAlongRouteArgs {
 		origin_node, expected_paths, expected_extra_fees, expected_min_htlc_overpay, skip_last,
-		payment_preimage: our_payment_preimage, allow_1_msat_fee_overpay, custom_tlvs,
+		payment_preimage: our_payment_preimage, allow_1_msat_fee_overpay, sender_custom_tlvs, user_custom_tlvs,
 	} = args;
 	let claim_event = expected_paths[0].last().unwrap().node.get_and_clear_pending_events();
 	assert_eq!(claim_event.len(), 1);
@@ -2909,7 +2916,8 @@ pub fn pass_claimed_payment_along_route(args: ClaimAlongRouteArgs) -> u64 {
 			assert_eq!(preimage, our_payment_preimage);
 			assert_eq!(htlcs.len(), expected_paths.len());  // One per path.
 			assert_eq!(htlcs.iter().map(|h| h.value_msat).sum::<u64>(), amount_msat);
-			assert_eq!(onion_fields.as_ref().unwrap().custom_tlvs, custom_tlvs);
+			assert_eq!(onion_fields.as_ref().unwrap().sender_custom_tlvs, sender_custom_tlvs);
+			assert_eq!(onion_fields.as_ref().unwrap().user_custom_tlvs, user_custom_tlvs);
 			check_claimed_htlcs_match_route(origin_node, expected_paths, htlcs);
 			fwd_amt_msat = amount_msat;
 		},
@@ -2926,7 +2934,8 @@ pub fn pass_claimed_payment_along_route(args: ClaimAlongRouteArgs) -> u64 {
 			assert_eq!(&payment_hash.0, &Sha256::hash(&our_payment_preimage.0)[..]);
 			assert_eq!(htlcs.len(), expected_paths.len());  // One per path.
 			assert_eq!(htlcs.iter().map(|h| h.value_msat).sum::<u64>(), amount_msat);
-			assert_eq!(onion_fields.as_ref().unwrap().custom_tlvs, custom_tlvs);
+			assert_eq!(onion_fields.as_ref().unwrap().sender_custom_tlvs, sender_custom_tlvs);
+			assert_eq!(onion_fields.as_ref().unwrap().user_custom_tlvs, user_custom_tlvs);
 			check_claimed_htlcs_match_route(origin_node, expected_paths, htlcs);
 			fwd_amt_msat = amount_msat;
 		}