MerkleTree.js

Construct Merkle Trees and verify proofs in JavaScript.

Contents

• Diagrams
• Install
• Getting started
• Documentation
• Test
• FAQ
• Notes
• Resources
• License

Diagrams

Diagram of Merkle Tree

Diagram of Merkle Tree Proof

Diagram of Invalid Merkle Tree Proofs

Diagram of Bitcoin Merkle Tree

Install

npm install merkletreejs

Getting started

Construct tree, generate proof, and verify proof:

const { MerkleTree } = require('merkletreejs')
const SHA256 = require('crypto-js/sha256')

const leaves = ['a', 'b', 'c'].map(x => SHA256(x))
const tree = new MerkleTree(leaves, SHA256)
const root = tree.getRoot().toString('hex')
const leaf = SHA256('a')
const proof = tree.getProof(leaf)
console.log(tree.verify(proof, leaf, root)) // true


const badLeaves = ['a', 'x', 'c'].map(x => SHA256(x))
const badTree = new MerkleTree(badLeaves, SHA256)
const badLeaf = SHA256('x')
const badProof = tree.getProof(badLeaf)
console.log(tree.verify(badProof, leaf, root)) // false

Print tree to console:

MerkleTree.print(tree)

Output

└─ 311d2e46f49b15fff8b746b74ad57f2cc9e0d9939fda94387141a2d3fdf187ae
   ├─ 176f0f307632fdd5831875eb709e2f68d770b102262998b214ddeb3f04164ae1
   │  ├─ 3ac225168df54212a25c1c01fd35bebfea408fdac2e31ddd6f80a4bbf9a5f1cb
   │  └─ b5553de315e0edf504d9150af82dafa5c4667fa618ed0a6f19c69b41166c5510
   └─ 0b42b6393c1f53060fe3ddbfcd7aadcca894465a5a438f69c87d790b2299b9b2
      └─ 0b42b6393c1f53060fe3ddbfcd7aadcca894465a5a438f69c87d790b2299b9b2

Documentation

merkletreejs > "index" > MerkleTree

Class: MerkleTree

Class reprensenting a Merkle Tree

namespace: MerkleTree

Hierarchy

MerkleTree

Index

Constructors

• constructor

Properties

• _sort
• duplicateOdd
• hashAlgo
• hashLeaves
• isBitcoinTree
• layers
• leaves

Methods

• createHashes
• getLayers
• getLayersAsObject
• getLeaves
• getProof
• getRoot
• print
• toString
• toTreeString
• verify
• bufferify
• print

---

Constructors

constructor

⊕ new MerkleTree(leaves: any, hashAlgorithm: any, options?: any): MerkleTree

Defined in index.ts:16

desc: Constructs a Merkle Tree. All nodes and leaves are stored as Buffers. Lonely leaf nodes are promoted to the next level up without being hashed again.

example: const MerkleTree = require('merkletreejs') const crypto = require('crypto')

function sha256(data) { // returns Buffer return crypto.createHash('sha256').update(data).digest() }

const leaves = ['a', 'b', 'c'].map(x => sha3(x))

const tree = new MerkleTree(leaves, sha256)

Parameters:

Name	Type	Default value	Description
leaves	any	-	Array of hashed leaves. Each leaf must be a Buffer.
hashAlgorithm	any	-	Algorithm used for hashing leaves and nodes
Default value options	any	{} as any	Additional options

Returns: MerkleTree

---

Properties

_sort

● _sort: boolean

Defined in index.ts:15

---

duplicateOdd

● duplicateOdd: boolean

Defined in index.ts:16

---

hashAlgo

● hashAlgo: any

Defined in index.ts:10

---

hashLeaves

● hashLeaves: boolean

Defined in index.ts:11

---

isBitcoinTree

● isBitcoinTree: boolean

Defined in index.ts:14

---

layers

● layers: any

Defined in index.ts:13

---

leaves

● leaves: any

Defined in index.ts:12

---

Methods

createHashes

▸ createHashes(nodes: any): void

Defined in index.ts:60

Parameters:

Name	Type
nodes	any

Returns: void

---

getLayers

▸ getLayers(): any

Defined in index.ts:145

getLayers

desc: Returns array of all layers of Merkle Tree, including leaves and root.

example: const layers = tree.getLayers()

Returns: any

---

getLayersAsObject

▸ getLayersAsObject(): any

Defined in index.ts:295

Returns: any

---

getLeaves

▸ getLeaves(): any

Defined in index.ts:134

getLeaves

desc: Returns array of leaves of Merkle Tree.

example: const leaves = tree.getLeaves()

Returns: any

---

getProof

▸ getProof(leaf: any, index?: any): any[]

Defined in index.ts:176

getProof

desc: Returns the proof for a target leaf.

example: const proof = tree.getProof(leaves[2])

example: const leaves = ['a', 'b', 'a'].map(x => sha3(x)) const tree = new MerkleTree(leaves, sha3) const proof = tree.getProof(leaves[2], 2)

Parameters:

Name	Type	Description
leaf	any	Target leaf
Optional index	any

Returns: any[]

• Array of objects containing a position property of type string with values of 'left' or 'right' and a data property of type Buffer.

---

getRoot

▸ getRoot(): any

Defined in index.ts:156

getRoot

desc: Returns the Merkle root hash as a Buffer.

example: const root = tree.getRoot()

Returns: any

---

print

▸ print(): void

Defined in index.ts:324

Returns: void

---

toString

▸ toString(): any

Defined in index.ts:335

Returns: any

---

toTreeString

▸ toTreeString(): any

Defined in index.ts:329

Returns: any

---

verify

▸ verify(proof: any, targetNode: any, root: any): boolean

Defined in index.ts:258

verify

desc: Returns true if the proof path (array of hashes) can connect the target node to the Merkle root.

example: const root = tree.getRoot() const proof = tree.getProof(leaves[2]) const verified = tree.verify(proof, leaves[2], root)

Parameters:

Name	Type	Description
proof	any	Array of proof objects that should connect target node to Merkle root.
targetNode	any	Target node Buffer
root	any	Merkle root Buffer

Returns: boolean

---

<Static> bufferify

▸ bufferify(x: any): any

Defined in index.ts:340

Parameters:

Name	Type
x	any

Returns: any

---

<Static> print

▸ print(tree: any): void

Defined in index.ts:345

Parameters:

Name	Type
tree	any

Returns: void

---

Test

npm test

FAQ

• Q: How do you verify merkle proofs in Solidity?
  • A: Check out the example repo merkletreejs-solidity on how to generate merkle proofs with this library and verify them in Solidity.

Notes

As is, this implemenation is vulnerable to a second pre-image attack. Use a difference hashing algorithm function for leaves and nodes, so that H(x) != H'(x).

Also, as is, this implementation is vulnerable to a forgery attack for an unbalanced tree, where the last leaf node can be duplicated to create an artificial balanced tree, resulting in the same Merkle root hash. Do not accept unbalanced tree to prevent this.

More info here.

Resources

• Bitcoin mining the hard way: the algorithms, protocols, and bytes

• Bitcoin Talk - Merkle Trees

• How Log Proofs Work

• Raiden Merkle Tree Implemenation

• Why aren't Solidity sha3 hashes not matching what other sha3 libraries produce?

• What is the purpose of using different hash functions for the leaves and internals of a hash tree?

• Why is the full Merkle path needed to verify a transaction?

• Where is Double hashing performed in Bitcoin?

License

MIT