Update ChannelMonitorUpdateStatus documentation with async support

Since we now (almost) support async monitor update persistence, the
documentation on `ChannelMonitorUpdateStatus` can be updated to no
longer suggest users must keep a local copy that persists before
returning. However, because there are still a few remaining issues,
we note that async support is currently beta and explicily warn of
potential for funds-loss.

Fixes #1684

Author: TheBlueMatt

lightning/src/chain/mod.rs

@@ -176,6 +176,16 @@ pub trait Confirm {
 }
 
 /// An enum representing the status of a channel monitor update persistence.
+///
+/// Note that there is no error variant - any failure to persist a [`ChannelMonitor`] should be
+/// retried indefinitely, the node shut down (as if we cannot update stored data we can't do much
+/// of anything useful), or the channel force-close using
+/// [`ChannelManager::force_close_broadcasting_latest_txn`].
+///
+/// Note that in the last case, force-closing with the latest [`ChannelMonitorUpdate`] applied may
+/// result in a transaction which can only be spent by the latest [`ChannelMonitor`]. Thus, if the
+/// latest [`ChannelMonitor`] is not durably persisted anywhere, naively calling
+/// [`ChannelManager::force_close_broadcasting_latest_txn`] *may result in loss of funds*!
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum ChannelMonitorUpdateStatus {
 	/// The update has been durably persisted and all copies of the relevant [`ChannelMonitor`]
@@ -204,6 +214,10 @@ pub enum ChannelMonitorUpdateStatus {
 	/// remote location (with local copies persisted immediately), it is anticipated that all
 	/// updates will return [`InProgress`] until the remote copies could be updated.
 	///
+	/// Note that while fully asynchronous persistence of [`ChannelMonitor`] data is generally
+	/// reliable, this feature is considered beta, and a handful of edge-cases remain. Until the
+	/// remaining cases are fixed, in rare cases, *using this feature may lead to funds loss*.
+	///
 	/// [`InProgress`]: ChannelMonitorUpdateStatus::InProgress
 	InProgress,
 }
@@ -216,14 +230,10 @@ pub enum ChannelMonitorUpdateStatus {
 /// channel state changes and HTLCs are resolved. See method documentation for specific
 /// requirements.
 ///
-/// Implementations **must** ensure that updates are successfully applied and persisted upon method
-/// completion. If an update will not succeed, then it must immediately shut down.
-///
 /// If an implementation maintains multiple instances of a channel's monitor (e.g., by storing
 /// backup copies), then it must ensure that updates are applied across all instances. Otherwise, it
 /// could result in a revoked transaction being broadcast, allowing the counterparty to claim all
-/// funds in the channel. See [`ChannelMonitorUpdateStatus`] for more details about how to handle
-/// multiple instances.
+/// funds in the channel.
 pub trait Watch<ChannelSigner: WriteableEcdsaChannelSigner> {
 	/// Watches a channel identified by `funding_txo` using `monitor`.
 	///