feat(data): integrate LittDB-backed BlockDB into autobahn data layer (CON-272) (#3707)

## Summary

- Replaces `DataWAL` (two WAL files) with a LittDB-backed `BlockDB` for
block and QC persistence
- `NewState(cfg, blockDB)` replays persisted state at construction time;
`None` disables persistence
- `GigaRouter` owns the `BlockDB` lifecycle: open in constructor, defer
close in `Run`

**Behavioral note:** On restart, blocks pruned before the previous
shutdown may briefly reappear until BlockDB GC catches up.

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: wen-coding

sei-db/ledger_db/block/block_db_test.go

@@ -69,6 +69,7 @@ func TestBlockDB(t *testing.T) {
 			t.Run("PruneQCOnlyThenWriteBlock", func(t *testing.T) {
 				testPruneQCOnlyThenWriteBlock(t, impl.build)
 			})
+			t.Run("Status", func(t *testing.T) { testStatus(t, impl.build) })
 			t.Run("WriteOrderRejected", func(t *testing.T) { testWriteOrderRejected(t, impl.build) })
 			t.Run("WriteOrderRejectedAfterRestart", func(t *testing.T) {
 				testWriteOrderRejectedAfterRestart(t, impl.build)
@@ -130,6 +131,74 @@ func testEmptyDB(t *testing.T, build builder) {
 	require.NoError(t, err)
 	require.False(t, ok, "empty db should yield no QCs")
 	require.NoError(t, qcIt.Close())
+
+	tips := db.Status()
+	require.Zero(t, tips.NextBlock, "empty db has no block write tip")
+	require.Zero(t, tips.NextQC, "empty db has no QC write tip")
+}
+
+// testStatus asserts Status matches the highest block/QC still present
+// (via reverse iterators), including after prune and restart, and that a QC
+// written ahead of its blocks advances only NextQC.
+func testStatus(t *testing.T, build builder) {
+	committee, keys := buildCommittee()
+	batches := generateBatches(committee, keys)
+	db, o := openFresh(t, build)
+	defer func() { _ = db.Close() }()
+
+	require.NoError(t, db.WriteQC(batches[0].first, batches[0].next, batches[0].qc))
+	tips := db.Status()
+	require.Equal(t, batches[0].next, tips.NextQC)
+	require.Zero(t, tips.NextBlock, "QC-only store has no block tip")
+	assertTipsMatchPresent(t, db)
+
+	for i, blk := range batches[0].blocks {
+		require.NoError(t, db.WriteBlock(batches[0].first+gbn(i), blk))
+	}
+	writeAll(t, db, batches[1:])
+	last := batches[len(batches)-1]
+	tips = db.Status()
+	require.Equal(t, last.next, tips.NextBlock)
+	require.Equal(t, last.next, tips.NextQC)
+	assertTipsMatchPresent(t, db)
+
+	// Prune away an early cohort; the write tip must still equal the highest
+	// present records (newest cohort is never removed).
+	require.Greater(t, len(batches), 1)
+	require.NoError(t, db.PruneBefore(batches[1].first))
+	assertTipsMatchPresent(t, db)
+	tips = db.Status()
+	require.Equal(t, last.next, tips.NextBlock, "prune must not move the block write tip")
+	require.Equal(t, last.next, tips.NextQC, "prune must not move the QC write tip")
+
+	db = restart(t, o, db)
+	assertTipsMatchPresent(t, db)
+	tips = db.Status()
+	require.Equal(t, last.next, tips.NextBlock, "block tip must survive restart")
+	require.Equal(t, last.next, tips.NextQC, "QC tip must survive restart")
+}
+
+// assertTipsMatchPresent checks Status against one reverse-iterator
+// step for blocks and QCs (the highest records the public read API still serves).
+func assertTipsMatchPresent(t *testing.T, db types.BlockDB) {
+	t.Helper()
+	tips := db.Status()
+
+	highest, hasBlock := recoverHighestBlock(t, db)
+	if tips.NextBlock != 0 {
+		require.True(t, hasBlock, "Status has a block tip but Blocks is empty")
+		require.Equal(t, highest+1, tips.NextBlock, "NextBlock must be one past the highest present block")
+	} else {
+		require.False(t, hasBlock, "Blocks has data but Status has no block tip")
+	}
+
+	lastQC, hasQC := recoverLastQC(t, db)
+	if tips.NextQC != 0 {
+		require.True(t, hasQC, "Status has a QC tip but QCs is empty")
+		require.Equal(t, lastQC.GlobalRange().Next, tips.NextQC, "NextQC must be Next of the highest present QC")
+	} else {
+		require.False(t, hasQC, "QCs has data but Status has no QC tip")
+	}
 }
 
 func testReadRoundTrip(t *testing.T, build builder) {

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

@@ -328,6 +328,19 @@ func (s *blockDB) Flush() error {
 	return nil
 }
 
+func (s *blockDB) Status() types.DBStatus {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	var tips types.DBStatus
+	if s.hasBlocks {
+		tips.NextBlock = s.lastBlockNumber + 1
+	}
+	if s.hasQC {
+		tips.NextQC = s.lastQCNext
+	}
+	return tips
+}
+
 func (s *blockDB) Blocks(reverse bool) (types.BlockIterator, error) {
 	it, err := s.table.Iterator(reverse)
 	if err != nil {

sei-db/ledger_db/block/memblock/mem_block_db.go

@@ -147,6 +147,19 @@ func (s *blockDB) PruneBefore(n types.GlobalBlockNumber) error {
 
 func (s *blockDB) Flush() error { return nil }
 
+func (s *blockDB) Status() types.DBStatus {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	var tips types.DBStatus
+	if s.hasBlocks {
+		tips.NextBlock = s.lastBlockNumber + 1
+	}
+	if s.hasQC {
+		tips.NextQC = s.lastQCNext
+	}
+	return tips
+}
+
 func (s *blockDB) Blocks(reverse bool) (types.BlockIterator, error) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()

sei-tendermint/autobahn/types/block_db.go

@@ -1,42 +1,9 @@
 package types
 
 import (
-	"errors"
-
 	"github.com/sei-protocol/sei-chain/sei-tendermint/libs/utils"
 )
 
-// ErrBlockOutOfOrder is returned by WriteBlock when the supplied
-// GlobalBlockNumber is not strictly greater than every previously written
-// block number. Blocks must be written in strictly ascending order.
-var ErrBlockOutOfOrder = errors.New("block: WriteBlock out of order")
-
-// ErrQCNonContiguous is returned by WriteQC when the QC's GlobalRange().First
-// does not equal the previous QC's GlobalRange().Next. QCs must be written as
-// a contiguous, ascending sequence.
-var ErrQCNonContiguous = errors.New("block: WriteQC non-contiguous")
-
-// ErrBlockMissingQC is returned by WriteBlock when no previously written QC
-// covers the block's GlobalBlockNumber. A QC covering a block must be written
-// before that block (see the BlockDB ordering contract).
-var ErrBlockMissingQC = errors.New("block: WriteBlock without covering QC")
-
-// ErrPruned is returned by the by-number read methods (ReadBlockByNumber and
-// ReadQCByBlockNumber) when the requested GlobalBlockNumber is strictly below
-// the current retention watermark: the record is treated as pruned and is not
-// served while below the watermark. It is distinct from a utils.None result,
-// which means "not present at or above the watermark" and may still be filled
-// by a future write.
-//
-// ErrPruned reflects the watermark's current position, not a permanent verdict.
-// The watermark only advances while a store stays open, so within a single
-// session ErrPruned is terminal — retrying the same n keeps returning it. It is
-// not durable across restarts: the watermark is re-derived on open and
-// reclamation is asynchronous, so an n that returned ErrPruned before a restart
-// may afterward read as present (or as utils.None). Callers should treat
-// ErrPruned as "not currently served," not as a guarantee the record is gone.
-var ErrPruned = errors.New("block: below retention watermark")
-
 // BlockDB is the durable backing store for data.State. It persists the two
 // kinds of finalized records the consensus state machine produces —
 // finalized blocks (indexed by GlobalBlockNumber and by header hash) and
@@ -183,6 +150,9 @@ type BlockDB interface {
 	// issuance).
 	Flush() error
 
+	// Status returns a consistent snapshot of the in-memory write tips (no I/O).
+	Status() DBStatus
+
 	// Blocks returns an iterator over every persisted block not yet
 	// pruned, for startup replay. Intended to be called once at
 	// construction by data.State.NewState.
@@ -269,6 +239,20 @@ type BlockDB interface {
 	Close() error
 }
 
+// DBStatus is the in-memory write tips returned by BlockDB.Status.
+// Both fields are exclusive "next to write" cursors (matching data.State's
+// nextQC / nextBlock). Zero means no write of that kind has occurred yet
+// (NextBlock/NextQC are never zero after a successful write: the first
+// written block number N yields NextBlock = N+1 ≥ 1).
+type DBStatus struct {
+	// NextBlock is one past the highest GlobalBlockNumber accepted by WriteBlock
+	// (the next block number that may be written). Zero if no block has been written.
+	NextBlock GlobalBlockNumber
+	// NextQC is the exclusive upper bound of the last WriteQC (the next QC
+	// range must start here). Zero if no QC has been written.
+	NextQC GlobalBlockNumber
+}
+
 // BlockIterator iterates over persisted blocks in GlobalBlockNumber order —
 // ascending, or descending if the iterator was created with reverse=true. It
 // is created via BlockDB.Blocks and captures a snapshot of the blocks present

sei-tendermint/autobahn/types/errors.go

@@ -0,0 +1,45 @@
+package types
+
+import "errors"
+
+// ErrNotFound is returned when a requested record is not yet available —
+// a block, QC, or AppProposal ahead of what data.State currently has (e.g.
+// ahead of the contiguous block/QC prefix). Distinct from ErrPruned, which
+// means the height is below the retention / eviction floor.
+var ErrNotFound = errors.New("not found")
+
+// ErrBlockGap is returned when BlockDB blocks are not contiguous (e.g. during
+// data.State recovery). That indicates store corruption or an incomplete write
+// that left a hole.
+var ErrBlockGap = errors.New("block gap in BlockDB")
+
+// ErrBlockOutOfOrder is returned by WriteBlock when the supplied
+// GlobalBlockNumber is not strictly greater than every previously written
+// block number. Blocks must be written in strictly ascending order.
+var ErrBlockOutOfOrder = errors.New("block: WriteBlock out of order")
+
+// ErrQCNonContiguous is returned by WriteQC when the QC's GlobalRange().First
+// does not equal the previous QC's GlobalRange().Next. QCs must be written as
+// a contiguous, ascending sequence.
+var ErrQCNonContiguous = errors.New("block: WriteQC non-contiguous")
+
+// ErrBlockMissingQC is returned by WriteBlock when no previously written QC
+// covers the block's GlobalBlockNumber. A QC covering a block must be written
+// before that block (see the BlockDB ordering contract).
+var ErrBlockMissingQC = errors.New("block: WriteBlock without covering QC")
+
+// ErrPruned is returned when a requested record is below the current retention
+// / eviction floor and is not served. Used for BlockDB by-number reads below
+// the store watermark, and for data.State lookups (blocks, QCs, AppProposals)
+// after in-memory eviction. Distinct from utils.None on BlockDB, which means
+// "not present at or above the watermark" and may still be filled by a future
+// write.
+//
+// ErrPruned reflects the watermark's current position, not a permanent verdict.
+// The watermark only advances while a store stays open, so within a single
+// session ErrPruned is terminal — retrying the same n keeps returning it. It is
+// not durable across restarts: the watermark is re-derived on open and
+// reclamation is asynchronous, so an n that returned ErrPruned before a restart
+// may afterward read as present (or as utils.None). Callers should treat
+// ErrPruned as "not currently served," not as a guarantee the record is gone.
+var ErrPruned = errors.New("pruned: below retention watermark")

sei-tendermint/cmd/tendermint/commands/gen_autobahn_config.go

@@ -34,6 +34,8 @@ Output is written to the file specified by --output.`,
 				return fmt.Errorf("--output flag is required")
 			}
 			persistentStateDir, _ := cmd.Flags().GetString("persistent-state-dir")
+			blockDBRetention, _ := cmd.Flags().GetString("blockdb-retention")
+			blockDBGCPeriod, _ := cmd.Flags().GetString("blockdb-gc-period")
 
 			var validators []config.AutobahnValidator
 			for _, dir := range args {
@@ -97,6 +99,11 @@ Output is written to the file specified by --output.`,
 			if persistentStateDir != "" {
 				cfg.PersistentStateDir = utils.Some(persistentStateDir)
 			}
+			blockDB, err := buildGenBlockDBConfig(blockDBRetention, blockDBGCPeriod)
+			if err != nil {
+				return err
+			}
+			cfg.BlockDB = blockDB
 
 			data, err := json.MarshalIndent(cfg, "", "  ")
 			if err != nil {
@@ -110,6 +117,35 @@ Output is written to the file specified by --output.`,
 		},
 	}
 	cmd.Flags().StringP("output", "o", "", "output file path for the autobahn config")
-	cmd.Flags().String("persistent-state-dir", "data/autobahn", "directory to persist autobahn consensus and data WALs across restarts; relative paths are resolved against the node's --home dir; pass --persistent-state-dir= (empty) to disable persistence and run in-memory only")
+	cmd.Flags().String("persistent-state-dir", "data/autobahn", "directory to persist autobahn consensus state and BlockDB across restarts; relative paths are resolved against the node's --home dir; pass --persistent-state-dir= (empty) to disable persistence and run in-memory only (memblock)")
+	// Default 30s: this helper is used by docker/local clusters, not production
+	// node bring-up. Pass --blockdb-retention= (empty) to omit block_db and keep
+	// littblock's production default (24h).
+	cmd.Flags().String("blockdb-retention", "30s", "BlockDB retention TTL written into block_db (default 30s for local/docker); pass empty to omit and keep littblock's 24h default")
+	cmd.Flags().String("blockdb-gc-period", "", "optional BlockDB GC period (e.g. 10s); omit to keep littblock default")
 	return cmd
 }
+
+// buildGenBlockDBConfig builds optional block_db overrides from gen-autobahn-config flags.
+// Empty duration strings leave BlockDB as the zero value (omitted from JSON).
+func buildGenBlockDBConfig(retention, gcPeriod string) (config.AutobahnBlockDBConfig, error) {
+	var bdb config.AutobahnBlockDBConfig
+	if retention != "" {
+		d, err := time.ParseDuration(retention)
+		if err != nil {
+			return config.AutobahnBlockDBConfig{}, fmt.Errorf("--blockdb-retention: %w", err)
+		}
+		bdb.Retention = utils.Some(utils.Duration(d))
+	}
+	if gcPeriod != "" {
+		d, err := time.ParseDuration(gcPeriod)
+		if err != nil {
+			return config.AutobahnBlockDBConfig{}, fmt.Errorf("--blockdb-gc-period: %w", err)
+		}
+		bdb.GCPeriod = utils.Some(utils.Duration(d))
+	}
+	if err := bdb.Validate(); err != nil {
+		return config.AutobahnBlockDBConfig{}, fmt.Errorf("block_db: %w", err)
+	}
+	return bdb, nil
+}

sei-tendermint/config/autobahn.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"net/url"
 
+	"github.com/sei-protocol/sei-chain/sei-db/ledger_db/block/littblock"
 	atypes "github.com/sei-protocol/sei-chain/sei-tendermint/autobahn/types"
 	"github.com/sei-protocol/sei-chain/sei-tendermint/internal/p2p"
 	"github.com/sei-protocol/sei-chain/sei-tendermint/libs/utils"
@@ -34,6 +35,26 @@ type AutobahnValidator struct {
 	EVMRPC URL `json:"evmrpc"`
 }
 
+// AutobahnBlockDBConfig holds optional overrides for the LittDB-backed BlockDB
+// opened under persistent_state_dir/blockdb. Paths are never taken from here —
+// Autobahn always roots BlockDB at <persistent_state_dir>/blockdb.
+//
+// Each field is independently optional. Absent fields keep whatever
+// littblock.DefaultConfig currently uses (do not duplicate those values here —
+// they live in the littblock / LittDB packages and may change).
+//
+// Disk impact (most → least useful for bounding usage): Retention, then
+// GCPeriod. Segment sizing is intentionally not exposed (engine-internal).
+type AutobahnBlockDBConfig struct {
+	// Retention is the failsafe minimum age before pruned records may be
+	// reclaimed. Primary knob for worst-case disk after PruneBefore advances.
+	// Absent ⇒ littblock.DefaultConfig Retention.
+	Retention utils.Option[utils.Duration] `json:"retention"`
+	// GCPeriod is how often GC runs once data is eligible (reclaim latency).
+	// Absent ⇒ littblock.DefaultConfig / LittDB GCPeriod.
+	GCPeriod utils.Option[utils.Duration] `json:"gc_period"`
+}
+
 // AutobahnFileConfig is the JSON structure of the autobahn config file.
 type AutobahnFileConfig struct {
 	Validators         []AutobahnValidator  `json:"validators"`
@@ -49,6 +70,11 @@ type AutobahnFileConfig struct {
 	// fullnodes serving downstream block-sync are subject to the same
 	// cap). Absent ⇒ DefaultMaxInboundFullnodePeers. Some(0) ⇒ reject all.
 	MaxInboundFullnodePeers utils.Option[uint64] `json:"max_inbound_fullnode_peers"`
+	// BlockDB optionally overlays AutobahnBlockDBConfig onto littblock.DefaultConfig
+	// when PersistentStateDir is set. Zero value ⇒ littblock.DefaultConfig unchanged
+	// (see AutobahnBlockDBConfig for field semantics). Ignored when
+	// PersistentStateDir is absent (memblock). Omitted from JSON when empty.
+	BlockDB AutobahnBlockDBConfig `json:"block_db,omitzero"`
 }
 
 // DefaultMaxInboundFullnodePeers is the built-in cap used when
@@ -80,5 +106,40 @@ func (fc *AutobahnFileConfig) Validate() error {
 	if fc.DialInterval <= 0 {
 		return errors.New("dial_interval must be > 0")
 	}
+	if err := fc.BlockDB.Validate(); err != nil {
+		return fmt.Errorf("block_db: %w", err)
+	}
 	return nil
 }
+
+// Validate checks optional BlockDB overrides. Absent fields are fine.
+func (c AutobahnBlockDBConfig) Validate() error {
+	if r, ok := c.Retention.Get(); ok && r <= 0 {
+		return errors.New("retention must be > 0 when set")
+	}
+	if p, ok := c.GCPeriod.Get(); ok && p <= 0 {
+		return errors.New("gc_period must be > 0 when set")
+	}
+	return nil
+}
+
+// LittBlockConfig returns littblock.DefaultConfig(dir) with this config's
+// optional overrides applied. Fsync is always forced on.
+func (c AutobahnBlockDBConfig) LittBlockConfig(dir string) (littblock.LittBlockConfig, error) {
+	if err := c.Validate(); err != nil {
+		return littblock.LittBlockConfig{}, err
+	}
+	cfg, err := littblock.DefaultConfig(dir)
+	if err != nil {
+		return littblock.LittBlockConfig{}, fmt.Errorf("littblock.DefaultConfig: %w", err)
+	}
+	if r, ok := c.Retention.Get(); ok {
+		cfg.Retention = r.Duration()
+	}
+	if p, ok := c.GCPeriod.Get(); ok {
+		cfg.Litt.GCPeriod = p.Duration()
+	}
+	// NOT SAFE to set false: crash can lose acknowledged BlockDB writes.
+	cfg.Litt.Fsync = true
+	return *cfg, nil
+}