_ Git - ldk-java/blob - src/main/java/org/ldk/structs/Confirm.java

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