BOLT 12 Invoice payments

lightning/src/events/mod.rs

@@ -508,6 +508,14 @@ pub enum Event {
 		/// serialized prior to LDK version 0.0.117.
 		sender_intended_total_msat: Option<u64>,
 	},
+	/// Indicates a request for an invoice failed to yield a response in a reasonable amount of time
+	/// or was explicitly abandoned by [`ChannelManager::abandon_payment`].
+	///
+	/// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
+	InvoiceRequestFailed {
+		/// The `payment_id` to have been associated with payment for the requested invoice.
+		payment_id: PaymentId,
+	},
 	/// 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).
 	///
@@ -1148,6 +1156,12 @@ impl Writeable for Event {
 					(8, funding_txo, required),
 				});
 			},
+			&Event::InvoiceRequestFailed { ref payment_id } => {
+				33u8.write(writer)?;
+				write_tlv_fields!(writer, {
+					(0, payment_id, 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`.
@@ -1535,6 +1549,17 @@ impl MaybeReadable for Event {
 				};
 				f()
 			},
+			33u8 => {
+				let f = || {
+					_init_and_read_len_prefixed_tlv_fields!(reader, {
+						(0, payment_id, required),
+					});
+					Ok(Some(Event::InvoiceRequestFailed {
+						payment_id: payment_id.0.unwrap(),
+					}))
+				};
+				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

@@ -1341,11 +1341,6 @@ const CHECK_CLTV_EXPIRY_SANITY_2: u32 = MIN_CLTV_EXPIRY_DELTA as u32 - LATENCY_G
 /// The number of ticks of [`ChannelManager::timer_tick_occurred`] until expiry of incomplete MPPs
 pub(crate) const MPP_TIMEOUT_TICKS: u8 = 3;
 
-/// The number of ticks of [`ChannelManager::timer_tick_occurred`] until we time-out the
-/// idempotency of payments by [`PaymentId`]. See
-/// [`OutboundPayments::remove_stale_resolved_payments`].
-pub(crate) const IDEMPOTENCY_TIMEOUT_TICKS: u8 = 7;
-
 /// The number of ticks of [`ChannelManager::timer_tick_occurred`] where a peer is disconnected
 /// until we mark the channel disabled and gossip the update.
 pub(crate) const DISABLE_GOSSIP_TICKS: u8 = 10;
@@ -1688,6 +1683,11 @@ pub enum ChannelShutdownState {
 /// These include payments that have yet to find a successful path, or have unresolved HTLCs.
 #[derive(Debug, PartialEq)]
 pub enum RecentPaymentDetails {
+	/// When an invoice was requested and thus a payment has not yet been sent.
+	AwaitingInvoice {
+		/// Identifier for the payment to ensure idempotency.
+		payment_id: PaymentId,
+	},
 	/// When a payment is still being sent and awaiting successful delivery.
 	Pending {
 		/// Hash of the payment that is currently being sent but has yet to be fulfilled or
@@ -2419,7 +2419,14 @@ where
 	/// [`Event::PaymentSent`]: events::Event::PaymentSent
 	pub fn list_recent_payments(&self) -> Vec<RecentPaymentDetails> {
 		self.pending_outbound_payments.pending_outbound_payments.lock().unwrap().iter()
-			.filter_map(|(_, pending_outbound_payment)| match pending_outbound_payment {
+			.filter_map(|(payment_id, pending_outbound_payment)| match pending_outbound_payment {
+				PendingOutboundPayment::AwaitingInvoice { .. } => {
+					Some(RecentPaymentDetails::AwaitingInvoice { payment_id: *payment_id })
+				},
+				// InvoiceReceived is an intermediate state and doesn't need to be exposed
+				PendingOutboundPayment::InvoiceReceived { .. } => {
+					Some(RecentPaymentDetails::AwaitingInvoice { payment_id: *payment_id })
+				},
 				PendingOutboundPayment::Retryable { payment_hash, total_msat, .. } => {
 					Some(RecentPaymentDetails::Pending {
 						payment_hash: *payment_hash,
@@ -3381,22 +3388,32 @@ where
 	}
 
 
-	/// Signals that no further retries for the given payment should occur. Useful if you have a
+	/// Signals that no further attempts for the given payment should occur. Useful if you have a
 	/// pending outbound payment with retries remaining, but wish to stop retrying the payment before
 	/// retries are exhausted.
 	///
+	/// # Event Generation
+	///
 	/// If no [`Event::PaymentFailed`] event had been generated before, one will be generated as soon
 	/// as there are no remaining pending HTLCs for this payment.
 	///
 	/// Note that calling this method does *not* prevent a payment from succeeding. You must still
 	/// wait until you receive either a [`Event::PaymentFailed`] or [`Event::PaymentSent`] event to
 	/// determine the ultimate status of a payment.
 	///
-	/// If an [`Event::PaymentFailed`] event is generated and we restart without this
-	/// [`ChannelManager`] having been persisted, another [`Event::PaymentFailed`] may be generated.
+	/// # Requested Invoices
 	///
-	/// [`Event::PaymentFailed`]: events::Event::PaymentFailed
-	/// [`Event::PaymentSent`]: events::Event::PaymentSent
+	/// In the case of paying a [`Bolt12Invoice`], abandoning the payment prior to receiving the
+	/// invoice will result in an [`Event::InvoiceRequestFailed`] and prevent any attempts at paying
+	/// it once received. The other events may only be generated once the invoice has been received.
+	///
+	/// # Restart Behavior
+	///
+	/// If an [`Event::PaymentFailed`] is generated and we restart without first persisting the
+	/// [`ChannelManager`], another [`Event::PaymentFailed`] may be generated; likewise for
+	/// [`Event::InvoiceRequestFailed`].
+	///
+	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 	pub fn abandon_payment(&self, payment_id: PaymentId) {
 		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
 		self.pending_outbound_payments.abandon_payment(payment_id, PaymentFailureReason::UserAbandoned, &self.pending_events);
@@ -4655,7 +4672,7 @@ where
 				let _ = handle_error!(self, err, counterparty_node_id);
 			}
 
-			self.pending_outbound_payments.remove_stale_resolved_payments(&self.pending_events);
+			self.pending_outbound_payments.remove_stale_payments(&self.pending_events);
 
 			// Technically we don't need to do this here, but if we have holding cell entries in a
 			// channel that need freeing, it's better to do that here and block a background task
@@ -8347,6 +8364,8 @@ where
 						session_priv.write(writer)?;
 					}
 				}
+				PendingOutboundPayment::AwaitingInvoice { .. } => {},
+				PendingOutboundPayment::InvoiceReceived { .. } => {},
 				PendingOutboundPayment::Fulfilled { .. } => {},
 				PendingOutboundPayment::Abandoned { .. } => {},
 			}