1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
7 import java.lang.ref.Reference;
8 import javax.annotation.Nullable;
11 * The `Confirm` trait is used to notify when transactions have been confirmed on chain or
12 * unconfirmed during a chain reorganization.
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.
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.
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
32 * - Dependent transactions within the same block must be given in topological order, possibly in
34 * - Unconfirmed transactions must be given after the original confirmations and before any
37 * See individual method documentation for further details.
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
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;
53 @Override @SuppressWarnings("deprecation")
54 protected void finalize() throws Throwable {
55 if (ptr != 0) { bindings.Confirm_free(ptr); } super.finalize();
58 public static interface ConfirmInterface {
60 * Processes transactions confirmed in a block with a given header and height.
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].
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`].
71 * [chain order]: Confirm#Order
72 * [`best_block_updated`]: Self::best_block_updated
74 void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height);
76 * Processes a transaction that is no longer confirmed as result of a chain reorganization.
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`].
82 * [`get_relevant_txids`]: Self::get_relevant_txids
83 * [`transactions_confirmed`]: Self::transactions_confirmed
85 void transaction_unconfirmed(byte[] txid);
87 * Processes an update to the best header connected at the given height.
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.
92 void best_block_updated(byte[] header, int height);
94 * Returns transactions that should be monitored for reorganization out of the chain.
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.
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`].
105 * [`transactions_confirmed`]: Self::transactions_confirmed
106 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
108 byte[][] get_relevant_txids();
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;
123 arg.transactions_confirmed(header, txdata_conv_28_arr, height);
125 @Override public void transaction_unconfirmed(byte[] txid) {
126 arg.transaction_unconfirmed(txid);
128 @Override public void best_block_updated(byte[] header, int height) {
129 arg.best_block_updated(header, height);
131 @Override public byte[][] get_relevant_txids() {
132 byte[][] ret = arg.get_relevant_txids();
133 byte[][] result = ret != null ? Arrays.stream(ret).map(ret_conv_8 -> InternalUtils.check_arr_len(ret_conv_8, 32)).toArray(byte[][]::new) : null;
137 return impl_holder.held;
140 * Processes transactions confirmed in a block with a given header and height.
142 * Should be called for any transactions registered by [`Filter::register_tx`] or any
143 * transactions spending an output registered by [`Filter::register_output`]. Such transactions
144 * appearing in the same block do not need to be included in the same call; instead, multiple
145 * calls with additional transactions may be made so long as they are made in [chain order].
147 * May be called before or after [`best_block_updated`] for the corresponding block. However,
148 * in the event of a chain reorganization, it must not be called with a `header` that is no
149 * longer in the chain as of the last call to [`best_block_updated`].
151 * [chain order]: Confirm#Order
152 * [`best_block_updated`]: Self::best_block_updated
154 public void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height) {
155 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);
156 Reference.reachabilityFence(this);
157 Reference.reachabilityFence(header);
158 Reference.reachabilityFence(txdata);
159 Reference.reachabilityFence(height);
163 * Processes a transaction that is no longer confirmed as result of a chain reorganization.
165 * Should be called for any transaction returned by [`get_relevant_txids`] if it has been
166 * reorganized out of the best chain. Once called, the given transaction should not be returned
167 * by [`get_relevant_txids`] unless it has been reconfirmed via [`transactions_confirmed`].
169 * [`get_relevant_txids`]: Self::get_relevant_txids
170 * [`transactions_confirmed`]: Self::transactions_confirmed
172 public void transaction_unconfirmed(byte[] txid) {
173 bindings.Confirm_transaction_unconfirmed(this.ptr, InternalUtils.check_arr_len(txid, 32));
174 Reference.reachabilityFence(this);
175 Reference.reachabilityFence(txid);
179 * Processes an update to the best header connected at the given height.
181 * Should be called when a new header is available but may be skipped for intermediary blocks
182 * if they become available at the same time.
184 public void best_block_updated(byte[] header, int height) {
185 bindings.Confirm_best_block_updated(this.ptr, InternalUtils.check_arr_len(header, 80), height);
186 Reference.reachabilityFence(this);
187 Reference.reachabilityFence(header);
188 Reference.reachabilityFence(height);
192 * Returns transactions that should be monitored for reorganization out of the chain.
194 * Should include any transactions passed to [`transactions_confirmed`] that have insufficient
195 * confirmations to be safe from a chain reorganization. Should not include any transactions
196 * passed to [`transaction_unconfirmed`] unless later reconfirmed.
198 * May be called to determine the subset of transactions that must still be monitored for
199 * reorganization. Will be idempotent between calls but may change as a result of calls to the
200 * other interface methods. Thus, this is useful to determine which transactions may need to be
201 * given to [`transaction_unconfirmed`].
203 * [`transactions_confirmed`]: Self::transactions_confirmed
204 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
206 public byte[][] get_relevant_txids() {
207 byte[][] ret = bindings.Confirm_get_relevant_txids(this.ptr);
208 Reference.reachabilityFence(this);