[FEAT]: Implement a Merkle Tree

examples/starknet/contracts/merkle_tree/.gitignore

@@ -0,0 +1,2 @@
+target
+.snfoundry_cache/

examples/starknet/contracts/merkle_tree/.tool-versions

@@ -0,0 +1,6 @@
+scarb 2.9.2
+cairo: 2.9.2
+sierra: 1.6.0
+snforge 0.34.0
+starknet 2.9.2
+starknet-foundry 0.34.0

examples/starknet/contracts/merkle_tree/Scarb.lock

@@ -0,0 +1,22 @@
+# Code generated by scarb DO NOT EDIT.
+version = 1
+
+[[package]]
+name = "merkle_tree"
+version = "0.1.0"
+dependencies = [
+ "snforge_std",
+]
+
+[[package]]
+name = "snforge_scarb_plugin"
+version = "0.34.0"
+source = "git+https://github.com/foundry-rs/starknet-foundry?tag=v0.34.0#d6976d4635cbe69bd199fd502788c469d408ed2d"
+
+[[package]]
+name = "snforge_std"
+version = "0.34.0"
+source = "git+https://github.com/foundry-rs/starknet-foundry?tag=v0.34.0#d6976d4635cbe69bd199fd502788c469d408ed2d"
+dependencies = [
+ "snforge_scarb_plugin",
+]

examples/starknet/contracts/merkle_tree/Scarb.toml

@@ -0,0 +1,49 @@
+[package]
+name = "merkle_tree"
+version = "0.1.0"
+edition = "2024_07"
+
+# See more keys and their definitions at https://docs.swmansion.com/scarb/docs/reference/manifest.html
+
+[dependencies]
+starknet = "2.9.2"
+
+[dev-dependencies]
+snforge_std = { git = "https://github.com/foundry-rs/starknet-foundry", tag = "v0.34.0" }
+assert_macros = "2.9.2"
+
+[[target.starknet-contract]]
+sierra = true
+
+[scripts]
+test = "snforge test"
+
+# Visit https://foundry-rs.github.io/starknet-foundry/appendix/scarb-toml.html for more information
+
+# [tool.snforge]                                             # Define `snforge` tool section
+# exit_first = true                                          # Stop tests execution immediately upon the first failure
+# fuzzer_runs = 1234                                         # Number of runs of the random fuzzer
+# fuzzer_seed = 1111                                         # Seed for the random fuzzer
+
+# [[tool.snforge.fork]]                                      # Used for fork testing
+# name = "SOME_NAME"                                         # Fork name
+# url = "http://your.rpc.url"                                # Url of the RPC provider
+# block_id.tag = "latest"                                    # Block to fork from (block tag)
+
+# [[tool.snforge.fork]]
+# name = "SOME_SECOND_NAME"
+# url = "http://your.second.rpc.url"                         
+# block_id.number = "123"                                    # Block to fork from (block number)
+
+# [[tool.snforge.fork]]
+# name = "SOME_THIRD_NAME"
+# url = "http://your.third.rpc.url"
+# block_id.hash = "0x123"                                    # Block to fork from (block hash)
+
+# [profile.dev.cairo]                                        # Configure Cairo compiler
+# unstable-add-statements-code-locations-debug-info = true   # Should be used if you want to use coverage
+# unstable-add-statements-functions-debug-info = true        # Should be used if you want to use coverage/profiler
+# inlining-strategy = "avoid"                                # Should be used if you want to use coverage
+
+# [features]                                                 # Used for conditional compilation
+# enable_for_tests = []                                      # Feature name and list of other features that should be enabled with it

examples/starknet/contracts/merkle_tree/snfoundry.toml

@@ -0,0 +1,11 @@
+# Visit https://foundry-rs.github.io/starknet-foundry/appendix/snfoundry-toml.html
+# and https://foundry-rs.github.io/starknet-foundry/projects/configuration.html for more information
+
+# [sncast.default]                                         # Define a profile name
+# url = "https://free-rpc.nethermind.io/sepolia-juno/v0_7" # Url of the RPC provider
+# accounts-file = "../account-file"                        # Path to the file with the account data
+# account = "mainuser"                                     # Account from `accounts_file` or default account file that will be used for the transactions
+# keystore = "~/keystore"                                  # Path to the keystore file
+# wait-params = { timeout = 300, retry-interval = 10 }     # Wait for submitted transaction parameters
+# block-explorer = "StarkScan"                             # Block explorer service used to display links to transaction details
+# show-explorer-links = true                               # Print links pointing to pages with transaction details in the chosen block explorer

examples/starknet/contracts/merkle_tree/src/MerkleTree.cairo

@@ -0,0 +1,150 @@
+#[starknet::interface]
+pub trait IMerkleTree<TContractState> {
+    fn hash(ref self: TContractState, data: ByteArray) -> felt252;
+    fn build_tree(ref self: TContractState, data: Array<ByteArray>) -> Array<felt252>;
+    fn get_root(self: @TContractState) -> felt252;
+    fn verify(
+        self: @TContractState, proof: Array<felt252>, root: felt252, leaf: felt252, index: usize,
+    ) -> bool;
+    fn generate_merkle_proof(self: @TContractState, index: u64, data_length: u64) -> Array<felt252>;
+}
+
+mod errors {
+    pub const NOT_PRESENT: felt252 = 'No element in merkle tree';
+}
+
+#[starknet::contract]
+mod MerkleTree {
+    use core::poseidon::PoseidonTrait;
+    use core::hash::{HashStateTrait, HashStateExTrait};
+    use starknet::storage::{
+        StoragePointerWriteAccess, StoragePointerReadAccess, Vec, MutableVecTrait, VecTrait,
+    };
+
+    #[storage]
+    struct Storage {
+        pub hashes: Vec<felt252>,
+    }
+
+    #[abi(embed_v0)]
+    impl IMerkleTreeImpl of super::IMerkleTree<ContractState> {
+        fn hash(ref self: ContractState, data: ByteArray) -> felt252 {
+            let mut serialized_byte_arr: Array<felt252> = ArrayTrait::new();
+            data.serialize(ref serialized_byte_arr);
+
+            core::poseidon::poseidon_hash_span(serialized_byte_arr.span())
+        }
+
+        fn build_tree(ref self: ContractState, mut data: Array<ByteArray>) -> Array<felt252> {
+            let data_len = data.len();
+            let mut _hashes: Array<felt252> = ArrayTrait::new();
+            let mut last_element = Option::None;
+
+            if data_len > 0 && (data_len % 2) != 0 {
+                last_element = Option::Some(data.at(data_len - 1).clone());
+            };
+
+            for value in data {
+                _hashes.append(self.hash(value));
+            };
+
+            let mut current_nodes_lvl_len = data_len;
+            let mut hashes_offset = 0;
+
+            // if data_len is uneven, add the last element to the hashes array
+            match last_element {
+                Option::Some(value) => {
+                    _hashes.append(self.hash(value));
+                    current_nodes_lvl_len += 1;
+                },
+                Option::None => {},
+            };
+
+            while current_nodes_lvl_len > 0 {
+                let mut i = 0;
+                while i < current_nodes_lvl_len - 1 {
+                    let left_elem = *_hashes.at(hashes_offset + i);
+                    let right_elem = *_hashes.at(hashes_offset + i + 1);
+
+                    let hash = PoseidonTrait::new().update_with((left_elem, right_elem)).finalize();
+                    _hashes.append(hash);
+
+                    i += 2;
+                };
+
+                hashes_offset += current_nodes_lvl_len;
+                current_nodes_lvl_len /= 2;
+                if current_nodes_lvl_len > 1 && current_nodes_lvl_len % 2 != 0 {
+                    // duplicate last element of hashes array if current_nodes_lvl_len is uneven
+                    let last_elem = *_hashes.at(_hashes.len() - 1);
+                    _hashes.append(last_elem);
+                    current_nodes_lvl_len += 1;
+                };
+            };
+
+            for hash in _hashes.span() {
+                self.hashes.append().write(*hash);
+            };
+
+            _hashes
+        }
+
+        fn get_root(self: @ContractState) -> felt252 {
+            let merkle_tree_length = self.hashes.len();
+            assert(merkle_tree_length > 0, super::errors::NOT_PRESENT);
+
+            self.hashes.at(merkle_tree_length - 1).read()
+        }
+
+        fn verify(
+            self: @ContractState,
+            mut proof: Array<felt252>,
+            root: felt252,
+            leaf: felt252,
+            mut index: usize,
+        ) -> bool {
+            let mut current_hash = leaf;
+
+            while let Option::Some(proof_value) = proof.pop_front() {
+                current_hash =
+                    if index % 2 == 0 {
+                        PoseidonTrait::new().update_with((current_hash, proof_value)).finalize()
+                    } else {
+                        PoseidonTrait::new().update_with((proof_value, current_hash)).finalize()
+                    };
+
+                index /= 2;
+            };
+
+            current_hash == root
+        }
+
+        fn generate_merkle_proof(
+            self: @ContractState, mut index: u64, data_length: u64
+        ) -> Array<felt252> {
+            let mut proof: Array<felt252> = ArrayTrait::new();
+            let mut offset = 0;
+            let mut current_nodes_lvl_len = if data_length % 2 != 0 {
+                data_length + 1
+            } else {
+                data_length
+            };
+
+            while current_nodes_lvl_len > 1 {
+                let sibling_index = if index % 2 == 0 {
+                    offset + index + 1
+                } else {
+                    offset + index - 1
+                };
+                proof.append(self.hashes.at(sibling_index).read());
+                offset += current_nodes_lvl_len;
+                current_nodes_lvl_len /= 2;
+                index /= 2;
+                if current_nodes_lvl_len > 1 && current_nodes_lvl_len % 2 != 0 {
+                    current_nodes_lvl_len += 1;
+                };
+            };
+            proof
+        }
+    }
+}

examples/starknet/contracts/merkle_tree/src/lib.cairo

@@ -0,0 +1 @@
+pub mod MerkleTree;