git.bitcoin.ninja 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 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 }