_ Git - ldk-java/blob - c_sharp/src/org/ldk/structs/Confirm.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  * The `Confirm` trait is used to notify LDK when relevant transactions have been confirmed on
  10  * chain or unconfirmed during a chain reorganization.
  11  *
  12  * Clients sourcing chain data using a transaction-oriented API should prefer this interface over
  13  * [`Listen`]. For instance, an Electrum-based transaction sync implementation may implement
  14  * [`Filter`] to subscribe to relevant transactions and unspent outputs it should monitor for
  15  * on-chain activity. Then, it needs to notify LDK via this interface upon observing any changes
  16  * with reference to the confirmation status of the monitored objects.
  17  *
  18  * # Use
  19  * The intended use is as follows:
  20  * - Call [`transactions_confirmed`] to notify LDK whenever any of the registered transactions or
  21  * outputs are, respectively, confirmed or spent on chain.
  22  * - Call [`transaction_unconfirmed`] to notify LDK whenever any transaction returned by
  23  * [`get_relevant_txids`] is no longer confirmed in the block with the given block hash.
  24  * - Call [`best_block_updated`] to notify LDK whenever a new chain tip becomes available.
  25  *
  26  * # Order
  27  *
  28  * Clients must call these methods in chain order. Specifically:
  29  * - Transactions which are confirmed in a particular block must be given before transactions
  30  * confirmed in a later block.
  31  * - Dependent transactions within the same block must be given in topological order, possibly in
  32  * separate calls.
  33  * - All unconfirmed transactions must be given after the original confirmations and before *any*
  34  * reconfirmations, i.e., [`transactions_confirmed`] and [`transaction_unconfirmed`] calls should
  35  * never be interleaved, but always conduced *en bloc*.
  36  * - Any reconfirmed transactions need to be explicitly unconfirmed before they are reconfirmed
  37  * in regard to the new block.
  38  *
  39  * See individual method documentation for further details.
  40  *
  41  * [`transactions_confirmed`]: Self::transactions_confirmed
  42  * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
  43  * [`best_block_updated`]: Self::best_block_updated
  44  * [`get_relevant_txids`]: Self::get_relevant_txids
  45  */
  46 public class Confirm : CommonBase {
  47         internal readonly bindings.LDKConfirm bindings_instance;
  48         internal Confirm(object _dummy, long ptr) : base(ptr) { bindings_instance = null; }
  49         private Confirm(bindings.LDKConfirm arg) : base(bindings.LDKConfirm_new(arg)) {
  50                 this.ptrs_to.AddLast(arg);
  51                 this.bindings_instance = arg;
  52         }
  53         ~Confirm() {
  54                 if (ptr != 0) { bindings.Confirm_free(ptr); }
  55         }
  56
  57         public interface ConfirmInterface {
  58                 /**
  59                  * Notifies LDK of transactions confirmed in a block with a given header and height.
  60                  *
  61                  * Must be called for any transactions registered by [`Filter::register_tx`] or any
  62                  * transactions spending an output registered by [`Filter::register_output`]. Such transactions
  63                  * appearing in the same block do not need to be included in the same call; instead, multiple
  64                  * calls with additional transactions may be made so long as they are made in [chain order].
  65                  *
  66                  * May be called before or after [`best_block_updated`] for the corresponding block. However,
  67                  * in the event of a chain reorganization, it must not be called with a `header` that is no
  68                  * longer in the chain as of the last call to [`best_block_updated`].
  69                  *
  70                  * [chain order]: Confirm#order
  71                  * [`best_block_updated`]: Self::best_block_updated
  72                  */
  73                 void transactions_confirmed(byte[] _header, TwoTuple_usizeTransactionZ[] _txdata, int _height);
  74                 /**
  75                  * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
  76                  *
  77                  * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
  78                  * reorganized out of the best chain or if it is no longer confirmed in the block with the
  79                  * given block hash. Once called, the given transaction will not be returned
  80                  * by [`get_relevant_txids`], unless it has been reconfirmed via [`transactions_confirmed`].
  81                  *
  82                  * [`get_relevant_txids`]: Self::get_relevant_txids
  83                  * [`transactions_confirmed`]: Self::transactions_confirmed
  84                  */
  85                 void transaction_unconfirmed(byte[] _txid);
  86                 /**
  87                  * Notifies LDK of an update to the best header connected at the given height.
  88                  *
  89                  * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
  90                  * blocks.
  91                  */
  92                 void best_block_updated(byte[] _header, int _height);
  93                 /**
  94                  * Returns transactions that must be monitored for reorganization out of the chain along
  95                  * with the hash of the block as part of which it had been previously confirmed.
  96                  *
  97                  * Note that the returned `Option<BlockHash>` might be `None` for channels created with LDK
  98                  * 0.0.112 and prior, in which case you need to manually track previous confirmations.
  99                  *
 100                  * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
 101                  * confirmations to be safe from a chain reorganization. Will not include any transactions
 102                  * passed to [`transaction_unconfirmed`], unless later reconfirmed.
 103                  *
 104                  * Must be called to determine the subset of transactions that must be monitored for
 105                  * reorganization. Will be idempotent between calls but may change as a result of calls to the
 106                  * other interface methods. Thus, this is useful to determine which transactions must be
 107                  * given to [`transaction_unconfirmed`].
 108                  *
 109                  * If any of the returned transactions are confirmed in a block other than the one with the
 110                  * given hash, they need to be unconfirmed and reconfirmed via [`transaction_unconfirmed`] and
 111                  * [`transactions_confirmed`], respectively.
 112                  *
 113                  * [`transactions_confirmed`]: Self::transactions_confirmed
 114                  * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
 115                  */
 116                 TwoTuple_TxidCOption_BlockHashZZ[] get_relevant_txids();
 117         }
 118         private class LDKConfirmHolder { internal Confirm held; }
 119         private class LDKConfirmImpl : bindings.LDKConfirm {
 120                 internal LDKConfirmImpl(ConfirmInterface arg, LDKConfirmHolder impl_holder) { this.arg = arg; this.impl_holder = impl_holder; }
 121                 private ConfirmInterface arg;
 122                 private LDKConfirmHolder impl_holder;
 123                 public void transactions_confirmed(byte[] _header, long[] _txdata, int _height) {
 124                         int _txdata_conv_28_len = _txdata.Length;
 125                         TwoTuple_usizeTransactionZ[] _txdata_conv_28_arr = new TwoTuple_usizeTransactionZ[_txdata_conv_28_len];
 126                         for (int c = 0; c < _txdata_conv_28_len; c++) {
 127                                 long _txdata_conv_28 = _txdata[c];
 128                                 TwoTuple_usizeTransactionZ _txdata_conv_28_hu_conv = new TwoTuple_usizeTransactionZ(null, _txdata_conv_28);
 129                                 if (_txdata_conv_28_hu_conv != null) { _txdata_conv_28_hu_conv.ptrs_to.AddLast(this); };
 130                                 _txdata_conv_28_arr[c] = _txdata_conv_28_hu_conv;
 131                         }
 132                         arg.transactions_confirmed(_header, _txdata_conv_28_arr, _height);
 133                                 GC.KeepAlive(arg);
 134                 }
 135                 public void transaction_unconfirmed(byte[] _txid) {
 136                         arg.transaction_unconfirmed(_txid);
 137                                 GC.KeepAlive(arg);
 138                 }
 139                 public void best_block_updated(byte[] _header, int _height) {
 140                         arg.best_block_updated(_header, _height);
 141                                 GC.KeepAlive(arg);
 142                 }
 143                 public long[] get_relevant_txids() {
 144                         TwoTuple_TxidCOption_BlockHashZZ[] ret = arg.get_relevant_txids();
 145                                 GC.KeepAlive(arg);
 146                         long[] result = ret != null ? InternalUtils.mapArray(ret, ret_conv_34 => ret_conv_34 == null ? 0 : ret_conv_34.clone_ptr()) : null;
 147                         return result;
 148                 }
 149         }
 150         public static Confirm new_impl(ConfirmInterface arg) {
 151                 LDKConfirmHolder impl_holder = new LDKConfirmHolder();
 152                 impl_holder.held = new Confirm(new LDKConfirmImpl(arg, impl_holder));
 153                 return impl_holder.held;
 154         }
 155         /**
 156          * Notifies LDK of transactions confirmed in a block with a given header and height.
 157          *
 158          * Must be called for any transactions registered by [`Filter::register_tx`] or any
 159          * transactions spending an output registered by [`Filter::register_output`]. Such transactions
 160          * appearing in the same block do not need to be included in the same call; instead, multiple
 161          * calls with additional transactions may be made so long as they are made in [chain order].
 162          *
 163          * May be called before or after [`best_block_updated`] for the corresponding block. However,
 164          * in the event of a chain reorganization, it must not be called with a `header` that is no
 165          * longer in the chain as of the last call to [`best_block_updated`].
 166          *
 167          * [chain order]: Confirm#order
 168          * [`best_block_updated`]: Self::best_block_updated
 169          */
 170         public void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height) {
 171                 bindings.Confirm_transactions_confirmed(this.ptr, InternalUtils.check_arr_len(header, 80), txdata != null ? InternalUtils.mapArray(txdata, txdata_conv_28 => txdata_conv_28 != null ? txdata_conv_28.ptr : 0) : null, height);
 172                 GC.KeepAlive(this);
 173                 GC.KeepAlive(header);
 174                 GC.KeepAlive(txdata);
 175                 GC.KeepAlive(height);
 176         }
 177
 178         /**
 179          * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
 180          *
 181          * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
 182          * reorganized out of the best chain or if it is no longer confirmed in the block with the
 183          * given block hash. Once called, the given transaction will not be returned
 184          * by [`get_relevant_txids`], unless it has been reconfirmed via [`transactions_confirmed`].
 185          *
 186          * [`get_relevant_txids`]: Self::get_relevant_txids
 187          * [`transactions_confirmed`]: Self::transactions_confirmed
 188          */
 189         public void transaction_unconfirmed(byte[] txid) {
 190                 bindings.Confirm_transaction_unconfirmed(this.ptr, InternalUtils.check_arr_len(txid, 32));
 191                 GC.KeepAlive(this);
 192                 GC.KeepAlive(txid);
 193         }
 194
 195         /**
 196          * Notifies LDK of an update to the best header connected at the given height.
 197          *
 198          * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
 199          * blocks.
 200          */
 201         public void best_block_updated(byte[] header, int height) {
 202                 bindings.Confirm_best_block_updated(this.ptr, InternalUtils.check_arr_len(header, 80), height);
 203                 GC.KeepAlive(this);
 204                 GC.KeepAlive(header);
 205                 GC.KeepAlive(height);
 206         }
 207
 208         /**
 209          * Returns transactions that must be monitored for reorganization out of the chain along
 210          * with the hash of the block as part of which it had been previously confirmed.
 211          *
 212          * Note that the returned `Option<BlockHash>` might be `None` for channels created with LDK
 213          * 0.0.112 and prior, in which case you need to manually track previous confirmations.
 214          *
 215          * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
 216          * confirmations to be safe from a chain reorganization. Will not include any transactions
 217          * passed to [`transaction_unconfirmed`], unless later reconfirmed.
 218          *
 219          * Must be called to determine the subset of transactions that must be monitored for
 220          * reorganization. Will be idempotent between calls but may change as a result of calls to the
 221          * other interface methods. Thus, this is useful to determine which transactions must be
 222          * given to [`transaction_unconfirmed`].
 223          *
 224          * If any of the returned transactions are confirmed in a block other than the one with the
 225          * given hash, they need to be unconfirmed and reconfirmed via [`transaction_unconfirmed`] and
 226          * [`transactions_confirmed`], respectively.
 227          *
 228          * [`transactions_confirmed`]: Self::transactions_confirmed
 229          * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
 230          */
 231         public TwoTuple_TxidCOption_BlockHashZZ[] get_relevant_txids() {
 232                 long[] ret = bindings.Confirm_get_relevant_txids(this.ptr);
 233                 GC.KeepAlive(this);
 234                 int ret_conv_34_len = ret.Length;
 235                 TwoTuple_TxidCOption_BlockHashZZ[] ret_conv_34_arr = new TwoTuple_TxidCOption_BlockHashZZ[ret_conv_34_len];
 236                 for (int i = 0; i < ret_conv_34_len; i++) {
 237                         long ret_conv_34 = ret[i];
 238                         TwoTuple_TxidCOption_BlockHashZZ ret_conv_34_hu_conv = new TwoTuple_TxidCOption_BlockHashZZ(null, ret_conv_34);
 239                         if (ret_conv_34_hu_conv != null) { ret_conv_34_hu_conv.ptrs_to.AddLast(this); };
 240                         ret_conv_34_arr[i] = ret_conv_34_hu_conv;
 241                 }
 242                 return ret_conv_34_arr;
 243         }
 244
 245 }
 246 } } }