From 1b85575066de35c5641e536f518702b7895ee9f5 Mon Sep 17 00:00:00 2001 From: Valentine Wallace Date: Tue, 10 Sep 2024 18:50:04 -0400 Subject: [PATCH] Document PendingOutboundPayment::{Static}InvoiceReceived semantics. While these variants may sound similar, they are very different. One is so temporary it's never even persisted to disk, the other is a state we will stay in for hours or days. See added docs for more info. --- lightning/src/ln/outbound_payment.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/lightning/src/ln/outbound_payment.rs b/lightning/src/ln/outbound_payment.rs index a0341438fa2..c42134da522 100644 --- a/lightning/src/ln/outbound_payment.rs +++ b/lightning/src/ln/outbound_payment.rs @@ -62,6 +62,9 @@ pub(crate) enum PendingOutboundPayment { max_total_routing_fee_msat: Option, invoice_request: Option, }, + // This state will never be persisted to disk because we transition from `AwaitingInvoice` to + // `Retryable` atomically within the `ChannelManager::total_consistency_lock`. Useful to avoid + // holding the `OutboundPayments::pending_outbound_payments` lock during pathfinding. InvoiceReceived { payment_hash: PaymentHash, retry_strategy: Retry, @@ -69,6 +72,10 @@ pub(crate) enum PendingOutboundPayment { // used anywhere. max_total_routing_fee_msat: Option, }, + // This state applies when we are paying an often-offline recipient and another node on the + // network served us a static invoice on the recipient's behalf in response to our invoice + // request. As a result, once a payment gets in this state it will remain here until the recipient + // comes back online, which may take hours or even days. StaticInvoiceReceived { payment_hash: PaymentHash, keysend_preimage: PaymentPreimage,