7 namespace org { namespace ldk { namespace structs {
11 /** An implementation of Confirm */
12 public interface ConfirmInterface {
13 /**Notifies LDK of transactions confirmed in a block with a given header and height.
15 * Must be called for any transactions registered by [`Filter::register_tx`] or any
16 * transactions spending an output registered by [`Filter::register_output`]. Such transactions
17 * appearing in the same block do not need to be included in the same call; instead, multiple
18 * calls with additional transactions may be made so long as they are made in [chain order].
20 * May be called before or after [`best_block_updated`] for the corresponding block. However,
21 * in the event of a chain reorganization, it must not be called with a `header` that is no
22 * longer in the chain as of the last call to [`best_block_updated`].
24 * [chain order]: Confirm#order
25 * [`best_block_updated`]: Self::best_block_updated
27 void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height);
28 /**Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
30 * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
31 * reorganized out of the best chain or if it is no longer confirmed in the block with the
32 * given block hash. Once called, the given transaction will not be returned
33 * by [`get_relevant_txids`], unless it has been reconfirmed via [`transactions_confirmed`].
35 * [`get_relevant_txids`]: Self::get_relevant_txids
36 * [`transactions_confirmed`]: Self::transactions_confirmed
38 void transaction_unconfirmed(byte[] txid);
39 /**Notifies LDK of an update to the best header connected at the given height.
41 * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
44 void best_block_updated(byte[] header, int height);
45 /**Returns transactions that must be monitored for reorganization out of the chain along
46 * with the height and the hash of the block as part of which it had been previously confirmed.
48 * Note that the returned `Option<BlockHash>` might be `None` for channels created with LDK
49 * 0.0.112 and prior, in which case you need to manually track previous confirmations.
51 * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
52 * confirmations to be safe from a chain reorganization. Will not include any transactions
53 * passed to [`transaction_unconfirmed`], unless later reconfirmed.
55 * Must be called to determine the subset of transactions that must be monitored for
56 * reorganization. Will be idempotent between calls but may change as a result of calls to the
57 * other interface methods. Thus, this is useful to determine which transactions must be
58 * given to [`transaction_unconfirmed`].
60 * If any of the returned transactions are confirmed in a block other than the one with the
61 * given hash at the given height, they need to be unconfirmed and reconfirmed via
62 * [`transaction_unconfirmed`] and [`transactions_confirmed`], respectively.
64 * [`transactions_confirmed`]: Self::transactions_confirmed
65 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
67 ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ[] get_relevant_txids();
71 * The `Confirm` trait is used to notify LDK when relevant transactions have been confirmed on
72 * chain or unconfirmed during a chain reorganization.
74 * Clients sourcing chain data using a transaction-oriented API should prefer this interface over
75 * [`Listen`]. For instance, an Electrum-based transaction sync implementation may implement
76 * [`Filter`] to subscribe to relevant transactions and unspent outputs it should monitor for
77 * on-chain activity. Then, it needs to notify LDK via this interface upon observing any changes
78 * with reference to the confirmation status of the monitored objects.
81 * The intended use is as follows:
82 * - Call [`transactions_confirmed`] to notify LDK whenever any of the registered transactions or
83 * outputs are, respectively, confirmed or spent on chain.
84 * - Call [`transaction_unconfirmed`] to notify LDK whenever any transaction returned by
85 * [`get_relevant_txids`] is no longer confirmed in the block with the given block hash.
86 * - Call [`best_block_updated`] to notify LDK whenever a new chain tip becomes available.
90 * Clients must call these methods in chain order. Specifically:
91 * - Transactions which are confirmed in a particular block must be given before transactions
92 * confirmed in a later block.
93 * - Dependent transactions within the same block must be given in topological order, possibly in
95 * - All unconfirmed transactions must be given after the original confirmations and before *any*
96 * reconfirmations, i.e., [`transactions_confirmed`] and [`transaction_unconfirmed`] calls should
97 * never be interleaved, but always conduced *en bloc*.
98 * - Any reconfirmed transactions need to be explicitly unconfirmed before they are reconfirmed
99 * in regard to the new block.
101 * See individual method documentation for further details.
103 * [`transactions_confirmed`]: Self::transactions_confirmed
104 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
105 * [`best_block_updated`]: Self::best_block_updated
106 * [`get_relevant_txids`]: Self::get_relevant_txids
108 public class Confirm : CommonBase {
109 internal bindings.LDKConfirm bindings_instance;
110 internal long instance_idx;
112 internal Confirm(object _dummy, long ptr) : base(ptr) { bindings_instance = null; }
114 if (ptr != 0) { bindings.Confirm_free(ptr); }
117 private class LDKConfirmHolder { internal Confirm held; }
118 private class LDKConfirmImpl : bindings.LDKConfirm {
119 internal LDKConfirmImpl(ConfirmInterface arg, LDKConfirmHolder impl_holder) { this.arg = arg; this.impl_holder = impl_holder; }
120 private ConfirmInterface arg;
121 private LDKConfirmHolder impl_holder;
122 public void transactions_confirmed(long _header, long _txdata, int _height) {
123 byte[] _header_conv = InternalUtils.decodeUint8Array(_header);
124 int _txdata_conv_28_len = InternalUtils.getArrayLength(_txdata);
125 TwoTuple_usizeTransactionZ[] _txdata_conv_28_arr = new TwoTuple_usizeTransactionZ[_txdata_conv_28_len];
126 for (int c = 0; c < _txdata_conv_28_len; c++) {
127 long _txdata_conv_28 = InternalUtils.getU64ArrayElem(_txdata, c);
128 TwoTuple_usizeTransactionZ _txdata_conv_28_hu_conv = new TwoTuple_usizeTransactionZ(null, _txdata_conv_28);
129 if (_txdata_conv_28_hu_conv != null) { _txdata_conv_28_hu_conv.ptrs_to.AddLast(this); };
130 _txdata_conv_28_arr[c] = _txdata_conv_28_hu_conv;
132 bindings.free_buffer(_txdata);
133 arg.transactions_confirmed(_header_conv, _txdata_conv_28_arr, _height);
136 public void transaction_unconfirmed(long _txid) {
137 byte[] _txid_conv = InternalUtils.decodeUint8Array(_txid);
138 arg.transaction_unconfirmed(_txid_conv);
141 public void best_block_updated(long _header, int _height) {
142 byte[] _header_conv = InternalUtils.decodeUint8Array(_header);
143 arg.best_block_updated(_header_conv, _height);
146 public long get_relevant_txids() {
147 ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ[] ret = arg.get_relevant_txids();
149 long result = InternalUtils.encodeUint64Array(InternalUtils.mapArray(ret, ret_conv_54 => ret_conv_54.clone_ptr()));
154 /** Creates a new instance of Confirm from a given implementation */
155 public static Confirm new_impl(ConfirmInterface arg) {
156 LDKConfirmHolder impl_holder = new LDKConfirmHolder();
157 LDKConfirmImpl impl = new LDKConfirmImpl(arg, impl_holder);
158 long[] ptr_idx = bindings.LDKConfirm_new(impl);
160 impl_holder.held = new Confirm(null, ptr_idx[0]);
161 impl_holder.held.instance_idx = ptr_idx[1];
162 impl_holder.held.bindings_instance = impl;
163 return impl_holder.held;
167 * Notifies LDK of transactions confirmed in a block with a given header and height.
169 * Must be called for any transactions registered by [`Filter::register_tx`] or any
170 * transactions spending an output registered by [`Filter::register_output`]. Such transactions
171 * appearing in the same block do not need to be included in the same call; instead, multiple
172 * calls with additional transactions may be made so long as they are made in [chain order].
174 * May be called before or after [`best_block_updated`] for the corresponding block. However,
175 * in the event of a chain reorganization, it must not be called with a `header` that is no
176 * longer in the chain as of the last call to [`best_block_updated`].
178 * [chain order]: Confirm#order
179 * [`best_block_updated`]: Self::best_block_updated
181 public void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height) {
182 bindings.Confirm_transactions_confirmed(this.ptr, InternalUtils.encodeUint8Array(InternalUtils.check_arr_len(header, 80)), InternalUtils.encodeUint64Array(InternalUtils.mapArray(txdata, txdata_conv_28 => txdata_conv_28.ptr)), height);
184 GC.KeepAlive(header);
185 GC.KeepAlive(txdata);
186 GC.KeepAlive(height);
190 * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
192 * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
193 * reorganized out of the best chain or if it is no longer confirmed in the block with the
194 * given block hash. Once called, the given transaction will not be returned
195 * by [`get_relevant_txids`], unless it has been reconfirmed via [`transactions_confirmed`].
197 * [`get_relevant_txids`]: Self::get_relevant_txids
198 * [`transactions_confirmed`]: Self::transactions_confirmed
200 public void transaction_unconfirmed(byte[] txid) {
201 bindings.Confirm_transaction_unconfirmed(this.ptr, InternalUtils.encodeUint8Array(InternalUtils.check_arr_len(txid, 32)));
207 * Notifies LDK of an update to the best header connected at the given height.
209 * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
212 public void best_block_updated(byte[] header, int height) {
213 bindings.Confirm_best_block_updated(this.ptr, InternalUtils.encodeUint8Array(InternalUtils.check_arr_len(header, 80)), height);
215 GC.KeepAlive(header);
216 GC.KeepAlive(height);
220 * Returns transactions that must be monitored for reorganization out of the chain along
221 * with the height and the hash of the block as part of which it had been previously confirmed.
223 * Note that the returned `Option<BlockHash>` might be `None` for channels created with LDK
224 * 0.0.112 and prior, in which case you need to manually track previous confirmations.
226 * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
227 * confirmations to be safe from a chain reorganization. Will not include any transactions
228 * passed to [`transaction_unconfirmed`], unless later reconfirmed.
230 * Must be called to determine the subset of transactions that must be monitored for
231 * reorganization. Will be idempotent between calls but may change as a result of calls to the
232 * other interface methods. Thus, this is useful to determine which transactions must be
233 * given to [`transaction_unconfirmed`].
235 * If any of the returned transactions are confirmed in a block other than the one with the
236 * given hash at the given height, they need to be unconfirmed and reconfirmed via
237 * [`transaction_unconfirmed`] and [`transactions_confirmed`], respectively.
239 * [`transactions_confirmed`]: Self::transactions_confirmed
240 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
242 public ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ[] get_relevant_txids() {
243 long ret = bindings.Confirm_get_relevant_txids(this.ptr);
245 if (ret >= 0 && ret <= 4096) { return null; }
246 int ret_conv_54_len = InternalUtils.getArrayLength(ret);
247 ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ[] ret_conv_54_arr = new ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ[ret_conv_54_len];
248 for (int c = 0; c < ret_conv_54_len; c++) {
249 long ret_conv_54 = InternalUtils.getU64ArrayElem(ret, c);
250 ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ ret_conv_54_hu_conv = new ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ(null, ret_conv_54);
251 if (ret_conv_54_hu_conv != null) { ret_conv_54_hu_conv.ptrs_to.AddLast(this); };
252 ret_conv_54_arr[c] = ret_conv_54_hu_conv;
254 bindings.free_buffer(ret);
255 return ret_conv_54_arr;