https://github.com/aiken-lang/merkle-patricia-forestry

🌳 Libraries (Aiken & Node.js) for working with Merkle Patricia Tries on Cardano.
https://github.com/aiken-lang/merkle-patricia-forestry

aiken cardano merkle-patricia-trie merkle-tree sparse-merkle-tree

Last synced: 2 days ago
JSON representation

🌳 Libraries (Aiken & Node.js) for working with Merkle Patricia Tries on Cardano.

• Host: GitHub
• URL: https://github.com/aiken-lang/merkle-patricia-forestry
• Owner: aiken-lang
• License: mpl-2.0
• Created: 2024-05-21T16:06:36.000Z (7 months ago)
• Default Branch: main
• Last Pushed: 2024-10-17T12:33:22.000Z (2 months ago)
• Last Synced: 2024-10-19T12:47:41.386Z (2 months ago)
• Topics: aiken, cardano, merkle-patricia-trie, merkle-tree, sparse-merkle-tree
• Language: JavaScript
• Homepage: https://aiken-lang.github.io/merkle-patricia-forestry/aiken/merkle_patricia_forestry.html
• Size: 1.13 MB
• Stars: 29
• Watchers: 1
• Forks: 5
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-aiken - aiken-lang/merkle-patricia-forestry - For working with modified Merkle Patricia Tries (on-chain & off-chain): a persistent & authenticated data structure to map between arbitrary keys and values. (Libraries)

README

        


  
Merkle Patricia Forestry

  

  
A set of (on-chain & off-chain) libraries for working with Merkle Patricia Tries on Cardano.


  


[![Licence](https://img.shields.io/github/license/aiken-lang/merkle-patricia-forestry?style=for-the-badge)](https://github.com/aiken-lang/merkle-patricia-forestry/blob/main/LICENSE)

[![Continuous Integration](https://img.shields.io/github/actions/workflow/status/aiken-lang/merkle-patricia-forestry/continuous-integration.yml?style=for-the-badge&label=continuous%20integration)](https://github.com/aiken-lang/merkle-patricia-forestry/actions/workflows/continuous-integration.yml)

[![NPM](https://img.shields.io/npm/v/%40aiken-lang%2Fmerkle-patricia-forestry?style=for-the-badge)](https://www.npmjs.com/package/@aiken-lang/merkle-patricia-forestry)

  




## Overview

A Merkle Patricia Trie is a persistent & authenticated data structure to map between arbitrary keys and values. It's like a hashmap on steroids, which isn't tamperable. The items are represented in a space-optimized trie (a.k.a prefix tree) of radix 16. The hash digest of their keys gives the path to values in the trie. For more details, read [the wiki](https://github.com/aiken-lang/merkle-patricia-forestry/wiki/Technical-analysis).

The use cases are numerous, such as maintaining large on-chain registries (e.g. domains) or providing unreasonably large oracled datasets of intrinsic data (e.g. a map of delegators/delegatees) or extrinsic data (e.g. GitHub data pertaining to an ecosystem of projects). It's also perfectly suited for long-running datasets that grow at a _slow_ rate (e.g. a PoW blockchain).

### Features

Using only a root hash digest (32 bytes) and a succinct proof (<1KB), Merkle Patricia Tries provides rapid:

- [x] membership

- [x] insertion

- [x] deletion

...of any key/value item in a large (billions) store.

## Getting Started

### Off-chain (JavaScript / Node.js)

```bash

yarn add @aiken-lang/merkle-patricia-forestry

```

See [off-chain](./off-chain#readme) for usage.

### On-chain (Aiken)

```bash

aiken add aiken-lang/merkle-patricia-forestry --version 2.0.0

```

See [on-chain](./on-chain#readme) for usage.

## Performances

This library implements a few optimizations. We borrow ideas from the [Ethereum's Modified Merkle Patricia Trie (MPT)](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie/) and also introduce a novel approach for organizing nodes as tiny [Sparse Merkle Trees](https://eprint.iacr.org/2016/683.pdf) that result in much smaller proof sizes, and gives the name to the structure: Merkle Patricia Forestry. This optimization and overall approach are covered in more detail [in the wiki](https://github.com/aiken-lang/merkle-patricia-forestry/wiki/Technical-analysis#forestry).

While this optimization sacrifices some memory and CPU execution units for smaller proof sizes, the library ultimately achieves a good trade-off. The table below summarizes the proof size, memory units, and CPU units for various sizes of tries. Note that the numbers in the table correspond to _one proof verification_ (e.g., membership). Insertion and deletion in the trie both require _two proof verifications_, so double the numbers!

trie size | avg proof size (bytes) | avg proof mem units     | avg proof cpu units    |

---:      | -------------:         | ------------:           | ------------:          |

10²       | 250                    | 70K  (0.70%) | 18M (0.12%) |

10³       | 350                    | 100K (1.00%) | 26M (0.19%) |

10⁴       | 460                    | 130K (1.30%) | 35M (0.25%) |

10⁵       | 560                    | 160K (1.60%) | 44M (0.31%) |

10⁶       | 670                    | 190K (1.90%) | 53M (0.38%) |

10⁷       | 780                    | 220K (2.20%) | 62M (0.44%) |

10⁸       | 880                    | 250K (2.50%) | 71M (0.51%) |

10⁹       | 990                    | 280K (2.80%) | 79M (0.56%) |

 > [!NOTE]

 >

 > On current mainnet, 140K mem units and 100M cpu units corresponds respectively to 1% of the maximum transaction mem and cpu budgets.