@crpdo/merkle/docs/api.md

A dynamic, in-memory merkle tree implementation in js

<a name="module_Merkle"></a>

## Merkle
The Merkle module, `@crpdo/merkle`, is responsible for creating 
Merkle trees, which are fundamental data structures in various cryptographic 
applications.


* [Merkle](#module_Merkle)
    * [~Merkle](#module_Merkle..Merkle)
        * [new Merkle([leaves], [checkpoint])](#new_module_Merkle..Merkle_new)
        * _instance_
            * [.depth](#module_Merkle..Merkle+depth) ⇒ <code>number</code>
            * [.hash(input)](#module_Merkle..Merkle+hash) ⇒ <code>string</code>
            * [.peek(back)](#module_Merkle..Merkle+peek) ⇒ <code>string</code>
            * [.checkpoint()](#module_Merkle..Merkle+checkpoint) ⇒ <code>Object</code>
            * [.commit([restart])](#module_Merkle..Merkle+commit) ⇒ <code>Object</code>
            * [.revert()](#module_Merkle..Merkle+revert) ⇒ <code>boolean</code> \| <code>string</code>
            * [.derive(undos)](#module_Merkle..Merkle+derive)
            * [.append(value)](#module_Merkle..Merkle+append)
            * [.getRoot()](#module_Merkle..Merkle+getRoot) ⇒ <code>\*</code>
            * [.genRoot()](#module_Merkle..Merkle+genRoot) ⇒ <code>\*</code>
            * [.getLeaf(index)](#module_Merkle..Merkle+getLeaf) ⇒ <code>\*</code>
            * [.getLeafCount()](#module_Merkle..Merkle+getLeafCount) ⇒ <code>number</code>
            * [.getIndex(leaf)](#module_Merkle..Merkle+getIndex) ⇒ <code>number</code>
            * [.getProof(index)](#module_Merkle..Merkle+getProof) ⇒ <code>Object</code>
            * [.verifyProof(proofData)](#module_Merkle..Merkle+verifyProof) ⇒ <code>boolean</code>
        * _static_
            * [.hash(input, [hashLength])](#module_Merkle..Merkle.hash) ⇒ <code>string</code>
            * [.derive(levels, undos, hashLength)](#module_Merkle..Merkle.derive) ⇒ <code>Array</code>
            * [._derive(levels, undos, hashLength)](#module_Merkle..Merkle._derive) ⇒ <code>Array</code>
            * [.append(value, levels, [undos])](#module_Merkle..Merkle.append) ⇒ <code>Array</code>
            * [.getRoot(levels, mutate)](#module_Merkle..Merkle.getRoot) ⇒ <code>\*</code>
            * [.getProof(index, levels)](#module_Merkle..Merkle.getProof) ⇒ <code>Array</code>
            * [.verifyProof(proof, root, target)](#module_Merkle..Merkle.verifyProof) ⇒ <code>boolean</code>

<a name="module_Merkle..Merkle"></a>

### Merkle~Merkle
Class representing a Merkle tree.
A Merkle tree is a tree of hashes and is used for efficient data verification.
It's widely used in distributed systems and blockchains for verifying the 
integrity of transaction data.

**Kind**: inner class of [<code>Merkle</code>](#module_Merkle)  

* [~Merkle](#module_Merkle..Merkle)
    * [new Merkle([leaves], [checkpoint])](#new_module_Merkle..Merkle_new)
    * _instance_
        * [.depth](#module_Merkle..Merkle+depth) ⇒ <code>number</code>
        * [.hash(input)](#module_Merkle..Merkle+hash) ⇒ <code>string</code>
        * [.peek(back)](#module_Merkle..Merkle+peek) ⇒ <code>string</code>
        * [.checkpoint()](#module_Merkle..Merkle+checkpoint) ⇒ <code>Object</code>
        * [.commit([restart])](#module_Merkle..Merkle+commit) ⇒ <code>Object</code>
        * [.revert()](#module_Merkle..Merkle+revert) ⇒ <code>boolean</code> \| <code>string</code>
        * [.derive(undos)](#module_Merkle..Merkle+derive)
        * [.append(value)](#module_Merkle..Merkle+append)
        * [.getRoot()](#module_Merkle..Merkle+getRoot) ⇒ <code>\*</code>
        * [.genRoot()](#module_Merkle..Merkle+genRoot) ⇒ <code>\*</code>
        * [.getLeaf(index)](#module_Merkle..Merkle+getLeaf) ⇒ <code>\*</code>
        * [.getLeafCount()](#module_Merkle..Merkle+getLeafCount) ⇒ <code>number</code>
        * [.getIndex(leaf)](#module_Merkle..Merkle+getIndex) ⇒ <code>number</code>
        * [.getProof(index)](#module_Merkle..Merkle+getProof) ⇒ <code>Object</code>
        * [.verifyProof(proofData)](#module_Merkle..Merkle+verifyProof) ⇒ <code>boolean</code>
    * _static_
        * [.hash(input, [hashLength])](#module_Merkle..Merkle.hash) ⇒ <code>string</code>
        * [.derive(levels, undos, hashLength)](#module_Merkle..Merkle.derive) ⇒ <code>Array</code>
        * [._derive(levels, undos, hashLength)](#module_Merkle..Merkle._derive) ⇒ <code>Array</code>
        * [.append(value, levels, [undos])](#module_Merkle..Merkle.append) ⇒ <code>Array</code>
        * [.getRoot(levels, mutate)](#module_Merkle..Merkle.getRoot) ⇒ <code>\*</code>
        * [.getProof(index, levels)](#module_Merkle..Merkle.getProof) ⇒ <code>Array</code>
        * [.verifyProof(proof, root, target)](#module_Merkle..Merkle.verifyProof) ⇒ <code>boolean</code>

<a name="new_module_Merkle..Merkle_new"></a>

#### new Merkle([leaves], [checkpoint])
Create a Merkle tree.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [leaves] | <code>Array</code> | <code>[]</code> | The leaves of the tree. |
| [checkpoint] | <code>boolean</code> | <code>true</code> | Whether to create a checkpoint. |

<a name="module_Merkle..Merkle+depth"></a>

#### merkle.depth ⇒ <code>number</code>
The depth of the Merkle tree, calculated as the length of the levels.

**Kind**: instance property of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>number</code> - The depth of the Merkle tree.  
<a name="module_Merkle..Merkle+hash"></a>

#### merkle.hash(input) ⇒ <code>string</code>
Generates a hash for the provided input using the static hash function.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>string</code> - The generated hash.  

| Param | Type | Description |
| --- | --- | --- |
| input | <code>string</code> | The input to hash. |

<a name="module_Merkle..Merkle+peek"></a>

#### merkle.peek(back) ⇒ <code>string</code>
Returns the key from the `this.stacks` object. 
If no parameter is provided, it returns the last key.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>string</code> - The key at the provided index or the last key.  

| Param | Type | Description |
| --- | --- | --- |
| back | <code>number</code> | The index of the key to return. |

<a name="module_Merkle..Merkle+checkpoint"></a>

#### merkle.checkpoint() ⇒ <code>Object</code>
Creates a new checkpoint for the Merkle tree.
This involves creating a new stack and associating it with the root.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>Object</code> - An object containing the root and the newly created stack.  
<a name="module_Merkle..Merkle+commit"></a>

#### merkle.commit([restart]) ⇒ <code>Object</code>
Commits changes made since the last checkpoint.
The root and its associated stack are removed from the `this.stacks` object.
If `restart` is true, a new checkpoint is created.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>Object</code> - An object containing the root and the stack that was 
just committed.  
**Throws**:

- <code>Error</code> If there is no checkpoint to commit.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [restart] | <code>boolean</code> | <code>true</code> | Whether to create a new checkpoint  after committing. |

<a name="module_Merkle..Merkle+revert"></a>

#### merkle.revert() ⇒ <code>boolean</code> \| <code>string</code>
Reverts changes made since the last checkpoint.
The stack associated with the current root is popped until empty, 
undoing the operations stored in it.
If the root does not match the original root after reverting, false 
is returned.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>boolean</code> \| <code>string</code> - False if the root after reverting does not 
match the original root, the root otherwise.  
**Throws**:

- <code>Error</code> If there is no checkpoint to revert to.

<a name="module_Merkle..Merkle+derive"></a>

#### merkle.derive(undos)
Derive new levels for the Merkle tree based on the existing ones and generate
a new root.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  

| Param | Type | Description |
| --- | --- | --- |
| undos | <code>Array</code> | The undo operations. |

<a name="module_Merkle..Merkle+append"></a>

#### merkle.append(value)
Method to append a new value to the Merkle tree and generate a new root.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  

| Param | Type | Description |
| --- | --- | --- |
| value | <code>string</code> | The value to append. |

<a name="module_Merkle..Merkle+getRoot"></a>

#### merkle.getRoot() ⇒ <code>\*</code>
Gets the root of the Merkle tree instance.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>\*</code> - - The root of the tree.  
<a name="module_Merkle..Merkle+genRoot"></a>

#### merkle.genRoot() ⇒ <code>\*</code>
Generates and sets the root of the Merkle tree instance.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>\*</code> - - The newly set root of the tree.  
<a name="module_Merkle..Merkle+getLeaf"></a>

#### merkle.getLeaf(index) ⇒ <code>\*</code>
Gets the leaf at the specified index.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>\*</code> - - The leaf at the specified index.  

| Param | Type | Description |
| --- | --- | --- |
| index | <code>number</code> | The index of the leaf to retrieve. |

<a name="module_Merkle..Merkle+getLeafCount"></a>

#### merkle.getLeafCount() ⇒ <code>number</code>
Gets the count of leaves in the Merkle tree instance.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>number</code> - - The count of leaves.  
<a name="module_Merkle..Merkle+getIndex"></a>

#### merkle.getIndex(leaf) ⇒ <code>number</code>
Gets the index of the specified leaf in the Merkle tree instance.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>number</code> - - The index of the leaf if found, -1 otherwise.  

| Param | Type | Description |
| --- | --- | --- |
| leaf | <code>\*</code> | The leaf to find. |

<a name="module_Merkle..Merkle+getProof"></a>

#### merkle.getProof(index) ⇒ <code>Object</code>
Generates a Merkle proof for a given leaf.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>Object</code> - - An object containing the Merkle proof, the target leaf,
its index, and the root of the tree.  

| Param | Type | Description |
| --- | --- | --- |
| index | <code>number</code> | Index of the leaf for which to generate the proof. |

<a name="module_Merkle..Merkle+verifyProof"></a>

#### merkle.verifyProof(proofData) ⇒ <code>boolean</code>
Verifies a Merkle proof.

**Kind**: instance method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>boolean</code> - - Returns true if the proof is valid, false otherwise.  

| Param | Type | Description |
| --- | --- | --- |
| proofData | <code>Object</code> | An object containing the Merkle proof, the root of the tree, and the target leaf. |

<a name="module_Merkle..Merkle.hash"></a>

#### Merkle.hash(input, [hashLength]) ⇒ <code>string</code>
Static method to create a hash from a given input.

**Kind**: static method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>string</code> - - The resulting hash.  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| input | <code>string</code> |  | The input to be hashed. |
| [hashLength] | <code>number</code> | <code>HASH_LENGTH</code> | The length of the hash. |

<a name="module_Merkle..Merkle.derive"></a>

#### Merkle.derive(levels, undos, hashLength) ⇒ <code>Array</code>
Static method to derive new levels for the Merkle tree based on the existing
ones.

**Kind**: static method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>Array</code> - The derived levels.  

| Param | Type | Description |
| --- | --- | --- |
| levels | <code>Array</code> | The existing levels of the Merkle tree. |
| undos | <code>Array</code> | The undo operations. |
| hashLength | <code>number</code> | The length of the hash. |

<a name="module_Merkle..Merkle._derive"></a>

#### Merkle.\_derive(levels, undos, hashLength) ⇒ <code>Array</code>
Internal static method to derive new levels for the Merkle tree based on
the existing ones.

**Kind**: static method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>Array</code> - The derived levels.  

| Param | Type | Description |
| --- | --- | --- |
| levels | <code>Array</code> | The existing levels of the Merkle tree. |
| undos | <code>Array</code> | The undo operations. |
| hashLength | <code>number</code> | The length of the hash. |

<a name="module_Merkle..Merkle.append"></a>

#### Merkle.append(value, levels, [undos]) ⇒ <code>Array</code>
Static method to append a new value to the Merkle tree and derive the new
levels.

**Kind**: static method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>Array</code> - The derived levels after appending the new value.  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| value | <code>string</code> |  | The value to append. |
| levels | <code>Array</code> |  | The existing levels of the Merkle tree. |
| [undos] | <code>Array</code> | <code>[]</code> | The undo operations. |

<a name="module_Merkle..Merkle.getRoot"></a>

#### Merkle.getRoot(levels, mutate) ⇒ <code>\*</code>
Retrieves the root of the Merkle tree.

**Kind**: static method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>\*</code> - - The root of the tree.  

| Param | Type | Description |
| --- | --- | --- |
| levels | <code>Array</code> | The levels of the tree. |
| mutate | <code>boolean</code> | Whether or not to mutate the levels. |

<a name="module_Merkle..Merkle.getProof"></a>

#### Merkle.getProof(index, levels) ⇒ <code>Array</code>
Generates a proof for a given leaf in a Merkle tree.
The proof consists of sibling hashes from leaf to root.

**Kind**: static method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>Array</code> - - An array containing pairs of left and right node hashes
for each level of the tree, starting from the given leaf level.  

| Param | Type | Description |
| --- | --- | --- |
| index | <code>number</code> | Index of the leaf for which the proof is generated. |
| levels | <code>Array</code> | Array containing all levels of the Merkle tree. |

<a name="module_Merkle..Merkle.verifyProof"></a>

#### Merkle.verifyProof(proof, root, target) ⇒ <code>boolean</code>
Verifies a Merkle proof.

**Kind**: static method of [<code>Merkle</code>](#module_Merkle..Merkle)  
**Returns**: <code>boolean</code> - - Returns true if the proof hash equals the root,
indicating the proof is valid, false otherwise.  

| Param | Type | Description |
| --- | --- | --- |
| proof | <code>Array</code> | Array containing pairs of left and right node hashes for each level of the tree. |
| root | <code>string</code> | The root hash of the tree. |
| target | <code>string</code> | The target leaf value. |