_ 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 when transactions have been confirmed on chain or
  12  * 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 client may implement [`Filter`] by subscribing to activity
  16  * related to registered transactions and outputs. Upon notification, it would pass along the
  17  * matching transactions using this interface.
  18  *
  19  * # Use
  20  *
  21  * The intended use is as follows:
  22  * - Call [`transactions_confirmed`] to process any on-chain activity of interest.
  23  * - Call [`transaction_unconfirmed`] to process any transaction returned by [`get_relevant_txids`]
  24  * that has been reorganized out of the chain.
  25  * - Call [`best_block_updated`] whenever a new chain tip becomes available.
  26  *
  27  * # Order
  28  *
  29  * Clients must call these methods in chain order. Specifically:
  30  * - Transactions confirmed in a block must be given before transactions confirmed in a later
  31  * block.
  32  * - Dependent transactions within the same block must be given in topological order, possibly in
  33  * separate calls.
  34  * - Unconfirmed transactions must be given after the original confirmations and before any
  35  * reconfirmation.
  36  *
  37  * See individual method documentation for further details.
  38  *
  39  * [`transactions_confirmed`]: Self::transactions_confirmed
  40  * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
  41  * [`best_block_updated`]: Self::best_block_updated
  42  * [`get_relevant_txids`]: Self::get_relevant_txids
  43  */
  44 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  45 public class Confirm extends CommonBase {
  46         final bindings.LDKConfirm bindings_instance;
  47         Confirm(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
  48         private Confirm(bindings.LDKConfirm arg) {
  49                 super(bindings.LDKConfirm_new(arg));
  50                 this.ptrs_to.add(arg);
  51                 this.bindings_instance = arg;
  52         }
  53         @Override @SuppressWarnings("deprecation")
  54         protected void finalize() throws Throwable {
  55                 if (ptr != 0) { bindings.Confirm_free(ptr); } super.finalize();
  56         }
  57
  58         public static interface ConfirmInterface {
  59                 /**
  60                  * Processes transactions confirmed in a block with a given header and height.
  61                  *
  62                  * Should be called for any transactions registered by [`Filter::register_tx`] or any
  63                  * transactions spending an output registered by [`Filter::register_output`]. Such transactions
  64                  * appearing in the same block do not need to be included in the same call; instead, multiple
  65                  * calls with additional transactions may be made so long as they are made in [chain order].
  66                  *
  67                  * May be called before or after [`best_block_updated`] for the corresponding block. However,
  68                  * in the event of a chain reorganization, it must not be called with a `header` that is no
  69                  * longer in the chain as of the last call to [`best_block_updated`].
  70                  *
  71                  * [chain order]: Confirm#Order
  72                  * [`best_block_updated`]: Self::best_block_updated
  73                  */
  74                 void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height);
  75                 /**
  76                  * Processes a transaction that is no longer confirmed as result of a chain reorganization.
  77                  *
  78                  * Should be called for any transaction returned by [`get_relevant_txids`] if it has been
  79                  * reorganized out of the best chain. Once called, the given transaction should 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                  * Processes an update to the best header connected at the given height.
  88                  *
  89                  * Should be called when a new header is available but may be skipped for intermediary blocks
  90                  * if they become available at the same time.
  91                  */
  92                 void best_block_updated(byte[] header, int height);
  93                 /**
  94                  * Returns transactions that should be monitored for reorganization out of the chain.
  95                  *
  96                  * Should include any transactions passed to [`transactions_confirmed`] that have insufficient
  97                  * confirmations to be safe from a chain reorganization. Should not include any transactions
  98                  * passed to [`transaction_unconfirmed`] unless later reconfirmed.
  99                  *
 100                  * May be called to determine the subset of transactions that must still be monitored for
 101                  * reorganization. Will be idempotent between calls but may change as a result of calls to the
 102                  * other interface methods. Thus, this is useful to determine which transactions may need to be
 103                  * given to [`transaction_unconfirmed`].
 104                  *
 105                  * [`transactions_confirmed`]: Self::transactions_confirmed
 106                  * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
 107                  */
 108                 byte[][] get_relevant_txids();
 109         }
 110         private static class LDKConfirmHolder { Confirm held; }
 111         public static Confirm new_impl(ConfirmInterface arg) {
 112                 final LDKConfirmHolder impl_holder = new LDKConfirmHolder();
 113                 impl_holder.held = new Confirm(new bindings.LDKConfirm() {
 114                         @Override public void transactions_confirmed(byte[] header, long[] txdata, int height) {
 115                                 int txdata_conv_28_len = txdata.length;
 116                                 TwoTuple_usizeTransactionZ[] txdata_conv_28_arr = new TwoTuple_usizeTransactionZ[txdata_conv_28_len];
 117                                 for (int c = 0; c < txdata_conv_28_len; c++) {
 118                                         long txdata_conv_28 = txdata[c];
 119                                         TwoTuple_usizeTransactionZ txdata_conv_28_hu_conv = new TwoTuple_usizeTransactionZ(null, txdata_conv_28);
 120                                         txdata_conv_28_hu_conv.ptrs_to.add(this);
 121                                         txdata_conv_28_arr[c] = txdata_conv_28_hu_conv;
 122                                 }
 123                                 arg.transactions_confirmed(header, txdata_conv_28_arr, height);
 124                                 Reference.reachabilityFence(arg);
 125                         }
 126                         @Override public void transaction_unconfirmed(byte[] txid) {
 127                                 arg.transaction_unconfirmed(txid);
 128                                 Reference.reachabilityFence(arg);
 129                         }
 130                         @Override public void best_block_updated(byte[] header, int height) {
 131                                 arg.best_block_updated(header, height);
 132                                 Reference.reachabilityFence(arg);
 133                         }
 134                         @Override public byte[][] get_relevant_txids() {
 135                                 byte[][] ret = arg.get_relevant_txids();
 136                                 Reference.reachabilityFence(arg);
 137                                 byte[][] result = ret != null ? Arrays.stream(ret).map(ret_conv_8 -> InternalUtils.check_arr_len(ret_conv_8, 32)).toArray(byte[][]::new) : null;
 138                                 return result;
 139                         }
 140                 });
 141                 return impl_holder.held;
 142         }
 143         /**
 144          * Processes transactions confirmed in a block with a given header and height.
 145          *
 146          * Should be called for any transactions registered by [`Filter::register_tx`] or any
 147          * transactions spending an output registered by [`Filter::register_output`]. Such transactions
 148          * appearing in the same block do not need to be included in the same call; instead, multiple
 149          * calls with additional transactions may be made so long as they are made in [chain order].
 150          *
 151          * May be called before or after [`best_block_updated`] for the corresponding block. However,
 152          * in the event of a chain reorganization, it must not be called with a `header` that is no
 153          * longer in the chain as of the last call to [`best_block_updated`].
 154          *
 155          * [chain order]: Confirm#Order
 156          * [`best_block_updated`]: Self::best_block_updated
 157          */
 158         public void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height) {
 159                 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);
 160                 Reference.reachabilityFence(this);
 161                 Reference.reachabilityFence(header);
 162                 Reference.reachabilityFence(txdata);
 163                 Reference.reachabilityFence(height);
 164         }
 165
 166         /**
 167          * Processes a transaction that is no longer confirmed as result of a chain reorganization.
 168          *
 169          * Should be called for any transaction returned by [`get_relevant_txids`] if it has been
 170          * reorganized out of the best chain. Once called, the given transaction should not be returned
 171          * by [`get_relevant_txids`] unless it has been reconfirmed via [`transactions_confirmed`].
 172          *
 173          * [`get_relevant_txids`]: Self::get_relevant_txids
 174          * [`transactions_confirmed`]: Self::transactions_confirmed
 175          */
 176         public void transaction_unconfirmed(byte[] txid) {
 177                 bindings.Confirm_transaction_unconfirmed(this.ptr, InternalUtils.check_arr_len(txid, 32));
 178                 Reference.reachabilityFence(this);
 179                 Reference.reachabilityFence(txid);
 180         }
 181
 182         /**
 183          * Processes an update to the best header connected at the given height.
 184          *
 185          * Should be called when a new header is available but may be skipped for intermediary blocks
 186          * if they become available at the same time.
 187          */
 188         public void best_block_updated(byte[] header, int height) {
 189                 bindings.Confirm_best_block_updated(this.ptr, InternalUtils.check_arr_len(header, 80), height);
 190                 Reference.reachabilityFence(this);
 191                 Reference.reachabilityFence(header);
 192                 Reference.reachabilityFence(height);
 193         }
 194
 195         /**
 196          * Returns transactions that should be monitored for reorganization out of the chain.
 197          *
 198          * Should include any transactions passed to [`transactions_confirmed`] that have insufficient
 199          * confirmations to be safe from a chain reorganization. Should not include any transactions
 200          * passed to [`transaction_unconfirmed`] unless later reconfirmed.
 201          *
 202          * May be called to determine the subset of transactions that must still be monitored for
 203          * reorganization. Will be idempotent between calls but may change as a result of calls to the
 204          * other interface methods. Thus, this is useful to determine which transactions may need to be
 205          * given to [`transaction_unconfirmed`].
 206          *
 207          * [`transactions_confirmed`]: Self::transactions_confirmed
 208          * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
 209          */
 210         public byte[][] get_relevant_txids() {
 211                 byte[][] ret = bindings.Confirm_get_relevant_txids(this.ptr);
 212                 Reference.reachabilityFence(this);
 213                 return ret;
 214         }
 215
 216 }