namespace org { namespace ldk { namespace enums {/**
* An enum representing the status of a channel monitor update persistence.
+ *
+ * These are generally used as the return value for an implementation of [`Persist`] which is used
+ * as the storage layer for a [`ChainMonitor`]. See the docs on [`Persist`] for a high-level
+ * explanation of how to handle different cases.
+ *
+ * While `UnrecoverableError` is provided as a failure variant, it is not truly \"handled\" on the
+ * calling side, and generally results in an immediate panic. For those who prefer to avoid
+ * panics, `InProgress` can be used and you can retry the update operation in the background or
+ * shut down cleanly.
+ *
+ * Note that channels should generally *not* be force-closed after a persistence failure.
+ * Force-closing with the latest [`ChannelMonitorUpdate`] applied may result in a transaction
+ * being broadcast which can only be spent by the latest [`ChannelMonitor`]! Thus, if the
+ * latest [`ChannelMonitor`] is not durably persisted anywhere and exists only in memory, naively
+ * calling [`ChannelManager::force_close_broadcasting_latest_txn`] *may result in loss of funds*!
+ *
+ * [`Persist`]: chainmonitor::Persist
+ * [`ChainMonitor`]: chainmonitor::ChainMonitor
+ * [`ChannelManager::force_close_broadcasting_latest_txn`]: crate::ln::channelmanager::ChannelManager::force_close_broadcasting_latest_txn
*/
public enum ChannelMonitorUpdateStatus {
/**
*/
LDKChannelMonitorUpdateStatus_Completed,
/**
- * 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).
+ * Indicates that the update will happen asynchronously in the background or that a transient
+ * failure occurred which is being retried in the background and will eventually complete.
*
- * 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.
+ * This will \"freeze\" a channel, preventing us from revoking old states or submitting a new
+ * commitment transaction to the counterparty. Once the update(s) which are `InProgress` have
+ * been completed, a [`MonitorEvent::Completed`] can be used to restore the channel to an
+ * operational state.
*
* 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
* 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
+ * For deployments where a copy of [`ChannelMonitor`]s 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`]: ChannelMonitorUpdateStatus::PermanentFailure
+ * Note that while fully asynchronous persistence of [`ChannelMonitor`] data is generally
+ * reliable, this feature is considered beta, and a handful of edge-cases remain. Until the
+ * remaining cases are fixed, in rare cases, *using this feature may lead to funds loss*.
+ *
* [`InProgress`]: ChannelMonitorUpdateStatus::InProgress
- * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
*/
LDKChannelMonitorUpdateStatus_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).
+ * Indicates that an update has failed and will not complete at any point in the future.
*
- * 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`].
+ * Currently returning this variant will cause LDK to immediately panic to encourage immediate
+ * shutdown. In the future this may be updated to disconnect peers and refuse to continue
+ * normal operation without a panic.
*
- * 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.
+ * Applications which wish to perform an orderly shutdown after failure should consider
+ * returning [`InProgress`] instead and simply shut down without ever marking the update
+ * complete.
*
- * 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
+ * [`InProgress`]: ChannelMonitorUpdateStatus::InProgress
*/
- LDKChannelMonitorUpdateStatus_PermanentFailure,
+ LDKChannelMonitorUpdateStatus_UnrecoverableError,
}} } }
projects / ldk-java / blobdiff