_ Git - ldk-java/blob - src/main/java/org/ldk/structs/Persist.java

   1 package org.ldk.structs;
   2
   3 import org.ldk.impl.bindings;
   4 import org.ldk.enums.*;
   5 import org.ldk.util.*;
   6 import java.util.Arrays;
   7 import java.lang.ref.Reference;
   8 import javax.annotation.Nullable;
   9
  10 /**
  11  * `Persist` defines behavior for persisting channel monitors: this could mean
  12  * writing once to disk, and/or uploading to one or more backup services.
  13  *
  14  * Persistence can happen in one of two ways - synchronously completing before the trait method
  15  * calls return or asynchronously in the background.
  16  *
  17  * # For those implementing synchronous persistence
  18  *
  19  * If persistence completes fully (including any relevant `fsync()` calls), the implementation
  20  * should return [`ChannelMonitorUpdateStatus::Completed`], indicating normal channel operation
  21  * should continue.
  22  *
  23  * If persistence fails for some reason, implementations should consider returning
  24  * [`ChannelMonitorUpdateStatus::InProgress`] and retry all pending persistence operations in
  25  * the background with [`ChainMonitor::list_pending_monitor_updates`] and
  26  * [`ChainMonitor::get_monitor`].
  27  *
  28  * Once a full [`ChannelMonitor`] has been persisted, all pending updates for that channel can
  29  * be marked as complete via [`ChainMonitor::channel_monitor_updated`].
  30  *
  31  * If at some point no further progress can be made towards persisting the pending updates, the
  32  * node should simply shut down.
  33  *
  34  * If the persistence has failed and cannot be retried further (e.g. because of an outage),
  35  * [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
  36  * an immediate panic and future operations in LDK generally failing.
  37  *
  38  * # For those implementing asynchronous persistence
  39  *
  40  * All calls should generally spawn a background task and immediately return
  41  * [`ChannelMonitorUpdateStatus::InProgress`]. Once the update completes,
  42  * [`ChainMonitor::channel_monitor_updated`] should be called with the corresponding
  43  * [`MonitorUpdateId`].
  44  *
  45  * Note that unlike the direct [`chain::Watch`] interface,
  46  * [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
  47  *
  48  * If at some point no further progress can be made towards persisting a pending update, the node
  49  * should simply shut down. Until then, the background task should either loop indefinitely, or
  50  * persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
  51  * and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
  52  * monitor updates may be marked completed).
  53  *
  54  * # Using remote watchtowers
  55  *
  56  * Watchtowers may be updated as a part of an implementation of this trait, utilizing the async
  57  * update process described above while the watchtower is being updated. The following methods are
  58  * provided for bulding transactions for a watchtower:
  59  * [`ChannelMonitor::initial_counterparty_commitment_tx`],
  60  * [`ChannelMonitor::counterparty_commitment_txs_from_update`],
  61  * [`ChannelMonitor::sign_to_local_justice_tx`], [`TrustedCommitmentTransaction::revokeable_output_index`],
  62  * [`TrustedCommitmentTransaction::build_to_local_justice_tx`].
  63  *
  64  * [`TrustedCommitmentTransaction::revokeable_output_index`]: crate::ln::chan_utils::TrustedCommitmentTransaction::revokeable_output_index
  65  * [`TrustedCommitmentTransaction::build_to_local_justice_tx`]: crate::ln::chan_utils::TrustedCommitmentTransaction::build_to_local_justice_tx
  66  */
  67 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  68 public class Persist extends CommonBase {
  69         final bindings.LDKPersist bindings_instance;
  70         Persist(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
  71         private Persist(bindings.LDKPersist arg) {
  72                 super(bindings.LDKPersist_new(arg));
  73                 this.ptrs_to.add(arg);
  74                 this.bindings_instance = arg;
  75         }
  76         @Override @SuppressWarnings("deprecation")
  77         protected void finalize() throws Throwable {
  78                 if (ptr != 0) { bindings.Persist_free(ptr); } super.finalize();
  79         }
  80         /**
  81          * Destroys the object, freeing associated resources. After this call, any access
  82          * to this object may result in a SEGFAULT or worse.
  83          *
  84          * You should generally NEVER call this method. You should let the garbage collector
  85          * do this for you when it finalizes objects. However, it may be useful for types
  86          * which represent locks and should be closed immediately to avoid holding locks
  87          * until the GC runs.
  88          */
  89         public void destroy() {
  90                 if (ptr != 0) { bindings.Persist_free(ptr); }
  91                 ptr = 0;
  92         }
  93         public static interface PersistInterface {
  94                 /**
  95                  * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is
  96                  * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup.
  97                  *
  98                  * The data can be stored any way you want, but the identifier provided by LDK is the
  99                  * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint
 100                  * and the stored channel data). Note that you **must** persist every new monitor to disk.
 101                  *
 102                  * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
 103                  * if you return [`ChannelMonitorUpdateStatus::InProgress`].
 104                  *
 105                  * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
 106                  * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
 107                  *
 108                  * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
 109                  * [`Writeable::write`]: crate::util::ser::Writeable::write
 110                  */
 111                 ChannelMonitorUpdateStatus persist_new_channel(OutPoint channel_id, ChannelMonitor data, MonitorUpdateId update_id);
 112                 /**
 113                  * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
 114                  * update.
 115                  *
 116                  * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the
 117                  * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
 118                  * details.
 119                  *
 120                  * During blockchain synchronization operations, and in some rare cases, this may be called with
 121                  * no [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
 122                  * Note that after the full [`ChannelMonitor`] is persisted any previous
 123                  * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
 124                  * applied to the persisted [`ChannelMonitor`] as they were already applied.
 125                  *
 126                  * If an implementer chooses to persist the updates only, they need to make
 127                  * sure that all the updates are applied to the `ChannelMonitors` *before
 128                  * the set of channel monitors is given to the `ChannelManager`
 129                  * deserialization routine. See [`ChannelMonitor::update_monitor`] for
 130                  * applying a monitor update to a monitor. If full `ChannelMonitors` are
 131                  * persisted, then there is no need to persist individual updates.
 132                  *
 133                  * Note that there could be a performance tradeoff between persisting complete
 134                  * channel monitors on every update vs. persisting only updates and applying
 135                  * them in batches. The size of each monitor grows `O(number of state updates)`
 136                  * whereas updates are small and `O(1)`.
 137                  *
 138                  * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
 139                  * if you return [`ChannelMonitorUpdateStatus::InProgress`].
 140                  *
 141                  * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`,
 142                  * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and
 143                  * [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
 144                  *
 145                  * [`Writeable::write`]: crate::util::ser::Writeable::write
 146                  *
 147                  * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
 148                  */
 149                 ChannelMonitorUpdateStatus update_persisted_channel(OutPoint channel_id, ChannelMonitorUpdate update, ChannelMonitor data, MonitorUpdateId update_id);
 150         }
 151         private static class LDKPersistHolder { Persist held; }
 152         public static Persist new_impl(PersistInterface arg) {
 153                 final LDKPersistHolder impl_holder = new LDKPersistHolder();
 154                 impl_holder.held = new Persist(new bindings.LDKPersist() {
 155                         @Override public ChannelMonitorUpdateStatus persist_new_channel(long channel_id, long data, long update_id) {
 156                                 org.ldk.structs.OutPoint channel_id_hu_conv = null; if (channel_id < 0 || channel_id > 4096) { channel_id_hu_conv = new org.ldk.structs.OutPoint(null, channel_id); }
 157                                 if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
 158                                 org.ldk.structs.ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new org.ldk.structs.ChannelMonitor(null, data); }
 159                                 org.ldk.structs.MonitorUpdateId update_id_hu_conv = null; if (update_id < 0 || update_id > 4096) { update_id_hu_conv = new org.ldk.structs.MonitorUpdateId(null, update_id); }
 160                                 if (update_id_hu_conv != null) { update_id_hu_conv.ptrs_to.add(this); };
 161                                 ChannelMonitorUpdateStatus ret = arg.persist_new_channel(channel_id_hu_conv, data_hu_conv, update_id_hu_conv);
 162                                 Reference.reachabilityFence(arg);
 163                                 return ret;
 164                         }
 165                         @Override public ChannelMonitorUpdateStatus update_persisted_channel(long channel_id, long update, long data, long update_id) {
 166                                 org.ldk.structs.OutPoint channel_id_hu_conv = null; if (channel_id < 0 || channel_id > 4096) { channel_id_hu_conv = new org.ldk.structs.OutPoint(null, channel_id); }
 167                                 if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
 168                                 org.ldk.structs.ChannelMonitorUpdate update_hu_conv = null; if (update < 0 || update > 4096) { update_hu_conv = new org.ldk.structs.ChannelMonitorUpdate(null, update); }
 169                                 if (update_hu_conv != null) { update_hu_conv.ptrs_to.add(this); };
 170                                 org.ldk.structs.ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new org.ldk.structs.ChannelMonitor(null, data); }
 171                                 org.ldk.structs.MonitorUpdateId update_id_hu_conv = null; if (update_id < 0 || update_id > 4096) { update_id_hu_conv = new org.ldk.structs.MonitorUpdateId(null, update_id); }
 172                                 if (update_id_hu_conv != null) { update_id_hu_conv.ptrs_to.add(this); };
 173                                 ChannelMonitorUpdateStatus ret = arg.update_persisted_channel(channel_id_hu_conv, update_hu_conv, data_hu_conv, update_id_hu_conv);
 174                                 Reference.reachabilityFence(arg);
 175                                 return ret;
 176                         }
 177                 });
 178                 return impl_holder.held;
 179         }
 180         /**
 181          * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is
 182          * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup.
 183          *
 184          * The data can be stored any way you want, but the identifier provided by LDK is the
 185          * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint
 186          * and the stored channel data). Note that you **must** persist every new monitor to disk.
 187          *
 188          * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
 189          * if you return [`ChannelMonitorUpdateStatus::InProgress`].
 190          *
 191          * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
 192          * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
 193          *
 194          * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
 195          * [`Writeable::write`]: crate::util::ser::Writeable::write
 196          */
 197         public ChannelMonitorUpdateStatus persist_new_channel(org.ldk.structs.OutPoint channel_id, org.ldk.structs.ChannelMonitor data, org.ldk.structs.MonitorUpdateId update_id) {
 198                 ChannelMonitorUpdateStatus ret = bindings.Persist_persist_new_channel(this.ptr, channel_id == null ? 0 : channel_id.ptr, data == null ? 0 : data.ptr, update_id == null ? 0 : update_id.ptr);
 199                 Reference.reachabilityFence(this);
 200                 Reference.reachabilityFence(channel_id);
 201                 Reference.reachabilityFence(data);
 202                 Reference.reachabilityFence(update_id);
 203                 if (this != null) { this.ptrs_to.add(channel_id); };
 204                 if (this != null) { this.ptrs_to.add(data); };
 205                 if (this != null) { this.ptrs_to.add(update_id); };
 206                 return ret;
 207         }
 208
 209         /**
 210          * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
 211          * update.
 212          *
 213          * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the
 214          * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
 215          * details.
 216          *
 217          * During blockchain synchronization operations, and in some rare cases, this may be called with
 218          * no [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
 219          * Note that after the full [`ChannelMonitor`] is persisted any previous
 220          * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
 221          * applied to the persisted [`ChannelMonitor`] as they were already applied.
 222          *
 223          * If an implementer chooses to persist the updates only, they need to make
 224          * sure that all the updates are applied to the `ChannelMonitors` *before
 225          * the set of channel monitors is given to the `ChannelManager`
 226          * deserialization routine. See [`ChannelMonitor::update_monitor`] for
 227          * applying a monitor update to a monitor. If full `ChannelMonitors` are
 228          * persisted, then there is no need to persist individual updates.
 229          *
 230          * Note that there could be a performance tradeoff between persisting complete
 231          * channel monitors on every update vs. persisting only updates and applying
 232          * them in batches. The size of each monitor grows `O(number of state updates)`
 233          * whereas updates are small and `O(1)`.
 234          *
 235          * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
 236          * if you return [`ChannelMonitorUpdateStatus::InProgress`].
 237          *
 238          * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`,
 239          * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and
 240          * [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
 241          *
 242          * [`Writeable::write`]: crate::util::ser::Writeable::write
 243          *
 244          * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
 245          */
 246         public ChannelMonitorUpdateStatus update_persisted_channel(org.ldk.structs.OutPoint channel_id, @Nullable org.ldk.structs.ChannelMonitorUpdate update, org.ldk.structs.ChannelMonitor data, org.ldk.structs.MonitorUpdateId update_id) {
 247                 ChannelMonitorUpdateStatus ret = bindings.Persist_update_persisted_channel(this.ptr, channel_id == null ? 0 : channel_id.ptr, update == null ? 0 : update.ptr, data == null ? 0 : data.ptr, update_id == null ? 0 : update_id.ptr);
 248                 Reference.reachabilityFence(this);
 249                 Reference.reachabilityFence(channel_id);
 250                 Reference.reachabilityFence(update);
 251                 Reference.reachabilityFence(data);
 252                 Reference.reachabilityFence(update_id);
 253                 if (this != null) { this.ptrs_to.add(channel_id); };
 254                 if (this != null) { this.ptrs_to.add(update); };
 255                 if (this != null) { this.ptrs_to.add(data); };
 256                 if (this != null) { this.ptrs_to.add(update_id); };
 257                 return ret;
 258         }
 259
 260 }