X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fchain%2Fmod.rs;h=e43c08d55e513a906000d52a2fd6795580bb5037;hb=refs%2Fheads%2Fupstream%2Fmain;hp=1abaa77f3e4a88013a1b5550b05db4dbf6eed80a;hpb=e5bd7920bddb4f312741673e37a07cd859fd24fb;p=rust-lightning diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs index 1abaa77f..e43c08d5 100644 --- a/lightning/src/chain/mod.rs +++ b/lightning/src/chain/mod.rs @@ -9,17 +9,20 @@ //! Structs and traits which allow other parts of rust-lightning to interact with the blockchain. -use bitcoin::blockdata::block::{Block, BlockHeader}; +use bitcoin::blockdata::block::{Block, Header}; use bitcoin::blockdata::constants::genesis_block; -use bitcoin::blockdata::script::Script; +use bitcoin::blockdata::script::{Script, ScriptBuf}; use bitcoin::hash_types::{BlockHash, Txid}; -use bitcoin::network::constants::Network; +use bitcoin::network::Network; use bitcoin::secp256k1::PublicKey; use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, MonitorEvent}; -use crate::sign::WriteableEcdsaChannelSigner; +use crate::ln::types::ChannelId; +use crate::sign::ecdsa::EcdsaChannelSigner; use crate::chain::transaction::{OutPoint, TransactionData}; +use crate::impl_writeable_tlv_based; +#[allow(unused_imports)] use crate::prelude::*; pub mod chaininterface; @@ -30,10 +33,12 @@ pub(crate) mod onchaintx; pub(crate) mod package; /// The best known block as identified by its hash and height. -#[derive(Clone, Copy, PartialEq, Eq)] +#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)] pub struct BestBlock { - block_hash: BlockHash, - height: u32, + /// The block's hash + pub block_hash: BlockHash, + /// The height at which the block was confirmed. + pub height: u32, } impl BestBlock { @@ -47,17 +52,19 @@ impl BestBlock { } /// Returns a `BestBlock` as identified by the given block hash and height. + /// + /// This is not exported to bindings users directly as the bindings auto-generate an + /// equivalent `new`. pub fn new(block_hash: BlockHash, height: u32) -> Self { BestBlock { block_hash, height } } - - /// Returns the best block hash. - pub fn block_hash(&self) -> BlockHash { self.block_hash } - - /// Returns the best block height. - pub fn height(&self) -> u32 { self.height } } +impl_writeable_tlv_based!(BestBlock, { + (0, block_hash, required), + (2, height, required), +}); + /// The `Listen` trait is used to notify when blocks have been connected or disconnected from the /// chain. @@ -73,7 +80,7 @@ impl BestBlock { pub trait Listen { /// Notifies the listener that a block was added at the given height, with the transaction data /// possibly filtered. - fn filtered_block_connected(&self, header: &BlockHeader, txdata: &TransactionData, height: u32); + fn filtered_block_connected(&self, header: &Header, txdata: &TransactionData, height: u32); /// Notifies the listener that a block was added at the given height. fn block_connected(&self, block: &Block, height: u32) { @@ -82,7 +89,7 @@ pub trait Listen { } /// Notifies the listener that a block was removed at the given height. - fn block_disconnected(&self, header: &BlockHeader, height: u32); + fn block_disconnected(&self, header: &Header, height: u32); } /// The `Confirm` trait is used to notify LDK when relevant transactions have been confirmed on @@ -135,7 +142,7 @@ pub trait Confirm { /// /// [chain order]: Confirm#order /// [`best_block_updated`]: Self::best_block_updated - fn transactions_confirmed(&self, header: &BlockHeader, txdata: &TransactionData, height: u32); + fn transactions_confirmed(&self, header: &Header, txdata: &TransactionData, height: u32); /// Notifies LDK of a transaction that is no longer confirmed as result of a chain reorganization. /// /// Must be called for any transaction returned by [`get_relevant_txids`] if it has been @@ -150,9 +157,9 @@ pub trait Confirm { /// /// 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); + fn best_block_updated(&self, header: &Header, height: u32); /// 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. + /// with the height and 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. @@ -167,19 +174,24 @@ pub trait Confirm { /// 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. + /// given hash at the given height, 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<(Txid, Option)>; + fn get_relevant_txids(&self) -> Vec<(Txid, u32, Option)>; } /// An enum representing the status of a channel monitor update persistence. /// -/// Note that there is no error variant - any failure to persist a [`ChannelMonitor`] should be -/// retried indefinitely, the node shut down (as if we cannot update stored data we can't do much -/// of anything useful). +/// 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 @@ -187,6 +199,8 @@ pub trait Confirm { /// 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 { @@ -212,8 +226,8 @@ pub enum ChannelMonitorUpdateStatus { /// 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 + /// 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. /// /// Note that while fully asynchronous persistence of [`ChannelMonitor`] data is generally @@ -222,6 +236,18 @@ pub enum ChannelMonitorUpdateStatus { /// /// [`InProgress`]: ChannelMonitorUpdateStatus::InProgress InProgress, + /// Indicates that an update has failed and will not complete at any point in the future. + /// + /// 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. + /// + /// 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. + /// + /// [`InProgress`]: ChannelMonitorUpdateStatus::InProgress + UnrecoverableError, } /// The `Watch` trait defines behavior for watching on-chain activity pertaining to channels as @@ -234,7 +260,7 @@ pub enum ChannelMonitorUpdateStatus { /// application crashes. /// /// See method documentation and [`ChannelMonitorUpdateStatus`] for specific requirements. -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 @@ -261,8 +287,10 @@ pub trait Watch { /// 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. + /// 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; @@ -276,7 +304,7 @@ pub trait Watch { /// /// For details on asynchronous [`ChannelMonitor`] updating and returning /// [`MonitorEvent::Completed`] here, see [`ChannelMonitorUpdateStatus::InProgress`]. - fn release_pending_monitor_events(&self) -> Vec<(OutPoint, Vec, Option)>; + fn release_pending_monitor_events(&self) -> Vec<(OutPoint, ChannelId, Vec, Option)>; } /// The `Filter` trait defines behavior for indicating chain activity of interest pertaining to @@ -302,6 +330,11 @@ pub trait Watch { pub trait Filter { /// Registers interest in a transaction with `txid` and having an output with `script_pubkey` as /// a spending condition. + /// + /// This may be used, for example, to monitor for when a funding transaction confirms. + /// + /// The `script_pubkey` is provided for informational purposes and may be useful for block + /// sources which only support filtering on scripts. fn register_tx(&self, txid: &Txid, script_pubkey: &Script); /// Registers interest in spends of a transaction output. @@ -310,6 +343,9 @@ pub trait Filter { /// to ensure that also dependent output spents within an already connected block are correctly /// handled, e.g., by re-scanning the block in question whenever new outputs have been /// registered mid-processing. + /// + /// This may be used, for example, to monitor for when a funding output is spent (by any + /// transaction). fn register_output(&self, output: WatchedOutput); } @@ -322,6 +358,9 @@ pub trait Filter { /// If `block_hash` is `Some`, this indicates the output was created in the corresponding block and /// may have been spent there. See [`Filter::register_output`] for details. /// +/// Depending on your block source, you may need one or both of either [`Self::outpoint`] or +/// [`Self::script_pubkey`]. +/// /// [`ChannelMonitor`]: channelmonitor::ChannelMonitor /// [`ChannelMonitor::block_connected`]: channelmonitor::ChannelMonitor::block_connected #[derive(Clone, PartialEq, Eq, Hash)] @@ -333,15 +372,15 @@ pub struct WatchedOutput { pub outpoint: OutPoint, /// Spending condition of the transaction output. - pub script_pubkey: Script, + pub script_pubkey: ScriptBuf, } -impl Listen for core::ops::Deref { - fn filtered_block_connected(&self, header: &BlockHeader, txdata: &TransactionData, height: u32) { +impl Listen for dyn core::ops::Deref { + fn filtered_block_connected(&self, header: &Header, txdata: &TransactionData, height: u32) { (**self).filtered_block_connected(header, txdata, height); } - fn block_disconnected(&self, header: &BlockHeader, height: u32) { + fn block_disconnected(&self, header: &Header, height: u32) { (**self).block_disconnected(header, height); } } @@ -351,12 +390,12 @@ where T::Target: Listen, U::Target: Listen, { - fn filtered_block_connected(&self, header: &BlockHeader, txdata: &TransactionData, height: u32) { + fn filtered_block_connected(&self, header: &Header, txdata: &TransactionData, height: u32) { self.0.filtered_block_connected(header, txdata, height); self.1.filtered_block_connected(header, txdata, height); } - fn block_disconnected(&self, header: &BlockHeader, height: u32) { + fn block_disconnected(&self, header: &Header, height: u32) { self.0.block_disconnected(header, height); self.1.block_disconnected(header, height); }