1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
7 import javax.annotation.Nullable;
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.
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`].
22 * Note that unlike the direct [`chain::Watch`] interface,
23 * [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
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.
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;
39 @Override @SuppressWarnings("deprecation")
40 protected void finalize() throws Throwable {
41 if (ptr != 0) { bindings.Persist_free(ptr); } super.finalize();
44 public static interface PersistInterface {
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.
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.
53 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
54 * if you return [`ChannelMonitorUpdateErr::TemporaryFailure`].
56 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
57 * and [`ChannelMonitorUpdateErr`] for requirements when returning errors.
59 * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
60 * [`Writeable::write`]: crate::util::ser::Writeable::write
62 Result_NoneChannelMonitorUpdateErrZ persist_new_channel(OutPoint channel_id, ChannelMonitor data, MonitorUpdateId update_id);
64 * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
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
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.
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.
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)`.
89 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
90 * if you return [`ChannelMonitorUpdateErr::TemporaryFailure`].
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.
96 * [`Writeable::write`]: crate::util::ser::Writeable::write
98 * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
100 Result_NoneChannelMonitorUpdateErrZ update_persisted_channel(OutPoint channel_id, ChannelMonitorUpdate update, ChannelMonitor data, MonitorUpdateId update_id);
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 ? ret.ptr : 0;
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 ? ret.ptr : 0;
128 return impl_holder.held;
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.
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.
138 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
139 * if you return [`ChannelMonitorUpdateErr::TemporaryFailure`].
141 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
142 * and [`ChannelMonitorUpdateErr`] for requirements when returning errors.
144 * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
145 * [`Writeable::write`]: crate::util::ser::Writeable::write
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);
156 * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
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
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.
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.
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)`.
181 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
182 * if you return [`ChannelMonitorUpdateErr::TemporaryFailure`].
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.
188 * [`Writeable::write`]: crate::util::ser::Writeable::write
190 * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
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);