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.

Author: shaavan

lightning/src/ln/blinded_payment_tests.rs

@@ -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_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_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

@@ -2668,7 +2668,7 @@ 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, custom_tlvs);
 						assert_eq!(onion_fields.as_ref().unwrap().payment_metadata, payment_metadata);
 						match &purpose {
 							PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
@@ -2849,7 +2849,7 @@ 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, custom_tlvs);
 			check_claimed_htlcs_match_route(origin_node, expected_paths, htlcs);
 			fwd_amt_msat = amount_msat;
 		},
@@ -2866,7 +2866,7 @@ 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, custom_tlvs);
 			check_claimed_htlcs_match_route(origin_node, expected_paths, htlcs);
 			fwd_amt_msat = amount_msat;
 		}

lightning/src/ln/max_payment_path_len_tests.rs

@@ -58,7 +58,8 @@ fn large_payment_metadata() {
 		}),
 		payment_metadata: None,
 		keysend_preimage: None,
-		custom_tlvs: &Vec::new(),
+		sender_custom_tlvs: &Vec::new(),
+		user_custom_tlvs: &Vec::new(),
 		sender_intended_htlc_amt_msat: MIN_FINAL_VALUE_ESTIMATE_WITH_OVERPAY,
 		cltv_expiry_height: nodes[0].best_block_info().1 + DEFAULT_MAX_TOTAL_CLTV_EXPIRY_DELTA,
 	}.serialized_length();
@@ -75,7 +76,8 @@ fn large_payment_metadata() {
 	let mut recipient_onion_max_md_size = RecipientOnionFields {
 		payment_secret: Some(payment_secret),
 		payment_metadata: Some(payment_metadata.clone()),
-		custom_tlvs: Vec::new(),
+		sender_custom_tlvs: Vec::new(),
+		user_custom_tlvs: Vec::new(),
 	};
 	nodes[0].node.send_payment(payment_hash, recipient_onion_max_md_size.clone(), PaymentId(payment_hash.0), route_0_1.route_params.clone().unwrap(), Retry::Attempts(0)).unwrap();
 	check_added_monitors!(nodes[0], 1);
@@ -123,7 +125,8 @@ fn large_payment_metadata() {
 	let mut recipient_onion_allows_2_hops = RecipientOnionFields {
 		payment_secret: Some(payment_secret_2),
 		payment_metadata: Some(vec![42; max_metadata_len - INTERMED_PAYLOAD_LEN_ESTIMATE]),
-		custom_tlvs: Vec::new(),
+		sender_custom_tlvs: Vec::new(),
+		user_custom_tlvs: Vec::new(),
 	};
 	let mut route_params_0_2 = route_0_2.route_params.clone().unwrap();
 	route_params_0_2.payment_params.max_path_length = 2;
@@ -184,7 +187,8 @@ fn one_hop_blinded_path_with_custom_tlv() {
 		encrypted_tlvs: &blinded_path.blinded_hops()[0].encrypted_payload,
 		intro_node_blinding_point: Some(blinded_path.blinding_point()),
 		keysend_preimage: None,
-		custom_tlvs: &Vec::new()
+		sender_custom_tlvs: &Vec::new(),
+		user_custom_tlvs: &Vec::new(),
 	}.serialized_length();
 	let max_custom_tlv_len = 1300
 		- crate::util::ser::BigSize(CUSTOM_TLV_TYPE).serialized_length() // custom TLV type
@@ -205,16 +209,16 @@ fn one_hop_blinded_path_with_custom_tlv() {
 	let path = &[&nodes[2]];
 	let args = PassAlongPathArgs::new(&nodes[1], path, amt_msat, payment_hash, events.pop().unwrap())
 		.with_payment_secret(payment_secret)
-		.with_custom_tlvs(recipient_onion_max_custom_tlv_size.custom_tlvs.clone());
+		.with_custom_tlvs(recipient_onion_max_custom_tlv_size.sender_custom_tlvs.clone());
 	do_pass_along_path(args);
 	claim_payment_along_route(
 		ClaimAlongRouteArgs::new(&nodes[1], &[&[&nodes[2]]], payment_preimage)
-			.with_custom_tlvs(recipient_onion_max_custom_tlv_size.custom_tlvs.clone())
+			.with_custom_tlvs(recipient_onion_max_custom_tlv_size.sender_custom_tlvs.clone())
 	);
 
 	// If 1 byte is added to the custom TLV value, we'll fail to send prior to pathfinding.
 	let mut recipient_onion_too_large_custom_tlv = recipient_onion_max_custom_tlv_size.clone();
-	recipient_onion_too_large_custom_tlv.custom_tlvs[0].1.push(42);
+	recipient_onion_too_large_custom_tlv.sender_custom_tlvs[0].1.push(42);
 	let err = nodes[1].node.send_payment(payment_hash, recipient_onion_too_large_custom_tlv, PaymentId(payment_hash.0), route_params.clone(), Retry::Attempts(0)).unwrap_err();
 	assert_eq!(err, RetryableSendFailure::OnionPacketSizeExceeded);
 
@@ -226,7 +230,7 @@ fn one_hop_blinded_path_with_custom_tlv() {
 	// If we remove enough custom TLV bytes to allow for 1 intermediate unblinded hop, we're now able
 	// to send nodes[0] -> nodes[2].
 	let mut recipient_onion_allows_2_hops = recipient_onion_max_custom_tlv_size.clone();
-	recipient_onion_allows_2_hops.custom_tlvs[0].1.resize(max_custom_tlv_len - INTERMED_PAYLOAD_LEN_ESTIMATE, 0);
+	recipient_onion_allows_2_hops.sender_custom_tlvs[0].1.resize(max_custom_tlv_len - INTERMED_PAYLOAD_LEN_ESTIMATE, 0);
 	nodes[0].node.send_payment(payment_hash, recipient_onion_allows_2_hops.clone(), PaymentId(payment_hash.0), route_params.clone(), Retry::Attempts(0)).unwrap();
 	check_added_monitors(&nodes[0], 1);
 
@@ -235,11 +239,11 @@ fn one_hop_blinded_path_with_custom_tlv() {
 	let path = &[&nodes[1], &nodes[2]];
 	let args = PassAlongPathArgs::new(&nodes[0], path, amt_msat, payment_hash, events.pop().unwrap())
 		.with_payment_secret(payment_secret)
-		.with_custom_tlvs(recipient_onion_allows_2_hops.custom_tlvs.clone());
+		.with_custom_tlvs(recipient_onion_allows_2_hops.sender_custom_tlvs.clone());
 	do_pass_along_path(args);
 	claim_payment_along_route(
 		ClaimAlongRouteArgs::new(&nodes[0], &[&[&nodes[1], &nodes[2]]], payment_preimage)
-			.with_custom_tlvs(recipient_onion_allows_2_hops.custom_tlvs)
+			.with_custom_tlvs(recipient_onion_allows_2_hops.sender_custom_tlvs)
 	);
 }
 
@@ -300,16 +304,16 @@ fn blinded_path_with_custom_tlv() {
 	let path = &[&nodes[2], &nodes[3]];
 	let args = PassAlongPathArgs::new(&nodes[1], path, amt_msat, payment_hash, events.pop().unwrap())
 		.with_payment_secret(payment_secret)
-		.with_custom_tlvs(recipient_onion_max_custom_tlv_size.custom_tlvs.clone());
+		.with_custom_tlvs(recipient_onion_max_custom_tlv_size.sender_custom_tlvs.clone());
 	do_pass_along_path(args);
 	claim_payment_along_route(
 		ClaimAlongRouteArgs::new(&nodes[1], &[&[&nodes[2], &nodes[3]]], payment_preimage)
-			.with_custom_tlvs(recipient_onion_max_custom_tlv_size.custom_tlvs.clone())
+			.with_custom_tlvs(recipient_onion_max_custom_tlv_size.sender_custom_tlvs.clone())
 	);
 
 	// If 1 byte is added to the custom TLV value, we'll fail to send prior to pathfinding.
 	let mut recipient_onion_too_large_custom_tlv = recipient_onion_max_custom_tlv_size.clone();
-	recipient_onion_too_large_custom_tlv.custom_tlvs[0].1.push(42);
+	recipient_onion_too_large_custom_tlv.sender_custom_tlvs[0].1.push(42);
 	let err = nodes[1].node.send_payment(payment_hash, recipient_onion_too_large_custom_tlv.clone(), PaymentId(payment_hash.0), route_params.clone(), Retry::Attempts(0)).unwrap_err();
 	assert_eq!(err, RetryableSendFailure::OnionPacketSizeExceeded);
 
@@ -333,7 +337,7 @@ fn blinded_path_with_custom_tlv() {
 	// If we remove enough custom TLV bytes to allow for 1 intermediate unblinded hop, we're now able
 	// to send nodes[0] -> nodes[3].
 	let mut recipient_onion_allows_2_hops = recipient_onion_max_custom_tlv_size.clone();
-	recipient_onion_allows_2_hops.custom_tlvs[0].1.resize(max_custom_tlv_len - INTERMED_PAYLOAD_LEN_ESTIMATE, 0);
+	recipient_onion_allows_2_hops.sender_custom_tlvs[0].1.resize(max_custom_tlv_len - INTERMED_PAYLOAD_LEN_ESTIMATE, 0);
 	nodes[0].node.send_payment(payment_hash, recipient_onion_allows_2_hops.clone(), PaymentId(payment_hash.0), route_params.clone(), Retry::Attempts(0)).unwrap();
 	check_added_monitors(&nodes[0], 1);
 
@@ -342,11 +346,11 @@ fn blinded_path_with_custom_tlv() {
 	let path = &[&nodes[1], &nodes[2], &nodes[3]];
 	let args = PassAlongPathArgs::new(&nodes[0], path, amt_msat, payment_hash, events.pop().unwrap())
 		.with_payment_secret(payment_secret)
-		.with_custom_tlvs(recipient_onion_allows_2_hops.custom_tlvs.clone());
+		.with_custom_tlvs(recipient_onion_allows_2_hops.sender_custom_tlvs.clone());
 	do_pass_along_path(args);
 	claim_payment_along_route(
 		ClaimAlongRouteArgs::new(&nodes[0], &[&[&nodes[1], &nodes[2], &nodes[3]]], payment_preimage)
-			.with_custom_tlvs(recipient_onion_allows_2_hops.custom_tlvs)
+			.with_custom_tlvs(recipient_onion_allows_2_hops.sender_custom_tlvs)
 	);
 }