From 4bcf53e597543ece3684cd49ce1afa4331ce59ff 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 092f1a7fc..ac2578a67 100644 --- a/lightning/src/ln/outbound_payment.rs +++ b/lightning/src/ln/outbound_payment.rs @@ -64,6 +64,9 @@ pub(crate) enum PendingOutboundPayment { max_total_routing_fee_msat: Option, retryable_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, @@ -71,6 +74,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, -- 2.39.5