6 namespace org { namespace ldk { namespace structs {
9 * The `Confirm` trait is used to notify LDK when relevant transactions have been confirmed on
10 * chain or 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-based transaction sync implementation may implement
14 * [`Filter`] to subscribe to relevant transactions and unspent outputs it should monitor for
15 * on-chain activity. Then, it needs to notify LDK via this interface upon observing any changes
16 * with reference to the confirmation status of the monitored objects.
19 * The intended use is as follows:
20 * - Call [`transactions_confirmed`] to notify LDK whenever any of the registered transactions or
21 * outputs are, respectively, confirmed or spent on chain.
22 * - Call [`transaction_unconfirmed`] to notify LDK whenever any transaction returned by
23 * [`get_relevant_txids`] is no longer confirmed in the block with the given block hash.
24 * - Call [`best_block_updated`] to notify LDK whenever a new chain tip becomes available.
28 * Clients must call these methods in chain order. Specifically:
29 * - Transactions which are confirmed in a particular block must be given before transactions
30 * confirmed in a later block.
31 * - Dependent transactions within the same block must be given in topological order, possibly in
33 * - All unconfirmed transactions must be given after the original confirmations and before *any*
34 * reconfirmations, i.e., [`transactions_confirmed`] and [`transaction_unconfirmed`] calls should
35 * never be interleaved, but always conduced *en bloc*.
36 * - Any reconfirmed transactions need to be explicitly unconfirmed before they are reconfirmed
37 * in regard to the new block.
39 * See individual method documentation for further details.
41 * [`transactions_confirmed`]: Self::transactions_confirmed
42 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
43 * [`best_block_updated`]: Self::best_block_updated
44 * [`get_relevant_txids`]: Self::get_relevant_txids
46 public class Confirm : CommonBase {
47 internal readonly bindings.LDKConfirm bindings_instance;
48 internal Confirm(object _dummy, long ptr) : base(ptr) { bindings_instance = null; }
49 private Confirm(bindings.LDKConfirm arg) : base(bindings.LDKConfirm_new(arg)) {
50 this.ptrs_to.AddLast(arg);
51 this.bindings_instance = arg;
54 if (ptr != 0) { bindings.Confirm_free(ptr); }
57 public interface ConfirmInterface {
59 * Notifies LDK of transactions confirmed in a block with a given header and height.
61 * Must 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_usizeTransactionZ[] _txdata, int _height);
75 * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
77 * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
78 * reorganized out of the best chain or if it is no longer confirmed in the block with the
79 * given block hash. Once called, the given transaction will 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 * Notifies LDK of an update to the best header connected at the given height.
89 * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
92 void best_block_updated(byte[] _header, int _height);
94 * Returns transactions that must be monitored for reorganization out of the chain along
95 * with the hash of the block as part of which it had been previously confirmed.
97 * Note that the returned `Option<BlockHash>` might be `None` for channels created with LDK
98 * 0.0.112 and prior, in which case you need to manually track previous confirmations.
100 * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
101 * confirmations to be safe from a chain reorganization. Will not include any transactions
102 * passed to [`transaction_unconfirmed`], unless later reconfirmed.
104 * Must be called to determine the subset of transactions that must be monitored for
105 * reorganization. Will be idempotent between calls but may change as a result of calls to the
106 * other interface methods. Thus, this is useful to determine which transactions must be
107 * given to [`transaction_unconfirmed`].
109 * If any of the returned transactions are confirmed in a block other than the one with the
110 * given hash, they need to be unconfirmed and reconfirmed via [`transaction_unconfirmed`] and
111 * [`transactions_confirmed`], respectively.
113 * [`transactions_confirmed`]: Self::transactions_confirmed
114 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
116 TwoTuple_TxidCOption_BlockHashZZ[] get_relevant_txids();
118 private class LDKConfirmHolder { internal Confirm held; }
119 private class LDKConfirmImpl : bindings.LDKConfirm {
120 internal LDKConfirmImpl(ConfirmInterface arg, LDKConfirmHolder impl_holder) { this.arg = arg; this.impl_holder = impl_holder; }
121 private ConfirmInterface arg;
122 private LDKConfirmHolder impl_holder;
123 public void transactions_confirmed(byte[] _header, long[] _txdata, int _height) {
124 int _txdata_conv_28_len = _txdata.Length;
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 = _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 arg.transactions_confirmed(_header, _txdata_conv_28_arr, _height);
135 public void transaction_unconfirmed(byte[] _txid) {
136 arg.transaction_unconfirmed(_txid);
139 public void best_block_updated(byte[] _header, int _height) {
140 arg.best_block_updated(_header, _height);
143 public long[] get_relevant_txids() {
144 TwoTuple_TxidCOption_BlockHashZZ[] ret = arg.get_relevant_txids();
146 long[] result = ret != null ? InternalUtils.mapArray(ret, ret_conv_34 => ret_conv_34 == null ? 0 : ret_conv_34.clone_ptr()) : null;
150 public static Confirm new_impl(ConfirmInterface arg) {
151 LDKConfirmHolder impl_holder = new LDKConfirmHolder();
152 impl_holder.held = new Confirm(new LDKConfirmImpl(arg, impl_holder));
153 return impl_holder.held;
156 * Notifies LDK of transactions confirmed in a block with a given header and height.
158 * Must be called for any transactions registered by [`Filter::register_tx`] or any
159 * transactions spending an output registered by [`Filter::register_output`]. Such transactions
160 * appearing in the same block do not need to be included in the same call; instead, multiple
161 * calls with additional transactions may be made so long as they are made in [chain order].
163 * May be called before or after [`best_block_updated`] for the corresponding block. However,
164 * in the event of a chain reorganization, it must not be called with a `header` that is no
165 * longer in the chain as of the last call to [`best_block_updated`].
167 * [chain order]: Confirm#order
168 * [`best_block_updated`]: Self::best_block_updated
170 public void transactions_confirmed(byte[] header, TwoTuple_usizeTransactionZ[] txdata, int height) {
171 bindings.Confirm_transactions_confirmed(this.ptr, InternalUtils.check_arr_len(header, 80), txdata != null ? InternalUtils.mapArray(txdata, txdata_conv_28 => txdata_conv_28 != null ? txdata_conv_28.ptr : 0) : null, height);
173 GC.KeepAlive(header);
174 GC.KeepAlive(txdata);
175 GC.KeepAlive(height);
179 * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
181 * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
182 * reorganized out of the best chain or if it is no longer confirmed in the block with the
183 * given block hash. Once called, the given transaction will not be returned
184 * by [`get_relevant_txids`], unless it has been reconfirmed via [`transactions_confirmed`].
186 * [`get_relevant_txids`]: Self::get_relevant_txids
187 * [`transactions_confirmed`]: Self::transactions_confirmed
189 public void transaction_unconfirmed(byte[] txid) {
190 bindings.Confirm_transaction_unconfirmed(this.ptr, InternalUtils.check_arr_len(txid, 32));
196 * Notifies LDK of an update to the best header connected at the given height.
198 * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
201 public void best_block_updated(byte[] header, int height) {
202 bindings.Confirm_best_block_updated(this.ptr, InternalUtils.check_arr_len(header, 80), height);
204 GC.KeepAlive(header);
205 GC.KeepAlive(height);
209 * Returns transactions that must be monitored for reorganization out of the chain along
210 * with the hash of the block as part of which it had been previously confirmed.
212 * Note that the returned `Option<BlockHash>` might be `None` for channels created with LDK
213 * 0.0.112 and prior, in which case you need to manually track previous confirmations.
215 * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
216 * confirmations to be safe from a chain reorganization. Will not include any transactions
217 * passed to [`transaction_unconfirmed`], unless later reconfirmed.
219 * Must be called to determine the subset of transactions that must be monitored for
220 * reorganization. Will be idempotent between calls but may change as a result of calls to the
221 * other interface methods. Thus, this is useful to determine which transactions must be
222 * given to [`transaction_unconfirmed`].
224 * If any of the returned transactions are confirmed in a block other than the one with the
225 * given hash, they need to be unconfirmed and reconfirmed via [`transaction_unconfirmed`] and
226 * [`transactions_confirmed`], respectively.
228 * [`transactions_confirmed`]: Self::transactions_confirmed
229 * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
231 public TwoTuple_TxidCOption_BlockHashZZ[] get_relevant_txids() {
232 long[] ret = bindings.Confirm_get_relevant_txids(this.ptr);
234 int ret_conv_34_len = ret.Length;
235 TwoTuple_TxidCOption_BlockHashZZ[] ret_conv_34_arr = new TwoTuple_TxidCOption_BlockHashZZ[ret_conv_34_len];
236 for (int i = 0; i < ret_conv_34_len; i++) {
237 long ret_conv_34 = ret[i];
238 TwoTuple_TxidCOption_BlockHashZZ ret_conv_34_hu_conv = new TwoTuple_TxidCOption_BlockHashZZ(null, ret_conv_34);
239 if (ret_conv_34_hu_conv != null) { ret_conv_34_hu_conv.ptrs_to.AddLast(this); };
240 ret_conv_34_arr[i] = ret_conv_34_hu_conv;
242 return ret_conv_34_arr;