X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fchain%2Fmod.rs;h=236b10a7b19d1288b5d74f784d066c2a8bacc169;hb=cc1b505b305c5339496d9aaca28c73b083ba602f;hp=33d4826fef210b849b61818fd9ba241aad2a9971;hpb=593d8c4610f082441563d4906d64175a354b1cfc;p=rust-lightning diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs index 33d4826f..236b10a7 100644 --- a/lightning/src/chain/mod.rs +++ b/lightning/src/chain/mod.rs @@ -12,13 +12,12 @@ use bitcoin::blockdata::block::{Block, BlockHeader}; use bitcoin::blockdata::constants::genesis_block; use bitcoin::blockdata::script::Script; -use bitcoin::blockdata::transaction::TxOut; use bitcoin::hash_types::{BlockHash, Txid}; use bitcoin::network::constants::Network; use bitcoin::secp256k1::PublicKey; use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, MonitorEvent}; -use crate::chain::keysinterface::Sign; +use crate::sign::WriteableEcdsaChannelSigner; use crate::chain::transaction::{OutPoint, TransactionData}; use crate::prelude::*; @@ -27,7 +26,6 @@ pub mod chaininterface; pub mod chainmonitor; pub mod channelmonitor; pub mod transaction; -pub mod keysinterface; pub(crate) mod onchaintx; pub(crate) mod package; @@ -41,7 +39,7 @@ pub struct BestBlock { impl BestBlock { /// Constructs a `BestBlock` that represents the genesis block at height 0 of the given /// network. - pub fn from_genesis(network: Network) -> Self { + pub fn from_network(network: Network) -> Self { BestBlock { block_hash: genesis_block(network).header.block_hash(), height: 0, @@ -60,26 +58,6 @@ impl BestBlock { pub fn height(&self) -> u32 { self.height } } -/// An error when accessing the chain via [`Access`]. -#[derive(Clone, Debug)] -pub enum AccessError { - /// The requested chain is unknown. - UnknownChain, - - /// The requested transaction doesn't exist or hasn't confirmed. - UnknownTx, -} - -/// The `Access` trait defines behavior for accessing chain data and state, such as blocks and -/// UTXOs. -pub trait Access { - /// Returns the transaction output of a funding transaction encoded by [`short_channel_id`]. - /// Returns an error if `genesis_hash` is for a different chain or if such a transaction output - /// is unknown. - /// - /// [`short_channel_id`]: https://github.com/lightning/bolts/blob/master/07-routing-gossip.md#definition-of-short_channel_id - fn get_utxo(&self, genesis_hash: &BlockHash, short_channel_id: u64) -> Result; -} /// The `Listen` trait is used to notify when blocks have been connected or disconnected from the /// chain. @@ -107,31 +85,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 +122,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,36 +136,39 @@ 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 along - /// with the hash of the block as part of which had been previously confirmed. + /// 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. /// - /// 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 - /// 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. + /// 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 @@ -287,7 +272,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 @@ -308,7 +293,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. @@ -404,3 +389,9 @@ where self.1.block_disconnected(header, height); } } + +/// A unique identifier to track each pending output claim within a [`ChannelMonitor`]. +/// +/// This is not exported to bindings users as we just use [u8; 32] directly. +#[derive(Copy, Clone, Debug, Hash, PartialEq, Eq)] +pub struct ClaimId(pub [u8; 32]);