Struct bdk_chain::SpkTxOutIndex

source ·
pub struct SpkTxOutIndex<I> { /* private fields */ }
Expand description

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§

source§

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

source

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.
source

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).

source

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

Get a reference to the set of indexed outpoints.

source

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

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

source

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.

source

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.

source

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.

source

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.

source

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

The script pubkeys that are being tracked by the index.

source

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.

source

pub fn unused_spks<R>( &self, range: R ) -> impl DoubleEndedIterator<Item = (&I, &Script)> + Clone
where 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));
source

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.

source

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.

source

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.

source

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

Returns the index associated with the script pubkey.

source

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

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.

source

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

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.

source

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§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

impl<I> Default for SpkTxOutIndex<I>

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

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

§

type ChangeSet = ()

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

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

Scan and index the given outpoint and txout.
source§

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

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

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

Determines the ChangeSet between self and an empty Indexer.
source§

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

Apply changeset to itself.
source§

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

Determines whether the transaction should be included in the index.

Auto Trait Implementations§

§

impl<I> Freeze for SpkTxOutIndex<I>

§

impl<I> RefUnwindSafe for SpkTxOutIndex<I>
where I: RefUnwindSafe,

§

impl<I> Send for SpkTxOutIndex<I>
where I: Send,

§

impl<I> Sync for SpkTxOutIndex<I>
where I: Sync,

§

impl<I> Unpin for SpkTxOutIndex<I>
where I: Unpin,

§

impl<I> UnwindSafe for SpkTxOutIndex<I>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V