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<Long, byte[]>[] 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<Long, byte[]>[] txdata_conv_24_arr = new TwoTuple[txdata.length];
115 for (int y = 0; y < txdata.length; y++) {
116 long txdata_conv_24 = txdata[y];
117 long txdata_conv_24_a = bindings.LDKC2Tuple_usizeTransactionZ_get_a(txdata_conv_24);
118 byte[] txdata_conv_24_b = bindings.LDKC2Tuple_usizeTransactionZ_get_b(txdata_conv_24);
119 TwoTuple<Long, byte[]> txdata_conv_24_conv = new TwoTuple<Long, byte[]>(txdata_conv_24_a, txdata_conv_24_b, () -> {
120 bindings.C2Tuple_usizeTransactionZ_free(txdata_conv_24);
122 txdata_conv_24_arr[y] = txdata_conv_24_conv;
124 arg.transactions_confirmed(header, txdata_conv_24_arr, height);
126 @Override public void transaction_unconfirmed(byte[] txid) {
127 arg.transaction_unconfirmed(txid);
129 @Override public void best_block_updated(byte[] header, int height) {
130 arg.best_block_updated(header, height);
132 @Override public byte[][] get_relevant_txids() {
133 byte[][] ret = arg.get_relevant_txids();
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<Long, byte[]>[] txdata, int height) {
155 bindings.Confirm_transactions_confirmed(this.ptr, header, txdata != null ? Arrays.stream(txdata).mapToLong(txdata_conv_24 -> bindings.C2Tuple_usizeTransactionZ_new(txdata_conv_24.a, txdata_conv_24.b)).toArray() : null, height);
156 /* TODO 2 TwoTuple<Long, byte[]> */;
160 * Processes a transaction that is no longer confirmed as result of a chain reorganization.
162 * Should be called for any transaction returned by [`get_relevant_txids`] if it has been
163 * reorganized out of the best chain. Once called, the given transaction should not be returned
164 * by [`get_relevant_txids`] unless it has been reconfirmed via [`transactions_confirmed`].
166 * [`get_relevant_txids`]: Self::get_relevant_txids
167 * [`transactions_confirmed`]: Self::transactions_confirmed
169 public void transaction_unconfirmed(byte[] txid) {
170 bindings.Confirm_transaction_unconfirmed(this.ptr, txid);
174 * Processes an update to the best header connected at the given height.
176 * Should be called when a new header is available but may be skipped for intermediary blocks
177 * if they become available at the same time.
179 public void best_block_updated(byte[] header, int height) {
180 bindings.Confirm_best_block_updated(this.ptr, header, height);
184 * Returns transactions that should be monitored for reorganization out of the chain.
186 * Should include any transactions passed to [`transactions_confirmed`] that have insufficient
187 * confirmations to be safe from a chain reorganization. Should not include any transactions
188 * passed to [`transaction_unconfirmed`] unless later reconfirmed.
190 * May be called to determine the subset of transactions that must still be monitored for
191 * reorganization. Will be idempotent between calls but may change as a result of calls to the
192 * other interface methods. Thus, this is useful to determine which transactions may need to be
193 * given to [`transaction_unconfirmed`].
195 * [`transactions_confirmed`]: Self::transactions_confirmed
196 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
198 public byte[][] get_relevant_txids() {
199 byte[][] ret = bindings.Confirm_get_relevant_txids(this.ptr);