Merge pull request #3036 from TheBlueMatt/2024-05-filter-color

Provide more color in filter registration methods

diff --combined lightning/src/chain/mod.rs
index 71b29b672caf7df8dfd3129ab20bd1b2aa0c326b,93c8aa197382ae6ab9221528557e07b0ffe71808..9207313d5fcb93b50fe1f1b16a294e86e683725d
--- 1/lightning/src/chain/mod.rs
--- 2/lightning/src/chain/mod.rs
+++ b/lightning/src/chain/mod.rs
@@@ -18,7 -18,7 +18,7 @@@ use bitcoin::secp256k1::PublicKey
  
  use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, MonitorEvent};
  use crate::ln::types::ChannelId;
 -use crate::sign::ecdsa::WriteableEcdsaChannelSigner;
 +use crate::sign::ecdsa::EcdsaChannelSigner;
  use crate::chain::transaction::{OutPoint, TransactionData};
  use crate::impl_writeable_tlv_based;
  
@@@ -52,9 -52,6 +52,9 @@@ 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 }
        }
@@@ -260,7 -257,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
@@@ -330,6 -327,11 +330,11 @@@
  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.
@@@ -338,6 -340,9 +343,9 @@@
        /// 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);
  }
  
@@@ -350,6 -355,9 +358,9 @@@
  /// 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)]