Add a user_payment_id to get_payment_secret+PaymentReceived

This allows users to store metadata about an invoice at
invoice-generation time and then index into that storage with a
general-purpose id when they call `get_payment_secret`. They will
then be provided the same index when the payment has been received.

Author: TheBlueMatt

fuzz/src/chanmon_consistency.rs

@@ -265,7 +265,7 @@ fn get_payment_secret_hash(dest: &ChanMan, payment_id: &mut u8) -> Option<(Payme
 	let mut payment_hash;
 	for _ in 0..256 {
 		payment_hash = PaymentHash(Sha256::hash(&[*payment_id; 1]).into_inner());
-		if let Ok(payment_secret) = dest.get_payment_secret(payment_hash, None, 1008) {
+		if let Ok(payment_secret) = dest.get_payment_secret(payment_hash, None, 1008, 0) {
 			return Some((payment_secret, payment_hash));
 		}
 		*payment_id = payment_id.wrapping_add(1);
@@ -686,7 +686,7 @@ pub fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
 				let had_events = !events.is_empty();
 				for event in events.drain(..) {
 					match event {
-						events::Event::PaymentReceived { payment_hash, payment_secret, amt } => {
+						events::Event::PaymentReceived { payment_hash, payment_secret, amt, user_payment_id: _ } => {
 							if claim_set.insert(payment_hash.0) {
 								if $fail {
 									assert!(nodes[$node].fail_htlc_backwards(&payment_hash, &payment_secret));

fuzz/src/full_stack.rs

@@ -570,7 +570,7 @@ pub fn do_test(data: &[u8], logger: &Arc<dyn Logger>) {
 				Event::FundingGenerationReady { temporary_channel_id, channel_value_satoshis, output_script, .. } => {
 					pending_funding_generation.push((temporary_channel_id, channel_value_satoshis, output_script));
 				},
-				Event::PaymentReceived { payment_hash, payment_secret, amt } => {
+				Event::PaymentReceived { payment_hash, payment_secret, amt, user_payment_id: _ } => {
 					//TODO: enhance by fetching random amounts from fuzz input?
 					payments_received.push((payment_hash, payment_secret, amt));
 				},

lightning/src/ln/chanmon_update_fail_tests.rs

@@ -205,7 +205,7 @@ fn do_test_simple_monitor_temporary_update_fail(disconnect: bool, persister_fail
 	let events_3 = nodes[1].node.get_and_clear_pending_events();
 	assert_eq!(events_3.len(), 1);
 	match events_3[0] {
-		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt } => {
+		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt, user_payment_id: _ } => {
 			assert_eq!(payment_hash_1, *payment_hash);
 			assert_eq!(Some(payment_secret_1), *payment_secret);
 			assert_eq!(amt, 1000000);
@@ -573,7 +573,7 @@ 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::PaymentReceived { ref payment_hash, ref payment_secret, amt } => {
+		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt, user_payment_id: _ } => {
 			assert_eq!(payment_hash_2, *payment_hash);
 			assert_eq!(Some(payment_secret_2), *payment_secret);
 			assert_eq!(amt, 1000000);
@@ -687,7 +687,7 @@ 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::PaymentReceived { payment_hash, payment_secret, amt } => {
+		Event::PaymentReceived { payment_hash, payment_secret, amt, user_payment_id: _ } => {
 			assert_eq!(payment_hash, our_payment_hash);
 			assert_eq!(Some(our_payment_secret), payment_secret);
 			assert_eq!(amt, 1000000);

lightning/src/ln/channelmanager.rs

@@ -360,6 +360,8 @@ struct PeerState {
 struct PendingInboundPayment {
 	/// The payment secret which the sender must use for us to accept this payment
 	payment_secret: PaymentSecret,
+	/// Arbitrary identifier the user specifies (or not)
+	user_payment_id: u64,
 	/// Height at which this HTLC expires - block height above this value will result in this
 	/// payment being removed. Note that we'll reject any payments within HTLC_FAIL_BACK_BUFFER of
 	/// the height at which they are received.
@@ -1962,9 +1964,11 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 								// that we are the ultimately recipient of the given payment hash.
 								// Further, we must not expose whether we have any other HTLCs
 								// associated with the same payment_hash pending or not.
+								let mut user_payment_id = 0;
 								if {
 									let payment_secrets = self.pending_inbound_payments.lock().unwrap();
 									if let Some(inbound_payment) = payment_secrets.get(&payment_hash) {
+										user_payment_id = inbound_payment.user_payment_id;
 										inbound_payment.payment_secret != payment_data.payment_secret ||
 										(inbound_payment.min_value_msat.is_some() && inbound_payment.min_value_msat.unwrap() > payment_data.total_msat)
 									} else { true }
@@ -1993,6 +1997,7 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 											payment_hash,
 											payment_secret: Some(payment_data.payment_secret),
 											amt: total_value,
+											user_payment_id,
 										});
 									}
 								}
@@ -3343,6 +3348,12 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 	/// secret fetched via this method or [`get_payment_secret`], and which is at least the `value`
 	/// provided here, if one is provided.
 	///
+	/// `user_payment_id` will be provided back in [`PaymentReceived::user_payment_id`] events to
+	/// allow tracking of which events correspond with which get_payment_secret_preimage calls.
+	/// user_payment_id has no meaning inside of LDK, it is simply copied to events and otherwise
+	/// ignored. It may be used to correlate PaymentReceived events with invoice metadata stored
+	/// elsewhere.
+	///
 	/// `min_value_msat` should be set if the invoice being generated contains a value. Any payment
 	/// received for the returned PaymentHash will be required to be at least `min_value_msat`
 	/// before a [`PaymentReceived`] event will be generated, ensuring that we do not provide the
@@ -3355,7 +3366,8 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 	///
 	/// [`get_payment_secret`]: Self::get_payment_secret
 	/// [`PaymentReceived`]: events::Event::PaymentReceived
-	pub fn get_payment_secret_preimage(&self, min_value_msat: Option<u64>, invoice_expiry_delta_blocks: u32) -> (PaymentHash, PaymentSecret) {
+	/// [`PaymentReceived::user_payment_id`]: events::Event::PaymentReceived::user_payment_id
+	pub fn get_payment_secret_preimage(&self, min_value_msat: Option<u64>, invoice_expiry_delta_blocks: u32, user_payment_id: u64) -> (PaymentHash, PaymentSecret) {
 		assert!(invoice_expiry_delta_blocks <= 6*24*365); // We may overflow later if this value is too large
 
 		let payment_secret = PaymentSecret(self.keys_manager.get_secure_random_bytes());
@@ -3365,7 +3377,7 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 		let _persistence_guard = PersistenceNotifierGuard::new(&self.total_consistency_lock, &self.persistence_notifier);
 		let mut payment_secrets = self.pending_inbound_payments.lock().unwrap();
 		if payment_secrets.insert(payment_hash, PendingInboundPayment {
-			payment_secret, min_value_msat,
+			payment_secret, min_value_msat, user_payment_id,
 			expiry_height: self.best_block.read().unwrap().height() + invoice_expiry_delta_blocks,
 			payment_preimage: Some(payment_preimage)
 		}).is_some() {
@@ -3384,6 +3396,12 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 	/// The payment_hash (and corresponding payment preimage) must be globally unique. This method
 	/// may return an Err if another payment with the same payment_hash is still pending.
 	///
+	/// `user_payment_id` will be provided back in [`PaymentReceived::user_payment_id`] events to
+	/// allow tracking of which events correspond with which get_payment_secret_preimage calls.
+	/// user_payment_id has no meaning inside of LDK, it is simply copied to events and otherwise
+	/// ignored. It may be used to correlate PaymentReceived events with invoice metadata stored
+	/// elsewhere.
+	///
 	/// `min_value_msat` should be set if the invoice being generated contains a value. Any payment
 	/// received for the returned PaymentHash will be required to be at least `min_value_msat`
 	/// before a [`PaymentReceived`] event will be generated, ensuring that we do not provide the
@@ -3396,7 +3414,8 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 	///
 	/// [`get_payment_secret_preimage`]: Self::get_payment_secret_preimage
 	/// [`PaymentReceived`]: events::Event::PaymentReceived
-	pub fn get_payment_secret(&self, payment_hash: PaymentHash, min_value_msat: Option<u64>, invoice_expiry_delta_blocks: u32) -> Result<PaymentSecret, APIError> {
+	/// [`PaymentReceived::user_payment_id`]: events::Event::PaymentReceived::user_payment_id
+	pub fn get_payment_secret(&self, payment_hash: PaymentHash, min_value_msat: Option<u64>, invoice_expiry_delta_blocks: u32, user_payment_id: u64) -> Result<PaymentSecret, APIError> {
 		assert!(invoice_expiry_delta_blocks <= 6*24*365); // We may overflow later if this value is too large
 
 		let payment_secret = PaymentSecret(self.keys_manager.get_secure_random_bytes());
@@ -3406,7 +3425,7 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 		match payment_secrets.entry(payment_hash) {
 			hash_map::Entry::Vacant(e) => {
 				e.insert(PendingInboundPayment {
-					payment_secret, min_value_msat, payment_preimage: None,
+					payment_secret, min_value_msat, user_payment_id, payment_preimage: None,
 					expiry_height: self.best_block.read().unwrap().height() + invoice_expiry_delta_blocks,
 				});
 			},
@@ -4285,6 +4304,7 @@ impl Readable for HTLCForwardInfo {
 
 impl_writeable!(PendingInboundPayment, 0, {
 	payment_secret,
+	user_payment_id,
 	expiry_height,
 	payment_preimage,
 	min_value_msat

lightning/src/ln/functional_test_utils.rs

@@ -899,7 +899,7 @@ macro_rules! get_payment_preimage_hash {
 			let payment_preimage = PaymentPreimage([*$dest_node.network_payment_count.borrow(); 32]);
 			*$dest_node.network_payment_count.borrow_mut() += 1;
 			let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0[..]).into_inner());
-			let payment_secret = $dest_node.node.get_payment_secret(payment_hash, None, 1008).unwrap();
+			let payment_secret = $dest_node.node.get_payment_secret(payment_hash, None, 1008, 0).unwrap();
 			(payment_preimage, payment_hash, payment_secret)
 		}
 	}
@@ -941,7 +941,7 @@ macro_rules! expect_payment_received {
 		let events = $node.node.get_and_clear_pending_events();
 		assert_eq!(events.len(), 1);
 		match events[0] {
-			Event::PaymentReceived { ref payment_hash, ref payment_secret, amt } => {
+			Event::PaymentReceived { ref payment_hash, ref payment_secret, amt, user_payment_id: _ } => {
 				assert_eq!($expected_payment_hash, *payment_hash);
 				assert_eq!(Some($expected_payment_secret), *payment_secret);
 				assert_eq!($expected_recv_value, amt);
@@ -1009,7 +1009,7 @@ pub fn pass_along_path<'a, 'b, 'c>(origin_node: &Node<'a, 'b, 'c>, expected_path
 			if payment_received_expected {
 				assert_eq!(events_2.len(), 1);
 				match events_2[0] {
-					Event::PaymentReceived { ref payment_hash, ref payment_secret, amt } => {
+					Event::PaymentReceived { ref payment_hash, ref payment_secret, amt, user_payment_id: _ } => {
 						assert_eq!(our_payment_hash, *payment_hash);
 						assert_eq!(Some(our_payment_secret), *payment_secret);
 						assert_eq!(amt, recv_value);

lightning/src/ln/functional_tests.rs

@@ -1469,7 +1469,7 @@ fn test_duplicate_htlc_different_direction_onchain() {
 
 	let net_graph_msg_handler = &nodes[1].net_graph_msg_handler;
 	let route = get_route(&nodes[1].node.get_our_node_id(), &net_graph_msg_handler.network_graph.read().unwrap(), &nodes[0].node.get_our_node_id(), Some(InvoiceFeatures::known()), None, &Vec::new(), 800_000, TEST_FINAL_CLTV, &logger).unwrap();
-	let node_a_payment_secret = nodes[0].node.get_payment_secret(payment_hash, None, 1008).unwrap();
+	let node_a_payment_secret = nodes[0].node.get_payment_secret(payment_hash, None, 1008, 0).unwrap();
 	send_along_route_with_secret(&nodes[1], route, &[&[&nodes[0]]], 800_000, payment_hash, node_a_payment_secret);
 
 	// Provide preimage to node 0 by claiming payment
@@ -2069,15 +2069,15 @@ 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::PaymentReceived { ref payment_hash, ref payment_secret, amt } => {
+		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt, user_payment_id: _ } => {
 			assert_eq!(our_payment_hash_21, *payment_hash);
 			assert_eq!(Some(our_payment_secret_21), *payment_secret);
 			assert_eq!(recv_value_21, amt);
 		},
 		_ => panic!("Unexpected event"),
 	}
 	match events[1] {
-		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt } => {
+		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt, user_payment_id: _ } => {
 			assert_eq!(our_payment_hash_22, *payment_hash);
 			assert_eq!(Some(our_payment_secret_22), *payment_secret);
 			assert_eq!(recv_value_22, amt);
@@ -3645,7 +3645,7 @@ fn do_test_drop_messages_peer_disconnect(messages_delivered: u8) {
 	let events_2 = nodes[1].node.get_and_clear_pending_events();
 	assert_eq!(events_2.len(), 1);
 	match events_2[0] {
-		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt } => {
+		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt, user_payment_id: _ } => {
 			assert_eq!(payment_hash_1, *payment_hash);
 			assert_eq!(Some(payment_secret_1), *payment_secret);
 			assert_eq!(amt, 1000000);
@@ -3982,7 +3982,7 @@ fn test_drop_messages_peer_disconnect_dual_htlc() {
 	let events_5 = nodes[1].node.get_and_clear_pending_events();
 	assert_eq!(events_5.len(), 1);
 	match events_5[0] {
-		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt: _ } => {
+		Event::PaymentReceived { ref payment_hash, ref payment_secret, amt: _, user_payment_id: _ } => {
 			assert_eq!(payment_hash_2, *payment_hash);
 			assert_eq!(Some(payment_secret_2), *payment_secret);
 		},
@@ -5112,7 +5112,7 @@ fn test_duplicate_payment_hash_one_failure_one_success() {
 
 	let (our_payment_preimage, duplicate_payment_hash, _) = route_payment(&nodes[0], &vec!(&nodes[1], &nodes[2])[..], 900000);
 
-	let payment_secret = nodes[3].node.get_payment_secret(duplicate_payment_hash, None, 1008).unwrap();
+	let payment_secret = nodes[3].node.get_payment_secret(duplicate_payment_hash, None, 1008, 0).unwrap();
 	let route = get_route(&nodes[0].node.get_our_node_id(), &nodes[0].net_graph_msg_handler.network_graph.read().unwrap(),
 		&nodes[3].node.get_our_node_id(), Some(InvoiceFeatures::known()), None, &Vec::new(), 900000, TEST_FINAL_CLTV, nodes[0].logger).unwrap();
 	send_along_route_with_secret(&nodes[0], route, &[&[&nodes[1], &nodes[2], &nodes[3]]], 900000, duplicate_payment_hash, payment_secret);
@@ -5306,30 +5306,30 @@ fn do_test_fail_backwards_unrevoked_remote_announce(deliver_last_raa: bool, anno
 	let our_node_id = &nodes[1].node.get_our_node_id();
 	let route = get_route(our_node_id, &net_graph_msg_handler.network_graph.read().unwrap(), &nodes[5].node.get_our_node_id(), Some(InvoiceFeatures::known()), None, &Vec::new(), ds_dust_limit*1000, TEST_FINAL_CLTV, &logger).unwrap();
 	// 2nd HTLC:
-	send_along_route_with_secret(&nodes[1], route.clone(), &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_1, nodes[5].node.get_payment_secret(payment_hash_1, None, 1008).unwrap()); // not added < dust limit + HTLC tx fee
+	send_along_route_with_secret(&nodes[1], route.clone(), &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_1, nodes[5].node.get_payment_secret(payment_hash_1, None, 1008, 0).unwrap()); // not added < dust limit + HTLC tx fee
 	// 3rd HTLC:
-	send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_2, nodes[5].node.get_payment_secret(payment_hash_2, None, 1008).unwrap()); // not added < dust limit + HTLC tx fee
+	send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_2, nodes[5].node.get_payment_secret(payment_hash_2, None, 1008, 0).unwrap()); // not added < dust limit + HTLC tx fee
 	// 4th HTLC:
 	let (_, payment_hash_3, _) = route_payment(&nodes[0], &[&nodes[2], &nodes[3], &nodes[4]], 1000000);
 	// 5th HTLC:
 	let (_, payment_hash_4, _) = route_payment(&nodes[0], &[&nodes[2], &nodes[3], &nodes[4]], 1000000);
 	let route = get_route(our_node_id, &net_graph_msg_handler.network_graph.read().unwrap(), &nodes[5].node.get_our_node_id(), Some(InvoiceFeatures::known()), None, &Vec::new(), 1000000, TEST_FINAL_CLTV, &logger).unwrap();
 	// 6th HTLC:
-	send_along_route_with_secret(&nodes[1], route.clone(), &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_3, nodes[5].node.get_payment_secret(payment_hash_3, None, 1008).unwrap());
+	send_along_route_with_secret(&nodes[1], route.clone(), &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_3, nodes[5].node.get_payment_secret(payment_hash_3, None, 1008, 0).unwrap());
 	// 7th HTLC:
-	send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_4, nodes[5].node.get_payment_secret(payment_hash_4, None, 1008).unwrap());
+	send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_4, nodes[5].node.get_payment_secret(payment_hash_4, None, 1008, 0).unwrap());
 
 	// 8th HTLC:
 	let (_, payment_hash_5, _) = route_payment(&nodes[0], &[&nodes[2], &nodes[3], &nodes[4]], 1000000);
 	// 9th HTLC:
 	let route = get_route(our_node_id, &net_graph_msg_handler.network_graph.read().unwrap(), &nodes[5].node.get_our_node_id(), Some(InvoiceFeatures::known()), None, &Vec::new(), ds_dust_limit*1000, TEST_FINAL_CLTV, &logger).unwrap();
-	send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_5, nodes[5].node.get_payment_secret(payment_hash_5, None, 1008).unwrap()); // not added < dust limit + HTLC tx fee
+	send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_5, nodes[5].node.get_payment_secret(payment_hash_5, None, 1008, 0).unwrap()); // not added < dust limit + HTLC tx fee
 
 	// 10th HTLC:
 	let (_, payment_hash_6, _) = route_payment(&nodes[0], &[&nodes[2], &nodes[3], &nodes[4]], ds_dust_limit*1000); // not added < dust limit + HTLC tx fee
 	// 11th HTLC:
 	let route = get_route(our_node_id, &net_graph_msg_handler.network_graph.read().unwrap(), &nodes[5].node.get_our_node_id(), Some(InvoiceFeatures::known()), None, &Vec::new(), 1000000, TEST_FINAL_CLTV, &logger).unwrap();
-	send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_6, nodes[5].node.get_payment_secret(payment_hash_6, None, 1008).unwrap());
+	send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_6, nodes[5].node.get_payment_secret(payment_hash_6, None, 1008, 0).unwrap());
 
 	// Double-check that six of the new HTLC were added
 	// We now have six HTLCs pending over the dust limit and six HTLCs under the dust limit (ie,

lightning/src/util/events.rs

@@ -75,6 +75,8 @@ pub enum Event {
 		/// compare this to the expected value before accepting the payment (as otherwise you are
 		/// providing proof-of-payment for less than the value you expected!).
 		amt: u64,
+		/// ;
+		user_payment_id: u64,
 	},
 	/// Indicates an outbound payment we made succeeded (ie it made it all the way to its target
 	/// and we got back the payment preimage for it).
@@ -129,11 +131,12 @@ impl Writeable for Event {
 				// We never write out FundingGenerationReady events as, upon disconnection, peers
 				// drop any channels which have not yet exchanged funding_signed.
 			},
-			&Event::PaymentReceived { ref payment_hash, ref payment_secret, ref amt } => {
+			&Event::PaymentReceived { ref payment_hash, ref payment_secret, ref amt, ref user_payment_id } => {
 				1u8.write(writer)?;
 				payment_hash.write(writer)?;
 				payment_secret.write(writer)?;
 				amt.write(writer)?;
+				user_payment_id.write(writer)?;
 			},
 			&Event::PaymentSent { ref payment_preimage } => {
 				2u8.write(writer)?;
@@ -177,6 +180,7 @@ impl MaybeReadable for Event {
 					payment_hash: Readable::read(reader)?,
 					payment_secret: Readable::read(reader)?,
 					amt: Readable::read(reader)?,
+					user_payment_id: Readable::read(reader)?,
 				})),
 			2u8 => Ok(Some(Event::PaymentSent {
 					payment_preimage: Readable::read(reader)?,