Struct ShieldedData

pub struct ShieldedData<AnchorV>
where
    AnchorV: AnchorVariant + Clone,
{
    pub value_balance: Amount,
    pub transfers: TransferData<AnchorV>,
    pub binding_sig: Signature<Binding>,
}

A bundle of Spend and Output descriptions and signature data.

Spend and Output descriptions are optional, but Zcash transactions must include a binding signature if and only if there is at least one Spend or Output description. This wrapper type bundles at least one Spend or Output description with the required signature data, so that an Option<ShieldedData> correctly models the presence or absence of any shielded data.

Differences between Transaction Versions

The Sapling value_balance field is optional in Transaction::V5, but required in Transaction::V4. In both cases, if there is no ShieldedData, then the field value must be zero. Therefore, we only need to store value_balance when there is some Sapling ShieldedData.

In Transaction::V4, each Spend has its own anchor. In Transaction::V5, there is a single shared_anchor for the entire transaction, which is only present when there is at least one spend. These structural differences are modeled using the AnchorVariant type trait and TransferData enum.

Fields

value_balance: Amount

The net value of Sapling spend transfers minus output transfers. Denoted as valueBalanceSapling in the spec.

transfers: TransferData<AnchorV>

A bundle of spends and outputs, containing at least one spend or output, in the order they appear in the transaction.

In V5 transactions, also contains a shared anchor, if there are any spends.

binding_sig: Signature<Binding>

A signature on the transaction hash. Denoted as bindingSigSapling in the spec.

Implementations

impl<AnchorV> ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone, Spend<PerSpendAnchor>: From<(Spend<AnchorV>, AnchorV::Shared)>,

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

Iterate over the Spends for this transaction, returning deduplicated tree::Roots, regardless of the underlying transaction version.

pub fn spends_per_anchor( &self, ) -> impl Iterator<Item = Spend<PerSpendAnchor>> + '_

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

Correctness

Do not use this function for serialization.

impl<AnchorV> ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone,

pub fn spends(&self) -> impl Iterator<Item = &Spend<AnchorV>>

Iterate over the Spends for this transaction, returning them as their generic type.

Correctness

Use this function for serialization.

pub fn outputs(&self) -> impl Iterator<Item = &Output>

Iterate over the Outputs for this transaction, in the order they appear in it.

pub fn shared_anchor(&self) -> Option<AnchorV::Shared>

Provide the shared anchor for this transaction, if present.

The shared anchor is only present if:

• there is at least one spend, and
• this is a V5 transaction.

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

Collect the Nullifiers for this transaction, if it contains Spends.

pub fn note_commitments(&self) -> impl Iterator<Item = &Fq>

Collect the cm_u’s for this transaction, if it contains Outputs, in the order they appear in the transaction.

pub fn binding_verification_key(&self) -> VerificationKeyBytes<Binding>

Calculate the Spend/Output binding verification key.

Getting the binding signature validating key from the Spend and Output description value commitments and the balancing value implicitly checks that the balancing value is consistent with the value transferred in the Spend and Output descriptions but also proves that the signer knew the randomness used for the Spend and Output value commitments, which prevents replays of Output descriptions.

The net value of Spend transfers minus Output transfers in a transaction is called the balancing value, measured in zatoshi as a signed integer v_balance.

Consistency of v_balance with the value commitments in Spend descriptions and Output descriptions is enforced by the binding signature.

Instead of generating a key pair at random, we generate it as a function of the value commitments in the Spend descriptions and Output descriptions of the transaction, and the balancing value.

https://zips.z.cash/protocol/protocol.pdf#saplingbalance

pub fn value_balance(&self) -> Amount<NegativeAllowed>

Provide access to the value_balance field of the shielded data.

Needed to calculate the sapling value balance.

Trait Implementations

impl<AnchorV> Arbitrary for ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone + Debug + 'static, TransferData<AnchorV>: Arbitrary,

type Parameters = ()

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

type Strategy = BoxedStrategy<ShieldedData<AnchorV>>

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

fn arbitrary_with(_args: 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.

fn arbitrary() -> Self::Strategy

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

impl<AnchorV> Clone for ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone + Clone,

fn clone(&self) -> ShieldedData<AnchorV>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<AnchorV> Debug for ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone + Debug,

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

Formats the value using the given formatter.

impl<'de, AnchorV> Deserialize<'de> for ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone + Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<AnchorV> Display for ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone,

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

Formats the value using the given formatter.

impl<AnchorV> PartialEq for ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone + PartialEq,

fn eq(&self, other: &ShieldedData<AnchorV>) -> 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<AnchorV> Serialize for ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone + Serialize,

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ZcashSerialize for ShieldedData<SharedAnchor>

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<AnchorV> Eq for ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone + Eq,

impl<AnchorV> StructuralPartialEq for ShieldedData<AnchorV>

where AnchorV: AnchorVariant + Clone,