_ Git - ldk-java/blob - c_sharp/src/org/ldk/structs/ChainMonitor.cs

   1 using org.ldk.impl;
   2 using org.ldk.enums;
   3 using org.ldk.util;
   4 using System;
   5
   6 namespace org { namespace ldk { namespace structs {
   7
   8
   9 /**
  10  * An implementation of [`chain::Watch`] for monitoring channels.
  11  *
  12  * Connected and disconnected blocks must be provided to `ChainMonitor` as documented by
  13  * [`chain::Watch`]. May be used in conjunction with [`ChannelManager`] to monitor channels locally
  14  * or used independently to monitor channels remotely. See the [module-level documentation] for
  15  * details.
  16  *
  17  * Note that `ChainMonitor` should regularly trigger rebroadcasts/fee bumps of pending claims from
  18  * a force-closed channel. This is crucial in preventing certain classes of pinning attacks,
  19  * detecting substantial mempool feerate changes between blocks, and ensuring reliability if
  20  * broadcasting fails. We recommend invoking this every 30 seconds, or lower if running in an
  21  * environment with spotty connections, like on mobile.
  22  *
  23  * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
  24  * [module-level documentation]: crate::chain::chainmonitor
  25  * [`rebroadcast_pending_claims`]: Self::rebroadcast_pending_claims
  26  */
  27 public class ChainMonitor : CommonBase {
  28         internal ChainMonitor(object _dummy, long ptr) : base(ptr) { }
  29         ~ChainMonitor() {
  30                 if (ptr != 0) { bindings.ChainMonitor_free(ptr); }
  31         }
  32
  33         /**
  34          * Creates a new `ChainMonitor` used to watch on-chain activity pertaining to channels.
  35          *
  36          * When an optional chain source implementing [`chain::Filter`] is provided, the chain monitor
  37          * will call back to it indicating transactions and outputs of interest. This allows clients to
  38          * pre-filter blocks or only fetch blocks matching a compact filter. Otherwise, clients may
  39          * always need to fetch full blocks absent another means for determining which blocks contain
  40          * transactions relevant to the watched channels.
  41          */
  42         public static ChainMonitor of(org.ldk.structs.Option_FilterZ chain_source, org.ldk.structs.BroadcasterInterface broadcaster, org.ldk.structs.Logger logger, org.ldk.structs.FeeEstimator feeest, org.ldk.structs.Persist persister) {
  43                 long ret = bindings.ChainMonitor_new(chain_source.ptr, broadcaster.ptr, logger.ptr, feeest.ptr, persister.ptr);
  44                 GC.KeepAlive(chain_source);
  45                 GC.KeepAlive(broadcaster);
  46                 GC.KeepAlive(logger);
  47                 GC.KeepAlive(feeest);
  48                 GC.KeepAlive(persister);
  49                 if (ret >= 0 && ret <= 4096) { return null; }
  50                 org.ldk.structs.ChainMonitor ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ChainMonitor(null, ret); }
  51                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(ret_hu_conv); };
  52                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(chain_source); };
  53                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(broadcaster); };
  54                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(logger); };
  55                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(feeest); };
  56                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(persister); };
  57                 return ret_hu_conv;
  58         }
  59
  60         /**
  61          * Gets the balances in the contained [`ChannelMonitor`]s which are claimable on-chain or
  62          * claims which are awaiting confirmation.
  63          *
  64          * Includes the balances from each [`ChannelMonitor`] *except* those included in
  65          * `ignored_channels`, allowing you to filter out balances from channels which are still open
  66          * (and whose balance should likely be pulled from the [`ChannelDetails`]).
  67          *
  68          * See [`ChannelMonitor::get_claimable_balances`] for more details on the exact criteria for
  69          * inclusion in the return value.
  70          */
  71         public Balance[] get_claimable_balances(ChannelDetails[] ignored_channels) {
  72                 long ret = bindings.ChainMonitor_get_claimable_balances(this.ptr, InternalUtils.encodeUint64Array(InternalUtils.mapArray(ignored_channels, ignored_channels_conv_16 => ignored_channels_conv_16 == null ? 0 : ignored_channels_conv_16.ptr)));
  73                 GC.KeepAlive(this);
  74                 GC.KeepAlive(ignored_channels);
  75                 if (ret >= 0 && ret <= 4096) { return null; }
  76                 int ret_conv_9_len = InternalUtils.getArrayLength(ret);
  77                 Balance[] ret_conv_9_arr = new Balance[ret_conv_9_len];
  78                 for (int j = 0; j < ret_conv_9_len; j++) {
  79                         long ret_conv_9 = InternalUtils.getU64ArrayElem(ret, j);
  80                         org.ldk.structs.Balance ret_conv_9_hu_conv = org.ldk.structs.Balance.constr_from_ptr(ret_conv_9);
  81                         if (ret_conv_9_hu_conv != null) { ret_conv_9_hu_conv.ptrs_to.AddLast(this); };
  82                         ret_conv_9_arr[j] = ret_conv_9_hu_conv;
  83                 }
  84                 bindings.free_buffer(ret);
  85                 foreach (ChannelDetails ignored_channels_conv_16 in ignored_channels) { if (this != null) { this.ptrs_to.AddLast(ignored_channels_conv_16); }; };
  86                 return ret_conv_9_arr;
  87         }
  88
  89         /**
  90          * Gets the [`LockedChannelMonitor`] for a given funding outpoint, returning an `Err` if no
  91          * such [`ChannelMonitor`] is currently being monitored for.
  92          *
  93          * Note that the result holds a mutex over our monitor set, and should not be held
  94          * indefinitely.
  95          */
  96         public Result_LockedChannelMonitorNoneZ get_monitor(org.ldk.structs.OutPoint funding_txo) {
  97                 long ret = bindings.ChainMonitor_get_monitor(this.ptr, funding_txo == null ? 0 : funding_txo.ptr);
  98                 GC.KeepAlive(this);
  99                 GC.KeepAlive(funding_txo);
 100                 if (ret >= 0 && ret <= 4096) { return null; }
 101                 Result_LockedChannelMonitorNoneZ ret_hu_conv = Result_LockedChannelMonitorNoneZ.constr_from_ptr(ret);
 102                 if (this != null) { this.ptrs_to.AddLast(funding_txo); };
 103                 return ret_hu_conv;
 104         }
 105
 106         /**
 107          * Lists the funding outpoint of each [`ChannelMonitor`] being monitored.
 108          *
 109          * Note that [`ChannelMonitor`]s are not removed when a channel is closed as they are always
 110          * monitoring for on-chain state resolutions.
 111          */
 112         public OutPoint[] list_monitors() {
 113                 long ret = bindings.ChainMonitor_list_monitors(this.ptr);
 114                 GC.KeepAlive(this);
 115                 if (ret >= 0 && ret <= 4096) { return null; }
 116                 int ret_conv_10_len = InternalUtils.getArrayLength(ret);
 117                 OutPoint[] ret_conv_10_arr = new OutPoint[ret_conv_10_len];
 118                 for (int k = 0; k < ret_conv_10_len; k++) {
 119                         long ret_conv_10 = InternalUtils.getU64ArrayElem(ret, k);
 120                         org.ldk.structs.OutPoint ret_conv_10_hu_conv = null; if (ret_conv_10 < 0 || ret_conv_10 > 4096) { ret_conv_10_hu_conv = new org.ldk.structs.OutPoint(null, ret_conv_10); }
 121                         if (ret_conv_10_hu_conv != null) { ret_conv_10_hu_conv.ptrs_to.AddLast(this); };
 122                         ret_conv_10_arr[k] = ret_conv_10_hu_conv;
 123                 }
 124                 bindings.free_buffer(ret);
 125                 return ret_conv_10_arr;
 126         }
 127
 128         /**
 129          * Lists the pending updates for each [`ChannelMonitor`] (by `OutPoint` being monitored).
 130          */
 131         public TwoTuple_OutPointCVec_MonitorUpdateIdZZ[] list_pending_monitor_updates() {
 132                 long ret = bindings.ChainMonitor_list_pending_monitor_updates(this.ptr);
 133                 GC.KeepAlive(this);
 134                 if (ret >= 0 && ret <= 4096) { return null; }
 135                 int ret_conv_41_len = InternalUtils.getArrayLength(ret);
 136                 TwoTuple_OutPointCVec_MonitorUpdateIdZZ[] ret_conv_41_arr = new TwoTuple_OutPointCVec_MonitorUpdateIdZZ[ret_conv_41_len];
 137                 for (int p = 0; p < ret_conv_41_len; p++) {
 138                         long ret_conv_41 = InternalUtils.getU64ArrayElem(ret, p);
 139                         TwoTuple_OutPointCVec_MonitorUpdateIdZZ ret_conv_41_hu_conv = new TwoTuple_OutPointCVec_MonitorUpdateIdZZ(null, ret_conv_41);
 140                         if (ret_conv_41_hu_conv != null) { ret_conv_41_hu_conv.ptrs_to.AddLast(this); };
 141                         ret_conv_41_arr[p] = ret_conv_41_hu_conv;
 142                 }
 143                 bindings.free_buffer(ret);
 144                 return ret_conv_41_arr;
 145         }
 146
 147         /**
 148          * Indicates the persistence of a [`ChannelMonitor`] has completed after
 149          * [`ChannelMonitorUpdateStatus::InProgress`] was returned from an update operation.
 150          *
 151          * Thus, the anticipated use is, at a high level:
 152          * 1) This [`ChainMonitor`] calls [`Persist::update_persisted_channel`] which stores the
 153          * update to disk and begins updating any remote (e.g. watchtower/backup) copies,
 154          * returning [`ChannelMonitorUpdateStatus::InProgress`],
 155          * 2) once all remote copies are updated, you call this function with the
 156          * `completed_update_id` that completed, and once all pending updates have completed the
 157          * channel will be re-enabled.
 158          *
 159          * Returns an [`APIError::APIMisuseError`] if `funding_txo` does not match any currently
 160          * registered [`ChannelMonitor`]s.
 161          */
 162         public Result_NoneAPIErrorZ channel_monitor_updated(org.ldk.structs.OutPoint funding_txo, org.ldk.structs.MonitorUpdateId completed_update_id) {
 163                 long ret = bindings.ChainMonitor_channel_monitor_updated(this.ptr, funding_txo == null ? 0 : funding_txo.ptr, completed_update_id == null ? 0 : completed_update_id.ptr);
 164                 GC.KeepAlive(this);
 165                 GC.KeepAlive(funding_txo);
 166                 GC.KeepAlive(completed_update_id);
 167                 if (ret >= 0 && ret <= 4096) { return null; }
 168                 Result_NoneAPIErrorZ ret_hu_conv = Result_NoneAPIErrorZ.constr_from_ptr(ret);
 169                 if (this != null) { this.ptrs_to.AddLast(funding_txo); };
 170                 if (this != null) { this.ptrs_to.AddLast(completed_update_id); };
 171                 return ret_hu_conv;
 172         }
 173
 174         /**
 175          * Gets a [`Future`] that completes when an event is available either via
 176          * [`chain::Watch::release_pending_monitor_events`] or
 177          * [`EventsProvider::process_pending_events`].
 178          *
 179          * Note that callbacks registered on the [`Future`] MUST NOT call back into this
 180          * [`ChainMonitor`] and should instead register actions to be taken later.
 181          *
 182          * [`EventsProvider::process_pending_events`]: crate::events::EventsProvider::process_pending_events
 183          */
 184         public Future get_update_future() {
 185                 long ret = bindings.ChainMonitor_get_update_future(this.ptr);
 186                 GC.KeepAlive(this);
 187                 if (ret >= 0 && ret <= 4096) { return null; }
 188                 org.ldk.structs.Future ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.Future(null, ret); }
 189                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(this); };
 190                 return ret_hu_conv;
 191         }
 192
 193         /**
 194          * Triggers rebroadcasts/fee-bumps of pending claims from a force-closed channel. This is
 195          * crucial in preventing certain classes of pinning attacks, detecting substantial mempool
 196          * feerate changes between blocks, and ensuring reliability if broadcasting fails. We recommend
 197          * invoking this every 30 seconds, or lower if running in an environment with spotty
 198          * connections, like on mobile.
 199          */
 200         public void rebroadcast_pending_claims() {
 201                 bindings.ChainMonitor_rebroadcast_pending_claims(this.ptr);
 202                 GC.KeepAlive(this);
 203         }
 204
 205         /**
 206          * Constructs a new Listen which calls the relevant methods on this_arg.
 207          * This copies the `inner` pointer in this_arg and thus the returned Listen must be freed before this_arg is
 208          */
 209         public Listen as_Listen() {
 210                 long ret = bindings.ChainMonitor_as_Listen(this.ptr);
 211                 GC.KeepAlive(this);
 212                 if (ret >= 0 && ret <= 4096) { return null; }
 213                 Listen ret_hu_conv = new Listen(null, ret);
 214                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(this); };
 215                 return ret_hu_conv;
 216         }
 217
 218         /**
 219          * Constructs a new Confirm which calls the relevant methods on this_arg.
 220          * This copies the `inner` pointer in this_arg and thus the returned Confirm must be freed before this_arg is
 221          */
 222         public Confirm as_Confirm() {
 223                 long ret = bindings.ChainMonitor_as_Confirm(this.ptr);
 224                 GC.KeepAlive(this);
 225                 if (ret >= 0 && ret <= 4096) { return null; }
 226                 Confirm ret_hu_conv = new Confirm(null, ret);
 227                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(this); };
 228                 return ret_hu_conv;
 229         }
 230
 231         /**
 232          * Constructs a new Watch which calls the relevant methods on this_arg.
 233          * This copies the `inner` pointer in this_arg and thus the returned Watch must be freed before this_arg is
 234          */
 235         public Watch as_Watch() {
 236                 long ret = bindings.ChainMonitor_as_Watch(this.ptr);
 237                 GC.KeepAlive(this);
 238                 if (ret >= 0 && ret <= 4096) { return null; }
 239                 Watch ret_hu_conv = new Watch(null, ret);
 240                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(this); };
 241                 return ret_hu_conv;
 242         }
 243
 244         /**
 245          * Constructs a new EventsProvider which calls the relevant methods on this_arg.
 246          * This copies the `inner` pointer in this_arg and thus the returned EventsProvider must be freed before this_arg is
 247          */
 248         public EventsProvider as_EventsProvider() {
 249                 long ret = bindings.ChainMonitor_as_EventsProvider(this.ptr);
 250                 GC.KeepAlive(this);
 251                 if (ret >= 0 && ret <= 4096) { return null; }
 252                 EventsProvider ret_hu_conv = new EventsProvider(null, ret);
 253                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(this); };
 254                 return ret_hu_conv;
 255         }
 256
 257 }
 258 } } }