Merge pull request #3329 from arik-so/monitor_archive_docs_followup

Document monitor archival idempotency requirement (#3276 followup)

Author: G8XSU

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);
 }