Struct bdk_chain::SpkTxOutIndex

pub struct SpkTxOutIndex<I> { /* private fields */ }

An index storing TxOuts that have a script pubkey that matches those in a list.

The basic idea is that you insert script pubkeys you care about into the index with insert_spk and then when you call Indexer::index_tx or Indexer::index_txout, the index will look at any txouts you pass in and store and index any txouts matching one of its script pubkeys.

Each script pubkey is associated with an application-defined index script index I, which must be Ord. Usually, this is used to associate the derivation index of the script pubkey or even a combination of (keychain, derivation_index).

Note there is no harm in scanning transactions that disappear from the blockchain or were never in there in the first place. SpkTxOutIndex is intentionally monotone – you cannot delete or modify txouts that have been indexed. To find out which txouts from the index are actually in the chain or unspent, you must use other sources of information like a TxGraph.

Implementations

impl<I: Clone + Ord> SpkTxOutIndex<I>

pub fn scan(&mut self, tx: &Transaction) -> BTreeSet<I>

Scans a transaction’s outputs for matching script pubkeys.

Typically, this is used in two situations:

1. After loading transaction data from the disk, you may scan over all the txouts to restore all your txouts.
2. When getting new data from the chain, you usually scan it before incorporating it into your chain state.

pub fn scan_txout(&mut self, op: OutPoint, txout: &TxOut) -> Option<&I>

Scan a single TxOut for a matching script pubkey and returns the index that matches the script pubkey (if any).

pub fn outpoints(&self) -> &BTreeSet<(I, OutPoint)>

Get a reference to the set of indexed outpoints.

pub fn txouts(
    &self
) -> impl DoubleEndedIterator<Item = (&I, OutPoint, &TxOut)> + ExactSizeIterator

Iterate over all known txouts that spend to tracked script pubkeys.

pub fn txouts_in_tx(
    &self,
    txid: Txid
) -> impl DoubleEndedIterator<Item = (&I, OutPoint, &TxOut)>

Finds all txouts on a transaction that has previously been scanned and indexed.

pub fn outputs_in_range(
    &self,
    range: impl RangeBounds<I>
) -> impl DoubleEndedIterator<Item = (&I, OutPoint)>

Iterates over all the outputs with script pubkeys in an index range.

pub fn txout(&self, outpoint: OutPoint) -> Option<(&I, &TxOut)>

Returns the txout and script pubkey index of the TxOut at OutPoint.

Returns None if the TxOut hasn’t been scanned or if nothing matching was found there.

pub fn spk_at_index(&self, index: &I) -> Option<&Script>

Returns the script that has been inserted at the index.

If that index hasn’t been inserted yet, it will return None.

pub fn all_spks(&self) -> &BTreeMap<I, ScriptBuf>

The script pubkeys that are being tracked by the index.

pub fn insert_spk(&mut self, index: I, spk: ScriptBuf) -> bool

Adds a script pubkey to scan for. Returns false and does nothing if spk already exists in the map

the index will look for outputs spending to this spk whenever it scans new data.

pub fn unused_spks<R>(
    &self,
    range: R
) -> impl DoubleEndedIterator<Item = (&I, &Script)> + Clonewhere
    R: RangeBounds<I>,

Iterates over all unused script pubkeys in an index range.

Here, “unused” means that after the script pubkey was stored in the index, the index has never scanned a transaction output with it.

Example

// imagine our spks are indexed like (keychain, derivation_index).
let txout_index = SpkTxOutIndex::<(u32, u32)>::default();
let all_unused_spks = txout_index.unused_spks(..);
let change_index = 1;
let unused_change_spks =
    txout_index.unused_spks((change_index, u32::MIN)..(change_index, u32::MAX));

pub fn is_used(&self, index: &I) -> bool

Returns whether the script pubkey at index has been used or not.

Here, “unused” means that after the script pubkey was stored in the index, the index has never scanned a transaction output with it.

pub fn mark_used(&mut self, index: &I) -> bool

Marks the script pubkey at index as used even though it hasn’t seen an output spending to it. This only affects when the index had already been added to self and was unused.

Returns whether the index was initially present as unused.

This is useful when you want to reserve a script pubkey for something but don’t want to add the transaction output using it to the index yet. Other callers will consider the index used until you call unmark_used.

pub fn unmark_used(&mut self, index: &I) -> bool

Undoes the effect of mark_used. Returns whether the index is inserted back into unused.

Note that if self has scanned an output with this script pubkey then this will have no effect.

pub fn index_of_spk(&self, script: &Script) -> Option<&I>

Returns the index associated with the script pubkey.

pub fn sent_and_received(
    &self,
    tx: &Transaction,
    range: impl RangeBounds<I>
) -> (u64, u64)

Computes the total value transfer effect tx has on the script pubkeys in range. Value is sent when a script pubkey in the range is on an input and received when it is on an output. For sent to be computed correctly, the output being spent must have already been scanned by the index. Calculating received just uses the [Transaction] outputs directly, so it will be correct even if it has not been scanned.

pub fn net_value(&self, tx: &Transaction, range: impl RangeBounds<I>) -> i64

Computes the net value transfer effect of tx on the script pubkeys in range. Shorthand for calling sent_and_received and subtracting sent from received.

pub fn is_relevant(&self, tx: &Transaction) -> bool

Whether any of the inputs of this transaction spend a txout tracked or whether any output matches one of our script pubkeys.

It is easily possible to misuse this method and get false negatives by calling it before you have scanned the TxOuts the transaction is spending. For example, if you want to filter out all the transactions in a block that are irrelevant, you must first scan all the transactions in the block and only then use this method.

Trait Implementations

impl<I: Clone> Clone for SpkTxOutIndex<I>

fn clone(&self) -> SpkTxOutIndex<I>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<I: Debug> Debug for SpkTxOutIndex<I>

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

Formats the value using the given formatter.

impl<I> Default for SpkTxOutIndex<I>

fn default() -> Self

Returns the “default value” for a type.

impl<I: Clone + Ord> Indexer for SpkTxOutIndex<I>

type ChangeSet = ()

The resultant “changeset” when new transaction data is indexed.

fn index_txout(&mut self, outpoint: OutPoint, txout: &TxOut) -> Self::ChangeSet

Scan and index the given outpoint and txout.

fn index_tx(&mut self, tx: &Transaction) -> Self::ChangeSet

Scans a transaction for relevant outpoints, which are stored and indexed internally.

fn initial_changeset(&self) -> Self::ChangeSet

Determines the ChangeSet between self and an empty Indexer.

fn apply_changeset(&mut self, _changeset: Self::ChangeSet)

Apply changeset to itself.

fn is_tx_relevant(&self, tx: &Transaction) -> bool

Determines whether the transaction should be included in the index.