Trait InputSource 

pub trait InputSource {
    type Error: Debug;
    type AccountId: Copy + Debug + Eq + Hash;
    type NoteRef: Copy + Debug + Eq + Ord;

    // Required methods
    fn get_spendable_note(
        &self,
        txid: &TxId,
        protocol: ShieldedPool,
        index: u32,
        target_height: TargetHeight,
        lock_filter: LockFilter<'_>,
    ) -> Result<Option<ReceivedNote<Self::NoteRef, Note>>, Self::Error>;
    fn anchor_computable(
        &self,
        protocol: ShieldedPool,
        height: BlockHeight,
    ) -> Result<bool, Self::Error>;
    fn select_spendable_notes(
        &self,
        account: Self::AccountId,
        target_value: TargetValue,
        sources: &[ShieldedPool],
        target_height: TargetHeight,
        confirmations_policy: ConfirmationsPolicy,
        exclude: &[Self::NoteRef],
        lock_filter: LockFilter<'_>,
    ) -> Result<ReceivedNotes<Self::NoteRef>, Self::Error>;
    fn select_unspent_notes(
        &self,
        account: Self::AccountId,
        sources: &[ShieldedPool],
        target_height: TargetHeight,
        exclude: &[Self::NoteRef],
        lock_filter: LockFilter<'_>,
    ) -> Result<ReceivedNotes<Self::NoteRef>, Self::Error>;
    fn get_change_receivers(
        &self,
        account: Self::AccountId,
    ) -> Result<ChangeReceivers, Self::Error>;
    fn get_account_metadata(
        &self,
        account: Self::AccountId,
        selector: &NoteFilter,
        target_height: TargetHeight,
        exclude: &[Self::NoteRef],
        lock_filter: LockFilter<'_>,
    ) -> Result<AccountMeta, Self::Error>;

    // Provided methods
    fn select_single_spendable_note(
        &self,
        account: Self::AccountId,
        value: Zatoshis,
        sources: &[ShieldedPool],
        target_height: TargetHeight,
        confirmations_policy: ConfirmationsPolicy,
        exclude: &[Self::NoteRef],
        lock_filter: LockFilter<'_>,
    ) -> Result<ReceivedNotes<Self::NoteRef>, Self::Error> { ... }
    fn get_unspent_transparent_output(
        &self,
        _outpoint: &OutPoint,
        _target_height: TargetHeight,
    ) -> Result<Option<WalletTransparentOutput<Self::AccountId>>, Self::Error> { ... }
    fn get_spendable_transparent_outputs(
        &self,
        _address: &TransparentAddress,
        _target_height: TargetHeight,
        _confirmations_policy: ConfirmationsPolicy,
        _output_filter: CoinbaseFilter,
        _lock_filter: LockFilter<'_>,
    ) -> Result<Vec<WalletTransparentOutput<Self::AccountId>>, Self::Error> { ... }
    fn get_spendable_transparent_outputs_for_addresses(
        &self,
        addresses: &[TransparentAddress],
        target_height: TargetHeight,
        confirmations_policy: ConfirmationsPolicy,
        output_filter: CoinbaseFilter,
        lock_filter: LockFilter<'_>,
    ) -> Result<Vec<WalletTransparentOutput<Self::AccountId>>, Self::Error> { ... }
    fn select_spendable_transparent_outputs(
        &self,
        account: Self::AccountId,
        target_height: TargetHeight,
        confirmations_policy: ConfirmationsPolicy,
        output_filter: CoinbaseFilter,
        address_allow_list: Option<&[TransparentAddress]>,
        target_value: TargetValue,
        max_inputs: usize,
        fee_rule: &StandardFeeRule,
        lock_filter: LockFilter<'_>,
    ) -> Result<Vec<WalletTransparentOutput<Self::AccountId>>, Self::Error> { ... }
}

A trait representing the capability to query a data store for unspent transaction outputs belonging to a account.

Required Associated Types

type Error: Debug

The type of errors produced by a wallet backend.

type AccountId: Copy + Debug + Eq + Hash

Backend-specific account identifier.

An account identifier corresponds to at most a single unified spending key’s worth of spend authority, such that both received notes and change spendable by that spending authority will be interpreted as belonging to that account. This might be a database identifier type or a UUID.

type NoteRef: Copy + Debug + Eq + Ord

Backend-specific note identifier.

For example, this might be a database identifier type or a UUID.

Required Methods

fn get_spendable_note( &self, txid: &TxId, protocol: ShieldedPool, index: u32, target_height: TargetHeight, lock_filter: LockFilter<'_>, ) -> Result<Option<ReceivedNote<Self::NoteRef, Note>>, Self::Error>

Fetches a spendable note by indexing into a transaction’s shielded outputs for the specified shielded protocol.

Returns Ok(None) if the note is not known to belong to the wallet or if the note is not spendable as of the given height. Locked outputs are selected according to lock_filter (see LockFilter; a LockFilter::Policy carrying the default LockedInputPolicy::Exclude selects none).

fn anchor_computable( &self, protocol: ShieldedPool, height: BlockHeight, ) -> Result<bool, Self::Error>

Returns whether an anchor is COMPUTABLE at height for spends from the given pool: whether this data source can produce the note commitment tree root, and witnesses to it, as of the end of that block.

A height inside the wallet’s scanned range need not qualify: tree states are only materialized at the heights the wallet chose to retain, and a wallet that scanned past NU6.3 activation before boundary checkpointing was repaired is permanently missing the anchor-retention boundaries whose blocks carried no shielded outputs. Such a hole cannot be backfilled from local state, so a caller deciding whether to anchor at a retained boundary should consult this before committing to it, and fall back rather than propose a transaction that cannot be built.

fn select_spendable_notes( &self, account: Self::AccountId, target_value: TargetValue, sources: &[ShieldedPool], target_height: TargetHeight, confirmations_policy: ConfirmationsPolicy, exclude: &[Self::NoteRef], lock_filter: LockFilter<'_>, ) -> Result<ReceivedNotes<Self::NoteRef>, Self::Error>

Returns a list of spendable notes sufficient to cover the specified target value, if possible. Only spendable notes from the pools in sources will be included, and a note in exclude is never returned. Locked outputs are selected according to lock_filter (see LockFilter; a LockFilter::Policy carrying the default Exclude selects none).

fn select_unspent_notes( &self, account: Self::AccountId, sources: &[ShieldedPool], target_height: TargetHeight, exclude: &[Self::NoteRef], lock_filter: LockFilter<'_>, ) -> Result<ReceivedNotes<Self::NoteRef>, Self::Error>

Returns the list of notes belonging to the wallet that are unspent as of the specified target height. Locked outputs are selected according to lock_filter (see LockFilter; a LockFilter::Policy carrying the default Exclude selects none).

fn get_change_receivers( &self, account: Self::AccountId, ) -> Result<ChangeReceivers, Self::Error>

Returns the outputs in which the specified account can receive change.

Returns an error if the account is not known to the wallet.

fn get_account_metadata( &self, account: Self::AccountId, selector: &NoteFilter, target_height: TargetHeight, exclude: &[Self::NoteRef], lock_filter: LockFilter<'_>, ) -> Result<AccountMeta, Self::Error>

Returns metadata describing the structure of the wallet for the specified account.

The returned metadata value must exclude:

• notes that are not considered spendable as of the given target_height
• unspent notes excluded by the provided selector;
• unspent notes identified in the given exclude list.
• locked notes not admitted by lock_filter (see LockFilter; a LockFilter::Policy carrying the default Exclude admits none).

Implementations of this method may limit the complexity of supported queries. Such limitations should be clearly documented for the implementing type.

Provided Methods

fn select_single_spendable_note( &self, account: Self::AccountId, value: Zatoshis, sources: &[ShieldedPool], target_height: TargetHeight, confirmations_policy: ConfirmationsPolicy, exclude: &[Self::NoteRef], lock_filter: LockFilter<'_>, ) -> Result<ReceivedNotes<Self::NoteRef>, Self::Error>

Returns the OLDEST single spendable note whose value alone is at least value, drawn from the first pool in sources (in the given preference order) that holds one. A note in exclude is never returned. The returned collection contains at most one note; it is empty when no single eligible note covers the value.

This is the selection primitive behind NoteSelection::PreferSingle: a ZIP 318 migration transfer spends exactly one note, so a canonical pool crossing must be funded from one.

The default implementation is BEST-EFFORT: it reports a note only when Self::select_spendable_notes happens to surface one that covers the value on its own. An implementation backed by a queryable store should override it with a direct query, so that a covering note is found whenever one exists.

fn get_unspent_transparent_output( &self, _outpoint: &OutPoint, _target_height: TargetHeight, ) -> Result<Option<WalletTransparentOutput<Self::AccountId>>, Self::Error>

Available on crate feature transparent-inputs only.

Fetches the transparent output corresponding to the provided outpoint if it is considered spendable as of the provided target_height.

Returns Ok(None) if the UTXO is not known to belong to the wallet or would not be spendable in a transaction mined in the block at the target height.

fn get_spendable_transparent_outputs( &self, _address: &TransparentAddress, _target_height: TargetHeight, _confirmations_policy: ConfirmationsPolicy, _output_filter: CoinbaseFilter, _lock_filter: LockFilter<'_>, ) -> Result<Vec<WalletTransparentOutput<Self::AccountId>>, Self::Error>

Available on crate feature transparent-inputs only.

Returns the list of unspent transparent outputs received by this wallet at address such that, at height target_height:

• the transaction that produced the output had or will have at least the required number of confirmations according to the provided ConfirmationsPolicy; and
• the output can potentially be spent in a transaction mined in a block at the given target_height (also taking into consideration the coinbase maturity rule).

The output_filter parameter controls which transparent outputs are eligible. When set to CoinbaseFilter::CoinbaseOnly, only outputs from coinbase transactions should be returned.

Any output that is potentially spent by an unmined transaction in the mempool should be excluded unless the spending transaction will be expired at target_height. Locked outputs are selected according to lock_filter (see LockFilter; a LockFilter::Policy carrying the default Exclude selects none).

fn get_spendable_transparent_outputs_for_addresses( &self, addresses: &[TransparentAddress], target_height: TargetHeight, confirmations_policy: ConfirmationsPolicy, output_filter: CoinbaseFilter, lock_filter: LockFilter<'_>, ) -> Result<Vec<WalletTransparentOutput<Self::AccountId>>, Self::Error>

Available on crate feature transparent-inputs only.

Returns the list of spendable transparent outputs received by this wallet at any of the given addresses, subject to the same spendability conditions as InputSource::get_spendable_transparent_outputs.

This is the batched equivalent of calling InputSource::get_spendable_transparent_outputs once per address. It exists so that data stores can satisfy a multi-address request with a single query rather than one query per address, which is prohibitively expensive for wallets that hold large numbers of transparent addresses (as occurs when shielding). The default implementation simply iterates over addresses; data stores should override it with a batched query where possible.

Each returned output identifies its receiving address via WalletTransparentOutput::recipient_address.

fn select_spendable_transparent_outputs( &self, account: Self::AccountId, target_height: TargetHeight, confirmations_policy: ConfirmationsPolicy, output_filter: CoinbaseFilter, address_allow_list: Option<&[TransparentAddress]>, target_value: TargetValue, max_inputs: usize, fee_rule: &StandardFeeRule, lock_filter: LockFilter<'_>, ) -> Result<Vec<WalletTransparentOutput<Self::AccountId>>, Self::Error>

Available on crate feature transparent-inputs only.

Returns the spendable transparent outputs received by account whose total post-fee value (sum of values minus the cumulative marginal fee cost of the gathered inputs themselves, per fee_rule) is at least target_value, or max_inputs outputs (whichever is reached first).

The gather is intended to scale to wallets with large numbers of transparent addresses and UTXOs: it returns a value-bounded subset rather than every spendable output, so the selector does not need to materialize the wallet’s full UTXO set. Data stores should implement this with a single query that orders eligible UTXOs by descending value and accumulates them, recomputing the cumulative fee via fee_rule at each step, stopping once the post-fee cumulative value meets the bound. This produces a tighter result than a static value bound, without requiring a separate round trip to correct an under-estimated headroom.

max_inputs bounds the number of transparent inputs a single transaction may consume, independent of target_value: even a small requested value could otherwise require an unbounded number of inputs for a wallet holding a very large number of small (e.g. dust) UTXOs. When the cap is reached before the value target, the returned set’s post-fee value may be less than target_value; the caller’s input-selection loop is expected to surface this as an InsufficientFunds error, the same as for any other value shortfall.

fee_rule is fixed to StandardFeeRule (rather than being generic over the caller’s actual ChangeStrategy) so that implementations of this method do not need to be generic over an arbitrary fee rule type. This is a heuristic bound only: the transaction’s real fee is still computed by the caller’s actual change strategy, and if this gather’s estimate turns out to be insufficient, the caller’s input-selection loop will surface an InsufficientFunds error and can re-invoke this method with a corrected target_value.

For TargetValue::AllFunds, no value bound is applied and the gather returns every eligible output up to max_inputs.

When address_allow_list is Some, only outputs received at one of the listed transparent addresses are eligible; when None, outputs received at any of the account’s transparent addresses are eligible. The restriction must be applied within the gather (not to its results), so that outputs excluded by the allow list do not consume the value bound.

This is the value-bounded counterpart to InputSource::get_spendable_transparent_outputs and InputSource::get_spendable_transparent_outputs_for_addresses, intended for use by general (non-shielding) input selection in propose_transaction.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl InputSource for FixedNotes

Available on crate features test-dependencies only.

type Error = FixedNotesError

type AccountId = u32

type NoteRef = u32

impl InputSource for MockWalletDb

Available on crate features test-dependencies only.

type Error = ()

type NoteRef = u32

type AccountId = u32