Introduce via_channel_ids and via_user_channel_ids in PaymentClaimable for MPP clarity

Previously, `channel_id` in `PaymentClaimable` only listed a single
inbound channel, which was misleading for MPP payments arriving via
multiple channels.

To better represent MPP scenarios, this update introduces:
- `via_channel_ids`: A list of all inbound channels used in the payment.
- `via_user_channel_ids`: The corresponding user-defined channel IDs for
  each inbound channel.

This change ensures a more accurate representation of multi-path payments
while maintaining backward compatibility.

Author: shaavan

lightning/src/events/mod.rs

@@ -774,10 +774,16 @@ pub enum Event {
 		/// Information for claiming this received payment, based on whether the purpose of the
 		/// payment is to pay an invoice or to send a spontaneous payment.
 		purpose: PaymentPurpose,
-		/// The `channel_id` indicating over which channel we received the payment.
-		via_channel_id: Option<ChannelId>,
-		/// The `user_channel_id` indicating over which channel we received the payment.
-		via_user_channel_id: Option<u128>,
+		/// The `channel_id`(s) indicating over which channel(s) we received the payment.
+		/// - In a non-MPP scenario, this will contain a single `channel_id` where the payment was received.
+		/// - In an MPP scenario, this will contain multiple `channel_id`s corresponding to the channels over
+		///   which the payment parts were received.
+		via_channel_ids: Vec<Option<ChannelId>>,
+		/// The `user_channel_id`(s) indicating over which channel(s) we received the payment.
+		/// - In a non-MPP scenario, this will contain a single `user_channel_id`.
+		/// - In an MPP scenario, this will contain multiple `user_channel_id`s corresponding to the channels
+		///   over which the payment parts were received.
+		via_user_channel_ids: Vec<Option<u128>>,
 		/// The block height at which this payment will be failed back and will no longer be
 		/// eligible for claiming.
 		///
@@ -1506,7 +1512,7 @@ impl Writeable for Event {
 				// drop any channels which have not yet exchanged funding_signed.
 			},
 			&Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat,
-				ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+				ref purpose, ref receiver_node_id, ref via_channel_ids, ref via_user_channel_ids,
 				ref claim_deadline, ref onion_fields, ref payment_id,
 			} => {
 				1u8.write(writer)?;
@@ -1544,16 +1550,20 @@ impl Writeable for Event {
 					(0, payment_hash, required),
 					(1, receiver_node_id, option),
 					(2, payment_secret, option),
-					(3, via_channel_id, option),
+					// legacy field
+					// (3, via_channel_id, option),
 					(4, amount_msat, required),
-					(5, via_user_channel_id, option),
+					// legacy field
+					// (5, via_user_channel_id, option),
 					// Type 6 was `user_payment_id` on 0.0.103 and earlier
 					(7, claim_deadline, option),
 					(8, payment_preimage, option),
 					(9, onion_fields, option),
 					(10, skimmed_fee_opt, option),
 					(11, payment_context, option),
 					(13, payment_id, option),
+					(15, *via_channel_ids, optional_vec),
+					(17, *via_user_channel_ids, optional_vec),
 				});
 			},
 			&Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref amount_msat, ref fee_paid_msat } => {
@@ -1855,6 +1865,8 @@ impl MaybeReadable for Event {
 					let mut onion_fields = None;
 					let mut payment_context = None;
 					let mut payment_id = None;
+					let mut via_channel_ids_opt = None;
+					let mut via_user_channel_ids_opt = None;
 					read_tlv_fields!(reader, {
 						(0, payment_hash, required),
 						(1, receiver_node_id, option),
@@ -1869,21 +1881,26 @@ impl MaybeReadable for Event {
 						(10, counterparty_skimmed_fee_msat_opt, option),
 						(11, payment_context, option),
 						(13, payment_id, option),
+						(15, via_channel_ids_opt, optional_vec),
+						(17, via_user_channel_ids_opt, optional_vec),
 					});
 					let purpose = match payment_secret {
 						Some(secret) => PaymentPurpose::from_parts(payment_preimage, secret, payment_context)
 							.map_err(|()| msgs::DecodeError::InvalidValue)?,
 						None if payment_preimage.is_some() => PaymentPurpose::SpontaneousPayment(payment_preimage.unwrap()),
 						None => return Err(msgs::DecodeError::InvalidValue),
 					};
+
+					let via_channel_ids = via_channel_ids_opt.unwrap_or(vec![via_channel_id]);
+					let via_user_channel_ids = via_user_channel_ids_opt.unwrap_or(vec![via_user_channel_id]);
 					Ok(Some(Event::PaymentClaimable {
 						receiver_node_id,
 						payment_hash,
 						amount_msat,
 						counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0),
 						purpose,
-						via_channel_id,
-						via_user_channel_id,
+						via_channel_ids,
+						via_user_channel_ids,
 						claim_deadline,
 						onion_fields,
 						payment_id,

lightning/src/ln/chanmon_update_fail_tests.rs

@@ -165,11 +165,11 @@ fn do_test_simple_monitor_temporary_update_fail(disconnect: bool) {
 	let events_3 = nodes[1].node.get_and_clear_pending_events();
 	assert_eq!(events_3.len(), 1);
 	match events_3[0] {
-		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id, .. } => {
+		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, ref via_channel_ids, .. } => {
 			assert_eq!(payment_hash_1, *payment_hash);
 			assert_eq!(amount_msat, 1_000_000);
 			assert_eq!(receiver_node_id.unwrap(), nodes[1].node.get_our_node_id());
-			assert_eq!(via_channel_id, Some(channel_id));
+			assert_eq!(*via_channel_ids.last().unwrap(), Some(channel_id));
 			match &purpose {
 				PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
 					assert!(payment_preimage.is_none());
@@ -547,11 +547,11 @@ fn do_test_monitor_temporary_update_fail(disconnect_count: usize) {
 	let events_5 = nodes[1].node.get_and_clear_pending_events();
 	assert_eq!(events_5.len(), 1);
 	match events_5[0] {
-		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id, .. } => {
+		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, ref via_channel_ids, .. } => {
 			assert_eq!(payment_hash_2, *payment_hash);
 			assert_eq!(amount_msat, 1_000_000);
 			assert_eq!(receiver_node_id.unwrap(), nodes[1].node.get_our_node_id());
-			assert_eq!(via_channel_id, Some(channel_id));
+			assert_eq!(*via_channel_ids.last().unwrap(), Some(channel_id));
 			match &purpose {
 				PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
 					assert!(payment_preimage.is_none());
@@ -665,11 +665,11 @@ fn test_monitor_update_fail_cs() {
 	let events = nodes[1].node.get_and_clear_pending_events();
 	assert_eq!(events.len(), 1);
 	match events[0] {
-		Event::PaymentClaimable { payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id, .. } => {
+		Event::PaymentClaimable { payment_hash, ref purpose, amount_msat, receiver_node_id, ref via_channel_ids, .. } => {
 			assert_eq!(payment_hash, our_payment_hash);
 			assert_eq!(amount_msat, 1_000_000);
 			assert_eq!(receiver_node_id.unwrap(), nodes[1].node.get_our_node_id());
-			assert_eq!(via_channel_id, Some(channel_id));
+			assert_eq!(*via_channel_ids.last().unwrap(), Some(channel_id));
 			match &purpose {
 				PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
 					assert!(payment_preimage.is_none());
@@ -1678,12 +1678,12 @@ fn test_monitor_update_fail_claim() {
 	let events = nodes[0].node.get_and_clear_pending_events();
 	assert_eq!(events.len(), 2);
 	match events[0] {
-		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id, via_user_channel_id, .. } => {
+		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, ref via_channel_ids, ref via_user_channel_ids, .. } => {
 			assert_eq!(payment_hash_2, *payment_hash);
 			assert_eq!(1_000_000, amount_msat);
 			assert_eq!(receiver_node_id.unwrap(), nodes[0].node.get_our_node_id());
-			assert_eq!(via_channel_id, Some(channel_id));
-			assert_eq!(via_user_channel_id, Some(42));
+			assert_eq!(*via_channel_ids.last().unwrap(), Some(channel_id));
+			assert_eq!(*via_user_channel_ids.last().unwrap(), Some(42));
 			match &purpose {
 				PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
 					assert!(payment_preimage.is_none());
@@ -1695,11 +1695,11 @@ fn test_monitor_update_fail_claim() {
 		_ => panic!("Unexpected event"),
 	}
 	match events[1] {
-		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id, .. } => {
+		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, ref via_channel_ids, .. } => {
 			assert_eq!(payment_hash_3, *payment_hash);
 			assert_eq!(1_000_000, amount_msat);
 			assert_eq!(receiver_node_id.unwrap(), nodes[0].node.get_our_node_id());
-			assert_eq!(via_channel_id, Some(channel_id));
+			assert_eq!(*via_channel_ids.last().unwrap(), Some(channel_id));
 			match &purpose {
 				PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
 					assert!(payment_preimage.is_none());

lightning/src/ln/channelmanager.rs

@@ -6292,8 +6292,8 @@ where
 												purpose: $purpose,
 												amount_msat,
 												counterparty_skimmed_fee_msat,
-												via_channel_id: Some(prev_channel_id),
-												via_user_channel_id: Some(prev_user_channel_id),
+												via_channel_ids: claimable_payment.get_channel_ids(),
+												via_user_channel_ids: claimable_payment.get_user_channel_ids(),
 												claim_deadline: Some(earliest_expiry - HTLC_FAIL_BACK_BUFFER),
 												onion_fields: claimable_payment.onion_fields.clone(),
 												payment_id: Some(payment_id),

lightning/src/ln/functional_test_utils.rs

@@ -2734,7 +2734,7 @@ pub fn do_pass_along_path<'a, 'b, 'c>(args: PassAlongPathArgs) -> Option<Event>
 				assert_eq!(events_2.len(), 1);
 				match &events_2[0] {
 					Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat,
-						receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+						receiver_node_id, ref via_channel_ids, ref via_user_channel_ids,
 						claim_deadline, onion_fields, ..
 					} => {
 						assert_eq!(our_payment_hash, *payment_hash);
@@ -2768,8 +2768,8 @@ pub fn do_pass_along_path<'a, 'b, 'c>(args: PassAlongPathArgs) -> Option<Event>
 							},
 						}
 						assert_eq!(*amount_msat, recv_value);
-						assert!(node.node.list_channels().iter().any(|details| details.channel_id == via_channel_id.unwrap()));
-						assert!(node.node.list_channels().iter().any(|details| details.user_channel_id == via_user_channel_id.unwrap()));
+						assert!(node.node.list_channels().iter().any(|details| details.channel_id == via_channel_ids.last().unwrap().unwrap()));
+						assert!(node.node.list_channels().iter().any(|details| details.user_channel_id == via_user_channel_ids.last().unwrap().unwrap()));
 						assert!(claim_deadline.unwrap() > node.best_block_info().1);
 					},
 					_ => panic!("Unexpected event"),

lightning/src/ln/functional_tests.rs

@@ -2068,11 +2068,11 @@ pub fn test_channel_reserve_holding_cell_htlcs() {
 	let events = nodes[2].node.get_and_clear_pending_events();
 	assert_eq!(events.len(), 2);
 	match events[0] {
-		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id, .. } => {
+		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, ref via_channel_ids, .. } => {
 			assert_eq!(our_payment_hash_21, *payment_hash);
 			assert_eq!(recv_value_21, amount_msat);
 			assert_eq!(nodes[2].node.get_our_node_id(), receiver_node_id.unwrap());
-			assert_eq!(via_channel_id, Some(chan_2.2));
+			assert_eq!(*via_channel_ids.last().unwrap(), Some(chan_2.2));
 			match &purpose {
 				PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
 					assert!(payment_preimage.is_none());
@@ -2084,11 +2084,11 @@ pub fn test_channel_reserve_holding_cell_htlcs() {
 		_ => panic!("Unexpected event"),
 	}
 	match events[1] {
-		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id, .. } => {
+		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, ref via_channel_ids, .. } => {
 			assert_eq!(our_payment_hash_22, *payment_hash);
 			assert_eq!(recv_value_22, amount_msat);
 			assert_eq!(nodes[2].node.get_our_node_id(), receiver_node_id.unwrap());
-			assert_eq!(via_channel_id, Some(chan_2.2));
+			assert_eq!(*via_channel_ids.last().unwrap(), Some(chan_2.2));
 			match &purpose {
 				PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
 					assert!(payment_preimage.is_none());
@@ -4313,11 +4313,11 @@ fn do_test_drop_messages_peer_disconnect(messages_delivered: u8, simulate_broken
 	let events_2 = nodes[1].node.get_and_clear_pending_events();
 	assert_eq!(events_2.len(), 1);
 	match events_2[0] {
-		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id, .. } => {
+		Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, ref via_channel_ids, .. } => {
 			assert_eq!(payment_hash_1, *payment_hash);
 			assert_eq!(amount_msat, 1_000_000);
 			assert_eq!(receiver_node_id.unwrap(), nodes[1].node.get_our_node_id());
-			assert_eq!(via_channel_id, Some(channel_id));
+			assert_eq!(*via_channel_ids.last().unwrap(), Some(channel_id));
 			match &purpose {
 				PaymentPurpose::Bolt11InvoicePayment { payment_preimage, payment_secret, .. } => {
 					assert!(payment_preimage.is_none());