js-merkle-tree

Generic Merkle trees in JavaScript.

Why?

Merkle trees organize an array of values into a tree whose elements can be rapidly verified as correct. Merkle trees are often used in peer-to-peer technologies so that peers can quickly verify that the data they have received is correct, guarding against data loss or manipulation. Dat, IPFS, and BitCoin all use Merkle trees for this reason.

This library is an effort to create a generic implementation of the datastructure accompanied by thorough testing and documentation.

Install

Use npm:

$ npm i @garbados/merkle-tree

Usage

Table of Contents

• MerkleTree
• proof
• root
• depth
• levels
• leaves
• digestFn

MerkleTree

Merkle trees, in JavaScript!

Parameters

• digestFn Function Digest function (or the name of one) used to hash values.
• data Array Values to be processed into a Merkle tree.

Examples

const MerkleTree = require('@garbados/merkle-tree')
const tree = new MerkleTree('sha256', [1, 2, 3, 4, 5, 6])
console.log(tree.root)
> b0f83986db9ecaa36bd08d732a99fc461f113b78e75612bade03892cd7bb8d25

proof

Retrieve the proof path for a given leaf node index.

Parameters

• index Number Index of a leaf node to verify.

Examples

const tree = new MerkleTree('sha256', [1, 2, 3, 4, 5, 6])
const proof = tree.proof(3)
console.log(tree.leaves[3] === proof[0][0])
> true

Returns Array Array of arrays of nodes associated with the given leaf node.

root

Getter for the root node.

Examples

console.log(tree.root)
> b0f83986db9ecaa36bd08d732a99fc461f113b78e75612bade03892cd7bb8d25

Returns String Value of the root node.

depth

Getter for the tree's depth.

Examples

console.log(tree.depth)
> 4

Returns Number Depth of the tree.

levels

Getter for the levels in the tree

Examples

console.log(tree.levels)
> [ [ 1, 2, 3, 4, 5, 6 ],
>   [ '49a64717d5d4cb19952e6eac2946415cf6879adacf9908e7d872332d32c6e684',
>     '8be6d66e9099c68d8feb52ce42478d2153cac2763b784174ae6ae96cd636b596',
>     '2f9cf80b937f44b41379ae3765c65668e5e96241d19d2088e76d72d18ea324b2' ],
>   [ '2450f5c346c26103f2bf4ba7052954556e58a1d577b78e17faa7d54c29cf6741',
>     '340c611ef9c540adf73ee22e41b148f9549c5bd88dfdf1a0792a23d564380dde' ],
>   [ 'b0f83986db9ecaa36bd08d732a99fc461f113b78e75612bade03892cd7bb8d25' ] ]

Returns Array<Array> Array of arrays of each node by level

leaves

Getter for the tree's leaf nodes AKA its initial values.

Examples

console.log(tree.leaves)
> [1, 2, 3, 4, 5, 6]

Returns Array Array of leaf nodes.

digestFn

Convenience wrapper around NodeJS' built-in crypto.

Parameters

• hashType String String value for a hash algorithm known to the platform's version of OpenSSL.
• data String The data to hash. Can be any value; it will be converted to a string.

Examples

const digestFn = MerkleTree.digestFn('sha256', 'hello world')
> b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

Returns String The hash of the given data using the given function.

Tests

To run the project's test suite, use npm

npm test

Contributions

All contributions are welcome: bug reports, feature requests, "why doesn't this work" questions, patches for fixes and features, etc. For all of the above, file an issue or submit a pull request.

License

Apache-2.0