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