Enum zebra_chain::transaction::Transaction

pub enum Transaction {
    V1 {
        inputs: Vec<Input>,
        outputs: Vec<Output>,
        lock_time: LockTime,
    },
    V2 {
        inputs: Vec<Input>,
        outputs: Vec<Output>,
        lock_time: LockTime,
        joinsplit_data: Option<JoinSplitData<Bctv14Proof>>,
    },
    V3 {
        inputs: Vec<Input>,
        outputs: Vec<Output>,
        lock_time: LockTime,
        expiry_height: Height,
        joinsplit_data: Option<JoinSplitData<Bctv14Proof>>,
    },
    V4 {
        inputs: Vec<Input>,
        outputs: Vec<Output>,
        lock_time: LockTime,
        expiry_height: Height,
        joinsplit_data: Option<JoinSplitData<Groth16Proof>>,
        sapling_shielded_data: Option<ShieldedData<PerSpendAnchor>>,
    },
    V5 {
        network_upgrade: NetworkUpgrade,
        lock_time: LockTime,
        expiry_height: Height,
        inputs: Vec<Input>,
        outputs: Vec<Output>,
        sapling_shielded_data: Option<ShieldedData<SharedAnchor>>,
        orchard_shielded_data: Option<ShieldedData>,
    },
}

A Zcash transaction.

A transaction is an encoded data structure that facilitates the transfer of value between two public key addresses on the Zcash ecosystem. Everything is designed to ensure that transactions can be created, propagated on the network, validated, and finally added to the global ledger of transactions (the blockchain).

Zcash has a number of different transaction formats. They are represented internally by different enum variants. Because we checkpoint on Canopy activation, we do not validate any pre-Sapling transaction types.

Variants

V1

A fully transparent transaction (version = 1).

Fields

inputs: Vec<Input>

The transparent inputs to the transaction.

outputs: Vec<Output>

The transparent outputs from the transaction.

lock_time: LockTime

The earliest time or block height that this transaction can be added to the chain.

V2

A Sprout transaction (version = 2).

Fields

inputs: Vec<Input>

The transparent inputs to the transaction.

outputs: Vec<Output>

The transparent outputs from the transaction.

lock_time: LockTime

The earliest time or block height that this transaction can be added to the chain.

joinsplit_data: Option<JoinSplitData<Bctv14Proof>>

The JoinSplit data for this transaction, if any.

V3

An Overwinter transaction (version = 3).

Fields

inputs: Vec<Input>

The transparent inputs to the transaction.

outputs: Vec<Output>

The transparent outputs from the transaction.

lock_time: LockTime

The earliest time or block height that this transaction can be added to the chain.

expiry_height: Height

The latest block height that this transaction can be added to the chain.

joinsplit_data: Option<JoinSplitData<Bctv14Proof>>

The JoinSplit data for this transaction, if any.

V4

A Sapling transaction (version = 4).

Fields

inputs: Vec<Input>

The transparent inputs to the transaction.

outputs: Vec<Output>

The transparent outputs from the transaction.

lock_time: LockTime

The earliest time or block height that this transaction can be added to the chain.

expiry_height: Height

The latest block height that this transaction can be added to the chain.

joinsplit_data: Option<JoinSplitData<Groth16Proof>>

The JoinSplit data for this transaction, if any.

sapling_shielded_data: Option<ShieldedData<PerSpendAnchor>>

The sapling shielded data for this transaction, if any.

V5

A version = 5 transaction , which supports Orchard, Sapling, and transparent, but not Sprout.

Fields

network_upgrade: NetworkUpgrade

The Network Upgrade for this transaction.

Derived from the ConsensusBranchId field.

lock_time: LockTime

The earliest time or block height that this transaction can be added to the chain.

expiry_height: Height

The latest block height that this transaction can be added to the chain.

inputs: Vec<Input>

The transparent inputs to the transaction.

outputs: Vec<Output>

The transparent outputs from the transaction.

sapling_shielded_data: Option<ShieldedData<SharedAnchor>>

The sapling shielded data for this transaction, if any.

orchard_shielded_data: Option<ShieldedData>

The orchard data for this transaction, if any.

Implementations

impl Transaction

pub fn new_v5_coinbase( network: &Network, height: Height, outputs: impl IntoIterator<Item = (Amount<NonNegative>, Script)>, extra_coinbase_data: Vec<u8>, ) -> Transaction

Returns a new version 5 coinbase transaction for network and height, which contains the specified outputs.

pub fn new_v4_coinbase( _network: &Network, height: Height, outputs: impl IntoIterator<Item = (Amount<NonNegative>, Script)>, like_zcashd: bool, extra_coinbase_data: Vec<u8>, ) -> Transaction

Returns a new version 4 coinbase transaction for network and height, which contains the specified outputs.

If like_zcashd is true, try to match the coinbase transactions generated by zcashd in the getblocktemplate RPC.

impl Transaction

pub fn v1_strategy(ledger_state: LedgerState) -> BoxedStrategy<Self>

Generate a proptest strategy for V1 Transactions

pub fn v2_strategy(ledger_state: LedgerState) -> BoxedStrategy<Self>

Generate a proptest strategy for V2 Transactions

pub fn v3_strategy(ledger_state: LedgerState) -> BoxedStrategy<Self>

Generate a proptest strategy for V3 Transactions

pub fn v4_strategy(ledger_state: LedgerState) -> BoxedStrategy<Self>

Generate a proptest strategy for V4 Transactions

pub fn v5_strategy(ledger_state: LedgerState) -> BoxedStrategy<Self>

Generate a proptest strategy for V5 Transactions

pub fn vec_strategy( ledger_state: LedgerState, len: usize, ) -> BoxedStrategy<Vec<Arc<Self>>>

Proptest Strategy for creating a Vector of transactions where the first transaction is always the only coinbase transaction

pub fn for_each_value_mut<F>(&mut self, f: F)

where F: FnMut(&mut Amount<NonNegative>),

Apply f to the transparent output, v_sprout_new, and v_sprout_old values in this transaction, regardless of version.

pub fn for_each_value_balance_mut<F>(&mut self, f: F)

where F: FnMut(&mut Amount<NegativeAllowed>),

Apply f to the sapling value balance and orchard value balance in this transaction, regardless of version.

pub fn fix_overflow(&mut self)

Fixup transparent values and shielded value balances, so that transaction and chain value pools won’t overflow MAX_MONEY.

These fixes are applied to coinbase and non-coinbase transactions.

pub fn fix_chain_value_pools( &mut self, chain_value_pools: ValueBalance<NonNegative>, outputs: &HashMap<OutPoint, Output>, ) -> Result<(Amount<NonNegative>, ValueBalance<NonNegative>), ValueBalanceError>

Fixup transparent values and shielded value balances, so that this transaction passes the “non-negative chain value pool” checks. (These checks use the sum of unspent outputs for each transparent and shielded pool.)

These fixes are applied to coinbase and non-coinbase transactions.

chain_value_pools contains the chain value pool balances, as of the previous transaction in this block (or the last transaction in the previous block).

outputs must contain all the transparent::Outputs spent in this transaction.

Currently, these fixes almost always leave some remaining value in each transparent and shielded chain value pool.

Before fixing the chain value balances, this method calls fix_overflow to make sure that transaction and chain value pools don’t overflow MAX_MONEY.

After fixing the chain value balances, this method calls fix_remaining_value to fix the remaining value in the transaction value pool.

Returns the remaining transaction value, and the updated chain value balances.

Panics

If any spent transparent::Output is missing from transparent::OutPoints.

fn input_value_pool( &self, outputs: &HashMap<OutPoint, Output>, ) -> Result<Amount<NonNegative>, ValueBalanceError>

Returns the total input value of this transaction’s value pool.

This is the sum of transparent inputs, sprout input values, and if positive, the sapling and orchard value balances.

outputs must contain all the transparent::Outputs spent in this transaction.

pub fn fix_remaining_value( &mut self, outputs: &HashMap<OutPoint, Output>, ) -> Result<Amount<NonNegative>, ValueBalanceError>

Fixup non-coinbase transparent values and shielded value balances, so that this transaction passes the “non-negative remaining transaction value” check. (This check uses the sum of inputs minus outputs.)

Returns the remaining transaction value.

outputs must contain all the transparent::Outputs spent in this transaction.

Currently, these fixes almost always leave some remaining value in the transaction value pool.

Panics

If any spent transparent::Output is missing from transparent::OutPoints.

impl Transaction

pub fn hash(&self) -> Hash

Compute the hash (mined transaction ID) of this transaction.

The hash uniquely identifies mined v5 transactions, and all v1-v4 transactions, whether mined or unmined.

pub fn unmined_id(&self) -> UnminedTxId

Compute the unmined transaction ID of this transaction.

This ID uniquely identifies unmined transactions, regardless of version.

pub fn sighash( &self, branch_id: ConsensusBranchId, hash_type: HashType, all_previous_outputs: &[Output], input_index_script_code: Option<(usize, Vec<u8>)>, ) -> SigHash

Calculate the sighash for the current transaction.

If you need to compute multiple sighashes for the same transactions, it’s more efficient to use Transaction::sighasher().

Details

all_previous_outputs represents the UTXOs being spent by each input in the transaction.

The input_index_script_code tuple indicates the index of the transparent Input for which we are producing a sighash and the respective script code being validated, or None if it’s a shielded input.

Panics

• if passed in any NetworkUpgrade from before NetworkUpgrade::Overwinter
• if called on a v1 or v2 transaction
• if the input index points to a transparent::Input::CoinBase
• if the input index is out of bounds for self.inputs()

pub fn sighasher<'a>( &'a self, branch_id: ConsensusBranchId, all_previous_outputs: &'a [Output], ) -> SigHasher<'a>

Return a SigHasher for this transaction.

pub fn auth_digest(&self) -> Option<AuthDigest>

Compute the authorizing data commitment of this transaction as specified in ZIP-244.

Returns None for pre-v5 transactions.

pub fn has_transparent_or_shielded_inputs(&self) -> bool

Does this transaction have transparent or shielded inputs?

pub fn has_shielded_inputs(&self) -> bool

Does this transaction have shielded inputs?

See Self::has_transparent_or_shielded_inputs for details.

pub fn has_transparent_or_shielded_outputs(&self) -> bool

Does this transaction have transparent or shielded outputs?

pub fn has_shielded_outputs(&self) -> bool

Does this transaction have shielded outputs?

See Self::has_transparent_or_shielded_outputs for details.

pub fn has_enough_orchard_flags(&self) -> bool

Does this transaction has at least one flag when we have at least one orchard action?

pub fn coinbase_spend_restriction( &self, spend_height: Height, ) -> CoinbaseSpendRestriction

Returns the CoinbaseSpendRestriction for this transaction, assuming it is mined at spend_height.

pub fn is_overwintered(&self) -> bool

Return if the fOverwintered flag of this transaction is set.

pub fn version(&self) -> u32

Return the version of this transaction.

pub fn lock_time(&self) -> Option<LockTime>

Get this transaction’s lock time.

pub fn raw_lock_time(&self) -> u32

Get the raw lock time value.

pub fn lock_time_is_time(&self) -> bool

Returns true if this transaction’s lock_time is a LockTime::Time. Returns false if it is a LockTime::Height (locked or unlocked), is unlocked, or if the transparent input sequence numbers have disabled lock times.

pub fn expiry_height(&self) -> Option<Height>

Get this transaction’s expiry height, if any.

pub fn expiry_height_mut(&mut self) -> &mut Height

Modify the expiry height of this transaction.

Panics

• if called on a v1 or v2 transaction

pub fn network_upgrade(&self) -> Option<NetworkUpgrade>

Get this transaction’s network upgrade field, if any. This field is serialized as nConsensusBranchId (7.1).

pub fn inputs(&self) -> &[Input]

Access the transparent inputs of this transaction, regardless of version.

pub fn inputs_mut(&mut self) -> &mut Vec<Input>

Modify the transparent inputs of this transaction, regardless of version.

pub fn spent_outpoints(&self) -> impl Iterator<Item = OutPoint> + '_

Access the transparent::OutPoints spent by this transaction’s transparent::Inputs.

pub fn outputs(&self) -> &[Output]

Access the transparent outputs of this transaction, regardless of version.

pub fn outputs_mut(&mut self) -> &mut Vec<Output>

Modify the transparent outputs of this transaction, regardless of version.

pub fn is_coinbase(&self) -> bool

Returns true if this transaction has valid inputs for a coinbase transaction, that is, has a single input and it is a coinbase input (null prevout).

pub fn is_valid_non_coinbase(&self) -> bool

Returns true if this transaction has valid inputs for a non-coinbase transaction, that is, does not have any coinbase input (non-null prevouts).

Note that it’s possible for a transaction return false in both Transaction::is_coinbase and Transaction::is_valid_non_coinbase, though those transactions will be rejected.

pub fn sprout_groth16_joinsplits( &self, ) -> Box<dyn Iterator<Item = &JoinSplit<Groth16Proof>> + '_>

Returns the Sprout JoinSplit<Groth16Proof>s in this transaction, regardless of version.

pub fn joinsplit_count(&self) -> usize

Returns the number of JoinSplits in this transaction, regardless of version.

pub fn sprout_nullifiers(&self) -> Box<dyn Iterator<Item = &Nullifier> + '_>

Access the sprout::Nullifiers in this transaction, regardless of version.

pub fn sprout_joinsplit_pub_key(&self) -> Option<VerificationKeyBytes>

Access the JoinSplit public validating key in this transaction, regardless of version, if any.

pub fn has_sprout_joinsplit_data(&self) -> bool

Return if the transaction has any Sprout JoinSplit data.

pub fn sprout_note_commitments( &self, ) -> Box<dyn Iterator<Item = &NoteCommitment> + '_>

Returns the Sprout note commitments in this transaction.

pub fn sapling_anchors(&self) -> Box<dyn Iterator<Item = Root> + '_>

Access the deduplicated sapling::tree::Roots in this transaction, regardless of version.

pub fn sapling_spends_per_anchor( &self, ) -> Box<dyn Iterator<Item = Spend<PerSpendAnchor>> + '_>

Iterate over the sapling Spends for this transaction, returning Spend<PerSpendAnchor> regardless of the underlying transaction version.

Shared anchors in V5 transactions are copied into each sapling spend. This allows the same code to validate spends from V4 and V5 transactions.

Correctness

Do not use this function for serialization.

pub fn sapling_outputs(&self) -> Box<dyn Iterator<Item = &Output> + '_>

Iterate over the sapling Outputs for this transaction

pub fn sapling_nullifiers(&self) -> Box<dyn Iterator<Item = &Nullifier> + '_>

Access the sapling::Nullifiers in this transaction, regardless of version.

pub fn sapling_note_commitments(&self) -> Box<dyn Iterator<Item = &Fq> + '_>

Returns the Sapling note commitments in this transaction, regardless of version.

pub fn has_sapling_shielded_data(&self) -> bool

Return if the transaction has any Sapling shielded data.

pub fn orchard_shielded_data(&self) -> Option<&ShieldedData>

Access the orchard::ShieldedData in this transaction, regardless of version.

pub fn orchard_shielded_data_mut(&mut self) -> Option<&mut ShieldedData>

Modify the orchard::ShieldedData in this transaction, regardless of version.

pub fn orchard_actions(&self) -> impl Iterator<Item = &Action>

Iterate over the orchard::Actions in this transaction, if there are any, regardless of version.

pub fn orchard_nullifiers(&self) -> impl Iterator<Item = &Nullifier>

Access the orchard::Nullifiers in this transaction, if there are any, regardless of version.

pub fn orchard_note_commitments(&self) -> impl Iterator<Item = &Base>

Access the note commitments in this transaction, if there are any, regardless of version.

pub fn orchard_flags(&self) -> Option<Flags>

Access the orchard::Flags in this transaction, if there is any, regardless of version.

pub fn has_orchard_shielded_data(&self) -> bool

Return if the transaction has any Orchard shielded data, regardless of version.

fn transparent_value_balance_from_outputs( &self, outputs: &HashMap<OutPoint, Output>, ) -> Result<ValueBalance<NegativeAllowed>, ValueBalanceError>

Return the transparent value balance, using the outputs spent by this transaction.

See transparent_value_balance for details.

pub fn output_values_mut( &mut self, ) -> impl Iterator<Item = &mut Amount<NonNegative>>

Modify the transparent output values of this transaction, regardless of version.

pub fn output_values_to_sprout( &self, ) -> Box<dyn Iterator<Item = &Amount<NonNegative>> + '_>

Returns the vpub_old fields from JoinSplits in this transaction, regardless of version, in the order they appear in the transaction.

These values are added to the sprout chain value pool, and removed from the value pool of this transaction.

pub fn output_values_to_sprout_mut( &mut self, ) -> Box<dyn Iterator<Item = &mut Amount<NonNegative>> + '_>

Modify the vpub_old fields from JoinSplits in this transaction, regardless of version, in the order they appear in the transaction.

See output_values_to_sprout for details.

pub fn input_values_from_sprout( &self, ) -> Box<dyn Iterator<Item = &Amount<NonNegative>> + '_>

Returns the vpub_new fields from JoinSplits in this transaction, regardless of version, in the order they appear in the transaction.

These values are removed from the value pool of this transaction. and added to the sprout chain value pool.

pub fn input_values_from_sprout_mut( &mut self, ) -> Box<dyn Iterator<Item = &mut Amount<NonNegative>> + '_>

Modify the vpub_new fields from JoinSplits in this transaction, regardless of version, in the order they appear in the transaction.

See input_values_from_sprout for details.

fn sprout_joinsplit_value_balances( &self, ) -> impl Iterator<Item = ValueBalance<NegativeAllowed>> + '_

Return a list of sprout value balances, the changes in the transaction value pool due to each sprout JoinSplit.

Each value balance is the sprout vpub_new field, minus the vpub_old field.

See sprout_value_balance for details.

fn sprout_value_balance( &self, ) -> Result<ValueBalance<NegativeAllowed>, ValueBalanceError>

Return the sprout value balance, the change in the transaction value pool due to sprout JoinSplits.

The sum of all sprout vpub_new fields, minus the sum of all vpub_old fields.

Positive values are added to this transaction’s value pool, and removed from the sprout chain value pool. Negative values are removed from this transaction, and added to the sprout pool.

https://zebra.zfnd.org/dev/rfcs/0012-value-pools.html#definitions

pub fn sapling_value_balance(&self) -> ValueBalance<NegativeAllowed>

Return the sapling value balance, the change in the transaction value pool due to sapling Spends and Outputs.

Returns the valueBalanceSapling field in this transaction.

Positive values are added to this transaction’s value pool, and removed from the sapling chain value pool. Negative values are removed from this transaction, and added to sapling pool.

https://zebra.zfnd.org/dev/rfcs/0012-value-pools.html#definitions

pub fn sapling_value_balance_mut( &mut self, ) -> Option<&mut Amount<NegativeAllowed>>

Modify the value_balance field from the sapling::ShieldedData in this transaction, regardless of version.

See sapling_value_balance for details.

pub fn orchard_value_balance(&self) -> ValueBalance<NegativeAllowed>

Return the orchard value balance, the change in the transaction value pool due to orchard::Actions.

Returns the valueBalanceOrchard field in this transaction.

Positive values are added to this transaction’s value pool, and removed from the orchard chain value pool. Negative values are removed from this transaction, and added to orchard pool.

https://zebra.zfnd.org/dev/rfcs/0012-value-pools.html#definitions

pub fn orchard_value_balance_mut( &mut self, ) -> Option<&mut Amount<NegativeAllowed>>

Modify the value_balance field from the orchard::ShieldedData in this transaction, regardless of version.

See orchard_value_balance for details.

pub(crate) fn value_balance_from_outputs( &self, outputs: &HashMap<OutPoint, Output>, ) -> Result<ValueBalance<NegativeAllowed>, ValueBalanceError>

Returns the value balances for this transaction using the provided transparent outputs.

pub fn value_balance( &self, utxos: &HashMap<OutPoint, Utxo>, ) -> Result<ValueBalance<NegativeAllowed>, ValueBalanceError>

Returns the value balances for this transaction.

These are the changes in the transaction value pool, split up into transparent, Sprout, Sapling, and Orchard values.

Calculated as the sum of the inputs and outputs from each pool, or the sum of the value balances from each pool.

Positive values are added to this transaction’s value pool, and removed from the corresponding chain value pool. Negative values are removed from this transaction, and added to the corresponding pool.

https://zebra.zfnd.org/dev/rfcs/0012-value-pools.html#definitions

utxos must contain the utxos of every input in the transaction, including UTXOs created by earlier transactions in this block.

Note

The chain value pool has the opposite sign to the transaction value pool.

Trait Implementations

impl Arbitrary for Transaction

type Parameters = LedgerState

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

fn arbitrary_with(ledger_state: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

type Strategy = BoxedStrategy<Transaction>

The type of Strategy used to generate values of type Self.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl Clone for Transaction

fn clone(&self) -> Transaction

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Transaction

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

Formats the value using the given formatter.

impl Display for Transaction

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

Formats the value using the given formatter.

impl From<&Transaction> for AuthDigest

fn from(transaction: &Transaction) -> Self

Computes the authorizing data commitment for a transaction.

Panics

If passed a pre-v5 transaction.

impl From<&Transaction> for Hash

fn from(transaction: &Transaction) -> Self

Converts to this type from the input type.

impl From<&Transaction> for UnminedTx

fn from(transaction: &Transaction) -> Self

Converts to this type from the input type.

impl From<&Transaction> for UnminedTxId

fn from(transaction: &Transaction) -> Self

Converts to this type from the input type.

impl From<&Transaction> for WtxId

fn from(transaction: &Transaction) -> Self

Computes the witnessed transaction ID for a transaction.

Panics

If passed a pre-v5 transaction.

impl From<Transaction> for AuthDigest

fn from(transaction: Transaction) -> Self

Computes the authorizing data commitment for a transaction.

Panics

If passed a pre-v5 transaction.

impl From<Transaction> for Hash

fn from(transaction: Transaction) -> Self

Converts to this type from the input type.

impl From<Transaction> for UnminedTx

fn from(transaction: Transaction) -> Self

Converts to this type from the input type.

impl From<Transaction> for UnminedTxId

fn from(transaction: Transaction) -> Self

Converts to this type from the input type.

impl From<Transaction> for WtxId

fn from(transaction: Transaction) -> Self

Computes the witnessed transaction ID for a transaction.

Panics

If passed a pre-v5 transaction.

impl PartialEq for Transaction

fn eq(&self, other: &Transaction) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Transaction

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TrustedPreallocate for Transaction

No valid Zcash message contains more transactions than can fit in a single block

tx messages contain a single transaction, and block messages are limited to the maximum block size.

fn max_allocation() -> u64

Provides a loose upper bound on the size of the Vec<T: TrustedPreallocate> which can possibly be received from an honest peer.

impl TryFrom<&Transaction> for Transaction

fn try_from(trans: &Transaction) -> Result<Self, Self::Error>

Convert a Zebra transaction into a librustzcash one.

Panics

If the transaction is not V5. (Currently there is no need for this conversion for other versions.)

type Error = Error

The type returned in the event of a conversion error.

impl ZcashDeserialize for Transaction

fn zcash_deserialize<R: Read>(reader: R) -> Result<Self, SerializationError>

Try to read self from the given reader.

impl ZcashSerialize for Transaction

fn zcash_serialize<W: Write>(&self, writer: W) -> Result<(), Error>

Write self to the given writer using the canonical format.

fn zcash_serialize_to_vec(&self) -> Result<Vec<u8>, Error>

Helper function to construct a vec to serialize the current struct into

fn zcash_serialized_size(&self) -> usize

Get the size of self by using a fake writer.

impl Eq for Transaction

impl StructuralPartialEq for Transaction