_ 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  * Each method can return three possible values:
  15  * If persistence (including any relevant `fsync()` calls) happens immediately, the
  16  * implementation should return [`ChannelMonitorUpdateStatus::Completed`], indicating normal
  17  * channel operation should continue.
  18  * If persistence happens asynchronously, implementations should first ensure the
  19  * [`ChannelMonitor`] or [`ChannelMonitorUpdate`] are written durably to disk, and then return
  20  * [`ChannelMonitorUpdateStatus::InProgress`] while the update continues in the background.
  21  * Once the update completes, [`ChainMonitor::channel_monitor_updated`] should be called with
  22  * the corresponding [`MonitorUpdateId`].
  23  *
  24  * Note that unlike the direct [`chain::Watch`] interface,
  25  * [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
  26  *
  27  * If persistence fails for some reason, implementations should return
  28  * [`ChannelMonitorUpdateStatus::PermanentFailure`], in which case the channel will likely be
  29  * closed without broadcasting the latest state. See
  30  * [`ChannelMonitorUpdateStatus::PermanentFailure`] for more details.
  31  */
  32 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  33 public class Persist extends CommonBase {
  34         final bindings.LDKPersist bindings_instance;
  35         Persist(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
  36         private Persist(bindings.LDKPersist arg) {
  37                 super(bindings.LDKPersist_new(arg));
  38                 this.ptrs_to.add(arg);
  39                 this.bindings_instance = arg;
  40         }
  41         @Override @SuppressWarnings("deprecation")
  42         protected void finalize() throws Throwable {
  43                 if (ptr != 0) { bindings.Persist_free(ptr); } super.finalize();
  44         }
  45         /**
  46          * Destroys the object, freeing associated resources. After this call, any access
  47          * to this object may result in a SEGFAULT or worse.
  48          *
  49          * You should generally NEVER call this method. You should let the garbage collector
  50          * do this for you when it finalizes objects. However, it may be useful for types
  51          * which represent locks and should be closed immediately to avoid holding locks
  52          * until the GC runs.
  53          */
  54         public void destroy() {
  55                 if (ptr != 0) { bindings.Persist_free(ptr); }
  56                 ptr = 0;
  57         }
  58         public static interface PersistInterface {
  59                 /**
  60                  * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is
  61                  * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup.
  62                  *
  63                  * The data can be stored any way you want, but the identifier provided by LDK is the
  64                  * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint
  65                  * and the stored channel data). Note that you **must** persist every new monitor to disk.
  66                  *
  67                  * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
  68                  * if you return [`ChannelMonitorUpdateStatus::InProgress`].
  69                  *
  70                  * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
  71                  * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
  72                  *
  73                  * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
  74                  * [`Writeable::write`]: crate::util::ser::Writeable::write
  75                  */
  76                 ChannelMonitorUpdateStatus persist_new_channel(OutPoint channel_id, ChannelMonitor data, MonitorUpdateId update_id);
  77                 /**
  78                  * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
  79                  * update.
  80                  *
  81                  * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the
  82                  * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
  83                  * details.
  84                  *
  85                  * During blockchain synchronization operations, this may be called with no
  86                  * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
  87                  * Note that after the full [`ChannelMonitor`] is persisted any previous
  88                  * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
  89                  * applied to the persisted [`ChannelMonitor`] as they were already applied.
  90                  *
  91                  * If an implementer chooses to persist the updates only, they need to make
  92                  * sure that all the updates are applied to the `ChannelMonitors` *before
  93                  * the set of channel monitors is given to the `ChannelManager`
  94                  * deserialization routine. See [`ChannelMonitor::update_monitor`] for
  95                  * applying a monitor update to a monitor. If full `ChannelMonitors` are
  96                  * persisted, then there is no need to persist individual updates.
  97                  *
  98                  * Note that there could be a performance tradeoff between persisting complete
  99                  * channel monitors on every update vs. persisting only updates and applying
 100                  * them in batches. The size of each monitor grows `O(number of state updates)`
 101                  * whereas updates are small and `O(1)`.
 102                  *
 103                  * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
 104                  * if you return [`ChannelMonitorUpdateStatus::InProgress`].
 105                  *
 106                  * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`,
 107                  * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and
 108                  * [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
 109                  *
 110                  * [`Writeable::write`]: crate::util::ser::Writeable::write
 111                  *
 112                  * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
 113                  */
 114                 ChannelMonitorUpdateStatus update_persisted_channel(OutPoint channel_id, ChannelMonitorUpdate update, ChannelMonitor data, MonitorUpdateId update_id);
 115         }
 116         private static class LDKPersistHolder { Persist held; }
 117         public static Persist new_impl(PersistInterface arg) {
 118                 final LDKPersistHolder impl_holder = new LDKPersistHolder();
 119                 impl_holder.held = new Persist(new bindings.LDKPersist() {
 120                         @Override public ChannelMonitorUpdateStatus persist_new_channel(long channel_id, long data, long update_id) {
 121                                 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); }
 122                                 if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
 123                                 org.ldk.structs.ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new org.ldk.structs.ChannelMonitor(null, data); }
 124                                 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); }
 125                                 if (update_id_hu_conv != null) { update_id_hu_conv.ptrs_to.add(this); };
 126                                 ChannelMonitorUpdateStatus ret = arg.persist_new_channel(channel_id_hu_conv, data_hu_conv, update_id_hu_conv);
 127                                 Reference.reachabilityFence(arg);
 128                                 return ret;
 129                         }
 130                         @Override public ChannelMonitorUpdateStatus update_persisted_channel(long channel_id, long update, long data, long update_id) {
 131                                 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); }
 132                                 if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
 133                                 org.ldk.structs.ChannelMonitorUpdate update_hu_conv = null; if (update < 0 || update > 4096) { update_hu_conv = new org.ldk.structs.ChannelMonitorUpdate(null, update); }
 134                                 if (update_hu_conv != null) { update_hu_conv.ptrs_to.add(this); };
 135                                 org.ldk.structs.ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new org.ldk.structs.ChannelMonitor(null, data); }
 136                                 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); }
 137                                 if (update_id_hu_conv != null) { update_id_hu_conv.ptrs_to.add(this); };
 138                                 ChannelMonitorUpdateStatus ret = arg.update_persisted_channel(channel_id_hu_conv, update_hu_conv, data_hu_conv, update_id_hu_conv);
 139                                 Reference.reachabilityFence(arg);
 140                                 return ret;
 141                         }
 142                 });
 143                 return impl_holder.held;
 144         }
 145         /**
 146          * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is
 147          * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup.
 148          *
 149          * The data can be stored any way you want, but the identifier provided by LDK is the
 150          * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint
 151          * and the stored channel data). Note that you **must** persist every new monitor to disk.
 152          *
 153          * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
 154          * if you return [`ChannelMonitorUpdateStatus::InProgress`].
 155          *
 156          * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
 157          * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
 158          *
 159          * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
 160          * [`Writeable::write`]: crate::util::ser::Writeable::write
 161          */
 162         public ChannelMonitorUpdateStatus persist_new_channel(org.ldk.structs.OutPoint channel_id, org.ldk.structs.ChannelMonitor data, org.ldk.structs.MonitorUpdateId update_id) {
 163                 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);
 164                 Reference.reachabilityFence(this);
 165                 Reference.reachabilityFence(channel_id);
 166                 Reference.reachabilityFence(data);
 167                 Reference.reachabilityFence(update_id);
 168                 if (this != null) { this.ptrs_to.add(channel_id); };
 169                 if (this != null) { this.ptrs_to.add(data); };
 170                 if (this != null) { this.ptrs_to.add(update_id); };
 171                 return ret;
 172         }
 173
 174         /**
 175          * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
 176          * update.
 177          *
 178          * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the
 179          * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
 180          * details.
 181          *
 182          * During blockchain synchronization operations, this may be called with no
 183          * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
 184          * Note that after the full [`ChannelMonitor`] is persisted any previous
 185          * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
 186          * applied to the persisted [`ChannelMonitor`] as they were already applied.
 187          *
 188          * If an implementer chooses to persist the updates only, they need to make
 189          * sure that all the updates are applied to the `ChannelMonitors` *before
 190          * the set of channel monitors is given to the `ChannelManager`
 191          * deserialization routine. See [`ChannelMonitor::update_monitor`] for
 192          * applying a monitor update to a monitor. If full `ChannelMonitors` are
 193          * persisted, then there is no need to persist individual updates.
 194          *
 195          * Note that there could be a performance tradeoff between persisting complete
 196          * channel monitors on every update vs. persisting only updates and applying
 197          * them in batches. The size of each monitor grows `O(number of state updates)`
 198          * whereas updates are small and `O(1)`.
 199          *
 200          * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
 201          * if you return [`ChannelMonitorUpdateStatus::InProgress`].
 202          *
 203          * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`,
 204          * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and
 205          * [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
 206          *
 207          * [`Writeable::write`]: crate::util::ser::Writeable::write
 208          *
 209          * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
 210          */
 211         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) {
 212                 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);
 213                 Reference.reachabilityFence(this);
 214                 Reference.reachabilityFence(channel_id);
 215                 Reference.reachabilityFence(update);
 216                 Reference.reachabilityFence(data);
 217                 Reference.reachabilityFence(update_id);
 218                 if (this != null) { this.ptrs_to.add(channel_id); };
 219                 if (this != null) { this.ptrs_to.add(update); };
 220                 if (this != null) { this.ptrs_to.add(data); };
 221                 if (this != null) { this.ptrs_to.add(update_id); };
 222                 return ret;
 223         }
 224
 225 }