From 57644f6a81c1a3778440c3169cae52e0a8e66e65 Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Sun, 5 May 2024 19:52:58 +0000 Subject: [PATCH] Provide more color in filter registration methods A few years ago we had repeated user confusion dealing with the `Filter` methods and exactly how they differ. Here we try to add a bit more color in several ways as suggested by users in a few places - listing examples of why the methods are used as well as ensuring its clearly communicated that not all parameters need be used. Fixes #1069 --- lightning/src/chain/mod.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs index a8afc7a1a..93c8aa197 100644 --- a/lightning/src/chain/mod.rs +++ b/lightning/src/chain/mod.rs @@ -327,6 +327,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. @@ -335,6 +340,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); } @@ -347,6 +355,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)] -- 2.39.5