zcash_client_backend::data_api::wallet::input_selection

Trait ShieldingSelector

pub trait ShieldingSelector {
    type Error;
    type InputSource: InputSource;

    // Required methods
    fn propose_shielding<ParamsT, ChangeT>(
        &self,
        params: &ParamsT,
        wallet_db: &Self::InputSource,
        change_strategy: &ChangeT,
        shielding_threshold: Zatoshis,
        source_addrs: &[TransparentAddress],
        to_account: <Self::InputSource as InputSource>::AccountId,
        target_height: TargetHeight,
        anchor_height: BlockHeight,
        zip318: &PoolMigrationParams,
        confirmations_policy: ConfirmationsPolicy,
        output_filter: CoinbaseFilter,
    ) -> Result<Proposal<<ChangeT as ChangeStrategy>::FeeRule, Infallible>, InputSelectorError<<Self::InputSource as InputSource>::Error, Self::Error, ChangeT::Error, Infallible>>
       where ParamsT: Parameters,
             ChangeT: ChangeStrategy<MetaSource = Self::InputSource>;
    fn propose_shielding_coinbase<ParamsT, FeeRuleT>(
        &self,
        params: &ParamsT,
        wallet_db: &Self::InputSource,
        fee_rule: &FeeRuleT,
        shielding_threshold: Zatoshis,
        source_addrs: &[TransparentAddress],
        to_address: ZcashAddress,
        memo: Option<MemoBytes>,
        limit: Option<usize>,
        target_height: TargetHeight,
        anchor_height: BlockHeight,
    ) -> Result<Proposal<FeeRuleT, Infallible>, InputSelectorError<<Self::InputSource as InputSource>::Error, Self::Error, FeeRuleT::Error, Infallible>>
       where ParamsT: Parameters,
             FeeRuleT: FeeRule + Clone;
}

Available on crate feature transparent-inputs only.

Expand description

A strategy for selecting transaction inputs and proposing transaction outputs for shielding-only transactions (transactions which spend transparent UTXOs and send all transaction outputs to the wallet’s shielded internal address(es)).

Required Associated Types§

Source

type Error

The type of errors that may be generated in input selection

Source

type InputSource: InputSource

The type of data source that the input selector expects to access to obtain input transparent UTXOs. This associated type permits input selectors that may use specialized knowledge of the internals of a particular backing data store, if the generic API of InputSource does not provide sufficiently fine-grained operations for a particular backing store to optimally perform input selection.

Required Methods§

Source

fn propose_shielding<ParamsT, ChangeT>( &self, params: &ParamsT, wallet_db: &Self::InputSource, change_strategy: &ChangeT, shielding_threshold: Zatoshis, source_addrs: &[TransparentAddress], to_account: <Self::InputSource as InputSource>::AccountId, target_height: TargetHeight, anchor_height: BlockHeight, zip318: &PoolMigrationParams, confirmations_policy: ConfirmationsPolicy, output_filter: CoinbaseFilter, ) -> Result<Proposal<<ChangeT as ChangeStrategy>::FeeRule, Infallible>, InputSelectorError<<Self::InputSource as InputSource>::Error, Self::Error, ChangeT::Error, Infallible>>
where ParamsT: Parameters, ChangeT: ChangeStrategy<MetaSource = Self::InputSource>,

Performs input selection and returns a proposal for the construction of a shielding transaction.

Implementations should return the maximum possible number of economically useful inputs required to supply at least the requested value, choosing only inputs received at the specified source addresses. If insufficient funds are available to satisfy the required outputs for the shielding request, this operation must fail and return InputSelectorError::InsufficientFunds.

The output_filter parameter controls which transparent outputs are eligible for inclusion in the proposal. See CoinbaseFilter for details.

Source

fn propose_shielding_coinbase<ParamsT, FeeRuleT>( &self, params: &ParamsT, wallet_db: &Self::InputSource, fee_rule: &FeeRuleT, shielding_threshold: Zatoshis, source_addrs: &[TransparentAddress], to_address: ZcashAddress, memo: Option<MemoBytes>, limit: Option<usize>, target_height: TargetHeight, anchor_height: BlockHeight, ) -> Result<Proposal<FeeRuleT, Infallible>, InputSelectorError<<Self::InputSource as InputSource>::Error, Self::Error, FeeRuleT::Error, Infallible>>
where ParamsT: Parameters, FeeRuleT: FeeRule + Clone,

Performs input selection and returns a proposal for the construction of a transaction that shields coinbase transparent outputs to an arbitrary shielded recipient.

This method differs from Self::propose_shielding in the following ways:

Only coinbase transparent outputs are eligible for inclusion in the proposal. This restriction is hard-coded; callers cannot opt in to selecting non-coinbase outputs via this method. Coinbase outputs are uniquely suited to being sent to arbitrary shielded recipients because they have no prior transparent transaction graph that could be exposed to the recipient.
The to_address argument specifies the destination of the shielded value. It must be a shielded address (Sapling, or a Unified Address with a shielded receiver). It may be an external address not belonging to any account we control.
The resulting proposal carries an explicit ZIP-321 payment to to_address for the full available value (input total minus fee). No change is produced, in either the transparent or any shielded pool. This is a privacy invariant: producing a shielded change output would allow the recipient (or any chain observer) to learn the sender’s total selected-coinbase value by summing the public transparent input values and subtracting the visible payment amount. Since this method targets the z_shieldcoinbase-style “sweep coinbase to a recipient” workflow, where the recipient may not belong to the sender’s wallet, change is forbidden by design.

Because no change is produced, this method takes a fee_rule directly rather than a ChangeStrategy: there is no change to compute, and no per-account metadata is required.

The memo parameter is stored in the shielded output’s memo field; it is always permitted because a shielded payment is always present.

The limit parameter, when Some(n), caps the number of transparent inputs to at most n, keeping the highest-value UTXOs (with a stable tiebreaker by outpoint). Some(0) selects no inputs and will therefore return InputSelectorError::InsufficientFunds.

If the total value of selected inputs (after any cap imposed by limit), minus the fee, is less than shielding_threshold, this method returns InputSelectorError::InsufficientFunds.