6 namespace org { namespace ldk { namespace structs {
9 * `Persist` defines behavior for persisting channel monitors: this could mean
10 * writing once to disk, and/or uploading to one or more backup services.
12 * Each method can return three possible values:
13 * If persistence (including any relevant `fsync()` calls) happens immediately, the
14 * implementation should return [`ChannelMonitorUpdateStatus::Completed`], indicating normal
15 * 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 * [`ChannelMonitorUpdateStatus::InProgress`] while the update continues in the background.
19 * Once the update completes, [`ChainMonitor::channel_monitor_updated`] should be called with
20 * 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 * [`ChannelMonitorUpdateStatus::PermanentFailure`], in which case the channel will likely be
27 * closed without broadcasting the latest state. See
28 * [`ChannelMonitorUpdateStatus::PermanentFailure`] for more details.
30 public class Persist : CommonBase {
31 internal readonly bindings.LDKPersist bindings_instance;
32 internal Persist(object _dummy, long ptr) : base(ptr) { bindings_instance = null; }
33 private Persist(bindings.LDKPersist arg) : base(bindings.LDKPersist_new(arg)) {
34 this.ptrs_to.AddLast(arg);
35 this.bindings_instance = arg;
38 if (ptr != 0) { bindings.Persist_free(ptr); }
41 public interface PersistInterface {
43 * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is
44 * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup.
46 * The data can be stored any way you want, but the identifier provided by LDK is the
47 * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint
48 * and the stored channel data). Note that you **must** persist every new monitor to disk.
50 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
51 * if you return [`ChannelMonitorUpdateStatus::InProgress`].
53 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
54 * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
56 * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
57 * [`Writeable::write`]: crate::util::ser::Writeable::write
59 ChannelMonitorUpdateStatus persist_new_channel(OutPoint _channel_id, ChannelMonitor _data, MonitorUpdateId _update_id);
61 * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
64 * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the
65 * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
68 * During blockchain synchronization operations, this may be called with no
69 * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
70 * Note that after the full [`ChannelMonitor`] is persisted any previous
71 * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
72 * applied to the persisted [`ChannelMonitor`] as they were already applied.
74 * If an implementer chooses to persist the updates only, they need to make
75 * sure that all the updates are applied to the `ChannelMonitors` *before
76 * the set of channel monitors is given to the `ChannelManager`
77 * deserialization routine. See [`ChannelMonitor::update_monitor`] for
78 * applying a monitor update to a monitor. If full `ChannelMonitors` are
79 * persisted, then there is no need to persist individual updates.
81 * Note that there could be a performance tradeoff between persisting complete
82 * channel monitors on every update vs. persisting only updates and applying
83 * them in batches. The size of each monitor grows `O(number of state updates)`
84 * whereas updates are small and `O(1)`.
86 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
87 * if you return [`ChannelMonitorUpdateStatus::InProgress`].
89 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`,
90 * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and
91 * [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
93 * [`Writeable::write`]: crate::util::ser::Writeable::write
95 * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
97 ChannelMonitorUpdateStatus update_persisted_channel(OutPoint _channel_id, ChannelMonitorUpdate _update, ChannelMonitor _data, MonitorUpdateId _update_id);
99 private class LDKPersistHolder { internal Persist held; }
100 private class LDKPersistImpl : bindings.LDKPersist {
101 internal LDKPersistImpl(PersistInterface arg, LDKPersistHolder impl_holder) { this.arg = arg; this.impl_holder = impl_holder; }
102 private PersistInterface arg;
103 private LDKPersistHolder impl_holder;
104 public ChannelMonitorUpdateStatus persist_new_channel(long _channel_id, long _data, long _update_id) {
105 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); }
106 if (_channel_id_hu_conv != null) { _channel_id_hu_conv.ptrs_to.AddLast(this); };
107 org.ldk.structs.ChannelMonitor _data_hu_conv = null; if (_data < 0 || _data > 4096) { _data_hu_conv = new org.ldk.structs.ChannelMonitor(null, _data); }
108 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); }
109 if (_update_id_hu_conv != null) { _update_id_hu_conv.ptrs_to.AddLast(this); };
110 ChannelMonitorUpdateStatus ret = arg.persist_new_channel(_channel_id_hu_conv, _data_hu_conv, _update_id_hu_conv);
114 public ChannelMonitorUpdateStatus update_persisted_channel(long _channel_id, long _update, long _data, long _update_id) {
115 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); }
116 if (_channel_id_hu_conv != null) { _channel_id_hu_conv.ptrs_to.AddLast(this); };
117 org.ldk.structs.ChannelMonitorUpdate _update_hu_conv = null; if (_update < 0 || _update > 4096) { _update_hu_conv = new org.ldk.structs.ChannelMonitorUpdate(null, _update); }
118 org.ldk.structs.ChannelMonitor _data_hu_conv = null; if (_data < 0 || _data > 4096) { _data_hu_conv = new org.ldk.structs.ChannelMonitor(null, _data); }
119 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); }
120 if (_update_id_hu_conv != null) { _update_id_hu_conv.ptrs_to.AddLast(this); };
121 ChannelMonitorUpdateStatus ret = arg.update_persisted_channel(_channel_id_hu_conv, _update_hu_conv, _data_hu_conv, _update_id_hu_conv);
126 public static Persist new_impl(PersistInterface arg) {
127 LDKPersistHolder impl_holder = new LDKPersistHolder();
128 impl_holder.held = new Persist(new LDKPersistImpl(arg, impl_holder));
129 return impl_holder.held;
132 * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is
133 * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup.
135 * The data can be stored any way you want, but the identifier provided by LDK is the
136 * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint
137 * and the stored channel data). Note that you **must** persist every new monitor to disk.
139 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
140 * if you return [`ChannelMonitorUpdateStatus::InProgress`].
142 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`
143 * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
145 * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
146 * [`Writeable::write`]: crate::util::ser::Writeable::write
148 public ChannelMonitorUpdateStatus persist_new_channel(org.ldk.structs.OutPoint channel_id, org.ldk.structs.ChannelMonitor data, org.ldk.structs.MonitorUpdateId update_id) {
149 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 GC.KeepAlive(channel_id);
153 GC.KeepAlive(update_id);
154 if (this != null) { this.ptrs_to.AddLast(channel_id); };
155 if (this != null) { this.ptrs_to.AddLast(data); };
156 if (this != null) { this.ptrs_to.AddLast(update_id); };
161 * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given
164 * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the
165 * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
168 * During blockchain synchronization operations, this may be called with no
169 * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
170 * Note that after the full [`ChannelMonitor`] is persisted any previous
171 * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
172 * applied to the persisted [`ChannelMonitor`] as they were already applied.
174 * If an implementer chooses to persist the updates only, they need to make
175 * sure that all the updates are applied to the `ChannelMonitors` *before
176 * the set of channel monitors is given to the `ChannelManager`
177 * deserialization routine. See [`ChannelMonitor::update_monitor`] for
178 * applying a monitor update to a monitor. If full `ChannelMonitors` are
179 * persisted, then there is no need to persist individual updates.
181 * Note that there could be a performance tradeoff between persisting complete
182 * channel monitors on every update vs. persisting only updates and applying
183 * them in batches. The size of each monitor grows `O(number of state updates)`
184 * whereas updates are small and `O(1)`.
186 * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`],
187 * if you return [`ChannelMonitorUpdateStatus::InProgress`].
189 * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`,
190 * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and
191 * [`ChannelMonitorUpdateStatus`] for requirements when returning errors.
193 * [`Writeable::write`]: crate::util::ser::Writeable::write
195 * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
197 public ChannelMonitorUpdateStatus update_persisted_channel(org.ldk.structs.OutPoint channel_id, org.ldk.structs.ChannelMonitorUpdate update, org.ldk.structs.ChannelMonitor data, org.ldk.structs.MonitorUpdateId update_id) {
198 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 GC.KeepAlive(channel_id);
201 GC.KeepAlive(update);
203 GC.KeepAlive(update_id);
204 if (this != null) { this.ptrs_to.AddLast(channel_id); };
205 if (this != null) { this.ptrs_to.AddLast(update); };
206 if (this != null) { this.ptrs_to.AddLast(data); };
207 if (this != null) { this.ptrs_to.AddLast(update_id); };