Add merkle proof module (#1101)

* feat: add main logic * feat: add hashes tests * feat: add some tests and update hashes * feat: add tests for multi proofs * feat: format files * feat: add more tests * feat: finish poseidon tests * fix: version * fix: typo * refactor: remove unnecessary check * refactor: merkle_tree into a separated package * feat: update CHANGELOG * feat: remove common module from utils * docs: add page for merkle tree * feat: format files * feat: update index from scarb bump * feat: add typos config file * refactor: add empty line * Update packages/utils/src/lib.cairo Co-authored-by: Andrew Fleming <fleming.andrew@protonmail.com> * Update packages/merkle_tree/src/hashes.cairo Co-authored-by: Andrew Fleming <fleming.andrew@protonmail.com> * feat: apple review updates * feat: update test * Update docs/modules/ROOT/pages/api/merkle-tree.adoc Co-authored-by: Andrew Fleming <fleming.andrew@protonmail.com> * Update packages/merkle_tree/src/tests/merkle_proof/test_with_poseidon.cairo Co-authored-by: Andrew Fleming <fleming.andrew@protonmail.com> * Update packages/merkle_tree/src/tests/merkle_proof/test_with_poseidon.cairo Co-authored-by: Andrew Fleming <fleming.andrew@protonmail.com> * Update docs/modules/ROOT/pages/api/merkle-tree.adoc Co-authored-by: immrsd <103599616+immrsd@users.noreply.github.com> * Update docs/modules/ROOT/pages/api/merkle-tree.adoc Co-authored-by: immrsd <103599616+immrsd@users.noreply.github.com> * feat: apply review updates * feat: format files --------- Co-authored-by: Andrew Fleming <fleming.andrew@protonmail.com> Co-authored-by: immrsd <103599616+immrsd@users.noreply.github.com>
OpenZeppelin · Aug 29, 2024 · d4cca89 · d4cca89
1 parent 1e9a40b
commit d4cca89
Show file tree

Hide file tree

Showing 22 changed files with 956 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - ERC2981 (NFT Royalty Standard) component (#1091)
+- `merkle_tree` package with utilities to verify proofs and multi proofs (#1101)
 
 ### Changed
 
@@ -22,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Changed ABI suffix to Trait in dual case account and eth account modules (#1096).
   - `DualCaseAccountABI` renamed to `DualCaseAccountTrait`
   - `DualCaseEthAccountABI` renamed to `DualCaseEthAccountTrait`
+- Bump scarb to v2.7.1 (#1025)
 
 ## 0.15.1 (2024-08-13)
 

diff --git a/Scarb.lock b/Scarb.lock
@@ -9,6 +9,7 @@ dependencies = [
  "openzeppelin_account",
  "openzeppelin_governance",
  "openzeppelin_introspection",
+ "openzeppelin_merkle_tree",
  "openzeppelin_presets",
  "openzeppelin_security",
  "openzeppelin_test_common",
@@ -58,6 +59,13 @@ dependencies = [
  "snforge_std",
 ]
 
+[[package]]
+name = "openzeppelin_merkle_tree"
+version = "0.15.1"
+dependencies = [
+ "snforge_std",
+]
+
 [[package]]
 name = "openzeppelin_presets"
 version = "0.15.1"

diff --git a/Scarb.toml b/Scarb.toml
@@ -4,6 +4,7 @@ members = [
     "packages/account",
     "packages/governance",
     "packages/introspection",
+    "packages/merkle_tree",
     "packages/presets",
     "packages/security",
     "packages/token",
@@ -20,8 +21,8 @@ version.workspace = true
 [workspace.package]
 version = "0.15.1"
 edition = "2023_11"
-cairo-version = "2.7.0"
-scarb-version = "2.7.0"
+cairo-version = "2.7.1"
+scarb-version = "2.7.1"
 authors = ["OpenZeppelin Community <maintainers@openzeppelin.org>"]
 description = "OpenZeppelin Contracts written in Cairo for Starknet, a decentralized ZK Rollup"
 documentation = "https://docs.openzeppelin.com/contracts-cairo"
@@ -34,11 +35,11 @@ keywords = [
     "cairo",
     "contracts",
     "security",
-    "standards",
+    "standards"
 ]
 
 [workspace.dependencies]
-starknet = "2.7.0"
+starknet = "2.7.1"
 snforge_std = { git = "https://github.com/foundry-rs/starknet-foundry.git", tag = "v0.27.0" }
 
 [dependencies]
@@ -47,6 +48,7 @@ openzeppelin_access = { path = "packages/access" }
 openzeppelin_account = { path = "packages/account" }
 openzeppelin_governance = { path = "packages/governance" }
 openzeppelin_introspection = { path = "packages/introspection" }
+openzeppelin_merkle_tree = { path = "packages/merkle_tree" }
 openzeppelin_presets = { path = "packages/presets" }
 openzeppelin_security = { path = "packages/security" }
 openzeppelin_token = { path = "packages/token" }

diff --git a/_typos.toml b/_typos.toml
@@ -0,0 +1,4 @@
+[default]
+extend-ignore-identifiers-re = [
+    "e288874ba",
+]
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -24,6 +24,8 @@
 *** xref:/guides/src5-migration.adoc[Migrating ERC165 to SRC5]
 *** xref:/api/introspection.adoc[API Reference]
 
+** xref:/api/merkle-tree.adoc[Merkle Tree]
+
 ** xref:security.adoc[Security]
 *** xref:/api/security.adoc[API Reference]
 

diff --git a/docs/modules/ROOT/pages/api/merkle-tree.adoc b/docs/modules/ROOT/pages/api/merkle-tree.adoc
@@ -0,0 +1,208 @@
+:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
+:strk-merkle-tree: https://github.com/ericnordelo/strk-merkle-tree[JavaScript library]
+:verify: xref:#merkle_proof-verify[verify]
+:verify_pedersen: xref:#merkle_proof-verify_perdersen[verify_pedersen]
+:verify_poseidon: xref:#merkle_proof-verify_poseidon[verify_poseidon]
+:verify_multi_proof: xref:#merkle_proof-verify_multi_proof[verify_multi_proof]
+:process_multi_proof: xref:#merkle_proof-process_multi_proof[process_multi_proof]
+
+= Merkle Tree
+
+OpenZeppelin Contracts for Cairo provides a `merkle_tree` package with a set of utilities for verifying Merkle Tree proofs on-chain. The tree and the proofs can be generated using this {strk-merkle-tree}.
+
+This module provides:
+
+- `{verify}` - can prove that some value is part of a Merkle tree.
+
+- `{verify_multi_proof}` - can prove multiple values are part of a Merkle tree.
+
+NOTE: `openzeppelin_merkle_tree` doesn't have dependencies outside of `corelib`, and can be used in projects that are not Starknet-related.
+
+[TIP]
+====
+To use it as a standalone package, you can add it in your `Scarb.toml` as follows:
+
+`openzeppelin_merkle_tree = { git = "https://github.com/openzeppelin/cairo-contracts.git", tag = "v0.X.X" }`
+====
+
+== Modules
+
+[.contract]
+[[merkle_proof]]
+=== `++merkle_proof++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.15.1/packages/merkle_tree/src/merkle_proof.cairo[{github-icon},role=heading-link]
+
+```cairo
+use openzeppelin_merkle_tree::merkle_proof;
+```
+
+These functions deal with verification of Merkle Tree proofs.
+
+The tree and the proofs can be generated using this {strk-merkle-tree}. You will find a quickstart guide in the readme.
+
+WARNING: You should avoid using leaf values that are two felt252 long prior to hashing, or use a hash function
+other than the one used to hash internal nodes for hashing leaves. This is because the concatenation of a sorted pair
+of internal nodes in the Merkle tree could be reinterpreted as a leaf value. The JavaScript library generates Merkle
+trees that are safe against this attack out of the box.
+
+[.contract-index]
+.Functions
+--
+* xref:#merkle_proof-verify[`++verify<Hasher>(proof, root, leaf)++`]
+* xref:#merkle_proof-verify_pedersen[`++verify_pedersen(proof, root, leaf)++`]
+* xref:#merkle_proof-verify_poseidon[`++verify_poseidon(proof, root, leaf)++`]
+* xref:#merkle_proof-process_proof[`++process_proof<Hasher>(proof, leaf)++`]
+* xref:#merkle_proof-verify_multi_proof[`++verify_multi_proof<Hasher>(proof, proof_flags, root, leaves)++`]
+* xref:#merkle_proof-process_multi_proof[`++process_multi_proof<Hasher>(proof, proof_flags, leaf)++`]
+--
+
+[#merkle_proof-Functions]
+==== Functions
+
+[.contract-item]
+[[merkle_proof-verify]]
+==== `[.contract-item-name]#++verify<+CommutativeHasher>++#++(proof: Span<felt252>, root: felt252, leaf: felt252) → bool++` [.item-kind]#public#
+
+Returns true if a `leaf` can be proved to be a part of a Merkle tree defined by `root`.
+
+For this, a `proof` must be provided, containing sibling hashes on the branch from the leaf to the root of the tree.
+
+Each pair of leaves and each pair of pre-images are assumed to be sorted.
+
+[NOTE]
+====
+This function expects a `CommutativeHasher` implementation. See xref:#hashes-CommutativeHasher[hashes::CommutativeHasher] for more information.
+
+`{verify_pedersen}` and `{verify_poseidon}` already include the corresponding `Hasher` implementations.
+====
+
+[.contract-item]
+[[merkle_proof-verify_pedersen]]
+==== `[.contract-item-name]#++verify_pedersen++#++(proof: Span<felt252>, root: felt252, leaf: felt252) → bool++` [.item-kind]#public#
+
+Version of `{verify}` using Perdersen as the hashing function.
+
+[.contract-item]
+[[merkle_proof-verify_poseidon]]
+==== `[.contract-item-name]#++verify_poseidon++#++(proof: Span<felt252>, root: felt252, leaf: felt252) → bool++` [.item-kind]#public#
+
+Version of `{verify}` using Poseidon as the hashing function.
+
+[.contract-item]
+[[merkle_proof-process_proof]]
+==== `[.contract-item-name]#++process_proof<+CommutativeHasher>++#++(proof: Span<felt252>, leaf: felt252) → felt252++` [.item-kind]#public#
+
+Returns the rebuilt hash obtained by traversing a Merkle tree up from `leaf` using `proof`.
+
+A `proof` is valid if and only if the rebuilt hash matches the root of the tree.
+
+When processing the proof, the pairs of leaves & pre-images are assumed to be sorted.
+
+NOTE: This function expects a `CommutativeHasher` implementation. See xref:#hashes-CommutativeHasher[hashes::CommutativeHasher] for more information.
+
+[.contract-item]
+[[merkle_proof-verify_multi_proof]]
+==== `[.contract-item-name]#++verify_multi_proof<+CommutativeHasher>++#++(proof: Span<felt252>, proof_flags: Span<bool>, root: felt252, leaves: Span<felt252>) → bool++` [.item-kind]#public#
+
+Returns true if the `leaves` can be simultaneously proven to be a part of a Merkle tree defined
+by `root`, according to `proof` and `proof_flags` as described in `{process_multi_proof}`.
+
+The `leaves` must be validated independently.
+
+CAUTION: Not all Merkle trees admit multiproofs. See `{process_multi_proof}` for details.
+
+NOTE: Consider the case where `root == proof.at(0) && leaves.len() == 0` as it will return `true`.
+
+NOTE: This function expects a `CommutativeHasher` implementation. See xref:#hashes-CommutativeHasher[hashes::CommutativeHasher] for more information.
+
+[.contract-item]
+[[merkle_proof-process_multi_proof]]
+==== `[.contract-item-name]#++process_multi_proof<+CommutativeHasher>++#++(proof: Span<felt252>, proof_flags: Span<bool>, leaves: Span<felt252>) → felt252++` [.item-kind]#public#
+
+Returns the root of a tree reconstructed from `leaves` and sibling nodes in `proof`.
+
+The reconstruction proceeds by incrementally reconstructing all inner nodes by combining a
+leaf/inner node with either another leaf/inner node or a proof sibling node, depending on
+whether each `proof_flags` item is true or false respectively.
+
+[CAUTION]
+====
+Not all Merkle trees admit multiproofs.
+To use multiproofs, it is sufficient to ensure that:
+
+1. The tree is complete (but not necessarily perfect).
+2. The leaves to be proven are in the opposite order they are in the tree.
+(i.e., as seen from right to left starting at the deepest layer and continuing at the next layer).
+====
+
+NOTE: The _empty set_ (i.e. the case where `proof.len() == 1 && leaves.len() == 0`) is
+considered a no-op, and therefore a valid multiproof (i.e. it returns `proof.at(0)`). Consider
+disallowing this case if you're not validating the leaves elsewhere.
+
+NOTE: This function expects a `CommutativeHasher` implementation. See xref:#hashes-CommutativeHasher[hashes::CommutativeHasher] for more information.
+
+
+[.contract]
+[[hashes]]
+=== `++hashes++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.15.1/packages/merkle_tree/src/hashes.cairo[{github-icon},role=heading-link]
+
+```cairo
+use openzeppelin_merkle_tree::hashes;
+```
+
+:pedersen-hasher: xref:#hashes-PedersenCHasher[PedersenCHasher]
+:poseidon-hasher: xref:#hashes-PoseidonCHasher[PoseidonCHasher]
+
+Module providing the trait and default implementations for the commutative hash functions used in
+xref:#merkle_proof[`merkle_proof`].
+
+NOTE: The `{pedersen-hasher}` implementation matches the default node hashing function used in the {strk-merkle-tree}.
+
+[.contract-index]
+.Traits
+--
+* xref:#hashes-CommutativeHasher[`++CommutativeHasher++`]
+--
+
+[.contract-index]
+.Impls
+--
+* xref:#hashes-PedersenCHasher[`++PedersenCHasher++`]
+* xref:#hashes-PoseidonCHasher[`++PoseidonCHasher++`]
+--
+
+[#hashes-Traits]
+==== Traits
+
+[.contract-item]
+[[hashes-CommutativeHasher]]
+==== `[.contract-item-name]#++CommutativeHasher++#` [.item-kind]#trait#
+
+Declares a commutative hash function with the following signature:
+
+`commutative_hash(a: felt252, b: felt252) -> felt252;`
+
+which computes a commutative hash of a sorted pair of `felt252`.
+
+This is usually implemented as an extension of a non-commutative hash function, like
+Pedersen or Poseidon, returning the hash of the concatenation of the two values by first
+sorting them.
+
+Frequently used when working with merkle proofs.
+
+NOTE: The `commutative_hash` function MUST follow the invariant that `commutative_hash(a, b) == commutative_hash(b, a)`.
+
+[#hashes-Impls]
+==== Impls
+
+[.contract-item]
+[[hashes-PedersenCHasher]]
+==== `[.contract-item-name]#++PedersenCHasher++#` [.item-kind]#impl#
+
+Implementation of the `CommutativeHasher` trait which computes the Pedersen hash of chaining the two input values
+with the len (2), sorting the pair first.
+
+[.contract-item]
+[[hashes-PoseidonCHasher]]
+==== `[.contract-item-name]#++PoseidonCHasher++#` [.item-kind]#impl#
+
+Implementation of the `CommutativeHasher` trait which computes the Poseidon hash of the concatenation of two values, sorting the pair first.
diff --git a/docs/modules/ROOT/pages/guides/snip12.adoc b/docs/modules/ROOT/pages/guides/snip12.adoc
@@ -351,7 +351,7 @@ mod CustomERC20 {
         let is_valid_signature_felt = DualCaseAccount { contract_address: owner }
             .is_valid_signature(hash, signature);
 
-        // Check either 'VALID' or True for backwards compatibility
+        // Check either 'VALID' or true for backwards compatibility
         let is_valid_signature = is_valid_signature_felt == starknet::VALIDATED
             || is_valid_signature_felt == 1;
         assert(is_valid_signature, 'Invalid signature');

diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
@@ -21,8 +21,8 @@ before proceeding, and run the following command to check that the installation
 ----
 $ scarb --version
 
-scarb 2.7.0 (e9a2b8716 2024-08-01)
-cairo: 2.7.0 (https://crates.io/crates/cairo-lang-compiler/2.7.0)
+scarb 2.7.1 (e288874ba 2024-08-13)
+cairo: 2.7.1 (https://crates.io/crates/cairo-lang-compiler/2.7.1)
 sierra: 1.6.0
 ----
 

diff --git a/packages/merkle_tree/Scarb.toml b/packages/merkle_tree/Scarb.toml
@@ -0,0 +1,21 @@
+
+[package]
+name = "openzeppelin_merkle_tree"
+version.workspace = true
+edition.workspace = true
+cairo-version.workspace = true
+scarb-version.workspace = true
+authors.workspace = true
+description.workspace = true
+documentation.workspace = true
+readme.workspace = true
+repository.workspace = true
+license-file.workspace = true
+keywords.workspace = true
+
+[tool]
+fmt.workspace = true
+
+[dev-dependencies]
+starknet.workspace = true
+snforge_std.workspace = true