From a3af4095aebbb3cb99bbdac1f07bd7c3a03ce73e Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Sat, 13 Aug 2022 07:56:54 +0100 Subject: [PATCH] Add more thorough documentation for `ValueCommitmentTrapdoor::from_bytes`. Also add a CHANGELOG entry for orchard::value::{ValueCommitmentTrapdoor, ValueCommitment::derive}. Signed-off-by: Daira Hopwood --- CHANGELOG.md | 6 ++++++ src/value.rs | 11 ++++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 760b2742..5e250d31 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,12 @@ and this project adheres to Rust's notion of - `CompactAction::from_parts` - `CompactAction::nullifier` - `OrchardDomain::for_nullifier` +- Low-level APIs in `orchard::value` for handling `ValueCommitment`s. + These are useful in code that constructs proof witnesses itself, but + note that doing so requires a detailed knowledge of the Zcash protocol + to avoid privacy and correctness pitfalls. + - `ValueCommitTrapdoor` + - `ValueCommitment::derive` ### Changed - Migrated to `halo2_proofs 0.2`. diff --git a/src/value.rs b/src/value.rs index 0269e81d..8945ef9d 100644 --- a/src/value.rs +++ b/src/value.rs @@ -219,7 +219,16 @@ impl ValueCommitTrapdoor { self.0 } - /// Constructs `ValueCommitTrapdoor` from the byte reprsentation of a scalar + /// Constructs `ValueCommitTrapdoor` from the byte representation of a scalar. + /// Returns a `None` [`CtOption`] if `bytes` is not a canonical representation + /// of a Pallas scalar. + /// + /// This is a low-level API, requiring a detailed understanding of the + /// [use of value commitment trapdoors][orchardbalance] in the Zcash protocol + /// to use correctly and securely. It is intended to be used in combination + /// with [`ValueCommitment::derive`]. + /// + /// [orchardbalance]: https://zips.z.cash/protocol/protocol.pdf#orchardbalance pub fn from_bytes(bytes: [u8; 32]) -> CtOption { pallas::Scalar::from_repr(bytes).map(ValueCommitTrapdoor) }