Document monitor archival idempotency requirement.

diff --git a/lightning/src/chain/chainmonitor.rs b/lightning/src/chain/chainmonitor.rs
index afd9df62851fb82fba1a73ee2fad61ec66ef8e7e..4e578ff9c472d09f21ca46decb779a7254bce69c 100644 (file)
--- a/lightning/src/chain/chainmonitor.rs
+++ b/lightning/src/chain/chainmonitor.rs
@@ -162,6 +162,13 @@ pub trait Persist<ChannelSigner: EcdsaChannelSigner> {
        ///
        /// Archiving the data in a backup location (rather than deleting it fully) is useful for
        /// hedging against data loss in case of unexpected failure.
+       ///
+       /// Note that if a crash occurs during the archiving process, and its implementation is not
+       /// atomic, a state may emerge with the archival operation only being partially complete. In
+       /// that scenario, the monitor may still be loaded on startup pending successful completion of
+       /// the archive process. Additionally, because the archive operation could be retried on
+       /// restart, this method must in that case be idempotent, ensuring it can handle scenarios where
+       /// the monitor already exists in the archive.
        fn archive_persisted_channel(&self, channel_funding_outpoint: OutPoint);
 }