@sec-block/secjs-merkle-tree

sec blockchain merkle tree lib

Usage no npm install needed!

<script type="module">
  import secBlockSecjsMerkleTree from 'https://cdn.skypack.dev/@sec-block/secjs-merkle-tree';
</script>

README

JavaScript Style Guide

[JavaScript Style Guide]

MerkleTree

This package is used for SEC blockchain merkle tree.

new MerkleTree(rawData, hashAlgo)

new MerkleTree(rawData, hashAlgo) Constructs a Merkle Tree. All rawData(will be converted to leaves and nodes after hash calculation) are stored as Buffers.

Param Type Description
rawData Buffer[], Array[] Array of raw data, will be convert to leaves after hash calculation
hashAlgo String Algorithm used to hash rawData, leaves and nodes, now the code only supports "md5", "sha1", "sha256", "sha512", "ripemd160"

Example

const crypto = require('crypto')
const MerkleTree = require('../src/index')

const rawData = ['a', 'b', 'c']
const tree = new MerkleTree(rawData, 'sha256')

merkleTree.getLeaves() ⇒ Array.<Buffer>

Returns array of leaves of Merkle Tree.

Kind: instance method of MerkleTree Example

const leaves = tree.getLeaves()

merkleTree.getLayers() ⇒ Array.<Buffer>

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

Kind: instance method of MerkleTree Example

const layers = tree.getLayers()

merkleTree.getRoot() ⇒ Buffer

Returns the Merkle root hash as a Buffer.

Kind: instance method of MerkleTree Example

const root = tree.getRoot()

merkleTree.getProof(rawData, [index]) ⇒ Array.<Buffer>

Returns the proof for a target leaf.

Kind: instance method of MerkleTree Returns: Array.<Object> - - Array of json object

Param Type Description
rawData Buffer, String Target leaf's raw data
[index] Number Target leaf index in leaves array. Use if there are leaves containing duplicate data in order to distinguish it.

If index is not defined, code will traverse the tree to find rawData's corresponding index. If index is defined, rawData is invalid and code will proceed with index only.

Example

const proof = tree.getProof(rawData[2])

Example

const rawData = ['a', 'b', 'c']
const tree = new MerkleTree(rawData, "sha256")
const proof = tree.getProof(rawData[2], 2)

merkleTree.verify(proof, targetNode, root) ⇒ Boolean

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

Kind: instance method of MerkleTree

Param Type Description
proof Array.<Object> Array of json object
targetNode Buffer, String Target node Buffer
root Buffer Merkle root Buffer

Example

const root = tree.getRoot()
const proof = tree.getProof(rawData[2])
const verified = tree.verify(proof, rawData[2], root)
```	

* * *
# 中文简介

代码用于SEC Merkle Tree Hash计算
主要的函数：
1.  定义MerkleTree:	MerkleTree(rawData, hashAlgo)
    其中rawData是原始的数据，例如区块链上每个区块utf-8编码形式的数据
    hashAlgo是Merkle树的hash运算算法，现在仅支持"md5", "sha1", "sha256", "sha512", "ripemd160"

2.  getProof(rawData, [index]) => Array.<Buffer>
    该函数会返回目标节点在hash树每一层的配偶节点的位置（左/右）及其hash值，返回类型为带key键的Array
    该函数配套verify函数，用于确认目标节点的数据是否遭到篡改
    
3.  verify(proof, targetNode, root) => Boolean
    该函数需要的输入为：getProof函数返回的目标节点每一层的配偶节点位置及hash值， 想测试的目标节点 raw data 以及 Merkle树根的值
    因此可以很容易的计算并确认数据没有遭到篡改
    
第二次原像攻击：
由于Merkle根值只是一个值，只能代表最后的值是否正确，而无法展示其他信息，如树的节点个数，树的层数等等，因此容易受到伪造者攻创建一个具有相同Merkle树根的虚假文档进行攻击
解决方法：
每一层的树在计算hash值之前加上所在层数对应的一个前缀值，例如第一层在data前面加0x00，以此类推