1+ package org .ldk .enums ;
2+
3+ /**
4+ * An enum representing the status of a channel monitor update persistence.
5+ */
6+ public enum ChannelMonitorUpdateStatus {
7+ /**
8+ * The update has been durably persisted and all copies of the relevant [`ChannelMonitor`]
9+ * have been updated.
10+ *
11+ * This includes performing any `fsync()` calls required to ensure the update is guaranteed to
12+ * be available on restart even if the application crashes.
13+ */
14+ LDKChannelMonitorUpdateStatus_Completed ,
15+ /**
16+ * Used to indicate a temporary failure (eg connection to a watchtower or remote backup of
17+ * our state failed, but is expected to succeed at some point in the future).
18+ *
19+ * Such a failure will \"freeze\" a channel, preventing us from revoking old states or
20+ * submitting new commitment transactions to the counterparty. Once the update(s) which failed
21+ * have been successfully applied, a [`MonitorEvent::Completed`] can be used to restore the
22+ * channel to an operational state.
23+ *
24+ * Note that a given [`ChannelManager`] will *never* re-generate a [`ChannelMonitorUpdate`].
25+ * If you return this error you must ensure that it is written to disk safely before writing
26+ * the latest [`ChannelManager`] state, or you should return [`PermanentFailure`] instead.
27+ *
28+ * Even when a channel has been \"frozen\", updates to the [`ChannelMonitor`] can continue to
29+ * occur (e.g. if an inbound HTLC which we forwarded was claimed upstream, resulting in us
30+ * attempting to claim it on this channel) and those updates must still be persisted.
31+ *
32+ * No updates to the channel will be made which could invalidate other [`ChannelMonitor`]s
33+ * until a [`MonitorEvent::Completed`] is provided, even if you return no error on a later
34+ * monitor update for the same channel.
35+ *
36+ * For deployments where a copy of ChannelMonitors and other local state are backed up in a
37+ * remote location (with local copies persisted immediately), it is anticipated that all
38+ * updates will return [`InProgress`] until the remote copies could be updated.
39+ *
40+ * [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure
41+ * [`InProgress`]: ChannelMonitorUpdateStatus::InProgress
42+ * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
43+ */
44+ LDKChannelMonitorUpdateStatus_InProgress ,
45+ /**
46+ * Used to indicate no further channel monitor updates will be allowed (likely a disk failure
47+ * or a remote copy of this [`ChannelMonitor`] is no longer reachable and thus not updatable).
48+ *
49+ * When this is returned, [`ChannelManager`] will force-close the channel but *not* broadcast
50+ * our current commitment transaction. This avoids a dangerous case where a local disk failure
51+ * (e.g. the Linux-default remounting of the disk as read-only) causes [`PermanentFailure`]s
52+ * for all monitor updates. If we were to broadcast our latest commitment transaction and then
53+ * restart, we could end up reading a previous [`ChannelMonitor`] and [`ChannelManager`],
54+ * revoking our now-broadcasted state before seeing it confirm and losing all our funds.
55+ *
56+ * Note that this is somewhat of a tradeoff - if the disk is really gone and we may have lost
57+ * the data permanently, we really should broadcast immediately. If the data can be recovered
58+ * with manual intervention, we'd rather close the channel, rejecting future updates to it,
59+ * and broadcast the latest state only if we have HTLCs to claim which are timing out (which
60+ * we do as long as blocks are connected).
61+ *
62+ * In order to broadcast the latest local commitment transaction, you'll need to call
63+ * [`ChannelMonitor::get_latest_holder_commitment_txn`] and broadcast the resulting
64+ * transactions once you've safely ensured no further channel updates can be generated by your
65+ * [`ChannelManager`].
66+ *
67+ * Note that at least one final [`ChannelMonitorUpdate`] may still be provided, which must
68+ * still be processed by a running [`ChannelMonitor`]. This final update will mark the
69+ * [`ChannelMonitor`] as finalized, ensuring no further updates (e.g. revocation of the latest
70+ * commitment transaction) are allowed.
71+ *
72+ * Note that even if you return a [`PermanentFailure`] due to unavailability of secondary
73+ * [`ChannelMonitor`] copies, you should still make an attempt to store the update where
74+ * possible to ensure you can claim HTLC outputs on the latest commitment transaction
75+ * broadcasted later.
76+ *
77+ * In case of distributed watchtowers deployment, the new version must be written to disk, as
78+ * state may have been stored but rejected due to a block forcing a commitment broadcast. This
79+ * storage is used to claim outputs of rejected state confirmed onchain by another watchtower,
80+ * lagging behind on block processing.
81+ *
82+ * [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure
83+ * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
84+ */
85+ LDKChannelMonitorUpdateStatus_PermanentFailure ,
86+ ; static native void init ();
87+ static { init (); }
88+ }
0 commit comments