Enum ProposalError 

#[non_exhaustive]
pub enum ProposalError {
    RequestTotalInvalid,
    Overflow,
    BalanceError {
        input_total: Zatoshis,
        output_total: Zatoshis,
    },
    ShieldingInvalid,
    AnchorNotFound(BlockHeight),
    MissingShieldedAnchor,
    ReferenceError(StepOutput),
    StepDoubleSpend(StepOutput),
    ChainDoubleSpend(OutputRef),
    InputsLocked(OutputRef),
    PaymentPoolsMismatch,
    SpendsChange(StepOutput),
    Zip321(Zip321Error),
    PaymentAmountMissing(usize),
    EphemeralOutputLeftUnspent(StepOutput),
    PaysTexFromShielded,
    EphemeralOutputsInvalid,
    EphemeralAddressLinkability,
    ShieldingRequiresShieldedRecipient,
    IncompatibleTxVersion(BranchId),
    OrchardReceiverRequiresIronwood(TxVersion),
    OrchardPoolValueCreation {
        input_total: Zatoshis,
        output_total: Zatoshis,
    },
    OrchardPoolPayment(usize),
    TransactionTooLarge {
        estimated_size: usize,
        limit: usize,
        sapling_input_count: usize,
        orchard_input_count: usize,
        ironwood_input_count: usize,
    },
}

Errors that can occur in construction of a Step.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

RequestTotalInvalid

The total output value of the transaction request is not a valid Zcash amount.

Overflow

The total of transaction inputs overflows the valid range of Zcash values.

BalanceError

The input total and output total of the payment request are not equal to one another. The sum of transaction outputs, change, and fees is required to be exactly equal to the value of provided inputs.

Fields

input_total: Zatoshis

output_total: Zatoshis

ShieldingInvalid

The is_shielding flag may only be set to true under the following conditions:

• The total of transparent inputs is nonzero
• There exist no Sapling inputs
• There provided transaction request is empty; i.e. the only output values specified are change and fee amounts.

AnchorNotFound(BlockHeight)

No anchor information could be obtained for the specified block height.

MissingShieldedAnchor

A proposal step produces a shielded bundle — it spends shielded notes, pays to a shielded pool, or returns shielded change — but does not specify an anchor height against which its shielded-tree lookups are performed. Only a purely transparent step may omit its anchor.

ReferenceError(StepOutput)

A reference to the output of a prior step is invalid.

StepDoubleSpend(StepOutput)

An attempted double-spend of a prior step output was detected.

ChainDoubleSpend(OutputRef)

An attempted double-spend of an output belonging to the wallet was detected.

InputsLocked(OutputRef)

An input selected by the proposal could not be locked, because a concurrent proposal or PCZT already holds a lock on it.

This is a transient condition, not a defect in the proposal itself: the wrapped output was spendable when it was selected, but another in-flight proposal locked it first. Callers should treat this as “the account is busy” and retry proposal creation; the retry will select around the locked output (or fail with an insufficient-funds error if no other outputs are available).

PaymentPoolsMismatch

There was a mismatch between the payments in the proposal’s transaction request and the payment pool selection values.

SpendsChange(StepOutput)

The proposal tried to spend a change output. Mark the ChangeValue as ephemeral if this is intended.

Zip321(Zip321Error)

The proposal results in an invalid payment request according to ZIP-321.

PaymentAmountMissing(usize)

The ZIP 321 payment request at the wrapped index lacked payment amount information.

EphemeralOutputLeftUnspent(StepOutput)

Available on crate feature transparent-inputs only.

A proposal step created an ephemeral output that was not spent in any later step.

PaysTexFromShielded

Available on crate feature transparent-inputs only.

The proposal included a payment to a TEX address and a spend from a shielded input in the same step.

EphemeralOutputsInvalid

Available on crate feature transparent-inputs only.

The change strategy provided to input selection failed to correctly generate an ephemeral change output when needed for sending to a TEX address.

EphemeralAddressLinkability

Available on crate feature transparent-inputs only.

The requested proposal would link activity on an ephemeral address to other wallet activity.

ShieldingRequiresShieldedRecipient

Available on crate feature transparent-inputs only.

A shielding proposal was constructed with a destination address that has no shielded receiver. Shielding requires the destination to be able to receive shielded value.

IncompatibleTxVersion(BranchId)

The transaction version requested is not compatible with the consensus branch for which the transaction is intended.

OrchardReceiverRequiresIronwood(TxVersion)

After NU6.3 activation, a payment to an Orchard receiver must be delivered through the Ironwood pool, which requires a version 6 transaction. The explicitly-requested transaction version has no Ironwood bundle, so it cannot carry the payment. (The Orchard turnstile is a consensus rule after NU6.3: no payment may add value to the Orchard pool, so such a payment cannot be delivered as a plain Orchard output either.)

OrchardPoolValueCreation

Available on crate feature orchard only.

After Ironwood activation, a proposal step would create value in the Orchard pool. The turnstile only permits value to leave the pool: a step may return change to it only when strictly less value returns than the step’s Orchard inputs remove. (Payments may never be directed to the Orchard pool after Ironwood activation; payment classification maintains that invariant, and step construction enforces it via ProposalError::OrchardPoolPayment.)

Fields

input_total: Zatoshis

The total value of the Orchard notes spent by the step.

output_total: Zatoshis

The total value of the Orchard-pool change outputs created by the step.

OrchardPoolPayment(usize)

Available on crate feature orchard only.

After Ironwood activation, the payment at the wrapped index of the step’s transaction request was directed to the Orchard pool. The turnstile only permits value to leave the pool, so no payment may be directed to it; payment classification routes Orchard-receiver payments to the Ironwood pool instead.

TransactionTooLarge

The transaction the step describes would exceed the maximum size a Zcash block may carry, and so cannot be included in any block. The serialized size of the step’s transaction was estimated from its inputs, outputs, and change, using conservative per-element byte costs; the estimate exceeds MAX_BLOCK_BYTES.

MAX_BLOCK_BYTES is the block size limit, not a per-transaction limit: a transaction that fits just under it still cannot be mined, because the block must also carry its header and coinbase transaction. Passing the gate is therefore necessary but not sufficient for mineability near the boundary; the builder is the final authority.

Recovery for a caller that receives this error: reduce the number of inputs by lowering the payment amount or by consolidating small notes via send-to-self transactions before retrying. Each consolidation round must be mined and its note commitments anchored before the resulting notes are spendable, so recovery spans multiple confirmations. For propose_send_max this error is a dead end — there is no smaller amount to back off to — and requires a multi-transaction strategy.

Fields

estimated_size: usize

The conservative upper-bound estimate of the step’s serialized byte size.

limit: usize

The maximum serialized byte size a Zcash block may carry (MAX_BLOCK_BYTES).

sapling_input_count: usize

The number of Sapling inputs the step spends, including prior-step inputs. Carried so a wallet can explain the situation in terms of notes rather than bytes; the different shielded pools have very different per-input costs.

orchard_input_count: usize

Available on crate feature orchard only.

The number of Orchard inputs the step spends, including prior-step inputs.

ironwood_input_count: usize

Available on crate feature orchard only.

The number of Ironwood inputs the step spends, including prior-step inputs.

Trait Implementations

impl Clone for ProposalError

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ProposalError

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

Formats the value using the given formatter.

impl Display for ProposalError

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

Formats the value using the given formatter.

impl Error for ProposalError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl<DE, TE, SE, FE, CE, N> From<ProposalError> for Error<DE, TE, SE, FE, CE, N>

fn from(e: ProposalError) -> Self

Converts to this type from the input type.

impl<E, S, C, N> From<ProposalError> for InputSelectorError<E, S, C, N>

fn from(err: ProposalError) -> Self

Converts to this type from the input type.