Merge pull request #267 from zcash/crate-cleanups

Crate cleanups

CHANGELOG.md

@@ -6,4 +6,8 @@ and this project adheres to Rust's notion of
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Removed
+- `orchard::value::ValueSum::from_raw`
+
+## [0.1.0-beta.1] - 2021-12-17
 Initial release!

src/tree.rs

@@ -151,11 +151,6 @@ impl MerklePath {
 
 /// A newtype wrapper for leaves and internal nodes in the Orchard
 /// 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)]
 pub struct MerkleHashOrchard(pallas::Base);
 

src/value.rs

@@ -1,18 +1,39 @@
 //! Monetary values within the Orchard shielded pool.
 //!
-//! Values are represented in two places within Orchard:
-//! - The value of an individual note, which is an unsigned 63-bit integer.
-//! - The sum of note values within an Orchard [`Action`] or [`Bundle`], which is a signed
-//!   63-bit integer.
+//! Values are represented in three places within the Orchard protocol:
+//! - [`NoteValue`], the value of an individual note. It is an unsigned 64-bit integer
+//!   (with maximum value [`MAX_NOTE_VALUE`]), and is serialized in a note plaintext.
+//! - [`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
-//! own general "amount" type as appropriate, and apply their own bounds checks if smaller
-//! than the Orchard protocol supports.
+//! If your specific instantiation of the Orchard protocol requires a smaller bound on
+//! valid note values (for example, Zcash's `MAX_MONEY` fits into a 51-bit integer), you
+//! 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.
 //!
+//! # 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
 //! [`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::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)]
 pub struct ValueSum(i128);
 
@@ -119,14 +140,6 @@ impl ValueSum {
         // Default for i64 is zero.
         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 {