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.

diff --git a/lightning/src/ln/outbound_payment.rs b/lightning/src/ln/outbound_payment.rs
index 092f1a7fc202e274d2e64c6bd31cd0480ec5624d..ac2578a67214840217dc8dc3968ad98943e88456 100644 (file)
--- 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<u64>,
                retryable_invoice_request: Option<RetryableInvoiceRequest>
        },
+       // 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<u64>,
        },
+       // 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,