Merge PR 'Preserve conflicting output watches' (#5557)
What changed, and why it matters
This change fixes a bug in how the Lightning Dev Kit's transaction-sync clients (Electrum and Esplora) keep track of watched Bitcoin outputs. Previously, if the same output was registered more than once with different script pubkeys (for example, one real and one bogus), the later registration would overwrite the earlier one. This could cause the client to stop monitoring the real output, potentially missing when it is spent on-chain. The fix stores all registered script pubkeys for each output instead of keeping only the last one, so no conflicting watch can hide a legitimate spend.
Treat this as a security-relevant correctness fix. Users relying on Electrum or Esplora transaction sync should upgrade to a release containing this commit, especially if their channel monitor may register outputs multiple times (e.g., on restart or reconnection). Review whether any missed spends could have affected channel state in running nodes.
Security signals we found
State overwrite bug in output watch tracking
Potential missed on-chain spend detection
Conflicting registrations could suppress legitimate script pubkey monitoring
Reorg handling relies on preserved watch state
Fix includes regression tests for ordering and reorg scenarios
Evidence from the diff
The patch changes watched_outputs and FilterQueue.outputs from HashMap<OutPoint, WatchedOutput> to HashMap<OutPoint, BTreeSet<ScriptBuf>>. This preserves every script pubkey registered for an output rather than replacing the whole WatchedOutput on re-registration. Electrum and Esplora sync logic is updated to iterate over all stored script pubkeys per outpoint when querying chain history/status. A new unit test and integration tests verify that repeated or conflicting registrations (including bogus-first order and sync-between-registrations) do not prevent detection of a confirmed spend, and that a reorged spend remains redetected.
Changed components
lightning-transaction-sync/src/common.rslightning-transaction-sync/src/electrum.rslightning-transaction-sync/src/esplora.rslightning-transaction-sync/tests/integration_tests.rsInspect captured patch +164 / −32
### lightning-transaction-sync/src/common.rs
@@ -8,9 +8,9 @@
use bitcoin::block::Header;
use bitcoin::{BlockHash, OutPoint, ScriptBuf, Transaction, Txid};
use lightning::chain::channelmonitor::ANTI_REORG_DELAY;
-use lightning::chain::{Confirm, WatchedOutput};
+use lightning::chain::Confirm;
-use std::collections::HashMap;
+use std::collections::{BTreeSet, HashMap};
use std::ops::Deref;
// Represents the current state.
@@ -22,11 +22,12 @@ pub(crate) struct SyncState {
// bogus `script_pubkey` which must not override a previously-registered one.
pub watched_transactions: HashMap<Txid, Vec<ScriptBuf>>,
// Outputs that were previously processed, but must not be forgotten yet as
- // as we still need to monitor any spends on-chain.
- pub watched_outputs: HashMap<OutPoint, WatchedOutput>,
+ // we still need to monitor any spends on-chain. Keep all registered `script_pubkey`s as some
+ // may be bogus.
+ pub watched_outputs: HashMap<OutPoint, BTreeSet<ScriptBuf>>,
// Outputs for which we previously saw a spend on-chain but kept around until the spends reach
// sufficient depth.
- pub outputs_spends_pending_threshold_conf: Vec<(Txid, u32, OutPoint, WatchedOutput)>,
+ pub outputs_spends_pending_threshold_conf: Vec<(Txid, u32, OutPoint, BTreeSet<ScriptBuf>)>,
// The tip hash observed during our last sync.
pub last_sync_hash: Option<BlockHash>,
// Indicates whether we need to resync, e.g., after encountering an error.
@@ -58,9 +59,12 @@ impl SyncState {
// If a previously-confirmed output spend is unconfirmed, re-add the watched output to
// the tracking map.
self.outputs_spends_pending_threshold_conf.retain(
- |(conf_txid, _, prev_outpoint, output)| {
+ |(conf_txid, _, prev_outpoint, script_pubkeys)| {
if txid == *conf_txid {
- self.watched_outputs.insert(*prev_outpoint, output.clone());
+ self.watched_outputs
+ .entry(*prev_outpoint)
+ .or_default()
+ .extend(script_pubkeys.iter().cloned());
false
} else {
true
@@ -108,8 +112,9 @@ pub(crate) struct FilterQueue {
// registered multiple times with different `script_pubkey`s, in which case we keep all of
// them, as some may be bogus.
pub transactions: HashMap<Txid, Vec<ScriptBuf>>,
- // Outputs that were registered via the `Filter` interface and have to be processed.
- pub outputs: HashMap<OutPoint, WatchedOutput>,
+ // Outputs that were registered via the `Filter` interface and have to be processed. Keep all
+ // registered `script_pubkey`s as some may be bogus.
+ pub outputs: HashMap<OutPoint, BTreeSet<ScriptBuf>>,
}
impl FilterQueue {
@@ -139,7 +144,9 @@ impl FilterQueue {
if !self.outputs.is_empty() {
pending_registrations = true;
- sync_state.watched_outputs.extend(self.outputs.drain());
+ for (outpoint, script_pubkeys) in self.outputs.drain() {
+ sync_state.watched_outputs.entry(outpoint).or_default().extend(script_pubkeys);
+ }
}
pending_registrations
}
### lightning-transaction-sync/src/electrum.rs
@@ -324,12 +324,15 @@ impl<L: Logger> ElectrumSyncClient<L> {
let num_tx_lookups = watched_script_pubkeys.len();
debug_assert_eq!(num_tx_lookups, watched_txs.len());
- for output in sync_state.watched_outputs.values() {
- watched_script_pubkeys.push(output.script_pubkey.clone());
+ for script_pubkey in sync_state.watched_outputs.values().flatten() {
+ watched_script_pubkeys.push(script_pubkey.clone());
}
let num_output_spend_lookups = watched_script_pubkeys.len() - num_tx_lookups;
- debug_assert_eq!(num_output_spend_lookups, sync_state.watched_outputs.len());
+ debug_assert_eq!(
+ num_output_spend_lookups,
+ sync_state.watched_outputs.values().flatten().count()
+ );
match self.client.batch_script_get_history(watched_script_pubkeys.iter().map(|s| s.deref()))
{
@@ -364,17 +367,19 @@ impl<L: Logger> ElectrumSyncClient<L> {
}
}
- for (watched_output, script_history) in
- sync_state.watched_outputs.values().zip(output_results)
- {
+ let watched_outpoints =
+ sync_state.watched_outputs.iter().flat_map(|(outpoint, script_pubkeys)| {
+ script_pubkeys.iter().map(move |_| outpoint)
+ });
+ for (watched_outpoint, script_history) in watched_outpoints.zip(output_results) {
for possible_output_spend in script_history {
if possible_output_spend.height <= 0 {
// Skip if it's a an unconfirmed entry.
continue;
}
let txid = possible_output_spend.tx_hash;
- if txid == watched_output.outpoint.txid {
+ if txid == watched_outpoint.txid {
// The transaction creating the watched output cannot spend it.
continue;
}
@@ -391,9 +396,7 @@ impl<L: Logger> ElectrumSyncClient<L> {
let mut is_spend = false;
for txin in &tx.input {
- let watched_outpoint =
- watched_output.outpoint.into_bitcoin_outpoint();
- if txin.previous_output == watched_outpoint {
+ if txin.previous_output == *watched_outpoint {
is_spend = true;
break;
}
@@ -553,7 +556,11 @@ impl<L: Logger> Filter for ElectrumSyncClient<L> {
fn register_output(&self, output: WatchedOutput) {
let mut locked_queue = self.queue.lock().unwrap();
- locked_queue.outputs.insert(output.outpoint.into_bitcoin_outpoint(), output);
+ locked_queue
+ .outputs
+ .entry(output.outpoint.into_bitcoin_outpoint())
+ .or_default()
+ .insert(output.script_pubkey);
}
}
### lightning-transaction-sync/src/esplora.rs
@@ -337,24 +337,21 @@ impl<L: Logger> EsploraSyncClient<L> {
// Check the status of registered outputs, and whether their spending transactions
// are confirmed.
- let watched_outputs = sync_state.watched_outputs.values();
+ let watched_outputs = sync_state.watched_outputs.keys();
#[cfg(not(feature = "async-interface"))]
- for output in watched_outputs {
- let output_status = self
- .client
- .get_output_status(&output.outpoint.txid, output.outpoint.index as u64)?;
+ for outpoint in watched_outputs {
+ let output_status =
+ self.client.get_output_status(&outpoint.txid, outpoint.vout as u64)?;
if let Some(confirmed_tx) = self.process_output_status(output_status, &confirmed_txs)? {
confirmed_txs.push(confirmed_tx);
}
}
#[cfg(feature = "async-interface")]
{
let confirmed_txs_ref = &confirmed_txs;
- let spending_txs = futures::stream::iter(watched_outputs.map(|output| async move {
- let output_status = self
- .client
- .get_output_status(&output.outpoint.txid, output.outpoint.index as u64)
- .await?;
+ let spending_txs = futures::stream::iter(watched_outputs.map(|outpoint| async move {
+ let output_status =
+ self.client.get_output_status(&outpoint.txid, outpoint.vout as u64).await?;
self.process_output_status(output_status, confirmed_txs_ref).await
}))
.buffer_unordered(self.max_concurrency)
@@ -591,6 +588,52 @@ impl<L: Logger> Filter for EsploraSyncClient<L> {
fn register_output(&self, output: WatchedOutput) {
let mut locked_queue = self.queue.lock().unwrap();
- locked_queue.outputs.insert(output.outpoint.into_bitcoin_outpoint(), output);
+ locked_queue
+ .outputs
+ .entry(output.outpoint.into_bitcoin_outpoint())
+ .or_default()
+ .insert(output.script_pubkey);
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use bitcoin::hashes::Hash;
+ use bitcoin::{BlockHash, ScriptBuf, Txid};
+ use lightning::chain::transaction::OutPoint as LnOutPoint;
+ use lightning::util::test_utils::TestLogger;
+
+ #[test]
+ fn register_output_dedups_on_script_pubkey() {
+ let logger = TestLogger::new();
+ let tx_sync = EsploraSyncClient::new("http://localhost:3000".to_string(), &logger);
+
+ let outpoint = LnOutPoint { txid: Txid::all_zeros(), index: 0 };
+ let script_pubkey = ScriptBuf::from(vec![0x51]);
+ let other_script_pubkey = ScriptBuf::from(vec![0x52]);
+
+ // The same output may be registered with varying `block_hash`es, e.g., on restart.
+ tx_sync.register_output(WatchedOutput {
+ block_hash: None,
+ outpoint,
+ script_pubkey: script_pubkey.clone(),
+ });
+ tx_sync.register_output(WatchedOutput {
+ block_hash: Some(BlockHash::all_zeros()),
+ outpoint,
+ script_pubkey: script_pubkey.clone(),
+ });
+ tx_sync.register_output(WatchedOutput {
+ block_hash: None,
+ outpoint,
+ script_pubkey: other_script_pubkey.clone(),
+ });
+
+ let queue = tx_sync.queue.lock().unwrap();
+ let scripts = &queue.outputs[&outpoint.into_bitcoin_outpoint()];
+ assert_eq!(scripts.len(), 2);
+ assert!(scripts.contains(&script_pubkey));
+ assert!(scripts.contains(&other_script_pubkey));
}
}
### lightning-transaction-sync/tests/integration_tests.rs
@@ -404,6 +404,81 @@ fn test_electrum_syncs() {
test_syncing!(tx_sync, confirmable, bitcoind, electrsd);
}
+#[cfg(feature = "_electrum")]
+fn do_test_conflicting_output_watches(sync_between_registrations: bool, bogus_first: bool) {
+ let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+ generate_blocks_and_wait(&bitcoind, &electrsd, 101);
+ let logger = TestLogger::new();
+ let tx_sync =
+ ElectrumSyncClient::new(format!("tcp://{}", electrsd.electrum_url), &logger).unwrap();
+ let confirmable = TestConfirmable::new();
+
+ let address = bitcoind.client.new_address().unwrap();
+ let spend_txid = bitcoind
+ .client
+ .send_to_address(&address, Amount::from_sat(5000))
+ .unwrap()
+ .0
+ .parse()
+ .unwrap();
+ let spend_tx = bitcoind.client.get_transaction(spend_txid).unwrap().into_model().unwrap().tx;
+ let prev_outpoint = spend_tx.input[0].previous_output;
+ let prev_tx =
+ bitcoind.client.get_transaction(prev_outpoint.txid).unwrap().into_model().unwrap().tx;
+ let output = WatchedOutput {
+ block_hash: None,
+ outpoint: OutPoint { txid: prev_outpoint.txid, index: prev_outpoint.vout as u16 },
+ script_pubkey: prev_tx.output[prev_outpoint.vout as usize].script_pubkey.clone(),
+ };
+ let bogus_output = WatchedOutput {
+ script_pubkey: bitcoind.client.new_address().unwrap().script_pubkey(),
+ ..output.clone()
+ };
+ let outputs =
+ if bogus_first { [bogus_output.clone(), output] } else { [output, bogus_output.clone()] };
+ for output in outputs {
+ // Repeated registrations must not prevent discovery of a spend, regardless of order.
+ tx_sync.register_output(output.clone());
+ tx_sync.register_output(output);
+ if sync_between_registrations {
+ tx_sync.sync(vec![&confirmable]).unwrap();
+ assert!(!confirmable.confirmed_txs.lock().unwrap().contains_key(&spend_txid));
+ }
+ }
+ // A conflicting funding registration also watches the transaction creating the output.
+ tx_sync.register_tx(&prev_outpoint.txid, &bogus_output.script_pubkey);
+ generate_blocks_and_wait(&bitcoind, &electrsd, 1);
+ tx_sync.sync(vec![&confirmable]).unwrap();
+ assert!(
+ confirmable.confirmed_txs.lock().unwrap().contains_key(&spend_txid),
+ "a conflicting registration hid the watched output's spend"
+ );
+
+ // Retain the watch if a confirmed spend is reorganized out and later reconfirmed.
+ let block_hash = bitcoind.client.get_best_block_hash().unwrap().into_model().unwrap().0;
+ bitcoind.client.invalidate_block(block_hash).unwrap();
+ generate_blocks_and_wait(&bitcoind, &electrsd, 2);
+ tx_sync.sync(vec![&confirmable]).unwrap();
+ assert!(confirmable.confirmed_txs.lock().unwrap().contains_key(&spend_txid));
+ assert!(confirmable.events.lock().unwrap().iter().any(|event| {
+ matches!(event, TestConfirmableEvent::Unconfirmed(txid) if *txid == spend_txid)
+ }));
+}
+
+#[test]
+#[cfg(feature = "_electrum")]
+fn test_conflicting_output_watches_same_sync() {
+ do_test_conflicting_output_watches(false, false);
+ do_test_conflicting_output_watches(false, true);
+}
+
+#[test]
+#[cfg(feature = "_electrum")]
+fn test_conflicting_output_watches_separate_syncs() {
+ do_test_conflicting_output_watches(true, false);
+ do_test_conflicting_output_watches(true, true);
+}
+
#[test]
#[cfg(feature = "_electrum")]
fn test_electrum_avoids_creator_transaction_downloads() {Why this scored 61/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.