Provide an InvoiceGenerated event for offers

When responding to an InvoiceRequest for an Offer, provide an event when
an invoice has been generated. This allows event handler to know when an
inbound payment may occur along with information from the invoice such
as metadata, payer_id, and payment_hash.

Author: jkczyz

lightning/src/events/mod.rs

@@ -25,6 +25,7 @@ use crate::ln::features::ChannelTypeFeatures;
 use crate::ln::msgs;
 use crate::ln::{ChannelId, PaymentPreimage, PaymentHash, PaymentSecret};
 use crate::chain::transaction;
+use crate::offers::invoice::Bolt12Invoice;
 use crate::routing::gossip::NetworkUpdate;
 use crate::util::errors::APIError;
 use crate::util::ser::{BigSize, FixedLengthReader, Writeable, Writer, MaybeReadable, Readable, RequiredWrapper, UpgradableRequired, WithoutLength};
@@ -582,6 +583,39 @@ pub enum Event {
 		/// The `payment_id` to have been associated with payment for the requested invoice.
 		payment_id: PaymentId,
 	},
+	/// Indicates that a [`Bolt12Invoice`] was generated in response to an [`InvoiceRequest`] and is
+	/// being prepared to be sent via an [`OnionMessage`].
+	///
+	/// Note that this doesn't necessarily mean that the invoice was sent and -- once sent -- it may
+	/// never reach its destination because of the unreliable nature of onion messages. Any of the
+	/// following scenarios may occur.
+	/// - Dropped by a node along the path to the destination
+	/// - Dropped upon node restart prior to being sent
+	/// - Buffered waiting to be sent by [`PeerManager`]
+	/// - Buffered waiting for an [`Event::ConnectionNeeded`] to be handled and peer connected
+	/// - Dropped waiting too long for such a peer connection
+	/// - Dropped because the onion message buffer was full
+	/// - Dropped because the [`MessageRouter`] failed to find an [`OnionMessagePath`] to the
+	///   destination
+	///
+	/// Thus, this event is largely for informational purposes as the corresponding [`Offer`] and
+	/// [`InvoiceRequest`] fields are accessible from the invoice. In particular:
+	/// - [`Bolt12Invoice::metadata`] can help identify the corresponding [`Offer`]
+	/// - A common [`Bolt12Invoice::payer_id`] indicates the payer sent multiple requests for
+	///   redundancy, though in that case the [`Bolt12Invoice::payment_hash`] used may be different.
+	///
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	/// [`OnionMessage`]: crate::ln::msgs::OnionMessage
+	/// [`PeerManager`]: crate::ln::peer_handler::PeerManager
+	/// [`MessageRouter`]: crate::onion_message::messenger::MessageRouter
+	/// [`OnionMessagePath`]: crate::onion_message::messenger::OnionMessagePath
+	/// [`Offer`]: crate::offers::offer::Offer
+	InvoiceGenerated {
+		/// An invoice that was generated in response to an [`InvoiceRequest`].
+		///
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		invoice: Bolt12Invoice,
+	},
 	/// 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).
 	///
@@ -1262,6 +1296,12 @@ impl Writeable for Event {
 				35u8.write(writer)?;
 				// Never write ConnectionNeeded events as buffered onion messages aren't serialized.
 			},
+			&Event::InvoiceGenerated { ref invoice } => {
+				37u8.write(writer)?;
+				write_tlv_fields!(writer, {
+					(0, invoice, required),
+				})
+			},
 			// 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`.
@@ -1668,6 +1708,18 @@ impl MaybeReadable for Event {
 			},
 			// Note that we do not write a length-prefixed TLV for ConnectionNeeded events.
 			35u8 => Ok(None),
+			37u8 => {
+				let f = || {
+					let mut invoice_bytes = WithoutLength(Vec::new());
+					read_tlv_fields!(reader, {
+						(0, invoice_bytes, required),
+					});
+					let invoice = Bolt12Invoice::try_from(invoice_bytes.0)
+						.map_err(|_| msgs::DecodeError::InvalidValue)?;
+					Ok(Some(Event::InvoiceGenerated { invoice }))
+				};
+				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

@@ -9486,7 +9486,11 @@ where
 				};
 
 				match response {
-					Ok(invoice) => Some(OffersMessage::Invoice(invoice)),
+					Ok(invoice) => {
+						let event = Event::InvoiceGenerated { invoice: invoice.clone() };
+						self.pending_events.lock().unwrap().push_back((event, None));
+						Some(OffersMessage::Invoice(invoice))
+					},
 					Err(error) => Some(OffersMessage::InvoiceError(error.into())),
 				}
 			},

lightning/src/ln/offers_tests.rs

@@ -211,6 +211,24 @@ fn extract_invoice_error<'a, 'b, 'c>(
 	}
 }
 
+fn expect_invoice_generated_event<'a, 'b, 'c, 'd>(
+	node: &'a Node<'b, 'c, 'd>, expected_invoice: &Bolt12Invoice
+) {
+	use crate::io::Cursor;
+	use crate::util::ser::MaybeReadable;
+	use crate::util::ser::Writeable;
+
+	let event = get_event!(node, Event::InvoiceGenerated);
+	match &event {
+		Event::InvoiceGenerated { invoice } => assert_eq!(invoice, expected_invoice),
+		_ => panic!(),
+	}
+
+	let mut bytes = Vec::new();
+	event.write(&mut bytes).unwrap();
+	assert_eq!(Some(event), MaybeReadable::read(&mut Cursor::new(&bytes)).unwrap());
+}
+
 /// Checks that blinded paths without Tor-only nodes are preferred when constructing an offer.
 #[test]
 fn prefers_non_tor_nodes_in_blinded_paths() {
@@ -403,6 +421,8 @@ fn creates_and_pays_for_offer_using_two_hop_blinded_path() {
 	david.onion_messenger.handle_onion_message(&charlie_id, &onion_message);
 
 	let invoice = extract_invoice(david, &onion_message);
+	expect_invoice_generated_event(alice, &invoice);
+
 	assert_eq!(invoice.amount_msats(), 10_000_000);
 	assert_ne!(invoice.signing_pubkey(), alice_id);
 	assert!(!invoice.payment_paths().is_empty());
@@ -540,6 +560,8 @@ fn creates_and_pays_for_offer_using_one_hop_blinded_path() {
 	bob.onion_messenger.handle_onion_message(&alice_id, &onion_message);
 
 	let invoice = extract_invoice(bob, &onion_message);
+	expect_invoice_generated_event(alice, &invoice);
+
 	assert_eq!(invoice.amount_msats(), 10_000_000);
 	assert_ne!(invoice.signing_pubkey(), alice_id);
 	assert!(!invoice.payment_paths().is_empty());
@@ -644,6 +666,8 @@ fn pays_for_offer_without_blinded_paths() {
 	bob.onion_messenger.handle_onion_message(&alice_id, &onion_message);
 
 	let invoice = extract_invoice(bob, &onion_message);
+	expect_invoice_generated_event(alice, &invoice);
+
 	route_bolt12_payment(bob, &[alice], &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);