Implement new Giga GarbageCollector interface

app/seidb_test.go

@@ -252,7 +252,9 @@ func TestParseReceiptConfigs_UsesConfiguredBackend(t *testing.T) {
 	assert.NoError(t, err)
 	assert.Equal(t, "pebbledb", receiptConfig.Backend)
 	assert.Equal(t, config.DefaultReceiptStoreConfig().AsyncWriteBuffer, receiptConfig.AsyncWriteBuffer)
-	assert.Equal(t, 0, receiptConfig.KeepRecent)
+	// Left at the default: no [receipt-store] key reaches KeepRecent. What a node retains is
+	// set later, by readReceiptStoreConfig from min-retain-blocks.
+	assert.Equal(t, config.DefaultReceiptKeepRecent, receiptConfig.KeepRecent)
 }
 
 func TestParseReceiptConfigs_UsesConfiguredValues(t *testing.T) {
@@ -267,7 +269,7 @@ func TestParseReceiptConfigs_UsesConfiguredValues(t *testing.T) {
 	assert.Equal(t, "/tmp/custom-receipt-db", receiptConfig.DBDirectory)
 	assert.Equal(t, "pebbledb", receiptConfig.Backend)
 	assert.Equal(t, 7, receiptConfig.AsyncWriteBuffer)
-	assert.Equal(t, 0, receiptConfig.KeepRecent)
+	assert.Equal(t, config.DefaultReceiptKeepRecent, receiptConfig.KeepRecent)
 	assert.Equal(t, 9, receiptConfig.PruneIntervalSeconds)
 	assert.True(t, receiptConfig.EnableReadWriteMetrics)
 }

app/testdata/state-commit.golden

@@ -15,6 +15,7 @@ FlatKVConfig.Fsync = bool(false)
 FlatKVConfig.AsyncWriteBuffer = int(0)
 FlatKVConfig.SnapshotInterval = uint32(10000)
 FlatKVConfig.SnapshotKeepRecent = uint32(1)
+FlatKVConfig.ExternalPruning = bool(false)
 FlatKVConfig.EnablePebbleMetrics = bool(true)
 FlatKVConfig.EnableReadWriteMetrics = bool(false)
 FlatKVConfig.AccountDBConfig.DataDir = string("")

sei-cosmos/server/config/testdata/server_config.golden

@@ -67,6 +67,7 @@ StateCommit.FlatKVConfig.Fsync = bool(false)
 StateCommit.FlatKVConfig.AsyncWriteBuffer = int(0)
 StateCommit.FlatKVConfig.SnapshotInterval = uint32(10000)
 StateCommit.FlatKVConfig.SnapshotKeepRecent = uint32(1)
+StateCommit.FlatKVConfig.ExternalPruning = bool(false)
 StateCommit.FlatKVConfig.EnablePebbleMetrics = bool(true)
 StateCommit.FlatKVConfig.EnableReadWriteMetrics = bool(false)
 StateCommit.FlatKVConfig.AccountDBConfig.DataDir = string("")

sei-db/config/giga_config.go

@@ -22,7 +22,7 @@ type GigaStorageConfig struct {
 	FlatKVConfig    *flatkvConfig.Config
 	SSConfig        StateStoreConfig
 	ReceiptDBConfig ReceiptStoreConfig
-	BlockDBConfig   *littblock.LittBlockConfig
+	BlockDBConfig   *littblock.BlockDBConfig
 	PruningConfig   *gc.StorageGarbageCollectorConfig
 }
 

sei-db/config/receipt_config.go

@@ -27,6 +27,12 @@ const (
 // littidx eth_getLogs (see ReceiptStoreConfig.LogFilterParallelism).
 const DefaultReceiptLogFilterParallelism = 16
 
+// DefaultReceiptKeepRecent is the default retention window in blocks for callers that
+// build a ReceiptStoreConfig directly. A seid node never uses it — see
+// ReceiptStoreConfig.KeepRecent for why — so it is sized for a tool or test that wants
+// bounded growth, not to express what a node should retain.
+const DefaultReceiptKeepRecent = 10000
+
 // ReceiptStoreConfig defines configuration for the receipt store database.
 type ReceiptStoreConfig struct {
 	// DBDirectory defines the directory to store the receipt store db files
@@ -47,14 +53,37 @@ type ReceiptStoreConfig struct {
 
 	// KeepRecent defines the number of versions to keep in receipt store.
 	// Setting it to 0 means keep everything (no pruning).
-	// This is NOT read from receipt-store config; it is always derived from
-	// the global min-retain-blocks flag at the app layer.
+	//
+	// This is NOT read from receipt-store config, and on a seid node it is not read
+	// from DefaultReceiptStoreConfig either: readReceiptStoreConfig overwrites it
+	// unconditionally from the global min-retain-blocks flag, including with 0 when
+	// that flag is unset. The default below is therefore only reachable by callers
+	// that build this config directly — tools and tests — and changing it does not
+	// change what any node retains.
 	KeepRecent int `mapstructure:"-"`
 
 	// PruneIntervalSeconds defines the interval in seconds to trigger pruning
 	// default to every 600 seconds
 	PruneIntervalSeconds int `mapstructure:"prune-interval-seconds"`
 
+	// ExternalPruning hands retention to the StorageGarbageCollector: the littidx backend
+	// stops running its own KeepRecent pruner and answers gc.PrunableStore.ExternalPruning
+	// with this value, so the collector prunes it instead.
+	//
+	// Like KeepRecent this is not read from the receipt-store config. It is set by whatever
+	// constructs the collector, because it is only correct when this store is actually
+	// registered with a running one — nothing here can check that, and the failure is silent
+	// and unbounded: the retention floor simply stops advancing.
+	//
+	// It is one field rather than two so the KeepRecent pruner and the collector can never
+	// both be enforcing retention. They would disagree, and the local pruner would win by
+	// deleting the rollback headroom the collector exists to preserve.
+	//
+	// Only the littidx backend honors this. The pebbledb backend is not a gc.PrunableStore,
+	// so the collector would not prune it and setting this would leave it with no pruner at
+	// all; newReceiptBackend rejects that combination rather than growing without bound.
+	ExternalPruning bool `mapstructure:"-"`
+
 	// EnableReadWriteMetrics emits simple estimated read/write counters for Pebble-backed receipt storage.
 	// defaults to false
 	EnableReadWriteMetrics bool `mapstructure:"enable-read-write-metrics"`
@@ -68,13 +97,15 @@ type ReceiptStoreConfig struct {
 }
 
 // DefaultReceiptStoreConfig returns the default ReceiptStoreConfig.
-// KeepRecent defaults to 0 (no pruning). The app layer is responsible
-// for setting KeepRecent from the global min-retain-blocks flag.
+//
+// KeepRecent is a bounded default rather than 0 so that a caller building this config
+// directly gets a store that prunes. It is not what a node retains: the app layer
+// replaces it with min-retain-blocks before the store is opened (see KeepRecent).
 func DefaultReceiptStoreConfig() ReceiptStoreConfig {
 	return ReceiptStoreConfig{
 		Backend:              "pebbledb",
 		AsyncWriteBuffer:     DefaultSSAsyncBuffer,
-		KeepRecent:           0,
+		KeepRecent:           DefaultReceiptKeepRecent,
 		PruneIntervalSeconds: DefaultSSPruneInterval,
 		LogFilterParallelism: DefaultReceiptLogFilterParallelism,
 	}

sei-db/config/receipt_config_fuzz_test.go

@@ -206,6 +206,12 @@ func TestManifestNamesEveryField(t *testing.T) {
 		// sitting in a config struct that configuration cannot address is exactly the kind of
 		// thing a replacement manager would otherwise try to map a key onto.
 		"KeepRecent",
+		// ExternalPruning is tagged mapstructure:"-" for a sharper reason than KeepRecent: it is
+		// only correct when this store is registered with a running StorageGarbageCollector, which
+		// is a property of how the process was wired and not something an operator can assert from
+		// app.toml. Exposing a key for it would let a node stand its pruner down with nothing to
+		// replace it, and the resulting unbounded growth is silent.
+		"ExternalPruning",
 	)
 }
 

sei-db/config/testdata/receipt-store.golden

@@ -1,7 +1,8 @@
 DBDirectory = string("")
 Backend = string("pebbledb")
 AsyncWriteBuffer = int(100)
-KeepRecent = int(0)
+KeepRecent = int(10000)
 PruneIntervalSeconds = int(600)
+ExternalPruning = bool(false)
 EnableReadWriteMetrics = bool(false)
 LogFilterParallelism = int(16)

sei-db/config/toml_test.go

@@ -58,6 +58,7 @@ func TestStateCommitConfigTemplate(t *testing.T) {
 	require.NotContains(t, flatKVSection, "snapshot-interval", "FlatKV snapshot-interval should not be exposed in app.toml")
 	require.NotContains(t, flatKVSection, "snapshot-keep-recent", "FlatKV snapshot-keep-recent should not be exposed in app.toml")
 	require.NotContains(t, flatKVSection, "enable-read-write-metrics", "FlatKV read/write metrics flag should not be exposed in app.toml")
+	require.NotContains(t, flatKVSection, "external-pruning", "FlatKV external-pruning should not be exposed in app.toml")
 
 	// sc-snapshot-writer-limit is intentionally removed from template (hardcoded to 4)
 	// but old configs with this field still parse fine via mapstructure

sei-db/ledger_db/block/block_db_test.go

@@ -1402,10 +1402,10 @@ func TestMemblockPruneIntoCohortRoundsDown(t *testing.T) {
 
 // littConfig builds a littblock config rooted at dir with a tiny retention so
 // the prune watermark is the sole observable reclamation gate in tests.
-func littConfig(t *testing.T, dir string) *littblock.LittBlockConfig {
+func littConfig(t *testing.T, dir string) *littblock.BlockDBConfig {
 	cfg, err := littblock.DefaultConfig(dir)
 	require.NoError(t, err)
-	cfg.Retention = time.Nanosecond
+	cfg.RetentionTime = time.Nanosecond
 	return cfg
 }
 

sei-db/ledger_db/block/blocksim/blocksim.go

@@ -506,7 +506,7 @@ func openBlockDB(config *BlocksimConfig) (types.BlockDB, error) {
 		if err != nil {
 			return nil, fmt.Errorf("failed to build litt block db config: %w", err)
 		}
-		littConfig.Retention = time.Duration(config.LittRetentionSeconds) * time.Second
+		littConfig.RetentionTime = time.Duration(config.LittRetentionSeconds) * time.Second
 		// Record litt_* metrics into blocksim's already-configured global OTel MeterProvider (set up in
 		// main before the DB is opened). MetricsServeEndpoint stays false so LittDB does not stand up its
 		// own registry/server; the metrics surface on blocksim's single /metrics endpoint.

sei-db/ledger_db/block/littblock/litt_block_config.go

@@ -5,46 +5,79 @@ import (
 	"time"
 
 	littdb "github.com/sei-protocol/sei-chain/sei-db/db_engine/litt"
+	"github.com/sei-protocol/sei-chain/sei-db/management/gc"
 )
 
-// LittBlockConfig configures a LittDB-backed types.BlockDB.
-type LittBlockConfig struct {
+// BlockDBConfig configures a LittDB-backed types.BlockDB.
+type BlockDBConfig struct {
 	// Litt is the underlying LittDB configuration, including the data directory
-	// paths. The block store builds its two tables (blocks, qcs) on top of this
-	// DB. Required; use DefaultConfig to obtain one with sane defaults, then
-	// override fields as needed (e.g. Litt.Fsync, Litt.GCPeriod).
+	// paths. The block store builds its single table (see tableName, which holds
+	// blocks and QCs both) on top of this DB. Required; use DefaultConfig to obtain
+	// one with sane defaults, then override fields as needed (e.g. Litt.Fsync,
+	// Litt.GCPeriod).
 	Litt *littdb.Config
 
-	// Retention is the failsafe minimum age before any pruned record may be
+	// RetentionTime is the failsafe minimum age before any pruned record may be
 	// reclaimed. Reclamation requires BOTH this age to elapse AND the prune
 	// watermark to advance past the record, so even an over-eager watermark
-	// cannot delete data younger than Retention. Must be positive.
-	Retention time.Duration
+	// cannot delete data younger than RetentionTime. Must be positive.
+	//
+	// It is an age floor, not a retention policy: how much history this store
+	// keeps is RetentionWindow below. Raising this only delays reclaiming what
+	// the watermark has already released, which costs disk and buys nothing the
+	// window does not already express.
+	RetentionTime time.Duration
+
+	// RetentionWindow is how much history this store keeps beyond the shared rollback
+	// window of the StorageGarbageCollector that manages it, in blocks. It is what
+	// gc.PrunableStore.GetRetentionWindow answers:
+	//
+	//	> 0  → that many blocks of history beyond the rollback window
+	//	0    → keep history to serve rollback window only
+	//	-1   → never prune this store (gc.InfiniteRetentionWindow)
+	//
+	// Zero does NOT mean "keep everything" here, unlike the KeepRecent fields on
+	// StateStoreConfig and ReceiptStoreConfig, where 0 disables pruning. It is the most
+	// aggressive setting this field has; "keep everything" is -1. Assigning a KeepRecent
+	// value to this field inverts the retention it asks for.
+	//
+	// This is an input to a minimum shared across every managed store, not a policy applied
+	// to this store alone: a deep window here also holds back receiptDB and the SC/SS
+	// snapshots. Must be >= gc.InfiniteRetentionWindow.
+	//
+	// Independent of Retention, which is a wall-clock TTL failsafe underneath the watermark.
+	// Both must permit reclamation before any record is dropped.
+	RetentionWindow int64
 }
 
-// DefaultConfig returns a LittBlockConfig preloaded with all defaults, rooted at
+// DefaultConfig returns a BlockDBConfig preloaded with all defaults, rooted at
 // dir. Override fields as needed, then pass it to NewBlockDB (which validates).
-func DefaultConfig(dir string) (*LittBlockConfig, error) {
+func DefaultConfig(dir string) (*BlockDBConfig, error) {
 	littConfig, err := littdb.DefaultConfig(dir)
 	if err != nil {
 		return nil, fmt.Errorf("failed to build litt config: %w", err)
 	}
-	return &LittBlockConfig{
-		Litt:      littConfig,
-		Retention: 24 * time.Hour,
+	return &BlockDBConfig{
+		Litt:            littConfig,
+		RetentionTime:   time.Hour,
+		RetentionWindow: 10000,
 	}, nil
 }
 
 // Validate performs a sanity check on the configuration.
-func (c *LittBlockConfig) Validate() error {
+func (c *BlockDBConfig) Validate() error {
 	if c == nil {
 		return fmt.Errorf("config is required")
 	}
 	if c.Litt == nil {
 		return fmt.Errorf("config.Litt is required")
 	}
-	if c.Retention <= 0 {
-		return fmt.Errorf("config.Retention must be positive (got %s)", c.Retention)
+	if c.RetentionTime <= 0 {
+		return fmt.Errorf("config.RetentionTime must be positive (got %s)", c.RetentionTime)
+	}
+	if c.RetentionWindow < gc.InfiniteRetentionWindow {
+		return fmt.Errorf("config.RetentionWindow must be >= %d (got %d)",
+			gc.InfiniteRetentionWindow, c.RetentionWindow)
 	}
 	return nil
 }

sei-db/ledger_db/block/littblock/litt_block_db.go

@@ -2,6 +2,8 @@ package littblock
 
 import (
 	"fmt"
+	"os"
+	"path/filepath"
 	"sync"
 	"sync/atomic"
 
@@ -12,18 +14,27 @@ import (
 	"github.com/sei-protocol/sei-chain/sei-tendermint/libs/utils"
 )
 
-// ledgerTableName is the single table holding both blocks and QCs. They share
-// one table so a crash leaves a contiguous write-order prefix spanning both
-// record kinds (see NewBlockDB), which is what guarantees a persisted block is
-// always covered by a persisted QC.
-const ledgerTableName = "ledger"
+// tableName is the single table holding blocks and QCs both, despite the name. They share one
+// table so a crash leaves a contiguous write-order prefix spanning both record kinds (see
+// NewBlockDB), which is what guarantees a persisted block is always covered by a persisted QC.
+//
+// This value is persisted layout, not just an identifier: littdb puts a table's data at
+// <root>/<tableName>/segments, so changing it makes NewBlockDB open a fresh empty table while the
+// old data sits untouched under the previous name — neither served nor reclaimed. refuseLegacyTable
+// turns that into a startup error rather than a store that looks healthy and empty.
+const tableName = "blocks"
+
+// legacyTableName is what tableName was called before the rename. Nothing opens it; it exists only
+// so refuseLegacyTable can recognize a directory written before the rename.
+const legacyTableName = "ledger"
 
 var _ types.BlockDB = (*blockDB)(nil)
 
 // blockDB is a durable types.BlockDB backed by LittDB
 type blockDB struct {
-	db    littdb.DB
-	table littdb.Table
+	db     littdb.DB
+	table  littdb.Table
+	config *BlockDBConfig
 
 	// watermark is a retention floor, always a QC boundary (a GlobalRange().First):
 	// PruneBefore rounds a requested prune point down to the start of the cohort
@@ -74,13 +85,18 @@ type blockDB struct {
 }
 
 // NewBlockDB opens (or creates) a LittDB-backed types.BlockDB from config. The
-// underlying LittDB is built from config.Litt, and the two tables apply
-// config.Retention as a TTL failsafe (pruning never reclaims data younger than
-// that even once the watermark has advanced past it).
-func NewBlockDB(config *LittBlockConfig) (types.BlockDB, error) {
+// underlying LittDB is built from config.Litt, and the table applies
+// config.RetentionTime as a TTL failsafe (pruning never reclaims data younger
+// than that even once the watermark has advanced past it).
+func NewBlockDB(config *BlockDBConfig) (types.BlockDB, error) {
 	if err := config.Validate(); err != nil {
 		return nil, fmt.Errorf("invalid block db config: %w", err)
 	}
+	// Before littbuilder.NewDB, so a refused open leaves the directory exactly as it found it
+	// rather than adding an empty table beside the one it is complaining about.
+	if err := refuseLegacyTable(config.Litt.Paths); err != nil {
+		return nil, err
+	}
 	db, err := littbuilder.NewDB(config.Litt)
 	if err != nil {
 		return nil, fmt.Errorf("failed to open litt db: %w", err)
@@ -96,8 +112,8 @@ func NewBlockDB(config *LittBlockConfig) (types.BlockDB, error) {
 	// guarantees a persisted block is always covered by a persisted QC. It also
 	// backs the write-order cursors and contiguous-QC recovery. ShardingFactor
 	// > 1, or splitting blocks and QCs across two tables, would void this.
-	tableConfig := littdb.DefaultTableConfig(ledgerTableName)
-	tableConfig.TTL = config.Retention
+	tableConfig := littdb.DefaultTableConfig(tableName)
+	tableConfig.TTL = config.RetentionTime
 	tableConfig.GCFilter = s.gcFilter
 	tableConfig.ShardingFactor = 1 // DO NOT CHANGE!!
 	table, err := db.BuildTable(tableConfig)
@@ -107,6 +123,7 @@ func NewBlockDB(config *LittBlockConfig) (types.BlockDB, error) {
 	}
 
 	s.table = table
+	s.config = config
 
 	if err := s.recoverCursors(); err != nil {
 		_ = db.Close()
@@ -119,6 +136,37 @@ func NewBlockDB(config *LittBlockConfig) (types.BlockDB, error) {
 	return s, nil
 }
 
+// refuseLegacyTable fails the open when any root path holds a table directory under
+// legacyTableName. Such a directory is blocks and QCs that this process cannot reach: littdb
+// resolves a table to <root>/<tableName>/segments, so the data is neither served nor reclaimed, and
+// the store would otherwise present itself as healthy and empty. An empty store is indistinguishable
+// from a correct one until something asks for history that is no longer there, which makes it the
+// worst shape this failure could take.
+//
+// No deployment can reach this — nothing has ever run littblock with the old name persisted — so it
+// exists for dev, CI, and devnet homes written before the rename. The operator action is to delete
+// the directory (or move it aside); this check can be deleted once no such directory remains.
+//
+// A root that cannot be stat'd is refused for the same reason it is refused when the directory is
+// present: an unreadable root cannot rule out data hiding under the old name.
+func refuseLegacyTable(paths []string) error {
+	for _, root := range paths {
+		legacy := filepath.Join(root, legacyTableName)
+		switch _, err := os.Stat(legacy); {
+		case err == nil:
+			return fmt.Errorf(
+				"block db: found a pre-rename %q table at %s; the table is now named %q, so those "+
+					"blocks and QCs would be neither served nor reclaimed. Delete or move the "+
+					"directory aside to start from an empty store",
+				legacyTableName, legacy, tableName)
+		case !os.IsNotExist(err):
+			return fmt.Errorf("block db: check for a pre-rename %q table at %s: %w",
+				legacyTableName, legacy, err)
+		}
+	}
+	return nil
+}
+
 // recoverCursors reloads the write-order cursors (lastBlockNumber, lastQCNext,
 // and their presence flags) from on-disk state. Without this, a reopened DB
 // would treat itself as empty and let WriteBlock/WriteQC silently accept