lightningdevkit/structs/Confirm.d.mts

Lightning Development Kit

import { TwoTuple_usizeTransactionZ } from '../structs/TwoTuple_usizeTransactionZ.mjs';
import { ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ } from '../structs/ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ.mjs';
import { CommonBase } from './CommonBase.mjs';
/** An implementation of Confirm */
export interface ConfirmInterface {
    /**Notifies LDK of transactions confirmed in a block with a given header and height.
     *
     * Must 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;
    /**Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
     *
     * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
     * reorganized out of the best chain or if it is no longer confirmed in the block with the
     * given block hash. Once called, the given transaction will 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;
    /**Notifies LDK of an update to the best header connected at the given height.
     *
     * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
     * blocks.
     */
    best_block_updated(header: Uint8Array, height: number): void;
    /**Returns transactions that must be monitored for reorganization out of the chain along
     * with the height and the hash of the block as part of which it had been previously confirmed.
     *
     * Note that the returned `Option<BlockHash>` might be `None` for channels created with LDK
     * 0.0.112 and prior, in which case you need to manually track previous confirmations.
     *
     * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
     * confirmations to be safe from a chain reorganization. Will not include any transactions
     * passed to [`transaction_unconfirmed`], unless later reconfirmed.
     *
     * Must be called to determine the subset of transactions that must 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 must be
     * given to [`transaction_unconfirmed`].
     *
     * If any of the returned transactions are confirmed in a block other than the one with the
     * given hash at the given height, they need to be unconfirmed and reconfirmed via
     * [`transaction_unconfirmed`] and [`transactions_confirmed`], respectively.
     *
     * [`transactions_confirmed`]: Self::transactions_confirmed
     * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
     */
    get_relevant_txids(): ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ[];
}
/**
 * The `Confirm` trait is used to notify LDK when relevant 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-based transaction sync implementation may implement
 * [`Filter`] to subscribe to relevant transactions and unspent outputs it should monitor for
 * on-chain activity. Then, it needs to notify LDK via this interface upon observing any changes
 * with reference to the confirmation status of the monitored objects.
 *
 * # Use
 * The intended use is as follows:
 * - Call [`transactions_confirmed`] to notify LDK whenever any of the registered transactions or
 * outputs are, respectively, confirmed or spent on chain.
 * - Call [`transaction_unconfirmed`] to notify LDK whenever any transaction returned by
 * [`get_relevant_txids`] is no longer confirmed in the block with the given block hash.
 * - Call [`best_block_updated`] to notify LDK whenever a new chain tip becomes available.
 *
 * # Order
 *
 * Clients must call these methods in chain order. Specifically:
 * - Transactions which are confirmed in a particular 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.
 * - All unconfirmed transactions must be given after the original confirmations and before *any*
 * reconfirmations, i.e., [`transactions_confirmed`] and [`transaction_unconfirmed`] calls should
 * never be interleaved, but always conduced *en bloc*.
 * - Any reconfirmed transactions need to be explicitly unconfirmed before they are reconfirmed
 * in regard to the new block.
 *
 * 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 declare class Confirm extends CommonBase {
    /** Creates a new instance of Confirm from a given implementation */
    static new_impl(arg: ConfirmInterface): Confirm;
    /**
     * Notifies LDK of transactions confirmed in a block with a given header and height.
     *
     * Must 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;
    /**
     * Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization.
     *
     * Must be called for any transaction returned by [`get_relevant_txids`] if it has been
     * reorganized out of the best chain or if it is no longer confirmed in the block with the
     * given block hash. Once called, the given transaction will 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;
    /**
     * Notifies LDK of an update to the best header connected at the given height.
     *
     * Must be called whenever a new chain tip becomes available. May be skipped for intermediary
     * blocks.
     */
    best_block_updated(header: Uint8Array, height: number): void;
    /**
     * Returns transactions that must be monitored for reorganization out of the chain along
     * with the height and the hash of the block as part of which it had been previously confirmed.
     *
     * Note that the returned `Option<BlockHash>` might be `None` for channels created with LDK
     * 0.0.112 and prior, in which case you need to manually track previous confirmations.
     *
     * Will include any transactions passed to [`transactions_confirmed`] that have insufficient
     * confirmations to be safe from a chain reorganization. Will not include any transactions
     * passed to [`transaction_unconfirmed`], unless later reconfirmed.
     *
     * Must be called to determine the subset of transactions that must 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 must be
     * given to [`transaction_unconfirmed`].
     *
     * If any of the returned transactions are confirmed in a block other than the one with the
     * given hash at the given height, they need to be unconfirmed and reconfirmed via
     * [`transaction_unconfirmed`] and [`transactions_confirmed`], respectively.
     *
     * [`transactions_confirmed`]: Self::transactions_confirmed
     * [`transaction_unconfirmed`]: Self::transaction_unconfirmed
     */
    get_relevant_txids(): ThreeTuple_ThirtyTwoBytesu32COption_ThirtyTwoBytesZZ[];
}