1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
9 * The `Confirm` trait is used to notify when transactions have been confirmed on chain or
10 * unconfirmed during a chain reorganization.
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.
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.
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
30 * - Dependent transactions within the same block must be given in topological order, possibly in
32 * - Unconfirmed transactions must be given after the original confirmations and before any
35 * See individual method documentation for further details.
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
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;
51 @Override @SuppressWarnings("deprecation")
52 protected void finalize() throws Throwable {
53 if (ptr != 0) { bindings.Confirm_free(ptr); } super.finalize();
56 public static interface ConfirmInterface {
58 * Processes transactions confirmed in a block with a given header and height.
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].
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`].
69 * [chain order]: Confirm#Order
70 * [`best_block_updated`]: Self::best_block_updated
72 void transactions_confirmed(byte[] header, TwoTuple<Long, byte[]>[] txdata, int height);
74 * Processes a transaction that is no longer confirmed as result of a chain reorganization.
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`].
80 * [`get_relevant_txids`]: Self::get_relevant_txids
81 * [`transactions_confirmed`]: Self::transactions_confirmed
83 void transaction_unconfirmed(byte[] txid);
85 * Processes an update to the best header connected at the given height.
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.
90 void best_block_updated(byte[] header, int height);
92 * Returns transactions that should be monitored for reorganization out of the chain.
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.
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`].
103 * [`transactions_confirmed`]: Self::transactions_confirmed
104 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
106 byte[][] get_relevant_txids();
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);
121 txdata_conv_24_arr[y] = txdata_conv_24_conv;
123 arg.transactions_confirmed(header, txdata_conv_24_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();
136 return impl_holder.held;
139 * Processes transactions confirmed in a block with a given header and height.
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].
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`].
150 * [chain order]: Confirm#Order
151 * [`best_block_updated`]: Self::best_block_updated
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[]> */;
159 * Processes a transaction that is no longer confirmed as result of a chain reorganization.
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`].
165 * [`get_relevant_txids`]: Self::get_relevant_txids
166 * [`transactions_confirmed`]: Self::transactions_confirmed
168 public void transaction_unconfirmed(byte[] txid) {
169 bindings.Confirm_transaction_unconfirmed(this.ptr, txid);
173 * Processes an update to the best header connected at the given height.
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.
178 public void best_block_updated(byte[] header, int height) {
179 bindings.Confirm_best_block_updated(this.ptr, header, height);
183 * Returns transactions that should be monitored for reorganization out of the chain.
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.
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`].
194 * [`transactions_confirmed`]: Self::transactions_confirmed
195 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
197 public byte[][] get_relevant_txids() {
198 byte[][] ret = bindings.Confirm_get_relevant_txids(this.ptr);