Skip to content

Commit 3126cd2

Browse files
evanlinjinevanlinjin
committed
feat(chain)!: Clean up ergonomics of IndexedTxGraph
* `new` is now intended to construct a fresh indexed-tx-graph * `from_changeset` is added for constructing indexed-tx-graph from a previously persisted changeset * added `reindex` for calling after indexer mutations that require it * reintroduce `Default` impl
1 parent a055581 commit 3126cd2

4 files changed

Lines changed: 131 additions & 50 deletions

File tree

‎crates/bitcoind_rpc/examples/filter_iter.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ fn main() -> anyhow::Result<()> {
3131
let (descriptor, _) = Descriptor::parse_descriptor(&secp, EXTERNAL)?;
3232
let (change_descriptor, _) = Descriptor::parse_descriptor(&secp, INTERNAL)?;
3333
let (mut chain, _) = LocalChain::from_genesis_hash(genesis_block(NETWORK).block_hash());
34+
3435
let mut graph = IndexedTxGraph::<ConfirmationBlockTime, KeychainTxOutIndex<&str>>::new({
3536
let mut index = KeychainTxOutIndex::default();
3637
index.insert_descriptor("external", descriptor.clone())?;

‎crates/chain/src/indexed_tx_graph.rs‎

Lines changed: 92 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,14 @@ use crate::{
1515
Anchor, BlockId, ChainOracle, Indexer, Merge, TxPosInBlock,
1616
};
1717

18-
/// The [`IndexedTxGraph`] combines a [`TxGraph`] and an [`Indexer`] implementation.
18+
/// A [`TxGraph<A>`] paired with an indexer `I`, enforcing that every insertion into the graph is
19+
/// simultaneously fed through the indexer.
1920
///
20-
/// It ensures that [`TxGraph`] and [`Indexer`] are updated atomically.
21+
/// This guarantees that `tx_graph` and `index` remain in sync: any transaction or floating txout
22+
/// you add to `tx_graph` has already been processed by `index`.
2123
#[derive(Debug, Clone)]
2224
pub struct IndexedTxGraph<A, I> {
23-
/// Transaction index.
25+
/// The indexer used for filtering transactions and floating txouts that we are interested in.
2426
pub index: I,
2527
graph: TxGraph<A>,
2628
}
@@ -35,14 +37,6 @@ impl<A, I: Default> Default for IndexedTxGraph<A, I> {
3537
}
3638

3739
impl<A, I> IndexedTxGraph<A, I> {
38-
/// Construct a new [`IndexedTxGraph`] with a given `index`.
39-
pub fn new(index: I) -> Self {
40-
Self {
41-
index,
42-
graph: TxGraph::default(),
43-
}
44-
}
45-
4640
/// Get a reference of the internal transaction graph.
4741
pub fn graph(&self) -> &TxGraph<A> {
4842
&self.graph
@@ -79,6 +73,87 @@ impl<A: Anchor, I: Indexer> IndexedTxGraph<A, I>
7973
where
8074
I::ChangeSet: Default + Merge,
8175
{
76+
/// Create a new, empty [`IndexedTxGraph`].
77+
///
78+
/// The underlying `TxGraph` is initialized with `TxGraph::default()`, and the provided
79+
/// `index`er is used as‐is (since there are no existing transactions to process).
80+
pub fn new(index: I) -> Self {
81+
Self {
82+
index,
83+
graph: TxGraph::default(),
84+
}
85+
}
86+
87+
/// Reconstruct an [`IndexedTxGraph`] from persisted graph + indexer state.
88+
///
89+
/// 1. Rebuilds the `TxGraph` from `changeset.tx_graph`.
90+
/// 2. Calls your `indexer_from_changeset` closure on `changeset.indexer` to restore any state
91+
/// your indexer needs beyond its raw changeset.
92+
/// 3. Runs a full `.reindex()`, returning its `ChangeSet` to describe any additional updates
93+
/// applied.
94+
///
95+
/// # Errors
96+
///
97+
/// Returns `Err(E)` if `indexer_from_changeset` fails.
98+
///
99+
/// # Examples
100+
///
101+
/// ```rust,no_run
102+
/// use bdk_chain::IndexedTxGraph;
103+
/// # use bdk_chain::indexed_tx_graph::ChangeSet;
104+
/// # use bdk_chain::indexer::keychain_txout::{KeychainTxOutIndex, DEFAULT_LOOKAHEAD};
105+
/// # use bdk_core::BlockId;
106+
/// # use bdk_testenv::anyhow;
107+
/// # use miniscript::{Descriptor, DescriptorPublicKey};
108+
/// # use std::str::FromStr;
109+
/// # let persisted_changeset = ChangeSet::<BlockId, _>::default();
110+
/// # let persisted_desc = Some(Descriptor::<DescriptorPublicKey>::from_str("")?);
111+
/// # let persisted_change_desc = Some(Descriptor::<DescriptorPublicKey>::from_str("")?);
112+
///
113+
/// let (graph, reindex_cs) =
114+
/// IndexedTxGraph::from_changeset(persisted_changeset, move |idx_cs| -> anyhow::Result<_> {
115+
/// // e.g. KeychainTxOutIndex needs descriptors that weren’t in its CS
116+
/// let mut idx = KeychainTxOutIndex::from_changeset(DEFAULT_LOOKAHEAD, true, idx_cs);
117+
/// if let Some(desc) = persisted_desc {
118+
/// idx.insert_descriptor("external", desc)?;
119+
/// }
120+
/// if let Some(desc) = persisted_change_desc {
121+
/// idx.insert_descriptor("internal", desc)?;
122+
/// }
123+
/// Ok(idx)
124+
/// })?;
125+
/// # Ok::<(), anyhow::Error>(())
126+
/// ```
127+
pub fn from_changeset<F, E>(
128+
changeset: ChangeSet<A, I::ChangeSet>,
129+
indexer_from_changeset: F,
130+
) -> Result<(Self, ChangeSet<A, I::ChangeSet>), E>
131+
where
132+
F: FnOnce(I::ChangeSet) -> Result<I, E>,
133+
{
134+
let graph = TxGraph::<A>::from_changeset(changeset.tx_graph);
135+
let index = indexer_from_changeset(changeset.indexer)?;
136+
let mut out = Self { graph, index };
137+
let out_changeset = out.reindex();
138+
Ok((out, out_changeset))
139+
}
140+
141+
/// Synchronizes the indexer to reflect every entry in the transaction graph.
142+
///
143+
/// Iterates over **all** full transactions and floating outputs in `self.graph`, passing each
144+
/// into `self.index`. Any indexer-side changes produced (via `index_tx` or `index_txout`) are
145+
/// merged into a fresh `ChangeSet`, which is then returned.
146+
pub fn reindex(&mut self) -> ChangeSet<A, I::ChangeSet> {
147+
let mut changeset = ChangeSet::<A, I::ChangeSet>::default();
148+
for tx in self.graph.full_txs() {
149+
changeset.indexer.merge(self.index.index_tx(&tx));
150+
}
151+
for (op, txout) in self.graph.floating_txouts() {
152+
changeset.indexer.merge(self.index.index_txout(op, txout));
153+
}
154+
changeset
155+
}
156+
82157
fn index_tx_graph_changeset(
83158
&mut self,
84159
tx_graph_changeset: &tx_graph::ChangeSet<A>,
@@ -443,6 +518,12 @@ impl<A, IA: Default> From<tx_graph::ChangeSet<A>> for ChangeSet<A, IA> {
443518
}
444519
}
445520

521+
impl<A, IA> From<(tx_graph::ChangeSet<A>, IA)> for ChangeSet<A, IA> {
522+
fn from((tx_graph, indexer): (tx_graph::ChangeSet<A>, IA)) -> Self {
523+
Self { tx_graph, indexer }
524+
}
525+
}
526+
446527
#[cfg(feature = "miniscript")]
447528
impl<A> From<crate::keychain_txout::ChangeSet> for ChangeSet<A, crate::keychain_txout::ChangeSet> {
448529
fn from(indexer: crate::keychain_txout::ChangeSet) -> Self {

‎crates/chain/tests/test_indexed_tx_graph.rs‎

Lines changed: 16 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,12 @@ fn insert_relevant_txs() {
3535
let spk_1 = descriptor.at_derivation_index(9).unwrap().script_pubkey();
3636
let lookahead = 10;
3737

38-
let mut graph = IndexedTxGraph::<ConfirmationBlockTime, KeychainTxOutIndex<()>>::new(
39-
KeychainTxOutIndex::new(lookahead, true),
40-
);
41-
let is_inserted = graph
42-
.index
43-
.insert_descriptor((), descriptor.clone())
44-
.unwrap();
45-
assert!(is_inserted);
38+
let mut graph = IndexedTxGraph::<ConfirmationBlockTime, KeychainTxOutIndex<()>>::new({
39+
let mut indexer = KeychainTxOutIndex::new(lookahead, true);
40+
let is_inserted = indexer.insert_descriptor((), descriptor.clone()).unwrap();
41+
assert!(is_inserted);
42+
indexer
43+
});
4644

4745
let tx_a = Transaction {
4846
output: vec![
@@ -160,18 +158,16 @@ fn test_list_owned_txouts() {
160158
let (desc_2, _) =
161159
Descriptor::parse_descriptor(&Secp256k1::signing_only(), DESCRIPTORS[3]).unwrap();
162160

163-
let mut graph = IndexedTxGraph::<ConfirmationBlockTime, KeychainTxOutIndex<String>>::new(
164-
KeychainTxOutIndex::new(10, true),
165-
);
166-
167-
assert!(graph
168-
.index
169-
.insert_descriptor("keychain_1".into(), desc_1)
170-
.unwrap());
171-
assert!(graph
172-
.index
173-
.insert_descriptor("keychain_2".into(), desc_2)
174-
.unwrap());
161+
let mut graph = IndexedTxGraph::<ConfirmationBlockTime, KeychainTxOutIndex<String>>::new({
162+
let mut indexer = KeychainTxOutIndex::new(10, true);
163+
assert!(indexer
164+
.insert_descriptor("keychain_1".into(), desc_1)
165+
.unwrap());
166+
assert!(indexer
167+
.insert_descriptor("keychain_2".into(), desc_2)
168+
.unwrap());
169+
indexer
170+
});
175171

176172
// Get trusted and untrusted addresses
177173

‎examples/example_cli/src/lib.rs‎

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
use bdk_chain::keychain_txout::DEFAULT_LOOKAHEAD;
12
use serde_json::json;
23
use std::cmp;
34
use std::collections::HashMap;
@@ -22,7 +23,6 @@ use bdk_chain::miniscript::{
2223
use bdk_chain::CanonicalizationParams;
2324
use bdk_chain::ConfirmationBlockTime;
2425
use bdk_chain::{
25-
indexed_tx_graph,
2626
indexer::keychain_txout::{self, KeychainTxOutIndex},
2727
local_chain::{self, LocalChain},
2828
tx_graph, ChainOracle, DescriptorExt, FullTxOut, IndexedTxGraph, Merge,
@@ -818,11 +818,10 @@ pub fn init_or_load<CS: clap::Subcommand, S: clap::Args>(
818818
Commands::Generate { network } => generate_bip86_helper(network).map(|_| None),
819819
// try load
820820
_ => {
821-
let (db, changeset) =
821+
let (mut db, changeset) =
822822
Store::<ChangeSet>::load(db_magic, db_path).context("could not open file store")?;
823823

824824
let changeset = changeset.expect("should not be empty");
825-
826825
let network = changeset.network.expect("changeset network");
827826

828827
let chain = Mutex::new({
@@ -832,23 +831,27 @@ pub fn init_or_load<CS: clap::Subcommand, S: clap::Args>(
832831
chain
833832
});
834833

835-
let graph = Mutex::new({
836-
// insert descriptors and apply loaded changeset
837-
let mut index = KeychainTxOutIndex::default();
838-
if let Some(desc) = changeset.descriptor {
839-
index.insert_descriptor(Keychain::External, desc)?;
840-
}
841-
if let Some(change_desc) = changeset.change_descriptor {
842-
index.insert_descriptor(Keychain::Internal, change_desc)?;
843-
}
844-
let mut graph = KeychainTxGraph::new(index);
845-
graph.apply_changeset(indexed_tx_graph::ChangeSet {
846-
tx_graph: changeset.tx_graph,
847-
indexer: changeset.indexer,
848-
});
849-
graph
850-
});
834+
let (graph, changeset) = IndexedTxGraph::from_changeset(
835+
(changeset.tx_graph, changeset.indexer).into(),
836+
|c| -> anyhow::Result<_> {
837+
let mut indexer =
838+
KeychainTxOutIndex::from_changeset(DEFAULT_LOOKAHEAD, true, c);
839+
if let Some(desc) = changeset.descriptor {
840+
indexer.insert_descriptor(Keychain::External, desc)?;
841+
}
842+
if let Some(change_desc) = changeset.change_descriptor {
843+
indexer.insert_descriptor(Keychain::Internal, change_desc)?;
844+
}
845+
Ok(indexer)
846+
},
847+
)?;
848+
db.append(&ChangeSet {
849+
indexer: changeset.indexer,
850+
tx_graph: changeset.tx_graph,
851+
..Default::default()
852+
})?;
851853

854+
let graph = Mutex::new(graph);
852855
let db = Mutex::new(db);
853856

854857
Ok(Some(Init {

0 commit comments

Comments
 (0)