Struct Amount

pub struct Amount(/* private fields */);

A type-safe representation of a ZCash amount in zatoshis (zats).

Amount represents a monetary value in the Zcash cryptocurrency, stored internally as a signed 64-bit integer count of zatoshis. One ZEC equals 100,000,000 zatoshis (1 ZEC = 10^8 zats), similar to Bitcoin’s satoshis.

The signed representation allows for representing both positive amounts (payments received) and negative amounts (payments sent) in transaction and balance calculations.

Zcash Concept Relation

In Zcash, monetary values are represented in two units:

• ZEC: The main unit of currency (analogous to dollars)
• zatoshis (zats): The smallest indivisible unit (analogous to cents)

Amount enforces the protocol limit of 21 million total ZEC, preventing overflow or underflow in calculations with proper error handling.

Data Preservation

The Amount type preserves the exact zatoshi values from wallet data, maintaining precise balances and transaction amounts during wallet migration. When displayed, values are formatted as ZEC with decimal places.

Examples

// Create an amount of 1.5 ZEC (150,000,000 zatoshis)
let amount = Amount::from_u64(150_000_000)?;

// Check if the amount is positive
assert!(amount.is_positive());

// Convert to raw zatoshi value
let zats: i64 = amount.into();
assert_eq!(zats, 150_000_000);

FIXME: Amounts in the zewif format should never be negative; negative values are only used transiently in the protocol.

Implementations

impl Amount

pub const fn zero() -> Self

Returns a zero-valued Amount.

pub const fn const_from_i64(amount: i64) -> Self

Creates a constant Amount from an i64.

Panics: if the amount is outside the range {-MAX_BALANCE..MAX_BALANCE}.

pub const fn const_from_u64(amount: u64) -> Self

Creates a constant Amount from a u64.

Panics: if the amount is outside the range {0..MAX_BALANCE}.

pub fn from_i64(amount: i64) -> Result<Self>

Creates an Amount from an i64.

Returns an error if the amount is outside the range {-MAX_BALANCE..MAX_BALANCE}.

pub fn from_nonnegative_i64(amount: i64) -> Result<Self>

Creates a non-negative Amount from an i64.

Returns an error if the amount is outside the range {0..MAX_BALANCE}.

pub fn from_u64(amount: u64) -> Result<Self>

Creates an Amount from a u64.

Returns an error if the amount is outside the range {0..MAX_MONEY}.

pub fn from_i64_le_bytes(bytes: [u8; 8]) -> Result<Self>

Reads an Amount from a signed 64-bit little-endian integer.

Returns an error if the amount is outside the range {-MAX_BALANCE..MAX_BALANCE}.

pub fn from_nonnegative_i64_le_bytes(bytes: [u8; 8]) -> Result<Self>

Reads a non-negative Amount from a signed 64-bit little-endian integer.

Returns an error if the amount is outside the range {0..MAX_BALANCE}.

pub fn from_u64_le_bytes(bytes: [u8; 8]) -> Result<Self>

Reads an Amount from an unsigned 64-bit little-endian integer.

Returns an error if the amount is outside the range {0..MAX_BALANCE}.

pub fn to_i64_le_bytes(self) -> [u8; 8]

Returns the Amount encoded as a signed 64-bit little-endian integer.

pub const fn is_positive(self) -> bool

Returns true if self is positive and false if the Amount is zero or negative.

pub const fn is_negative(self) -> bool

Returns true if self is negative and false if the Amount is zero or positive.

pub fn sum<I: IntoIterator<Item = Amount>>(values: I) -> Option<Amount>

Sums a collection of Amount values with overflow checking.

This helper method safely adds a collection of Amounts, returning None if any intermediate calculation would exceed the valid Amount range.

Arguments

• values - An iterable collection of Amount values to sum

Returns

• Some(Amount) - The sum if all operations were successful
• None - If any intermediate sum would exceed MAX_BALANCE

Examples

// Sum several ZEC amounts
let amounts = vec![
    Amount::from_u64(100_000_000)?, // 1 ZEC
    Amount::from_u64(50_000_000)?,  // 0.5 ZEC
    Amount::from_u64(25_000_000)?,  // 0.25 ZEC
];

let total = Amount::sum(amounts).unwrap();
let total_zats: i64 = total.into();
assert_eq!(total_zats, 175_000_000); // 1.75 ZEC

Trait Implementations

impl Add<Amount> for Option<Amount>

Adds an Amount to an Option<Amount>, propagating None

type Output = Option<Amount>

The resulting type after applying the + operator.

fn add(self, rhs: Amount) -> Option<Amount>

Performs the + operation.

impl Add for Amount

Adds two Amounts, checking for overflow/underflow

type Output = Option<Amount>

The resulting type after applying the + operator.

fn add(self, rhs: Amount) -> Option<Amount>

Performs the + operation.

impl Clone for Amount

fn clone(&self) -> Amount

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Amount

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

Formats the value using the given formatter.

impl From<&Amount> for CBOR

fn from(value: &Amount) -> Self

Converts to this type from the input type.

impl From<&Amount> for i64

Extracts the raw i64 zatoshi value from an Amount reference

fn from(amount: &Amount) -> i64

Converts to this type from the input type.

impl From<Amount> for CBOR

fn from(value: Amount) -> Self

Converts to this type from the input type.

impl From<Amount> for Envelope

fn from(value: Amount) -> Self

Converts to this type from the input type.

impl From<Amount> for i64

Extracts the raw i64 zatoshi value from an Amount

fn from(amount: Amount) -> i64

Converts to this type from the input type.

impl Mul<usize> for Amount

Multiplies an Amount by a usize factor, checking for overflow/underflow

type Output = Option<Amount>

The resulting type after applying the * operator.

fn mul(self, rhs: usize) -> Option<Amount>

Performs the * operation.

impl Neg for Amount

Negates an Amount, flipping its sign

type Output = Amount

The resulting type after applying the - operator.

fn neg(self) -> Self

Performs the unary - operation.

impl Ord for Amount

fn cmp(&self, other: &Amount) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Amount

fn eq(&self, other: &Amount) -> 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 PartialOrd for Amount

fn partial_cmp(&self, other: &Amount) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Sub<Amount> for Option<Amount>

Subtracts an Amount from an Option<Amount>, propagating None

type Output = Option<Amount>

The resulting type after applying the - operator.

fn sub(self, rhs: Amount) -> Option<Amount>

Performs the - operation.

impl Sub for Amount

Subtracts one Amount from another, checking for overflow/underflow

type Output = Option<Amount>

The resulting type after applying the - operator.

fn sub(self, rhs: Amount) -> Option<Amount>

Performs the - operation.

impl<'a> Sum<&'a Amount> for Option<Amount>

Implements std::iter::Sum for Amount references with overflow checking

fn sum<I: Iterator<Item = &'a Amount>>(iter: I) -> Self

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

impl Sum<Amount> for Option<Amount>

Implements std::iter::Sum for Amount with overflow checking

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

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

impl TryFrom<Amount> for u64

Converts an Amount to u64, ensuring the value is non-negative

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Amount) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<CBOR> for Amount

type Error = Error

The type returned in the event of a conversion error.

fn try_from(cbor: CBOR) -> Result<Self>

Performs the conversion.

impl TryFrom<Envelope> for Amount

type Error = Error

The type returned in the event of a conversion error.

fn try_from(envelope: Envelope) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i64> for Amount

Converts an i64 into an Amount, with range checking

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: i64) -> Result<Self>

Performs the conversion.

impl Copy for Amount

impl Eq for Amount

impl StructuralPartialEq for Amount