From ab03a376ef171614257796bdfd9415c4b2b76ddd Mon Sep 17 00:00:00 2001
From: Conrado Gouvea <conrado@zfnd.org>
Date: Fri, 18 Feb 2022 23:27:09 -0300
Subject: [PATCH] docs: document consensus rules from 7.3 Spend Description
 Encoding and Consensus (#3575)

---
 zebra-chain/src/sapling/spend.rs         | 10 +++++++++-
 zebra-chain/src/transaction/serialize.rs | 20 +++-----------------
 2 files changed, 12 insertions(+), 18 deletions(-)

diff --git a/zebra-chain/src/sapling/spend.rs b/zebra-chain/src/sapling/spend.rs
index 8b532ede..cd3ab728 100644
--- a/zebra-chain/src/sapling/spend.rs
+++ b/zebra-chain/src/sapling/spend.rs
@@ -193,12 +193,20 @@ impl ZcashDeserialize for Spend<PerSpendAnchor> {
         // https://zips.z.cash/protocol/protocol.pdf#spenddesc
         //
         // See comments below for each specific type.
+        //
+        // > LEOS2IP_{256}(anchorSapling), if present, MUST be less than 𝑞_𝕁.
+        //
+        // https://zips.z.cash/protocol/protocol.pdf#spendencodingandconsensus
+        //
+        // Applies to `per_spend_anchor` below; validated in
+        // [`crate::sapling::tree::Root::zcash_deserialize`].
         Ok(Spend {
             // Type is `ValueCommit^{Sapling}.Output`, i.e. J
             // https://zips.z.cash/protocol/protocol.pdf#abstractcommit
             // See [`commitment::NotSmallOrderValueCommitment::zcash_deserialize`].
             cv: commitment::NotSmallOrderValueCommitment::zcash_deserialize(&mut reader)?,
-            // Type is `B^{[ℓ_{Sapling}_{Merkle}]}`, i.e. 32 bytes
+            // Type is `B^{[ℓ_{Sapling}_{Merkle}]}`, i.e. 32 bytes.
+            // But as mentioned above, we validate it further as an integer.
             per_spend_anchor: (&mut reader).zcash_deserialize_into()?,
             // Type is `B^Y^{[ℓ_{PRFnfSapling}/8]}`, i.e. 32 bytes
             nullifier: note::Nullifier::from(reader.read_32_bytes()?),
diff --git a/zebra-chain/src/transaction/serialize.rs b/zebra-chain/src/transaction/serialize.rs
index 55ca1135..c11aca49 100644
--- a/zebra-chain/src/transaction/serialize.rs
+++ b/zebra-chain/src/transaction/serialize.rs
@@ -207,13 +207,11 @@ impl ZcashDeserialize for Option<sapling::ShieldedData<SharedAnchor>> {
         //
         // Type is `B^{[ℓ_{Sapling}_{Merkle}]}`, i.e. 32 bytes
         //
-        // # Consensus
+        // > LEOS2IP_{256}(anchorSapling), if present, MUST be less than 𝑞_𝕁.
         //
-        // > Elements of a Spend description MUST be valid encodings of the types given above.
+        // https://zips.z.cash/protocol/protocol.pdf#spendencodingandconsensus
         //
-        // https://zips.z.cash/protocol/protocol.pdf#spenddesc
-        //
-        // Type is `B^{[ℓ_{Sapling}_{Merkle}]}`, i.e. 32 bytes
+        // Validated in [`crate::sapling::tree::Root::zcash_deserialize`].
         let shared_anchor = if spends_count > 0 {
             Some((&mut reader).zcash_deserialize_into()?)
         } else {
@@ -233,18 +231,6 @@ impl ZcashDeserialize for Option<sapling::ShieldedData<SharedAnchor>> {
         // It is not enforced here; this just reads 192 bytes.
         // The type is validated when validating the proof, see
         // [`groth16::Item::try_from`]. In #3179 we plan to validate here instead.
-        //
-        // # Consensus
-        //
-        // > Elements of a Spend description MUST be valid encodings of the types given above.
-        //
-        // https://zips.z.cash/protocol/protocol.pdf#spenddesc
-        //
-        // Type is `ZKSpend.Proof`, described in
-        // https://zips.z.cash/protocol/protocol.pdf#grothencoding
-        // It is not enforced here; this just reads 192 bytes.
-        // The type is validated when validating the proof, see
-        // [`groth16::Item::try_from`]. In #3179 we plan to validate here instead.
         let spend_proofs = zcash_deserialize_external_count(spends_count, &mut reader)?;
 
         // Denoted as `vSpendAuthSigsSapling` in the spec.