From d1764fa1cca341daf1876f25a0999943f9f478c0 Mon Sep 17 00:00:00 2001 From: Lucas Oliveira Date: Sat, 30 Dec 2023 23:23:10 -0300 Subject: [PATCH 1/4] update: docs WIP --- README.md | 51 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index a15ed4f..e1ebf72 100644 --- a/README.md +++ b/README.md @@ -34,9 +34,7 @@ ## Table of Contents - [Credits](#credits) -- [How to install](#how-to-install) -- [How it works](#how-it-works) -- [How to use](#how-to-use) +- [Documentation](#Documentation) - [Roadmap](#roadmap) - [Contributing](#contributing) - [License](#license) @@ -45,7 +43,9 @@ [![GitHub Contributors Image](https://contrib.rocks/image?repo=olivmath/merkly)](https://github.com/olivmath/merkly/graphs/contributors) -## How to install +## Documentation + +**HOW TO INSTALL** ``` poetry add merkly @@ -55,9 +55,18 @@ poetry add merkly pip install merkly ``` -## How to works +**HOW TO WORKS** + +
+ Atenção! Este é um alerta importante. +
+ +> **Nota:** Este é um alerta ou nota importante. + +!!! warning "Atenção" +Este é um alerta importante. -- _We use keccak-256 under-the-hood if you dont pass your hash function_ +- `We use keccak-256 under-the-hood if you dont pass your hash function` This library provides a clean and easy to use implementation of the Merkle Tree with the following features: @@ -66,7 +75,7 @@ This library provides a clean and easy to use implementation of the Merkle Tree - Create Proof - Verify Proof -## How to Use +**HOW TO USE** **Create a Merkle Tree** @@ -163,20 +172,20 @@ assert mtree.verify(p, 'b') == True ## Roadmap -| Feature | Status | Version | -| ------------------------------------- | -------------- | ------- | -| Auto deploy PyPi | ✅ Deployed | 0.2.0 | -| Create Root | ✅ Deployed | 0.4.0 | -| Create Proof | ✅ Deployed | 0.5.0 | -| Verify Proof | ✅ Deployed | 0.6.0 | -| Use any Hash function | ✅ Deployed | 0.7.0 | -| Leafs of any size | ✅ Deployed | 0.8.0 | -| Security deprecation pysha3 | ✅ Deployed | 0.8.1 | -| Compatible with MerkleTreeJs | ✅ Deployed | 1.0.0 | -| First Issue solved by community | ✅ Deployed | 1.0.0 | -| Accelerator code with Rust | 🏗️ Alpha | 1.1.0 | -| Tutorial how to use with solidity | 🖊️ Design | x.x.x | -| Tutorial how to use with MerkleTreeJS | 🖊️ Design | x.x.x | +| Feature | Status | Version | +| ------------------------------------- | ----------- | ------- | +| Auto deploy PyPi | ✅ Deployed | 0.2.0 | +| Create Root | ✅ Deployed | 0.4.0 | +| Create Proof | ✅ Deployed | 0.5.0 | +| Verify Proof | ✅ Deployed | 0.6.0 | +| Use any Hash function | ✅ Deployed | 0.7.0 | +| Leafs of any size | ✅ Deployed | 0.8.0 | +| Security deprecation pysha3 | ✅ Deployed | 0.8.1 | +| Compatible with MerkleTreeJs | ✅ Deployed | 1.0.0 | +| First Issue solved by community | ✅ Deployed | 1.0.0 | +| Accelerator code with Rust | 🏗️ Alpha | 1.1.0 | +| Tutorial how to use with solidity | 🖊️ Design | x.x.x | +| Tutorial how to use with MerkleTreeJS | 🖊️ Design | x.x.x | ## Contributing From 4dd9dc25f0703d94143e5706c2263aceb13efcad Mon Sep 17 00:00:00 2001 From: Lucas Oliveira Date: Sun, 31 Dec 2023 00:23:31 -0300 Subject: [PATCH 2/4] update: contributing --- CONTRIBUTING.md | 35 +++++++++++++---------------------- 1 file changed, 13 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3dc35e..e9cd798 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,45 +2,36 @@ ## WORKFLOW -1. Create and describe your **proposal/bug** in an _issue_. -2. Create a new **branch** and **pull request** with the pattern `1-my-feature`. +1. Create your **proposal/bug** in an _issue_. +2. Create a new **branch** and **pull request** with the pattern: + - `feat/my-new-feature`. + - `docs/add-new-docs`. + - `test/add-a-test`. + - `fix/big-bug`. +3. Open a PR for you _issue_ (or link with a existent) +4. Await to `merge` +5. Publish new change by `tag` Gitlab Flow --- -## DEVELOPMENT ENVIRONMENT - -**pre-req** - -- [docker](https://docs.docker.com/engine/install/) -- [vscode](https://code.visualstudio.com/download) -- [remote container](https://code.visualstudio.com/docs/remote/containers) - -1. Update the image with `Dockerfile` -2. Development and test inside a container before do `git push` - -envdev - ---- - ## CONVENTIONAL COMMIT ``` type(escope): short description -What does the modification do? -why was it modified? - +You need describe better? +Write more here ``` type -- **deprecated!** compatibility break - **add** adds a new feature - **fix** fixes a bug -- **remove** remove a peace of code - **update** does not add a feature or fix a bug +- **remove** remove a peace of code +- **security** update/fix some security matter code --- From bc14d956e4b164a9966414bc6eb77cd4d5d2d1b7 Mon Sep 17 00:00:00 2001 From: Lucas Oliveira Date: Sun, 31 Dec 2023 00:24:06 -0300 Subject: [PATCH 3/4] update: readme --- README.md | 93 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 49 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index e1ebf72..6649a1a 100644 --- a/README.md +++ b/README.md @@ -57,16 +57,7 @@ pip install merkly **HOW TO WORKS** -
- Atenção! Este é um alerta importante. -
- -> **Nota:** Este é um alerta ou nota importante. - -!!! warning "Atenção" -Este é um alerta importante. - -- `We use keccak-256 under-the-hood if you dont pass your hash function` +> **WARNING:** We use keccak-256 under-the-hood if you dont pass your hash function This library provides a clean and easy to use implementation of the Merkle Tree with the following features: @@ -77,29 +68,29 @@ This library provides a clean and easy to use implementation of the Merkle Tree **HOW TO USE** -**Create a Merkle Tree** +**Creating a Merkle Tree** ```python from merkly.mtree import MerkleTree from typing import Callable -# choose any hash function that is of type (str) -> str -my_hash_function: Callable[[str], str] = lambda data: str(ord(data) * 1000) +# choose any hash function that is of type (bytes, bytes) -> bytes +my_hash_function: Callable[[bytes, bytes], bytes] = lambda x, y: x + y # create a Merkle Tree mtree = MerkleTree(['a', 'b', 'c', 'd'], my_hash_function) # show original input -assert mtree.raw_leafs == ['a', 'b', 'c', 'd'] +assert mtree.raw_leaves == ['a', 'b', 'c', 'd'] -# hashed leafs -assert mtree.leafs == ['97000', '98000', '99000', '100000'] +# hashed leaves +assert mtree.leaves == [b'a', b'b', b'c', b'd'] -# shorted hashed leafs -assert mtree.short_leafs == ['9700...', '9800...', '9900...', '1000...'] +# shorted hashed leaves +assert mtree.short_leaves == [b'a', b'b', b'c', b'd'] ``` -**Create a Merkle Tree (Default: Keccak256)** +**Creating a Default Merkle Tree (with Keccak256)** ```python from merkly.mtree import MerkleTree @@ -108,26 +99,31 @@ from merkly.mtree import MerkleTree mtree = MerkleTree(['a', 'b', 'c', 'd']) # show original input -assert mtree.raw_leafs == ['a', 'b', 'c', 'd'] - -# hashed leafs -assert mtree.leafs == [ - '3ac225168df54212a25c1c01fd35bebfea408fdac2e31ddd6f80a4bbf9a5f1cb', - 'b5553de315e0edf504d9150af82dafa5c4667fa618ed0a6f19c69b41166c5510', - '0b42b6393c1f53060fe3ddbfcd7aadcca894465a5a438f69c87d790b2299b9b2', - 'f1918e8562236eb17adc8502332f4c9c82bc14e19bfc0aa10ab674ff75b3d2f3' +assert mtree.raw_leaves == ['a', 'b', 'c', 'd'] + +# hashed leaves (just bytes) +assert mtree.leaves == [ + b':\xc2%\x16\x8d\xf5B\x12\xa2\\\x1c\x01\xfd5\xbe\xbf\xea@\x8f\xda\xc2\xe3\x1d\xddo\x80\xa4\xbb\xf9\xa5\xf1\xcb', b'\xb5U=\xe3\x15\xe0\xed\xf5\x04\xd9\x15\n\xf8-\xaf\xa5\xc4f\x7f\xa6\x18\xed\no\x19\xc6\x9bA\x16lU\x10', b'\x0bB\xb69<\x1fS\x06\x0f\xe3\xdd\xbf\xcdz\xad\xcc\xa8\x94FZZC\x8fi\xc8}y\x0b"\x99\xb9\xb2', b'\xf1\x91\x8e\x85b#n\xb1z\xdc\x85\x023/L\x9c\x82\xbc\x14\xe1\x9b\xfc\n\xa1\n\xb6t\xffu\xb3\xd2\xf3' ] -# shorted hashed leafs -assert mtree.short_leafs == [ - '3ac2...', - 'b555...', - '0b42...', - 'f191...' +# shorted hashed leaves +assert mtree.short_leaves == [b':\xc2', b'\xb5U', b'\x0bB', b'\xf1\x91'] + + +######## comming soon! + +# human leaves +assert mtree.human_leaves == [ + "3ac225168df54212a25c1c01fd35bebfea408fdac2e31ddd6f80a4bbf9a5f1cb", + "b5553de315e0edf504d9150af82dafa5c4667fa618ed0a6f19c69b41166c5510", + "0b42b6393c1f53060fe3ddbfcd7aadcca894465a5a438f69c87d790b2299b9b2", + "f1918e8562236eb17adc8502332f4c9c82bc14e19bfc0aa10ab674ff75b3d2f3", ] +# shorted human hashed leaves +assert mtree.human_short_leaves = ["3ac2", "b555", "0b42", "f191"] ``` -**Create a Root** +**Creating a Root** ```python from merkly.mtree import MerkleTree @@ -135,36 +131,47 @@ from merkly.mtree import MerkleTree # create a Merkle Tree mtree = MerkleTree(['a', 'b', 'c', 'd']) -# get root of tree -assert mtree.root == '115cbb4775ed495f3d954dfa47164359a97762b40059d9502895def16eed609c' +# get root of tree (This is compatible with MerkleTreeJS) +assert mtree.root.hex() == '68203f90e9d07dc5859259d7536e87a6ba9d345f2552b5b9de2999ddce9ce1bf' ``` -**Create Proof of a leaf** +**Creating Proof of a leaf** ```python from merkly.mtree import MerkleTree +from merkly.node import Node, Side # create a Merkle Tree mtree = MerkleTree(['a', 'b', 'c', 'd']) # get proof of a `raw` leaf assert mtree.proof('b') == [ - Node(left: '3ac2...'), - Node(right: 'b555...'), - Node(right: '6467...') + Node(data=b"3ac225168df54212a25c1c01fd35bebfea408fdac2e31ddd6f80a4bbf9a5f1cb", side=Side.LEFT), + Node(data=b"d253a52d4cb00de2895e85f2529e2976e6aaaa5c18106b68ab66813e14415669", side=Side.RIGHT) ] ``` -**Verify Proof of a leaf** +**Checking the proof of a sheet** ```python from merkly.mtree import MerkleTree +from merkly.node import Node, Side + # create a Merkle Tree mtree = MerkleTree(['a', 'b', 'c', 'd']) # get proof of a raw leaf -p = mtree.proof('b') +p = [ + Node( + data=b"3ac225168df54212a25c1c01fd35bebfea408fdac2e31ddd6f80a4bbf9a5f1cb", + side=Side.LEFT + ), + Node( + data=b"d253a52d4cb00de2895e85f2529e2976e6aaaa5c18106b68ab66813e14415669", + side=Side.RIGHT + ) +] # verify your proof of raw leaf assert mtree.verify(p, 'b') == True @@ -195,5 +202,3 @@ assert mtree.verify(p, 'b') == True ## License [MIT](LICENSE) - - From 1b210fa78d85e97f23a7cad5cec91b2dfbdef289 Mon Sep 17 00:00:00 2001 From: Lucas Oliveira Date: Sun, 31 Dec 2023 00:25:06 -0300 Subject: [PATCH 4/4] add: new docs --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 774ebc3..0425846 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "merkly" -version = "1.0.1" +version = "1.0.2" description = "🌳 The simple and easy implementation of Merkle Tree" authors = ["Lucas Oliveira "] repository = "https://github.com/olivmath/merkly.git"