{"id":27122667,"url":"https://github.com/alilloig/merkle-mountain-range-contracts","last_synced_at":"2026-01-20T03:34:27.514Z","repository":{"id":284558964,"uuid":"950166862","full_name":"alilloig/merkle-mountain-range-contracts","owner":"alilloig","description":"A collection of Merkle Mountain Range implementations for different blockchains","archived":false,"fork":false,"pushed_at":"2025-04-01T15:54:39.000Z","size":48,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T16:26:14.110Z","etag":null,"topics":["blockchain","cadence","move-language","smart-contracts"],"latest_commit_sha":null,"homepage":"","language":"Move","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alilloig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-03-17T18:25:57.000Z","updated_at":"2025-04-01T14:54:11.000Z","dependencies_parsed_at":"2025-03-26T14:41:35.870Z","dependency_job_id":"ed41280d-b618-43e0-926e-4c41bf778f9e","html_url":"https://github.com/alilloig/merkle-mountain-range-contracts","commit_stats":null,"previous_names":["alilloig/sui-merkle-mountain-range","alilloig/merkle-mountain-range-contracts"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilloig%2Fmerkle-mountain-range-contracts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilloig%2Fmerkle-mountain-range-contracts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilloig%2Fmerkle-mountain-range-contracts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alilloig%2Fmerkle-mountain-range-contracts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alilloig","download_url":"https://codeload.github.com/alilloig/merkle-mountain-range-contracts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648878,"owners_count":20972944,"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":["blockchain","cadence","move-language","smart-contracts"],"created_at":"2025-04-07T11:49:54.583Z","updated_at":"2026-01-11T02:43:07.156Z","avatar_url":"https://github.com/alilloig.png","language":"Move","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Merkle Mountain Range\n\n## Introduction\n\nA Merkle Mountain Range (MMR) is a data structure that extends the concept of a Merkle tree to allow for efficient appending of new elements and efficient proof generation. MMRs are particularly useful in scenarios where on-chain data updates are necessary.\n\n### Properties and Applications\n\n1. **Append-Only**: Efficiently supports adding new elements\n2. **Compact Proofs**: Proof size is logarithmic in the number of elements\n3. **Verification Efficiency**: Proofs can be verified quickly\n4. **No Rebalancing**: Unlike traditional Merkle trees, MMRs don't require rebalancing\n\n## Basic Structure and Formation\n\nIn an MMR, nodes are arranged in a series of perfect binary trees (mountains) of decreasing height from left to right. \nWhen a piece of data is to be added to the MMR it gets hashed creating a node that, using 1-based numbering and starting from the left, is added to the MMR. Whenever a left node gains a sibling, a parent node is created by hashing both children together, following sequential numbering. If the newly created parent node already has a right sibling at the same level, another parent node will be created for them, and so on.\n\n### Visualizing an MMR\n\nLet's look at an MMR with 13 leaves (represented by positions 1, 2, 4, 5, 8, 9, 11, 12, 16, 17, 19, 20 and 23):\n\n```\n                               15\n                              /  \\\n                             /    \\\n                            /      \\\n                           7        14          22\n                          / \\      /  \\        /  \\\n                         /   \\    /    \\      /    \\\n                        3     6  10     13   18     21\n                       / \\   / \\ / \\   / \\   / \\   / \\\n                      1   2 4  5 8  9 11 12 16 17 19 20 23\n\n```\n\n## Key concepts\n\nClarifying a few key terms is essential for understanding MMRs and avoiding confusion during implementation, which also improves code readability.\n\n### Position\n\nThe number assigned to each node is called its position. This numbering will be 1-based rather than 0-based as it will be on other data structs. \nWhile this may seem arbitrary, it is crucial for the mathematical properties of MMRs, enabling operations such as calculating a node's height. \nIt is important not to confuse this position with the order in which data was added to the MMR—sometimes referred to as the \"leaf number\"—as this is not relevant to MMR implementation.\n\n### Height \n\nEach node has an associated height depending on which level of the MMR they are placed.\nIn this implementation height is numbered 1-based as positions are.\nBased on the height of a given node, we can differentiate node types.\n\n#### Node Types\n\nA node on the first level, height 1, will always be a **Leaf Node**.\nThese nodes contain the hash of the stored data along with the position of the leaf within the structure.\nThe top nodes of each perfect binary tree (mountain) will be **Peak Nodes**. In our previous example peaks will be nodes 15, 22 and 23.\nIntermediate nodes do not require a specific term, as their height is only relevant for traversal calculations within the MMR.\nGiven a node position, its height can be calculated by iterating through the binary tree it is part of.\n\n### Size\n\nThe total amount of nodes that form the MMR, including leaves and peaks, is referred as the MMR size.\n\n### Root\n\nThe unique identifier of a MMR at a certain point of its life, obtained by hashing together all the peaks (also known as bagging peaks) preceded by its size.\n\n## MMR Proofs\n\nThe minimum necessary set of information from the MMR needed for checking if a piece of data was included on it.\nAll these elements correspond to a specific point in the MMR's lifecycle, meaning that if a proof is generated for the same data at a later time, after more leaves have been added, the proof will differ.\n\n- Position of the leaf where the data was included.\n- Local tree path hashes.\n- Left hand sided peaks.\n- Right hand sided peaks.\n- MMR's root hash and size.\n\nTaking our initial MMR example if we want to generate a proof for the node 16, we will pack in a structure the following information:\n```pseudocode\nstruct Proof {\n   int position = 16\n   [hash] localTreePathHashes = [h(n17),h(n21)]\n   [hash] lhsPeaksHashes = [h(n15)]\n   [hash] rhsPeaksHashes = [h(n23)]\n   hash mmrRoot = h(23,h(n15),h(n22),h(n23))\n   int mmrSize = 23\n}\n```\n\nUnderstanding the concept of local tree path hashes is crucial, as they are the key element in proof generation and verification.\nWhen verifying a proof, we compute the MMR root hash using the proof's information and the data being verified as part of the MMR.\nBy hashing the data to be verified, we can use the **local tree path hashes** to compute all parent node hashes, ultimately deriving the local tree peak hash.\n\n## Acknowledgments\n\nMake sure to check the [CONTRIBUTORS](./CONTRIBUTORS.md) file for proper credit on this!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falilloig%2Fmerkle-mountain-range-contracts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falilloig%2Fmerkle-mountain-range-contracts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falilloig%2Fmerkle-mountain-range-contracts/lists"}