2019-09-25 23:23:04 -07:00
|
|
|
|
//! Note Commitment Trees.
|
|
|
|
|
//!
|
|
|
|
|
//! A note commitment tree is an incremental Merkle tree of fixed depth
|
|
|
|
|
//! used to store note commitments that JoinSplit transfers or Spend
|
|
|
|
|
//! transfers produce. Just as the unspent transaction output set (UTXO
|
|
|
|
|
//! set) used in Bitcoin, it is used to express the existence of value and
|
|
|
|
|
//! the capability to spend it. However, unlike the UTXO set, it is not
|
|
|
|
|
//! the job of this tree to protect against double-spending, as it is
|
|
|
|
|
//! append-only.
|
|
|
|
|
//!
|
|
|
|
|
//! A root of a note commitment tree is associated with each treestate.
|
2020-07-28 00:52:04 -07:00
|
|
|
|
|
2020-05-26 18:00:58 -07:00
|
|
|
|
#![allow(clippy::unit_arg)]
|
2020-07-28 00:52:04 -07:00
|
|
|
|
#![allow(dead_code)]
|
2019-09-25 23:23:04 -07:00
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
use std::fmt;
|
2020-02-07 12:53:44 -08:00
|
|
|
|
|
2020-07-28 00:52:04 -07:00
|
|
|
|
use bitvec::prelude::*;
|
2021-07-15 06:58:36 -07:00
|
|
|
|
use incrementalmerkletree::{bridgetree, Frontier};
|
2020-09-18 19:47:22 -07:00
|
|
|
|
use lazy_static::lazy_static;
|
2021-07-15 06:58:36 -07:00
|
|
|
|
use thiserror::Error;
|
2020-07-28 00:52:04 -07:00
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
use super::commitment::pedersen_hashes::pedersen_hash;
|
|
|
|
|
|
|
|
|
|
pub(super) const MERKLE_DEPTH: usize = 32;
|
2020-09-19 01:09:09 -07:00
|
|
|
|
|
2020-07-28 00:52:04 -07:00
|
|
|
|
/// MerkleCRH^Sapling Hash Function
|
|
|
|
|
///
|
2020-10-05 18:28:49 -07:00
|
|
|
|
/// Used to hash incremental Merkle tree hash values for Sapling.
|
|
|
|
|
///
|
2021-03-14 17:41:43 -07:00
|
|
|
|
/// MerkleCRH^Sapling(layer, left, right) := PedersenHash("Zcash_PH", l || left || right)
|
2020-09-18 19:47:22 -07:00
|
|
|
|
/// where l = I2LEBSP_6(MerkleDepth^Sapling − 1 − layer) and
|
|
|
|
|
/// left, right, and the output are all technically 255 bits (l_MerkleSapling), not 256.
|
2020-07-28 00:52:04 -07:00
|
|
|
|
///
|
|
|
|
|
/// https://zips.z.cash/protocol/protocol.pdf#merklecrh
|
2020-09-09 00:15:12 -07:00
|
|
|
|
fn merkle_crh_sapling(layer: u8, left: [u8; 32], right: [u8; 32]) -> [u8; 32] {
|
2020-09-18 19:47:22 -07:00
|
|
|
|
let mut s = bitvec![Lsb0, u8;];
|
2020-07-28 00:52:04 -07:00
|
|
|
|
|
|
|
|
|
// Prefix: l = I2LEBSP_6(MerkleDepth^Sapling − 1 − layer)
|
2021-07-15 06:58:36 -07:00
|
|
|
|
let l = (MERKLE_DEPTH - 1) as u8 - layer;
|
|
|
|
|
s.extend_from_bitslice(&BitSlice::<Lsb0, _>::from_element(&l)[0..6]);
|
2021-06-22 20:16:22 -07:00
|
|
|
|
s.extend_from_bitslice(&BitArray::<Lsb0, _>::from(left)[0..255]);
|
|
|
|
|
s.extend_from_bitslice(&BitArray::<Lsb0, _>::from(right)[0..255]);
|
2020-07-28 00:52:04 -07:00
|
|
|
|
|
2020-09-09 00:15:12 -07:00
|
|
|
|
pedersen_hash(*b"Zcash_PH", &s).to_bytes()
|
2020-07-28 00:52:04 -07:00
|
|
|
|
}
|
2019-09-25 23:23:04 -07:00
|
|
|
|
|
2020-09-18 19:47:22 -07:00
|
|
|
|
lazy_static! {
|
2021-07-15 06:58:36 -07:00
|
|
|
|
/// List of "empty" Sapling note commitment nodes, one for each layer.
|
|
|
|
|
///
|
|
|
|
|
/// The list is indexed by the layer number (0: root; MERKLE_DEPTH: leaf).
|
2020-09-18 19:47:22 -07:00
|
|
|
|
///
|
2020-10-28 08:14:32 -07:00
|
|
|
|
/// https://zips.z.cash/protocol/protocol.pdf#constants
|
2021-07-15 06:58:36 -07:00
|
|
|
|
pub(super) static ref EMPTY_ROOTS: Vec<[u8; 32]> = {
|
|
|
|
|
// The empty leaf node. This is layer 32.
|
|
|
|
|
let mut v = vec![NoteCommitmentTree::uncommitted()];
|
|
|
|
|
|
|
|
|
|
// Starting with layer 31 (the first internal layer, after the leaves),
|
|
|
|
|
// generate the empty roots up to layer 0, the root.
|
|
|
|
|
for layer in (0..MERKLE_DEPTH).rev() {
|
|
|
|
|
// The vector is generated from the end, pushing new nodes to its beginning.
|
|
|
|
|
// For this reason, the layer below is v[0].
|
|
|
|
|
let next = merkle_crh_sapling(layer as u8, v[0], v[0]);
|
|
|
|
|
v.insert(0, next);
|
2020-09-18 19:47:22 -07:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
v
|
|
|
|
|
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
|
2021-03-14 17:41:43 -07:00
|
|
|
|
/// The index of a note's commitment at the leafmost layer of its Note
|
2020-07-27 23:27:02 -07:00
|
|
|
|
/// Commitment Tree.
|
|
|
|
|
///
|
|
|
|
|
/// https://zips.z.cash/protocol/protocol.pdf#merkletree
|
|
|
|
|
pub struct Position(pub(crate) u64);
|
|
|
|
|
|
2019-09-25 23:23:04 -07:00
|
|
|
|
/// Sapling note commitment tree root node hash.
|
|
|
|
|
///
|
|
|
|
|
/// The root hash in LEBS2OSP256(rt) encoding of the Sapling note
|
|
|
|
|
/// commitment tree corresponding to the final Sapling treestate of
|
|
|
|
|
/// this block. A root of a note commitment tree is associated with
|
|
|
|
|
/// each treestate.
|
2020-09-24 15:46:04 -07:00
|
|
|
|
#[derive(Clone, Copy, Default, Eq, PartialEq, Serialize, Deserialize, Hash)]
|
2020-08-28 01:22:40 -07:00
|
|
|
|
pub struct Root(pub [u8; 32]);
|
2019-09-25 23:23:04 -07:00
|
|
|
|
|
2020-08-28 01:22:40 -07:00
|
|
|
|
impl fmt::Debug for Root {
|
2020-02-07 12:53:44 -08:00
|
|
|
|
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
|
2020-08-28 01:22:40 -07:00
|
|
|
|
f.debug_tuple("Root").field(&hex::encode(&self.0)).finish()
|
2020-02-07 12:53:44 -08:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2021-03-24 09:28:25 -07:00
|
|
|
|
impl From<[u8; 32]> for Root {
|
|
|
|
|
fn from(bytes: [u8; 32]) -> Root {
|
|
|
|
|
Self(bytes)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
impl From<Root> for [u8; 32] {
|
|
|
|
|
fn from(root: Root) -> Self {
|
|
|
|
|
root.0
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2021-06-04 06:31:47 -07:00
|
|
|
|
impl From<&[u8; 32]> for Root {
|
|
|
|
|
fn from(bytes: &[u8; 32]) -> Root {
|
|
|
|
|
(*bytes).into()
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
impl From<&Root> for [u8; 32] {
|
|
|
|
|
fn from(root: &Root) -> Self {
|
|
|
|
|
(*root).into()
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
/// A node of the Sapling Incremental Note Commitment Tree.
|
|
|
|
|
///
|
|
|
|
|
/// Note that it's handled as a byte buffer and not a point coordinate (jubjub::Fq)
|
|
|
|
|
/// because that's how the spec handles the MerkleCRH^Sapling function inputs and outputs.
|
|
|
|
|
#[derive(Clone, Debug)]
|
|
|
|
|
struct Node([u8; 32]);
|
|
|
|
|
|
|
|
|
|
impl incrementalmerkletree::Hashable for Node {
|
|
|
|
|
fn empty_leaf() -> Self {
|
|
|
|
|
Self(NoteCommitmentTree::uncommitted())
|
|
|
|
|
}
|
2019-09-25 23:23:04 -07:00
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
/// Combine two nodes to generate a new node in the given level.
|
|
|
|
|
/// Level 0 is the layer above the leaves (layer 31).
|
|
|
|
|
/// Level 31 is the root (layer 0).
|
|
|
|
|
fn combine(level: incrementalmerkletree::Altitude, a: &Self, b: &Self) -> Self {
|
|
|
|
|
let layer = (MERKLE_DEPTH - 1) as u8 - u8::from(level);
|
|
|
|
|
Self(merkle_crh_sapling(layer, a.0, b.0))
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Return the node for the level below the given level. (A quirk of the API)
|
|
|
|
|
fn empty_root(level: incrementalmerkletree::Altitude) -> Self {
|
|
|
|
|
let layer_below: usize = MERKLE_DEPTH - usize::from(level);
|
|
|
|
|
Self(EMPTY_ROOTS[layer_below])
|
2019-09-25 23:23:04 -07:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
impl From<jubjub::Fq> for Node {
|
|
|
|
|
fn from(x: jubjub::Fq) -> Self {
|
|
|
|
|
Node(x.into())
|
|
|
|
|
}
|
|
|
|
|
}
|
2020-09-15 12:20:17 -07:00
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
#[allow(dead_code, missing_docs)]
|
|
|
|
|
#[derive(Error, Debug, PartialEq)]
|
|
|
|
|
pub enum NoteCommitmentTreeError {
|
|
|
|
|
#[error("The note commitment tree is full")]
|
|
|
|
|
FullTree,
|
|
|
|
|
}
|
2020-09-15 12:20:17 -07:00
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
/// Sapling Incremental Note Commitment Tree.
|
|
|
|
|
#[derive(Clone, Debug)]
|
|
|
|
|
pub struct NoteCommitmentTree {
|
|
|
|
|
/// The tree represented as a Frontier.
|
|
|
|
|
///
|
|
|
|
|
/// A Frontier is a subset of the tree that allows to fully specify it.
|
|
|
|
|
/// It consists of nodes along the rightmost (newer) branch of the tree that
|
|
|
|
|
/// has non-empty nodes. Upper (near root) empty nodes of the branch are not
|
|
|
|
|
/// stored.
|
|
|
|
|
inner: bridgetree::Frontier<Node, { MERKLE_DEPTH as u8 }>,
|
|
|
|
|
}
|
2020-09-15 12:20:17 -07:00
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
impl NoteCommitmentTree {
|
|
|
|
|
/// Adds a note commitment u-coordinate to the tree.
|
|
|
|
|
///
|
|
|
|
|
/// The leaves of the tree are actually a base field element, the
|
|
|
|
|
/// u-coordinate of the commitment, the data that is actually stored on the
|
|
|
|
|
/// chain and input into the proof.
|
|
|
|
|
///
|
|
|
|
|
/// Returns an error if the tree is full.
|
|
|
|
|
pub fn append(&mut self, cm_u: jubjub::Fq) -> Result<(), NoteCommitmentTreeError> {
|
|
|
|
|
if self.inner.append(&cm_u.into()) {
|
|
|
|
|
Ok(())
|
|
|
|
|
} else {
|
|
|
|
|
Err(NoteCommitmentTreeError::FullTree)
|
2020-09-15 12:20:17 -07:00
|
|
|
|
}
|
2019-09-25 23:23:04 -07:00
|
|
|
|
}
|
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
/// Returns the current root of the tree, used as an anchor in Sapling
|
|
|
|
|
/// shielded transactions.
|
|
|
|
|
pub fn root(&self) -> Root {
|
|
|
|
|
Root(self.inner.root().0)
|
|
|
|
|
}
|
|
|
|
|
|
2020-09-15 12:20:17 -07:00
|
|
|
|
/// Get the Jubjub-based Pedersen hash of root node of this merkle tree of
|
2021-07-15 06:58:36 -07:00
|
|
|
|
/// note commitments.
|
2020-09-15 12:20:17 -07:00
|
|
|
|
pub fn hash(&self) -> [u8; 32] {
|
2021-07-15 06:58:36 -07:00
|
|
|
|
self.root().into()
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// An as-yet unused Sapling note commitment tree leaf node.
|
|
|
|
|
///
|
|
|
|
|
/// Distinct for Sapling, a distinguished hash value of:
|
|
|
|
|
///
|
|
|
|
|
/// Uncommitted^Sapling = I2LEBSP_l_MerkleSapling(1)
|
|
|
|
|
pub fn uncommitted() -> [u8; 32] {
|
|
|
|
|
jubjub::Fq::one().to_bytes()
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Count of note commitments added to the tree.
|
|
|
|
|
///
|
|
|
|
|
/// For Sapling, the tree is capped at 2^32.
|
|
|
|
|
pub fn count(&self) -> u64 {
|
|
|
|
|
self.inner
|
|
|
|
|
.position()
|
|
|
|
|
.map_or(0, |pos| usize::from(pos) as u64 + 1)
|
2019-09-25 23:23:04 -07:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
impl Default for NoteCommitmentTree {
|
|
|
|
|
fn default() -> Self {
|
|
|
|
|
Self {
|
|
|
|
|
inner: bridgetree::Frontier::new(),
|
2020-09-18 23:52:36 -07:00
|
|
|
|
}
|
|
|
|
|
}
|
2021-07-15 06:58:36 -07:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
impl Eq for NoteCommitmentTree {}
|
|
|
|
|
|
|
|
|
|
impl PartialEq for NoteCommitmentTree {
|
|
|
|
|
fn eq(&self, other: &Self) -> bool {
|
|
|
|
|
self.hash() == other.hash()
|
|
|
|
|
}
|
|
|
|
|
}
|
2020-09-18 23:52:36 -07:00
|
|
|
|
|
2021-07-15 06:58:36 -07:00
|
|
|
|
impl From<Vec<jubjub::Fq>> for NoteCommitmentTree {
|
|
|
|
|
/// Compute the tree from a whole bunch of note commitments at once.
|
|
|
|
|
fn from(values: Vec<jubjub::Fq>) -> Self {
|
|
|
|
|
let mut tree = Self::default();
|
|
|
|
|
|
|
|
|
|
if values.is_empty() {
|
|
|
|
|
return tree;
|
2020-09-18 23:52:36 -07:00
|
|
|
|
}
|
2021-07-15 06:58:36 -07:00
|
|
|
|
|
|
|
|
|
for cm_u in values {
|
|
|
|
|
let _ = tree.append(cm_u);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
tree
|
2019-09-25 23:23:04 -07:00
|
|
|
|
}
|
|
|
|
|
}
|