add comments

core/trie2/hasher.go

@@ -7,7 +7,7 @@ import (
 	"github.com/NethermindEth/juno/core/crypto"
 )
 
-// hasher handles node hashing for the trie. It supports both sequential and parallel
+// A tool for shashing nodes in the trie. It supports both sequential and parallel
 // hashing modes.
 type hasher struct {
 	hashFn   crypto.HashFn // The hash function to use
@@ -21,7 +21,7 @@ func newHasher(hash crypto.HashFn, parallel bool) hasher {
 	}
 }
 
-// hash computes the hash of a node and returns both the hash node and a cached
+// Computes the hash of a node and returns both the hash node and a cached
 // version of the original node. If the node already has a cached hash, returns
 // that instead of recomputing.
 func (h *hasher) hash(n node) (node, node) {

core/trie2/id.go

@@ -21,6 +21,7 @@ type ID struct {
 	StorageRoot felt.Felt // The root hash of the storage trie of a contract.
 }
 
+// Returns the corresponding DB bucket for the trie
 func (id *ID) Bucket() db.Bucket {
 	switch id.TrieType {
 	case ClassTrie:
@@ -57,6 +58,7 @@ func ContractTrieID(root, owner, storageRoot felt.Felt) *ID {
 	}
 }
 
+// A general identifier, typically used for temporary trie
 func TrieID(root felt.Felt) *ID {
 	return &ID{
 		TrieType:    Empty,

core/trie2/node_enc.go

@@ -31,6 +31,7 @@ const (
 	edgeNodeType
 )
 
+// Enc(binary) = binaryNodeType + HashNode(left) + HashNode(right)
 func (n *binaryNode) write(buf *bytes.Buffer) error {
 	if err := buf.WriteByte(binaryNodeType); err != nil {
 		return err
@@ -47,6 +48,7 @@ func (n *binaryNode) write(buf *bytes.Buffer) error {
 	return nil
 }
 
+// Enc(edge) = edgeNodeType + HashNode(child) + Path
 func (n *edgeNode) write(buf *bytes.Buffer) error {
 	if err := buf.WriteByte(edgeNodeType); err != nil {
 		return err
@@ -63,6 +65,7 @@ func (n *edgeNode) write(buf *bytes.Buffer) error {
 	return nil
 }
 
+// Enc(hash) = Felt
 func (n *hashNode) write(buf *bytes.Buffer) error {
 	if _, err := buf.Write(n.Felt.Marshal()); err != nil {
 		return err
@@ -71,6 +74,7 @@ func (n *hashNode) write(buf *bytes.Buffer) error {
 	return nil
 }
 
+// Enc(value) = Felt
 func (n *valueNode) write(buf *bytes.Buffer) error {
 	if _, err := buf.Write(n.Felt.Marshal()); err != nil {
 		return err
@@ -79,6 +83,7 @@ func (n *valueNode) write(buf *bytes.Buffer) error {
 	return nil
 }
 
+// Returns the encoded bytes of a node
 func nodeToBytes(n node) []byte {
 	buf := bufferPool.Get().(*bytes.Buffer)
 	buf.Reset()
@@ -96,6 +101,7 @@ func nodeToBytes(n node) []byte {
 	return res
 }
 
+// Decodes the encoded bytes and returns the corresponding node
 func decodeNode(blob []byte, hash felt.Felt, pathLen, maxPathLen uint8) (node, error) {
 	if len(blob) == 0 {
 		return nil, errors.New("cannot decode empty blob")

core/trie2/proof.go

@@ -571,6 +571,8 @@ func hasRightElement(node node, key Path) bool {
 	return false
 }
 
+// Resolves the whole path of the given key and node.
+// If skipResolved is true, it will only return the immediate child node of the current node
 func get(rn node, key *Path, skipResolved bool) node {
 	for {
 		switch n := rn.(type) {

core/trie2/tracer.go

@@ -4,6 +4,7 @@ import (
 	"maps"
 )
 
+// Tracks the changes to the trie, so that we know which node needs to be updated or deleted in the database
 type nodeTracer struct {
 	inserts map[Path]struct{}
 	deletes map[Path]struct{}
@@ -16,17 +17,23 @@ func newTracer() *nodeTracer {
 	}
 }
 
+// Tracks the newly inserted trie node. If the trie node was previously deleted, remove it from the deletion set
+// as it means that the node will not be deleted in the database
 func (t *nodeTracer) onInsert(key *Path) {
 	k := *key
 	if _, present := t.deletes[k]; present {
+		delete(t.deletes, k)
 		return
 	}
 	t.inserts[k] = struct{}{}
 }
 
+// Tracks the newly deleted trie node. If the trie node was previously inserted, remove it from the insertion set
+// as it means that the node will not be inserted in the database
 func (t *nodeTracer) onDelete(key *Path) {
 	k := *key
 	if _, present := t.inserts[k]; present {
+		delete(t.inserts, k)
 		return
 	}
 	t.deletes[k] = struct{}{}

core/trie2/trie.go

@@ -454,6 +454,7 @@ func (t *Trie) delete(n node, prefix, key *Path) (bool, node, error) {
 	}
 }
 
+// Resolves the node at the given path from the database
 func (t *Trie) resolveNode(hash *hashNode, path Path) (node, error) {
 	buf := bufferPool.Get().(*bytes.Buffer)
 	buf.Reset()
@@ -471,6 +472,7 @@ func (t *Trie) resolveNode(hash *hashNode, path Path) (node, error) {
 	return decodeNode(blob, hash.Felt, path.Len(), t.height)
 }
 
+// Calculate the hash of the root node
 func (t *Trie) hashRoot() (node, node) {
 	if t.root == nil {
 		return &hashNode{Felt: felt.Zero}, nil