1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
7 import javax.annotation.Nullable;
10 * The `Confirm` trait is used to notify when transactions have been confirmed on chain or
11 * unconfirmed during a chain reorganization.
13 * Clients sourcing chain data using a transaction-oriented API should prefer this interface over
14 * [`Listen`]. For instance, an Electrum client may implement [`Filter`] by subscribing to activity
15 * related to registered transactions and outputs. Upon notification, it would pass along the
16 * matching transactions using this interface.
20 * The intended use is as follows:
21 * - Call [`transactions_confirmed`] to process any on-chain activity of interest.
22 * - Call [`transaction_unconfirmed`] to process any transaction returned by [`get_relevant_txids`]
23 * that has been reorganized out of the chain.
24 * - Call [`best_block_updated`] whenever a new chain tip becomes available.
28 * Clients must call these methods in chain order. Specifically:
29 * - Transactions confirmed in a block must be given before transactions confirmed in a later
31 * - Dependent transactions within the same block must be given in topological order, possibly in
33 * - Unconfirmed transactions must be given after the original confirmations and before any
36 * See individual method documentation for further details.
38 * [`transactions_confirmed`]: Self::transactions_confirmed
39 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
40 * [`best_block_updated`]: Self::best_block_updated
41 * [`get_relevant_txids`]: Self::get_relevant_txids
43 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
44 public class Confirm extends CommonBase {
45 final bindings.LDKConfirm bindings_instance;
46 Confirm(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
47 private Confirm(bindings.LDKConfirm arg) {
48 super(bindings.LDKConfirm_new(arg));
49 this.ptrs_to.add(arg);
50 this.bindings_instance = arg;
52 @Override @SuppressWarnings("deprecation")
53 protected void finalize() throws Throwable {
54 if (ptr != 0) { bindings.Confirm_free(ptr); } super.finalize();
57 public static interface ConfirmInterface {
59 * Processes transactions confirmed in a block with a given header and height.
61 * Should 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].
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`].
70 * [chain order]: Confirm#Order
71 * [`best_block_updated`]: Self::best_block_updated
73 void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height);
75 * Processes a transaction that is no longer confirmed as result of a chain reorganization.
77 * Should be called for any transaction returned by [`get_relevant_txids`] if it has been
78 * reorganized out of the best chain. Once called, the given transaction should not be returned
79 * by [`get_relevant_txids`] unless it has been reconfirmed via [`transactions_confirmed`].
81 * [`get_relevant_txids`]: Self::get_relevant_txids
82 * [`transactions_confirmed`]: Self::transactions_confirmed
84 void transaction_unconfirmed(byte[] txid);
86 * Processes an update to the best header connected at the given height.
88 * Should be called when a new header is available but may be skipped for intermediary blocks
89 * if they become available at the same time.
91 void best_block_updated(byte[] header, int height);
93 * Returns transactions that should be monitored for reorganization out of the chain.
95 * Should include any transactions passed to [`transactions_confirmed`] that have insufficient
96 * confirmations to be safe from a chain reorganization. Should not include any transactions
97 * passed to [`transaction_unconfirmed`] unless later reconfirmed.
99 * May be called to determine the subset of transactions that must still be monitored for
100 * reorganization. Will be idempotent between calls but may change as a result of calls to the
101 * other interface methods. Thus, this is useful to determine which transactions may need to be
102 * given to [`transaction_unconfirmed`].
104 * [`transactions_confirmed`]: Self::transactions_confirmed
105 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
107 byte[][] get_relevant_txids();
109 private static class LDKConfirmHolder { Confirm held; }
110 public static Confirm new_impl(ConfirmInterface arg) {
111 final LDKConfirmHolder impl_holder = new LDKConfirmHolder();
112 impl_holder.held = new Confirm(new bindings.LDKConfirm() {
113 @Override public void transactions_confirmed(byte[] header, long[] txdata, int height) {
114 TwoTuple_usizeTransactionZ[] txdata_conv_28_arr = new TwoTuple_usizeTransactionZ[txdata.length];
115 for (int c = 0; c < txdata.length; c++) {
116 long txdata_conv_28 = txdata[c];
117 TwoTuple_usizeTransactionZ txdata_conv_28_hu_conv = new TwoTuple_usizeTransactionZ(null, txdata_conv_28);
118 txdata_conv_28_hu_conv.ptrs_to.add(this);
119 txdata_conv_28_arr[c] = txdata_conv_28_hu_conv;
121 arg.transactions_confirmed(header, txdata_conv_28_arr, height);
123 @Override public void transaction_unconfirmed(byte[] txid) {
124 arg.transaction_unconfirmed(txid);
126 @Override public void best_block_updated(byte[] header, int height) {
127 arg.best_block_updated(header, height);
129 @Override public byte[][] get_relevant_txids() {
130 byte[][] ret = arg.get_relevant_txids();
134 return impl_holder.held;
137 * Processes transactions confirmed in a block with a given header and height.
139 * Should be called for any transactions registered by [`Filter::register_tx`] or any
140 * transactions spending an output registered by [`Filter::register_output`]. Such transactions
141 * appearing in the same block do not need to be included in the same call; instead, multiple
142 * calls with additional transactions may be made so long as they are made in [chain order].
144 * May be called before or after [`best_block_updated`] for the corresponding block. However,
145 * in the event of a chain reorganization, it must not be called with a `header` that is no
146 * longer in the chain as of the last call to [`best_block_updated`].
148 * [chain order]: Confirm#Order
149 * [`best_block_updated`]: Self::best_block_updated
151 public void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height) {
152 bindings.Confirm_transactions_confirmed(this.ptr, header, txdata != null ? Arrays.stream(txdata).mapToLong(txdata_conv_28 -> txdata_conv_28 != null ? txdata_conv_28.ptr : 0).toArray() : null, height);
156 * Processes a transaction that is no longer confirmed as result of a chain reorganization.
158 * Should be called for any transaction returned by [`get_relevant_txids`] if it has been
159 * reorganized out of the best chain. Once called, the given transaction should not be returned
160 * by [`get_relevant_txids`] unless it has been reconfirmed via [`transactions_confirmed`].
162 * [`get_relevant_txids`]: Self::get_relevant_txids
163 * [`transactions_confirmed`]: Self::transactions_confirmed
165 public void transaction_unconfirmed(byte[] txid) {
166 bindings.Confirm_transaction_unconfirmed(this.ptr, txid);
170 * Processes an update to the best header connected at the given height.
172 * Should be called when a new header is available but may be skipped for intermediary blocks
173 * if they become available at the same time.
175 public void best_block_updated(byte[] header, int height) {
176 bindings.Confirm_best_block_updated(this.ptr, header, height);
180 * Returns transactions that should be monitored for reorganization out of the chain.
182 * Should include any transactions passed to [`transactions_confirmed`] that have insufficient
183 * confirmations to be safe from a chain reorganization. Should not include any transactions
184 * passed to [`transaction_unconfirmed`] unless later reconfirmed.
186 * May be called to determine the subset of transactions that must still be monitored for
187 * reorganization. Will be idempotent between calls but may change as a result of calls to the
188 * other interface methods. Thus, this is useful to determine which transactions may need to be
189 * given to [`transaction_unconfirmed`].
191 * [`transactions_confirmed`]: Self::transactions_confirmed
192 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
194 public byte[][] get_relevant_txids() {
195 byte[][] ret = bindings.Confirm_get_relevant_txids(this.ptr);