From d84764f2db0913d1c417e6f58c875e9ae6744e3d Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Mon, 20 Dec 2021 15:24:48 +0000 Subject: [PATCH 1/3] Remove outdated doc comment on `MerkleHashOrchard` Closes zcash/orchard#245. --- src/tree.rs | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/tree.rs b/src/tree.rs index c3b3f08b..436642a9 100644 --- a/src/tree.rs +++ b/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 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); From 04af08d343d0699b060ebccce9a52c5efadfb130 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Mon, 20 Dec 2021 16:05:01 +0000 Subject: [PATCH 2/3] Fix documentation of `orchard::value` module Closes zcash/orchard#142. --- src/value.rs | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/src/value.rs b/src/value.rs index 9bdecfc3..445f43ef 100644 --- a/src/value.rs +++ b/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` 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}; From d11fbd4a5602781002883b35dac9aa573b6aad30 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Mon, 20 Dec 2021 16:08:44 +0000 Subject: [PATCH 3/3] Remove `ValueSum::from_raw` There is no reason for crate users to be constructing `ValueSum` directly. We no longer use it to represent `valueBalanceOrchard`, instead requiring the user to specify their own type. --- CHANGELOG.md | 4 ++++ src/value.rs | 10 +--------- 2 files changed, 5 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bafd9c53..86feaa61 100644 --- a/CHANGELOG.md +++ b/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! diff --git a/src/value.rs b/src/value.rs index 445f43ef..a27c5682 100644 --- a/src/value.rs +++ b/src/value.rs @@ -131,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); @@ -140,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 {