triedb/pathdb: implement journal and add more comments

core/rawdb/accessors_trie.go

@@ -65,7 +65,7 @@ func (h *hasher) release() {
 }
 
 // ReadAccountTrieNode retrieves the account trie node and the associated node
-// hash with the specified node path.
+// hash with the specified node path. If it's empty, return empty hash.
 func ReadAccountTrieNode(db ethdb.KeyValueReader, path []byte) ([]byte, common.Hash) {
 	data, err := db.Get(accountTrieNodeKey(path))
 	if err != nil {

trie/triedb/pathdb/database.go

@@ -19,6 +19,7 @@ package pathdb
 import (
 	"errors"
 	"fmt"
+	"io"
 	"sync"
 	"time"
 
@@ -58,6 +59,11 @@ type layer interface {
 	//
 	// Note, the maps are retained by the method to avoid copying everything.
 	update(root common.Hash, id uint64, block uint64, nodes map[common.Hash]map[string]*trienode.Node, states *triestate.Set) *diffLayer
+
+	// journal commits an entire diff hierarchy to disk into a single journal entry.
+	// This is meant to be used during shutdown to persist the layer without
+	// flattening everything down (bad for reorgs).
+	journal(w io.Writer) error
 }
 
 // Config contains the settings for database.

trie/triedb/pathdb/disklayer.go

@@ -38,8 +38,9 @@ type diskLayer struct {
 	db     *Database        // Path-based trie database
 	cleans *fastcache.Cache // GC friendly memory cache of clean node RLPs
 	buffer *nodebuffer      // Node buffer to aggregate writes
-	stale  bool             // Signals that the layer became stale (state progressed)
-	lock   sync.RWMutex     // Lock used to protect stale flag
+	// A stale state means that the data or information is outdated compared to a newer version or a more recent state.
+	stale bool         // Signals that the layer became stale (state progressed)
+	lock  sync.RWMutex // Lock used to protect stale flag
 }
 
 // newDiskLayer creates a new disk layer based on the passing arguments.