Merge pull request #840 from jkczyz/2021-03-rescan-logic

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

diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs
index 7d410b9b71dd116cbe22d2858e9664ec6bc14381..18c7fd55d7b6643bbbc140a5208df42e39e42ea3 100644 (file)
--- a/lightning/src/chain/mod.rs
+++ b/lightning/src/chain/mod.rs
@@ -11,7 +11,7 @@
 
 use bitcoin::blockdata::block::{Block, BlockHeader};
 use bitcoin::blockdata::script::Script;
-use bitcoin::blockdata::transaction::TxOut;
+use bitcoin::blockdata::transaction::{Transaction, TxOut};
 use bitcoin::hash_types::{BlockHash, Txid};
 
 use chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, ChannelMonitorUpdateErr, MonitorEvent};
@@ -129,9 +129,38 @@ pub trait Filter: Send + Sync {
        /// a spending condition.
        fn register_tx(&self, txid: &Txid, script_pubkey: &Script);
 
-       /// Registers interest in spends of a transaction output identified by `outpoint` having
-       /// `script_pubkey` as the spending condition.
-       fn register_output(&self, outpoint: &OutPoint, script_pubkey: &Script);
+       /// Registers interest in spends of a transaction output.
+       ///
+       /// Optionally, when `output.block_hash` is set, should return any transaction spending the
+       /// output that is found in the corresponding block along with its index.
+       ///
+       /// This return value is useful for Electrum clients in order to supply in-block descendant
+       /// transactions which otherwise were not included. This is not necessary for other clients if
+       /// such descendant transactions were already included (e.g., when a BIP 157 client provides the
+       /// full block).
+       fn register_output(&self, output: WatchedOutput) -> Option<(usize, Transaction)>;
+}
+
+/// A transaction output watched by a [`ChannelMonitor`] for spends on-chain.
+///
+/// Used to convey to a [`Filter`] such an output with a given spending condition. Any transaction
+/// spending the output must be given to [`ChannelMonitor::block_connected`] either directly or via
+/// the return value of [`Filter::register_output`].
+///
+/// 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.
+///
+/// [`ChannelMonitor`]: channelmonitor::ChannelMonitor
+/// [`ChannelMonitor::block_connected`]: channelmonitor::ChannelMonitor::block_connected
+pub struct WatchedOutput {
+       /// First block where the transaction output may have been spent.
+       pub block_hash: Option<BlockHash>,
+
+       /// Outpoint identifying the transaction output.
+       pub outpoint: OutPoint,
+
+       /// Spending condition of the transaction output.
+       pub script_pubkey: Script,
 }
 
 impl<T: Listen> Listen for std::ops::Deref<Target = T> {