/// have been successfully applied, a [`MonitorEvent::Completed`] can be used to restore the
/// channel to an operational state.
///
- /// Note that a given [`ChannelManager`] will *never* re-generate a [`ChannelMonitorUpdate`].
- /// If you return this error you must ensure that it is written to disk safely before writing
- /// the latest [`ChannelManager`] state, or you should return [`PermanentFailure`] instead.
- ///
/// Even when a channel has been "frozen", updates to the [`ChannelMonitor`] can continue to
/// occur (e.g. if an inbound HTLC which we forwarded was claimed upstream, resulting in us
/// attempting to claim it on this channel) and those updates must still be persisted.
/// remote location (with local copies persisted immediately), it is anticipated that all
/// updates will return [`InProgress`] until the remote copies could be updated.
///
- /// [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure
/// [`InProgress`]: ChannelMonitorUpdateStatus::InProgress
- /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
InProgress,
- /// Used to indicate no further channel monitor updates will be allowed (likely a disk failure
- /// or a remote copy of this [`ChannelMonitor`] is no longer reachable and thus not updatable).
- ///
- /// When this is returned, [`ChannelManager`] will force-close the channel but *not* broadcast
- /// our current commitment transaction. This avoids a dangerous case where a local disk failure
- /// (e.g. the Linux-default remounting of the disk as read-only) causes [`PermanentFailure`]s
- /// for all monitor updates. If we were to broadcast our latest commitment transaction and then
- /// restart, we could end up reading a previous [`ChannelMonitor`] and [`ChannelManager`],
- /// revoking our now-broadcasted state before seeing it confirm and losing all our funds.
- ///
- /// Note that this is somewhat of a tradeoff - if the disk is really gone and we may have lost
- /// the data permanently, we really should broadcast immediately. If the data can be recovered
- /// with manual intervention, we'd rather close the channel, rejecting future updates to it,
- /// and broadcast the latest state only if we have HTLCs to claim which are timing out (which
- /// we do as long as blocks are connected).
- ///
- /// In order to broadcast the latest local commitment transaction, you'll need to call
- /// [`ChannelMonitor::get_latest_holder_commitment_txn`] and broadcast the resulting
- /// transactions once you've safely ensured no further channel updates can be generated by your
- /// [`ChannelManager`].
- ///
- /// Note that at least one final [`ChannelMonitorUpdate`] may still be provided, which must
- /// still be processed by a running [`ChannelMonitor`]. This final update will mark the
- /// [`ChannelMonitor`] as finalized, ensuring no further updates (e.g. revocation of the latest
- /// commitment transaction) are allowed.
- ///
- /// Note that even if you return a [`PermanentFailure`] due to unavailability of secondary
- /// [`ChannelMonitor`] copies, you should still make an attempt to store the update where
- /// possible to ensure you can claim HTLC outputs on the latest commitment transaction
- /// broadcasted later.
- ///
- /// In case of distributed watchtowers deployment, the new version must be written to disk, as
- /// state may have been stored but rejected due to a block forcing a commitment broadcast. This
- /// storage is used to claim outputs of rejected state confirmed onchain by another watchtower,
- /// lagging behind on block processing.
- ///
- /// [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure
- /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
- PermanentFailure,
}
/// The `Watch` trait defines behavior for watching on-chain activity pertaining to channels as
/// requirements.
///
/// Implementations **must** ensure that updates are successfully applied and persisted upon method
-/// completion. If an update fails with a [`PermanentFailure`], then it must immediately shut down
-/// without taking any further action such as persisting the current state.
+/// 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.
-///
-/// [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure
pub trait Watch<ChannelSigner: WriteableEcdsaChannelSigner> {
/// Watches a channel identified by `funding_txo` using `monitor`.
///
/// with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means
/// calling [`block_connected`] and [`block_disconnected`] on the monitor.
///
- /// Note: this interface MUST error with [`ChannelMonitorUpdateStatus::PermanentFailure`] if
- /// the given `funding_txo` has previously been registered via `watch_channel`.
+ /// A return of `Err(())` indicates that the channel should immediately be force-closed without
+ /// broadcasting the funding transaction.
+ ///
+ /// If the given `funding_txo` has previously been registered via `watch_channel`, `Err(())`
+ /// must be returned.
///
/// [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch
/// [`block_connected`]: channelmonitor::ChannelMonitor::block_connected
/// [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected
- fn watch_channel(&self, funding_txo: OutPoint, monitor: ChannelMonitor<ChannelSigner>) -> ChannelMonitorUpdateStatus;
+ fn watch_channel(&self, funding_txo: OutPoint, monitor: ChannelMonitor<ChannelSigner>) -> Result<ChannelMonitorUpdateStatus, ()>;
/// Updates a channel identified by `funding_txo` by applying `update` to its monitor.
///
- /// Implementations must call [`update_monitor`] with the given update. See
- /// [`ChannelMonitorUpdateStatus`] for invariants around returning an error.
+ /// Implementations must call [`ChannelMonitor::update_monitor`] with the given update. This
+ /// may fail (returning an `Err(())`), in which case this should return
+ /// [`ChannelMonitorUpdateStatus::InProgress`] (and the update should never complete). This
+ /// generally implies the channel has been closed (either by the funding outpoint being spent
+ /// on-chain or the [`ChannelMonitor`] having decided to do so and broadcasted a transaction),
+ /// and the [`ChannelManager`] state will be updated once it sees the funding spend on-chain.
+ ///
+ /// If persistence fails, this should return [`ChannelMonitorUpdateStatus::InProgress`] and
+ /// the node should shut down immediately.
///
- /// [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor
+ /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
fn update_channel(&self, funding_txo: OutPoint, update: &ChannelMonitorUpdate) -> ChannelMonitorUpdateStatus;
/// Returns any monitor events since the last call. Subsequent calls must only return new
projects / rust-lightning / blobdiff