From c428df2a6a7c9afea4b44eb668ec70fffa83544b Mon Sep 17 00:00:00 2001
From: Gary Rong <garyrong0905@gmail.com>
Date: Thu, 29 May 2025 15:22:34 +0800
Subject: [PATCH] triedb/pathdb: update comment

---
 triedb/pathdb/history_indexer.go |  3 +++
 triedb/pathdb/history_reader.go  |  3 ++-
 triedb/pathdb/reader.go          | 15 +++++++++++++--
 3 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/triedb/pathdb/history_indexer.go b/triedb/pathdb/history_indexer.go
index ade4f1a41c..0a7d76f989 100644
--- a/triedb/pathdb/history_indexer.go
+++ b/triedb/pathdb/history_indexer.go
@@ -479,6 +479,9 @@ func (i *historyIndexer) close() {
 	i.initer.close()
 }
 
+// inited returns a flag indicating whether the existing state histories
+// have been fully indexed, in other words, whether they are available
+// for external access.
 func (i *historyIndexer) inited() bool {
 	return i.initer.inited()
 }
diff --git a/triedb/pathdb/history_reader.go b/triedb/pathdb/history_reader.go
index b7aaf5e34f..259540e8cf 100644
--- a/triedb/pathdb/history_reader.go
+++ b/triedb/pathdb/history_reader.go
@@ -311,7 +311,8 @@ func (r *historyReader) read(state stateIdentQuery, stateID uint64, lastID uint6
 	lastIndexedID := rawdb.ReadLastStateHistoryIndex(r.disk)
 
 	// To serve the request, all state histories from stateID+1 to lastID
-	// must be indexed
+	// must be indexed. It's not supposed to happen unless system is very
+	// wrong.
 	if lastIndexedID == nil || *lastIndexedID < lastID {
 		indexed := "null"
 		if lastIndexedID != nil {
diff --git a/triedb/pathdb/reader.go b/triedb/pathdb/reader.go
index e53f364b26..b1a7fdd926 100644
--- a/triedb/pathdb/reader.go
+++ b/triedb/pathdb/reader.go
@@ -210,8 +210,19 @@ func (db *Database) HistoricReader(root common.Hash) (*HistoricalStateReader, er
 	if db.indexer == nil || !db.indexer.inited() {
 		return nil, errors.New("state histories haven't been fully indexed yet")
 	}
-	// States older than current disk layer (disk layer is included) are available
-	// for accessing.
+	if db.freezer == nil {
+		return nil, errors.New("state histories are not available")
+	}
+	// States at the current disk layer or above are directly accessible via
+	// db.StateReader.
+	//
+	// States older than the current disk layer (including the disk layer
+	// itself) are available through historic state access.
+	//
+	// Note: the requested state may refer to a stale historic state that has
+	// already been pruned. This function does not validate availability, as
+	// underlying states may be pruned dynamically. Validity is checked during
+	// each actual state retrieval.
 	id := rawdb.ReadStateID(db.diskdb, root)
 	if id == nil {
 		return nil, fmt.Errorf("state %#x is not available", root)