Merge pull request #3078 from jkczyz/2024-05-invoice-event

Asynchronous `Bolt12Invoice` payment

fuzz/src/full_stack.rs

@@ -870,7 +870,7 @@ mod tests {
 		// our network key
 		ext_from_hex("0100000000000000000000000000000000000000000000000000000000000000", &mut test);
 		// config
-		ext_from_hex("0000000000900000000000000000640001000000000001ffff0000000000000000ffffffffffffffffffffffffffffffff0000000000000000ffffffffffffffff000000ffffffff00ffff1a000400010000020400000000040200000a08ffffffffffffffff0001000000", &mut test);
+		ext_from_hex("0000000000900000000000000000640001000000000001ffff0000000000000000ffffffffffffffffffffffffffffffff0000000000000000ffffffffffffffff000000ffffffff00ffff1a000400010000020400000000040200000a08ffffffffffffffff000100000000", &mut test);
 
 		// new outbound connection with id 0
 		ext_from_hex("00", &mut test);
@@ -1383,7 +1383,7 @@ mod tests {
 		// our network key
 		ext_from_hex("0100000000000000000000000000000000000000000000000000000000000000", &mut test);
 		// config
-		ext_from_hex("0000000000900000000000000000640001000000000001ffff0000000000000000ffffffffffffffffffffffffffffffff0000000000000000ffffffffffffffff000000ffffffff00ffff1a000400010000020400000000040200000a08ffffffffffffffff0001000000", &mut test);
+		ext_from_hex("0000000000900000000000000000640001000000000001ffff0000000000000000ffffffffffffffffffffffffffffffff0000000000000000ffffffffffffffff000000ffffffff00ffff1a000400010000020400000000040200000a08ffffffffffffffff000100000000", &mut test);
 
 		// new outbound connection with id 0
 		ext_from_hex("00", &mut test);

lightning/src/events/mod.rs

@@ -19,18 +19,20 @@ pub mod bump_transaction;
 pub use bump_transaction::BumpTransactionEvent;
 
 use crate::blinded_path::payment::{Bolt12OfferContext, Bolt12RefundContext, PaymentContext, PaymentContextRef};
-use crate::sign::SpendableOutputDescriptor;
+use crate::chain::transaction;
 use crate::ln::channelmanager::{InterceptId, PaymentId, RecipientOnionFields};
 use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
 use crate::ln::features::ChannelTypeFeatures;
 use crate::ln::msgs;
 use crate::ln::types::{ChannelId, PaymentPreimage, PaymentHash, PaymentSecret};
-use crate::chain::transaction;
+use crate::offers::invoice::Bolt12Invoice;
+use crate::onion_message::messenger::Responder;
 use crate::routing::gossip::NetworkUpdate;
+use crate::routing::router::{BlindedTail, Path, RouteHop, RouteParameters};
+use crate::sign::SpendableOutputDescriptor;
 use crate::util::errors::APIError;
 use crate::util::ser::{BigSize, FixedLengthReader, Writeable, Writer, MaybeReadable, Readable, RequiredWrapper, UpgradableRequired, WithoutLength};
 use crate::util::string::UntrustedString;
-use crate::routing::router::{BlindedTail, Path, RouteHop, RouteParameters};
 
 use bitcoin::{Transaction, OutPoint};
 use bitcoin::blockdata::locktime::absolute::LockTime;
@@ -736,6 +738,31 @@ pub enum Event {
 		/// The `payment_id` to have been associated with payment for the requested invoice.
 		payment_id: PaymentId,
 	},
+	/// Indicates a [`Bolt12Invoice`] in response to an [`InvoiceRequest`] or a [`Refund`] was
+	/// received.
+	///
+	/// This event will only be generated if [`UserConfig::manually_handle_bolt12_invoices`] is set.
+	/// Use [`ChannelManager::send_payment_for_bolt12_invoice`] to pay the invoice or
+	/// [`ChannelManager::abandon_payment`] to abandon the associated payment. See those docs for
+	/// further details.
+	///
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	/// [`Refund`]: crate::offers::refund::Refund
+	/// [`UserConfig::manually_handle_bolt12_invoices`]: crate::util::config::UserConfig::manually_handle_bolt12_invoices
+	/// [`ChannelManager::send_payment_for_bolt12_invoice`]: crate::ln::channelmanager::ChannelManager::send_payment_for_bolt12_invoice
+	/// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
+	InvoiceReceived {
+		/// The `payment_id` associated with payment for the invoice.
+		payment_id: PaymentId,
+		/// The invoice to pay.
+		invoice: Bolt12Invoice,
+		/// A responder for replying with an [`InvoiceError`] if needed.
+		///
+		/// `None` if the invoice wasn't sent with a reply path.
+		///
+		/// [`InvoiceError`]: crate::offers::invoice_error::InvoiceError
+		responder: Option<Responder>,
+	},
 	/// Indicates an outbound payment we made succeeded (i.e. it made it all the way to its target
 	/// and we got back the payment preimage for it).
 	///
@@ -1492,7 +1519,15 @@ impl Writeable for Event {
 				write_tlv_fields!(writer, {
 					(0, peer_node_id, required),
 				});
-			}
+			},
+			&Event::InvoiceReceived { ref payment_id, ref invoice, ref responder } => {
+				41u8.write(writer)?;
+				write_tlv_fields!(writer, {
+					(0, payment_id, required),
+					(2, invoice, required),
+					(4, responder, option),
+				})
+			},
 			// Note that, going forward, all new events must only write data inside of
 			// `write_tlv_fields`. Versions 0.0.101+ will ignore odd-numbered events that write
 			// data via `write_tlv_fields`.
@@ -1929,6 +1964,21 @@ impl MaybeReadable for Event {
 				};
 				f()
 			},
+			41u8 => {
+				let mut f = || {
+					_init_and_read_len_prefixed_tlv_fields!(reader, {
+						(0, payment_id, required),
+						(2, invoice, required),
+						(4, responder, option),
+					});
+					Ok(Some(Event::InvoiceReceived {
+						payment_id: payment_id.0.unwrap(),
+						invoice: invoice.0.unwrap(),
+						responder,
+					}))
+				};
+				f()
+			},
 			// Versions prior to 0.0.100 did not ignore odd types, instead returning InvalidValue.
 			// Version 0.0.100 failed to properly ignore odd types, possibly resulting in corrupt
 			// reads.

lightning/src/ln/channelmanager.rs

@@ -58,7 +58,7 @@ use crate::ln::onion_utils::{HTLCFailReason, INVALID_ONION_BLINDING};
 use crate::ln::msgs::{ChannelMessageHandler, DecodeError, LightningError};
 #[cfg(test)]
 use crate::ln::outbound_payment;
-use crate::ln::outbound_payment::{Bolt12PaymentError, OutboundPayments, PaymentAttempts, PendingOutboundPayment, SendAlongPathArgs, StaleExpiration};
+use crate::ln::outbound_payment::{OutboundPayments, PaymentAttempts, PendingOutboundPayment, SendAlongPathArgs, StaleExpiration};
 use crate::ln::wire::Encode;
 use crate::offers::invoice::{BlindedPayInfo, Bolt12Invoice, DEFAULT_RELATIVE_EXPIRY, DerivedSigningPubkey, ExplicitSigningPubkey, InvoiceBuilder, UnsignedBolt12Invoice};
 use crate::offers::invoice_error::InvoiceError;
@@ -105,7 +105,7 @@ use core::time::Duration;
 use core::ops::Deref;
 
 // Re-export this for use in the public API.
-pub use crate::ln::outbound_payment::{PaymentSendFailure, ProbeSendFailure, Retry, RetryableSendFailure, RecipientOnionFields};
+pub use crate::ln::outbound_payment::{Bolt12PaymentError, PaymentSendFailure, ProbeSendFailure, Retry, RetryableSendFailure, RecipientOnionFields};
 use crate::ln::script::ShutdownScript;
 
 // We hold various information about HTLC relay in the HTLC objects in Channel itself:
@@ -3996,7 +3996,36 @@ where
 		self.pending_outbound_payments.test_set_payment_metadata(payment_id, new_payment_metadata);
 	}
 
-	pub(super) fn send_payment_for_bolt12_invoice(&self, invoice: &Bolt12Invoice, payment_id: PaymentId) -> Result<(), Bolt12PaymentError> {
+	/// Pays the [`Bolt12Invoice`] associated with the `payment_id` encoded in its `payer_metadata`.
+	///
+	/// The invoice's `payer_metadata` is used to authenticate that the invoice was indeed requested
+	/// before attempting a payment. [`Bolt12PaymentError::UnexpectedInvoice`] is returned if this
+	/// fails or if the encoded `payment_id` is not recognized. The latter may happen once the
+	/// payment is no longer tracked because the payment was attempted after:
+	/// - an invoice for the `payment_id` was already paid,
+	/// - one full [timer tick] has elapsed since initially requesting the invoice when paying an
+	///   offer, or
+	/// - the refund corresponding to the invoice has already expired.
+	///
+	/// To retry the payment, request another invoice using a new `payment_id`.
+	///
+	/// Attempting to pay the same invoice twice while the first payment is still pending will
+	/// result in a [`Bolt12PaymentError::DuplicateInvoice`].
+	///
+	/// Otherwise, either [`Event::PaymentSent`] or [`Event::PaymentFailed`] are used to indicate
+	/// whether or not the payment was successful.
+	///
+	/// [timer tick]: Self::timer_tick_occurred
+	pub fn send_payment_for_bolt12_invoice(&self, invoice: &Bolt12Invoice) -> Result<(), Bolt12PaymentError> {
+		let secp_ctx = &self.secp_ctx;
+		let expanded_key = &self.inbound_payment_key;
+		match invoice.verify(expanded_key, secp_ctx) {
+			Ok(payment_id) => self.send_payment_for_verified_bolt12_invoice(invoice, payment_id),
+			Err(()) => Err(Bolt12PaymentError::UnexpectedInvoice),
+		}
+	}
+
+	fn send_payment_for_verified_bolt12_invoice(&self, invoice: &Bolt12Invoice, payment_id: PaymentId) -> Result<(), Bolt12PaymentError> {
 		let best_block_height = self.best_block.read().unwrap().height;
 		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
 		self.pending_outbound_payments
@@ -10272,42 +10301,45 @@ where
 				};
 
 				match response {
-					Ok(invoice) => return responder.respond(OffersMessage::Invoice(invoice)),
-					Err(error) => return responder.respond(OffersMessage::InvoiceError(error.into())),
+					Ok(invoice) => responder.respond(OffersMessage::Invoice(invoice)),
+					Err(error) => responder.respond(OffersMessage::InvoiceError(error.into())),
 				}
 			},
 			OffersMessage::Invoice(invoice) => {
-				let response = invoice
-					.verify(expanded_key, secp_ctx)
-					.map_err(|()| InvoiceError::from_string("Unrecognized invoice".to_owned()))
-					.and_then(|payment_id| {
+				let result = match invoice.verify(expanded_key, secp_ctx) {
+					Ok(payment_id) => {
 						let features = self.bolt12_invoice_features();
 						if invoice.invoice_features().requires_unknown_bits_from(&features) {
 							Err(InvoiceError::from(Bolt12SemanticError::UnknownRequiredFeatures))
+						} else if self.default_configuration.manually_handle_bolt12_invoices {
+							let event = Event::InvoiceReceived { payment_id, invoice, responder };
+							self.pending_events.lock().unwrap().push_back((event, None));
+							return ResponseInstruction::NoResponse;
 						} else {
-							self.send_payment_for_bolt12_invoice(&invoice, payment_id)
+							self.send_payment_for_verified_bolt12_invoice(&invoice, payment_id)
 								.map_err(|e| {
 									log_trace!(self.logger, "Failed paying invoice: {:?}", e);
 									InvoiceError::from_string(format!("{:?}", e))
 								})
 						}
-					});
+					},
+					Err(()) => Err(InvoiceError::from_string("Unrecognized invoice".to_owned())),
+				};
 
-				match (responder, response) {
-					(Some(responder), Err(e)) => responder.respond(OffersMessage::InvoiceError(e)),
-					(None, Err(_)) => {
-						log_trace!(
-							self.logger,
-							"A response was generated, but there is no reply_path specified for sending the response."
-						);
-						return ResponseInstruction::NoResponse;
-					}
-					_ => return ResponseInstruction::NoResponse,
+				match result {
+					Ok(()) => ResponseInstruction::NoResponse,
+					Err(e) => match responder {
+						Some(responder) => responder.respond(OffersMessage::InvoiceError(e)),
+						None => {
+							log_trace!(self.logger, "No reply path for sending invoice error: {:?}", e);
+							ResponseInstruction::NoResponse
+						},
+					},
 				}
 			},
 			OffersMessage::InvoiceError(invoice_error) => {
 				log_trace!(self.logger, "Received invoice_error: {}", invoice_error);
-				return ResponseInstruction::NoResponse;
+				ResponseInstruction::NoResponse
 			},
 		}
 	}

lightning/src/ln/offers_tests.rs

@@ -46,9 +46,10 @@ use core::time::Duration;
 use crate::blinded_path::{BlindedPath, IntroductionNode};
 use crate::blinded_path::payment::{Bolt12OfferContext, Bolt12RefundContext, PaymentContext};
 use crate::events::{Event, MessageSendEventsProvider, PaymentPurpose};
-use crate::ln::channelmanager::{MAX_SHORT_LIVED_RELATIVE_EXPIRY, PaymentId, RecentPaymentDetails, Retry, self};
+use crate::ln::channelmanager::{Bolt12PaymentError, MAX_SHORT_LIVED_RELATIVE_EXPIRY, PaymentId, RecentPaymentDetails, Retry, self};
 use crate::ln::functional_test_utils::*;
 use crate::ln::msgs::{ChannelMessageHandler, Init, NodeAnnouncement, OnionMessage, OnionMessageHandler, RoutingMessageHandler, SocketAddress, UnsignedGossipMessage, UnsignedNodeAnnouncement};
+use crate::ln::outbound_payment::IDEMPOTENCY_TIMEOUT_TICKS;
 use crate::offers::invoice::Bolt12Invoice;
 use crate::offers::invoice_error::InvoiceError;
 use crate::offers::invoice_request::{InvoiceRequest, InvoiceRequestFields};
@@ -865,6 +866,90 @@ fn pays_for_refund_without_blinded_paths() {
 	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
+/// Checks that a deferred invoice can be paid asynchronously from an Event::InvoiceReceived.
+#[test]
+fn pays_bolt12_invoice_asynchronously() {
+	let mut manually_pay_cfg = test_default_channel_config();
+	manually_pay_cfg.manually_handle_bolt12_invoices = true;
+
+	let chanmon_cfgs = create_chanmon_cfgs(2);
+	let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+	let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, Some(manually_pay_cfg)]);
+	let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+
+	create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 10_000_000, 1_000_000_000);
+
+	let alice = &nodes[0];
+	let alice_id = alice.node.get_our_node_id();
+	let bob = &nodes[1];
+	let bob_id = bob.node.get_our_node_id();
+
+	let offer = alice.node
+		.create_offer_builder(None).unwrap()
+		.amount_msats(10_000_000)
+		.build().unwrap();
+
+	let payment_id = PaymentId([1; 32]);
+	bob.node.pay_for_offer(&offer, None, None, None, payment_id, Retry::Attempts(0), None).unwrap();
+	expect_recent_payment!(bob, RecentPaymentDetails::AwaitingInvoice, payment_id);
+
+	let onion_message = bob.onion_messenger.next_onion_message_for_peer(alice_id).unwrap();
+	alice.onion_messenger.handle_onion_message(&bob_id, &onion_message);
+
+	let (invoice_request, _) = extract_invoice_request(alice, &onion_message);
+	let payment_context = PaymentContext::Bolt12Offer(Bolt12OfferContext {
+		offer_id: offer.id(),
+		invoice_request: InvoiceRequestFields {
+			payer_id: invoice_request.payer_id(),
+			quantity: None,
+			payer_note_truncated: None,
+		},
+	});
+
+	let onion_message = alice.onion_messenger.next_onion_message_for_peer(bob_id).unwrap();
+	bob.onion_messenger.handle_onion_message(&alice_id, &onion_message);
+
+	let invoice = match get_event!(bob, Event::InvoiceReceived) {
+		Event::InvoiceReceived { payment_id: actual_payment_id, invoice, .. } => {
+			assert_eq!(actual_payment_id, payment_id);
+			invoice
+		},
+		_ => panic!("No Event::InvoiceReceived"),
+	};
+	assert_eq!(invoice.amount_msats(), 10_000_000);
+	assert_ne!(invoice.signing_pubkey(), alice_id);
+	assert!(!invoice.payment_paths().is_empty());
+	for (_, path) in invoice.payment_paths() {
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(alice_id));
+	}
+
+	assert!(bob.node.send_payment_for_bolt12_invoice(&invoice).is_ok());
+	assert_eq!(
+		bob.node.send_payment_for_bolt12_invoice(&invoice),
+		Err(Bolt12PaymentError::DuplicateInvoice),
+	);
+
+	route_bolt12_payment(bob, &[alice], &invoice);
+	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
+
+	claim_bolt12_payment(bob, &[alice], payment_context);
+	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
+
+	assert_eq!(
+		bob.node.send_payment_for_bolt12_invoice(&invoice),
+		Err(Bolt12PaymentError::DuplicateInvoice),
+	);
+
+	for _ in 0..=IDEMPOTENCY_TIMEOUT_TICKS {
+		bob.node.timer_tick_occurred();
+	}
+
+	assert_eq!(
+		bob.node.send_payment_for_bolt12_invoice(&invoice),
+		Err(Bolt12PaymentError::UnexpectedInvoice),
+	);
+}
+
 /// Fails creating an offer when a blinded path cannot be created without exposing the node's id.
 #[test]
 fn fails_creating_offer_without_blinded_paths() {

lightning/src/ln/outbound_payment.rs

@@ -501,9 +501,9 @@ pub enum PaymentSendFailure {
 	},
 }
 
-/// An error when attempting to pay a BOLT 12 invoice.
+/// An error when attempting to pay a [`Bolt12Invoice`].
 #[derive(Clone, Debug, PartialEq, Eq)]
-pub(super) enum Bolt12PaymentError {
+pub enum Bolt12PaymentError {
 	/// The invoice was not requested.
 	UnexpectedInvoice,
 	/// Payment for an invoice with the corresponding [`PaymentId`] was already initiated.

lightning/src/offers/invoice.rs

@@ -124,7 +124,7 @@ use crate::offers::parse::{Bolt12ParseError, Bolt12SemanticError, ParsedMessage}
 use crate::offers::payer::{PAYER_METADATA_TYPE, PayerTlvStream, PayerTlvStreamRef};
 use crate::offers::refund::{IV_BYTES as REFUND_IV_BYTES, Refund, RefundContents};
 use crate::offers::signer;
-use crate::util::ser::{HighZeroBytesDroppedBigSize, Iterable, SeekReadable, WithoutLength, Writeable, Writer};
+use crate::util::ser::{HighZeroBytesDroppedBigSize, Iterable, Readable, SeekReadable, WithoutLength, Writeable, Writer};
 use crate::util::string::PrintableString;
 
 #[allow(unused_imports)]
@@ -1119,6 +1119,13 @@ impl Writeable for Bolt12Invoice {
 	}
 }
 
+impl Readable for Bolt12Invoice {
+	fn read<R: io::Read>(reader: &mut R) -> Result<Self, DecodeError> {
+		let bytes: WithoutLength<Vec<u8>> = Readable::read(reader)?;
+		Self::try_from(bytes.0).map_err(|_| DecodeError::InvalidValue)
+	}
+}
+
 impl Writeable for InvoiceContents {
 	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 		self.as_tlv_stream().write(writer)

lightning/src/onion_message/messenger.rs

@@ -325,12 +325,18 @@ impl OnionMessageRecipient {
 
 /// The `Responder` struct creates an appropriate [`ResponseInstruction`]
 /// for responding to a message.
+#[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Responder {
 	/// The path along which a response can be sent.
 	reply_path: BlindedPath,
 	path_id: Option<[u8; 32]>
 }
 
+impl_writeable_tlv_based!(Responder, {
+	(0, reply_path, required),
+	(2, path_id, option),
+});
+
 impl Responder {
 	/// Creates a new [`Responder`] instance with the provided reply path.
 	pub(super) fn new(reply_path: BlindedPath, path_id: Option<[u8; 32]>) -> Self {