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