feat(autobahn): multi-epoch window for CommitQC/AppQC flow (CON-358)

sei-db/ledger_db/block/block_db_test.go

@@ -1484,8 +1484,6 @@ const (
 	testSeed      = 20260615
 )
 
-var genesisTime = time.Unix(1_700_000_000, 0)
-
 // batch is a contiguous run of blocks at global numbers [first, next) together
 // with the QC that finalizes them. next == first+len(blocks).
 type batch struct {
@@ -1577,7 +1575,7 @@ func buildFullCommitQC(
 	} else {
 		appQC = utils.None[*types.AppQC]()
 	}
-	ep := types.NewEpoch(0, types.OpenRoadRange(), genesisTime, committee, 0)
+	ep := types.NewEpoch(0, types.OpenRoadRange(), committee)
 	cqc := types.BuildCommitQC(ep, keys, prev, laneQCs, appQC)
 	return types.NewFullCommitQC(cqc, headers), blockList
 }

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

@@ -168,15 +168,29 @@ func (g *BlockGenerator) buildFullCommitQC() (*types.FullCommitQC, []*types.Bloc
 		}
 	}
 
-	viewSpec := types.ViewSpec{CommitQC: prev, Epoch: types.NewEpoch(0, types.OpenRoadRange(), genesisTime, committee, 0)}
+	viewSpec := types.ViewSpec{
+		CommitQC: prev,
+		Epochs: types.NewEpochDuo(
+			types.NewEpoch(0, types.OpenRoadRange(), committee),
+			utils.None[*types.Epoch](),
+		),
+		GenesisFirstBlock: 0,
+		GenesisTimestamp:  genesisTime,
+	}
 	leader := committee.Leader(viewSpec.View())
-	appQC := func() utils.Option[*types.AppQC] {
-		if n := viewSpec.NextGlobalBlock(); n > 0 {
-			p := types.NewAppProposal(n-1, viewSpec.View().Index, types.AppHash(g.rand.Bytes(hashSizeBytes)), viewSpec.Epoch.EpochIndex())
-			return utils.Some(g.fakeAppQC(p))
-		}
-		return utils.None[*types.AppQC]()
-	}()
+	// AppQC certifies the prior tipcut (road == prev.Index), not the tipcut
+	// being built. buildProposal drops AppQCs whose block is not finalized;
+	// Verify additionally requires road < view.
+	var appQC utils.Option[*types.AppQC]
+	if cqc, ok := prev.Get(); ok {
+		p := types.NewAppProposal(
+			cqc.GlobalRange().Next-1,
+			cqc.Proposal().Index(),
+			types.AppHash(g.rand.Bytes(hashSizeBytes)),
+			cqc.Proposal().EpochIndex(),
+		)
+		appQC = utils.Some(g.fakeAppQC(p))
+	}
 	proposal := utils.OrPanic1(types.NewProposalForTesting(
 		committee,
 		viewSpec,

sei-tendermint/AGENTS.md

@@ -33,6 +33,7 @@ Within sei-tendermint subdirectory
     optional uint64 index = 1; // required
     optional AppProposal app = 4; // optional
 * Avoid removing comments and logs which are not obviously obsolete. Keep the original wording, only fixing mistakes or obsolete parts.
+* Prefer concise comments that state invariants, contracts, and observable behavior (plus brief correctness reasoning when non-obvious). Avoid narrating how the implementation works step-by-step.
 * TestRng instance should be one per test, constructed directly in the test function. In case of nested/table tests, each nested test should create its own instance. 
   Use TestRng.Split() (before spawning) if you need to pass entropy source to a spawned goroutine
   to ensure deterministic entropy across the goroutines.

sei-tendermint/autobahn/types/app_qc.go

@@ -35,8 +35,17 @@ func (m *AppQC) Next() RoadIndex {
 	return m.Proposal().Next()
 }
 
-// Verify verifies the AppQC against the committee.
-func (m *AppQC) Verify(c *Committee) error {
+// Verify checks epoch_index / road against ep, then quorum under ep's committee.
+func (m *AppQC) Verify(ep *Epoch) error {
+	p := m.Proposal()
+	if got, want := p.EpochIndex(), ep.EpochIndex(); got != want {
+		return fmt.Errorf("appQC epoch %d, want %d", got, want)
+	}
+	if rr := ep.RoadRange(); !rr.Has(p.RoadIndex()) {
+		return fmt.Errorf("app road_index %v not in epoch %d roads [%v,%v)",
+			p.RoadIndex(), ep.EpochIndex(), rr.First, rr.Next)
+	}
+	c := ep.Committee()
 	return m.vote.verifyQC(c, c.AppQuorum(), m.sigs)
 }
 

sei-tendermint/autobahn/types/app_qc_test.go

@@ -0,0 +1,23 @@
+package types
+
+import (
+	"testing"
+
+	"github.com/sei-protocol/sei-chain/sei-tendermint/libs/utils"
+	"github.com/sei-protocol/sei-chain/sei-tendermint/libs/utils/require"
+)
+
+func TestAppQCVerifyChecksEpochAndRoad(t *testing.T) {
+	rng := utils.TestRng()
+	committee, keys := GenCommittee(rng, 4)
+	ep := NewEpoch(1, RoadRange{First: 100, Next: 200}, committee)
+
+	ok := makeAppQCFor(keys, 0, 150, GenAppHash(rng), 1)
+	require.NoError(t, ok.Verify(ep))
+
+	wrongEpoch := makeAppQCFor(keys, 0, 150, GenAppHash(rng), 0)
+	require.Error(t, wrongEpoch.Verify(ep))
+
+	wrongRoad := makeAppQCFor(keys, 0, 50, GenAppHash(rng), 1)
+	require.Error(t, wrongRoad.Verify(ep))
+}

sei-tendermint/autobahn/types/block.go

@@ -119,6 +119,10 @@ type GlobalBlock struct {
 	Payload      *Payload
 	// Highest known finalized state.
 	FinalAppState utils.Option[*AppProposal]
+	// Covering CommitQC road (from assembleGlobalBlock).
+	RoadIndex RoadIndex
+	// True when GlobalNumber is last in that QC's GlobalRange.
+	LastInCommitQC bool
 }
 
 // NewBlock creates a new Block.

sei-tendermint/autobahn/types/committee_test.go

@@ -129,10 +129,10 @@ func TestPrepareQCVerifyChecksEpochBinding(t *testing.T) {
 
 	require.NoError(t, sign(ProposalAt(ep, View{Index: ep.RoadRange().First})).Verify(ep))
 
-	wrongEpoch := newProposal(View{Index: ep.RoadRange().First, EpochIndex: ep.EpochIndex() + 1}, time.Time{}, nil, utils.None[*AppProposal](), ep.FirstBlock())
+	wrongEpoch := newProposal(View{Index: ep.RoadRange().First, EpochIndex: ep.EpochIndex() + 1}, time.Time{}, nil, utils.None[*AppProposal](), 1)
 	require.Error(t, sign(wrongEpoch).Verify(ep))
 
-	outOfRoads := newProposal(View{Index: ep.RoadRange().Last + 1, EpochIndex: ep.EpochIndex()}, time.Time{}, nil, utils.None[*AppProposal](), ep.FirstBlock())
+	outOfRoads := newProposal(View{Index: ep.RoadRange().Next, EpochIndex: ep.EpochIndex()}, time.Time{}, nil, utils.None[*AppProposal](), 1)
 	require.Error(t, sign(outOfRoads).Verify(ep))
 }
 
@@ -145,10 +145,10 @@ func TestCommitQCVerifyChecksEpochBinding(t *testing.T) {
 
 	require.NoError(t, sign(ProposalAt(ep, View{Index: ep.RoadRange().First})).Verify(ep))
 
-	wrongEpoch := newProposal(View{Index: ep.RoadRange().First, EpochIndex: ep.EpochIndex() + 1}, time.Time{}, nil, utils.None[*AppProposal](), ep.FirstBlock())
+	wrongEpoch := newProposal(View{Index: ep.RoadRange().First, EpochIndex: ep.EpochIndex() + 1}, time.Time{}, nil, utils.None[*AppProposal](), 1)
 	require.Error(t, sign(wrongEpoch).Verify(ep))
 
-	outOfRoads := newProposal(View{Index: ep.RoadRange().Last + 1, EpochIndex: ep.EpochIndex()}, time.Time{}, nil, utils.None[*AppProposal](), ep.FirstBlock())
+	outOfRoads := newProposal(View{Index: ep.RoadRange().Next, EpochIndex: ep.EpochIndex()}, time.Time{}, nil, utils.None[*AppProposal](), 1)
 	require.Error(t, sign(outOfRoads).Verify(ep))
 }
 
@@ -171,18 +171,18 @@ func TestCommitQCVerifyChecksWeight(t *testing.T) {
 func TestAppQCVerifyChecksWeight(t *testing.T) {
 	rng := utils.TestRng()
 	ep, keys := makeEpoch(rng)
-	vote := NewAppVote(NewAppProposal(0, 0, GenAppHash(rng), ep.EpochIndex()))
+	vote := NewAppVote(NewAppProposal(0, ep.RoadRange().First, GenAppHash(rng), ep.EpochIndex()))
 
 	heavyOnly := NewAppQC([]*Signed[*AppVote]{
 		Sign(keys[0], vote),
 	})
-	require.NoError(t, heavyOnly.Verify(ep.Committee()))
+	require.NoError(t, heavyOnly.Verify(ep))
 
 	lightMajority := NewAppQC([]*Signed[*AppVote]{
 		Sign(keys[1], vote),
 		Sign(keys[2], vote),
 	})
-	require.Error(t, lightMajority.Verify(ep.Committee()))
+	require.Error(t, lightMajority.Verify(ep))
 }
 
 func TestTimeoutQCVerifyChecksEpochBinding(t *testing.T) {

sei-tendermint/autobahn/types/epoch.go

@@ -1,51 +1,48 @@
 package types
 
 import (
-	"time"
-
 	"github.com/sei-protocol/sei-chain/sei-tendermint/libs/utils"
 )
 
 // EpochIndex is the epoch number.
 type EpochIndex uint64
 
-// RoadRange is an inclusive range of RoadIndex values [First, Last].
+// RoadRange is a half-open range of RoadIndex values [First, Next).
+// Matches GlobalRange / LaneRange: Next is exclusive (Next == lastInclusive+1).
 type RoadRange struct {
 	First RoadIndex
-	Last  RoadIndex
+	Next  RoadIndex
 }
 
-// OpenRoadRange returns a RoadRange covering all road indices from 0.
-// Use in tests and genesis epochs where no upper bound is known yet.
-func OpenRoadRange() RoadRange { return RoadRange{First: 0, Last: utils.Max[RoadIndex]()} }
+// OpenRoadRange returns [0, Max) for tests/genesis when no upper bound is known yet.
+func OpenRoadRange() RoadRange { return RoadRange{First: 0, Next: utils.Max[RoadIndex]()} }
+
+func (r RoadRange) Has(idx RoadIndex) bool { return idx >= r.First && idx < r.Next }
 
-// Has reports whether idx falls within this range (inclusive on both ends).
-func (r RoadRange) Has(idx RoadIndex) bool { return idx >= r.First && idx <= r.Last }
+// IsLastRoad is true when idx+1 == Next (same shape as GlobalRange.IsLastBlock).
+func (r RoadRange) IsLastRoad(idx RoadIndex) bool { return idx+1 == r.Next }
 
 // Epoch holds the complete context for a single epoch.
 // Retrieved from the local Registry; never transmitted on the wire.
+//
+// First global block / timestamp floors are not on Epoch: they come from the
+// last CommitQC of the prior epoch (or genesis GenDoc via Registry), and the
+// registry does not store CommitQCs.
 type Epoch struct {
 	utils.ReadOnly
-	epochIndex     EpochIndex
-	roads          RoadRange
-	firstTimestamp time.Time
-	committee      *Committee
-	firstBlock     GlobalBlockNumber
+	epochIndex EpochIndex
+	roads      RoadRange
+	committee  *Committee
 }
 
-// NewEpoch constructs an Epoch.
-func NewEpoch(index EpochIndex, roads RoadRange, firstTimestamp time.Time, committee *Committee, firstBlock GlobalBlockNumber) *Epoch {
+func NewEpoch(index EpochIndex, roads RoadRange, committee *Committee) *Epoch {
 	return &Epoch{
-		epochIndex:     index,
-		roads:          roads,
-		firstTimestamp: firstTimestamp,
-		committee:      committee,
-		firstBlock:     firstBlock,
+		epochIndex: index,
+		roads:      roads,
+		committee:  committee,
 	}
 }
 
-func (e *Epoch) EpochIndex() EpochIndex        { return e.epochIndex }
-func (e *Epoch) RoadRange() RoadRange          { return e.roads }
-func (e *Epoch) FirstTimestamp() time.Time     { return e.firstTimestamp }
-func (e *Epoch) Committee() *Committee         { return e.committee }
-func (e *Epoch) FirstBlock() GlobalBlockNumber { return e.firstBlock }
+func (e *Epoch) EpochIndex() EpochIndex { return e.epochIndex }
+func (e *Epoch) RoadRange() RoadRange   { return e.roads }
+func (e *Epoch) Committee() *Committee  { return e.committee }

sei-tendermint/autobahn/types/epoch_duo.go

@@ -0,0 +1,103 @@
+package types
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/sei-protocol/sei-chain/sei-tendermint/libs/utils"
+)
+
+// EpochDuo is a Prev|Current epoch window. Current is always set; Prev is
+// absent iff Current is epoch 0, otherwise contiguous with Current (index
+// Current-1 and Prev.Next == Current.First).
+type EpochDuo struct {
+	Prev    utils.Option[*Epoch]
+	Current *Epoch
+}
+
+// NewEpochDuo builds a Prev|Current window. Panics unless
+// prev≠None ⇔ current.EpochIndex()>0, and when Prev is present it must be
+// contiguous with Current.
+func NewEpochDuo(current *Epoch, prev utils.Option[*Epoch]) EpochDuo {
+	cur := current.EpochIndex()
+	p, hasPrev := prev.Get()
+	if hasPrev != (cur > 0) {
+		panic(fmt.Sprintf("NewEpochDuo: Prev present=%v but Current epoch %d (want Prev iff Current>0)",
+			hasPrev, cur))
+	}
+	if hasPrev {
+		if p.EpochIndex()+1 != cur {
+			panic(fmt.Sprintf("NewEpochDuo: Prev epoch %d not contiguous with Current %d",
+				p.EpochIndex(), cur))
+		}
+		if got, want := p.RoadRange().Next, current.RoadRange().First; got != want {
+			panic(fmt.Sprintf("NewEpochDuo: Prev roads end at %d, Current starts at %d", got, want))
+		}
+	}
+	return EpochDuo{Prev: prev, Current: current}
+}
+
+var ErrRoadBeforeWindow = errors.New("road before epoch duo window")
+var ErrRoadAfterWindow = errors.New("road after epoch duo window")
+
+// RoadStatus classifies a road relative to a Prev|Current window for admit waits.
+type RoadStatus int
+
+const (
+	RoadReady  RoadStatus = iota // in the admitted window
+	RoadStale                    // behind the window (soft-drop / ErrPruned)
+	RoadFuture                   // ahead of the window (backpressure wait)
+)
+
+// RoadStatusCurrent classifies roadIdx against Current only (CommitQC tip).
+func (w EpochDuo) RoadStatusCurrent(roadIdx RoadIndex) RoadStatus {
+	if w.Current.RoadRange().Has(roadIdx) {
+		return RoadReady
+	}
+	if roadIdx < w.Current.RoadRange().First {
+		return RoadStale
+	}
+	return RoadFuture
+}
+
+// RoadStatusDuo classifies roadIdx against Prev|Current (AppVote/AppQC).
+func (w EpochDuo) RoadStatusDuo(roadIdx RoadIndex) RoadStatus {
+	_, err := w.EpochForRoad(roadIdx)
+	if err == nil {
+		return RoadReady
+	}
+	if errors.Is(err, ErrRoadBeforeWindow) {
+		return RoadStale
+	}
+	return RoadFuture
+}
+
+// EpochForRoad returns the epoch containing roadIdx.
+// Window is [Prev.First or Current.First, Current.Next). Outside →
+// ErrRoadBeforeWindow / ErrRoadAfterWindow. Under contiguous Prev|Current there
+// is no gap, so a miss after the after-window check is always before-window.
+func (w EpochDuo) EpochForRoad(roadIdx RoadIndex) (*Epoch, error) {
+	if roadIdx >= w.Current.RoadRange().Next {
+		return nil, fmt.Errorf("road %d after window %v: %w", roadIdx, w, ErrRoadAfterWindow)
+	}
+	if w.Current.RoadRange().Has(roadIdx) {
+		return w.Current, nil
+	}
+	if prev, ok := w.Prev.Get(); ok && prev.RoadRange().Has(roadIdx) {
+		return prev, nil
+	}
+	return nil, fmt.Errorf("road %d before window %v: %w", roadIdx, w, ErrRoadBeforeWindow)
+}
+
+func (w EpochDuo) String() string {
+	s := "epochs ["
+	sep := ""
+	// Prev then Current so a window {4,5} prints as "epochs [4, 5]".
+	for _, oep := range [2]utils.Option[*Epoch]{w.Prev, utils.Some(w.Current)} {
+		if ep, ok := oep.Get(); ok {
+			s += fmt.Sprintf("%s%d", sep, ep.EpochIndex())
+			sep = ", "
+		}
+	}
+	return s + "]"
+}