X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fchain%2Fmod.rs;h=89e0b155cf68b2db3f24c1a0b23f1e01aacb67b1;hb=44e87b86f27a1a6ff3860e8ab87a52e756aa7cc8;hp=f0544679817db3434a679662901240b99d68da54;hpb=15a5966fa24286ca805aea3a97e606b10c71543d;p=rust-lightning diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs index f0544679..89e0b155 100644 --- a/lightning/src/chain/mod.rs +++ b/lightning/src/chain/mod.rs @@ -12,27 +12,25 @@ 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 chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, MonitorEvent}; -use chain::keysinterface::Sign; -use chain::transaction::{OutPoint, TransactionData}; +use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, MonitorEvent}; +use crate::sign::WriteableEcdsaChannelSigner; +use crate::chain::transaction::{OutPoint, TransactionData}; -use prelude::*; +use crate::prelude::*; pub mod chaininterface; pub mod chainmonitor; pub mod channelmonitor; pub mod transaction; -pub mod keysinterface; pub(crate) mod onchaintx; pub(crate) mod package; /// The best known block as identified by its hash and height. -#[derive(Clone, Copy, PartialEq)] +#[derive(Clone, Copy, PartialEq, Eq)] pub struct BestBlock { block_hash: BlockHash, height: u32, @@ -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,145 +136,157 @@ 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. + /// + /// 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 + /// 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 error enum representing a failure to persist a channel monitor update. -#[derive(Clone, Copy, Debug, PartialEq)] -pub enum ChannelMonitorUpdateErr { - /// Used to indicate a temporary failure (eg connection to a watchtower or remote backup of - /// our state failed, but is expected to succeed at some point in the future). - /// - /// Such a failure will "freeze" a channel, preventing us from revoking old states or - /// submitting new commitment transactions to the counterparty. Once the update(s) that failed - /// have been successfully applied, a [`MonitorEvent::UpdateCompleted`] event should be returned - /// via [`Watch::release_pending_monitor_events`] which will then restore the channel to an - /// operational state. +/// An enum representing the status of a channel monitor update persistence. +/// +/// These are generally used as the return value for an implementation of [`Persist`] which is used +/// as the storage layer for a [`ChainMonitor`]. See the docs on [`Persist`] for a high-level +/// explanation of how to handle different cases. +/// +/// While `UnrecoverableError` is provided as a failure variant, it is not truly "handled" on the +/// calling side, and generally results in an immediate panic. For those who prefer to avoid +/// panics, `InProgress` can be used and you can retry the update operation in the background or +/// shut down cleanly. +/// +/// Note that channels should generally *not* be force-closed after a persistence failure. +/// Force-closing with the latest [`ChannelMonitorUpdate`] applied may result in a transaction +/// being broadcast which can only be spent by the latest [`ChannelMonitor`]! Thus, if the +/// latest [`ChannelMonitor`] is not durably persisted anywhere and exists only in memory, naively +/// calling [`ChannelManager::force_close_broadcasting_latest_txn`] *may result in loss of funds*! +/// +/// [`Persist`]: chainmonitor::Persist +/// [`ChainMonitor`]: chainmonitor::ChainMonitor +/// [`ChannelManager::force_close_broadcasting_latest_txn`]: crate::ln::channelmanager::ChannelManager::force_close_broadcasting_latest_txn +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum ChannelMonitorUpdateStatus { + /// The update has been durably persisted and all copies of the relevant [`ChannelMonitor`] + /// have been updated. /// - /// Note that a given ChannelManager will *never* re-generate a given ChannelMonitorUpdate. If - /// you return a TemporaryFailure you must ensure that it is written to disk safely before - /// writing out the latest ChannelManager state. + /// This includes performing any `fsync()` calls required to ensure the update is guaranteed to + /// be available on restart even if the application crashes. + Completed, + /// Indicates that the update will happen asynchronously in the background or that a transient + /// failure occurred which is being retried in the background and will eventually complete. /// - /// Even when a channel has been "frozen" updates to the ChannelMonitor can continue to occur - /// (eg if an inbound HTLC which we forwarded was claimed upstream resulting in us attempting - /// to claim it on this channel) and those updates must be applied wherever they can be. At - /// least one such updated ChannelMonitor must be persisted otherwise PermanentFailure should - /// be returned to get things on-chain ASAP using only the in-memory copy. Obviously updates to - /// the channel which would invalidate previous ChannelMonitors are not made when a channel has - /// been "frozen". + /// This will "freeze" a channel, preventing us from revoking old states or submitting a new + /// commitment transaction to the counterparty. Once the update(s) which are `InProgress` have + /// been completed, a [`MonitorEvent::Completed`] can be used to restore the channel to an + /// operational state. /// - /// Note that even if updates made after TemporaryFailure succeed you must still provide a - /// [`MonitorEvent::UpdateCompleted`] to ensure you have the latest monitor and re-enable - /// normal channel operation. Note that this is normally generated through a call to - /// [`ChainMonitor::channel_monitor_updated`]. + /// Even when a channel has been "frozen", updates to the [`ChannelMonitor`] can continue to + /// occur (e.g. if an inbound HTLC which we forwarded was claimed upstream, resulting in us + /// attempting to claim it on this channel) and those updates must still be persisted. /// - /// Note that the update being processed here will not be replayed for you when you return a - /// [`MonitorEvent::UpdateCompleted`] event via [`Watch::release_pending_monitor_events`], so - /// you must store the update itself on your own local disk prior to returning a - /// TemporaryFailure. You may, of course, employ a journaling approach, storing only the - /// ChannelMonitorUpdate on disk without updating the monitor itself, replaying the journal at - /// reload-time. + /// No updates to the channel will be made which could invalidate other [`ChannelMonitor`]s + /// until a [`MonitorEvent::Completed`] is provided, even if you return no error on a later + /// monitor update for the same channel. /// - /// For deployments where a copy of ChannelMonitors and other local state are backed up in a - /// remote location (with local copies persisted immediately), it is anticipated that all - /// updates will return TemporaryFailure until the remote copies could be updated. + /// For deployments where a copy of [`ChannelMonitor`]s and other local state are backed up in + /// a remote location (with local copies persisted immediately), it is anticipated that all + /// updates will return [`InProgress`] until the remote copies could be updated. /// - /// [`ChainMonitor::channel_monitor_updated`]: chainmonitor::ChainMonitor::channel_monitor_updated - TemporaryFailure, - /// Used to indicate no further channel monitor updates will be allowed (eg we've moved on to a - /// different watchtower and cannot update with all watchtowers that were previously informed - /// of this channel). + /// Note that while fully asynchronous persistence of [`ChannelMonitor`] data is generally + /// reliable, this feature is considered beta, and a handful of edge-cases remain. Until the + /// remaining cases are fixed, in rare cases, *using this feature may lead to funds loss*. /// - /// At reception of this error, ChannelManager will force-close the channel and return at - /// least a final ChannelMonitorUpdate::ChannelForceClosed which must be delivered to at - /// least one ChannelMonitor copy. Revocation secret MUST NOT be released and offchain channel - /// update must be rejected. + /// [`InProgress`]: ChannelMonitorUpdateStatus::InProgress + InProgress, + /// Indicates that an update has failed and will not complete at any point in the future. /// - /// This failure may also signal a failure to update the local persisted copy of one of - /// the channel monitor instance. + /// Currently returning this variant will cause LDK to immediately panic to encourage immediate + /// shutdown. In the future this may be updated to disconnect peers and refuse to continue + /// normal operation without a panic. /// - /// Note that even when you fail a holder commitment transaction update, you must store the - /// update to ensure you can claim from it in case of a duplicate copy of this ChannelMonitor - /// broadcasts it (e.g distributed channel-monitor deployment) + /// Applications which wish to perform an orderly shutdown after failure should consider + /// returning [`InProgress`] instead and simply shut down without ever marking the update + /// complete. /// - /// In case of distributed watchtowers deployment, the new version must be written to disk, as - /// state may have been stored but rejected due to a block forcing a commitment broadcast. This - /// storage is used to claim outputs of rejected state confirmed onchain by another watchtower, - /// lagging behind on block processing. - PermanentFailure, + /// [`InProgress`]: ChannelMonitorUpdateStatus::InProgress + UnrecoverableError, } /// The `Watch` trait defines behavior for watching on-chain activity pertaining to channels as /// blocks are connected and disconnected. /// /// Each channel is associated with a [`ChannelMonitor`]. Implementations of this trait are -/// responsible for maintaining a set of monitors such that they can be updated accordingly as -/// channel state changes and HTLCs are resolved. See method documentation for specific -/// requirements. +/// responsible for maintaining a set of monitors such that they can be updated as channel state +/// changes. On each update, *all copies* of a [`ChannelMonitor`] must be updated and the update +/// persisted to disk to ensure that the latest [`ChannelMonitor`] state can be reloaded if the +/// application crashes. /// -/// Implementations **must** ensure that updates are successfully applied and persisted upon method -/// completion. If an update fails with a [`PermanentFailure`], then it must immediately shut down -/// without taking any further action such as persisting the current state. -/// -/// If an implementation maintains multiple instances of a channel's monitor (e.g., by storing -/// backup copies), then it must ensure that updates are applied across all instances. Otherwise, it -/// could result in a revoked transaction being broadcast, allowing the counterparty to claim all -/// funds in the channel. See [`ChannelMonitorUpdateErr`] for more details about how to handle -/// multiple instances. -/// -/// [`PermanentFailure`]: ChannelMonitorUpdateErr::PermanentFailure -pub trait Watch { +/// See method documentation and [`ChannelMonitorUpdateStatus`] for specific requirements. +pub trait Watch { /// Watches a channel identified by `funding_txo` using `monitor`. /// /// Implementations are responsible for watching the chain for the funding transaction along /// with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means /// calling [`block_connected`] and [`block_disconnected`] on the monitor. /// - /// Note: this interface MUST error with `ChannelMonitorUpdateErr::PermanentFailure` if - /// the given `funding_txo` has previously been registered via `watch_channel`. + /// A return of `Err(())` indicates that the channel should immediately be force-closed without + /// broadcasting the funding transaction. + /// + /// If the given `funding_txo` has previously been registered via `watch_channel`, `Err(())` + /// must be returned. /// /// [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch /// [`block_connected`]: channelmonitor::ChannelMonitor::block_connected /// [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected - fn watch_channel(&self, funding_txo: OutPoint, monitor: ChannelMonitor) -> Result<(), ChannelMonitorUpdateErr>; + fn watch_channel(&self, funding_txo: OutPoint, monitor: ChannelMonitor) -> Result; /// Updates a channel identified by `funding_txo` by applying `update` to its monitor. /// - /// Implementations must call [`update_monitor`] with the given update. See - /// [`ChannelMonitorUpdateErr`] for invariants around returning an error. + /// Implementations must call [`ChannelMonitor::update_monitor`] with the given update. This + /// may fail (returning an `Err(())`), in which case this should return + /// [`ChannelMonitorUpdateStatus::InProgress`] (and the update should never complete). This + /// generally implies the channel has been closed (either by the funding outpoint being spent + /// on-chain or the [`ChannelMonitor`] having decided to do so and broadcasted a transaction), + /// and the [`ChannelManager`] state will be updated once it sees the funding spend on-chain. /// - /// [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor - fn update_channel(&self, funding_txo: OutPoint, update: ChannelMonitorUpdate) -> Result<(), ChannelMonitorUpdateErr>; + /// In general, persistence failures should be retried after returning + /// [`ChannelMonitorUpdateStatus::InProgress`] and eventually complete. If a failure truly + /// cannot be retried, the node should shut down immediately after returning + /// [`ChannelMonitorUpdateStatus::UnrecoverableError`], see its documentation for more info. + /// + /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager + 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. @@ -302,7 +296,7 @@ pub trait Watch { /// to disk. /// /// For details on asynchronous [`ChannelMonitor`] updating and returning - /// [`MonitorEvent::UpdateCompleted`] here, see [`ChannelMonitorUpdateErr::TemporaryFailure`]. + /// [`MonitorEvent::Completed`] here, see [`ChannelMonitorUpdateStatus::InProgress`]. fn release_pending_monitor_events(&self) -> Vec<(OutPoint, Vec, Option)>; } @@ -321,9 +315,9 @@ pub trait Watch { /// Note that use as part of a [`Watch`] implementation involves reentrancy. Therefore, the `Filter` /// should not block on I/O. Implementations should instead queue the newly monitored data to be /// processed later. Then, in order to block until the data has been processed, any [`Watch`] -/// invocation that has called the `Filter` must return [`TemporaryFailure`]. +/// invocation that has called the `Filter` must return [`InProgress`]. /// -/// [`TemporaryFailure`]: ChannelMonitorUpdateErr::TemporaryFailure +/// [`InProgress`]: ChannelMonitorUpdateStatus::InProgress /// [BIP 157]: https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki /// [BIP 158]: https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki pub trait Filter { @@ -351,7 +345,7 @@ pub trait Filter { /// /// [`ChannelMonitor`]: channelmonitor::ChannelMonitor /// [`ChannelMonitor::block_connected`]: channelmonitor::ChannelMonitor::block_connected -#[derive(Clone, PartialEq, Hash)] +#[derive(Clone, PartialEq, Eq, Hash)] pub struct WatchedOutput { /// First block where the transaction output may have been spent. pub block_hash: Option, @@ -388,3 +382,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]);