pub enum ChannelMonitorUpdateStatus {
Completed,
InProgress,
PermanentFailure,
}
Expand description
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 ChannelMonitor
s
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 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.
Trait Implementations§
§impl Clone for ChannelMonitorUpdateStatus
impl Clone for ChannelMonitorUpdateStatus
§fn clone(&self) -> ChannelMonitorUpdateStatus
fn clone(&self) -> ChannelMonitorUpdateStatus
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more§impl Debug for ChannelMonitorUpdateStatus
impl Debug for ChannelMonitorUpdateStatus
§impl PartialEq for ChannelMonitorUpdateStatus
impl PartialEq for ChannelMonitorUpdateStatus
§fn eq(&self, other: &ChannelMonitorUpdateStatus) -> bool
fn eq(&self, other: &ChannelMonitorUpdateStatus) -> bool
self
and other
values to be equal, and is used
by ==
.impl Copy for ChannelMonitorUpdateStatus
impl Eq for ChannelMonitorUpdateStatus
impl StructuralPartialEq for ChannelMonitorUpdateStatus
Auto Trait Implementations§
impl Freeze for ChannelMonitorUpdateStatus
impl RefUnwindSafe for ChannelMonitorUpdateStatus
impl Send for ChannelMonitorUpdateStatus
impl Sync for ChannelMonitorUpdateStatus
impl Unpin for ChannelMonitorUpdateStatus
impl UnwindSafe for ChannelMonitorUpdateStatus
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Copy,
impl<T> CloneToUninit for Twhere
T: Copy,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T
in a tonic::Request