X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fchain%2Fmod.rs;h=01eae488700605b2f23c50d5fdfdc0c2319859bc;hb=ccf92157620da45032d75f06b5972eaf142c1ce3;hp=bb80440d116a5a11286c41745d9b55e2c07137a5;hpb=31042ab7d524d75a1e9eb34080c1bdc666c9101e;p=rust-lightning diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs index bb80440d..01eae488 100644 --- a/lightning/src/chain/mod.rs +++ b/lightning/src/chain/mod.rs @@ -17,11 +17,11 @@ use bitcoin::hash_types::{BlockHash, Txid}; use bitcoin::network::constants::Network; use bitcoin::secp256k1::PublicKey; -use chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, MonitorEvent}; -use chain::keysinterface::Sign; -use chain::transaction::{OutPoint, TransactionData}; +use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, MonitorEvent}; +use crate::chain::keysinterface::WriteableEcdsaChannelSigner; +use crate::chain::transaction::{OutPoint, TransactionData}; -use prelude::*; +use crate::prelude::*; pub mod chaininterface; pub mod chainmonitor; @@ -107,31 +107,35 @@ pub trait Listen { fn block_disconnected(&self, header: &BlockHeader, height: u32); } -/// The `Confirm` trait is used to notify when transactions have been confirmed on chain or -/// unconfirmed during a chain reorganization. +/// 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 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. +/// [`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 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. +/// - 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 confirmed in a block must be given before transactions confirmed in a later -/// block. +/// - 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. -/// - Unconfirmed transactions must be given after the original confirmations and before any -/// reconfirmation. +/// - 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. /// @@ -140,9 +144,9 @@ pub trait Listen { /// [`best_block_updated`]: Self::best_block_updated /// [`get_relevant_txids`]: Self::get_relevant_txids pub trait Confirm { - /// Processes transactions confirmed in a block with a given header and height. + /// Notifies LDK of transactions confirmed in a block with a given header and height. /// - /// Should be called for any transactions registered by [`Filter::register_tx`] or any + /// 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]. @@ -154,37 +158,40 @@ pub trait Confirm { /// [chain order]: Confirm#order /// [`best_block_updated`]: Self::best_block_updated fn transactions_confirmed(&self, header: &BlockHeader, txdata: &TransactionData, height: u32); - - /// Processes a transaction that is no longer confirmed as result of a chain reorganization. + /// Notifies LDK of 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 will not be returned + /// 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 fn transaction_unconfirmed(&self, txid: &Txid); - - /// Processes an update to the best header connected at the given height. + /// Notifies LDK of 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. + /// Must be called whenever a new chain tip becomes available. May be skipped for intermediary + /// blocks. fn best_block_updated(&self, header: &BlockHeader, height: u32); - - /// Returns transactions that should be monitored for reorganization out of the chain. + /// 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. /// /// 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. /// - /// May be called to determine the subset of transactions that must still be monitored for + /// 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 may need to be + /// 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 - fn get_relevant_txids(&self) -> Vec; + fn get_relevant_txids(&self) -> Vec<(Txid, Option)>; } /// An enum representing the status of a channel monitor update persistence. @@ -284,7 +291,7 @@ pub enum ChannelMonitorUpdateStatus { /// multiple instances. /// /// [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure -pub trait Watch { +pub trait Watch { /// Watches a channel identified by `funding_txo` using `monitor`. /// /// Implementations are responsible for watching the chain for the funding transaction along @@ -305,7 +312,7 @@ pub trait Watch { /// [`ChannelMonitorUpdateStatus`] for invariants around returning an error. /// /// [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor - fn update_channel(&self, funding_txo: OutPoint, update: ChannelMonitorUpdate) -> ChannelMonitorUpdateStatus; + fn update_channel(&self, funding_txo: OutPoint, update: &ChannelMonitorUpdate) -> ChannelMonitorUpdateStatus; /// Returns any monitor events since the last call. Subsequent calls must only return new /// events.