Add BLIP-42 contact support for BOLT12 payments

This adds support for BLIP-42, enabling bidirectional contact
establishment between payers and payees in BOLT12 payments.

Sender side:
- Add `send_with_contact` and `send_using_amount_with_contact` methods
  to `Bolt12Payment` that accept optional `ContactSecrets` and a payer
  offer to include in the invoice request.

Receiver side:
- Extend `Event::PaymentReceived` with `contact_secret` and `payer_offer`
  fields, which are extracted from incoming BOLT12 payments when present.

The implementation is stateless - ldk-node surfaces the BLIP-42 data
to the application layer without managing contact state internally.

See BLIP-42: https://github.com/lightning/blips/blob/master/blip-0042.md

Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>

Author: vincenzopalazzo

Cargo.toml

@@ -39,17 +39,17 @@ default = []
 #lightning-liquidity = { version = "0.2.0", features = ["std"] }
 #lightning-macros = { version = "0.2.0" }
 
-lightning = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc", features = ["std"] }
-lightning-types = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc" }
-lightning-invoice = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc", features = ["std"] }
-lightning-net-tokio = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc" }
-lightning-persister = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc", features = ["tokio"] }
-lightning-background-processor = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc" }
-lightning-rapid-gossip-sync = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc" }
-lightning-block-sync = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc", features = ["rest-client", "rpc-client", "tokio"] }
-lightning-transaction-sync = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc", features = ["esplora-async-https", "time", "electrum-rustls-ring"] }
-lightning-liquidity = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc", features = ["std"] }
-lightning-macros = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc" }
+lightning = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2", features = ["std"] }
+lightning-types = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2" }
+lightning-invoice = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2", features = ["std"] }
+lightning-net-tokio = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2" }
+lightning-persister = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2", features = ["tokio"] }
+lightning-background-processor = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2" }
+lightning-rapid-gossip-sync = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2" }
+lightning-block-sync = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2", features = ["rest-client", "rpc-client", "tokio"] }
+lightning-transaction-sync = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2", features = ["esplora-async-https", "time", "electrum-rustls-ring"] }
+lightning-liquidity = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2", features = ["std"] }
+lightning-macros = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2" }
 
 bdk_chain = { version = "0.23.0", default-features = false, features = ["std"] }
 bdk_esplora = { version = "0.22.0", default-features = false, features = ["async-https-rustls", "tokio"]}
@@ -82,7 +82,7 @@ prost = { version = "0.11.6", default-features = false}
 winapi = { version = "0.3", features = ["winbase"] }
 
 [dev-dependencies]
-lightning = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "5bf0d1e2427d759fc1ba4108ddc7e9b32e8bacfc", features = ["std", "_test_utils"] }
+lightning = { git = "https://github.com/vincenzopalazzo/rust-lightning", branch = "macros/blip02-prep-v2", features = ["std", "_test_utils"] }
 proptest = "1.0.0"
 regex = "1.5.6"
 criterion = { version = "0.7.0", features = ["async_tokio"] }

bindings/ldk_node.udl

@@ -227,6 +227,12 @@ interface Bolt12Payment {
 	PaymentId send([ByRef]Offer offer, u64? quantity, string? payer_note, RouteParametersConfig? route_parameters);
 	[Throws=NodeError]
 	PaymentId send_using_amount([ByRef]Offer offer, u64 amount_msat, u64? quantity, string? payer_note, RouteParametersConfig? route_parameters);
+	/// Send a payment with BLIP-42 contact information for contact establishment.
+	[Throws=NodeError]
+	PaymentId send_with_contact([ByRef]Offer offer, u64? quantity, string? payer_note, RouteParametersConfig? route_parameters, ContactSecrets? contact_secrets, Offer? payer_offer);
+	/// Send a payment with an explicit amount and BLIP-42 contact information.
+	[Throws=NodeError]
+	PaymentId send_using_amount_with_contact([ByRef]Offer offer, u64 amount_msat, u64? quantity, string? payer_note, RouteParametersConfig? route_parameters, ContactSecrets? contact_secrets, Offer? payer_offer);
 	[Throws=NodeError]
 	Offer receive(u64 amount_msat, [ByRef]string description, u32? expiry_secs, u64? quantity);
 	[Throws=NodeError]
@@ -402,7 +408,7 @@ enum VssHeaderProviderError {
 interface Event {
 	PaymentSuccessful(PaymentId? payment_id, PaymentHash payment_hash, PaymentPreimage? payment_preimage, u64? fee_paid_msat);
 	PaymentFailed(PaymentId? payment_id, PaymentHash? payment_hash, PaymentFailureReason? reason);
-	PaymentReceived(PaymentId? payment_id, PaymentHash payment_hash, u64 amount_msat, sequence<CustomTlvRecord> custom_records);
+	PaymentReceived(PaymentId? payment_id, PaymentHash payment_hash, u64 amount_msat, sequence<CustomTlvRecord> custom_records, sequence<u8>? contact_secret, string? payer_offer);
 	PaymentClaimable(PaymentId payment_id, PaymentHash payment_hash, u64 claimable_amount_msat, u32? claim_deadline, sequence<CustomTlvRecord> custom_records);
 	PaymentForwarded(ChannelId prev_channel_id, ChannelId next_channel_id, UserChannelId?
 	prev_user_channel_id, UserChannelId? next_user_channel_id, PublicKey? prev_node_id, PublicKey? next_node_id, u64? total_fee_earned_msat, u64? skimmed_fee_msat, boolean claim_from_onchain_tx, u64? outbound_amount_forwarded_msat);
@@ -763,6 +769,18 @@ dictionary RouteHintHop {
 	RoutingFees fees;
 };
 
+/// BLIP-42 Contact secrets used for mutual authentication in payments.
+///
+/// When sending payments with contact information, the primary secret is sent to establish
+/// the contact relationship. Additional remote secrets can be stored for recognizing
+/// payments from contacts who independently added us.
+dictionary ContactSecrets {
+	/// The primary secret (32 bytes) used when sending payments to identify ourselves.
+	sequence<u8> primary_secret;
+	/// Additional secrets received from contacts for recognizing their payments.
+	sequence<sequence<u8>> additional_remote_secrets;
+};
+
 [Traits=(Debug, Display, Eq)]
 interface Bolt11Invoice {
 	[Throws=NodeError, Name=from_str]

src/event.rs

@@ -106,6 +106,25 @@ pub enum Event {
 		amount_msat: u64,
 		/// Custom TLV records received on the payment
 		custom_records: Vec<CustomTlvRecord>,
+		/// BLIP-42: The contact secret sent by the payer.
+		///
+		/// If present, this indicates the payer wants to establish a contact relationship.
+		/// The recipient can use this secret along with `payer_offer` to add the payer as a contact.
+		///
+		/// See [BLIP-42](https://github.com/lightning/blips/blob/master/blip-0042.md) for more details.
+		///
+		/// Will only be `Some` for BOLT12 payments where the payer included contact information.
+		/// The value is 32 bytes.
+		contact_secret: Option<Vec<u8>>,
+		/// BLIP-42: The payer's BOLT12 offer.
+		///
+		/// If present, this is the payer's offer that can be used to pay them back or establish
+		/// bidirectional contact. This is typically a compact offer with minimal blinded paths.
+		///
+		/// See [BLIP-42](https://github.com/lightning/blips/blob/master/blip-0042.md) for more details.
+		///
+		/// Will only be `Some` for BOLT12 payments where the payer included their offer.
+		payer_offer: Option<String>,
 	},
 	/// A payment has been forwarded.
 	PaymentForwarded {
@@ -275,6 +294,9 @@ impl_writeable_tlv_based_enum!(Event,
 		(1, payment_id, option),
 		(2, amount_msat, required),
 		(3, custom_records, optional_vec),
+		// BLIP-42 contact fields
+		(5, contact_secret, option),
+		(7, payer_offer, option),
 	},
 	(3, ChannelReady) => {
 		(0, channel_id, required),
@@ -938,6 +960,21 @@ where
 					amount_msat,
 				);
 
+				// Extract BLIP-42 contact fields from Bolt12 payments
+				let (contact_secret, payer_offer) = match &purpose {
+					PaymentPurpose::Bolt12OfferPayment { payment_context, .. } => {
+						let contact_secret =
+							payment_context.invoice_request.contact_secret.map(|s| s.to_vec());
+						let payer_offer = payment_context
+							.invoice_request
+							.payer_offer
+							.as_ref()
+							.map(|offer| offer.to_string());
+						(contact_secret, payer_offer)
+					},
+					_ => (None, None),
+				};
+
 				let update = match purpose {
 					PaymentPurpose::Bolt11InvoicePayment {
 						payment_preimage,
@@ -1008,6 +1045,8 @@ where
 					custom_records: onion_fields
 						.map(|cf| cf.custom_tlvs().into_iter().map(|tlv| tlv.into()).collect())
 						.unwrap_or_default(),
+					contact_secret,
+					payer_offer,
 				};
 				match self.event_queue.add_event(event).await {
 					Ok(_) => return Ok(()),

src/lib.rs

@@ -161,7 +161,10 @@ use types::{
 	Broadcaster, BumpTransactionEventHandler, ChainMonitor, ChannelManager, DynStore, Graph,
 	KeysManager, OnionMessenger, PaymentStore, PeerManager, Router, Scorer, Sweeper, Wallet,
 };
-pub use types::{ChannelDetails, CustomTlvRecord, PeerDetails, SyncAndAsyncKVStore, UserChannelId};
+pub use types::{
+	ChannelDetails, ContactSecrets, CustomTlvRecord, PeerDetails, SyncAndAsyncKVStore,
+	UserChannelId,
+};
 pub use {
 	bip39, bitcoin, lightning, lightning_invoice, lightning_liquidity, lightning_types, tokio,
 	vss_client,