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 [`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`].
24 * Note that unlike the direct [`chain::Watch`] interface,
25 * [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
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.
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;
41 @Override @SuppressWarnings("deprecation")
42 protected void finalize() throws Throwable {
43 if (ptr != 0) { bindings.Persist_free(ptr); } super.finalize();
46 public static interface PersistInterface {
48 * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is
49 * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup.
51 * The data can be stored any way you want, but the identifier provided by LDK is the
52 * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint
53 * and the stored channel data). Note that you **must** persist every new monitor to disk.
55 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
56 * if you return [`ChannelMonitorUpdateStatus::InProgress`].
58 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
59 * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
61 * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
62 * [`Writeable::write`]: crate::util::ser::Writeable::write
64 ChannelMonitorUpdateStatus persist_new_channel(OutPoint channel_id, ChannelMonitor data, MonitorUpdateId update_id);
66 * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
69 * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the
70 * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
73 * During blockchain synchronization operations, this may be called with no
74 * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
75 * Note that after the full [`ChannelMonitor`] is persisted any previous
76 * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
77 * applied to the persisted [`ChannelMonitor`] as they were already applied.
79 * If an implementer chooses to persist the updates only, they need to make
80 * sure that all the updates are applied to the `ChannelMonitors` *before
81 * the set of channel monitors is given to the `ChannelManager`
82 * deserialization routine. See [`ChannelMonitor::update_monitor`] for
83 * applying a monitor update to a monitor. If full `ChannelMonitors` are
84 * persisted, then there is no need to persist individual updates.
86 * Note that there could be a performance tradeoff between persisting complete
87 * channel monitors on every update vs. persisting only updates and applying
88 * them in batches. The size of each monitor grows `O(number of state updates)`
89 * whereas updates are small and `O(1)`.
91 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
92 * if you return [`ChannelMonitorUpdateStatus::InProgress`].
94 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`,
95 * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and
96 * [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
98 * [`Writeable::write`]: crate::util::ser::Writeable::write
100 * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
102 ChannelMonitorUpdateStatus update_persisted_channel(OutPoint channel_id, ChannelMonitorUpdate update, ChannelMonitor data, MonitorUpdateId update_id);
104 private static class LDKPersistHolder { Persist held; }
105 public static Persist new_impl(PersistInterface arg) {
106 final LDKPersistHolder impl_holder = new LDKPersistHolder();
107 impl_holder.held = new Persist(new bindings.LDKPersist() {
108 @Override public ChannelMonitorUpdateStatus persist_new_channel(long channel_id, long data, long update_id) {
109 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); }
110 if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
111 org.ldk.structs.ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new org.ldk.structs.ChannelMonitor(null, data); }
112 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); }
113 if (update_id_hu_conv != null) { update_id_hu_conv.ptrs_to.add(this); };
114 ChannelMonitorUpdateStatus ret = arg.persist_new_channel(channel_id_hu_conv, data_hu_conv, update_id_hu_conv);
115 Reference.reachabilityFence(arg);
118 @Override public ChannelMonitorUpdateStatus 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 ChannelMonitorUpdateStatus ret = arg.update_persisted_channel(channel_id_hu_conv, update_hu_conv, data_hu_conv, update_id_hu_conv);
126 Reference.reachabilityFence(arg);
130 return impl_holder.held;
133 * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is
134 * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup.
136 * The data can be stored any way you want, but the identifier provided by LDK is the
137 * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint
138 * and the stored channel data). Note that you **must** persist every new monitor to disk.
140 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
141 * if you return [`ChannelMonitorUpdateStatus::InProgress`].
143 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
144 * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
146 * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
147 * [`Writeable::write`]: crate::util::ser::Writeable::write
149 public ChannelMonitorUpdateStatus persist_new_channel(OutPoint channel_id, ChannelMonitor data, MonitorUpdateId update_id) {
150 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);
151 Reference.reachabilityFence(this);
152 Reference.reachabilityFence(channel_id);
153 Reference.reachabilityFence(data);
154 Reference.reachabilityFence(update_id);
155 if (this != null) { this.ptrs_to.add(channel_id); };
156 if (this != null) { this.ptrs_to.add(data); };
157 if (this != null) { this.ptrs_to.add(update_id); };
162 * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
165 * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the
166 * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
169 * During blockchain synchronization operations, this may be called with no
170 * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
171 * Note that after the full [`ChannelMonitor`] is persisted any previous
172 * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
173 * applied to the persisted [`ChannelMonitor`] as they were already applied.
175 * If an implementer chooses to persist the updates only, they need to make
176 * sure that all the updates are applied to the `ChannelMonitors` *before
177 * the set of channel monitors is given to the `ChannelManager`
178 * deserialization routine. See [`ChannelMonitor::update_monitor`] for
179 * applying a monitor update to a monitor. If full `ChannelMonitors` are
180 * persisted, then there is no need to persist individual updates.
182 * Note that there could be a performance tradeoff between persisting complete
183 * channel monitors on every update vs. persisting only updates and applying
184 * them in batches. The size of each monitor grows `O(number of state updates)`
185 * whereas updates are small and `O(1)`.
187 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
188 * if you return [`ChannelMonitorUpdateStatus::InProgress`].
190 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`,
191 * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and
192 * [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
194 * [`Writeable::write`]: crate::util::ser::Writeable::write
196 * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
198 public ChannelMonitorUpdateStatus update_persisted_channel(OutPoint channel_id, @Nullable ChannelMonitorUpdate update, ChannelMonitor data, MonitorUpdateId update_id) {
199 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);
200 Reference.reachabilityFence(this);
201 Reference.reachabilityFence(channel_id);
202 Reference.reachabilityFence(update);
203 Reference.reachabilityFence(data);
204 Reference.reachabilityFence(update_id);
205 if (this != null) { this.ptrs_to.add(channel_id); };
206 if (this != null) { this.ptrs_to.add(update); };
207 if (this != null) { this.ptrs_to.add(data); };
208 if (this != null) { this.ptrs_to.add(update_id); };