js-merkle

Library for building merkle trees and verifying merkle proofs, including multi proofs. Built to be easy to understand

Usage no npm install needed!

<script type="module">
  import jsMerkle from 'https://cdn.skypack.dev/js-merkle';
</script>

README

JS-MERKLE

NPM Version Coverage Status Build status

This is a library for working with merkle trees. It supports building Merkle trees, creating Merkle proofs including multi proofs, and verifying Merkle proofs.

The key advantages of this library:

  • Zero dependencies - safer to use in the project, as it doesn't bring anything with it
  • Tiny size
  • Multi proof support
  • Codebase is well-structured and easy to understand

Usage

Creating a Merkle proof:

import { MerkleTree } from 'js-merkle';

const leafValues = ['a', 'b', 'c', 'd', 'e', 'f'];
const leafs = leafValues.map((x) => sha256(Buffer.from(x)));

const merkleTree = new MerkleTree(leafHashes, sha256);
// Getting a proof for a single element ('b' in leafValues):
const proof = merkleTree.getProof([1]);
// Getting a multiproof ('b' and 'd' in leafValues):
const multiProof = merkleTree.getProof([1,3]);
// Getting proof hashes to serialize the proof:
const proofHashes = multiProof.getProofHashes();

Verifying the proof:

import { MerkleTree, MerkleProof } from 'js-merkle';

const leafValues = ['a', 'b', 'c', 'd', 'e', 'f'];
const leafs = leafValues.map((x) => sha256(Buffer.from(x)));
const merkleTree = new MerkleTree(leafHashes, sha256);
const root = merkleTree.getRoot();

const proof = new MerkleProof(proofHashes, sha256);
const leavesCount = 6;
const leafsIndiciesToVerify = [1, 3];
const isVerified = proof.verify(root, leafsIndiciesToVerify, [leafs[1], leafs[3]], leavesCount);

console.log('Verification successfull:', isVerified);

Alternatively to just verifying the proof, you can extract the root:

Change the .verify line in the verification example to:

const extractedRoot = proof.calculateRoot(leafsIndiciesToVerify, [leafs[1], leafs[3]], leavesCount);

Serializing the proof:

import { MerkleTree, MerkleProof } from 'js-merkle';

const leafValues = ['a', 'b', 'c', 'd', 'e', 'f'];
const leafs = leafValues.map((x) => sha256(Buffer.from(x)));
const merkleTree = new MerkleTree(leafHashes, sha256);
const root = merkleTree.getRoot();

const proof = new MerkleProof(proofHashes, sha256);
// To buffer, for node.js or if you have a buffer polyfill in your app:
const proofBuffer = proof.toBuffer();
// To Uint8Array, if you plan to use the lib in the browser:
const proofArray = proof.toBytes();

Parsing a serialized proof:

import { MerkleTree, MerkleProof } from 'js-merkle';

const leafValues = ['a', 'b', 'c', 'd', 'e', 'f'];
const leafs = leafValues.map((x) => sha256(Buffer.from(x)));
const merkleTree = new MerkleTree(leafHashes, sha256);
const root = merkleTree.getRoot();

const proof = new MerkleProof(proofHashes, sha256);
const proofBuffer = proof.toBuffer();
const proofArray = proof.toBytes();

// From a proof serialized to buffer:
const restoredProofFromBuffer = MerkleProof.fromBuffer(proofBuffer, sha256);
// From a proof serialized to a Uint8Array:
const restoredProofFromBuffer = MerkleProof.fromBytes(proofArray, sha256);

Contributing

Everyone is welcome to contribute in any way of form! For the further details, please read CONTRIBUTING.md

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details