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 * The `Watch` trait defines behavior for watching on-chain activity pertaining to channels as
12 * blocks are connected and disconnected.
14 * Each channel is associated with a [`ChannelMonitor`]. Implementations of this trait are
15 * responsible for maintaining a set of monitors such that they can be updated as channel state
16 * changes. On each update, *all copies* of a [`ChannelMonitor`] must be updated and the update
17 * persisted to disk to ensure that the latest [`ChannelMonitor`] state can be reloaded if the
18 * application crashes.
20 * See method documentation and [`ChannelMonitorUpdateStatus`] for specific requirements.
22 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
23 public class Watch extends CommonBase {
24 final bindings.LDKWatch bindings_instance;
25 Watch(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
26 private Watch(bindings.LDKWatch arg) {
27 super(bindings.LDKWatch_new(arg));
28 this.ptrs_to.add(arg);
29 this.bindings_instance = arg;
31 @Override @SuppressWarnings("deprecation")
32 protected void finalize() throws Throwable {
33 if (ptr != 0) { bindings.Watch_free(ptr); } super.finalize();
36 * Destroys the object, freeing associated resources. After this call, any access
37 * to this object may result in a SEGFAULT or worse.
39 * You should generally NEVER call this method. You should let the garbage collector
40 * do this for you when it finalizes objects. However, it may be useful for types
41 * which represent locks and should be closed immediately to avoid holding locks
44 public void destroy() {
45 if (ptr != 0) { bindings.Watch_free(ptr); }
48 public static interface WatchInterface {
50 * Watches a channel identified by `funding_txo` using `monitor`.
52 * Implementations are responsible for watching the chain for the funding transaction along
53 * with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means
54 * calling [`block_connected`] and [`block_disconnected`] on the monitor.
56 * A return of `Err(())` indicates that the channel should immediately be force-closed without
57 * broadcasting the funding transaction.
59 * If the given `funding_txo` has previously been registered via `watch_channel`, `Err(())`
62 * [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch
63 * [`block_connected`]: channelmonitor::ChannelMonitor::block_connected
64 * [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected
66 Result_ChannelMonitorUpdateStatusNoneZ watch_channel(OutPoint funding_txo, ChannelMonitor monitor);
68 * Updates a channel identified by `funding_txo` by applying `update` to its monitor.
70 * Implementations must call [`ChannelMonitor::update_monitor`] with the given update. This
71 * may fail (returning an `Err(())`), in which case this should return
72 * [`ChannelMonitorUpdateStatus::InProgress`] (and the update should never complete). This
73 * generally implies the channel has been closed (either by the funding outpoint being spent
74 * on-chain or the [`ChannelMonitor`] having decided to do so and broadcasted a transaction),
75 * and the [`ChannelManager`] state will be updated once it sees the funding spend on-chain.
77 * In general, persistence failures should be retried after returning
78 * [`ChannelMonitorUpdateStatus::InProgress`] and eventually complete. If a failure truly
79 * cannot be retried, the node should shut down immediately after returning
80 * [`ChannelMonitorUpdateStatus::UnrecoverableError`], see its documentation for more info.
82 * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
84 ChannelMonitorUpdateStatus update_channel(OutPoint funding_txo, ChannelMonitorUpdate update);
86 * Returns any monitor events since the last call. Subsequent calls must only return new
89 * Note that after any block- or transaction-connection calls to a [`ChannelMonitor`], no
90 * further events may be returned here until the [`ChannelMonitor`] has been fully persisted
93 * For details on asynchronous [`ChannelMonitor`] updating and returning
94 * [`MonitorEvent::Completed`] here, see [`ChannelMonitorUpdateStatus::InProgress`].
96 ThreeTuple_OutPointCVec_MonitorEventZPublicKeyZ[] release_pending_monitor_events();
98 private static class LDKWatchHolder { Watch held; }
99 public static Watch new_impl(WatchInterface arg) {
100 final LDKWatchHolder impl_holder = new LDKWatchHolder();
101 impl_holder.held = new Watch(new bindings.LDKWatch() {
102 @Override public long watch_channel(long funding_txo, long monitor) {
103 org.ldk.structs.OutPoint funding_txo_hu_conv = null; if (funding_txo < 0 || funding_txo > 4096) { funding_txo_hu_conv = new org.ldk.structs.OutPoint(null, funding_txo); }
104 if (funding_txo_hu_conv != null) { funding_txo_hu_conv.ptrs_to.add(this); };
105 org.ldk.structs.ChannelMonitor monitor_hu_conv = null; if (monitor < 0 || monitor > 4096) { monitor_hu_conv = new org.ldk.structs.ChannelMonitor(null, monitor); }
106 if (monitor_hu_conv != null) { monitor_hu_conv.ptrs_to.add(this); };
107 Result_ChannelMonitorUpdateStatusNoneZ ret = arg.watch_channel(funding_txo_hu_conv, monitor_hu_conv);
108 Reference.reachabilityFence(arg);
109 long result = ret == null ? 0 : ret.clone_ptr();
112 @Override public ChannelMonitorUpdateStatus update_channel(long funding_txo, long update) {
113 org.ldk.structs.OutPoint funding_txo_hu_conv = null; if (funding_txo < 0 || funding_txo > 4096) { funding_txo_hu_conv = new org.ldk.structs.OutPoint(null, funding_txo); }
114 if (funding_txo_hu_conv != null) { funding_txo_hu_conv.ptrs_to.add(this); };
115 org.ldk.structs.ChannelMonitorUpdate update_hu_conv = null; if (update < 0 || update > 4096) { update_hu_conv = new org.ldk.structs.ChannelMonitorUpdate(null, update); }
116 ChannelMonitorUpdateStatus ret = arg.update_channel(funding_txo_hu_conv, update_hu_conv);
117 Reference.reachabilityFence(arg);
120 @Override public long[] release_pending_monitor_events() {
121 ThreeTuple_OutPointCVec_MonitorEventZPublicKeyZ[] ret = arg.release_pending_monitor_events();
122 Reference.reachabilityFence(arg);
123 long[] result = ret != null ? Arrays.stream(ret).mapToLong(ret_conv_49 -> ret_conv_49 == null ? 0 : ret_conv_49.clone_ptr()).toArray() : null;
127 return impl_holder.held;
130 * Watches a channel identified by `funding_txo` using `monitor`.
132 * Implementations are responsible for watching the chain for the funding transaction along
133 * with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means
134 * calling [`block_connected`] and [`block_disconnected`] on the monitor.
136 * A return of `Err(())` indicates that the channel should immediately be force-closed without
137 * broadcasting the funding transaction.
139 * If the given `funding_txo` has previously been registered via `watch_channel`, `Err(())`
142 * [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch
143 * [`block_connected`]: channelmonitor::ChannelMonitor::block_connected
144 * [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected
146 public Result_ChannelMonitorUpdateStatusNoneZ watch_channel(org.ldk.structs.OutPoint funding_txo, org.ldk.structs.ChannelMonitor monitor) {
147 long ret = bindings.Watch_watch_channel(this.ptr, funding_txo == null ? 0 : funding_txo.ptr, monitor == null ? 0 : monitor.ptr);
148 Reference.reachabilityFence(this);
149 Reference.reachabilityFence(funding_txo);
150 Reference.reachabilityFence(monitor);
151 if (ret >= 0 && ret <= 4096) { return null; }
152 Result_ChannelMonitorUpdateStatusNoneZ ret_hu_conv = Result_ChannelMonitorUpdateStatusNoneZ.constr_from_ptr(ret);
153 if (this != null) { this.ptrs_to.add(funding_txo); };
154 if (this != null) { this.ptrs_to.add(monitor); };
159 * Updates a channel identified by `funding_txo` by applying `update` to its monitor.
161 * Implementations must call [`ChannelMonitor::update_monitor`] with the given update. This
162 * may fail (returning an `Err(())`), in which case this should return
163 * [`ChannelMonitorUpdateStatus::InProgress`] (and the update should never complete). This
164 * generally implies the channel has been closed (either by the funding outpoint being spent
165 * on-chain or the [`ChannelMonitor`] having decided to do so and broadcasted a transaction),
166 * and the [`ChannelManager`] state will be updated once it sees the funding spend on-chain.
168 * In general, persistence failures should be retried after returning
169 * [`ChannelMonitorUpdateStatus::InProgress`] and eventually complete. If a failure truly
170 * cannot be retried, the node should shut down immediately after returning
171 * [`ChannelMonitorUpdateStatus::UnrecoverableError`], see its documentation for more info.
173 * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
175 public ChannelMonitorUpdateStatus update_channel(org.ldk.structs.OutPoint funding_txo, org.ldk.structs.ChannelMonitorUpdate update) {
176 ChannelMonitorUpdateStatus ret = bindings.Watch_update_channel(this.ptr, funding_txo == null ? 0 : funding_txo.ptr, update == null ? 0 : update.ptr);
177 Reference.reachabilityFence(this);
178 Reference.reachabilityFence(funding_txo);
179 Reference.reachabilityFence(update);
180 if (this != null) { this.ptrs_to.add(funding_txo); };
181 if (this != null) { this.ptrs_to.add(update); };
186 * Returns any monitor events since the last call. Subsequent calls must only return new
189 * Note that after any block- or transaction-connection calls to a [`ChannelMonitor`], no
190 * further events may be returned here until the [`ChannelMonitor`] has been fully persisted
193 * For details on asynchronous [`ChannelMonitor`] updating and returning
194 * [`MonitorEvent::Completed`] here, see [`ChannelMonitorUpdateStatus::InProgress`].
196 public ThreeTuple_OutPointCVec_MonitorEventZPublicKeyZ[] release_pending_monitor_events() {
197 long[] ret = bindings.Watch_release_pending_monitor_events(this.ptr);
198 Reference.reachabilityFence(this);
199 int ret_conv_49_len = ret.length;
200 ThreeTuple_OutPointCVec_MonitorEventZPublicKeyZ[] ret_conv_49_arr = new ThreeTuple_OutPointCVec_MonitorEventZPublicKeyZ[ret_conv_49_len];
201 for (int x = 0; x < ret_conv_49_len; x++) {
202 long ret_conv_49 = ret[x];
203 ThreeTuple_OutPointCVec_MonitorEventZPublicKeyZ ret_conv_49_hu_conv = new ThreeTuple_OutPointCVec_MonitorEventZPublicKeyZ(null, ret_conv_49);
204 if (ret_conv_49_hu_conv != null) { ret_conv_49_hu_conv.ptrs_to.add(this); };
205 ret_conv_49_arr[x] = ret_conv_49_hu_conv;
207 return ret_conv_49_arr;