core, eth, triedb: serve historical states over RPC (#31161)

This is the part-2 for archive node over path mode, which ultimately
ships the functionality to serve the historical states

Author: rjl493456442

core/blockchain_reader.go

@@ -370,6 +370,13 @@ func (bc *BlockChain) StateAt(root common.Hash) (*state.StateDB, error) {
 	return state.New(root, bc.statedb)
 }
 
+// HistoricState returns a historic state specified by the given root.
+// Live states are not available and won't be served, please use `State`
+// or `StateAt` instead.
+func (bc *BlockChain) HistoricState(root common.Hash) (*state.StateDB, error) {
+	return state.New(root, state.NewHistoricDatabase(bc.db, bc.triedb))
+}
+
 // Config retrieves the chain's fork configuration.
 func (bc *BlockChain) Config() *params.ChainConfig { return bc.chainConfig }
 

core/state/database_history.go

@@ -0,0 +1,155 @@
+// Copyright 2025 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// The go-ethereum library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
+
+package state
+
+import (
+	"errors"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/lru"
+	"github.com/ethereum/go-ethereum/core/state/snapshot"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/ethdb"
+	"github.com/ethereum/go-ethereum/rlp"
+	"github.com/ethereum/go-ethereum/trie/utils"
+	"github.com/ethereum/go-ethereum/triedb"
+	"github.com/ethereum/go-ethereum/triedb/pathdb"
+)
+
+// historicReader wraps a historical state reader defined in path database,
+// providing historic state serving over the path scheme.
+//
+// TODO(rjl493456442): historicReader is not thread-safe and does not fully
+// comply with the StateReader interface requirements, needs to be fixed.
+// Currently, it is only used in a non-concurrent context, so it is safe for now.
+type historicReader struct {
+	reader *pathdb.HistoricalStateReader
+}
+
+// newHistoricReader constructs a reader for historic state serving.
+func newHistoricReader(r *pathdb.HistoricalStateReader) *historicReader {
+	return &historicReader{reader: r}
+}
+
+// Account implements StateReader, retrieving the account specified by the address.
+//
+// An error will be returned if the associated snapshot is already stale or
+// the requested account is not yet covered by the snapshot.
+//
+// The returned account might be nil if it's not existent.
+func (r *historicReader) Account(addr common.Address) (*types.StateAccount, error) {
+	account, err := r.reader.Account(addr)
+	if err != nil {
+		return nil, err
+	}
+	if account == nil {
+		return nil, nil
+	}
+	acct := &types.StateAccount{
+		Nonce:    account.Nonce,
+		Balance:  account.Balance,
+		CodeHash: account.CodeHash,
+		Root:     common.BytesToHash(account.Root),
+	}
+	if len(acct.CodeHash) == 0 {
+		acct.CodeHash = types.EmptyCodeHash.Bytes()
+	}
+	if acct.Root == (common.Hash{}) {
+		acct.Root = types.EmptyRootHash
+	}
+	return acct, nil
+}
+
+// Storage implements StateReader, retrieving the storage slot specified by the
+// address and slot key.
+//
+// An error will be returned if the associated snapshot is already stale or
+// the requested storage slot is not yet covered by the snapshot.
+//
+// The returned storage slot might be empty if it's not existent.
+func (r *historicReader) Storage(addr common.Address, key common.Hash) (common.Hash, error) {
+	blob, err := r.reader.Storage(addr, key)
+	if err != nil {
+		return common.Hash{}, err
+	}
+	if len(blob) == 0 {
+		return common.Hash{}, nil
+	}
+	_, content, _, err := rlp.Split(blob)
+	if err != nil {
+		return common.Hash{}, err
+	}
+	var slot common.Hash
+	slot.SetBytes(content)
+	return slot, nil
+}
+
+// HistoricDB is the implementation of Database interface, with the ability to
+// access historical state.
+type HistoricDB struct {
+	disk          ethdb.KeyValueStore
+	triedb        *triedb.Database
+	codeCache     *lru.SizeConstrainedCache[common.Hash, []byte]
+	codeSizeCache *lru.Cache[common.Hash, int]
+	pointCache    *utils.PointCache
+}
+
+// NewHistoricDatabase creates a historic state database.
+func NewHistoricDatabase(disk ethdb.KeyValueStore, triedb *triedb.Database) *HistoricDB {
+	return &HistoricDB{
+		disk:          disk,
+		triedb:        triedb,
+		codeCache:     lru.NewSizeConstrainedCache[common.Hash, []byte](codeCacheSize),
+		codeSizeCache: lru.NewCache[common.Hash, int](codeSizeCacheSize),
+		pointCache:    utils.NewPointCache(pointCacheSize),
+	}
+}
+
+// Reader implements Database interface, returning a reader of the specific state.
+func (db *HistoricDB) Reader(stateRoot common.Hash) (Reader, error) {
+	hr, err := db.triedb.HistoricReader(stateRoot)
+	if err != nil {
+		return nil, err
+	}
+	return newReader(newCachingCodeReader(db.disk, db.codeCache, db.codeSizeCache), newHistoricReader(hr)), nil
+}
+
+// OpenTrie opens the main account trie. It's not supported by historic database.
+func (db *HistoricDB) OpenTrie(root common.Hash) (Trie, error) {
+	return nil, errors.New("not implemented")
+}
+
+// OpenStorageTrie opens the storage trie of an account. It's not supported by
+// historic database.
+func (db *HistoricDB) OpenStorageTrie(stateRoot common.Hash, address common.Address, root common.Hash, trie Trie) (Trie, error) {
+	return nil, errors.New("not implemented")
+}
+
+// PointCache returns the cache holding points used in verkle tree key computation
+func (db *HistoricDB) PointCache() *utils.PointCache {
+	return db.pointCache
+}
+
+// TrieDB returns the underlying trie database for managing trie nodes.
+func (db *HistoricDB) TrieDB() *triedb.Database {
+	return db.triedb
+}
+
+// Snapshot returns the underlying state snapshot.
+func (db *HistoricDB) Snapshot() *snapshot.Tree {
+	return nil
+}

eth/api_backend.go

@@ -238,7 +238,10 @@ func (b *EthAPIBackend) StateAndHeaderByNumber(ctx context.Context, number rpc.B
 	}
 	stateDb, err := b.eth.BlockChain().StateAt(header.Root)
 	if err != nil {
-		return nil, nil, err
+		stateDb, err = b.eth.BlockChain().HistoricState(header.Root)
+		if err != nil {
+			return nil, nil, err
+		}
 	}
 	return stateDb, header, nil
 }
@@ -260,7 +263,10 @@ func (b *EthAPIBackend) StateAndHeaderByNumberOrHash(ctx context.Context, blockN
 		}
 		stateDb, err := b.eth.BlockChain().StateAt(header.Root)
 		if err != nil {
-			return nil, nil, err
+			stateDb, err = b.eth.BlockChain().HistoricState(header.Root)
+			if err != nil {
+				return nil, nil, err
+			}
 		}
 		return stateDb, header, nil
 	}

eth/state_accessor.go

@@ -182,10 +182,11 @@ func (eth *Ethereum) pathState(block *types.Block) (*state.StateDB, func(), erro
 	if err == nil {
 		return statedb, noopReleaser, nil
 	}
-	// TODO historic state is not supported in path-based scheme.
-	// Fully archive node in pbss will be implemented by relying
-	// on state history, but needs more work on top.
-	return nil, nil, errors.New("historical state not available in path scheme yet")
+	statedb, err = eth.blockchain.HistoricState(block.Root())
+	if err == nil {
+		return statedb, noopReleaser, nil
+	}
+	return nil, nil, errors.New("historical state is not available")
 }
 
 // stateAtBlock retrieves the state database associated with a certain block.

triedb/database.go

@@ -129,6 +129,15 @@ func (db *Database) StateReader(blockRoot common.Hash) (database.StateReader, er
 	return db.backend.StateReader(blockRoot)
 }
 
+// HistoricReader constructs a reader for accessing the requested historic state.
+func (db *Database) HistoricReader(root common.Hash) (*pathdb.HistoricalStateReader, error) {
+	pdb, ok := db.backend.(*pathdb.Database)
+	if !ok {
+		return nil, errors.New("not supported")
+	}
+	return pdb.HistoricReader(root)
+}
+
 // Update performs a state transition by committing dirty nodes contained in the
 // given set in order to update state from the specified parent to the specified
 // root. The held pre-images accumulated up to this point will be flushed in case

triedb/pathdb/history_indexer.go

@@ -504,7 +504,7 @@ func (i *indexIniter) index(done chan struct{}, interrupt *atomic.Int32, lastID
 				)
 				// Override the ETA if larger than the largest until now
 				eta := time.Duration(left/speed) * time.Millisecond
-				log.Info("Indexing state history", "processed", done, "left", left, "eta", common.PrettyDuration(eta))
+				log.Info("Indexing state history", "processed", done, "left", left, "elapsed", common.PrettyDuration(time.Since(start)), "eta", common.PrettyDuration(eta))
 			}
 		}
 		// Check interruption signal and abort process if it's fired