update: docs WIP

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`
 
 <img width="1172" alt="Gitlab Flow" src="https://user-images.githubusercontent.com/50037567/165442258-072abfe6-2295-40d6-a573-92f851878c4c.png">
 
 ---
 
-## 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`
-
-<img width="784" alt="envdev" src="https://user-images.githubusercontent.com/50037567/167924906-e9791796-c673-49b6-957b-493b33745907.png">
-
----
-
 ## 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
 
 ---
 

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,9 @@ poetry add merkly
 pip install merkly
 ```
 
-## How to works
+**HOW TO WORKS**
 
-- _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:
 
@@ -66,31 +66,31 @@ 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**
+**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
@@ -99,84 +99,100 @@ 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
 
 # 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
 ```
 
 ## 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
 
@@ -186,5 +202,3 @@ assert mtree.verify(p, 'b') == True
 ## License
 
 [MIT](LICENSE)
-
-<!-- https://math.mit.edu/research/highschool/primes/materials/2018/Kuszmaul.pdf -->

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 <olivmath@protonmail.com>"]
 repository = "https://github.com/olivmath/merkly.git"