From: Matt Corallo <git@bluematt.me>
Date: Thu, 8 Dec 2022 00:33:15 +0000 (+0000)
Subject: Note that abandon_payment does not persist the state update in docs
X-Git-Tag: v0.0.113~6^2
X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=refs%2Fheads%2F2022-12-abandon-crash-reset;p=rust-lightning

Note that abandon_payment does not persist the state update in docs

If a user calls `abandon_payment`, then restarts without freshly
persisting the `ChannelManager`, the payment will still be pending
on restart. This was unclear from the docs (and the docs seemed to
imply otherwise). Because this doesn't materially impact the
usability of `abandon_payment` (users shouldn't be called
`retry_payment` on an abandoned one anyway), we simply document it.

Fixes #1804.
---

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index bb99b02d9..29304cadb 100644
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -2761,15 +2761,21 @@ impl<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelManager<M, T, K, F
 
 	/// Signals that no further retries for the given payment will occur.
 	///
-	/// After this method returns, any future calls to [`retry_payment`] for the given `payment_id`
-	/// will fail with [`PaymentSendFailure::ParameterError`]. If no such event has been generated,
-	/// an [`Event::PaymentFailed`] event will be generated as soon as there are no remaining
-	/// pending HTLCs for this payment.
+	/// After this method returns, no future calls to [`retry_payment`] for the given `payment_id`
+	/// are allowed. 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, the payment may still be in the pending state
+	/// upon restart. This allows further calls to [`retry_payment`] (and requiring a second call
+	/// to [`abandon_payment`] to mark the payment as failed again). Otherwise, future calls to
+	/// [`retry_payment`] will fail with [`PaymentSendFailure::ParameterError`].
+	///
+	/// [`abandon_payment`]: Self::abandon_payment
 	/// [`retry_payment`]: Self::retry_payment
 	/// [`Event::PaymentFailed`]: events::Event::PaymentFailed
 	/// [`Event::PaymentSent`]: events::Event::PaymentSent
diff --git a/pending_changelog/matt-abandon-restart.txt b/pending_changelog/matt-abandon-restart.txt
new file mode 100644
index 000000000..07dc07364
--- /dev/null
+++ b/pending_changelog/matt-abandon-restart.txt
@@ -0,0 +1,4 @@
+## API Updates
+- `ChannelManager::abandon_payment` docs have been updated to note that the
+  payment may return to pending after a restart if no persistence occurs. This
+  is not a change in behavior - ensure your existing code is safe.