pub trait Confirm {
// Required methods
fn transactions_confirmed(
&self,
header: &BlockHeader,
txdata: &TransactionData<'_>,
height: u32
);
fn transaction_unconfirmed(&self, txid: &Txid);
fn best_block_updated(&self, header: &BlockHeader, height: u32);
fn get_relevant_txids(&self) -> Vec<(Txid, Option<BlockHash>)>;
}Expand description
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_confirmedto notify LDK whenever any of the registered transactions or outputs are, respectively, confirmed or spent on chain. - Call
transaction_unconfirmedto notify LDK whenever any transaction returned byget_relevant_txidsis no longer confirmed in the block with the given block hash. - Call
best_block_updatedto 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_confirmedandtransaction_unconfirmedcalls 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.
Required Methods§
sourcefn transactions_confirmed(
&self,
header: &BlockHeader,
txdata: &TransactionData<'_>,
height: u32
)
fn transactions_confirmed( &self, header: &BlockHeader, txdata: &TransactionData<'_>, height: u32 )
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.
sourcefn transaction_unconfirmed(&self, txid: &Txid)
fn transaction_unconfirmed(&self, txid: &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.
sourcefn best_block_updated(&self, header: &BlockHeader, height: u32)
fn best_block_updated(&self, header: &BlockHeader, height: u32)
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.
sourcefn get_relevant_txids(&self) -> Vec<(Txid, Option<BlockHash>)>
fn get_relevant_txids(&self) -> Vec<(Txid, Option<BlockHash>)>
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<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, they need to be unconfirmed and reconfirmed via transaction_unconfirmed and
transactions_confirmed, respectively.