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