Add more thorough documentation for `ValueCommitmentTrapdoor::from_bytes`.

Also add a CHANGELOG entry for orchard::value::{ValueCommitmentTrapdoor, ValueCommitment::derive}.

Signed-off-by: Daira Hopwood <daira@jacaranda.org>

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`.

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<Self> {
         pallas::Scalar::from_repr(bytes).map(ValueCommitTrapdoor)
     }