//! Structs and traits which allow other parts of rust-lightning to interact with the blockchain.
use bitcoin::blockdata::block::{Block, BlockHeader};
+use bitcoin::blockdata::constants::genesis_block;
use bitcoin::blockdata::script::Script;
use bitcoin::blockdata::transaction::{Transaction, TxOut};
use bitcoin::hash_types::{BlockHash, Txid};
+use bitcoin::network::constants::Network;
-use chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, ChannelMonitorUpdateErr, MonitorEvent};
+use chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, MonitorEvent};
use chain::keysinterface::Sign;
use chain::transaction::{OutPoint, TransactionData};
+use 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)]
+pub struct BestBlock {
+ block_hash: BlockHash,
+ height: u32,
+}
+
+impl BestBlock {
+ /// Constructs a `BestBlock` that represents the genesis block at height 0 of the given
+ /// network.
+ pub fn from_genesis(network: Network) -> Self {
+ BestBlock {
+ block_hash: genesis_block(network).header.block_hash(),
+ height: 0,
+ }
+ }
+
+ /// Returns a `BestBlock` as identified by the given block hash and height.
+ 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 }
+}
/// An error when accessing the chain via [`Access`].
#[derive(Clone)]
/// The `Access` trait defines behavior for accessing chain data and state, such as blocks and
/// UTXOs.
-pub trait Access: Send + Sync {
+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.
/// in the event of a chain reorganization, it must not be called with a `header` that is no
/// longer in the chain as of the last call to [`best_block_updated`].
///
- /// [chain order]: Self#order
+ /// [chain order]: Confirm#Order
/// [`best_block_updated`]: Self::best_block_updated
fn transactions_confirmed(&self, header: &BlockHeader, txdata: &TransactionData, height: u32);
fn get_relevant_txids(&self) -> Vec<Txid>;
}
+/// 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) which failed
+ /// have been successfully applied, ChannelManager::channel_monitor_updated can be used to
+ /// restore the channel to an operational state.
+ ///
+ /// 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.
+ ///
+ /// 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".
+ ///
+ /// Note that even if updates made after TemporaryFailure succeed you must still call
+ /// channel_monitor_updated to ensure you have the latest monitor and re-enable normal channel
+ /// operation.
+ ///
+ /// Note that the update being processed here will not be replayed for you when you call
+ /// ChannelManager::channel_monitor_updated, so you must store the update itself along
+ /// with the persisted ChannelMonitor 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.
+ ///
+ /// 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.
+ 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).
+ ///
+ /// 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.
+ ///
+ /// This failure may also signal a failure to update the local persisted copy of one of
+ /// the channel monitor instance.
+ ///
+ /// 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)
+ ///
+ /// 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,
+}
+
/// The `Watch` trait defines behavior for watching on-chain activity pertaining to channels as
/// blocks are connected and disconnected.
///
/// funds in the channel. See [`ChannelMonitorUpdateErr`] for more details about how to handle
/// multiple instances.
///
-/// [`ChannelMonitor`]: channelmonitor::ChannelMonitor
-/// [`ChannelMonitorUpdateErr`]: channelmonitor::ChannelMonitorUpdateErr
-/// [`PermanentFailure`]: channelmonitor::ChannelMonitorUpdateErr::PermanentFailure
-pub trait Watch<ChannelSigner: Sign>: Send + Sync {
+/// [`PermanentFailure`]: ChannelMonitorUpdateErr::PermanentFailure
+pub trait Watch<ChannelSigner: Sign> {
/// 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`.
+ ///
/// [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch
/// [`block_connected`]: channelmonitor::ChannelMonitor::block_connected
/// [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected
/// [`ChannelMonitorUpdateErr`] for invariants around returning an error.
///
/// [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor
- /// [`ChannelMonitorUpdateErr`]: channelmonitor::ChannelMonitorUpdateErr
fn update_channel(&self, funding_txo: OutPoint, update: ChannelMonitorUpdate) -> Result<(), ChannelMonitorUpdateErr>;
/// Returns any monitor events since the last call. Subsequent calls must only return new
/// processed later. Then, in order to block until the data has been processed, any [`Watch`]
/// invocation that has called the `Filter` must return [`TemporaryFailure`].
///
-/// [`TemporaryFailure`]: channelmonitor::ChannelMonitorUpdateErr::TemporaryFailure
+/// [`TemporaryFailure`]: ChannelMonitorUpdateErr::TemporaryFailure
/// [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: Send + Sync {
+pub trait Filter {
/// Registers interest in a transaction with `txid` and having an output with `script_pubkey` as
/// a spending condition.
fn register_tx(&self, txid: &Txid, script_pubkey: &Script);
///
/// [`ChannelMonitor`]: channelmonitor::ChannelMonitor
/// [`ChannelMonitor::block_connected`]: channelmonitor::ChannelMonitor::block_connected
+#[derive(Clone, PartialEq, Hash)]
pub struct WatchedOutput {
/// First block where the transaction output may have been spent.
pub block_hash: Option<BlockHash>,
pub script_pubkey: Script,
}
-impl<T: Listen> Listen for std::ops::Deref<Target = T> {
+impl<T: Listen> Listen for core::ops::Deref<Target = T> {
fn block_connected(&self, block: &Block, height: u32) {
(**self).block_connected(block, height);
}
}
}
-impl<T: std::ops::Deref, U: std::ops::Deref> Listen for (T, U)
+impl<T: core::ops::Deref, U: core::ops::Deref> Listen for (T, U)
where
T::Target: Listen,
U::Target: Listen,