chore(core)!: s/tx_graph::Update/TxUpdate/

We shouldn't refer to `tx_graph` in `bdk_core`. TxGraph happens to
consume `Update` but it doesn't conceptually own the definition of an
update to transactions.

I tried to also remove a lot of references to "graph" where they
shouldn't be. "graph" is a very general kind of data structure so we
should avoid referring to it where it's not relevant. `tx_update` is
much better than `graph_update`.

Author: LLFourn

crates/chain/src/indexed_tx_graph.rs

@@ -90,10 +90,10 @@ where
 
     /// Apply an `update` directly.
     ///
-    /// `update` is a [`tx_graph::Update<A>`] and the resultant changes is returned as [`ChangeSet`].
+    /// `update` is a [`tx_graph::TxUpdate<A>`] and the resultant changes is returned as [`ChangeSet`].
     #[cfg(feature = "std")]
     #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
-    pub fn apply_update(&mut self, update: tx_graph::Update<A>) -> ChangeSet<A, I::ChangeSet> {
+    pub fn apply_update(&mut self, update: tx_graph::TxUpdate<A>) -> ChangeSet<A, I::ChangeSet> {
         let tx_graph = self.graph.apply_update(update);
         let indexer = self.index_tx_graph_changeset(&tx_graph);
         ChangeSet { tx_graph, indexer }
@@ -114,7 +114,7 @@ where
     /// set to the current time.
     pub fn apply_update_at(
         &mut self,
-        update: tx_graph::Update<A>,
+        update: tx_graph::TxUpdate<A>,
         seen_at: Option<u64>,
     ) -> ChangeSet<A, I::ChangeSet> {
         let tx_graph = self.graph.apply_update_at(update, seen_at);

crates/chain/src/tx_graph.rs

@@ -78,7 +78,7 @@
 //! # let tx_b = tx_from_hex(RAW_TX_2);
 //! let mut graph: TxGraph = TxGraph::default();
 //!
-//! let mut update = tx_graph::Update::default();
+//! let mut update = tx_graph::TxUpdate::default();
 //! update.txs.push(Arc::new(tx_a));
 //! update.txs.push(Arc::new(tx_b));
 //!
@@ -98,15 +98,15 @@ use crate::{Anchor, Balance, ChainOracle, ChainPosition, FullTxOut, Merge};
 use alloc::collections::vec_deque::VecDeque;
 use alloc::sync::Arc;
 use alloc::vec::Vec;
-pub use bdk_core::tx_graph::Update;
+pub use bdk_core::TxUpdate;
 use bitcoin::{Amount, OutPoint, ScriptBuf, SignedAmount, Transaction, TxOut, Txid};
 use core::fmt::{self, Formatter};
 use core::{
     convert::Infallible,
     ops::{Deref, RangeInclusive},
 };
 
-impl<A> From<TxGraph<A>> for Update<A> {
+impl<A> From<TxGraph<A>> for TxUpdate<A> {
     fn from(graph: TxGraph<A>) -> Self {
         Self {
             txs: graph.full_txs().map(|tx_node| tx_node.tx).collect(),
@@ -120,8 +120,8 @@ impl<A> From<TxGraph<A>> for Update<A> {
     }
 }
 
-impl<A: Ord + Clone> From<Update<A>> for TxGraph<A> {
-    fn from(update: Update<A>) -> Self {
+impl<A: Ord + Clone> From<TxUpdate<A>> for TxGraph<A> {
+    fn from(update: TxUpdate<A>) -> Self {
         let mut graph = TxGraph::<A>::default();
         let _ = graph.apply_update_at(update, None);
         graph
@@ -655,7 +655,7 @@ impl<A: Clone + Ord> TxGraph<A> {
     /// exist in `update` but not in `self`).
     #[cfg(feature = "std")]
     #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
-    pub fn apply_update(&mut self, update: Update<A>) -> ChangeSet<A> {
+    pub fn apply_update(&mut self, update: TxUpdate<A>) -> ChangeSet<A> {
         use std::time::*;
         let now = SystemTime::now()
             .duration_since(UNIX_EPOCH)
@@ -676,7 +676,7 @@ impl<A: Clone + Ord> TxGraph<A> {
     ///
     /// Use [`apply_update`](TxGraph::apply_update) to have the `seen_at` value automatically set
     /// to the current time.
-    pub fn apply_update_at(&mut self, update: Update<A>, seen_at: Option<u64>) -> ChangeSet<A> {
+    pub fn apply_update_at(&mut self, update: TxUpdate<A>, seen_at: Option<u64>) -> ChangeSet<A> {
         let mut changeset = ChangeSet::<A>::default();
         let mut unanchored_txs = HashSet::<Txid>::new();
         for tx in update.txs {

crates/chain/tests/test_tx_graph.rs

@@ -88,7 +88,7 @@ fn insert_txouts() {
 
     // Make the update graph
     let update = {
-        let mut update = tx_graph::Update::default();
+        let mut update = tx_graph::TxUpdate::default();
         for (outpoint, txout) in &update_ops {
             // Insert partials transactions.
             update.txouts.insert(*outpoint, txout.clone());
@@ -1137,12 +1137,12 @@ fn call_map_anchors_with_non_deterministic_anchor() {
     );
 }
 
-/// Tests `From` impls for conversion between [`TxGraph`] and [`tx_graph::Update`].
+/// Tests `From` impls for conversion between [`TxGraph`] and [`tx_graph::TxUpdate`].
 #[test]
 fn tx_graph_update_conversion() {
-    use tx_graph::Update;
+    use tx_graph::TxUpdate;
 
-    type TestCase = (&'static str, Update<ConfirmationBlockTime>);
+    type TestCase = (&'static str, TxUpdate<ConfirmationBlockTime>);
 
     fn make_tx(v: i32) -> Transaction {
         Transaction {
@@ -1161,24 +1161,24 @@ fn tx_graph_update_conversion() {
     }
 
     let test_cases: &[TestCase] = &[
-        ("empty_update", Update::default()),
+        ("empty_update", TxUpdate::default()),
         (
             "single_tx",
-            Update {
+            TxUpdate {
                 txs: vec![make_tx(0).into()],
                 ..Default::default()
             },
         ),
         (
             "two_txs",
-            Update {
+            TxUpdate {
                 txs: vec![make_tx(0).into(), make_tx(1).into()],
                 ..Default::default()
             },
         ),
         (
             "with_floating_txouts",
-            Update {
+            TxUpdate {
                 txs: vec![make_tx(0).into(), make_tx(1).into()],
                 txouts: [
                     (OutPoint::new(h!("a"), 0), make_txout(0)),
@@ -1191,7 +1191,7 @@ fn tx_graph_update_conversion() {
         ),
         (
             "with_anchors",
-            Update {
+            TxUpdate {
                 txs: vec![make_tx(0).into(), make_tx(1).into()],
                 txouts: [
                     (OutPoint::new(h!("a"), 0), make_txout(0)),
@@ -1209,7 +1209,7 @@ fn tx_graph_update_conversion() {
         ),
         (
             "with_seen_ats",
-            Update {
+            TxUpdate {
                 txs: vec![make_tx(0).into(), make_tx(1).into()],
                 txouts: [
                     (OutPoint::new(h!("a"), 0), make_txout(0)),
@@ -1230,7 +1230,7 @@ fn tx_graph_update_conversion() {
     for (test_name, update) in test_cases {
         let mut tx_graph = TxGraph::<ConfirmationBlockTime>::default();
         let _ = tx_graph.apply_update_at(update.clone(), None);
-        let update_from_tx_graph: Update<ConfirmationBlockTime> = tx_graph.into();
+        let update_from_tx_graph: TxUpdate<ConfirmationBlockTime> = tx_graph.into();
 
         assert_eq!(
             update

crates/core/src/chain_data.rs renamed to crates/core/src/block_id.rs

@@ -59,55 +59,13 @@ pub type Indexed<T> = (u32, T);
 /// A tuple of keychain `K`, derivation index (`u32`) and a `T` associated with them.
 pub type KeychainIndexed<K, T> = ((K, u32), T);
 
-mod chain_data;
-pub use chain_data::*;
+mod block_id;
+pub use block_id::*;
 
 mod checkpoint;
 pub use checkpoint::*;
 
-pub mod spk_client;
-
-/// Core structures for [`TxGraph`].
-///
-/// [`TxGraph`]: https://docs.rs/bdk_chain/latest/bdk_chain/tx_graph/struct.TxGraph.html
-pub mod tx_graph {
-    use crate::collections::{BTreeMap, BTreeSet, HashMap};
-    use alloc::{sync::Arc, vec::Vec};
-    use bitcoin::{OutPoint, Transaction, TxOut, Txid};
-
-    /// Data object used to update a [`TxGraph`].
-    ///
-    /// [`TxGraph`]: https://docs.rs/bdk_chain/latest/bdk_chain/tx_graph/struct.TxGraph.html
-    #[derive(Debug, Clone)]
-    pub struct Update<A = ()> {
-        /// Full transactions.
-        pub txs: Vec<Arc<Transaction>>,
-        /// Floating txouts.
-        pub txouts: BTreeMap<OutPoint, TxOut>,
-        /// Transaction anchors.
-        pub anchors: BTreeSet<(A, Txid)>,
-        /// Seen at times for transactions.
-        pub seen_ats: HashMap<Txid, u64>,
-    }
+mod tx_update;
+pub use tx_update::*;
 
-    impl<A> Default for Update<A> {
-        fn default() -> Self {
-            Self {
-                txs: Default::default(),
-                txouts: Default::default(),
-                anchors: Default::default(),
-                seen_ats: Default::default(),
-            }
-        }
-    }
-
-    impl<A: Ord> Update<A> {
-        /// Extend this update with `other`.
-        pub fn extend(&mut self, other: Update<A>) {
-            self.txs.extend(other.txs);
-            self.txouts.extend(other.txouts);
-            self.anchors.extend(other.anchors);
-            self.seen_ats.extend(other.seen_ats);
-        }
-    }
-}
+pub mod spk_client;

crates/core/src/lib.rs

@@ -323,18 +323,16 @@ impl<I> SyncRequest<I> {
 #[must_use]
 #[derive(Debug)]
 pub struct SyncResult<A = ConfirmationBlockTime> {
-    /// The update to apply to the receiving
-    /// [`TxGraph`](../../bdk_chain/tx_graph/struct.TxGraph.html).
-    pub graph_update: crate::tx_graph::Update<A>,
-    /// The update to apply to the receiving
-    /// [`LocalChain`](../../bdk_chain/local_chain/struct.LocalChain.html).
+    /// Relevant transaction data discovered during the scan.
+    pub tx_update: crate::TxUpdate<A>,
+    /// Changes to the chain discovered during the scan.
     pub chain_update: Option<CheckPoint>,
 }
 
 impl<A> Default for SyncResult<A> {
     fn default() -> Self {
         Self {
-            graph_update: Default::default(),
+            tx_update: Default::default(),
             chain_update: Default::default(),
         }
     }
@@ -462,19 +460,19 @@ impl<K: Ord + Clone> FullScanRequest<K> {
 #[must_use]
 #[derive(Debug)]
 pub struct FullScanResult<K, A = ConfirmationBlockTime> {
-    /// The update to apply to the receiving
-    /// [`LocalChain`](../../bdk_chain/local_chain/struct.LocalChain.html).
-    pub graph_update: crate::tx_graph::Update<A>,
-    /// The update to apply to the receiving [`TxGraph`](../../bdk_chain/tx_graph/struct.TxGraph.html).
-    pub chain_update: Option<CheckPoint>,
-    /// Last active indices for the corresponding keychains (`K`).
+    /// Relevant transaction data discovered during the scan.
+    pub tx_update: crate::TxUpdate<A>,
+    /// Last active indices for the corresponding keychains (`K`). An index is active if it had a
+    /// transaction associated with the script pubkey at that index.
     pub last_active_indices: BTreeMap<K, u32>,
+    /// Changes to the chain discovered during the scan.
+    pub chain_update: Option<CheckPoint>,
 }
 
 impl<K, A> Default for FullScanResult<K, A> {
     fn default() -> Self {
         Self {
-            graph_update: Default::default(),
+            tx_update: Default::default(),
             chain_update: Default::default(),
             last_active_indices: Default::default(),
         }

crates/core/src/spk_client.rs

@@ -0,0 +1,43 @@
+use crate::collections::{BTreeMap, BTreeSet, HashMap};
+use alloc::{sync::Arc, vec::Vec};
+use bitcoin::{OutPoint, Transaction, TxOut, Txid};
+
+/// Data object used to communicate updates about relevant transactions from some chain data soruce
+/// to the core model (usually a `bdk_chain::TxGraph`).
+#[derive(Debug, Clone)]
+pub struct TxUpdate<A = ()> {
+    /// Full transactions. These are transactions that were determined to be relevant to the wallet
+    /// given the request.
+    pub txs: Vec<Arc<Transaction>>,
+    /// Floating txouts. These are `TxOut`s that exist but the whole transaction wasn't included in
+    /// `txs` since only knowing about the output is important. These are often used to help determine
+    /// the fee of a wallet transaction.
+    pub txouts: BTreeMap<OutPoint, TxOut>,
+    /// Transaction anchors. Anchors tells us a position in the chain where a transaction was
+    /// confirmed.
+    pub anchors: BTreeSet<(A, Txid)>,
+    /// Seen at times for transactions. This records when a transaction was most recently seen in
+    /// the user's mempool for the sake of tie-breaking other conflicting transactions.
+    pub seen_ats: HashMap<Txid, u64>,
+}
+
+impl<A> Default for TxUpdate<A> {
+    fn default() -> Self {
+        Self {
+            txs: Default::default(),
+            txouts: Default::default(),
+            anchors: Default::default(),
+            seen_ats: Default::default(),
+        }
+    }
+}
+
+impl<A: Ord> TxUpdate<A> {
+    /// Extend this update with `other`.
+    pub fn extend(&mut self, other: TxUpdate<A>) {
+        self.txs.extend(other.txs);
+        self.txouts.extend(other.txouts);
+        self.anchors.extend(other.anchors);
+        self.seen_ats.extend(other.seen_ats);
+    }
+}