From 5ab19f76e9f66e2b7b07dae7b8947159d812dd50 Mon Sep 17 00:00:00 2001
From: Diego <diego2737@gmail.com>
Date: Wed, 24 Jul 2024 10:03:54 +0000
Subject: [PATCH 1/2] docs(pkg/triedb): Add trieDB readme

---
 pkg/trie/triedb/README.md | 114 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 pkg/trie/triedb/README.md

diff --git a/pkg/trie/triedb/README.md b/pkg/trie/triedb/README.md
new file mode 100644
index 0000000000..682c810d3d
--- /dev/null
+++ b/pkg/trie/triedb/README.md
@@ -0,0 +1,114 @@
+# trieDB
+
+
+`triedb` is a library that acts as a layer over a key-value database, formatting those data into a radix-16 trie compatible with [polkadot spec](https://spec.polkadot.network/chap-state#sect-state-storage).  
+It offers functionalities for writing and reading operations and uses lazy loading to fetch data from the database, as well as a caching system to optimize searches.
+
+## Main features
+
+- **Writes**: Basic functions to manipulate data in the trie.
+- **Reads**: Basic functions to get data from the trie.
+- **Lazy Loading**: Load data on demand.
+- **Caching**: Enhances search performance.
+- **Compatibility**: Works with any database implementing the `db.RWDatabase` interface and any cache implementing the `cache.TrieCache` interface.
+- **Merkle proofs**: Create and verify merkle proofs.
+- **Iterator**: Traverse the trie keys in order.
+
+## Usage
+
+### Create a Trie
+
+To create an empty trie:
+
+```go
+trie := triedb.NewEmptyTrieDB(db)
+```
+
+### Insert Data
+
+To insert a key and its associated value:
+
+```go
+err := trie.Put([]byte("key"), []byte("value"))
+```
+
+### Get Data
+
+To get the value associated with a key:
+
+```go
+value := trie.Get([]byte("key"))
+```
+
+> Note: value will be empty `[]byte()` if there is no value for that key in the DB
+
+
+### Remove Data
+
+To delete a key and its associated value:
+
+```go
+trie.Delete([]byte("key"))
+```
+
+### Commit Data
+
+All modifications happen in memory until a commit is applied to the database. The commit is automatically applied whenever the root hash of the trie is calculated using:
+
+```go
+rootHash, err := trie.Hash()
+if err != nil {
+    // handle error
+}
+```
+
+or
+
+```go
+rootHash := trie.MustHash()
+```
+
+### Create a merkle proof
+
+To create a merkle proof you will need a `db` previously created using a trie, the `trieVersion` (v0, v1), the `rootHash` for the trie in that db and an slice of `keys` for which the proof will be created.
+
+```go
+merkleProof, err := proof.NewMerkleProof(db, trieVersion, rootHash, keys) 
+```
+
+### Verify merkle proofs
+
+In order to verify a merkle proof you can execute the `Verify` method over a previously created proof specifying the `trieVersion`, `rootHash` and the `items` you want to check, doing the following:
+
+```go
+err = merkleProof.Verify(trieVersion, rootHash, items)
+if err != nil {
+    fmt.Println("Invalid proof")
+}
+```
+
+> Note: items is a slice of `proofItem` structure.   
+
+### Iterator
+
+There are two ways to use the key iterator.
+Iterating by keys
+
+```go
+trieIterator := triedb.NewTrieDBIterator(trie)
+
+for key := iter.NextKey(); key != nil; key = iter.NextKey() {
+    fmt.Printf("key: %s", key)
+}
+```
+
+Iterating by entries
+
+```go
+trieIterator := triedb.NewTrieDBIterator(trie)
+
+for entry := iter.NextEntry(); entry != nil; entry = iter.NextEntry() {
+    fmt.Printf("key: %s, value: %s", entry.Key, entry.Value)
+}
+```
+

From dce838dffcd6cff1764cf6a23fdc6a61f72a010e Mon Sep 17 00:00:00 2001
From: Diego <diego2737@gmail.com>
Date: Fri, 16 Aug 2024 13:36:20 -0300
Subject: [PATCH 2/2] docs: Link trieDB readme in project readme

---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 4e7395a63c..f3041ae34b 100644
--- a/README.md
+++ b/README.md
@@ -159,6 +159,30 @@ Then start the three hosts:
 ./bin/gossamer --chain westend-local --charlie
 ```
 
+## Standalone Packages
+
+In addition to the core functionality provided by Gossamer, we have developed some standalone packages that can be used independently. These packages are located in the `pkg` directory and serve various utility purposes. Here’s an overview of some of these packages:
+
+### Scale
+
+To support parity's [scale type encoding](https://docs.substrate.io/reference/scale-codec/) in golang.  
+More details [here](./pkg/scale/README.md)
+
+### Trie
+
+The `trie` package includes multiple implementations of polkadot merkle tries. These implementations are useful for various applications requiring efficient data structures. Here are the key implementations:
+
+#### In-Memory Trie
+
+This implementation supports polkadot merkle tries that are stored entirely in memory. It includes features for backing up the trie using a database to ensure persistence.
+
+#### TrieDB
+
+An evolution of the in-memory trie, `TrieDB` introduces lazy loading capabilities from the underlying database. This approach optimizes performance and resource usage by loading data only as needed.
+
+For more details on how to use `TrieDB`, refer to the specific [README](pkg/trie/triedb/README.md)
+
+
 ## Contribute
 
 - Check out the [Contributing Guidelines](.github/CONTRIBUTING.md) and our