blip42: Add ContactInfo to payment events for contact management

Implements BLIP-42 contact information propagation through payment events:

- Add ContactInfo struct to events module with contact_secret and payer_offer
- Update PaymentSent event to include optional ContactInfo
- Update outbound_payment to track and propagate ContactInfo
- Update test utilities to handle ContactInfo in payment events
- Update async_payments_tests and payment_tests for new event fields

This allows applications to establish contact relationships when
BOLT12 offer payments complete.

Signed-off-by: Vincenzo Palazzo <[email protected]>

Author: vincenzopalazzo

lightning/src/events/mod.rs

@@ -727,6 +727,55 @@ pub enum InboundChannelFunds {
 	/// who is the channel opener in this case.
 	DualFunded,
 }
+/// Contact information for BLIP-42 contact management, containing the contact secrets
+/// and payer offer that were used when paying a BOLT12 offer.
+///
+/// This information allows the payer to establish a contact relationship with the recipient,
+/// enabling future direct payments without needing a new offer.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ContactInfo {
+	/// The contact secrets that were generated and sent in the invoice request.
+	pub contact_secrets: crate::offers::contacts::ContactSecrets,
+	/// The payer's offer that was sent in the invoice request.
+	pub payer_offer: crate::offers::offer::Offer,
+}
+
+impl Writeable for ContactInfo {
+	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
+		// Serialize ContactSecrets by writing its fields
+		self.contact_secrets.primary_secret().write(writer)?;
+		(self.contact_secrets.additional_remote_secrets().len() as u16).write(writer)?;
+		for secret in self.contact_secrets.additional_remote_secrets() {
+			secret.write(writer)?;
+		}
+		// Serialize Offer as bytes (as a length-prefixed Vec<u8>)
+		self.payer_offer.as_ref().to_vec().write(writer)?;
+		Ok(())
+	}
+}
+
+impl Readable for ContactInfo {
+	fn read<R: io::Read>(reader: &mut R) -> Result<Self, crate::ln::msgs::DecodeError> {
+		// Deserialize ContactSecrets
+		let primary_secret: crate::offers::contacts::ContactSecret = Readable::read(reader)?;
+		let num_secrets: u16 = Readable::read(reader)?;
+		let mut additional_remote_secrets = Vec::with_capacity(num_secrets as usize);
+		for _ in 0..num_secrets {
+			additional_remote_secrets.push(Readable::read(reader)?);
+		}
+		let contact_secrets = crate::offers::contacts::ContactSecrets::with_additional_secrets(
+			primary_secret,
+			additional_remote_secrets,
+		);
+
+		// Deserialize Offer (as a length-prefixed Vec<u8>)
+		let payer_offer_bytes: Vec<u8> = Readable::read(reader)?;
+		let payer_offer = crate::offers::offer::Offer::try_from(payer_offer_bytes)
+			.map_err(|_| crate::ln::msgs::DecodeError::InvalidValue)?;
+
+		Ok(ContactInfo { contact_secrets, payer_offer })
+	}
+}
 
 /// An Event which you should probably take some action in response to.
 ///
@@ -1064,6 +1113,13 @@ pub enum Event {
 		///
 		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
 		bolt12_invoice: Option<PaidBolt12Invoice>,
+		/// Contact information for BLIP-42 contact management.
+		///
+		/// This is `Some` when paying a BOLT12 offer with contact information enabled,
+		/// containing the contact secrets and payer offer that were sent in the invoice request.
+		///
+		/// This allows the payer to establish a contact relationship with the recipient.
+		contact_info: Option<ContactInfo>,
 	},
 	/// Indicates an outbound payment failed. Individual [`Event::PaymentPathFailed`] events
 	/// provide failure information for each path attempt in the payment, including retries.
@@ -1951,6 +2007,7 @@ impl Writeable for Event {
 				ref amount_msat,
 				ref fee_paid_msat,
 				ref bolt12_invoice,
+				ref contact_info,
 			} => {
 				2u8.write(writer)?;
 				write_tlv_fields!(writer, {
@@ -1960,6 +2017,7 @@ impl Writeable for Event {
 					(5, fee_paid_msat, option),
 					(7, amount_msat, option),
 					(9, bolt12_invoice, option),
+					(11, contact_info, option),
 				});
 			},
 			&Event::PaymentPathFailed {
@@ -2422,13 +2480,15 @@ impl MaybeReadable for Event {
 					let mut amount_msat = None;
 					let mut fee_paid_msat = None;
 					let mut bolt12_invoice = None;
+					let mut contact_info = None;
 					read_tlv_fields!(reader, {
 						(0, payment_preimage, required),
 						(1, payment_hash, option),
 						(3, payment_id, option),
 						(5, fee_paid_msat, option),
 						(7, amount_msat, option),
 						(9, bolt12_invoice, option),
+						(11, contact_info, option),
 					});
 					if payment_hash.is_none() {
 						payment_hash = Some(PaymentHash(
@@ -2442,6 +2502,7 @@ impl MaybeReadable for Event {
 						amount_msat,
 						fee_paid_msat,
 						bolt12_invoice,
+						contact_info,
 					}))
 				};
 				f()

lightning/src/ln/async_payments_tests.rs

@@ -988,7 +988,7 @@ fn ignore_duplicate_invoice() {
 	let args = PassAlongPathArgs::new(sender, route[0], amt_msat, payment_hash, ev);
 	let claimable_ev = do_pass_along_path(args).unwrap();
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
-	let (res, _) =
+	let (res, _, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
 	assert_eq!(res, Some(PaidBolt12Invoice::StaticInvoice(static_invoice.clone())));
 
@@ -1073,7 +1073,7 @@ fn ignore_duplicate_invoice() {
 	};
 
 	// After paying invoice, check that static invoice is ignored.
-	let res = claim_payment(sender, route[0], payment_preimage);
+	let (res, _) = claim_payment(sender, route[0], payment_preimage);
 	assert_eq!(res, Some(PaidBolt12Invoice::Bolt12Invoice(invoice)));
 
 	sender.onion_messenger.handle_onion_message(always_online_node_id, &static_invoice_om);
@@ -1142,7 +1142,7 @@ fn async_receive_flow_success() {
 	let args = PassAlongPathArgs::new(&nodes[0], route[0], amt_msat, payment_hash, ev);
 	let claimable_ev = do_pass_along_path(args).unwrap();
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
-	let (res, _) =
+	let (res, _, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(&nodes[0], route, keysend_preimage));
 	assert_eq!(res, Some(PaidBolt12Invoice::StaticInvoice(static_invoice)));
 }
@@ -2942,7 +2942,7 @@ fn async_payment_e2e() {
 
 	let route: &[&[&Node]] = &[&[sender_lsp, invoice_server, recipient]];
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
-	let (res, _) =
+	let (res, _, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
 	assert_eq!(res, Some(PaidBolt12Invoice::StaticInvoice(static_invoice)));
 }
@@ -3180,7 +3180,7 @@ fn intercepted_hold_htlc() {
 
 	let route: &[&[&Node]] = &[&[lsp, recipient]];
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
-	let (res, _) =
+	let (res, _, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
 	assert_eq!(res, Some(PaidBolt12Invoice::StaticInvoice(static_invoice)));
 }
@@ -3427,7 +3427,7 @@ fn release_htlc_races_htlc_onion_decode() {
 
 	let route: &[&[&Node]] = &[&[sender_lsp, invoice_server, recipient]];
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
-	let (res, _) =
+	let (res, _, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
 	assert_eq!(res, Some(PaidBolt12Invoice::StaticInvoice(static_invoice)));
 }

lightning/src/ln/functional_test_utils.rs

@@ -3033,7 +3033,7 @@ pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM = CM>>(
 	node: &H, expected_payment_preimage: PaymentPreimage,
 	expected_fee_msat_opt: Option<Option<u64>>, expect_per_path_claims: bool,
 	expect_post_ev_mon_update: bool,
-) -> (Option<PaidBolt12Invoice>, Vec<Event>) {
+) -> (Option<PaidBolt12Invoice>, Vec<Event>, Option<crate::events::ContactInfo>) {
 	if expect_post_ev_mon_update {
 		check_added_monitors(node, 0);
 	}
@@ -3051,6 +3051,7 @@ pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM = CM>>(
 	}
 	// We return the invoice because some test may want to check the invoice details.
 	let invoice;
+	let contact_info_result;
 	let mut path_events = Vec::new();
 	let expected_payment_id = match events[0] {
 		Event::PaymentSent {
@@ -3060,6 +3061,7 @@ pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM = CM>>(
 			ref amount_msat,
 			ref fee_paid_msat,
 			ref bolt12_invoice,
+			ref contact_info,
 		} => {
 			assert_eq!(expected_payment_preimage, *payment_preimage);
 			assert_eq!(expected_payment_hash, *payment_hash);
@@ -3070,6 +3072,7 @@ pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM = CM>>(
 				assert!(fee_paid_msat.is_some());
 			}
 			invoice = bolt12_invoice.clone();
+			contact_info_result = contact_info.clone();
 			payment_id.unwrap()
 		},
 		_ => panic!("Unexpected event"),
@@ -3087,7 +3090,7 @@ pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM = CM>>(
 			}
 		}
 	}
-	(invoice, path_events)
+	(invoice, path_events, contact_info_result)
 }
 
 #[macro_export]
@@ -4119,28 +4122,28 @@ pub fn pass_claimed_payment_along_route(args: ClaimAlongRouteArgs) -> u64 {
 }
 pub fn claim_payment_along_route(
 	args: ClaimAlongRouteArgs,
-) -> (Option<PaidBolt12Invoice>, Vec<Event>) {
+) -> (Option<PaidBolt12Invoice>, Vec<Event>, Option<crate::events::ContactInfo>) {
 	let origin_node = args.origin_node;
 	let payment_preimage = args.payment_preimage;
 	let skip_last = args.skip_last;
 	let expected_total_fee_msat = do_claim_payment_along_route(args);
 	if !skip_last {
 		expect_payment_sent!(origin_node, payment_preimage, Some(expected_total_fee_msat))
 	} else {
-		(None, Vec::new())
+		(None, Vec::new(), None)
 	}
 }
 
 pub fn claim_payment<'a, 'b, 'c>(
 	origin_node: &Node<'a, 'b, 'c>, expected_route: &[&Node<'a, 'b, 'c>],
 	our_payment_preimage: PaymentPreimage,
-) -> Option<PaidBolt12Invoice> {
-	claim_payment_along_route(ClaimAlongRouteArgs::new(
+) -> (Option<PaidBolt12Invoice>, Option<crate::events::ContactInfo>) {
+	let result = claim_payment_along_route(ClaimAlongRouteArgs::new(
 		origin_node,
 		&[expected_route],
 		our_payment_preimage,
-	))
-	.0
+	));
+	(result.0, result.2)
 }
 
 pub const TEST_FINAL_CLTV: u32 = 70;