refactor!(chain): Unify ChangeSet nomenclature

This commit renames:

- indexed_tx_graph::IndexedAdditions -> indexed_tx_graph::ChangeSet
- tx_graph::Additions -> tx_graph::ChangeSet
- keychain::DerivationAdditions -> keychain::ChangeSet
- CanonicalTx::node -> CanonicalTx::tx_node
- CanonicalTx::observed_as -> CanonicalTx::chain_position

This commit also changes the visibility of TxGraph::determine_changeset
to be pub(crate)

This commit removes:
- `TxGraph::insert_txout_preview`
- `TxGraph::insert_tx_preview`
- `insert_anchor_preview`
- `insert_seen_at_preview`

Solves #1022

crates/bdk/src/wallet/export.rs

@@ -126,13 +126,12 @@ impl FullyNodedExport {
         Self::is_compatible_with_core(&descriptor)?;
 
         let blockheight = if include_blockheight {
-            wallet
-                .transactions()
-                .next()
-                .map_or(0, |canonical_tx| match canonical_tx.observed_as {
+            wallet.transactions().next().map_or(0, |canonical_tx| {
+                match canonical_tx.chain_position {
                     bdk_chain::ChainPosition::Confirmed(a) => a.confirmation_height,
                     bdk_chain::ChainPosition::Unconfirmed(_) => 0,
-                })
+                }
+            })
         } else {
             0
         };

crates/bdk/src/wallet/mod.rs

@@ -21,7 +21,7 @@ use alloc::{
 };
 pub use bdk_chain::keychain::Balance;
 use bdk_chain::{
-    indexed_tx_graph::IndexedAdditions,
+    indexed_tx_graph,
     keychain::{KeychainTxOutIndex, LocalChangeSet, LocalUpdate},
     local_chain::{self, CannotConnectError, CheckPoint, CheckPointIter, LocalChain},
     tx_graph::{CanonicalTx, TxGraph},
@@ -247,7 +247,7 @@ impl<D> Wallet<D> {
 
         let changeset = db.load_from_persistence().map_err(NewError::Persist)?;
         chain.apply_changeset(&changeset.chain_changeset);
-        indexed_graph.apply_additions(changeset.indexed_additions);
+        indexed_graph.apply_changeset(changeset.indexed_changeset);
 
         let persist = Persist::new(db);
 
@@ -320,14 +320,14 @@ impl<D> Wallet<D> {
     {
         let keychain = self.map_keychain(keychain);
         let txout_index = &mut self.indexed_graph.index;
-        let (index, spk, additions) = match address_index {
+        let (index, spk, changeset) = match address_index {
             AddressIndex::New => {
-                let ((index, spk), index_additions) = txout_index.reveal_next_spk(&keychain);
-                (index, spk.into(), Some(index_additions))
+                let ((index, spk), index_changeset) = txout_index.reveal_next_spk(&keychain);
+                (index, spk.into(), Some(index_changeset))
             }
             AddressIndex::LastUnused => {
-                let ((index, spk), index_additions) = txout_index.next_unused_spk(&keychain);
-                (index, spk.into(), Some(index_additions))
+                let ((index, spk), index_changeset) = txout_index.next_unused_spk(&keychain);
+                (index, spk.into(), Some(index_changeset))
             }
             AddressIndex::Peek(index) => {
                 let (index, spk) = txout_index
@@ -339,9 +339,11 @@ impl<D> Wallet<D> {
             }
         };
 
-        if let Some(additions) = additions {
+        if let Some(changeset) = changeset {
             self.persist
-                .stage(ChangeSet::from(IndexedAdditions::from(additions)));
+                .stage(ChangeSet::from(indexed_tx_graph::ChangeSet::from(
+                    changeset,
+                )));
             self.persist.commit()?;
         }
 
@@ -436,12 +438,12 @@ impl<D> Wallet<D> {
         let graph = self.indexed_graph.graph();
 
         let canonical_tx = CanonicalTx {
-            observed_as: graph.get_chain_position(
+            chain_position: graph.get_chain_position(
                 &self.chain,
                 self.chain.tip().map(|cp| cp.block_id()).unwrap_or_default(),
                 txid,
             )?,
-            node: graph.get_tx_node(txid)?,
+            tx_node: graph.get_tx_node(txid)?,
         };
 
         Some(new_tx_details(
@@ -889,12 +891,14 @@ impl<D> Wallet<D> {
             Some(ref drain_recipient) => drain_recipient.clone(),
             None => {
                 let change_keychain = self.map_keychain(KeychainKind::Internal);
-                let ((index, spk), index_additions) =
+                let ((index, spk), index_changeset) =
                     self.indexed_graph.index.next_unused_spk(&change_keychain);
                 let spk = spk.into();
                 self.indexed_graph.index.mark_used(&change_keychain, index);
                 self.persist
-                    .stage(ChangeSet::from(IndexedAdditions::from(index_additions)));
+                    .stage(ChangeSet::from(indexed_tx_graph::ChangeSet::from(
+                        index_changeset,
+                    )));
                 self.persist.commit().expect("TODO");
                 spk
             }
@@ -1286,7 +1290,7 @@ impl<D> Wallet<D> {
                 .indexed_graph
                 .graph()
                 .get_chain_position(&self.chain, chain_tip, input.previous_output.txid)
-                .map(|observed_as| match observed_as {
+                .map(|chain_position| match chain_position {
                     ChainPosition::Confirmed(a) => a.confirmation_height,
                     ChainPosition::Unconfirmed(_) => u32::MAX,
                 });
@@ -1469,7 +1473,7 @@ impl<D> Wallet<D> {
                     .graph()
                     .get_chain_position(&self.chain, chain_tip, txid)
                 {
-                    Some(observed_as) => observed_as.cloned().into(),
+                    Some(chain_position) => chain_position.cloned().into(),
                     None => return false,
                 };
 
@@ -1716,11 +1720,13 @@ impl<D> Wallet<D> {
         D: PersistBackend<ChangeSet>,
     {
         let mut changeset = ChangeSet::from(self.chain.apply_update(update.chain)?);
-        let (_, index_additions) = self
+        let (_, index_changeset) = self
             .indexed_graph
             .index
             .reveal_to_target_multi(&update.last_active_indices);
-        changeset.append(ChangeSet::from(IndexedAdditions::from(index_additions)));
+        changeset.append(ChangeSet::from(indexed_tx_graph::ChangeSet::from(
+            index_changeset,
+        )));
         changeset.append(ChangeSet::from(
             self.indexed_graph.apply_update(update.graph),
         ));
@@ -1827,7 +1833,7 @@ fn new_tx_details(
 ) -> TransactionDetails {
     let graph = indexed_graph.graph();
     let index = &indexed_graph.index;
-    let tx = canonical_tx.node.tx;
+    let tx = canonical_tx.tx_node.tx;
 
     let received = tx
         .output
@@ -1867,11 +1873,11 @@ fn new_tx_details(
 
     TransactionDetails {
         transaction: if include_raw { Some(tx.clone()) } else { None },
-        txid: canonical_tx.node.txid,
+        txid: canonical_tx.tx_node.txid,
         received,
         sent,
         fee,
-        confirmation_time: canonical_tx.observed_as.cloned().into(),
+        confirmation_time: canonical_tx.chain_position.cloned().into(),
     }
 }
 

crates/bdk/tests/wallet.rs

@@ -1571,7 +1571,7 @@ fn test_bump_fee_remove_output_manually_selected_only() {
                 .transactions()
                 .last()
                 .unwrap()
-                .observed_as
+                .chain_position
                 .cloned()
                 .into(),
         )
@@ -1621,7 +1621,7 @@ fn test_bump_fee_add_input() {
         .transactions()
         .last()
         .unwrap()
-        .observed_as
+        .chain_position
         .cloned()
         .into();
     wallet.insert_tx(init_tx, pos).unwrap();

crates/chain/src/indexed_tx_graph.rs

@@ -6,8 +6,8 @@ use alloc::vec::Vec;
 use bitcoin::{OutPoint, Transaction, TxOut};
 
 use crate::{
-    keychain::DerivationAdditions,
-    tx_graph::{Additions, TxGraph},
+    keychain,
+    tx_graph::{self, TxGraph},
     Anchor, Append,
 };
 
@@ -46,47 +46,47 @@ impl<A, I> IndexedTxGraph<A, I> {
 }
 
 impl<A: Anchor, I: Indexer> IndexedTxGraph<A, I> {
-    /// Applies the [`IndexedAdditions`] to the [`IndexedTxGraph`].
-    pub fn apply_additions(&mut self, additions: IndexedAdditions<A, I::Additions>) {
-        let IndexedAdditions {
-            graph_additions,
-            index_additions,
-        } = additions;
+    /// Applies the [`ChangeSet`] to the [`IndexedTxGraph`].
+    pub fn apply_changeset(&mut self, changeset: ChangeSet<A, I::ChangeSet>) {
+        let ChangeSet {
+            graph_changeset,
+            index_changeset,
+        } = changeset;
 
-        self.index.apply_additions(index_additions);
+        self.index.apply_changeset(index_changeset);
 
-        for tx in &graph_additions.txs {
+        for tx in &graph_changeset.txs {
             self.index.index_tx(tx);
         }
-        for (&outpoint, txout) in &graph_additions.txouts {
+        for (&outpoint, txout) in &graph_changeset.txouts {
             self.index.index_txout(outpoint, txout);
         }
 
-        self.graph.apply_additions(graph_additions);
+        self.graph.apply_changeset(graph_changeset);
     }
 }
 
 impl<A: Anchor, I: Indexer> IndexedTxGraph<A, I>
 where
-    I::Additions: Default + Append,
+    I::ChangeSet: Default + Append,
 {
     /// Apply an `update` directly.
     ///
-    /// `update` is a [`TxGraph<A>`] and the resultant changes is returned as [`IndexedAdditions`].
-    pub fn apply_update(&mut self, update: TxGraph<A>) -> IndexedAdditions<A, I::Additions> {
-        let graph_additions = self.graph.apply_update(update);
+    /// `update` is a [`TxGraph<A>`] and the resultant changes is returned as [`ChangeSet`].
+    pub fn apply_update(&mut self, update: TxGraph<A>) -> ChangeSet<A, I::ChangeSet> {
+        let graph_changeset = self.graph.apply_update(update);
 
-        let mut index_additions = I::Additions::default();
-        for added_tx in &graph_additions.txs {
-            index_additions.append(self.index.index_tx(added_tx));
+        let mut index_changeset = I::ChangeSet::default();
+        for added_tx in &graph_changeset.txs {
+            index_changeset.append(self.index.index_tx(added_tx));
         }
-        for (&added_outpoint, added_txout) in &graph_additions.txouts {
-            index_additions.append(self.index.index_txout(added_outpoint, added_txout));
+        for (&added_outpoint, added_txout) in &graph_changeset.txouts {
+            index_changeset.append(self.index.index_txout(added_outpoint, added_txout));
         }
 
-        IndexedAdditions {
-            graph_additions,
-            index_additions,
+        ChangeSet {
+            graph_changeset,
+            index_changeset,
         }
     }
 
@@ -95,7 +95,7 @@ where
         &mut self,
         outpoint: OutPoint,
         txout: &TxOut,
-    ) -> IndexedAdditions<A, I::Additions> {
+    ) -> ChangeSet<A, I::ChangeSet> {
         let mut update = TxGraph::<A>::default();
         let _ = update.insert_txout(outpoint, txout.clone());
         self.apply_update(update)
@@ -110,7 +110,7 @@ where
         tx: &Transaction,
         anchors: impl IntoIterator<Item = A>,
         seen_at: Option<u64>,
-    ) -> IndexedAdditions<A, I::Additions> {
+    ) -> ChangeSet<A, I::ChangeSet> {
         let txid = tx.txid();
 
         let mut update = TxGraph::<A>::default();
@@ -138,20 +138,20 @@ where
         &mut self,
         txs: impl IntoIterator<Item = (&'t Transaction, impl IntoIterator<Item = A>)>,
         seen_at: Option<u64>,
-    ) -> IndexedAdditions<A, I::Additions> {
+    ) -> ChangeSet<A, I::ChangeSet> {
         // The algorithm below allows for non-topologically ordered transactions by using two loops.
         // This is achieved by:
         // 1. insert all txs into the index. If they are irrelevant then that's fine it will just
         //    not store anything about them.
         // 2. decide whether to insert them into the graph depending on whether `is_tx_relevant`
         //    returns true or not. (in a second loop).
-        let mut additions = IndexedAdditions::<A, I::Additions>::default();
+        let mut changeset = ChangeSet::<A, I::ChangeSet>::default();
         let mut transactions = Vec::new();
         for (tx, anchors) in txs.into_iter() {
-            additions.index_additions.append(self.index.index_tx(tx));
+            changeset.index_changeset.append(self.index.index_tx(tx));
             transactions.push((tx, anchors));
         }
-        additions.append(
+        changeset.append(
             transactions
                 .into_iter()
                 .filter_map(|(tx, anchors)| match self.index.is_tx_relevant(tx) {
@@ -163,7 +163,7 @@ where
                     acc
                 }),
         );
-        additions
+        changeset
     }
 }
 
@@ -181,64 +181,64 @@ where
     )
 )]
 #[must_use]
-pub struct IndexedAdditions<A, IA> {
-    /// [`TxGraph`] additions.
-    pub graph_additions: Additions<A>,
-    /// [`Indexer`] additions.
-    pub index_additions: IA,
+pub struct ChangeSet<A, IA> {
+    /// [`TxGraph`] changeset.
+    pub graph_changeset: tx_graph::ChangeSet<A>,
+    /// [`Indexer`] changeset.
+    pub index_changeset: IA,
 }
 
-impl<A, IA: Default> Default for IndexedAdditions<A, IA> {
+impl<A, IA: Default> Default for ChangeSet<A, IA> {
     fn default() -> Self {
         Self {
-            graph_additions: Default::default(),
-            index_additions: Default::default(),
+            graph_changeset: Default::default(),
+            index_changeset: Default::default(),
         }
     }
 }
 
-impl<A: Anchor, IA: Append> Append for IndexedAdditions<A, IA> {
+impl<A: Anchor, IA: Append> Append for ChangeSet<A, IA> {
     fn append(&mut self, other: Self) {
-        self.graph_additions.append(other.graph_additions);
-        self.index_additions.append(other.index_additions);
+        self.graph_changeset.append(other.graph_changeset);
+        self.index_changeset.append(other.index_changeset);
     }
 
     fn is_empty(&self) -> bool {
-        self.graph_additions.is_empty() && self.index_additions.is_empty()
+        self.graph_changeset.is_empty() && self.index_changeset.is_empty()
     }
 }
 
-impl<A, IA: Default> From<Additions<A>> for IndexedAdditions<A, IA> {
-    fn from(graph_additions: Additions<A>) -> Self {
+impl<A, IA: Default> From<tx_graph::ChangeSet<A>> for ChangeSet<A, IA> {
+    fn from(graph_changeset: tx_graph::ChangeSet<A>) -> Self {
         Self {
-            graph_additions,
+            graph_changeset,
             ..Default::default()
         }
     }
 }
 
-impl<A, K> From<DerivationAdditions<K>> for IndexedAdditions<A, DerivationAdditions<K>> {
-    fn from(index_additions: DerivationAdditions<K>) -> Self {
+impl<A, K> From<keychain::ChangeSet<K>> for ChangeSet<A, keychain::ChangeSet<K>> {
+    fn from(index_changeset: keychain::ChangeSet<K>) -> Self {
         Self {
-            graph_additions: Default::default(),
-            index_additions,
+            graph_changeset: Default::default(),
+            index_changeset,
         }
     }
 }
 
 /// Represents a structure that can index transaction data.
 pub trait Indexer {
-    /// The resultant "additions" when new transaction data is indexed.
-    type Additions;
+    /// The resultant "changeset" when new transaction data is indexed.
+    type ChangeSet;
 
     /// Scan and index the given `outpoint` and `txout`.
-    fn index_txout(&mut self, outpoint: OutPoint, txout: &TxOut) -> Self::Additions;
+    fn index_txout(&mut self, outpoint: OutPoint, txout: &TxOut) -> Self::ChangeSet;
 
     /// Scan and index the given transaction.
-    fn index_tx(&mut self, tx: &Transaction) -> Self::Additions;
+    fn index_tx(&mut self, tx: &Transaction) -> Self::ChangeSet;
 
-    /// Apply additions to itself.
-    fn apply_additions(&mut self, additions: Self::Additions);
+    /// Apply changeset to itself.
+    fn apply_changeset(&mut self, changeset: Self::ChangeSet);
 
     /// Determines whether the transaction should be included in the index.
     fn is_tx_relevant(&self, tx: &Transaction) -> bool;