Update docs

This commit is contained in:
Miguel Mota 2022-11-30 20:41:15 -08:00
parent 683d0dc1a9
commit 970fcf8246
No known key found for this signature in database
GPG Key ID: 67EC1161588A00F9
10 changed files with 904 additions and 1 deletions

View File

@ -133,6 +133,10 @@ npm test
- Q: Is there an NFT whitelist example in Solidity? - Q: Is there an NFT whitelist example in Solidity?
- A: Check out the example repo [merkletreejs-nft-whitelist](https://github.com/miguelmota/merkletreejs-nft-whitelist) on how to generate merkle root of whitelisted accounts and merkle proofs with this library and verify them in Solidity. - A: Check out the example repo [merkletreejs-nft-whitelist](https://github.com/miguelmota/merkletreejs-nft-whitelist) on how to generate merkle root of whitelisted accounts and merkle proofs with this library and verify them in Solidity.
- Q: What other types of merkle trees are supported?
- Besides standard `MerkleTree`, there's also `MerkleMountainRange`, `MerkleSumTree`, and `IncrementalMerkleTree` implemenation classes available.
- Q: Is there a CLI version of this library? - Q: Is there a CLI version of this library?
- Yes, see [merkletreejs-cli](https://github.com/miguelmota/merkletreejs-cli). - Yes, see [merkletreejs-cli](https://github.com/miguelmota/merkletreejs-cli).

View File

@ -10,6 +10,8 @@
↳ [MerkleMountainRange](_src_merklemountainrange_.merklemountainrange.md) ↳ [MerkleMountainRange](_src_merklemountainrange_.merklemountainrange.md)
↳ [MerkleSumTree](_src_merklesumtree_.merklesumtree.md)
↳ [MerkleTree](_src_merkletree_.merkletree.md) ↳ [MerkleTree](_src_merkletree_.merkletree.md)
## Index ## Index

View File

@ -0,0 +1,66 @@
[merkletreejs](../README.md) [Globals](../globals.md) ["src/MerkleSumTree"](../modules/_src_merklesumtree_.md) [Bucket](_src_merklesumtree_.bucket.md)
# Class: Bucket
## Hierarchy
* **Bucket**
## Index
### Constructors
* [constructor](_src_merklesumtree_.bucket.md#constructor)
### Properties
* [hashed](_src_merklesumtree_.bucket.md#hashed)
* [left](_src_merklesumtree_.bucket.md#left)
* [parent](_src_merklesumtree_.bucket.md#parent)
* [right](_src_merklesumtree_.bucket.md#right)
* [size](_src_merklesumtree_.bucket.md#size)
## Constructors
### constructor
\+ **new Bucket**(`size`: BigInt | number, `hashed`: Buffer): *[Bucket](_src_merklesumtree_.bucket.md)*
**Parameters:**
Name | Type |
------ | ------ |
`size` | BigInt | number |
`hashed` | Buffer |
**Returns:** *[Bucket](_src_merklesumtree_.bucket.md)*
## Properties
### hashed
**hashed**: *Buffer*
___
### left
**left**: *[Bucket](_src_merklesumtree_.bucket.md) | null*
___
### parent
**parent**: *[Bucket](_src_merklesumtree_.bucket.md) | null*
___
### right
**right**: *[Bucket](_src_merklesumtree_.bucket.md) | null*
___
### size
**size**: *BigInt*

View File

@ -0,0 +1,65 @@
[merkletreejs](../README.md) [Globals](../globals.md) ["src/MerkleSumTree"](../modules/_src_merklesumtree_.md) [Leaf](_src_merklesumtree_.leaf.md)
# Class: Leaf
## Hierarchy
* **Leaf**
## Index
### Constructors
* [constructor](_src_merklesumtree_.leaf.md#constructor)
### Properties
* [data](_src_merklesumtree_.leaf.md#data)
* [hashFn](_src_merklesumtree_.leaf.md#hashfn)
* [rng](_src_merklesumtree_.leaf.md#rng)
### Methods
* [getBucket](_src_merklesumtree_.leaf.md#getbucket)
## Constructors
### constructor
\+ **new Leaf**(`hashFn`: [THashFn](../modules/_src_merklesumtree_.md#thashfn), `rng`: (number | BigInt)[], `data`: Buffer | null): *[Leaf](_src_merklesumtree_.leaf.md)*
**Parameters:**
Name | Type |
------ | ------ |
`hashFn` | [THashFn](../modules/_src_merklesumtree_.md#thashfn) |
`rng` | (number | BigInt)[] |
`data` | Buffer | null |
**Returns:** *[Leaf](_src_merklesumtree_.leaf.md)*
## Properties
### data
**data**: *Buffer | null*
___
### hashFn
**hashFn**: *[THashFn](../modules/_src_merklesumtree_.md#thashfn)*
___
### rng
**rng**: *BigInt[]*
## Methods
### getBucket
**getBucket**(): *[Bucket](_src_merklesumtree_.bucket.md)*
**Returns:** *[Bucket](_src_merklesumtree_.bucket.md)*

View File

@ -0,0 +1,674 @@
[merkletreejs](../README.md) [Globals](../globals.md) ["src/MerkleSumTree"](../modules/_src_merklesumtree_.md) [MerkleSumTree](_src_merklesumtree_.merklesumtree.md)
# Class: MerkleSumTree
## Hierarchy
* [Base](_src_base_.base.md)
↳ **MerkleSumTree**
## Index
### Constructors
* [constructor](_src_merklesumtree_.merklesumtree.md#constructor)
### Properties
* [buckets](_src_merklesumtree_.merklesumtree.md#buckets)
* [hashFn](_src_merklesumtree_.merklesumtree.md#hashfn)
* [leaves](_src_merklesumtree_.merklesumtree.md#leaves)
* [root](_src_merklesumtree_.merklesumtree.md#root)
### Methods
* [bigNumberify](_src_merklesumtree_.merklesumtree.md#bignumberify)
* [binarySearch](_src_merklesumtree_.merklesumtree.md#binarysearch)
* [bufferIndexOf](_src_merklesumtree_.merklesumtree.md#protected-bufferindexof)
* [bufferToHex](_src_merklesumtree_.merklesumtree.md#buffertohex)
* [bufferify](_src_merklesumtree_.merklesumtree.md#bufferify)
* [bufferifyFn](_src_merklesumtree_.merklesumtree.md#bufferifyfn)
* [getProof](_src_merklesumtree_.merklesumtree.md#getproof)
* [isHexString](_src_merklesumtree_.merklesumtree.md#protected-ishexstring)
* [linearSearch](_src_merklesumtree_.merklesumtree.md#linearsearch)
* [log2](_src_merklesumtree_.merklesumtree.md#protected-log2)
* [print](_src_merklesumtree_.merklesumtree.md#print)
* [sizeToBuffer](_src_merklesumtree_.merklesumtree.md#sizetobuffer)
* [sum](_src_merklesumtree_.merklesumtree.md#sum)
* [verifyProof](_src_merklesumtree_.merklesumtree.md#verifyproof)
* [zip](_src_merklesumtree_.merklesumtree.md#protected-zip)
* [bigNumberify](_src_merklesumtree_.merklesumtree.md#static-bignumberify)
* [binarySearch](_src_merklesumtree_.merklesumtree.md#static-binarysearch)
* [bufferToHex](_src_merklesumtree_.merklesumtree.md#static-buffertohex)
* [bufferify](_src_merklesumtree_.merklesumtree.md#static-bufferify)
* [checkConsecutive](_src_merklesumtree_.merklesumtree.md#static-checkconsecutive)
* [hexZeroPad](_src_merklesumtree_.merklesumtree.md#static-hexzeropad)
* [isHexString](_src_merklesumtree_.merklesumtree.md#static-ishexstring)
* [linearSearch](_src_merklesumtree_.merklesumtree.md#static-linearsearch)
* [print](_src_merklesumtree_.merklesumtree.md#static-print)
## Constructors
### constructor
\+ **new MerkleSumTree**(`leaves`: [Leaf](_src_merklesumtree_.leaf.md)[], `hashFn`: [THashFn](../modules/_src_merklesumtree_.md#thashfn)): *[MerkleSumTree](_src_merklesumtree_.merklesumtree.md)*
**Parameters:**
Name | Type |
------ | ------ |
`leaves` | [Leaf](_src_merklesumtree_.leaf.md)[] |
`hashFn` | [THashFn](../modules/_src_merklesumtree_.md#thashfn) |
**Returns:** *[MerkleSumTree](_src_merklesumtree_.merklesumtree.md)*
## Properties
### buckets
**buckets**: *[Bucket](_src_merklesumtree_.bucket.md)[]*
___
### hashFn
**hashFn**: *[THashFn](../modules/_src_merklesumtree_.md#thashfn)*
___
### leaves
**leaves**: *[Leaf](_src_merklesumtree_.leaf.md)[]*
___
### root
**root**: *[Bucket](_src_merklesumtree_.bucket.md)*
## Methods
### bigNumberify
**bigNumberify**(`value`: any): *BigInt*
*Inherited from [Base](_src_base_.base.md).[bigNumberify](_src_base_.base.md#bignumberify)*
**Parameters:**
Name | Type |
------ | ------ |
`value` | any |
**Returns:** *BigInt*
___
### binarySearch
**binarySearch**(`array`: Buffer[], `element`: Buffer, `compareFunction`: function): *number*
*Inherited from [Base](_src_base_.base.md).[binarySearch](_src_base_.base.md#static-binarysearch)*
binarySearch
**`desc`** Returns the first index of which given item is found in array using binary search.
**`example`**
```js
const index = tree.binarySearch(array, element, Buffer.compare)
```
**Parameters:**
**array**: *Buffer[]*
Array of items.
**element**: *Buffer*
Item to find.
**compareFunction**: *function*
▸ (`a`: unknown, `b`: unknown): *number*
**Parameters:**
Name | Type |
------ | ------ |
`a` | unknown |
`b` | unknown |
**Returns:** *number*
- Index number
___
### `Protected` bufferIndexOf
**bufferIndexOf**(`array`: Buffer[], `element`: Buffer, `isSorted`: boolean): *number*
*Inherited from [Base](_src_base_.base.md).[bufferIndexOf](_src_base_.base.md#protected-bufferindexof)*
bufferIndexOf
**`desc`** Returns the first index of which given buffer is found in array.
**`example`**
```js
const index = tree.bufferIndexOf(haystack, needle)
```
**Parameters:**
Name | Type | Default |
------ | ------ | ------ |
`array` | Buffer[] | - |
`element` | Buffer | - |
`isSorted` | boolean | false |
**Returns:** *number*
- Index number
___
### bufferToHex
**bufferToHex**(`value`: Buffer, `withPrefix`: boolean): *string*
*Inherited from [Base](_src_base_.base.md).[bufferToHex](_src_base_.base.md#buffertohex)*
bufferToHex
**`desc`** Returns a hex string with 0x prefix for given buffer.
**`example`**
```js
const hexStr = tree.bufferToHex(Buffer.from('A'))
```
**Parameters:**
Name | Type | Default |
------ | ------ | ------ |
`value` | Buffer | - |
`withPrefix` | boolean | true |
**Returns:** *string*
___
### bufferify
**bufferify**(`value`: any): *Buffer*
*Inherited from [Base](_src_base_.base.md).[bufferify](_src_base_.base.md#static-bufferify)*
bufferify
**`desc`** Returns a buffer type for the given value.
**`example`**
```js
const buf = tree.bufferify('0x1234')
```
**Parameters:**
Name | Type |
------ | ------ |
`value` | any |
**Returns:** *Buffer*
___
### bufferifyFn
**bufferifyFn**(`f`: any): *any*
*Inherited from [Base](_src_base_.base.md).[bufferifyFn](_src_base_.base.md#bufferifyfn)*
bufferifyFn
**`desc`** Returns a function that will bufferify the return value.
**`example`**
```js
const fn = tree.bufferifyFn((value) => sha256(value))
```
**Parameters:**
Name | Type |
------ | ------ |
`f` | any |
**Returns:** *any*
___
### getProof
**getProof**(`index`: number | BigInt): *any[]*
**Parameters:**
Name | Type |
------ | ------ |
`index` | number | BigInt |
**Returns:** *any[]*
___
### `Protected` isHexString
**isHexString**(`value`: string): *boolean*
*Inherited from [Base](_src_base_.base.md).[isHexString](_src_base_.base.md#static-ishexstring)*
isHexString
**`desc`** Returns true if value is a hex string.
**`example`**
```js
console.log(MerkleTree.isHexString('0x1234'))
```
**Parameters:**
Name | Type |
------ | ------ |
`value` | string |
**Returns:** *boolean*
___
### linearSearch
**linearSearch**(`array`: Buffer[], `element`: Buffer, `eqChecker`: function): *number*
*Inherited from [Base](_src_base_.base.md).[linearSearch](_src_base_.base.md#static-linearsearch)*
linearSearch
**`desc`** Returns the first index of which given item is found in array using linear search.
**`example`**
```js
const index = tree.linearSearch(array, element, (a, b) => a === b)
```
**Parameters:**
**array**: *Buffer[]*
Array of items.
**element**: *Buffer*
Item to find.
**eqChecker**: *function*
▸ (`a`: unknown, `b`: unknown): *boolean*
**Parameters:**
Name | Type |
------ | ------ |
`a` | unknown |
`b` | unknown |
**Returns:** *number*
- Index number
___
### `Protected` log2
**log2**(`n`: number): *number*
*Inherited from [Base](_src_base_.base.md).[log2](_src_base_.base.md#protected-log2)*
log2
**`desc`** Returns the log2 of number.
**Parameters:**
Name | Type |
------ | ------ |
`n` | number |
**Returns:** *number*
___
### print
**print**(): *void*
*Inherited from [Base](_src_base_.base.md).[print](_src_base_.base.md#print)*
print
**`desc`** Prints out a visual representation of the merkle tree.
**`example`**
```js
tree.print()
```
**Returns:** *void*
___
### sizeToBuffer
**sizeToBuffer**(`size`: BigInt): *Buffer*
**Parameters:**
Name | Type |
------ | ------ |
`size` | BigInt |
**Returns:** *Buffer*
___
### sum
**sum**(`arr`: BigInt[]): *bigint*
**Parameters:**
Name | Type |
------ | ------ |
`arr` | BigInt[] |
**Returns:** *bigint*
___
### verifyProof
**verifyProof**(`root`: [Bucket](_src_merklesumtree_.bucket.md), `leaf`: [Leaf](_src_merklesumtree_.leaf.md), `proof`: [ProofStep](_src_merklesumtree_.proofstep.md)[]): *boolean*
**Parameters:**
Name | Type |
------ | ------ |
`root` | [Bucket](_src_merklesumtree_.bucket.md) |
`leaf` | [Leaf](_src_merklesumtree_.leaf.md) |
`proof` | [ProofStep](_src_merklesumtree_.proofstep.md)[] |
**Returns:** *boolean*
___
### `Protected` zip
**zip**(`a`: any[], `b`: any[]): *any[][]*
*Inherited from [Base](_src_base_.base.md).[zip](_src_base_.base.md#protected-zip)*
zip
**`desc`** Returns true if value is a hex string.
**`example`**
```js
const zipped = tree.zip(['a', 'b'],['A', 'B'])
console.log(zipped) // [ [ 'a', 'A' ], [ 'b', 'B' ] ]
```
**Parameters:**
Name | Type | Description |
------ | ------ | ------ |
`a` | any[] | first array |
`b` | any[] | second array |
**Returns:** *any[][]*
___
### `Static` bigNumberify
**bigNumberify**(`value`: any): *BigInt*
*Inherited from [Base](_src_base_.base.md).[bigNumberify](_src_base_.base.md#bignumberify)*
**Parameters:**
Name | Type |
------ | ------ |
`value` | any |
**Returns:** *BigInt*
___
### `Static` binarySearch
**binarySearch**(`array`: Buffer[], `element`: Buffer, `compareFunction`: function): *number*
*Inherited from [Base](_src_base_.base.md).[binarySearch](_src_base_.base.md#static-binarysearch)*
binarySearch
**`desc`** Returns the first index of which given item is found in array using binary search.
**`example`**
```js
const index = MerkleTree.binarySearch(array, element, Buffer.compare)
```
**Parameters:**
**array**: *Buffer[]*
Array of items.
**element**: *Buffer*
Item to find.
**compareFunction**: *function*
▸ (`a`: unknown, `b`: unknown): *number*
**Parameters:**
Name | Type |
------ | ------ |
`a` | unknown |
`b` | unknown |
**Returns:** *number*
- Index number
___
### `Static` bufferToHex
**bufferToHex**(`value`: Buffer, `withPrefix`: boolean): *string*
*Inherited from [Base](_src_base_.base.md).[bufferToHex](_src_base_.base.md#buffertohex)*
bufferToHex
**`desc`** Returns a hex string with 0x prefix for given buffer.
**`example`**
```js
const hexStr = MerkleTree.bufferToHex(Buffer.from('A'))
```
**Parameters:**
Name | Type | Default |
------ | ------ | ------ |
`value` | Buffer | - |
`withPrefix` | boolean | true |
**Returns:** *string*
___
### `Static` bufferify
**bufferify**(`value`: any): *Buffer*
*Inherited from [Base](_src_base_.base.md).[bufferify](_src_base_.base.md#static-bufferify)*
bufferify
**`desc`** Returns a buffer type for the given value.
**`example`**
```js
const buf = MerkleTree.bufferify('0x1234')
```
**Parameters:**
Name | Type |
------ | ------ |
`value` | any |
**Returns:** *Buffer*
___
### `Static` checkConsecutive
**checkConsecutive**(`leaves`: [Leaf](_src_merklesumtree_.leaf.md)[]): *void*
**Parameters:**
Name | Type |
------ | ------ |
`leaves` | [Leaf](_src_merklesumtree_.leaf.md)[] |
**Returns:** *void*
___
### `Static` hexZeroPad
**hexZeroPad**(`hexStr`: string, `length`: number): *string*
*Inherited from [Base](_src_base_.base.md).[hexZeroPad](_src_base_.base.md#static-hexzeropad)*
**Parameters:**
Name | Type |
------ | ------ |
`hexStr` | string |
`length` | number |
**Returns:** *string*
___
### `Static` isHexString
**isHexString**(`v`: string): *boolean*
*Inherited from [Base](_src_base_.base.md).[isHexString](_src_base_.base.md#static-ishexstring)*
isHexString
**`desc`** Returns true if value is a hex string.
**`example`**
```js
console.log(MerkleTree.isHexString('0x1234'))
```
**Parameters:**
Name | Type |
------ | ------ |
`v` | string |
**Returns:** *boolean*
___
### `Static` linearSearch
**linearSearch**(`array`: Buffer[], `element`: Buffer, `eqChecker`: function): *number*
*Inherited from [Base](_src_base_.base.md).[linearSearch](_src_base_.base.md#static-linearsearch)*
linearSearch
**`desc`** Returns the first index of which given item is found in array using linear search.
**`example`**
```js
const index = MerkleTree.linearSearch(array, element, (a, b) => a === b)
```
**Parameters:**
**array**: *Buffer[]*
Array of items.
**element**: *Buffer*
Item to find.
**eqChecker**: *function*
▸ (`a`: unknown, `b`: unknown): *boolean*
**Parameters:**
Name | Type |
------ | ------ |
`a` | unknown |
`b` | unknown |
**Returns:** *number*
- Index number
___
### `Static` print
**print**(`tree`: any): *void*
*Inherited from [Base](_src_base_.base.md).[print](_src_base_.base.md#print)*
print
**`desc`** Prints out a visual representation of the given merkle tree.
**`example`**
```js
MerkleTree.print(tree)
```
**Parameters:**
Name | Type | Description |
------ | ------ | ------ |
`tree` | any | Merkle tree instance. |
**Returns:** *void*

View File

@ -0,0 +1,45 @@
[merkletreejs](../README.md) [Globals](../globals.md) ["src/MerkleSumTree"](../modules/_src_merklesumtree_.md) [ProofStep](_src_merklesumtree_.proofstep.md)
# Class: ProofStep
## Hierarchy
* **ProofStep**
## Index
### Constructors
* [constructor](_src_merklesumtree_.proofstep.md#constructor)
### Properties
* [bucket](_src_merklesumtree_.proofstep.md#bucket)
* [right](_src_merklesumtree_.proofstep.md#right)
## Constructors
### constructor
\+ **new ProofStep**(`bucket`: [Bucket](_src_merklesumtree_.bucket.md), `right`: boolean): *[ProofStep](_src_merklesumtree_.proofstep.md)*
**Parameters:**
Name | Type |
------ | ------ |
`bucket` | [Bucket](_src_merklesumtree_.bucket.md) |
`right` | boolean |
**Returns:** *[ProofStep](_src_merklesumtree_.proofstep.md)*
## Properties
### bucket
**bucket**: *[Bucket](_src_merklesumtree_.bucket.md)*
___
### right
**right**: *boolean*

View File

@ -9,5 +9,6 @@
* ["src/Base"](modules/_src_base_.md) * ["src/Base"](modules/_src_base_.md)
* ["src/IncrementalMerkleTree"](modules/_src_incrementalmerkletree_.md) * ["src/IncrementalMerkleTree"](modules/_src_incrementalmerkletree_.md)
* ["src/MerkleMountainRange"](modules/_src_merklemountainrange_.md) * ["src/MerkleMountainRange"](modules/_src_merklemountainrange_.md)
* ["src/MerkleSumTree"](modules/_src_merklesumtree_.md)
* ["src/MerkleTree"](modules/_src_merkletree_.md) * ["src/MerkleTree"](modules/_src_merkletree_.md)
* ["src/index"](modules/_src_index_.md) * ["src/index"](modules/_src_index_.md)

View File

@ -8,6 +8,7 @@
* [IncrementalMerkleTree](_src_index_.md#incrementalmerkletree) * [IncrementalMerkleTree](_src_index_.md#incrementalmerkletree)
* [MerkleMountainRange](_src_index_.md#merklemountainrange) * [MerkleMountainRange](_src_index_.md#merklemountainrange)
* [MerkleSumTree](_src_index_.md#merklesumtree)
## References ## References
@ -20,3 +21,9 @@ ___
### MerkleMountainRange ### MerkleMountainRange
**MerkleMountainRange**: **MerkleMountainRange**:
___
### MerkleSumTree
**MerkleSumTree**:

View File

@ -0,0 +1,39 @@
[merkletreejs](../README.md) [Globals](../globals.md) ["src/MerkleSumTree"](_src_merklesumtree_.md)
# Module: "src/MerkleSumTree"
## Index
### Classes
* [Bucket](../classes/_src_merklesumtree_.bucket.md)
* [Leaf](../classes/_src_merklesumtree_.leaf.md)
* [MerkleSumTree](../classes/_src_merklesumtree_.merklesumtree.md)
* [ProofStep](../classes/_src_merklesumtree_.proofstep.md)
### Type aliases
* [THashFn](_src_merklesumtree_.md#thashfn)
* [TValue](_src_merklesumtree_.md#tvalue)
## Type aliases
### THashFn
Ƭ **THashFn**: *function*
#### Type declaration:
▸ (`value`: [TValue](_src_merklesumtree_.md#tvalue)): *Buffer*
**Parameters:**
Name | Type |
------ | ------ |
`value` | [TValue](_src_merklesumtree_.md#tvalue) |
___
### TValue
Ƭ **TValue**: *Buffer | BigInt | string | number | null | undefined*

View File

@ -4,7 +4,7 @@ const { MerkleSumTree, Leaf } = require('../dist/MerkleSumTree')
const sha256 = (data) => crypto.createHash('sha256').update(data).digest() const sha256 = (data) => crypto.createHash('sha256').update(data).digest()
test('MerkleSumTree', t => { test('MerkleSumTree - sha256', t => {
t.plan(4) t.plan(4)
const treeSize = 2n ** 64n const treeSize = 2n ** 64n