X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fenums%2FChannelMonitorUpdateStatus.java;h=4cbadd6fc649b8efb4f9efdc864e418eb0d31762;hb=ffdd56c967087cba7548599934585b8a9a3102e2;hp=ac7d3f848edd08cc7b681a75e890eec90c640611;hpb=5e9de82b3a7712a41189756d9d16d946142b2ac5;p=ldk-java diff --git a/src/main/java/org/ldk/enums/ChannelMonitorUpdateStatus.java b/src/main/java/org/ldk/enums/ChannelMonitorUpdateStatus.java index ac7d3f84..4cbadd6f 100644 --- a/src/main/java/org/ldk/enums/ChannelMonitorUpdateStatus.java +++ b/src/main/java/org/ldk/enums/ChannelMonitorUpdateStatus.java @@ -2,6 +2,25 @@ package org.ldk.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 { /** @@ -13,17 +32,13 @@ 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 @@ -33,56 +48,31 @@ public enum ChannelMonitorUpdateStatus { * 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, ; static native void init(); - static { init(); } + static { org.ldk.impl.bindings.run_statics(); init(); } } \ No newline at end of file