refactor(sei-db): encapsulate ReadOptions lifecycle in iterator constructors

Push ReadOptions creation into the iterator constructors so callers
never handle ReadOptions directly:

- newIterator() creates a versioned iterator with internally managed
  ReadOptions, used by Iterator() and ReverseIterator()
- newRangeIterator() creates a timestamp-range iterator, used by
  RawIterate()
- newTSReadOptions() now returns a cleanup closure alongside the
  ReadOptions, making it harder to forget Destroy() for non-iterator
  uses (getSlice)
- The iterator stores a cleanup func() instead of *ReadOptions,
  called on Close()

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: pdrobnjak

sei-db/db_engine/rocksdb/mvcc/db.go

@@ -127,8 +127,8 @@ func OpenDB(dataDir string, config config.StateStoreConfig) (*Database, error) {
 }
 
 func (db *Database) getSlice(storeKey string, version int64, key []byte) (*grocksdb.Slice, error) {
-	readOpts := newTSReadOptions(version)
-	defer readOpts.Destroy()
+	readOpts, cleanup := newTSReadOptions(version)
+	defer cleanup()
 	return db.storage.GetCF(
 		readOpts,
 		db.cfHandle,
@@ -324,9 +324,7 @@ func (db *Database) Iterator(storeKey string, version int64, start, end []byte)
 	prefix := storePrefix(storeKey)
 	start, end = util.IterateWithPrefix(prefix, start, end)
 
-	readOpts := newTSReadOptions(version)
-	itr := db.storage.NewIteratorCF(readOpts, db.cfHandle)
-	return NewRocksDBIterator(itr, readOpts, prefix, start, end, version, db.earliestVersion, false), nil
+	return newIterator(db.storage, db.cfHandle, prefix, start, end, version, db.earliestVersion, false), nil
 }
 
 func (db *Database) ReverseIterator(storeKey string, version int64, start, end []byte) (types.DBIterator, error) {
@@ -341,9 +339,7 @@ func (db *Database) ReverseIterator(storeKey string, version int64, start, end [
 	prefix := storePrefix(storeKey)
 	start, end = util.IterateWithPrefix(prefix, start, end)
 
-	readOpts := newTSReadOptions(version)
-	itr := db.storage.NewIteratorCF(readOpts, db.cfHandle)
-	return NewRocksDBIterator(itr, readOpts, prefix, start, end, version, db.earliestVersion, true), nil
+	return newIterator(db.storage, db.cfHandle, prefix, start, end, version, db.earliestVersion, true), nil
 }
 
 // Import loads the initial version of the state in parallel with numWorkers goroutines
@@ -404,25 +400,13 @@ func (db *Database) RawIterate(storeKey string, fn func(key []byte, value []byte
 		return false, err
 	}
 
-	var startTs [TimestampSize]byte
-	binary.LittleEndian.PutUint64(startTs[:], uint64(0))
-
-	var endTs [TimestampSize]byte
-	binary.LittleEndian.PutUint64(endTs[:], uint64(latestVersion))
-
-	// Set timestamp lower and upper bound to iterate over all keys in db
-	readOpts := grocksdb.NewDefaultReadOptions()
-	readOpts.SetIterStartTimestamp(startTs[:])
-	readOpts.SetTimestamp(endTs[:])
-
-	itr := db.storage.NewIteratorCF(readOpts, db.cfHandle)
-	rocksItr := NewRocksDBIterator(itr, readOpts, prefix, start, end, latestVersion, 1, false)
+	rocksItr := newRangeIterator(db.storage, db.cfHandle, prefix, start, end, 0, latestVersion, 1)
 	defer func() { _ = rocksItr.Close() }()
 
 	for rocksItr.Valid() {
 		key := rocksItr.Key()
 		value := rocksItr.Value()
-		version := int64(binary.LittleEndian.Uint64(itr.Timestamp().Data()))
+		version := int64(binary.LittleEndian.Uint64(rocksItr.Timestamp().Data()))
 
 		// Call callback fn
 		if fn(key, value, version) {
@@ -443,15 +427,17 @@ func (db *Database) GetLatestMigratedModule() (string, error) {
 	panic("not implemented")
 }
 
-// newTSReadOptions returns ReadOptions used in the RocksDB column family read.
-func newTSReadOptions(version int64) *grocksdb.ReadOptions {
+// newTSReadOptions returns ReadOptions used in the RocksDB column family read
+// and a cleanup function that destroys them. The caller must ensure cleanup is
+// called when the ReadOptions are no longer needed.
+func newTSReadOptions(version int64) (*grocksdb.ReadOptions, func()) {
 	var ts [TimestampSize]byte
 	binary.LittleEndian.PutUint64(ts[:], uint64(version))
 
 	readOpts := grocksdb.NewDefaultReadOptions()
 	readOpts.SetTimestamp(ts[:])
 
-	return readOpts
+	return readOpts, func() { readOpts.Destroy() }
 }
 
 func storePrefix(storeKey string) []byte {

sei-db/db_engine/rocksdb/mvcc/iterator.go

@@ -5,6 +5,7 @@ package mvcc
 
 import (
 	"bytes"
+	"encoding/binary"
 
 	"github.com/linxGnu/grocksdb"
 	"github.com/sei-protocol/sei-chain/sei-db/state_db/ss/types"
@@ -14,25 +15,48 @@ var _ types.DBIterator = (*iterator)(nil)
 
 type iterator struct {
 	source             *grocksdb.Iterator
-	readOpts           *grocksdb.ReadOptions
+	cleanup            func()
 	prefix, start, end []byte
 	version            int64
 	reverse            bool
 	invalid            bool
 }
 
-func NewRocksDBIterator(source *grocksdb.Iterator, readOpts *grocksdb.ReadOptions, prefix, start, end []byte, version int64, earliestVersion int64, reverse bool) *iterator {
+// newIterator creates a versioned iterator. ReadOptions are created and owned
+// internally — destroyed when Close() is called.
+func newIterator(storage *grocksdb.DB, cfHandle *grocksdb.ColumnFamilyHandle, prefix, start, end []byte, version int64, earliestVersion int64, reverse bool) *iterator {
+	readOpts, cleanup := newTSReadOptions(version)
+	source := storage.NewIteratorCF(readOpts, cfHandle)
+	return buildIterator(source, cleanup, prefix, start, end, version, earliestVersion, reverse)
+}
+
+// newRangeIterator creates an iterator over a version range. ReadOptions are
+// created and owned internally — destroyed when Close() is called.
+func newRangeIterator(storage *grocksdb.DB, cfHandle *grocksdb.ColumnFamilyHandle, prefix, start, end []byte, startVersion, endVersion int64, earliestVersion int64) *iterator {
+	readOpts := grocksdb.NewDefaultReadOptions()
+	var startTs [TimestampSize]byte
+	binary.LittleEndian.PutUint64(startTs[:], uint64(startVersion))
+	var endTs [TimestampSize]byte
+	binary.LittleEndian.PutUint64(endTs[:], uint64(endVersion))
+	readOpts.SetIterStartTimestamp(startTs[:])
+	readOpts.SetTimestamp(endTs[:])
+
+	source := storage.NewIteratorCF(readOpts, cfHandle)
+	return buildIterator(source, func() { readOpts.Destroy() }, prefix, start, end, endVersion, earliestVersion, false)
+}
+
+func buildIterator(source *grocksdb.Iterator, cleanup func(), prefix, start, end []byte, version int64, earliestVersion int64, reverse bool) *iterator {
 	// Return invalid iterator if requested iterator height is lower than earliest version after pruning
 	if version < earliestVersion {
 		return &iterator{
-			source:   source,
-			readOpts: readOpts,
-			prefix:   prefix,
-			start:    start,
-			end:      end,
-			version:  version,
-			reverse:  reverse,
-			invalid:  true,
+			source:  source,
+			cleanup: cleanup,
+			prefix:  prefix,
+			start:   start,
+			end:     end,
+			version: version,
+			reverse: reverse,
+			invalid: true,
 		}
 	}
 
@@ -60,14 +84,14 @@ func NewRocksDBIterator(source *grocksdb.Iterator, readOpts *grocksdb.ReadOption
 	}
 
 	return &iterator{
-		source:   source,
-		readOpts: readOpts,
-		prefix:   prefix,
-		start:    start,
-		end:      end,
-		version:  version,
-		reverse:  reverse,
-		invalid:  !source.Valid(),
+		source:  source,
+		cleanup: cleanup,
+		prefix:  prefix,
+		start:   start,
+		end:     end,
+		version: version,
+		reverse: reverse,
+		invalid: !source.Valid(),
 	}
 }
 
@@ -141,6 +165,10 @@ func (itr *iterator) Value() []byte {
 	return copyAndFreeSlice(itr.source.Value())
 }
 
+func (itr *iterator) Timestamp() *grocksdb.Slice {
+	return itr.source.Timestamp()
+}
+
 func (itr iterator) Next() {
 	if itr.invalid {
 		return
@@ -160,9 +188,9 @@ func (itr *iterator) Error() error {
 func (itr *iterator) Close() error {
 	itr.source.Close()
 	itr.source = nil
-	if itr.readOpts != nil {
-		itr.readOpts.Destroy()
-		itr.readOpts = nil
+	if itr.cleanup != nil {
+		itr.cleanup()
+		itr.cleanup = nil
 	}
 	itr.invalid = true
 	return nil