Merkleproof verify circuit (#143)

* merkletree: add keypath circuit

* merkletree-circuit: implement proof of existence verification in-circuit

* parametrize max_depth at the tree circuit

* Constrain selectors in-circuit

* implement merketree nonexistence proof circuit, and add edgecase tests

* add non-existence proofs documentation in the mdbook, mv EMPTY->EMPTY_VALUE & NULL->EMPTY_HASH, dependency clean and public exposure methods

* review comments, some extra polishing and add a test that expects wrong proofs to fail

* Add circuit to check only merkleproofs-of-existence

With this, the merkletree_circuit module offers two different circuits:
- `MerkleProofCircuit`: allows to verify both proofs of existence and proofs
non-existence with the same circuit.
- `MerkleProofExistenceCircuit`: allows to verify proofs of existence only.

In this way, if only proofs of existence are needed,
`MerkleProofExistenceCircuit` should be used, which requires less amount
of constraints than `MerkleProofCircuit`.

* Code review

---------

Co-authored-by: Ahmad <[email protected]>

Author: arnaucube

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.

src/backends/plonky2/basetypes.rs

@@ -30,9 +30,9 @@ pub type Proof = Plonky2Proof<F, PoseidonGoldilocksConfig, D>;
 pub const HASH_SIZE: usize = 4;
 pub const VALUE_SIZE: usize = 4;
 
-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]);

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()

src/backends/plonky2/primitives/merkletree.rs

@@ -1,13 +1,16 @@
 //! Module that implements the MerkleTree specified at
 //! https://0xparc.github.io/pod2/merkletree.html .
 use anyhow::{anyhow, Result};
-use plonky2::field::goldilocks_field::GoldilocksField;
+use plonky2::field::types::Field;
 use std::collections::HashMap;
 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::*;
 
 /// Implements the MerkleTree specified at
 /// https://0xparc.github.io/pod2/merkletree.html
@@ -178,8 +181,8 @@ impl MerkleTree {
 /// mitigate fake proofs.
 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(Hash([GoldilocksField(0); 4]))
+        .map(|v| hash_fields(&[key.0.to_vec(), v.0.to_vec(), vec![F::ONE]].concat()))
+        .unwrap_or(EMPTY_HASH)
 }
 
 impl<'a> IntoIterator for &'a MerkleTree {
@@ -209,10 +212,10 @@ pub struct MerkleProof {
     // note: currently we don't use the `_existence` field, we would use if we merge the methods
     // `verify` and `verify_nonexistence` into a single one
     #[allow(unused)]
-    existence: bool,
-    siblings: Vec<Hash>,
+    pub(crate) existence: bool,
+    pub(crate) siblings: Vec<Hash>,
     // other_leaf is used for non-existence proofs
-    other_leaf: Option<(Value, Value)>,
+    pub(crate) other_leaf: Option<(Value, Value)>,
 }
 
 impl fmt::Display for MerkleProof {
@@ -244,11 +247,12 @@ impl MerkleProof {
         let path = keypath(max_depth, *key)?;
         let mut h = kv_hash(key, value);
         for (i, sibling) in self.siblings.iter().enumerate().rev() {
-            let input: Vec<F> = if path[i] {
+            let mut input: Vec<F> = if path[i] {
                 [sibling.0, h.0].concat()
             } else {
                 [h.0, sibling.0].concat()
             };
+            input.push(F::TWO);
             h = hash_fields(&input);
         }
         Ok(h)
@@ -302,14 +306,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(),
         }
@@ -360,7 +364,7 @@ impl Node {
     }
 
     // adds the leaf at the tree from the current node (self), without computing any hash
-    fn add_leaf(&mut self, lvl: usize, max_depth: usize, leaf: Leaf) -> Result<()> {
+    pub(crate) fn add_leaf(&mut self, lvl: usize, max_depth: usize, leaf: Leaf) -> Result<()> {
         counter::count_tree_insert();
 
         if lvl >= max_depth {
@@ -472,12 +476,12 @@ 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();
-        let input: Vec<F> = [l_hash.0, r_hash.0].concat();
+        let input: Vec<F> = [l_hash.0.to_vec(), r_hash.0.to_vec(), vec![F::TWO]].concat();
         let h = hash_fields(&input);
         self.hash = Some(h);
         h
@@ -520,7 +524,7 @@ impl Leaf {
 // max-depth? ie, what happens when two keys share the same path for more bits
 // than the max_depth?
 /// returns the path of the given key
-fn keypath(max_depth: usize, k: Value) -> Result<Vec<bool>> {
+pub(crate) fn keypath(max_depth: usize, k: Value) -> Result<Vec<bool>> {
     let bytes = k.to_bytes();
     if max_depth > 8 * bytes.len() {
         // note that our current keys are of Value type, which are 4 Goldilocks