Struct ValueBalance

pub struct ValueBalance<C> {
    transparent: Amount<C>,
    sprout: Amount<C>,
    sapling: Amount<C>,
    orchard: Amount<C>,
    deferred: Amount<C>,
}

A balance in each chain value pool or transaction value pool.

Fields

transparent: Amount<C>

sprout: Amount<C>

sapling: Amount<C>

orchard: Amount<C>

deferred: Amount<C>

Implementations

impl<C> ValueBalance<C>

where C: Constraint + Copy,

pub fn from_transparent_amount(transparent_amount: Amount<C>) -> Self

Creates a ValueBalance from the given transparent amount.

pub fn from_sprout_amount(sprout_amount: Amount<C>) -> Self

Creates a ValueBalance from the given sprout amount.

pub fn from_sapling_amount(sapling_amount: Amount<C>) -> Self

Creates a ValueBalance from the given sapling amount.

pub fn from_orchard_amount(orchard_amount: Amount<C>) -> Self

Creates a ValueBalance from the given orchard amount.

pub fn transparent_amount(&self) -> Amount<C>

Get the transparent amount from the ValueBalance.

pub fn set_transparent_value_balance( &mut self, transparent_value_balance: ValueBalance<C>, ) -> &Self

Insert a transparent value balance into a given ValueBalance leaving the other values untouched.

pub fn sprout_amount(&self) -> Amount<C>

Get the sprout amount from the ValueBalance.

pub fn set_sprout_value_balance( &mut self, sprout_value_balance: ValueBalance<C>, ) -> &Self

Insert a sprout value balance into a given ValueBalance leaving the other values untouched.

pub fn sapling_amount(&self) -> Amount<C>

Get the sapling amount from the ValueBalance.

pub fn set_sapling_value_balance( &mut self, sapling_value_balance: ValueBalance<C>, ) -> &Self

Insert a sapling value balance into a given ValueBalance leaving the other values untouched.

pub fn orchard_amount(&self) -> Amount<C>

Get the orchard amount from the ValueBalance.

pub fn set_orchard_value_balance( &mut self, orchard_value_balance: ValueBalance<C>, ) -> &Self

Insert an orchard value balance into a given ValueBalance leaving the other values untouched.

pub fn deferred_amount(&self) -> Amount<C>

Returns the deferred amount.

pub fn set_deferred_amount(&mut self, deferred_amount: Amount<C>) -> &Self

Sets the deferred amount without affecting other amounts.

pub fn zero() -> Self

Creates a ValueBalance where all the pools are zero.

pub fn constrain<C2>(self) -> Result<ValueBalance<C2>, ValueBalanceError>

where C2: Constraint,

Convert this value balance to a different ValueBalance type, if it satisfies the new constraint

impl ValueBalance<NegativeAllowed>

pub fn remaining_transaction_value(&self) -> Result<Amount<NonNegative>, Error>

Assumes that this value balance is a non-coinbase transaction value balance, and returns the remaining value in the transaction value pool.

Consensus

The remaining value in the transparent transaction value pool MUST be nonnegative.

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

This rule applies to Block and Mempool transactions.

Design: https://github.com/ZcashFoundation/zebra/blob/main/book/src/dev/rfcs/0012-value-pools.md#definitions

impl ValueBalance<NonNegative>

pub fn add_transaction( self, transaction: impl Borrow<Transaction>, utxos: &HashMap<OutPoint, Output>, ) -> Result<ValueBalance<NonNegative>, ValueBalanceError>

Returns the sum of this value balance, and the chain value pool changes in transaction.

outputs must contain the transparent::Outputs of every input in this transaction, including UTXOs created by earlier transactions in its block.

Note: the chain value pool has the opposite sign to the transaction value pool.

Consensus

If any of the “Sprout chain value pool balance”, “Sapling chain value pool balance”, or “Orchard chain value pool balance” would become negative in the block chain created as a result of accepting a block, then all nodes MUST reject the block as invalid.

Nodes MAY relay transactions even if one or more of them cannot be mined due to the aforementioned restriction.

https://zips.z.cash/zip-0209#specification

Since this consensus rule is optional for mempool transactions, Zebra does not check it in the mempool transaction verifier.

pub fn add_transparent_input( self, input: impl Borrow<Input>, utxos: &HashMap<OutPoint, Output>, ) -> Result<ValueBalance<NonNegative>, ValueBalanceError>

Returns the sum of this value balance, and the chain value pool change in input.

outputs must contain the transparent::Output spent by input, (including UTXOs created by earlier transactions in its block).

Note: the chain value pool has the opposite sign to the transaction value pool. Inputs remove value from the chain value pool.

pub fn add_chain_value_pool_change( self, chain_value_pool_change: ValueBalance<NegativeAllowed>, ) -> Result<ValueBalance<NonNegative>, ValueBalanceError>

Returns the sum of this value balance, and the given chain_value_pool_change.

Note that the chain value pool has the opposite sign to the transaction value pool.

Consensus

If the Sprout chain value pool balance would become negative in the block chain created as a result of accepting a block, then all nodes MUST reject the block as invalid.

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

If the Sapling chain value pool balance would become negative in the block chain created as a result of accepting a block, then all nodes MUST reject the block as invalid.

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

If the Orchard chain value pool balance would become negative in the block chain created as a result of accepting a block , then all nodes MUST reject the block as invalid.

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

If any of the “Sprout chain value pool balance”, “Sapling chain value pool balance”, or “Orchard chain value pool balance” would become negative in the block chain created as a result of accepting a block, then all nodes MUST reject the block as invalid.

https://zips.z.cash/zip-0209#specification

Zebra also checks that the transparent value pool is non-negative. In Zebra, we define this pool as the sum of all unspent transaction outputs. (Despite their encoding as an int64, transparent output values must be non-negative.)

This is a consensus rule derived from Bitcoin:

because a UTXO can only be spent once, the full value of the included UTXOs must be spent or given to a miner as a transaction fee.

https://developer.bitcoin.org/devguide/transactions.html#transaction-fees-and-change

We implement the consensus rules above by constraining the returned value balance to ValueBalance<NonNegative>.

pub fn fake_populated_pool() -> ValueBalance<NonNegative>

Create a fake value pool for testing purposes.

The resulting ValueBalance will have half of the MAX_MONEY amount on each pool.

pub fn to_bytes(self) -> [u8; 40]

To byte array

pub fn from_bytes( bytes: &[u8], ) -> Result<ValueBalance<NonNegative>, ValueBalanceError>

From byte array

Trait Implementations

impl<C> Add<Result<ValueBalance<C>, ValueBalanceError>> for ValueBalance<C>

where C: Constraint,

type Output = Result<ValueBalance<C>, ValueBalanceError>

The resulting type after applying the + operator.

fn add(self, rhs: Result<ValueBalance<C>, ValueBalanceError>) -> Self::Output

Performs the + operation.

impl<C> Add<ValueBalance<C>> for Result<ValueBalance<C>, ValueBalanceError>

where C: Constraint,

type Output = Result<ValueBalance<C>, ValueBalanceError>

The resulting type after applying the + operator.

fn add(self, rhs: ValueBalance<C>) -> Self::Output

Performs the + operation.

impl<C> Add for ValueBalance<C>

where C: Constraint,

type Output = Result<ValueBalance<C>, ValueBalanceError>

The resulting type after applying the + operator.

fn add(self, rhs: ValueBalance<C>) -> Self::Output

Performs the + operation.

impl<C> AddAssign<ValueBalance<C>> for Result<ValueBalance<C>, ValueBalanceError>

where ValueBalance<C>: Copy, C: Constraint,

fn add_assign(&mut self, rhs: ValueBalance<C>)

Performs the += operation.

impl Arbitrary for ValueBalance<NegativeAllowed>

type Parameters = ()

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

type Strategy = BoxedStrategy<ValueBalance<NegativeAllowed>>

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 Arbitrary for ValueBalance<NonNegative>

type Parameters = ()

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

type Strategy = BoxedStrategy<ValueBalance<NonNegative>>

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<C: Clone> Clone for ValueBalance<C>

fn clone(&self) -> ValueBalance<C>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<C: Debug> Debug for ValueBalance<C>

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

Formats the value using the given formatter.

impl<C: Default> Default for ValueBalance<C>

fn default() -> ValueBalance<C>

Returns the “default value” for a type.

impl<C: Hash> Hash for ValueBalance<C>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<C> Neg for ValueBalance<C>

where C: Constraint,

type Output = ValueBalance<NegativeAllowed>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<C: PartialEq> PartialEq for ValueBalance<C>

fn eq(&self, other: &ValueBalance<C>) -> 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<C> Sub<Result<ValueBalance<C>, ValueBalanceError>> for ValueBalance<C>

where C: Constraint,

type Output = Result<ValueBalance<C>, ValueBalanceError>

The resulting type after applying the - operator.

fn sub(self, rhs: Result<ValueBalance<C>, ValueBalanceError>) -> Self::Output

Performs the - operation.

impl<C> Sub<ValueBalance<C>> for Result<ValueBalance<C>, ValueBalanceError>

where C: Constraint,

type Output = Result<ValueBalance<C>, ValueBalanceError>

The resulting type after applying the - operator.

fn sub(self, rhs: ValueBalance<C>) -> Self::Output

Performs the - operation.

impl<C> Sub for ValueBalance<C>

where C: Constraint,

type Output = Result<ValueBalance<C>, ValueBalanceError>

The resulting type after applying the - operator.

fn sub(self, rhs: ValueBalance<C>) -> Self::Output

Performs the - operation.

impl<C> SubAssign<ValueBalance<C>> for Result<ValueBalance<C>, ValueBalanceError>

where ValueBalance<C>: Copy, C: Constraint,

fn sub_assign(&mut self, rhs: ValueBalance<C>)

Performs the -= operation.

impl<'amt, C> Sum<&'amt ValueBalance<C>> for Result<ValueBalance<C>, ValueBalanceError>

where C: Constraint + Copy + 'amt,

fn sum<I: Iterator<Item = &'amt ValueBalance<C>>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by “summing up” the items.

impl<C> Sum<ValueBalance<C>> for Result<ValueBalance<C>, ValueBalanceError>

where C: Constraint + Copy,

fn sum<I: Iterator<Item = ValueBalance<C>>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by “summing up” the items.

impl<C: Copy> Copy for ValueBalance<C>

impl<C: Eq> Eq for ValueBalance<C>

impl<C> StructuralPartialEq for ValueBalance<C>