X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fchain%2Fmod.rs;h=736da139a558a3f20960ad75e8c90f23264594fd;hb=23c5308bcbea61d89b1e5d3df6b6da721bc74c2a;hp=0370c0840f9b611c99f84f41191ea72d1a5644b5;hpb=3bd395f2a8a7398d7bf5ad9b2c7257e64f9c126b;p=rust-lightning diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs index 0370c084..736da139 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::WriteableEcdsaChannelSigner; +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. @@ -214,10 +192,6 @@ pub enum ChannelMonitorUpdateStatus { /// have been successfully applied, a [`MonitorEvent::Completed`] can be used to restore the /// channel to an operational state. /// - /// Note that a given [`ChannelManager`] will *never* re-generate a [`ChannelMonitorUpdate`]. - /// If you return this error you must ensure that it is written to disk safely before writing - /// the latest [`ChannelManager`] state, or you should return [`PermanentFailure`] instead. - /// /// 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. @@ -230,49 +204,8 @@ pub enum ChannelMonitorUpdateStatus { /// remote location (with local copies persisted immediately), it is anticipated that all /// updates will return [`InProgress`] until the remote copies could be updated. /// - /// [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure /// [`InProgress`]: ChannelMonitorUpdateStatus::InProgress - /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager InProgress, - /// Used to indicate no further channel monitor updates will be allowed (likely a disk failure - /// or a remote copy of this [`ChannelMonitor`] is no longer reachable and thus not updatable). - /// - /// When this is returned, [`ChannelManager`] will force-close the channel but *not* broadcast - /// our current commitment transaction. This avoids a dangerous case where a local disk failure - /// (e.g. the Linux-default remounting of the disk as read-only) causes [`PermanentFailure`]s - /// for all monitor updates. If we were to broadcast our latest commitment transaction and then - /// restart, we could end up reading a previous [`ChannelMonitor`] and [`ChannelManager`], - /// revoking our now-broadcasted state before seeing it confirm and losing all our funds. - /// - /// Note that this is somewhat of a tradeoff - if the disk is really gone and we may have lost - /// the data permanently, we really should broadcast immediately. If the data can be recovered - /// with manual intervention, we'd rather close the channel, rejecting future updates to it, - /// and broadcast the latest state only if we have HTLCs to claim which are timing out (which - /// we do as long as blocks are connected). - /// - /// In order to broadcast the latest local commitment transaction, you'll need to call - /// [`ChannelMonitor::get_latest_holder_commitment_txn`] and broadcast the resulting - /// transactions once you've safely ensured no further channel updates can be generated by your - /// [`ChannelManager`]. - /// - /// Note that at least one final [`ChannelMonitorUpdate`] may still be provided, which must - /// still be processed by a running [`ChannelMonitor`]. This final update will mark the - /// [`ChannelMonitor`] as finalized, ensuring no further updates (e.g. revocation of the latest - /// commitment transaction) are allowed. - /// - /// Note that even if you return a [`PermanentFailure`] due to unavailability of secondary - /// [`ChannelMonitor`] copies, you should still make an attempt to store the update where - /// possible to ensure you can claim HTLC outputs on the latest commitment transaction - /// broadcasted later. - /// - /// 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`]: ChannelMonitorUpdateStatus::PermanentFailure - /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager - PermanentFailure, } /// The `Watch` trait defines behavior for watching on-chain activity pertaining to channels as @@ -284,16 +217,13 @@ pub enum ChannelMonitorUpdateStatus { /// requirements. /// /// 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. +/// completion. If an update will not succeed, then it must immediately shut down. /// /// 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 [`ChannelMonitorUpdateStatus`] for more details about how to handle /// multiple instances. -/// -/// [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure pub trait Watch { /// Watches a channel identified by `funding_txo` using `monitor`. /// @@ -301,20 +231,30 @@ pub trait Watch { /// 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 [`ChannelMonitorUpdateStatus::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) -> ChannelMonitorUpdateStatus; + 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 - /// [`ChannelMonitorUpdateStatus`] 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. + /// + /// If persistence fails, this should return [`ChannelMonitorUpdateStatus::InProgress`] and + /// the node should shut down immediately. /// - /// [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor + /// [`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 @@ -411,3 +351,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]);