Trait lightning::chain::Confirm [−][src]
pub trait Confirm { 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>ⓘ; }
Expand description
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 byget_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.
Required methods
fn transactions_confirmed(
&self,
header: &BlockHeader,
txdata: &TransactionData<'_>,
height: u32
)
fn transactions_confirmed(
&self,
header: &BlockHeader,
txdata: &TransactionData<'_>,
height: u32
)
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
.
fn transaction_unconfirmed(&self, txid: &Txid)
fn transaction_unconfirmed(&self, txid: &Txid)
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
.
fn best_block_updated(&self, header: &BlockHeader, height: u32)
fn best_block_updated(&self, header: &BlockHeader, height: u32)
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.
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
.