_ Git - ldk-java/blob - src/main/java/org/ldk/enums/ChannelMonitorUpdateStatus.java

   1 package org.ldk.enums;
   2
   3 /**
   4  * An enum representing the status of a channel monitor update persistence.
   5  *
   6  * These are generally used as the return value for an implementation of [`Persist`] which is used
   7  * as the storage layer for a [`ChainMonitor`]. See the docs on [`Persist`] for a high-level
   8  * explanation of how to handle different cases.
   9  *
  10  * While `UnrecoverableError` is provided as a failure variant, it is not truly \"handled\" on the
  11  * calling side, and generally results in an immediate panic. For those who prefer to avoid
  12  * panics, `InProgress` can be used and you can retry the update operation in the background or
  13  * shut down cleanly.
  14  *
  15  * Note that channels should generally *not* be force-closed after a persistence failure.
  16  * Force-closing with the latest [`ChannelMonitorUpdate`] applied may result in a transaction
  17  * being broadcast which can only be spent by the latest [`ChannelMonitor`]! Thus, if the
  18  * latest [`ChannelMonitor`] is not durably persisted anywhere and exists only in memory, naively
  19  * calling [`ChannelManager::force_close_broadcasting_latest_txn`] *may result in loss of funds*!
  20  *
  21  * [`Persist`]: chainmonitor::Persist
  22  * [`ChainMonitor`]: chainmonitor::ChainMonitor
  23  * [`ChannelManager::force_close_broadcasting_latest_txn`]: crate::ln::channelmanager::ChannelManager::force_close_broadcasting_latest_txn
  24  */
  25 public enum ChannelMonitorUpdateStatus {
  26         /**
  27          * The update has been durably persisted and all copies of the relevant [`ChannelMonitor`]
  28          * have been updated.
  29          *
  30          * This includes performing any `fsync()` calls required to ensure the update is guaranteed to
  31          * be available on restart even if the application crashes.
  32          */
  33         LDKChannelMonitorUpdateStatus_Completed,
  34         /**
  35          * Indicates that the update will happen asynchronously in the background or that a transient
  36          * failure occurred which is being retried in the background and will eventually complete.
  37          *
  38          * This will \"freeze\" a channel, preventing us from revoking old states or submitting a new
  39          * commitment transaction to the counterparty. Once the update(s) which are `InProgress` have
  40          * been completed, a [`MonitorEvent::Completed`] can be used to restore the channel to an
  41          * operational state.
  42          *
  43          * Even when a channel has been \"frozen\", updates to the [`ChannelMonitor`] can continue to
  44          * occur (e.g. if an inbound HTLC which we forwarded was claimed upstream, resulting in us
  45          * attempting to claim it on this channel) and those updates must still be persisted.
  46          *
  47          * No updates to the channel will be made which could invalidate other [`ChannelMonitor`]s
  48          * until a [`MonitorEvent::Completed`] is provided, even if you return no error on a later
  49          * monitor update for the same channel.
  50          *
  51          * For deployments where a copy of [`ChannelMonitor`]s and other local state are backed up in
  52          * a remote location (with local copies persisted immediately), it is anticipated that all
  53          * updates will return [`InProgress`] until the remote copies could be updated.
  54          *
  55          * Note that while fully asynchronous persistence of [`ChannelMonitor`] data is generally
  56          * reliable, this feature is considered beta, and a handful of edge-cases remain. Until the
  57          * remaining cases are fixed, in rare cases, *using this feature may lead to funds loss*.
  58          *
  59          * [`InProgress`]: ChannelMonitorUpdateStatus::InProgress
  60          */
  61         LDKChannelMonitorUpdateStatus_InProgress,
  62         /**
  63          * Indicates that an update has failed and will not complete at any point in the future.
  64          *
  65          * Currently returning this variant will cause LDK to immediately panic to encourage immediate
  66          * shutdown. In the future this may be updated to disconnect peers and refuse to continue
  67          * normal operation without a panic.
  68          *
  69          * Applications which wish to perform an orderly shutdown after failure should consider
  70          * returning [`InProgress`] instead and simply shut down without ever marking the update
  71          * complete.
  72          *
  73          * [`InProgress`]: ChannelMonitorUpdateStatus::InProgress
  74          */
  75         LDKChannelMonitorUpdateStatus_UnrecoverableError,
  76         ; static native void init();
  77         static { init(); }
  78 }