Merge pull request #3144 from TheBlueMatt/2024-06-message-flags

[rust-lightning] / lightning / src / chain / mod.rs

diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs
index 368dd8497b037e4821c0c41b0de7f3e7585d8042..e43c08d55e513a906000d52a2fd6795580bb5037 100644 (file)
--- a/lightning/src/chain/mod.rs
+++ b/lightning/src/chain/mod.rs
@@ -13,14 +13,16 @@ use bitcoin::blockdata::block::{Block, Header};
 use bitcoin::blockdata::constants::genesis_block;
 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::ln::ChannelId;
-use crate::sign::ecdsa::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;
@@ -31,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 {
@@ -48,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.
@@ -254,7 +260,7 @@ pub enum ChannelMonitorUpdateStatus {
 /// application crashes.
 ///
 /// See method documentation and [`ChannelMonitorUpdateStatus`] for specific requirements.
-pub trait Watch<ChannelSigner: WriteableEcdsaChannelSigner> {
+pub trait Watch<ChannelSigner: EcdsaChannelSigner> {
        /// Watches a channel identified by `funding_txo` using `monitor`.
        ///
        /// Implementations are responsible for watching the chain for the funding transaction along
@@ -324,6 +330,11 @@ pub trait Watch<ChannelSigner: WriteableEcdsaChannelSigner> {
 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.
@@ -332,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);
 }
 
@@ -344,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)]