refactor(test): move tx_template to testenv

- move tx_template from chain to testenv
- update imports from chain/common/ to bdk_testenv
/tx_template/

Author: tvpeter

crates/chain/tests/common/mod.rs

@@ -1,8 +1,5 @@
 #![cfg(feature = "miniscript")]
 
-#[macro_use]
-mod common;
-
 use std::{collections::BTreeSet, str::FromStr, sync::Arc};
 
 use bdk_chain::{

crates/chain/tests/test_indexed_tx_graph.rs

@@ -1,7 +1,5 @@
 #![cfg(feature = "miniscript")]
 
-#[macro_use]
-mod common;
 use bdk_chain::{collections::*, BlockId, CanonicalizationParams, ConfirmationBlockTime};
 use bdk_chain::{
     local_chain::LocalChain,
@@ -10,13 +8,13 @@ use bdk_chain::{
     Anchor, ChainOracle, ChainPosition, Merge,
 };
 use bdk_testenv::{block_id, hash, utils::new_tx};
+use bdk_testenv::{init_graph, TxInTemplate, TxOutTemplate, TxTemplate};
 use bitcoin::hex::FromHex;
 use bitcoin::Witness;
 use bitcoin::{
     absolute, hashes::Hash, transaction, Amount, BlockHash, OutPoint, ScriptBuf, SignedAmount,
     Transaction, TxIn, TxOut, Txid,
 };
-use common::*;
 use core::iter;
 use rand::RngCore;
 use std::sync::Arc;

crates/chain/tests/test_tx_graph.rs

@@ -1,12 +1,9 @@
 #![cfg(feature = "miniscript")]
 
-#[macro_use]
-mod common;
-
 use bdk_chain::{local_chain::LocalChain, Balance, BlockId};
 use bdk_testenv::{block_id, hash, local_chain};
+use bdk_testenv::{init_graph, TxInTemplate, TxOutTemplate, TxTemplate};
 use bitcoin::{Amount, BlockHash, OutPoint};
-use common::*;
 use std::collections::{BTreeSet, HashSet};
 
 #[allow(dead_code)]

crates/chain/tests/test_tx_graph_conflicts.rs

@@ -19,6 +19,7 @@ workspace = true
 bdk_chain = { path = "../chain", version = "0.23.1", default-features = false }
 electrsd = { version = "0.38.0", features = [ "legacy" ], default-features = false }
 bitcoin = { version = "0.32.0", default-features = false }
+rand = { version = "0.8.0", default-features = false, features = ["std", "small_rng", "std_rng"] }
 
 [dev-dependencies]
 bdk_testenv = { path = "." }

crates/testenv/Cargo.toml

@@ -1,6 +1,8 @@
 #![cfg_attr(coverage_nightly, feature(coverage_attribute))]
 
+pub mod tx_template;
 pub mod utils;
+pub use tx_template::*;
 
 use anyhow::Context;
 use bdk_chain::bitcoin::{

crates/testenv/src/lib.rs

@@ -1,57 +1,79 @@
-#![cfg(feature = "miniscript")]
+//! Transaction templates for constructing complex transaction histories for testing purposes.
 
-use bdk_testenv::utils::DESCRIPTORS;
-use rand::distributions::{Alphanumeric, DistString};
-use std::collections::HashMap;
-
-use bdk_chain::{spk_txout::SpkTxOutIndex, tx_graph::TxGraph, Anchor, CanonicalizationParams};
+use crate::utils::DESCRIPTORS;
+use bdk_chain::{
+    miniscript::Descriptor, spk_txout::SpkTxOutIndex, tx_graph::TxGraph, Anchor,
+    CanonicalizationParams,
+};
 use bitcoin::{
     locktime::absolute::LockTime, secp256k1::Secp256k1, transaction, Amount, OutPoint, ScriptBuf,
     Sequence, Transaction, TxIn, TxOut, Txid, Witness,
 };
-use miniscript::Descriptor;
+use rand::distributions::{Alphanumeric, DistString};
+use std::collections::HashMap;
 
-/// Template for creating a transaction in `TxGraph`.
+/// Template for creating a transaction in a [`TxGraph`].
 ///
-/// The incentive for transaction templates is to create a transaction history in a simple manner to
-/// avoid having to explicitly hash previous transactions to form previous outpoints of later
-/// transactions.
+/// This is the main building block for constructing complex transaction histories
+/// for tests. It allows you to refer to previous transactions by name instead of
+/// manually managing txids and outpoints.
 #[derive(Clone, Copy, Default)]
 pub struct TxTemplate<'a, A> {
-    /// Uniquely identifies the transaction, before it can have a txid.
+    /// A unique name used to refer to this transaction in other templates.
     pub tx_name: &'a str,
+
+    /// The inputs of this transaction.
     pub inputs: &'a [TxInTemplate<'a>],
+
+    /// The outputs of this transaction.
     pub outputs: &'a [TxOutTemplate],
+
+    /// Anchors (confirmations) for this transaction.
     pub anchors: &'a [A],
+
+    /// Unix timestamp when this transaction was last seen in the mempool.
     pub last_seen: Option<u64>,
+
+    /// If `true`, this transaction will be treated as canonical regardless of
+    /// conflict resolution rules (used for testing forced canonicalization).
     pub assume_canonical: bool,
 }
 
+/// Describes how an input is created in a [`TxTemplate`].
 #[allow(dead_code)]
 pub enum TxInTemplate<'a> {
-    /// This will give a random txid and vout.
+    /// A random (bogus) previous output. Useful when the actual prevout doesn't matter.
     Bogus,
 
-    /// This is used for coinbase transactions because they do not have previous outputs.
+    /// A coinbase input (no previous output).
     Coinbase,
 
-    /// Contains the `tx_name` and `vout` that we are spending. The rule is that we must only spend
-    /// from tx of a previous `TxTemplate`.
+    /// Spends from a previous transaction defined in the template list.
+    ///
+    /// The rule is that the referenced transaction (`prev_name`) must appear
+    /// earlier in the list passed to [`init_graph`].
     PrevTx(&'a str, usize),
 }
 
+/// Describes an output in a [`TxTemplate`].
 pub struct TxOutTemplate {
+    /// Value in satoshis.
     pub value: u64,
-    pub spk_index: Option<u32>, // some = get spk from SpkTxOutIndex, none = random spk
+    /// If `Some(index)`, the output will use the script pubkey at that index
+    /// from the test descriptor set. If `None`, a random (empty) script is used.
+    pub spk_index: Option<u32>,
 }
 
-#[allow(unused)]
 impl TxOutTemplate {
     pub fn new(value: u64, spk_index: Option<u32>) -> Self {
         TxOutTemplate { value, spk_index }
     }
 }
 
+/// The result of calling [`init_graph`].
+///
+/// Contains the built [`TxGraph`], the associated indexer, and a mapping from
+/// template names to their final txids.
 #[allow(dead_code)]
 pub struct TxTemplateEnv<'a, A> {
     pub tx_graph: TxGraph<A>,
@@ -60,14 +82,21 @@ pub struct TxTemplateEnv<'a, A> {
     pub canonicalization_params: CanonicalizationParams,
 }
 
-#[allow(dead_code)]
+/// Builds a [`TxGraph`] (and associated indexer) from a list of [`TxTemplate`]s.
+///
+/// This is the main entry point for using transaction templates in tests.
+/// It handles txid generation, outpoint wiring, anchor insertion, and last-seen
+/// timestamps automatically.
 pub fn init_graph<'a, A: Anchor + Clone + 'a>(
     tx_templates: impl IntoIterator<Item = &'a TxTemplate<'a, A>>,
 ) -> TxTemplateEnv<'a, A> {
     let (descriptor, _) =
         Descriptor::parse_descriptor(&Secp256k1::signing_only(), DESCRIPTORS[2]).unwrap();
+
     let mut tx_graph = TxGraph::<A>::default();
     let mut indexer = SpkTxOutIndex::default();
+
+    // Pre-populate the indexer with 10 script pubkeys from the test descriptor
     (0..10).for_each(|index| {
         indexer.insert_spk(
             index,
@@ -77,9 +106,10 @@ pub fn init_graph<'a, A: Anchor + Clone + 'a>(
                 .script_pubkey(),
         );
     });
-    let mut txid_to_name = HashMap::<&'a str, Txid>::new();
 
+    let mut txid_to_name = HashMap::<&'a str, Txid>::new();
     let mut canonicalization_params = CanonicalizationParams::default();
+
     for (bogus_txin_vout, tx_tmp) in tx_templates.into_iter().enumerate() {
         let tx = Transaction {
             version: transaction::Version::non_standard(0),
@@ -137,19 +167,24 @@ pub fn init_graph<'a, A: Anchor + Clone + 'a>(
         };
 
         let txid = tx.compute_txid();
+
         if tx_tmp.assume_canonical {
             canonicalization_params.assume_canonical.push(txid);
         }
+
         txid_to_name.insert(tx_tmp.tx_name, txid);
         indexer.scan(&tx);
         let _ = tx_graph.insert_tx(tx.clone());
+
         for anchor in tx_tmp.anchors.iter() {
             let _ = tx_graph.insert_anchor(txid, anchor.clone());
         }
+
         if let Some(last_seen) = tx_tmp.last_seen {
             let _ = tx_graph.insert_seen_at(txid, last_seen);
         }
     }
+
     TxTemplateEnv {
         tx_graph,
         indexer,