mirror of https://github.com/zcash/orchard.git
commit
40cc3cb728
|
@ -6,4 +6,8 @@ and this project adheres to Rust's notion of
|
||||||
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||||
|
|
||||||
## [Unreleased]
|
## [Unreleased]
|
||||||
|
### Removed
|
||||||
|
- `orchard::value::ValueSum::from_raw`
|
||||||
|
|
||||||
|
## [0.1.0-beta.1] - 2021-12-17
|
||||||
Initial release!
|
Initial release!
|
||||||
|
|
|
@ -151,11 +151,6 @@ impl MerklePath {
|
||||||
|
|
||||||
/// A newtype wrapper for leaves and internal nodes in the Orchard
|
/// A newtype wrapper for leaves and internal nodes in the Orchard
|
||||||
/// incremental note commitment tree.
|
/// incremental note commitment tree.
|
||||||
///
|
|
||||||
/// This wraps a CtOption<pallas::Base> because Sinsemilla hashes
|
|
||||||
/// can produce a bottom value which needs to be accounted for in
|
|
||||||
/// the production of a Merkle root. Leaf nodes are always wrapped
|
|
||||||
/// with the `Some` constructor.
|
|
||||||
#[derive(Copy, Clone, Debug)]
|
#[derive(Copy, Clone, Debug)]
|
||||||
pub struct MerkleHashOrchard(pallas::Base);
|
pub struct MerkleHashOrchard(pallas::Base);
|
||||||
|
|
||||||
|
|
45
src/value.rs
45
src/value.rs
|
@ -1,18 +1,39 @@
|
||||||
//! Monetary values within the Orchard shielded pool.
|
//! Monetary values within the Orchard shielded pool.
|
||||||
//!
|
//!
|
||||||
//! Values are represented in two places within Orchard:
|
//! Values are represented in three places within the Orchard protocol:
|
||||||
//! - The value of an individual note, which is an unsigned 63-bit integer.
|
//! - [`NoteValue`], the value of an individual note. It is an unsigned 64-bit integer
|
||||||
//! - The sum of note values within an Orchard [`Action`] or [`Bundle`], which is a signed
|
//! (with maximum value [`MAX_NOTE_VALUE`]), and is serialized in a note plaintext.
|
||||||
//! 63-bit integer.
|
//! - [`ValueSum`], the sum of note values within an Orchard [`Action`] or [`Bundle`].
|
||||||
|
//! It is a signed 64-bit integer (with range [`VALUE_SUM_RANGE`]).
|
||||||
|
//! - `valueBalanceOrchard`, which is a signed 63-bit integer. This is represented by a
|
||||||
|
//! user-defined type parameter on [`Bundle`], returned by [`Bundle::value_balance`].
|
||||||
//!
|
//!
|
||||||
//! We give these separate types within this crate. Users should map these types to their
|
//! If your specific instantiation of the Orchard protocol requires a smaller bound on
|
||||||
//! own general "amount" type as appropriate, and apply their own bounds checks if smaller
|
//! valid note values (for example, Zcash's `MAX_MONEY` fits into a 51-bit integer), you
|
||||||
//! than the Orchard protocol supports.
|
//! should enforce this in two ways:
|
||||||
|
//!
|
||||||
|
//! - Define your `valueBalanceOrchard` type to enforce your valid value range. This can
|
||||||
|
//! be checked in its `TryFrom<i64>` implementation.
|
||||||
|
//! - Define your own "amount" type for note values, and convert it to `NoteValue` prior
|
||||||
|
//! to calling [`Builder::add_recipient`].
|
||||||
//!
|
//!
|
||||||
//! Inside the circuit, note values are constrained to be unsigned 64-bit integers.
|
//! Inside the circuit, note values are constrained to be unsigned 64-bit integers.
|
||||||
//!
|
//!
|
||||||
|
//! # Caution!
|
||||||
|
//!
|
||||||
|
//! An `i64` is _not_ a signed 64-bit integer! The [Rust documentation] calls `i64` the
|
||||||
|
//! 64-bit signed integer type, which is true in the sense that its encoding in memory
|
||||||
|
//! takes up 64 bits. Numerically, however, `i64` is a signed 63-bit integer.
|
||||||
|
//!
|
||||||
|
//! Fortunately, users of this crate should never need to construct [`ValueSum`] directly;
|
||||||
|
//! you should only need to interact with [`NoteValue`] (which can be safely constructed
|
||||||
|
//! from a `u64`) and `valueBalanceOrchard` (which can be represented as an `i64`).
|
||||||
|
//!
|
||||||
//! [`Action`]: crate::bundle::Action
|
//! [`Action`]: crate::bundle::Action
|
||||||
//! [`Bundle`]: crate::bundle::Bundle
|
//! [`Bundle`]: crate::bundle::Bundle
|
||||||
|
//! [`Bundle::value_balance`]: crate::bundle::Bundle::value_balance
|
||||||
|
//! [`Builder::add_recipient`]: crate::builder::Builder::add_recipient
|
||||||
|
//! [Rust documentation]: https://doc.rust-lang.org/stable/std/primitive.i64.html
|
||||||
|
|
||||||
use std::convert::{TryFrom, TryInto};
|
use std::convert::{TryFrom, TryInto};
|
||||||
use std::fmt::{self, Debug};
|
use std::fmt::{self, Debug};
|
||||||
|
@ -110,7 +131,7 @@ impl Sub for NoteValue {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// A sum of Orchard note values
|
/// A sum of Orchard note values.
|
||||||
#[derive(Clone, Copy, Debug, Default, PartialEq)]
|
#[derive(Clone, Copy, Debug, Default, PartialEq)]
|
||||||
pub struct ValueSum(i128);
|
pub struct ValueSum(i128);
|
||||||
|
|
||||||
|
@ -119,14 +140,6 @@ impl ValueSum {
|
||||||
// Default for i64 is zero.
|
// Default for i64 is zero.
|
||||||
Default::default()
|
Default::default()
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Creates a value sum from its raw numeric value.
|
|
||||||
///
|
|
||||||
/// This only enforces that the value is a signed 63-bit integer. Callers should
|
|
||||||
/// enforce any additional constraints on the value's valid range themselves.
|
|
||||||
pub fn from_raw(value: i64) -> Self {
|
|
||||||
ValueSum(value as i128)
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
impl Add for ValueSum {
|
impl Add for ValueSum {
|
||||||
|
|
Loading…
Reference in New Issue