Class Confirm


  • public class Confirm
    extends Object
    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
    • Method Detail

      • destroy

        public void destroy()
        Destroys the object, freeing associated resources. After this call, any access to this object may result in a SEGFAULT or worse. You should generally NEVER call this method. You should let the garbage collector do this for you when it finalizes objects. However, it may be useful for types which represent locks and should be closed immediately to avoid holding locks until the GC runs.
      • transactions_confirmed

        public void transactions_confirmed​(byte[] header,
                                           TwoTuple_usizeTransactionZ[] txdata,
                                           int height)
        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
      • transaction_unconfirmed

        public void transaction_unconfirmed​(byte[] txid)
        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
      • best_block_updated

        public void best_block_updated​(byte[] header,
                                       int height)
        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.
      • get_relevant_txids

        public TwoTuple_TxidBlockHashZ[] get_relevant_txids()
        Returns transactions that must be monitored for reorganization out of the chain along with the hash of the block as part of which it had been previously confirmed. Note that the returned `Option` 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, they need to be unconfirmed and reconfirmed via [`transaction_unconfirmed`] and [`transactions_confirmed`], respectively. [`transactions_confirmed`]: Self::transactions_confirmed [`transaction_unconfirmed`]: Self::transaction_unconfirmed