Return the invoice when requesting a refund

When sending an invoice for a refund, information from the invoice may
be useful for caller. For instance, the payment_hash can be used to
track whether the refund was paid. Return the invoice to facilitate this
use case.

Author: jkczyz

lightning/src/events/mod.rs

@@ -584,7 +584,9 @@ pub enum Event {
 		payment_id: PaymentId,
 	},
 	/// Indicates that a [`Bolt12Invoice`] was generated in response to an [`InvoiceRequest`] and is
-	/// being prepared to be sent via an [`OnionMessage`].
+	/// being prepared to be sent via an [`OnionMessage`]. The event is provided only for invoices
+	/// corresponding to an [`Offer`], not for a [`Refund`]. For the latter, the invoice is returned
+	/// by [`ChannelManager::request_refund_payment`].
 	///
 	/// 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
@@ -606,10 +608,12 @@ pub enum Event {
 	///
 	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 	/// [`OnionMessage`]: crate::ln::msgs::OnionMessage
+	/// [`Offer`]: crate::offers::offer::Offer
+	/// [`Refund`]: crate::offers::refund::Refund
+	/// [`ChannelManager::request_refund_payment`]: crate::ln::channelmanager::ChannelManager::request_refund_payment
 	/// [`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`].
 		///

lightning/src/ln/channelmanager.rs

@@ -7906,7 +7906,7 @@ where
 	///
 	/// The resulting invoice uses a [`PaymentHash`] recognized by the [`ChannelManager`] and a
 	/// [`BlindedPath`] containing the [`PaymentSecret`] needed to reconstruct the corresponding
-	/// [`PaymentPreimage`].
+	/// [`PaymentPreimage`]. It is returned purely for informational purposes.
 	///
 	/// # Limitations
 	///
@@ -7921,7 +7921,9 @@ where
 	/// path for the invoice.
 	///
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
-	pub fn request_refund_payment(&self, refund: &Refund) -> Result<(), Bolt12SemanticError> {
+	pub fn request_refund_payment(
+		&self, refund: &Refund
+	) -> Result<Bolt12Invoice, Bolt12SemanticError> {
 		let expanded_key = &self.inbound_payment_key;
 		let entropy = &*self.entropy_source;
 		let secp_ctx = &self.secp_ctx;
@@ -7954,7 +7956,7 @@ where
 				let mut pending_offers_messages = self.pending_offers_messages.lock().unwrap();
 				if refund.paths().is_empty() {
 					let message = new_pending_onion_message(
-						OffersMessage::Invoice(invoice),
+						OffersMessage::Invoice(invoice.clone()),
 						Destination::Node(refund.payer_id()),
 						Some(reply_path),
 					);
@@ -7970,7 +7972,7 @@ where
 					}
 				}
 
-				Ok(())
+				Ok(invoice)
 			},
 			Err(()) => Err(Bolt12SemanticError::InvalidAmount),
 		}

lightning/src/ln/offers_tests.rs

@@ -492,7 +492,7 @@ fn creates_and_pays_for_refund_using_two_hop_blinded_path() {
 	}
 	expect_recent_payment!(david, RecentPaymentDetails::AwaitingInvoice, payment_id);
 
-	alice.node.request_refund_payment(&refund).unwrap();
+	let expected_invoice = alice.node.request_refund_payment(&refund).unwrap();
 
 	connect_peers(alice, charlie);
 
@@ -503,6 +503,8 @@ fn creates_and_pays_for_refund_using_two_hop_blinded_path() {
 	david.onion_messenger.handle_onion_message(&charlie_id, &onion_message);
 
 	let invoice = extract_invoice(david, &onion_message);
+	assert_eq!(invoice, expected_invoice);
+
 	assert_eq!(invoice.amount_msats(), 10_000_000);
 	assert_ne!(invoice.signing_pubkey(), alice_id);
 	assert!(!invoice.payment_paths().is_empty());
@@ -610,12 +612,14 @@ fn creates_and_pays_for_refund_using_one_hop_blinded_path() {
 	}
 	expect_recent_payment!(bob, RecentPaymentDetails::AwaitingInvoice, payment_id);
 
-	alice.node.request_refund_payment(&refund).unwrap();
+	let expected_invoice = alice.node.request_refund_payment(&refund).unwrap();
 
 	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 = extract_invoice(bob, &onion_message);
+	assert_eq!(invoice, expected_invoice);
+
 	assert_eq!(invoice.amount_msats(), 10_000_000);
 	assert_ne!(invoice.signing_pubkey(), alice_id);
 	assert!(!invoice.payment_paths().is_empty());
@@ -704,12 +708,14 @@ fn pays_for_refund_without_blinded_paths() {
 	assert!(refund.paths().is_empty());
 	expect_recent_payment!(bob, RecentPaymentDetails::AwaitingInvoice, payment_id);
 
-	alice.node.request_refund_payment(&refund).unwrap();
+	let expected_invoice = alice.node.request_refund_payment(&refund).unwrap();
 
 	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 = extract_invoice(bob, &onion_message);
+	assert_eq!(invoice, expected_invoice);
+
 	route_bolt12_payment(bob, &[alice], &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);