Enum ChannelMonitorUpdateStatus

pub enum ChannelMonitorUpdateStatus {
    Completed,
    InProgress,
    PermanentFailure,
}

An enum representing the status of a channel monitor update persistence.

Variants

Completed

The update has been durably persisted and all copies of the relevant ChannelMonitor have been updated.

This includes performing any fsync() calls required to ensure the update is guaranteed to be available on restart even if the application crashes.

InProgress

Used to indicate a temporary failure (eg connection to a watchtower or remote backup of our state failed, but is expected to succeed at some point in the future).

Such a failure will “freeze” a channel, preventing us from revoking old states or submitting new commitment transactions to the counterparty. Once the update(s) which failed 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.

No updates to the channel will be made which could invalidate other ChannelMonitors until a MonitorEvent::Completed is provided, even if you return no error on a later monitor update for the same channel.

For deployments where a copy of ChannelMonitors and other local state are backed up in a remote location (with local copies persisted immediately), it is anticipated that all updates will return InProgress until the remote copies could be updated.

PermanentFailure

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 PermanentFailures 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.

Trait Implementations

impl Clone for ChannelMonitorUpdateStatus

fn clone(&self) -> ChannelMonitorUpdateStatus

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ChannelMonitorUpdateStatus

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for ChannelMonitorUpdateStatus

fn eq(&self, other: &ChannelMonitorUpdateStatus) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for ChannelMonitorUpdateStatus

impl Eq for ChannelMonitorUpdateStatus

impl StructuralPartialEq for ChannelMonitorUpdateStatus