npm package: @garbados/merkle-tree
Description: An example Merkle tree implementation.
Author: Diana Thayer
Latest version: 1.0.3-alpha

# js-merkle-tree

[![Stability](https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square)](https://nodejs.org/api/documentation.html#documentation_stability_index)
[![NPM Version](https://img.shields.io/npm/v/@garbados/merkle-tree.svg?style=flat-square)](https://www.npmjs.com/package/@garbados/merkle-tree)
[![JS Standard Style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
[![Build Status](https://img.shields.io/travis/garbados/js-merkle-tree/master.svg?style=flat-square)](https://travis-ci.org/garbados/js-merkle-tree)
[![Coverage Status](https://img.shields.io/coveralls/github/garbados/js-merkle-tree/master.svg?style=flat-square)](https://coveralls.io/github/garbados/js-merkle-tree?branch=master)

Generic [Merkle trees](https://en.wikipedia.org/wiki/Merkle_tree) 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](http://datproject.org/), [IPFS](http://ipfs.io/), and [BitCoin](https://bitcoin.org/) 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](https://www.npmjs.com/):

```bash
$ npm i @garbados/merkle-tree
```

## Usage

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### Table of Contents

-   [MerkleTree](#merkletree)
-   [proof](#proof)
-   [root](#root)
-   [depth](#depth)
-   [levels](#levels)
-   [leaves](#leaves)
-   [digestFn](#digestfn)

### MerkleTree

Merkle trees, in JavaScript!

**Parameters**

-   `digestFn` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Digest function (or the name of one) used to hash values.
-   `data` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** Values to be processed into a Merkle tree.

**Examples**

```javascript
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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Index of a leaf node to verify.

**Examples**

```javascript
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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** Array of arrays of nodes associated with the given leaf node.

### root

Getter for the root node.

**Examples**

```javascript
console.log(tree.root)
> b0f83986db9ecaa36bd08d732a99fc461f113b78e75612bade03892cd7bb8d25
```

Returns **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Value of the root node.

### depth

Getter for the tree's depth.

**Examples**

```javascript
console.log(tree.depth)
> 4
```

Returns **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Depth of the tree.

### levels

Getter for the levels in the tree

**Examples**

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

Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)>** Array of arrays of each node by level

### leaves

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

**Examples**

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

Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** Array of leaf nodes.

### digestFn

Convenience wrapper around NodeJS' built-in crypto.

**Parameters**

-   `hashType` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** String value for a hash algorithm known to the platform's version of OpenSSL.
-   `data` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The data to hash. Can be any value; it will be converted to a string.

**Examples**

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

Returns **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The hash of the given data using the given function.

## Tests

To run the project's test suite, use [npm](https://npmjs.com/)

```bash
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](https://github.com/garbados/js-merkle-tree/issues) or [submit a pull request](https://github.com/garbados/js-merkle-tree/pulls).

## License

[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0)