add non-existence proofs documentation in the mdbook, mv EMPTY->EMPTY_VALUE & NULL->EMPTY_HASH

arnaucube · arnaucube · commit 3ced8ea0fad8 · 2025-03-17T18:18:38.000+01:00
diff --git a/book/src/merkletree.md b/book/src/merkletree.md
@@ -137,6 +137,10 @@ Since leaf positions are deterministic based on the key, the same approach is us
 
 For the current use cases, we don't need to prove that the key exists but the value is different on that leaf, so we only use the option 1.
 
+There are 2 cases to have into account when dealing with non-inclusion proofs:
+- case i) the expected leaf does not exist.
+- case ii) the expected leaf does exist in the tree, but it has a different `key`.
+
 
 ## Encoding
 > TODO: how key-values, nodes, merkle-proofs, ... are encoded.
diff --git a/src/backends/plonky2/basetypes.rs b/src/backends/plonky2/basetypes.rs
@@ -30,10 +30,9 @@ pub type Proof = Plonky2Proof<F, PoseidonGoldilocksConfig, D>;
 pub const HASH_SIZE: usize = 4;
 pub const VALUE_SIZE: usize = 4;
 
-// TODO mv `EMPTY`-> `EMTPY_VALUE`, and `NULL` -> `EMPTY_HASH`.
-pub const EMPTY: Value = Value([F::ZERO, F::ZERO, F::ZERO, F::ZERO]);
+pub const EMPTY_VALUE: Value = Value([F::ZERO, F::ZERO, F::ZERO, F::ZERO]);
 pub const SELF_ID_HASH: Hash = Hash([F::ONE, F::ZERO, F::ZERO, F::ZERO]);
-pub const NULL: Hash = Hash([F::ZERO, F::ZERO, F::ZERO, F::ZERO]);
+pub const EMPTY_HASH: Hash = Hash([F::ZERO, F::ZERO, F::ZERO, F::ZERO]);
 
 #[derive(Clone, Copy, Debug, Default, Hash, PartialEq, Eq)]
 pub struct Value(pub [F; VALUE_SIZE]);
diff --git a/src/backends/plonky2/mock_signed.rs b/src/backends/plonky2/mock_signed.rs
@@ -110,7 +110,7 @@ pub mod tests {
     use super::*;
     use crate::constants::MAX_DEPTH;
     use crate::frontend;
-    use crate::middleware::{self, F, NULL};
+    use crate::middleware::{self, EMPTY_HASH, F};
 
     #[test]
     fn test_mock_signed_0() -> Result<()> {
@@ -137,7 +137,7 @@ pub mod tests {
         assert!(!bad_pod.verify());
 
         let mut bad_pod = pod.clone();
-        let bad_kv = (hash_str(KEY_SIGNER).into(), Value(PodId(NULL).0 .0));
+        let bad_kv = (hash_str(KEY_SIGNER).into(), Value(PodId(EMPTY_HASH).0 .0));
         let bad_kvs_mt = &bad_pod
             .kvs()
             .into_iter()
diff --git a/src/backends/plonky2/primitives/merkletree.rs b/src/backends/plonky2/primitives/merkletree.rs
@@ -7,7 +7,7 @@ use std::fmt;
 use std::iter::IntoIterator;
 
 use crate::backends::counter;
-use crate::backends::plonky2::basetypes::{hash_fields, Hash, Value, F, NULL};
+use crate::backends::plonky2::basetypes::{hash_fields, Hash, Value, EMPTY_HASH, F};
 
 // mod merkletree_circuit;
 pub use super::merkletree_circuit::*;
@@ -182,7 +182,7 @@ impl MerkleTree {
 pub fn kv_hash(key: &Value, value: Option<Value>) -> Hash {
     value
         .map(|v| hash_fields(&[key.0.to_vec(), v.0.to_vec(), vec![GoldilocksField(1)]].concat()))
-        .unwrap_or(NULL)
+        .unwrap_or(EMPTY_HASH)
 }
 
 impl<'a> IntoIterator for &'a MerkleTree {
@@ -305,14 +305,14 @@ impl Node {
     }
     fn compute_hash(&mut self) -> Hash {
         match self {
-            Self::None => NULL,
+            Self::None => EMPTY_HASH,
             Self::Leaf(l) => l.compute_hash(),
             Self::Intermediate(n) => n.compute_hash(),
         }
     }
     fn hash(&self) -> Hash {
         match self {
-            Self::None => NULL,
+            Self::None => EMPTY_HASH,
             Self::Leaf(l) => l.hash(),
             Self::Intermediate(n) => n.hash(),
         }
@@ -475,8 +475,8 @@ impl Intermediate {
     }
     fn compute_hash(&mut self) -> Hash {
         if self.left.clone().is_empty() && self.right.clone().is_empty() {
-            self.hash = Some(NULL);
-            return NULL;
+            self.hash = Some(EMPTY_HASH);
+            return EMPTY_HASH;
         }
         let l_hash = self.left.compute_hash();
         let r_hash = self.right.compute_hash();
diff --git a/src/backends/plonky2/primitives/merkletree_circuit.rs b/src/backends/plonky2/primitives/merkletree_circuit.rs
@@ -24,7 +24,7 @@ use std::iter::IntoIterator;
 
 use crate::backends::counter;
 use crate::backends::plonky2::basetypes::{
-    hash_fields, Hash, Value, D, EMPTY, F, HASH_SIZE, NULL, VALUE_SIZE,
+    hash_fields, Hash, Value, D, EMPTY_HASH, EMPTY_VALUE, F, HASH_SIZE, VALUE_SIZE,
 };
 use crate::backends::plonky2::primitives::merkletree::MerkleProof;
 
@@ -34,7 +34,6 @@ pub struct MerkleProofCircuit<const MAX_DEPTH: usize> {
     value: Vec<Target>,
     existence: BoolTarget,
     siblings: Vec<HashOutTarget>,
-    // siblings_selectors: Vec<BoolTarget>,
     case_ii_selector: BoolTarget, // for case ii)
     other_key: Vec<Target>,
     other_value: Vec<Target>,
@@ -49,7 +48,7 @@ impl<const MAX_DEPTH: usize> MerkleProofCircuit<MAX_DEPTH> {
         let value = builder.add_virtual_targets(VALUE_SIZE);
         // from proof struct:
         let existence = builder.add_virtual_bool_target_safe();
-        // siblings are padded
+        // siblings are padded till MAX_DEPTH length
         let siblings = builder.add_virtual_hashes(MAX_DEPTH);
 
         let case_ii_selector = builder.add_virtual_bool_target_safe();
@@ -102,7 +101,7 @@ impl<const MAX_DEPTH: usize> MerkleProofCircuit<MAX_DEPTH> {
 
         // if we're in the case i), use leaf_hash=EMPTY_HASH, else use the
         // previously computed hash h.
-        let empty_hash = builder.constant_hash(HashOut::from(NULL.0));
+        let empty_hash = builder.constant_hash(HashOut::from(EMPTY_HASH.0));
         let leaf_hash = HashOutTarget::from_vec(
             (0..4)
                 .map(|j| builder.select(case_i_selector, empty_hash.elements[j], h.elements[j]))
@@ -115,10 +114,7 @@ impl<const MAX_DEPTH: usize> MerkleProofCircuit<MAX_DEPTH> {
         // compute the root for the given siblings and the computed leaf_hash
         // (this is for the three cases (existence, non-existence case i, and
         // non-existence case ii)
-        let computed_root = Self::compute_root_from_leaf(
-            builder, &path, &leaf_hash, &siblings,
-            // &siblings_selectors,
-        )?;
+        let computed_root = Self::compute_root_from_leaf(builder, &path, &leaf_hash, &siblings)?;
         // ensure that the computed root matches the given root (which is a
         // public input)
         builder.connect_hashes(computed_root, root);
@@ -152,7 +148,7 @@ impl<const MAX_DEPTH: usize> MerkleProofCircuit<MAX_DEPTH> {
 
         // pad siblings with zeros to length MAX_DEPTH
         let mut siblings = proof.siblings.clone();
-        siblings.resize(MAX_DEPTH, NULL);
+        siblings.resize(MAX_DEPTH, EMPTY_HASH);
         assert_eq!(self.siblings.len(), siblings.len());
 
         for (i, sibling) in siblings.iter().enumerate() {
@@ -167,8 +163,8 @@ impl<const MAX_DEPTH: usize> MerkleProofCircuit<MAX_DEPTH> {
         } else {
             // existence & non-existence case i) expected leaf does not exist
             pw.set_bool_target(self.case_ii_selector, false)?;
-            pw.set_target_arr(&self.other_key, &EMPTY.0.to_vec())?;
-            pw.set_target_arr(&self.other_value, &EMPTY.0.to_vec())?;
+            pw.set_target_arr(&self.other_key, &EMPTY_VALUE.0.to_vec())?;
+            pw.set_target_arr(&self.other_value, &EMPTY_VALUE.0.to_vec())?;
         }
 
         Ok(())
@@ -408,7 +404,7 @@ pub mod tests {
             (key, value, proof)
         } else {
             let key = Value::from(hash_value(&Value::from(200)));
-            (key, EMPTY, tree.prove_nonexistence(&key)?)
+            (key, EMPTY_VALUE, tree.prove_nonexistence(&key)?)
         };
         assert_eq!(proof.existence, existence);
 
@@ -473,7 +469,7 @@ pub mod tests {
             tree.prove(&key)?
         } else {
             let proof = tree.prove_nonexistence(&key)?;
-            (EMPTY, proof)
+            (EMPTY_VALUE, proof)
         };
 
         assert_eq!(proof.existence, contains);
diff --git a/src/middleware/basetypes.rs b/src/middleware/basetypes.rs
@@ -35,6 +35,6 @@
 /// then the Value, Hash and F types would come from the plonky3 backend.
 #[cfg(feature = "backend_plonky2")]
 pub use crate::backends::plonky2::basetypes::{
-    hash_fields, hash_str, hash_value, Hash, Value, EMPTY, F, HASH_SIZE, NULL, SELF_ID_HASH,
-    VALUE_SIZE,
+    hash_fields, hash_str, hash_value, Hash, Value, EMPTY_HASH, EMPTY_VALUE, F, HASH_SIZE,
+    SELF_ID_HASH, VALUE_SIZE,
 };
diff --git a/src/middleware/containers.rs b/src/middleware/containers.rs
@@ -8,7 +8,7 @@ use crate::constants::MAX_DEPTH;
 #[cfg(feature = "backend_plonky2")]
 use crate::backends::plonky2::primitives::merkletree::{Iter as TreeIter, MerkleProof, MerkleTree};
 
-use super::basetypes::{hash_value, Hash, Value, EMPTY};
+use super::basetypes::{hash_value, Hash, Value, EMPTY_VALUE};
 
 /// Dictionary: the user original keys and values are hashed to be used in the leaf.
 ///    leaf.key=hash(original_key)
@@ -78,7 +78,7 @@ impl Set {
             .iter()
             .map(|e| {
                 let h = hash_value(e);
-                (Value::from(h), EMPTY)
+                (Value::from(h), EMPTY_VALUE)
             })
             .collect();
         Ok(Self {
@@ -99,7 +99,7 @@ impl Set {
         self.mt.prove_nonexistence(value)
     }
     pub fn verify(root: Hash, proof: &MerkleProof, value: &Value) -> Result<()> {
-        MerkleTree::verify(MAX_DEPTH, root, proof, value, &EMPTY)
+        MerkleTree::verify(MAX_DEPTH, root, proof, value, &EMPTY_VALUE)
     }
     pub fn verify_nonexistence(root: Hash, proof: &MerkleProof, value: &Value) -> Result<()> {
         MerkleTree::verify_nonexistence(MAX_DEPTH, root, proof, value)
diff --git a/src/middleware/mod.rs b/src/middleware/mod.rs
@@ -23,7 +23,7 @@ impl fmt::Display for PodId {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         if *self == SELF {
             write!(f, "self")
-        } else if self.0 == NULL {
+        } else if self.0 == EMPTY_HASH {
             write!(f, "null")
         } else {
             write!(f, "{}", self.0)
@@ -185,7 +185,7 @@ impl Pod for NonePod {
         true
     }
     fn id(&self) -> PodId {
-        PodId(NULL)
+        PodId(EMPTY_HASH)
     }
     fn pub_statements(&self) -> Vec<Statement> {
         Vec::new()
