Struct IndexedTxGraph

pub struct IndexedTxGraph<A, I> {
    pub index: I,
    /* private fields */
}

A TxGraph<A> paired with an indexer I, enforcing that every insertion into the graph is simultaneously fed through the indexer.

This guarantees that tx_graph and index remain in sync: any transaction or floating txout you add to tx_graph has already been processed by index.

Fields

index: I

The indexer used for filtering transactions and floating txouts that we are interested in.

Implementations

impl<A, I> IndexedTxGraph<A, I>

pub fn graph(&self) -> &TxGraph<A>

Get a reference of the internal transaction graph.

impl<A: Anchor, I: Indexer> IndexedTxGraph<A, I>

pub fn apply_changeset(&mut self, changeset: ChangeSet<A, I::ChangeSet>)

Applies the ChangeSet to the IndexedTxGraph.

pub fn initial_changeset(&self) -> ChangeSet<A, I::ChangeSet>

Determines the ChangeSet between self and an empty IndexedTxGraph.

impl<A: Anchor, I: Indexer> IndexedTxGraph<A, I>

where I::ChangeSet: Default + Merge,

pub fn new(index: I) -> Self

Create a new, empty IndexedTxGraph.

The underlying TxGraph is initialized with TxGraph::default(), and the provided indexer is used as‐is (since there are no existing transactions to process).

pub fn from_changeset<F, E>( changeset: ChangeSet<A, I::ChangeSet>, indexer_from_changeset: F, ) -> Result<(Self, ChangeSet<A, I::ChangeSet>), E>

where F: FnOnce(I::ChangeSet) -> Result<I, E>,

Reconstruct an IndexedTxGraph from persisted graph + indexer state.

1. Rebuilds the TxGraph from changeset.tx_graph.
2. Calls your indexer_from_changeset closure on changeset.indexer to restore any state your indexer needs beyond its raw changeset.
3. Runs a full .reindex(), returning its ChangeSet to describe any additional updates applied.

Errors

Returns Err(E) if indexer_from_changeset fails.

Examples

use bdk_chain::IndexedTxGraph;

let (graph, reindex_cs) =
    IndexedTxGraph::from_changeset(persisted_changeset, move |idx_cs| -> anyhow::Result<_> {
        // e.g. KeychainTxOutIndex needs descriptors that weren’t in its change set.
        let mut idx = KeychainTxOutIndex::from_changeset(DEFAULT_LOOKAHEAD, true, idx_cs);
        if let Some(desc) = persisted_desc {
            idx.insert_descriptor("external", desc)?;
        }
        if let Some(desc) = persisted_change_desc {
            idx.insert_descriptor("internal", desc)?;
        }
        Ok(idx)
    })?;

pub fn reindex(&mut self) -> ChangeSet<A, I::ChangeSet>

Synchronizes the indexer to reflect every entry in the transaction graph.

Iterates over all full transactions and floating outputs in self.graph, passing each into self.index. Any indexer-side changes produced (via index_tx or index_txout) are merged into a fresh ChangeSet, which is then returned.

pub fn apply_update( &mut self, update: TxUpdate<A>, ) -> ChangeSet<A, I::ChangeSet>

Apply an update directly.

update is a tx_graph::TxUpdate<A> and the resultant changes is returned as ChangeSet.

pub fn insert_txout( &mut self, outpoint: OutPoint, txout: TxOut, ) -> ChangeSet<A, I::ChangeSet>

Insert a floating txout of given outpoint.

pub fn insert_tx<T: Into<Arc<Transaction>>>( &mut self, tx: T, ) -> ChangeSet<A, I::ChangeSet>

Insert and index a transaction into the graph.

pub fn insert_anchor( &mut self, txid: Txid, anchor: A, ) -> ChangeSet<A, I::ChangeSet>

Insert an anchor for a given transaction.

pub fn insert_seen_at( &mut self, txid: Txid, seen_at: u64, ) -> ChangeSet<A, I::ChangeSet>

Insert a unix timestamp of when a transaction is seen in the mempool.

This is used for transaction conflict resolution in TxGraph where the transaction with the later last-seen is prioritized.

pub fn insert_evicted_at( &mut self, txid: Txid, evicted_at: u64, ) -> ChangeSet<A, I::ChangeSet>

Inserts the given evicted_at for txid.

The evicted_at timestamp represents the last known time when the transaction was observed to be missing from the mempool. If txid was previously recorded with an earlier evicted_at value, it is updated only if the new value is greater.

pub fn batch_insert_relevant_evicted_at( &mut self, evicted_ats: impl IntoIterator<Item = (Txid, u64)>, ) -> ChangeSet<A, I::ChangeSet>

Batch inserts (txid, evicted_at) pairs for txids that the graph is tracking.

The evicted_at timestamp represents the last known time when the transaction was observed to be missing from the mempool. If txid was previously recorded with an earlier evicted_at value, it is updated only if the new value is greater.

pub fn batch_insert_relevant<T: Into<Arc<Transaction>>>( &mut self, txs: impl IntoIterator<Item = (T, impl IntoIterator<Item = A>)>, ) -> ChangeSet<A, I::ChangeSet>

Batch insert transactions, filtering out those that are irrelevant.

txs do not need to be in topological order.

Relevancy is determined by the internal Indexer::is_tx_relevant implementation of I. A transaction that conflicts with a relevant transaction is also considered relevant. Irrelevant transactions in txs will be ignored.

pub fn batch_insert_relevant_unconfirmed<T: Into<Arc<Transaction>>>( &mut self, unconfirmed_txs: impl IntoIterator<Item = (T, u64)>, ) -> ChangeSet<A, I::ChangeSet>

Batch insert unconfirmed transactions, filtering out those that are irrelevant.

Relevancy is determined by the internal Indexer::is_tx_relevant implementation of I. A transaction that conflicts with a relevant transaction is also considered relevant. Irrelevant transactions in unconfirmed_txs will be ignored.

Items of txs are tuples containing the transaction and a last seen timestamp. The last seen communicates when the transaction is last seen in the mempool which is used for conflict-resolution in TxGraph (refer to TxGraph::insert_seen_at for details).

pub fn batch_insert_unconfirmed<T: Into<Arc<Transaction>>>( &mut self, txs: impl IntoIterator<Item = (T, u64)>, ) -> ChangeSet<A, I::ChangeSet>

Batch insert unconfirmed transactions.

Items of txs are tuples containing the transaction and a last seen timestamp. The last seen communicates when the transaction is last seen in the mempool which is used for conflict-resolution in TxGraph (refer to TxGraph::insert_seen_at for details).

To filter out irrelevant transactions, use batch_insert_relevant_unconfirmed instead.

impl<A, I> IndexedTxGraph<A, I>

where I::ChangeSet: Default + Merge, for<'b> A: Anchor + From<TxPosInBlock<'b>>, I: Indexer,

Methods are available if the anchor (A) can be created from TxPosInBlock.

pub fn apply_block_relevant( &mut self, block: &Block, height: u32, ) -> ChangeSet<A, I::ChangeSet>

Batch insert all transactions of the given block of height, filtering out those that are irrelevant.

Each inserted transaction’s anchor will be constructed using TxPosInBlock.

Relevancy is determined by the internal Indexer::is_tx_relevant implementation of I. A transaction that conflicts with a relevant transaction is also considered relevant. Irrelevant transactions in block will be ignored.

pub fn apply_block( &mut self, block: Block, height: u32, ) -> ChangeSet<A, I::ChangeSet>

Batch insert all transactions of the given block of height.

Each inserted transaction’s anchor will be constructed using TxPosInBlock.

To only insert relevant transactions, use apply_block_relevant instead.

impl<A, X> IndexedTxGraph<A, X>

where A: Anchor,

pub fn try_list_expected_spk_txids<'a, C, I>( &'a self, chain: &'a C, chain_tip: BlockId, spk_index_range: impl RangeBounds<I> + 'a, ) -> impl Iterator<Item = Result<(ScriptBuf, Txid), C::Error>> + 'a

where C: ChainOracle, X: AsRef<SpkTxOutIndex<I>> + 'a, I: Debug + Clone + Ord + 'a,

List txids that are expected to exist under the given spks.

This is used to fill SyncRequestBuilder::expected_spk_txids.

The spk index range can be contrained with range.

Error

If the ChainOracle implementation (chain) fails, an error will be returned with the returned item.

If the ChainOracle is infallible, list_expected_spk_txids can be used instead.

pub fn list_expected_spk_txids<'a, C, I>( &'a self, chain: &'a C, chain_tip: BlockId, spk_index_range: impl RangeBounds<I> + 'a, ) -> impl Iterator<Item = (ScriptBuf, Txid)> + 'a

where C: ChainOracle<Error = Infallible>, X: AsRef<SpkTxOutIndex<I>> + 'a, I: Debug + Clone + Ord + 'a,

List txids that are expected to exist under the given spks.

This is the infallible version of try_list_expected_spk_txids.

Trait Implementations

impl<A, I> AsRef<TxGraph<A>> for IndexedTxGraph<A, I>

fn as_ref(&self) -> &TxGraph<A>

Converts this type into a shared reference of the (usually inferred) input type.

impl<A: Clone, I: Clone> Clone for IndexedTxGraph<A, I>

fn clone(&self) -> IndexedTxGraph<A, I>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A: Debug, I: Debug> Debug for IndexedTxGraph<A, I>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A, I: Default> Default for IndexedTxGraph<A, I>

fn default() -> Self

Returns the “default value” for a type.