{"id":18486934,"url":"https://github.com/Tierion/merkle-tools","last_synced_at":"2025-04-08T20:30:31.403Z","repository":{"id":56225919,"uuid":"62061188","full_name":"Tierion/merkle-tools","owner":"Tierion","description":"JavaScript tools for creating Merkle trees, generating merkle proofs, and verification of merkle proofs.","archived":false,"fork":false,"pushed_at":"2023-12-07T20:24:19.000Z","size":62,"stargazers_count":73,"open_issues_count":3,"forks_count":37,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-10-31T15:47:06.843Z","etag":null,"topics":["bitcoin","cryptography","hash","merkle","merkle-tree"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/Tierion.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":"2016-06-27T14:12:00.000Z","updated_at":"2024-07-09T09:49:33.000Z","dependencies_parsed_at":"2024-06-18T13:54:04.155Z","dependency_job_id":"51f146ea-c5cf-4440-b9e8-bcfc977e537e","html_url":"https://github.com/Tierion/merkle-tools","commit_stats":{"total_commits":51,"total_committers":10,"mean_commits":5.1,"dds":0.6666666666666667,"last_synced_commit":"4192f78bc1cfd93dddc1b6ea7d072876f23a4a31"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tierion%2Fmerkle-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tierion%2Fmerkle-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tierion%2Fmerkle-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tierion%2Fmerkle-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tierion","download_url":"https://codeload.github.com/Tierion/merkle-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223343497,"owners_count":17129952,"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":["bitcoin","cryptography","hash","merkle","merkle-tree"],"created_at":"2024-11-06T12:49:58.278Z","updated_at":"2024-11-06T12:50:47.404Z","avatar_url":"https://github.com/Tierion.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# merkle-tools\n\n[![Standard - JavaScript Style Guide](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)\n[![npm](https://img.shields.io/npm/l/merkle-tools.svg)](https://www.npmjs.com/package/merkle-tools)\n[![npm](https://img.shields.io/npm/v/merkle-tools.svg)](https://www.npmjs.com/package/merkle-tools)\n\nTools for creating Merkle trees, generating merkle proofs, and verification of merkle proofs.\n\n## Installation\n\n```\n$ npm install --save merkle-tools\n```\n\n### Create MerkleTools Object\n\n```js\nvar MerkleTools = require('merkle-tools')\n\nvar treeOptions = {\n  hashType: 'md5' // optional, defaults to 'sha256'\n}\n// valid hashTypes include all crypto hash algorithms\n// such as 'MD5', 'SHA1', 'SHA224', 'SHA256', 'SHA384', 'SHA512'\n// as well as the SHA3 family of algorithms\n// including 'SHA3-224', 'SHA3-256', 'SHA3-384', and 'SHA3-512'\n\nvar merkleTools = new MerkleTools(treeOptions) // treeOptions is optional\n```\n\n## Methods\n\n### addLeaf(value, doHash)\n\nAdds a value as a leaf to the tree. The value must be either a Buffer or a hex string, otherwise set the optional doHash to true to have your value hashed prior to being added to the tree. \n\n```js\nvar hexData = '05ae04314577b2783b4be98211d1b72476c59e9c413cfb2afa2f0c68e0d93911'\nvar otherData = 'Some text data, perhaps'\n\nmerkleTools.addLeaf(hexData)\nmerkleTools.addLeaf(otherData, true)\n```\n\n### addLeaves(valueArray, doHash)\n\nAdds an array of values as leaves to the tree. The values must be either a Buffers or a hex strings, otherwise set the optional doHash to true to have your values hashed prior to being added to the tree. \n\n```js\nvar hexData = ['05ae04314577b2783b4be98211d1b72476c59e9c413cfb2afa2f0c68e0d93911', 'c5ed1192d909d1af814f64c7dc9e6a4983a63891a2c59ed14448d90271cb5519', \n'4bac27393bdd9777ce02453256c5577cd02275510b2227f473d03f533924f877']\nvar otherData = ['l', 'm', 'n', 'o', 'p']\n\nmerkleTools.addLeaves(hexData)\nmerkleTools.addLeaves(otherData, true)\n```\n\n### getLeafCount()\n\nReturns the number of leaves that are currently added to the tree. \n\n```js\nvar leafCount =  merkleTools.getLeafCount()\n```\n\n### getLeaf(index)\n\nReturns the value of the leaf at the given index as a Buffer. Returns null if no leaf exists at the given index. \n\n```js\nvar leafValue =  merkleTools.getLeaf(5)\n```\n\n### resetTree()\n\nRemoves all the leaves from the tree, prepararing to begin creating a new tree.\n\n```js\nmerkleTools.resetTree()\n```\n\n### makeTree(doubleHash)\n\nGenerates the merkle tree using the leaves that have been added.\n\n```js\nvar doubleHash = false // true to hash pairs twice as the tree is constructed \n\nmerkleTools.makeTree(doubleHash)\n```\n\n### makeBTCTree(doubleHash)\n\nGenerates the merkle tree with the flawed Bitcoin merkle tree implementation.\nThis should only be used when you need to replicate Bitcoin constructed merkle trees.\n\n```js\nvar doubleHash = true // true to hash pairs twice as the tree is constructed \n\nmerkleTools.makeBTCTree(doubleHash)\n```\n\n### getTreeReadyState()\n\nReturns boolean indicating if the tree is built and ready to supply its root and proofs. The Ready state is True only after the tree is built with 'makeTree'.  Adding leaves or resetting the tree will change the ready state to False.\n\n```js\nvar isReady =  merkleTools.getTreeReadyState()\n```\n\n### getMerkleRoot()\n\nReturns the merkle root of the tree as a Buffer. If the tree is not ready, null is returned.\n\n```js\nvar rootValue = merkleTools.getMerkleRoot()\n```\n\n### getProof(index, asBinary)\n\nReturns the proof as an array of hash objects or array of Buffers for the leaf at the given index. If the tree is not ready or no leaf exists at the given index, null is returned.  \n\n```js\nvar proof = merkleTools.getProof(2)\n\n// By default, an array of hash objects is returned\n// example: \n// proof == [\n//   { right: '09096dbc49b7909917e13b795ebf289ace50b870440f10424af8845fb7761ea5' },\n//   { right: 'ed2456914e48c1e17b7bd922177291ef8b7f553edf1b1f66b6fc1a076524b22f' },\n//   { left: 'eac53dde9661daf47a428efea28c81a021c06d64f98eeabbdcff442d992153a8' }\n// ]\n\nvar proof = merkleTools.getProof(2, true)\n\n// With asBinary set to true, an array of Buffers is returned \n// 0x00 indicated 'left', 0x01 indicates 'right'\n// example: \n// proof == [\n//   \u003cBuffer 01\u003e,\n//   \u003cBuffer 09096dbc49b7909917e13b795ebf289ace50b870440f10424af8845fb7761ea5\u003e,\n//   \u003cBuffer 01\u003e\n//   \u003cBuffer ed2456914e48c1e17b7bd922177291ef8b7f553edf1b1f66b6fc1a076524b22f\u003e,\n//   \u003cBuffer 00\u003e\n//   \u003cBuffer eac53dde9661daf47a428efea28c81a021c06d64f98eeabbdcff442d992153a8\u003e\n// ]\n```\n\nThe proof array contains a set of merkle sibling objects. Each object contains the sibling hash, with the key value of either right or left. The right or left value tells you where that sibling was in relation to the current hash being evaluated. This information is needed for proof validation, as explained in the following section.\n\n### validateProof(proof, targetHash, merkleRoot, doubleHash)\n\nReturns a boolean indicating whether or not the proof is valid and correctly connects the targetHash to the merkleRoot. Proof is a proof array as supplied by the 'getProof' method. The targetHash and merkleRoot parameters must be Buffers or hex strings. Setting doubleHash to true will double each hash operation to match the Bitcoin merkle tree style.\n\n```js\nvar proof = [\n   { right: '09096dbc49b7909917e13b795ebf289ace50b870440f10424af8845fb7761ea5' },\n   { right: 'ed2456914e48c1e17b7bd922177291ef8b7f553edf1b1f66b6fc1a076524b22f' },\n   { left: 'eac53dde9661daf47a428efea28c81a021c06d64f98eeabbdcff442d992153a8' },\n ]\nvar targetHash = '36e0fd847d927d68475f32a94efff30812ee3ce87c7752973f4dd7476aa2e97e'\nvar merkleRoot = 'b8b1f39aa2e3fc2dde37f3df04e829f514fb98369b522bfb35c663befa896766'\n\nvar isValid = merkleTools.validateProof(proof, targetHash, merkleRoot)\n```\n\nThe proof process uses all the proof objects in the array to attempt to prove a relationship between the targetHash and the merkleRoot values. The steps to validate a proof are:\n\n1. Concatenate targetHash and the first hash in the proof array. The right or left designation specifies which side of the concatenation that the proof hash value should be on.\n2. Hash the resulting value.\n3. Concatenate the resulting hash with the next hash in the proof array, using the same left and right rules.\n4. Hash that value and continue the process until you’ve gone through each item in the proof array.\n5. The final hash value should equal the merkleRoot value if the proof is valid, otherwise the proof is invalid.\n\n## Common Usage\n\n### Creating a tree and generating the proofs\n\n```js\nvar MerkleTools = require('merkle-tools')\n\nvar merkleTools = new MerkleTools() // no options, defaults to sha-256 hash type\n\n// add some leaves to the tree\nmerkleTools.addLeaf('7d49f074d2c3fa193e305bc109892f20760cbbecc218b43394a9356da35a72b3')\nmerkleTools.addLeaf('ba78a656108137a01f104b82a3554cedffce9f36e8a4149d68e0310b0943c09d')\nmerkleTools.addLeaves(['x', 'y', 'z'], true) // we must indicate these values need to be hashed\n\nmerkleTools.makeTree()\n\nvar proof0 = merkleTools.getProof(0)\nvar proof1 = merkleTools.getProof(1)\nvar proof2 = merkleTools.getProof(2)\n\nmerkleTools.resetTree() // use this when done with this tree and you intend on creating a new one\n\n```\n\n## Notes\n\n### About tree generation using makeTree()\n\n1. Internally, leaves are stored as Buffers. When the tree is built, it is generated by hashing together the Buffer values. \n2. Lonely leaf nodes are promoted to the next level up, as depicted below.\n\n                         ROOT=Hash(H+E)\n                         /        \\\n                        /          \\\n                 H=Hash(F+G)        E\n                 /       \\           \\\n                /         \\           \\\n         F=Hash(A+B)    G=Hash(C+D)    E\n          /     \\        /     \\        \\\n         /       \\      /       \\        \\\n        A         B    C         D        E\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTierion%2Fmerkle-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTierion%2Fmerkle-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTierion%2Fmerkle-tools/lists"}