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 LDK when relevant transactions have been confirmed on
12 * chain or 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-based transaction sync implementation may implement
16 * [`Filter`] to subscribe to relevant transactions and unspent outputs it should monitor for
17 * on-chain activity. Then, it needs to notify LDK via this interface upon observing any changes
18 * with reference to the confirmation status of the monitored objects.
21 * The intended use is as follows:
22 * - Call [`transactions_confirmed`] to notify LDK whenever any of the registered transactions or
23 * outputs are, respectively, confirmed or spent on chain.
24 * - Call [`transaction_unconfirmed`] to notify LDK whenever any transaction returned by
25 * [`get_relevant_txids`] is no longer confirmed in the block with the given block hash.
26 * - Call [`best_block_updated`] to notify LDK whenever a new chain tip becomes available.
30 * Clients must call these methods in chain order. Specifically:
31 * - Transactions which are confirmed in a particular block must be given before transactions
32 * confirmed in a later block.
33 * - Dependent transactions within the same block must be given in topological order, possibly in
35 * - All unconfirmed transactions must be given after the original confirmations and before *any*
36 * reconfirmations, i.e., [`transactions_confirmed`] and [`transaction_unconfirmed`] calls should
37 * never be interleaved, but always conduced *en bloc*.
38 * - Any reconfirmed transactions need to be explicitly unconfirmed before they are reconfirmed
39 * in regard to the new block.
41 * See individual method documentation for further details.
43 * [`transactions_confirmed`]: Self::transactions_confirmed
44 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
45 * [`best_block_updated`]: Self::best_block_updated
46 * [`get_relevant_txids`]: Self::get_relevant_txids
48 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
49 public class Confirm extends CommonBase {
50 final bindings.LDKConfirm bindings_instance;
51 Confirm(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
52 private Confirm(bindings.LDKConfirm arg) {
53 super(bindings.LDKConfirm_new(arg));
54 this.ptrs_to.add(arg);
55 this.bindings_instance = arg;
57 @Override @SuppressWarnings("deprecation")
58 protected void finalize() throws Throwable {
59 if (ptr != 0) { bindings.Confirm_free(ptr); } super.finalize();
62 public static interface ConfirmInterface {
64 * Notifies LDK of transactions confirmed in a block with a given header and height.
66 * Must be called for any transactions registered by [`Filter::register_tx`] or any
67 * transactions spending an output registered by [`Filter::register_output`]. Such transactions
68 * appearing in the same block do not need to be included in the same call; instead, multiple
69 * calls with additional transactions may be made so long as they are made in [chain order].
71 * May be called before or after [`best_block_updated`] for the corresponding block. However,
72 * in the event of a chain reorganization, it must not be called with a `header` that is no
73 * longer in the chain as of the last call to [`best_block_updated`].
75 * [chain order]: Confirm#order
76 * [`best_block_updated`]: Self::best_block_updated
78 void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height);
80 * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
82 * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
83 * reorganized out of the best chain or if it is no longer confirmed in the block with the
84 * given block hash. Once called, the given transaction will not be returned
85 * by [`get_relevant_txids`], unless it has been reconfirmed via [`transactions_confirmed`].
87 * [`get_relevant_txids`]: Self::get_relevant_txids
88 * [`transactions_confirmed`]: Self::transactions_confirmed
90 void transaction_unconfirmed(byte[] txid);
92 * Notifies LDK of an update to the best header connected at the given height.
94 * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
97 void best_block_updated(byte[] header, int height);
99 * Returns transactions that must be monitored for reorganization out of the chain along
100 * with the hash of the block as part of which it had been previously confirmed.
102 * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
103 * confirmations to be safe from a chain reorganization. Will not include any transactions
104 * passed to [`transaction_unconfirmed`], unless later reconfirmed.
106 * Must be called to determine the subset of transactions that must be monitored for
107 * reorganization. Will be idempotent between calls but may change as a result of calls to the
108 * other interface methods. Thus, this is useful to determine which transactions must be
109 * given to [`transaction_unconfirmed`].
111 * If any of the returned transactions are confirmed in a block other than the one with the
112 * given hash, they need to be unconfirmed and reconfirmed via [`transaction_unconfirmed`] and
113 * [`transactions_confirmed`], respectively.
115 * [`transactions_confirmed`]: Self::transactions_confirmed
116 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
118 TwoTuple_TxidBlockHashZ[] get_relevant_txids();
120 private static class LDKConfirmHolder { Confirm held; }
121 public static Confirm new_impl(ConfirmInterface arg) {
122 final LDKConfirmHolder impl_holder = new LDKConfirmHolder();
123 impl_holder.held = new Confirm(new bindings.LDKConfirm() {
124 @Override public void transactions_confirmed(byte[] header, long[] txdata, int height) {
125 int txdata_conv_28_len = txdata.length;
126 TwoTuple_usizeTransactionZ[] txdata_conv_28_arr = new TwoTuple_usizeTransactionZ[txdata_conv_28_len];
127 for (int c = 0; c < txdata_conv_28_len; c++) {
128 long txdata_conv_28 = txdata[c];
129 TwoTuple_usizeTransactionZ txdata_conv_28_hu_conv = new TwoTuple_usizeTransactionZ(null, txdata_conv_28);
130 if (txdata_conv_28_hu_conv != null) { txdata_conv_28_hu_conv.ptrs_to.add(this); };
131 txdata_conv_28_arr[c] = txdata_conv_28_hu_conv;
133 arg.transactions_confirmed(header, txdata_conv_28_arr, height);
134 Reference.reachabilityFence(arg);
136 @Override public void transaction_unconfirmed(byte[] txid) {
137 arg.transaction_unconfirmed(txid);
138 Reference.reachabilityFence(arg);
140 @Override public void best_block_updated(byte[] header, int height) {
141 arg.best_block_updated(header, height);
142 Reference.reachabilityFence(arg);
144 @Override public long[] get_relevant_txids() {
145 TwoTuple_TxidBlockHashZ[] ret = arg.get_relevant_txids();
146 Reference.reachabilityFence(arg);
147 long[] result = ret != null ? Arrays.stream(ret).mapToLong(ret_conv_25 -> ret_conv_25 == null ? 0 : ret_conv_25.clone_ptr()).toArray() : null;
151 return impl_holder.held;
154 * Notifies LDK of transactions confirmed in a block with a given header and height.
156 * Must be called for any transactions registered by [`Filter::register_tx`] or any
157 * transactions spending an output registered by [`Filter::register_output`]. Such transactions
158 * appearing in the same block do not need to be included in the same call; instead, multiple
159 * calls with additional transactions may be made so long as they are made in [chain order].
161 * May be called before or after [`best_block_updated`] for the corresponding block. However,
162 * in the event of a chain reorganization, it must not be called with a `header` that is no
163 * longer in the chain as of the last call to [`best_block_updated`].
165 * [chain order]: Confirm#order
166 * [`best_block_updated`]: Self::best_block_updated
168 public void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height) {
169 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);
170 Reference.reachabilityFence(this);
171 Reference.reachabilityFence(header);
172 Reference.reachabilityFence(txdata);
173 Reference.reachabilityFence(height);
177 * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
179 * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
180 * reorganized out of the best chain or if it is no longer confirmed in the block with the
181 * given block hash. Once called, the given transaction will not be returned
182 * by [`get_relevant_txids`], unless it has been reconfirmed via [`transactions_confirmed`].
184 * [`get_relevant_txids`]: Self::get_relevant_txids
185 * [`transactions_confirmed`]: Self::transactions_confirmed
187 public void transaction_unconfirmed(byte[] txid) {
188 bindings.Confirm_transaction_unconfirmed(this.ptr, InternalUtils.check_arr_len(txid, 32));
189 Reference.reachabilityFence(this);
190 Reference.reachabilityFence(txid);
194 * Notifies LDK of an update to the best header connected at the given height.
196 * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
199 public void best_block_updated(byte[] header, int height) {
200 bindings.Confirm_best_block_updated(this.ptr, InternalUtils.check_arr_len(header, 80), height);
201 Reference.reachabilityFence(this);
202 Reference.reachabilityFence(header);
203 Reference.reachabilityFence(height);
207 * Returns transactions that must be monitored for reorganization out of the chain along
208 * with the hash of the block as part of which it had been previously confirmed.
210 * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
211 * confirmations to be safe from a chain reorganization. Will not include any transactions
212 * passed to [`transaction_unconfirmed`], unless later reconfirmed.
214 * Must be called to determine the subset of transactions that must be monitored for
215 * reorganization. Will be idempotent between calls but may change as a result of calls to the
216 * other interface methods. Thus, this is useful to determine which transactions must be
217 * given to [`transaction_unconfirmed`].
219 * If any of the returned transactions are confirmed in a block other than the one with the
220 * given hash, they need to be unconfirmed and reconfirmed via [`transaction_unconfirmed`] and
221 * [`transactions_confirmed`], respectively.
223 * [`transactions_confirmed`]: Self::transactions_confirmed
224 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
226 public TwoTuple_TxidBlockHashZ[] get_relevant_txids() {
227 long[] ret = bindings.Confirm_get_relevant_txids(this.ptr);
228 Reference.reachabilityFence(this);
229 int ret_conv_25_len = ret.length;
230 TwoTuple_TxidBlockHashZ[] ret_conv_25_arr = new TwoTuple_TxidBlockHashZ[ret_conv_25_len];
231 for (int z = 0; z < ret_conv_25_len; z++) {
232 long ret_conv_25 = ret[z];
233 TwoTuple_TxidBlockHashZ ret_conv_25_hu_conv = new TwoTuple_TxidBlockHashZ(null, ret_conv_25);
234 if (ret_conv_25_hu_conv != null) { ret_conv_25_hu_conv.ptrs_to.add(this); };
235 ret_conv_25_arr[z] = ret_conv_25_hu_conv;
237 return ret_conv_25_arr;