X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=ldk-java;a=blobdiff_plain;f=ts%2Fstructs%2FConfirm.mts;h=5d08223bae69f0cb34ee197bac01606b3272b016;hp=2878b12d8aa72273bb7eb292ef5929ba2f62019f;hb=c629a01650402c8e2f9b9db8ced9ed63ce687727;hpb=d1d0121c000b713c10fd0bedd249eb8dda2e4db7;ds=sidebyside diff --git a/ts/structs/Confirm.mts b/ts/structs/Confirm.mts index 2878b12d..5d08223b 100644 --- a/ts/structs/Confirm.mts +++ b/ts/structs/Confirm.mts @@ -283,10 +283,53 @@ import * as bindings from '../bindings.mjs' +/** An implementation of Confirm */ export interface ConfirmInterface { + /**Processes transactions confirmed in a block with a given header and height. + * + * Should be called for any transactions registered by [`Filter::register_tx`] or any + * transactions spending an output registered by [`Filter::register_output`]. Such transactions + * appearing in the same block do not need to be included in the same call; instead, multiple + * calls with additional transactions may be made so long as they are made in [chain order]. + * + * May be called before or after [`best_block_updated`] for the corresponding block. However, + * in the event of a chain reorganization, it must not be called with a `header` that is no + * longer in the chain as of the last call to [`best_block_updated`]. + * + * [chain order]: Confirm#Order + * [`best_block_updated`]: Self::best_block_updated + */ transactions_confirmed(header: Uint8Array, txdata: TwoTuple_usizeTransactionZ[], height: number): void; + /**Processes a transaction that is no longer confirmed as result of a chain reorganization. + * + * Should be called for any transaction returned by [`get_relevant_txids`] if it has been + * reorganized out of the best chain. Once called, the given transaction should not be returned + * by [`get_relevant_txids`] unless it has been reconfirmed via [`transactions_confirmed`]. + * + * [`get_relevant_txids`]: Self::get_relevant_txids + * [`transactions_confirmed`]: Self::transactions_confirmed + */ transaction_unconfirmed(txid: Uint8Array): void; + /**Processes an update to the best header connected at the given height. + * + * Should be called when a new header is available but may be skipped for intermediary blocks + * if they become available at the same time. + */ best_block_updated(header: Uint8Array, height: number): void; + /**Returns transactions that should be monitored for reorganization out of the chain. + * + * Should include any transactions passed to [`transactions_confirmed`] that have insufficient + * confirmations to be safe from a chain reorganization. Should not include any transactions + * passed to [`transaction_unconfirmed`] unless later reconfirmed. + * + * May be called to determine the subset of transactions that must still be monitored for + * reorganization. Will be idempotent between calls but may change as a result of calls to the + * other interface methods. Thus, this is useful to determine which transactions may need to be + * given to [`transaction_unconfirmed`]. + * + * [`transactions_confirmed`]: Self::transactions_confirmed + * [`transaction_unconfirmed`]: Self::transaction_unconfirmed + */ get_relevant_txids(): Uint8Array[]; } @@ -294,6 +337,40 @@ class LDKConfirmHolder { held: Confirm; } +/** + * The `Confirm` trait is used to notify when transactions have been confirmed on chain or + * unconfirmed during a chain reorganization. + * + * Clients sourcing chain data using a transaction-oriented API should prefer this interface over + * [`Listen`]. For instance, an Electrum client may implement [`Filter`] by subscribing to activity + * related to registered transactions and outputs. Upon notification, it would pass along the + * matching transactions using this interface. + * + * # Use + * + * The intended use is as follows: + * - Call [`transactions_confirmed`] to process any on-chain activity of interest. + * - Call [`transaction_unconfirmed`] to process any transaction returned by [`get_relevant_txids`] + * that has been reorganized out of the chain. + * - Call [`best_block_updated`] whenever a new chain tip becomes available. + * + * # Order + * + * Clients must call these methods in chain order. Specifically: + * - Transactions confirmed in a block must be given before transactions confirmed in a later + * block. + * - Dependent transactions within the same block must be given in topological order, possibly in + * separate calls. + * - Unconfirmed transactions must be given after the original confirmations and before any + * reconfirmation. + * + * See individual method documentation for further details. + * + * [`transactions_confirmed`]: Self::transactions_confirmed + * [`transaction_unconfirmed`]: Self::transaction_unconfirmed + * [`best_block_updated`]: Self::best_block_updated + * [`get_relevant_txids`]: Self::get_relevant_txids + */ export class Confirm extends CommonBase { /* @internal */ public bindings_instance?: bindings.LDKConfirm; @@ -304,7 +381,8 @@ export class Confirm extends CommonBase { this.bindings_instance = null; } - static new_impl(arg: ConfirmInterface): Confirm { + /** Creates a new instance of Confirm from a given implementation */ + public static new_impl(arg: ConfirmInterface): Confirm { const impl_holder: LDKConfirmHolder = new LDKConfirmHolder(); let structImplementation = { transactions_confirmed (header: number, txdata: number, height: number): void { @@ -317,6 +395,7 @@ export class Confirm extends CommonBase { CommonBase.add_ref_from(txdata_conv_28_hu_conv, this); txdata_conv_28_arr[c] = txdata_conv_28_hu_conv; } + bindings.freeWasmMemory(txdata) arg.transactions_confirmed(header_conv, txdata_conv_28_arr, height); }, transaction_unconfirmed (txid: number): void { @@ -339,18 +418,65 @@ export class Confirm extends CommonBase { impl_holder.held.bindings_instance = structImplementation; return impl_holder.held; } + + /** + * Processes transactions confirmed in a block with a given header and height. + * + * Should be called for any transactions registered by [`Filter::register_tx`] or any + * transactions spending an output registered by [`Filter::register_output`]. Such transactions + * appearing in the same block do not need to be included in the same call; instead, multiple + * calls with additional transactions may be made so long as they are made in [chain order]. + * + * May be called before or after [`best_block_updated`] for the corresponding block. However, + * in the event of a chain reorganization, it must not be called with a `header` that is no + * longer in the chain as of the last call to [`best_block_updated`]. + * + * [chain order]: Confirm#Order + * [`best_block_updated`]: Self::best_block_updated + */ public transactions_confirmed(header: Uint8Array, txdata: TwoTuple_usizeTransactionZ[], height: number): void { bindings.Confirm_transactions_confirmed(this.ptr, bindings.encodeUint8Array(bindings.check_arr_len(header, 80)), bindings.encodeUint32Array(txdata != null ? txdata.map(txdata_conv_28 => txdata_conv_28 != null ? CommonBase.get_ptr_of(txdata_conv_28) : 0) : null), height); } + /** + * Processes a transaction that is no longer confirmed as result of a chain reorganization. + * + * Should be called for any transaction returned by [`get_relevant_txids`] if it has been + * reorganized out of the best chain. Once called, the given transaction should not be returned + * by [`get_relevant_txids`] unless it has been reconfirmed via [`transactions_confirmed`]. + * + * [`get_relevant_txids`]: Self::get_relevant_txids + * [`transactions_confirmed`]: Self::transactions_confirmed + */ public transaction_unconfirmed(txid: Uint8Array): void { bindings.Confirm_transaction_unconfirmed(this.ptr, bindings.encodeUint8Array(bindings.check_arr_len(txid, 32))); } + /** + * Processes an update to the best header connected at the given height. + * + * Should be called when a new header is available but may be skipped for intermediary blocks + * if they become available at the same time. + */ public best_block_updated(header: Uint8Array, height: number): void { bindings.Confirm_best_block_updated(this.ptr, bindings.encodeUint8Array(bindings.check_arr_len(header, 80)), height); } + /** + * Returns transactions that should be monitored for reorganization out of the chain. + * + * Should include any transactions passed to [`transactions_confirmed`] that have insufficient + * confirmations to be safe from a chain reorganization. Should not include any transactions + * passed to [`transaction_unconfirmed`] unless later reconfirmed. + * + * May be called to determine the subset of transactions that must still be monitored for + * reorganization. Will be idempotent between calls but may change as a result of calls to the + * other interface methods. Thus, this is useful to determine which transactions may need to be + * given to [`transaction_unconfirmed`]. + * + * [`transactions_confirmed`]: Self::transactions_confirmed + * [`transaction_unconfirmed`]: Self::transaction_unconfirmed + */ public get_relevant_txids(): Uint8Array[] { const ret: number = bindings.Confirm_get_relevant_txids(this.ptr); const ret_conv_12_len: number = bindings.getArrayLength(ret); @@ -360,6 +486,7 @@ export class Confirm extends CommonBase { const ret_conv_12_conv: Uint8Array = bindings.decodeUint8Array(ret_conv_12); ret_conv_12_arr[m] = ret_conv_12_conv; } + bindings.freeWasmMemory(ret) return ret_conv_12_arr; }