- * Note that for every new monitor, you **must** persist the new `ChannelMonitor`
- * to disk/backups. And, on every update, you **must** persist either the
- * `ChannelMonitorUpdate` or the updated monitor itself. Otherwise, there is risk
- * of situations such as revoking a transaction, then crashing before this
- * revocation can be persisted, then unintentionally broadcasting a revoked
- * transaction and losing money. This is a risk because previous channel states
- * are toxic, so it's important that whatever channel state is persisted is
- * kept up-to-date.
+ * Each method can return three possible values:
+ * If persistence (including any relevant `fsync()` calls) happens immediately, the
+ * implementation should return `Ok(())`, indicating normal channel operation should continue.
+ * If persistence happens asynchronously, implementations should first ensure the
+ * [`ChannelMonitor`] or [`ChannelMonitorUpdate`] are written durably to disk, and then return
+ * `Err(ChannelMonitorUpdateErr::TemporaryFailure)` while the update continues in the
+ * background. Once the update completes, [`ChainMonitor::channel_monitor_updated`] should be
+ * called with the corresponding [`MonitorUpdateId`].
+ *
+ * Note that unlike the direct [`chain::Watch`] interface,
+ * [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
+ *
+ * If persistence fails for some reason, implementations should return
+ * `Err(ChannelMonitorUpdateErr::PermanentFailure)`, in which case the channel will likely be
+ * closed without broadcasting the latest state. See
+ * [`ChannelMonitorUpdateErr::PermanentFailure`] for more details.