From 70f0e7b9f0ce6f92cec712cfd5606c7ba7bf945c Mon Sep 17 00:00:00 2001 From: Oladapo Oyindamola <111582215+0xZaddyy@users.noreply.github.com> Date: Sat, 25 Apr 2026 00:39:14 +0100 Subject: [PATCH 1/3] add `OP_RETURN` filtering to change identification heuristics `OP_RETURN` outputs cannot be spent, so they should never be considered as change outputs in transaction analysis. --- .../heuristics/src/change_identification.rs | 142 ++++++++++++++++-- src/crates/primitives/src/test_utils/mod.rs | 11 ++ .../primitives/src/traits/abstract_types.rs | 4 + 3 files changed, 148 insertions(+), 9 deletions(-) diff --git a/src/crates/heuristics/src/change_identification.rs b/src/crates/heuristics/src/change_identification.rs index 5b62333..6c0bc3c 100644 --- a/src/crates/heuristics/src/change_identification.rs +++ b/src/crates/heuristics/src/change_identification.rs @@ -1,5 +1,6 @@ use tx_indexer_primitives::{ handle::TxHandle, + output_type::OutputType, traits::abstract_types::{HasNLockTime, HasScriptPubkey, OutputCount, TxConstituent}, }; @@ -13,7 +14,15 @@ pub struct NaiveChangeIdentificationHueristic; impl NaiveChangeIdentificationHueristic { /// Check if a txout is change based on its containing transaction. - pub fn is_change(txout: impl TxConstituent) -> TxOutChangeAnnotation { + /// OP_RETURN outputs are never considered change. + pub fn is_change(txout: T) -> TxOutChangeAnnotation + where + T: TxConstituent + HasScriptPubkey, + { + if txout.is_op_return() { + return TxOutChangeAnnotation::NotChange; + } + let tx = txout.containing_tx(); if tx.output_count() > 0 && txout.vout() == tx.output_count() - 1 { TxOutChangeAnnotation::Change @@ -26,10 +35,16 @@ impl NaiveChangeIdentificationHueristic { pub struct NLockTimeChangeIdentification; impl NLockTimeChangeIdentification { - pub fn is_change( - tx_out: impl TxConstituent, - spending_tx: impl HasNLockTime, - ) -> TxOutChangeAnnotation { + /// Check if a txout is change based on nLockTime comparison. + /// OP_RETURN outputs are never considered change. + pub fn is_change(tx_out: T, spending_tx: impl HasNLockTime) -> TxOutChangeAnnotation + where + T: TxConstituent + HasScriptPubkey, + { + if tx_out.is_op_return() { + return TxOutChangeAnnotation::NotChange; + } + let containing_tx_n_locktime = tx_out.containing_tx().n_locktime(); let child_tx_n_locktime = spending_tx.n_locktime(); if containing_tx_n_locktime == 0 && child_tx_n_locktime == 0 { @@ -55,9 +70,16 @@ impl ScriptTypesMatchingChangeIdentification { /// This applies the address-type heuristic conservatively: mixed input /// types, unresolved prevouts, or multiple matching outputs are all treated /// as inconclusive and return `NotChange`. - pub fn is_change<'a>( - tx_out: impl TxConstituent>, - ) -> TxOutChangeAnnotation { + /// + /// OP_RETURN outputs are never considered change. + pub fn is_change<'a, T>(tx_out: T) -> TxOutChangeAnnotation + where + T: TxConstituent> + HasScriptPubkey, + { + if tx_out.is_op_return() { + return TxOutChangeAnnotation::NotChange; + } + let tx = tx_out.containing_tx(); let mut input_types = tx.inputs().map(|input| input.output_type()); @@ -77,7 +99,11 @@ impl ScriptTypesMatchingChangeIdentification { let matching_outputs: Vec = tx .outputs() .enumerate() - .filter_map(|(index, output)| (output.output_type() == input_type).then_some(index)) + .filter_map(|(index, output)| { + let out_type = output.output_type(); + // Skip OP_RETURN outputs when looking for change candidates + (out_type == input_type && out_type != OutputType::OpReturn).then_some(index) + }) .collect(); if matching_outputs.len() == 1 && matching_outputs[0] == tx_out.vout() { @@ -253,6 +279,104 @@ mod tests { ); } + #[test] + fn test_script_types_matching_excludes_op_return() { + let storage = storage_from_loose_txs(vec![ + // inputs: P2PKH + DummyTxData::new_with_outputs(vec![DummyTxOutData::new_with_script( + 100, + 0, + script_from_address("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"), + )]), + DummyTxData::new_with_outputs(vec![DummyTxOutData::new_with_script( + 150, + 0, + script_from_address("1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2"), + )]), + DummyTxData::new( + vec![ + // OP_RETURN output - should never be considered change + DummyTxOutData::new_with_script( + 0, + 0, + vec![0x6a, 0x04, 0x48, 0x65, 0x6c, 0x6c], // OP_RETURN "Hell" + ), + // P2PKH output - should be considered change since it's the only spendable P2PKH + DummyTxOutData::new_with_script( + 249, + 1, + script_from_address("1BoatSLRHtKNngkdXEeobR76b53LETtpyT"), + ), + ], + vec![TxOutId::new(TxId(1), 0), TxOutId::new(TxId(2), 0)], + 0, + ), + ]); + + let op_return_output = AnyOutId::from(TxOutId::new(TxId(3), 0)).with(&storage); + let p2pkh_output = AnyOutId::from(TxOutId::new(TxId(3), 1)).with(&storage); + + // OP_RETURN should never be classified as change + assert_eq!( + ScriptTypesMatchingChangeIdentification::is_change(op_return_output), + TxOutChangeAnnotation::NotChange + ); + + // P2PKH output should be change since it's the only spendable output matching input type + assert_eq!( + ScriptTypesMatchingChangeIdentification::is_change(p2pkh_output), + TxOutChangeAnnotation::Change + ); + } + + #[test] + fn test_all_heuristics_filter_op_return() { + // Create an OP_RETURN output to test that all heuristics filter it out + let op_return_script = vec![0x6a, 0x04, 0x48, 0x65, 0x6c, 0x6c]; // OP_RETURN "Hell" + + // Test NaiveChangeIdentificationHueristic with OP_RETURN as last output + let txout_op_return = DummyTxOut { + vout: 1, // Last output in a 2-output tx + containing_tx: DummyTxData::new( + vec![ + DummyTxOutData::new_with_script( + 100, + 0, + script_from_address("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"), + ), + DummyTxOutData::new_with_script(0, 1, op_return_script.clone()), + ], + vec![], + 0, + ), + }; + // Even though it's the last output, OP_RETURN should not be change + assert_eq!( + NaiveChangeIdentificationHueristic::is_change(txout_op_return), + TxOutChangeAnnotation::NotChange + ); + + // Test NLockTimeChangeIdentification with OP_RETURN + let tx_out_op_return = DummyTxOut { + vout: 0, + containing_tx: DummyTxData::new( + vec![DummyTxOutData::new_with_script( + 0, + 0, + op_return_script.clone(), + )], + vec![], + 1, // Non-zero locktime + ), + }; + let spending_tx = DummyTxData::new(vec![], vec![], 1); // Same locktime + // Even with matching locktimes, OP_RETURN should not be change + assert_eq!( + NLockTimeChangeIdentification::is_change(tx_out_op_return, spending_tx), + TxOutChangeAnnotation::NotChange + ); + } + #[test] fn test_script_types_matching_requires_unique_output_match() { let storage = storage_from_loose_txs(vec![ diff --git a/src/crates/primitives/src/test_utils/mod.rs b/src/crates/primitives/src/test_utils/mod.rs index b8b32cf..c2e6b4a 100644 --- a/src/crates/primitives/src/test_utils/mod.rs +++ b/src/crates/primitives/src/test_utils/mod.rs @@ -247,3 +247,14 @@ impl TxConstituent for DummyTxOut { self.vout } } + +impl HasScriptPubkey for DummyTxOut { + fn script_pubkey_bytes(&self) -> Vec { + // Get the script pubkey from the corresponding output in the containing transaction + self.containing_tx + .outputs() + .nth(self.vout) + .map(|output| output.script_pubkey_bytes()) + .unwrap_or_default() + } +} diff --git a/src/crates/primitives/src/traits/abstract_types.rs b/src/crates/primitives/src/traits/abstract_types.rs index 3e77588..8cdc6f3 100644 --- a/src/crates/primitives/src/traits/abstract_types.rs +++ b/src/crates/primitives/src/traits/abstract_types.rs @@ -92,6 +92,10 @@ pub trait HasScriptPubkey { fn output_type(&self) -> OutputType { classify_script_pubkey(&self.script_pubkey_bytes()) } + + fn is_op_return(&self) -> bool { + self.output_type() == OutputType::OpReturn + } } /// Transaction version From 486f60d8c6ad70d49aab55717aff908e6810f41e Mon Sep 17 00:00:00 2001 From: Oladapo Oyindamola <111582215+0xZaddyy@users.noreply.github.com> Date: Wed, 29 Apr 2026 00:39:27 +0100 Subject: [PATCH 2/3] enforce spendable-only outputs via SpendableTxConstituent newtype Replace per-heuristic is_op_return() checks with a type-level guarantee: single-output change heuristics now take SpendableTxConstituent, so the OP_RETURN filter happens once at the call boundary and unspendable outputs can't reach the heuristic at all. Also fixes UIH1: an OP_RETURN with value=0 was becoming the min_out and getting flagged as a change candidate. UIH1/UIH2 now filter OP_RETURN during their output iteration. Adds a regression test for the value=0 case. --- src/crates/heuristics/src/ast/change.rs | 25 +-- src/crates/heuristics/src/ast/uih.rs | 45 +++++- .../heuristics/src/change_identification.rs | 147 ++++++++---------- src/crates/heuristics/src/uih.rs | 21 ++- src/crates/primitives/src/handle.rs | 34 ++++ 5 files changed, 172 insertions(+), 100 deletions(-) diff --git a/src/crates/heuristics/src/ast/change.rs b/src/crates/heuristics/src/ast/change.rs index 1a5366e..fba8f05 100644 --- a/src/crates/heuristics/src/ast/change.rs +++ b/src/crates/heuristics/src/ast/change.rs @@ -9,11 +9,12 @@ use tx_indexer_pipeline::{ }; use tx_indexer_primitives::{ AbstractTxIn, + handle::SpendableTxConstituent, unified::{AnyOutId, AnyTxId}, }; use crate::change_identification::{ - NLockTimeChangeIdentification, NaiveChangeIdentificationHueristic, TxOutChangeAnnotation, + NLockTimeChangeIdentification, NaiveChangeIdentificationHeuristic, TxOutChangeAnnotation, }; /// Node that identifies change outputs in transactions. @@ -44,10 +45,13 @@ impl Node for ChangeIdentificationNode { for output_id in txouts.iter() { let output = output_id.with(ctx.unified_storage()); - let is_change = matches!( - NaiveChangeIdentificationHueristic::is_change(output), - TxOutChangeAnnotation::Change - ); + let is_change = match SpendableTxConstituent::try_new(output) { + Ok(spendable) => matches!( + NaiveChangeIdentificationHeuristic::is_change(spendable), + TxOutChangeAnnotation::Change + ), + Err(_) => false, // OP_RETURN outputs cannot be change + }; result.insert(*output_id, is_change); } @@ -114,10 +118,13 @@ impl Node for FingerPrintChangeIdentificationNode { let is_change = match output.spender_txin() { Some(spending_txin) => { let spending_tx = spending_txin.containing_tx(); - matches!( - NLockTimeChangeIdentification::is_change(output, spending_tx), - TxOutChangeAnnotation::Change - ) + match SpendableTxConstituent::try_new(output) { + Ok(spendable) => matches!( + NLockTimeChangeIdentification::is_change(spendable, spending_tx), + TxOutChangeAnnotation::Change + ), + Err(_) => false, // OP_RETURN outputs cannot be change + } } None => false, // Unspent output: not change by fingerprint }; diff --git a/src/crates/heuristics/src/ast/uih.rs b/src/crates/heuristics/src/ast/uih.rs index 8a000f7..be3a2cb 100644 --- a/src/crates/heuristics/src/ast/uih.rs +++ b/src/crates/heuristics/src/ast/uih.rs @@ -12,7 +12,10 @@ use tx_indexer_pipeline::{ node::{Node, NodeId}, value::{TxMask, TxOutSet, TxSet}, }; -use tx_indexer_primitives::unified::{AnyOutId, AnyTxId}; +use tx_indexer_primitives::{ + traits::abstract_types::HasScriptPubkey, + unified::{AnyOutId, AnyTxId}, +}; use crate::uih::UnnecessaryInputHeuristic; @@ -45,7 +48,11 @@ impl Node for UnnecessaryInputHeuristic1Node { for tx_id in &tx_ids { let tx = tx_id.with(ctx.unified_storage()); - let outputs: Vec<_> = tx.outputs().map(|o| (o.id(), o.value())).collect(); + let outputs: Vec<_> = tx + .outputs() + .filter(|o| !o.is_op_return()) + .map(|o| (o.id(), o.value())) + .collect(); if outputs.is_empty() { continue; } @@ -139,7 +146,7 @@ mod tests { use tx_indexer_primitives::{ UnifiedStorage, loose::{LooseIndexBuilder, TxId, TxOutId}, - test_utils::DummyTxData, + test_utils::{DummyTxData, DummyTxOutData}, traits::abstract_types::AbstractTransaction, unified::{AnyOutId, AnyTxId}, }; @@ -200,6 +207,22 @@ mod tests { ] } + fn setup_uih1_op_return_value_zero_fixture() -> Vec> + { + vec![ + Arc::new(DummyTxData::new_with_amounts(vec![100])), + Arc::new(DummyTxData::new_with_amounts(vec![200])), + Arc::new(DummyTxData::new( + vec![ + DummyTxOutData::new(150, 0), + DummyTxOutData::new_with_script(0, 1, vec![0x6a, 0x04, 0xde, 0xad, 0xbe, 0xef]), + ], + vec![TxOutId::new(TxId(1), 0), TxOutId::new(TxId(2), 0)], + 0, + )), + ] + } + fn setup_uih2_no_unnecessary_fixture() -> Vec> { vec![ Arc::new(DummyTxData::new_with_amounts(vec![100])), @@ -273,6 +296,22 @@ mod tests { ); } + #[test] + fn test_uih1_ignores_op_return() { + let all_txs = setup_uih1_op_return_value_zero_fixture(); + let ctx = Arc::new(PipelineContext::new()); + let mut engine = engine_with_loose(ctx.clone(), all_txs); + + let source = AllLooseTxs::new(&ctx); + let uih1 = UnnecessaryInputHeuristic1::new(source.txs()); + let result = engine.eval(&uih1); + + assert!( + result.is_empty(), + "UIH1 must not classify an OP_RETURN value=0 as a change candidate" + ); + } + #[test] fn test_uih1_tie_smallest_outputs() { let all_txs = setup_uih1_tie_fixture(); diff --git a/src/crates/heuristics/src/change_identification.rs b/src/crates/heuristics/src/change_identification.rs index 6c0bc3c..255761d 100644 --- a/src/crates/heuristics/src/change_identification.rs +++ b/src/crates/heuristics/src/change_identification.rs @@ -1,6 +1,5 @@ use tx_indexer_primitives::{ - handle::TxHandle, - output_type::OutputType, + handle::{SpendableTxConstituent, TxHandle}, traits::abstract_types::{HasNLockTime, HasScriptPubkey, OutputCount, TxConstituent}, }; @@ -10,19 +9,15 @@ pub enum TxOutChangeAnnotation { NotChange, } -pub struct NaiveChangeIdentificationHueristic; +pub struct NaiveChangeIdentificationHeuristic; -impl NaiveChangeIdentificationHueristic { +impl NaiveChangeIdentificationHeuristic { /// Check if a txout is change based on its containing transaction. - /// OP_RETURN outputs are never considered change. - pub fn is_change(txout: T) -> TxOutChangeAnnotation + /// Accepts only spendable outputs; the type system rules OP_RETURN out. + pub fn is_change(txout: SpendableTxConstituent) -> TxOutChangeAnnotation where - T: TxConstituent + HasScriptPubkey, + T: TxConstituent, { - if txout.is_op_return() { - return TxOutChangeAnnotation::NotChange; - } - let tx = txout.containing_tx(); if tx.output_count() > 0 && txout.vout() == tx.output_count() - 1 { TxOutChangeAnnotation::Change @@ -36,15 +31,14 @@ pub struct NLockTimeChangeIdentification; impl NLockTimeChangeIdentification { /// Check if a txout is change based on nLockTime comparison. - /// OP_RETURN outputs are never considered change. - pub fn is_change(tx_out: T, spending_tx: impl HasNLockTime) -> TxOutChangeAnnotation + /// Accepts only spendable outputs; the type system rules OP_RETURN out. + pub fn is_change( + tx_out: SpendableTxConstituent, + spending_tx: impl HasNLockTime, + ) -> TxOutChangeAnnotation where - T: TxConstituent + HasScriptPubkey, + T: TxConstituent, { - if tx_out.is_op_return() { - return TxOutChangeAnnotation::NotChange; - } - let containing_tx_n_locktime = tx_out.containing_tx().n_locktime(); let child_tx_n_locktime = spending_tx.n_locktime(); if containing_tx_n_locktime == 0 && child_tx_n_locktime == 0 { @@ -71,15 +65,11 @@ impl ScriptTypesMatchingChangeIdentification { /// types, unresolved prevouts, or multiple matching outputs are all treated /// as inconclusive and return `NotChange`. /// - /// OP_RETURN outputs are never considered change. - pub fn is_change<'a, T>(tx_out: T) -> TxOutChangeAnnotation + /// Accepts only spendable outputs; the type system rules OP_RETURN out. + pub fn is_change<'a, T>(tx_out: SpendableTxConstituent) -> TxOutChangeAnnotation where - T: TxConstituent> + HasScriptPubkey, + T: TxConstituent>, { - if tx_out.is_op_return() { - return TxOutChangeAnnotation::NotChange; - } - let tx = tx_out.containing_tx(); let mut input_types = tx.inputs().map(|input| input.output_type()); @@ -96,17 +86,19 @@ impl ScriptTypesMatchingChangeIdentification { return TxOutChangeAnnotation::NotChange; } - let matching_outputs: Vec = tx + let mut matching = tx .outputs() - .enumerate() - .filter_map(|(index, output)| { - let out_type = output.output_type(); - // Skip OP_RETURN outputs when looking for change candidates - (out_type == input_type && out_type != OutputType::OpReturn).then_some(index) - }) - .collect(); - - if matching_outputs.len() == 1 && matching_outputs[0] == tx_out.vout() { + .filter_map(|o| SpendableTxConstituent::try_new(o).ok()) + .filter(|spendable| spendable.output_type() == input_type); + + let Some(only) = matching.next() else { + return TxOutChangeAnnotation::NotChange; + }; + if matching.next().is_some() { + return TxOutChangeAnnotation::NotChange; + } + + if only.vout() as usize == tx_out.vout() { TxOutChangeAnnotation::Change } else { TxOutChangeAnnotation::NotChange @@ -151,8 +143,9 @@ mod tests { vout: 0, containing_tx: DummyTxData::new_with_amounts(vec![100]), }; + let spendable = SpendableTxConstituent::try_new(txout).ok().unwrap(); assert_eq!( - NaiveChangeIdentificationHueristic::is_change(txout), + NaiveChangeIdentificationHeuristic::is_change(spendable), TxOutChangeAnnotation::Change ); } @@ -164,8 +157,9 @@ mod tests { containing_tx: DummyTxData::new_with_amounts(vec![100]), }; let spending_tx = DummyTxData::new_with_amounts(vec![100]); + let spendable = SpendableTxConstituent::try_new(tx_out).ok().unwrap(); assert_eq!( - NLockTimeChangeIdentification::is_change(tx_out, spending_tx), + NLockTimeChangeIdentification::is_change(spendable, spending_tx), TxOutChangeAnnotation::NotChange ); @@ -175,8 +169,9 @@ mod tests { containing_tx: DummyTxData::new(vec![DummyTxOutData::new(100, 0)], vec![], 1), }; let spending_tx = DummyTxData::new(vec![DummyTxOutData::new(100, 0)], vec![], 1); + let spendable = SpendableTxConstituent::try_new(tx_out).ok().unwrap(); assert_eq!( - NLockTimeChangeIdentification::is_change(tx_out, spending_tx), + NLockTimeChangeIdentification::is_change(spendable, spending_tx), TxOutChangeAnnotation::Change ); } @@ -221,11 +216,15 @@ mod tests { let change = AnyOutId::from(TxOutId::new(TxId(3), 1)).with(&storage); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change(payment), + ScriptTypesMatchingChangeIdentification::is_change( + SpendableTxConstituent::try_new(payment).ok().unwrap() + ), TxOutChangeAnnotation::NotChange ); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change(change), + ScriptTypesMatchingChangeIdentification::is_change( + SpendableTxConstituent::try_new(change).ok().unwrap() + ), TxOutChangeAnnotation::Change ); } @@ -270,11 +269,15 @@ mod tests { let change = AnyOutId::from(TxOutId::new(TxId(3), 1)).with(&storage); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change(payment), + ScriptTypesMatchingChangeIdentification::is_change( + SpendableTxConstituent::try_new(payment).ok().unwrap() + ), TxOutChangeAnnotation::NotChange ); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change(change), + ScriptTypesMatchingChangeIdentification::is_change( + SpendableTxConstituent::try_new(change).ok().unwrap() + ), TxOutChangeAnnotation::NotChange ); } @@ -301,7 +304,7 @@ mod tests { 0, vec![0x6a, 0x04, 0x48, 0x65, 0x6c, 0x6c], // OP_RETURN "Hell" ), - // P2PKH output - should be considered change since it's the only spendable P2PKH + // P2PKH output - the only spendable P2PKH, so it's change DummyTxOutData::new_with_script( 249, 1, @@ -316,27 +319,25 @@ mod tests { let op_return_output = AnyOutId::from(TxOutId::new(TxId(3), 0)).with(&storage); let p2pkh_output = AnyOutId::from(TxOutId::new(TxId(3), 1)).with(&storage); - // OP_RETURN should never be classified as change - assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change(op_return_output), - TxOutChangeAnnotation::NotChange - ); + // OP_RETURN cannot be wrapped in SpendableTxConstituent -- type system rejects it + assert!(SpendableTxConstituent::try_new(op_return_output).is_err()); - // P2PKH output should be change since it's the only spendable output matching input type + // P2PKH output is change since it's the only spendable output matching input type assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change(p2pkh_output), + ScriptTypesMatchingChangeIdentification::is_change( + SpendableTxConstituent::try_new(p2pkh_output).ok().unwrap() + ), TxOutChangeAnnotation::Change ); } #[test] - fn test_all_heuristics_filter_op_return() { - // Create an OP_RETURN output to test that all heuristics filter it out + fn test_op_return_cannot_be_wrapped() { + // The type system enforces OP_RETURN exclusion at the wrapper boundary, + // so heuristics never have to check for it themselves. let op_return_script = vec![0x6a, 0x04, 0x48, 0x65, 0x6c, 0x6c]; // OP_RETURN "Hell" - - // Test NaiveChangeIdentificationHueristic with OP_RETURN as last output let txout_op_return = DummyTxOut { - vout: 1, // Last output in a 2-output tx + vout: 1, containing_tx: DummyTxData::new( vec![ DummyTxOutData::new_with_script( @@ -344,37 +345,13 @@ mod tests { 0, script_from_address("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"), ), - DummyTxOutData::new_with_script(0, 1, op_return_script.clone()), + DummyTxOutData::new_with_script(0, 1, op_return_script), ], vec![], 0, ), }; - // Even though it's the last output, OP_RETURN should not be change - assert_eq!( - NaiveChangeIdentificationHueristic::is_change(txout_op_return), - TxOutChangeAnnotation::NotChange - ); - - // Test NLockTimeChangeIdentification with OP_RETURN - let tx_out_op_return = DummyTxOut { - vout: 0, - containing_tx: DummyTxData::new( - vec![DummyTxOutData::new_with_script( - 0, - 0, - op_return_script.clone(), - )], - vec![], - 1, // Non-zero locktime - ), - }; - let spending_tx = DummyTxData::new(vec![], vec![], 1); // Same locktime - // Even with matching locktimes, OP_RETURN should not be change - assert_eq!( - NLockTimeChangeIdentification::is_change(tx_out_op_return, spending_tx), - TxOutChangeAnnotation::NotChange - ); + assert!(SpendableTxConstituent::try_new(txout_op_return).is_err()); } #[test] @@ -414,11 +391,15 @@ mod tests { let output1 = AnyOutId::from(TxOutId::new(TxId(3), 1)).with(&storage); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change(output0), + ScriptTypesMatchingChangeIdentification::is_change( + SpendableTxConstituent::try_new(output0).ok().unwrap() + ), TxOutChangeAnnotation::NotChange ); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change(output1), + ScriptTypesMatchingChangeIdentification::is_change( + SpendableTxConstituent::try_new(output1).ok().unwrap() + ), TxOutChangeAnnotation::NotChange ); } diff --git a/src/crates/heuristics/src/uih.rs b/src/crates/heuristics/src/uih.rs index 46222a4..cb758c1 100644 --- a/src/crates/heuristics/src/uih.rs +++ b/src/crates/heuristics/src/uih.rs @@ -1,17 +1,24 @@ use bitcoin::Amount; use tx_indexer_primitives::traits::abstract_types::{ - EnumerateInputValueInArbitraryOrder, EnumerateOutputValueInArbitraryOrder, + AbstractTransaction, EnumerateInputValueInArbitraryOrder, }; pub struct UnnecessaryInputHeuristic; impl UnnecessaryInputHeuristic { + /// Minimum output value among spendable outputs, when it is less than the + /// minimum input value. OP_RETURN outputs are excluded since they cannot be + /// spent and including them (often value=0) would always trip UIH1. pub fn uih1_min_output_value(tx: &T) -> Option where - T: EnumerateInputValueInArbitraryOrder + EnumerateOutputValueInArbitraryOrder, + T: EnumerateInputValueInArbitraryOrder + AbstractTransaction, { let input_values: Vec = tx.input_values().collect(); - let output_values: Vec = tx.output_values().collect(); + let output_values: Vec = tx + .outputs() + .filter(|o| !o.is_op_return()) + .map(|o| o.value()) + .collect(); if input_values.is_empty() || output_values.is_empty() { return None; @@ -37,10 +44,14 @@ impl UnnecessaryInputHeuristic { pub fn is_uih2(tx: &T) -> bool where - T: EnumerateInputValueInArbitraryOrder + EnumerateOutputValueInArbitraryOrder, + T: EnumerateInputValueInArbitraryOrder + AbstractTransaction, { let input_values: Vec = tx.input_values().collect(); - let output_values: Vec = tx.output_values().collect(); + let output_values: Vec = tx + .outputs() + .filter(|o| !o.is_op_return()) + .map(|o| o.value()) + .collect(); if input_values.len() < 2 || output_values.is_empty() { return false; diff --git a/src/crates/primitives/src/handle.rs b/src/crates/primitives/src/handle.rs index 3a90d43..9794eb3 100644 --- a/src/crates/primitives/src/handle.rs +++ b/src/crates/primitives/src/handle.rs @@ -311,3 +311,37 @@ impl<'a> TxConstituent for TxOutHandle<'a> { self.vout() as usize } } + +/// Wrapper guaranteeing the inner value is a spendable output (not OP_RETURN). +/// +/// Construct via [`SpendableTxConstituent::try_new`]: `Ok` for spendable outputs, +/// `Err` returns the original value back so callers can handle the unspendable +/// case explicitly. Heuristics that consume `SpendableTxConstituent` no +/// longer need their own OP_RETURN check — the type system enforces it at the +/// call boundary. +pub struct SpendableTxConstituent(T); + +impl SpendableTxConstituent { + /// Wraps `value` if it is spendable; returns it back as `Err` if OP_RETURN. + pub fn try_new(value: T) -> Result { + if value.is_op_return() { + Err(value) + } else { + Ok(Self(value)) + } + } +} + +impl SpendableTxConstituent { + pub fn into_inner(self) -> T { + self.0 + } +} + +impl std::ops::Deref for SpendableTxConstituent { + type Target = T; + + fn deref(&self) -> &T { + &self.0 + } +} From f88d27ff8b6086d9d96cb28b47e202c73b37a269 Mon Sep 17 00:00:00 2001 From: Oladapo Oyindamola <111582215+0xZaddyy@users.noreply.github.com> Date: Sat, 2 May 2026 08:20:44 +0100 Subject: [PATCH 3/3] generalize spendability check via `is_spendable()` trait method --- src/crates/heuristics/src/ast/uih.rs | 34 +++++++-- .../heuristics/src/change_identification.rs | 70 +++++++------------ src/crates/heuristics/src/uih.rs | 69 +++--------------- src/crates/primitives/src/handle.rs | 28 ++++++-- src/crates/primitives/src/test_utils/mod.rs | 24 +++++++ .../primitives/src/traits/abstract_types.rs | 5 ++ 6 files changed, 113 insertions(+), 117 deletions(-) diff --git a/src/crates/heuristics/src/ast/uih.rs b/src/crates/heuristics/src/ast/uih.rs index be3a2cb..34659eb 100644 --- a/src/crates/heuristics/src/ast/uih.rs +++ b/src/crates/heuristics/src/ast/uih.rs @@ -6,6 +6,7 @@ use std::collections::HashSet; +use bitcoin::Amount; use tx_indexer_pipeline::{ engine::EvalContext, expr::Expr, @@ -13,7 +14,7 @@ use tx_indexer_pipeline::{ value::{TxMask, TxOutSet, TxSet}, }; use tx_indexer_primitives::{ - traits::abstract_types::HasScriptPubkey, + traits::abstract_types::{EnumerateInputValueInArbitraryOrder, HasScriptPubkey}, unified::{AnyOutId, AnyTxId}, }; @@ -50,14 +51,18 @@ impl Node for UnnecessaryInputHeuristic1Node { let outputs: Vec<_> = tx .outputs() - .filter(|o| !o.is_op_return()) + .filter(|o| o.is_spendable()) .map(|o| (o.id(), o.value())) .collect(); - if outputs.is_empty() { + let Some(min_out) = outputs.iter().map(|(_, v)| *v).min() else { continue; - } + }; + let Some(min_in) = tx.input_values().min() else { + continue; + }; - if let Some(min_out) = UnnecessaryInputHeuristic::uih1_min_output_value(&tx) { + if let Some(min_out) = UnnecessaryInputHeuristic::uih1_min_output_value(min_in, min_out) + { for (out_id, v) in &outputs { if *v == min_out { result.insert(*out_id); @@ -115,7 +120,24 @@ impl Node for UnnecessaryInputHeuristic2Node { for tx_id in &tx_ids { let tx = tx_id.with(ctx.unified_storage()); - result.insert(*tx_id, UnnecessaryInputHeuristic::is_uih2(&tx)); + let input_values: Vec = tx.input_values().collect(); + let output_values: Vec = tx + .outputs() + .filter(|o| o.is_spendable()) + .map(|o| o.value()) + .collect(); + + let flagged = if input_values.len() < 2 || output_values.is_empty() { + false + } else { + let sum_in = input_values.iter().copied().sum(); + let min_in = input_values.iter().copied().min().expect("len >= 2"); + let sum_out = output_values.iter().copied().sum(); + let min_out = output_values.iter().copied().min().expect("non-empty"); + UnnecessaryInputHeuristic::is_uih2(sum_in, min_in, sum_out, min_out) + }; + + result.insert(*tx_id, flagged); } result diff --git a/src/crates/heuristics/src/change_identification.rs b/src/crates/heuristics/src/change_identification.rs index 255761d..5e44b44 100644 --- a/src/crates/heuristics/src/change_identification.rs +++ b/src/crates/heuristics/src/change_identification.rs @@ -86,19 +86,18 @@ impl ScriptTypesMatchingChangeIdentification { return TxOutChangeAnnotation::NotChange; } - let mut matching = tx + let matching_indices: Vec = tx .outputs() - .filter_map(|o| SpendableTxConstituent::try_new(o).ok()) - .filter(|spendable| spendable.output_type() == input_type); + .enumerate() + .filter_map(|(index, output)| (output.output_type() == input_type).then_some(index)) + .collect(); - let Some(only) = matching.next() else { - return TxOutChangeAnnotation::NotChange; - }; - if matching.next().is_some() { + // There must be exactly one matching output for it to be considered change + if matching_indices.len() != 1 { return TxOutChangeAnnotation::NotChange; } - if only.vout() as usize == tx_out.vout() { + if matching_indices[0] == tx_out.vout() { TxOutChangeAnnotation::Change } else { TxOutChangeAnnotation::NotChange @@ -114,7 +113,7 @@ mod tests { UnifiedStorage, loose::LooseIndexBuilder, loose::{TxId, TxOutId}, - test_utils::{DummyTxData, DummyTxOut, DummyTxOutData}, + test_utils::{DUMMY_UNSPENDABLE_SCRIPT, DummyTxData, DummyTxOut, DummyTxOutData}, unified::AnyOutId, }; @@ -143,7 +142,7 @@ mod tests { vout: 0, containing_tx: DummyTxData::new_with_amounts(vec![100]), }; - let spendable = SpendableTxConstituent::try_new(txout).ok().unwrap(); + let spendable: SpendableTxConstituent<_> = txout.try_into().unwrap(); assert_eq!( NaiveChangeIdentificationHeuristic::is_change(spendable), TxOutChangeAnnotation::Change @@ -157,7 +156,7 @@ mod tests { containing_tx: DummyTxData::new_with_amounts(vec![100]), }; let spending_tx = DummyTxData::new_with_amounts(vec![100]); - let spendable = SpendableTxConstituent::try_new(tx_out).ok().unwrap(); + let spendable: SpendableTxConstituent<_> = tx_out.try_into().unwrap(); assert_eq!( NLockTimeChangeIdentification::is_change(spendable, spending_tx), TxOutChangeAnnotation::NotChange @@ -169,7 +168,7 @@ mod tests { containing_tx: DummyTxData::new(vec![DummyTxOutData::new(100, 0)], vec![], 1), }; let spending_tx = DummyTxData::new(vec![DummyTxOutData::new(100, 0)], vec![], 1); - let spendable = SpendableTxConstituent::try_new(tx_out).ok().unwrap(); + let spendable: SpendableTxConstituent<_> = tx_out.try_into().unwrap(); assert_eq!( NLockTimeChangeIdentification::is_change(spendable, spending_tx), TxOutChangeAnnotation::Change @@ -216,15 +215,11 @@ mod tests { let change = AnyOutId::from(TxOutId::new(TxId(3), 1)).with(&storage); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change( - SpendableTxConstituent::try_new(payment).ok().unwrap() - ), + ScriptTypesMatchingChangeIdentification::is_change(payment.try_into().unwrap()), TxOutChangeAnnotation::NotChange ); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change( - SpendableTxConstituent::try_new(change).ok().unwrap() - ), + ScriptTypesMatchingChangeIdentification::is_change(change.try_into().unwrap()), TxOutChangeAnnotation::Change ); } @@ -269,15 +264,11 @@ mod tests { let change = AnyOutId::from(TxOutId::new(TxId(3), 1)).with(&storage); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change( - SpendableTxConstituent::try_new(payment).ok().unwrap() - ), + ScriptTypesMatchingChangeIdentification::is_change(payment.try_into().unwrap()), TxOutChangeAnnotation::NotChange ); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change( - SpendableTxConstituent::try_new(change).ok().unwrap() - ), + ScriptTypesMatchingChangeIdentification::is_change(change.try_into().unwrap()), TxOutChangeAnnotation::NotChange ); } @@ -299,11 +290,7 @@ mod tests { DummyTxData::new( vec![ // OP_RETURN output - should never be considered change - DummyTxOutData::new_with_script( - 0, - 0, - vec![0x6a, 0x04, 0x48, 0x65, 0x6c, 0x6c], // OP_RETURN "Hell" - ), + DummyTxOutData::new_with_script(0, 0, vec![0x6a, 0x04, 0xde, 0xad, 0xbe, 0xef]), // P2PKH output - the only spendable P2PKH, so it's change DummyTxOutData::new_with_script( 249, @@ -320,23 +307,20 @@ mod tests { let p2pkh_output = AnyOutId::from(TxOutId::new(TxId(3), 1)).with(&storage); // OP_RETURN cannot be wrapped in SpendableTxConstituent -- type system rejects it - assert!(SpendableTxConstituent::try_new(op_return_output).is_err()); + assert!(TryInto::>::try_into(op_return_output).is_err()); // P2PKH output is change since it's the only spendable output matching input type assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change( - SpendableTxConstituent::try_new(p2pkh_output).ok().unwrap() - ), + ScriptTypesMatchingChangeIdentification::is_change(p2pkh_output.try_into().unwrap()), TxOutChangeAnnotation::Change ); } #[test] - fn test_op_return_cannot_be_wrapped() { - // The type system enforces OP_RETURN exclusion at the wrapper boundary, + fn test_unspendable_cannot_be_wrapped() { + // The type system enforces unspendable output exclusion at the wrapper boundary, // so heuristics never have to check for it themselves. - let op_return_script = vec![0x6a, 0x04, 0x48, 0x65, 0x6c, 0x6c]; // OP_RETURN "Hell" - let txout_op_return = DummyTxOut { + let txout_unspendable = DummyTxOut { vout: 1, containing_tx: DummyTxData::new( vec![ @@ -345,13 +329,13 @@ mod tests { 0, script_from_address("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"), ), - DummyTxOutData::new_with_script(0, 1, op_return_script), + DummyTxOutData::new_with_script(0, 1, DUMMY_UNSPENDABLE_SCRIPT), ], vec![], 0, ), }; - assert!(SpendableTxConstituent::try_new(txout_op_return).is_err()); + assert!(TryInto::>::try_into(txout_unspendable).is_err()); } #[test] @@ -391,15 +375,11 @@ mod tests { let output1 = AnyOutId::from(TxOutId::new(TxId(3), 1)).with(&storage); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change( - SpendableTxConstituent::try_new(output0).ok().unwrap() - ), + ScriptTypesMatchingChangeIdentification::is_change(output0.try_into().unwrap()), TxOutChangeAnnotation::NotChange ); assert_eq!( - ScriptTypesMatchingChangeIdentification::is_change( - SpendableTxConstituent::try_new(output1).ok().unwrap() - ), + ScriptTypesMatchingChangeIdentification::is_change(output1.try_into().unwrap()), TxOutChangeAnnotation::NotChange ); } diff --git a/src/crates/heuristics/src/uih.rs b/src/crates/heuristics/src/uih.rs index cb758c1..ddb60cc 100644 --- a/src/crates/heuristics/src/uih.rs +++ b/src/crates/heuristics/src/uih.rs @@ -1,69 +1,20 @@ use bitcoin::Amount; -use tx_indexer_primitives::traits::abstract_types::{ - AbstractTransaction, EnumerateInputValueInArbitraryOrder, -}; pub struct UnnecessaryInputHeuristic; impl UnnecessaryInputHeuristic { - /// Minimum output value among spendable outputs, when it is less than the - /// minimum input value. OP_RETURN outputs are excluded since they cannot be - /// spent and including them (often value=0) would always trip UIH1. - pub fn uih1_min_output_value(tx: &T) -> Option - where - T: EnumerateInputValueInArbitraryOrder + AbstractTransaction, - { - let input_values: Vec = tx.input_values().collect(); - let output_values: Vec = tx - .outputs() - .filter(|o| !o.is_op_return()) - .map(|o| o.value()) - .collect(); - - if input_values.is_empty() || output_values.is_empty() { - return None; - } - - let min_in = input_values - .iter() - .min() - .copied() - .expect("non-empty inputs"); - let min_out = output_values - .iter() - .min() - .copied() - .expect("non-empty outputs"); - - if min_out < min_in { - Some(min_out) - } else { - None - } + /// UIH1 (Optimal change): the smallest output is likely change when it is + /// strictly less than the smallest input. Returns `Some(min_out)` in that + /// case. Caller is responsible for excluding unspendable outputs from + /// `min_out` — including them (often value=0) would always trip UIH1. + pub fn uih1_min_output_value(min_in: Amount, min_out: Amount) -> Option { + (min_out < min_in).then_some(min_out) } - pub fn is_uih2(tx: &T) -> bool - where - T: EnumerateInputValueInArbitraryOrder + AbstractTransaction, - { - let input_values: Vec = tx.input_values().collect(); - let output_values: Vec = tx - .outputs() - .filter(|o| !o.is_op_return()) - .map(|o| o.value()) - .collect(); - - if input_values.len() < 2 || output_values.is_empty() { - return false; - } - - let sum_in = input_values.iter().fold(Amount::from_sat(0), |a, b| a + *b); - let min_in = input_values.iter().min().copied().expect("len >= 2"); - let sum_out = output_values - .iter() - .fold(Amount::from_sat(0), |a, b| a + *b); - let min_out = output_values.iter().min().copied().expect("non-empty"); - + /// UIH2 (Unnecessary input): the largest output could be paid without the + /// smallest input. Caller is responsible for excluding unspendable outputs + /// from the sum/min and ensuring there are at least two inputs. + pub fn is_uih2(sum_in: Amount, min_in: Amount, sum_out: Amount, min_out: Amount) -> bool { (sum_in - min_in) >= (sum_out - min_out) } } diff --git a/src/crates/primitives/src/handle.rs b/src/crates/primitives/src/handle.rs index 9794eb3..be12efa 100644 --- a/src/crates/primitives/src/handle.rs +++ b/src/crates/primitives/src/handle.rs @@ -65,6 +65,14 @@ pub struct TxOutHandle<'a> { pub(crate) index: &'a dyn IndexedGraph, } +impl<'a> std::fmt::Debug for TxOutHandle<'a> { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("TxOutHandle") + .field("out_id", &self.out_id) + .finish() + } +} + impl<'a> TxOutHandle<'a> { pub fn id(&self) -> AnyOutId { self.out_id @@ -316,22 +324,28 @@ impl<'a> TxConstituent for TxOutHandle<'a> { /// /// Construct via [`SpendableTxConstituent::try_new`]: `Ok` for spendable outputs, /// `Err` returns the original value back so callers can handle the unspendable -/// case explicitly. Heuristics that consume `SpendableTxConstituent` no -/// longer need their own OP_RETURN check — the type system enforces it at the -/// call boundary. +/// case explicitly. pub struct SpendableTxConstituent(T); impl SpendableTxConstituent { - /// Wraps `value` if it is spendable; returns it back as `Err` if OP_RETURN. + /// Wraps `value` if it is spendable; returns it back as `Err` if unspendable. pub fn try_new(value: T) -> Result { - if value.is_op_return() { - Err(value) - } else { + if value.is_spendable() { Ok(Self(value)) + } else { + Err(value) } } } +impl<'a> TryFrom> for SpendableTxConstituent> { + type Error = TxOutHandle<'a>; + + fn try_from(value: TxOutHandle<'a>) -> Result { + Self::try_new(value) + } +} + impl SpendableTxConstituent { pub fn into_inner(self) -> T { self.0 diff --git a/src/crates/primitives/src/test_utils/mod.rs b/src/crates/primitives/src/test_utils/mod.rs index c2e6b4a..2196219 100644 --- a/src/crates/primitives/src/test_utils/mod.rs +++ b/src/crates/primitives/src/test_utils/mod.rs @@ -12,6 +12,10 @@ use crate::{ }, }; +/// Dummy unspendable script for testing - all bits set to 0xFF +/// This is used instead of real OP_RETURN scripts in tests to mark outputs as unspendable +pub const DUMMY_UNSPENDABLE_SCRIPT: &[u8] = &[0xFF, 0xFF, 0xFF, 0xFF]; + #[derive(Debug, Clone, PartialEq, Eq, Hash)] pub struct DummyTxData { outputs: Vec, @@ -116,6 +120,11 @@ impl HasScriptPubkey for DummyTxOutData { fn script_pubkey_bytes(&self) -> Vec { self.script_pubkey.clone() } + + fn is_spendable(&self) -> bool { + // Check for our dummy unspendable script or real OP_RETURN + self.script_pubkey != DUMMY_UNSPENDABLE_SCRIPT && !self.is_op_return() + } } impl AbstractTxOut for DummyTxOutData { @@ -232,6 +241,7 @@ impl From for Box { } } +#[derive(Debug)] pub struct DummyTxOut { pub vout: usize, pub containing_tx: DummyTxData, @@ -257,4 +267,18 @@ impl HasScriptPubkey for DummyTxOut { .map(|output| output.script_pubkey_bytes()) .unwrap_or_default() } + + fn is_spendable(&self) -> bool { + // Check for our dummy unspendable script or real OP_RETURN + let script = self.script_pubkey_bytes(); + script != DUMMY_UNSPENDABLE_SCRIPT && !self.is_op_return() + } +} + +impl TryFrom for crate::handle::SpendableTxConstituent { + type Error = DummyTxOut; + + fn try_from(value: DummyTxOut) -> Result { + Self::try_new(value) + } } diff --git a/src/crates/primitives/src/traits/abstract_types.rs b/src/crates/primitives/src/traits/abstract_types.rs index 8cdc6f3..e3bb206 100644 --- a/src/crates/primitives/src/traits/abstract_types.rs +++ b/src/crates/primitives/src/traits/abstract_types.rs @@ -96,6 +96,11 @@ pub trait HasScriptPubkey { fn is_op_return(&self) -> bool { self.output_type() == OutputType::OpReturn } + + /// Returns true if this output can be spent + fn is_spendable(&self) -> bool { + !self.is_op_return() + } } /// Transaction version