triedb/pathdb: generalize the history indexer

It's a pre-requisite for shipping full archive node, reusing
the existing history indexing mechanism for trienode history.

Author: rjl493456442

triedb/pathdb/database.go

@@ -189,7 +189,7 @@ func New(diskdb ethdb.Database, config *Config, isVerkle bool) *Database {
 	}
 	// TODO (rjl493456442) disable the background indexing in read-only mode
 	if db.stateFreezer != nil && db.config.EnableStateIndexing {
-		db.stateIndexer = newHistoryIndexer(db.diskdb, db.stateFreezer, db.tree.bottom().stateID())
+		db.stateIndexer = newHistoryIndexer(db.diskdb, db.stateFreezer, db.tree.bottom().stateID(), typeStateHistory)
 		log.Info("Enabled state history indexing")
 	}
 	fields := config.fields()
@@ -245,7 +245,7 @@ func (db *Database) repairHistory() error {
 	}
 	// Truncate the extra state histories above in freezer in case it's not
 	// aligned with the disk layer. It might happen after a unclean shutdown.
-	pruned, err := truncateFromHead(db.stateFreezer, id)
+	pruned, err := truncateFromHead(db.stateFreezer, typeStateHistory, id)
 	if err != nil {
 		log.Crit("Failed to truncate extra state histories", "err", err)
 	}
@@ -448,7 +448,7 @@ func (db *Database) Enable(root common.Hash) error {
 	//   2. Re-initialize the indexer so it starts indexing from the new state root.
 	if db.stateIndexer != nil && db.stateFreezer != nil && db.config.EnableStateIndexing {
 		db.stateIndexer.close()
-		db.stateIndexer = newHistoryIndexer(db.diskdb, db.stateFreezer, db.tree.bottom().stateID())
+		db.stateIndexer = newHistoryIndexer(db.diskdb, db.stateFreezer, db.tree.bottom().stateID(), typeStateHistory)
 		log.Info("Re-enabled state history indexing")
 	}
 	log.Info("Rebuilt trie database", "root", root)
@@ -502,7 +502,7 @@ func (db *Database) Recover(root common.Hash) error {
 	if err := db.diskdb.SyncKeyValue(); err != nil {
 		return err
 	}
-	_, err := truncateFromHead(db.stateFreezer, dl.stateID())
+	_, err := truncateFromHead(db.stateFreezer, typeStateHistory, dl.stateID())
 	if err != nil {
 		return err
 	}

triedb/pathdb/disklayer.go

@@ -378,7 +378,7 @@ func (dl *diskLayer) writeStateHistory(diff *diffLayer) (bool, error) {
 		log.Debug("Skip tail truncation", "persistentID", persistentID, "tailID", tail+1, "headID", diff.stateID(), "limit", limit)
 		return true, nil
 	}
-	pruned, err := truncateFromTail(dl.db.stateFreezer, newFirst-1)
+	pruned, err := truncateFromTail(dl.db.stateFreezer, typeStateHistory, newFirst-1)
 	if err != nil {
 		return false, err
 	}

triedb/pathdb/history.go

@@ -19,19 +19,155 @@ package pathdb
 import (
 	"errors"
 	"fmt"
+	"iter"
 
+	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/ethdb"
 	"github.com/ethereum/go-ethereum/log"
 )
 
+// historyType represents the category of historical data.
+type historyType uint8
+
+const (
+	// typeStateHistory indicates history data related to account or storage changes.
+	typeStateHistory historyType = 0
+)
+
+// String returns the string format representation.
+func (h historyType) String() string {
+	switch h {
+	case typeStateHistory:
+		return "state"
+	default:
+		return fmt.Sprintf("unknown type: %d", h)
+	}
+}
+
+// elementType represents the category of state element.
+type elementType uint8
+
+const (
+	typeAccount elementType = 0 // represents the account data
+	typeStorage elementType = 1 // represents the storage slot data
+)
+
+// String returns the string format representation.
+func (e elementType) String() string {
+	switch e {
+	case typeAccount:
+		return "account"
+	case typeStorage:
+		return "storage"
+	default:
+		return fmt.Sprintf("unknown element type: %d", e)
+	}
+}
+
+// toHistoryType maps an element type to its corresponding history type.
+func toHistoryType(typ elementType) historyType {
+	if typ == typeAccount || typ == typeStorage {
+		return typeStateHistory
+	}
+	panic(fmt.Sprintf("unknown element type %v", typ))
+}
+
+// stateIdent represents the identifier of a state element, which can be
+// an account or a storage slot.
+type stateIdent struct {
+	typ elementType
+
+	// The hash of the account address. This is used instead of the raw account
+	// address is to align the traversal order with the Merkle-Patricia-Trie.
+	addressHash common.Hash
+
+	// The hash of the storage slot key. This is used instead of the raw slot key
+	// because, in legacy state histories (prior to the Cancun fork), the slot
+	// identifier is the hash of the key, and the original key (preimage) cannot
+	// be recovered. To maintain backward compatibility, the key hash is used.
+	//
+	// Meanwhile, using the storage key hash also preserve the traversal order
+	// with Merkle-Patricia-Trie.
+	//
+	// This field is null if the identifier refers to an account or a trie node.
+	storageHash common.Hash
+}
+
+// String returns the string format state identifier.
+func (ident stateIdent) String() string {
+	if ident.typ == typeAccount {
+		return ident.addressHash.Hex()
+	}
+	return ident.addressHash.Hex() + ident.storageHash.Hex()
+}
+
+// newAccountIdent constructs a state identifier for an account.
+func newAccountIdent(addressHash common.Hash) stateIdent {
+	return stateIdent{
+		typ:         typeAccount,
+		addressHash: addressHash,
+	}
+}
+
+// newStorageIdent constructs a state identifier for a storage slot.
+// The address denotes the address hash of the associated account;
+// the storageHash denotes the hash of the raw storage slot key;
+func newStorageIdent(addressHash common.Hash, storageHash common.Hash) stateIdent {
+	return stateIdent{
+		typ:         typeStorage,
+		addressHash: addressHash,
+		storageHash: storageHash,
+	}
+}
+
+// stateIdentQuery is the extension of stateIdent by adding the account address
+// and raw storage key.
+type stateIdentQuery struct {
+	stateIdent
+
+	address    common.Address
+	storageKey common.Hash
+}
+
+// newAccountIdentQuery constructs a state identifier for an account.
+func newAccountIdentQuery(address common.Address, addressHash common.Hash) stateIdentQuery {
+	return stateIdentQuery{
+		stateIdent: newAccountIdent(addressHash),
+		address:    address,
+	}
+}
+
+// newStorageIdentQuery constructs a state identifier for a storage slot.
+// the address denotes the address of the associated account;
+// the addressHash denotes the address hash of the associated account;
+// the storageKey denotes the raw storage slot key;
+// the storageHash denotes the hash of the raw storage slot key;
+func newStorageIdentQuery(address common.Address, addressHash common.Hash, storageKey common.Hash, storageHash common.Hash) stateIdentQuery {
+	return stateIdentQuery{
+		stateIdent: newStorageIdent(addressHash, storageHash),
+		address:    address,
+		storageKey: storageKey,
+	}
+}
+
+// history defines the interface of historical data, implemented by stateHistory
+// and trienodeHistory (in the near future).
+type history interface {
+	// typ returns the historical data type held in the history.
+	typ() historyType
+
+	// forEach returns an iterator to traverse the state entries in the history.
+	forEach() iter.Seq[stateIdent]
+}
+
 var (
 	errHeadTruncationOutOfRange = errors.New("history head truncation out of range")
 	errTailTruncationOutOfRange = errors.New("history tail truncation out of range")
 )
 
 // truncateFromHead removes excess elements from the head of the freezer based
 // on the given parameters. It returns the number of items that were removed.
-func truncateFromHead(store ethdb.AncientStore, nhead uint64) (int, error) {
+func truncateFromHead(store ethdb.AncientStore, typ historyType, nhead uint64) (int, error) {
 	ohead, err := store.Ancients()
 	if err != nil {
 		return 0, err
@@ -40,11 +176,11 @@ func truncateFromHead(store ethdb.AncientStore, nhead uint64) (int, error) {
 	if err != nil {
 		return 0, err
 	}
-	log.Info("Truncating from head", "ohead", ohead, "tail", otail, "nhead", nhead)
+	log.Info("Truncating from head", "type", typ.String(), "ohead", ohead, "tail", otail, "nhead", nhead)
 
 	// Ensure that the truncation target falls within the valid range.
 	if ohead < nhead || nhead < otail {
-		return 0, fmt.Errorf("%w, tail: %d, head: %d, target: %d", errHeadTruncationOutOfRange, otail, ohead, nhead)
+		return 0, fmt.Errorf("%w, %s, tail: %d, head: %d, target: %d", errHeadTruncationOutOfRange, typ, otail, ohead, nhead)
 	}
 	// Short circuit if nothing to truncate.
 	if ohead == nhead {
@@ -61,7 +197,7 @@ func truncateFromHead(store ethdb.AncientStore, nhead uint64) (int, error) {
 
 // truncateFromTail removes excess elements from the end of the freezer based
 // on the given parameters. It returns the number of items that were removed.
-func truncateFromTail(store ethdb.AncientStore, ntail uint64) (int, error) {
+func truncateFromTail(store ethdb.AncientStore, typ historyType, ntail uint64) (int, error) {
 	ohead, err := store.Ancients()
 	if err != nil {
 		return 0, err
@@ -72,7 +208,7 @@ func truncateFromTail(store ethdb.AncientStore, ntail uint64) (int, error) {
 	}
 	// Ensure that the truncation target falls within the valid range.
 	if otail > ntail || ntail > ohead {
-		return 0, fmt.Errorf("%w, tail: %d, head: %d, target: %d", errTailTruncationOutOfRange, otail, ohead, ntail)
+		return 0, fmt.Errorf("%w, %s, tail: %d, head: %d, target: %d", errTailTruncationOutOfRange, typ, otail, ohead, ntail)
 	}
 	// Short circuit if nothing to truncate.
 	if otail == ntail {