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

@@ -1323,7 +1323,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();
@@ -1336,11 +1336,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

@@ -187,7 +187,9 @@ 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>)>,
+		sender_custom_tlvs: Vec<(u64, Vec<u8>)>,
+		/// Custom TLVs which were set by us through the reply path
+		user_custom_tlvs: Vec<u8>,
 		/// Set if this HTLC is the final hop in a multi-hop blinded path.
 		requires_blinded_error: bool,
 	},
@@ -217,7 +219,9 @@ pub enum PendingHTLCRouting {
 		///
 		/// For HTLCs received by LDK, these will ultimately bubble back up as
 		/// [`RecipientOnionFields::custom_tlvs`].
-		custom_tlvs: Vec<(u64, Vec<u8>)>,
+		sender_custom_tlvs: Vec<(u64, Vec<u8>)>,
+		/// Custom TLVs which were set by us through the reply path
+		user_custom_tlvs: Vec<u8>,
 		/// Set if this HTLC is the final hop in a multi-hop blinded path.
 		requires_blinded_error: bool,
 	},
@@ -5712,23 +5716,24 @@ where
 								let (cltv_expiry, onion_payload, payment_data, payment_context, phantom_shared_secret, mut onion_fields) = 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)
 									},
 									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: _
 									} => {
 										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)
@@ -6700,10 +6705,10 @@ where
 						}
 					});
 
-				if let Some(RecipientOnionFields { ref custom_tlvs, .. }) = claiming_payment.onion_fields {
-					if !custom_tlvs_known && custom_tlvs.iter().any(|(typ, _)| typ % 2 == 0) {
+				if let Some(RecipientOnionFields { ref sender_custom_tlvs, .. }) = claiming_payment.onion_fields {
+					if !custom_tlvs_known && sender_custom_tlvs.iter().any(|(typ, _)| typ % 2 == 0) {
 						log_info!(self.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)));
 						claimable_payments.pending_claiming_payments.remove(&payment_hash);
 						mem::drop(claimable_payments);
 						for htlc in payment.htlcs {
@@ -11455,17 +11460,19 @@ 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, user_custom_tlvs, optional_vec),
 	},
 );
 
@@ -14182,7 +14189,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.
@@ -14204,7 +14212,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]),
@@ -14228,7 +14237,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,
 			node[0].node.default_configuration.accept_mpp_keysend);
 

lightning/src/ln/functional_test_utils.rs

@@ -2585,7 +2585,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>>,
 }
 
@@ -2597,7 +2598,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,
+			is_probe: false, sender_custom_tlvs: Vec::new(), user_custom_tlvs: Vec::new(), payment_metadata: None,
 		}
 	}
 	pub fn without_clearing_recipient_events(mut self) -> Self {
@@ -2621,8 +2622,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 {
@@ -2635,7 +2640,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,
+		clear_recipient_events, expected_preimage, is_probe, sender_custom_tlvs, user_custom_tlvs,
+		payment_metadata,
 	} = args;
 
 	let mut payment_event = SendEvent::from_event(ev);
@@ -2668,7 +2674,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, .. } => {
@@ -2782,7 +2789,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.
 	//
@@ -2801,7 +2809,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 {
@@ -2820,16 +2828,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);
@@ -2849,7 +2857,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;
 		},
@@ -2866,7 +2875,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;
 		}