{"id":23536567,"url":"https://github.com/polytope-labs/solidity-merkle-trees","last_synced_at":"2025-05-16T07:07:13.839Z","repository":{"id":65368790,"uuid":"583419398","full_name":"polytope-labs/solidity-merkle-trees","owner":"polytope-labs","description":"The most advanced solidity library for merkle (multi) proof verification of different kinds of merkle trees","archived":false,"fork":false,"pushed_at":"2024-12-09T20:34:00.000Z","size":209,"stargazers_count":189,"open_issues_count":2,"forks_count":36,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-12T04:47:33.316Z","etag":null,"topics":["algorithms","cryptography","ethereum","merkle-mountain-range","merkle-multi-proofs","merkle-patricia-trie","merkle-proof","merkle-tree","solidity","substrate"],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polytope-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-29T18:12:47.000Z","updated_at":"2025-03-19T22:52:10.000Z","dependencies_parsed_at":"2023-02-11T19:00:48.631Z","dependency_job_id":"febd18ca-5ae3-49ee-a01d-bf16df6e1cc2","html_url":"https://github.com/polytope-labs/solidity-merkle-trees","commit_stats":{"total_commits":37,"total_committers":9,"mean_commits":4.111111111111111,"dds":0.5945945945945945,"last_synced_commit":"f637bb083eb6bdef3daee016e300a56800c2725e"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polytope-labs%2Fsolidity-merkle-trees","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polytope-labs%2Fsolidity-merkle-trees/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polytope-labs%2Fsolidity-merkle-trees/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polytope-labs%2Fsolidity-merkle-trees/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polytope-labs","download_url":"https://codeload.github.com/polytope-labs/solidity-merkle-trees/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254485065,"owners_count":22078767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithms","cryptography","ethereum","merkle-mountain-range","merkle-multi-proofs","merkle-patricia-trie","merkle-proof","merkle-tree","solidity","substrate"],"created_at":"2024-12-26T02:29:28.271Z","updated_at":"2025-05-16T07:07:08.817Z","avatar_url":"https://github.com/polytope-labs.png","language":"Solidity","funding_links":[],"categories":["Libraries \u0026 Frameworks"],"sub_categories":[],"readme":"# `@polytope-labs/solidity-merkle-trees`\n\n![Unit Tests](https://github.com/polytope-labs/solidity-merkle-trees/actions/workflows/test.yml/badge.svg)\n[![NPM](https://img.shields.io/npm/v/@polytope-labs/solidity-merkle-trees?label=%40polytope-labs%2Fsolidity-merkle-trees)](https://www.npmjs.com/package/@polytope-labs/solidity-merkle-trees)\n\n\u003cimg src=\"assets/web3 foundation_grants_badge_white.png\"  style=\"max-width: 100%; height: auto; max-height: 20em\"\u003e\n\nThis library contains the implementations of various merkle tree verification algorithms. Currently supported algorithms:\n\u003cbr /\u003e\n\n- [x] Merkle Trees (supports unbalanced trees).\n- [x] Merkle Mountain Ranges.\n- [x] Merkle-Patricia Trie.\n\n\n## Installation\n\n```\nnpm install @polytope-labs/solidity-merkle-trees\n```\n\n## Merkle Multi Proofs\n\nThis algorithm is based on the research done here: https://research.polytope.technology/merkle-multi-proofs\n\nYou can use it to verify proofs like so:\n\n```solidity\npragma solidity ^0.8.0;\n\nimport \"@polytope-labs/solidity-merkle-trees/MerkleMultiProof.sol\";\n\ncontract YourContract {\n    function verify(\n        bytes32 root,\n        Node[][] memory proof,\n        Node[] leaves\n    ) public {\n        require(MerkleMultiProof.VerifyProof(root, proof, leaves), \"Invalid proof\");\n    }\n}\n```\n\nYou can generate the 2D merkle multi proofs using this rust lib [polytope-labs/rs-merkle](https://github.com/polytope-labs/rs-merkle)\n\n## Merkle Mountain Range Multi Proofs\n\nThis algorithm is based on the research done here: https://research.polytope.technology/merkle-mountain-range-multi-proofs\n\nYou can use it to verify proofs like so:\n\n```solidity\npragma solidity ^0.8.0;\n\nimport \"@polytope-labs/solidity-merkle-trees/MerkleMountainRange.sol\";\n\ncontract YourContract {\n    function verify(\n        bytes32 root,\n        bytes32[] memory proof,\n        MmrLeaf[] memory leaves,\n        uint256 mmrSize\n    ) public {\n        require(MerkleMountainRange.VerifyProof(root, proof, leaves, mmrSize), \"Invalid proof\");\n    }\n}\n```\n\nYou can derive the k-indices for the mmr leaves using this rust lib [polytope-labs/merkle-mountain-range](https://github.com/polytope-labs/merkle-mountain-range).\n\n## Merkle Patricia Trie\n\nThis library also supports the verification of the different styles of merkle patricia tries:\n\n- [x] Substrate\n- [x] Ethereum\n- [ ] NEAR\n      \u003cbr /\u003e\n\n```solidity\npragma solidity ^0.8.0;\n\nimport \"@polytope-labs/solidity-merkle-trees/MerklePatricia.sol\";\n\ncontract YourContract {\n    function verifySubstrateProof(\n        bytes32 root,\n        bytes[] memory proof,\n        bytes[] memory keys,\n    ) public {\n        bytes[] values = MerklePatricia.VerifySubstrateProof(root, proof, keys); // verifies proofs from state.getReadProof\n        // do something with the verified values.\n    }\n\n    function verifyEthereumProof(\n        bytes32 root,\n        bytes[] memory proof,\n        bytes[] memory keys,\n    ) public {\n        // verifies ethereum specific merkle patricia proofs as described by EIP-1188.\n        // can be used to verify the receipt trie, transaction trie and state trie\n        // contributed by @ripa1995\n        bytes[] values = MerklePatricia.VerifyEthereumProof(root, proof, keys);\n        // do something with the verified values.\n      }\n}\n```\n\n## Testing Guide\n\nThis guide assumes [Rust](https://www.rust-lang.org/tools/install)...along with it's [nightly](https://rust-lang.github.io/rustup/concepts/channels.html#:~:text=it%20just%20run-,rustup%20toolchain%20install%20nightly,-%3A) version, [Solidity](https://docs.soliditylang.org/en/v0.8.17/installing-solidity.html), [cargo-fuzz](https://github.com/rust-fuzz/cargo-fuzz) and [Forge](https://github.com/foundry-rs/foundry/blob/master/README.md) are installed, if not browse the official websites/repositories for instructions.\n\nChange into the forge directory and build the contracts;\n\n```bash\ncd forge\nforge build\n```\n\nTo run the unit tests associated with the Merkle Multi Proof library;\n\n```bash\ncargo test --lib merkle_multi_proof\n```\n\nTo run the unit tests associated with the Merkle Mountain Range library;\n\n```bash\ncargo test --lib merkle_mountain_range\n```\n\nTo run the unit and fuzz tests associated with the Merkle Patricia Trie library;\n\n```bash\ncargo test --lib merkle_patricia\ncargo +nightly fuzz run trie_proof_valid\ncargo +nightly fuzz run trie_proof_invalid\n```\n\n### Run Tests in Docker\n\nExecute the following commands in the project directory:\n\n```bash\ngit submodule update --init --recursive\n# run tests for all merkle verifiers\ndocker run --memory=\"24g\" --rm --user root -v \"$PWD\":/app -w /app rust:latest cargo test --release --manifest-path=./forge/Cargo.toml\n# fuzz the merkle-patricia verifier\ndocker build -t test .\ndocker run --memory=\"24g\" --rm --user root -v \"$PWD\":/app -w /app/forge/fuzz test cargo +nightly fuzz run trie_proof_valid\ndocker run --memory=\"24g\" --rm --user root -v \"$PWD\":/app -w /app/forge/fuzz test cargo +nightly fuzz run trie_proof_invalid\n\n```\n\n## License\n\nThis library is licensed under the [Apache 2.0 License](./LICENSE), Copyright (c) 2023 Polytope Labs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolytope-labs%2Fsolidity-merkle-trees","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolytope-labs%2Fsolidity-merkle-trees","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolytope-labs%2Fsolidity-merkle-trees/lists"}