From ece2d0f09bf08c1c733c00a9033cc594b193bf22 Mon Sep 17 00:00:00 2001
From: Marek <mail@marek.onl>
Date: Fri, 14 Jan 2022 02:28:35 +0100
Subject: [PATCH] Document the consensus rules for note commitment trees
 (#3319)

Co-authored-by: teor <teor@riseup.net>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
---
 zebra-chain/src/orchard/tree.rs | 10 ++++++++++
 zebra-chain/src/sapling/tree.rs | 10 ++++++++++
 zebra-chain/src/sprout/tree.rs  |  9 +++++++++
 3 files changed, 29 insertions(+)

diff --git a/zebra-chain/src/orchard/tree.rs b/zebra-chain/src/orchard/tree.rs
index c8cab34bd..a2c86a3e0 100644
--- a/zebra-chain/src/orchard/tree.rs
+++ b/zebra-chain/src/orchard/tree.rs
@@ -221,7 +221,17 @@ pub struct NoteCommitmentTree {
     /// 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.
+    ///
+    /// # Consensus
+    ///
+    /// > [NU5 onward] A block MUST NOT add Orchard note commitments that would result in the Orchard note
+    /// > commitment tree exceeding its capacity of 2^(MerkleDepth^Orchard) leaf nodes.
+    ///
+    /// <https://zips.z.cash/protocol/protocol.pdf#merkletree>
+    ///
+    /// Note: MerkleDepth^Orchard = MERKLE_DEPTH = 32.
     inner: bridgetree::Frontier<Node, { MERKLE_DEPTH as u8 }>,
+
     /// A cached root of the tree.
     ///
     /// Every time the root is computed by [`Self::root`] it is cached here,
diff --git a/zebra-chain/src/sapling/tree.rs b/zebra-chain/src/sapling/tree.rs
index 1f02d6f46..15af1ba76 100644
--- a/zebra-chain/src/sapling/tree.rs
+++ b/zebra-chain/src/sapling/tree.rs
@@ -184,7 +184,17 @@ pub struct NoteCommitmentTree {
     /// 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.
+    ///
+    /// # Consensus
+    ///
+    /// > [Sapling onward] A block MUST NOT add Sapling note commitments that would result in the Sapling note
+    /// > commitment tree exceeding its capacity of 2^(MerkleDepth^Sapling) leaf nodes.
+    ///
+    /// <https://zips.z.cash/protocol/protocol.pdf#merkletree>
+    ///
+    /// Note: MerkleDepth^Sapling = MERKLE_DEPTH = 32.
     inner: bridgetree::Frontier<Node, { MERKLE_DEPTH as u8 }>,
+
     /// A cached root of the tree.
     ///
     /// Every time the root is computed by [`Self::root`] it is cached here,
diff --git a/zebra-chain/src/sprout/tree.rs b/zebra-chain/src/sprout/tree.rs
index 06fd59de1..ffc2a0c23 100644
--- a/zebra-chain/src/sprout/tree.rs
+++ b/zebra-chain/src/sprout/tree.rs
@@ -209,6 +209,15 @@ pub struct NoteCommitmentTree {
     /// 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.
+    ///
+    /// # Consensus
+    ///
+    /// > A block MUST NOT add Sprout note commitments that would result in the Sprout note commitment tree
+    /// > exceeding its capacity of 2^(MerkleDepth^Sprout) leaf nodes.
+    ///
+    /// <https://zips.z.cash/protocol/protocol.pdf#merkletree>
+    ///
+    /// Note: MerkleDepth^Sprout = MERKLE_DEPTH = 29.
     inner: bridgetree::Frontier<Node, { MERKLE_DEPTH as u8 }>,
 
     /// A cached root of the tree.