op-supervisor: DB improvements for cross-safe updates (#12622)

Co-authored-by: axelKingsley <axel.kingsley@gmail.com>
Co-authored-by: Tyler Smith <mail@tcry.pt>

op-supervisor/supervisor/backend/backend.go

@@ -17,7 +17,6 @@ import (
 	"github.com/ethereum-optimism/optimism/op-service/sources"
 	"github.com/ethereum-optimism/optimism/op-supervisor/config"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db"
-	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/entrydb"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/depset"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/processors"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/frontend"
@@ -71,7 +70,7 @@ func NewSupervisorBackend(ctx context.Context, logger log.Logger, m Metrics, cfg
 	chains := depSet.Chains()
 
 	// create initial per-chain resources
-	chainsDBs := db.NewChainsDB(logger)
+	chainsDBs := db.NewChainsDB(logger, depSet)
 	chainProcessors := make(map[types.ChainID]*processors.ChainProcessor, len(chains))
 	chainMetrics := make(map[types.ChainID]*chainMetrics, len(chains))
 
@@ -167,7 +166,7 @@ func (su *SupervisorBackend) attachRPC(ctx context.Context, rpc string) error {
 		return err
 	}
 	if !su.depSet.HasChain(chainID) {
-		return fmt.Errorf("chain %s is not part of the interop dependency set: %w", chainID, db.ErrUnknownChain)
+		return fmt.Errorf("chain %s is not part of the interop dependency set: %w", chainID, types.ErrUnknownChain)
 	}
 	cm, ok := su.chainMetrics[chainID]
 	if !ok {
@@ -273,10 +272,10 @@ func (su *SupervisorBackend) CheckMessage(identifier types.Identifier, payloadHa
 	blockNum := identifier.BlockNumber
 	logIdx := identifier.LogIndex
 	_, err := su.chainDBs.Check(chainID, blockNum, uint32(logIdx), payloadHash)
-	if errors.Is(err, entrydb.ErrFuture) {
+	if errors.Is(err, types.ErrFuture) {
 		return types.LocalUnsafe, nil
 	}
-	if errors.Is(err, entrydb.ErrConflict) {
+	if errors.Is(err, types.ErrConflict) {
 		return types.Invalid, nil
 	}
 	if err != nil {
@@ -378,7 +377,7 @@ func (su *SupervisorBackend) UpdateLocalUnsafe(chainID types.ChainID, head eth.B
 	defer su.mu.RUnlock()
 	ch, ok := su.chainProcessors[chainID]
 	if !ok {
-		return db.ErrUnknownChain
+		return types.ErrUnknownChain
 	}
 	return ch.OnNewHead(head)
 }

op-supervisor/supervisor/backend/backend_test.go

@@ -21,7 +21,6 @@ import (
 	"github.com/ethereum-optimism/optimism/op-service/testutils"
 	"github.com/ethereum-optimism/optimism/op-supervisor/config"
 	"github.com/ethereum-optimism/optimism/op-supervisor/metrics"
-	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/entrydb"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/depset"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/types"
 )
@@ -89,7 +88,7 @@ func TestBackendLifetime(t *testing.T) {
 	t.Log("started!")
 
 	_, err = b.UnsafeView(context.Background(), chainA, types.ReferenceView{})
-	require.ErrorIs(t, err, entrydb.ErrFuture, "no data yet, need local-unsafe")
+	require.ErrorIs(t, err, types.ErrFuture, "no data yet, need local-unsafe")
 
 	src.ExpectL1BlockRefByNumber(0, blockX, nil)
 	src.ExpectFetchReceipts(blockX.Hash, &testutils.MockBlockInfo{
@@ -118,7 +117,7 @@ func TestBackendLifetime(t *testing.T) {
 	b.chainProcessors[chainA].ProcessToHead()
 
 	_, err = b.UnsafeView(context.Background(), chainA, types.ReferenceView{})
-	require.ErrorIs(t, err, entrydb.ErrFuture, "still no data yet, need cross-unsafe")
+	require.ErrorIs(t, err, types.ErrFuture, "still no data yet, need cross-unsafe")
 
 	err = b.chainDBs.UpdateCrossUnsafe(chainA, types.BlockSeal{
 		Hash:      blockX.Hash,

op-supervisor/supervisor/backend/db/db.go

@@ -12,13 +12,10 @@ import (
 	"github.com/ethereum-optimism/optimism/op-service/eth"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/fromda"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/logs"
+	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/depset"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/types"
 )
 
-var (
-	ErrUnknownChain = errors.New("unknown chain")
-)
-
 type LogStorage interface {
 	io.Closer
 
@@ -46,13 +43,22 @@ type LogStorage interface {
 	// The block-seal of the blockNum block, that the log was included in, is returned.
 	// This seal may be fully zeroed, without error, if the block isn't fully known yet.
 	Contains(blockNum uint64, logIdx uint32, logHash common.Hash) (includedIn types.BlockSeal, err error)
+
+	// OpenBlock accumulates the ExecutingMessage events for a block and returns them
+	OpenBlock(blockNum uint64) (ref eth.BlockRef, logCount uint32, execMsgs map[uint32]*types.ExecutingMessage, err error)
 }
 
 type LocalDerivedFromStorage interface {
+	First() (derivedFrom types.BlockSeal, derived types.BlockSeal, err error)
 	Latest() (derivedFrom types.BlockSeal, derived types.BlockSeal, err error)
 	AddDerived(derivedFrom eth.BlockRef, derived eth.BlockRef) error
 	LastDerivedAt(derivedFrom eth.BlockID) (derived types.BlockSeal, err error)
 	DerivedFrom(derived eth.BlockID) (derivedFrom types.BlockSeal, err error)
+	FirstAfter(derivedFrom, derived eth.BlockID) (nextDerivedFrom, nextDerived types.BlockSeal, err error)
+	NextDerivedFrom(derivedFrom eth.BlockID) (nextDerivedFrom types.BlockSeal, err error)
+	NextDerived(derived eth.BlockID) (derivedFrom types.BlockSeal, nextDerived types.BlockSeal, err error)
+	PreviousDerivedFrom(derivedFrom eth.BlockID) (prevDerivedFrom types.BlockSeal, err error)
+	PreviousDerived(derived eth.BlockID) (prevDerived types.BlockSeal, err error)
 }
 
 var _ LocalDerivedFromStorage = (*fromda.DB)(nil)
@@ -65,7 +71,7 @@ type CrossDerivedFromStorage interface {
 var _ LogStorage = (*logs.DB)(nil)
 
 // ChainsDB is a database that stores logs and derived-from data for multiple chains.
-// it implements the ChainsStorage interface.
+// it implements the LogStorage interface, as well as several DB interfaces needed by the cross package.
 type ChainsDB struct {
 	// RW mutex:
 	// Read = chains can be read / mutated.
@@ -90,16 +96,21 @@ type ChainsDB struct {
 	// an error until it has this L1 finality to work with.
 	finalizedL1 eth.L1BlockRef
 
+	// depSet is the dependency set, used to determine what may be tracked,
+	// what is missing, and to provide it to DB users.
+	depSet depset.DependencySet
+
 	logger log.Logger
 }
 
-func NewChainsDB(l log.Logger) *ChainsDB {
+func NewChainsDB(l log.Logger, depSet depset.DependencySet) *ChainsDB {
 	return &ChainsDB{
 		logDBs:      make(map[types.ChainID]LogStorage),
 		logger:      l,
 		localDBs:    make(map[types.ChainID]LocalDerivedFromStorage),
 		crossDBs:    make(map[types.ChainID]CrossDerivedFromStorage),
 		crossUnsafe: make(map[types.ChainID]types.BlockSeal),
+		depSet:      depSet,
 	}
 }
 
@@ -168,6 +179,10 @@ func (db *ChainsDB) ResumeFromLastSealedBlock() error {
 	return nil
 }
 
+func (db *ChainsDB) DependencySet() depset.DependencySet {
+	return db.depSet
+}
+
 func (db *ChainsDB) Close() error {
 	db.mu.Lock()
 	defer db.mu.Unlock()

op-supervisor/supervisor/backend/db/fromda/db.go

@@ -3,6 +3,7 @@ package fromda
 import (
 	"cmp"
 	"fmt"
+	"io"
 	"sort"
 	"sync"
 
@@ -64,12 +65,48 @@ func (db *DB) Rewind(derivedFrom uint64) error {
 	return nil
 }
 
+// First returns the first known values, alike to Latest.
+func (db *DB) First() (derivedFrom types.BlockSeal, derived types.BlockSeal, err error) {
+	db.rwLock.RLock()
+	defer db.rwLock.RUnlock()
+	lastIndex := db.store.LastEntryIdx()
+	if lastIndex < 0 {
+		return types.BlockSeal{}, types.BlockSeal{}, types.ErrFuture
+	}
+	last, err := db.readAt(0)
+	if err != nil {
+		return types.BlockSeal{}, types.BlockSeal{}, fmt.Errorf("failed to read first derivation data: %w", err)
+	}
+	return last.derivedFrom, last.derived, nil
+}
+
+func (db *DB) PreviousDerived(derived eth.BlockID) (prevDerived types.BlockSeal, err error) {
+	db.rwLock.RLock()
+	defer db.rwLock.RUnlock()
+	// get the last time this L2 block was seen.
+	selfIndex, self, err := db.firstDerivedFrom(derived.Number)
+	if err != nil {
+		return types.BlockSeal{}, fmt.Errorf("failed to find derived %d: %w", derived.Number, err)
+	}
+	if self.derived.ID() != derived {
+		return types.BlockSeal{}, fmt.Errorf("found %s, but expected %s: %w", self.derived, derived, types.ErrConflict)
+	}
+	if selfIndex == 0 { // genesis block has a zeroed block as parent block
+		return types.BlockSeal{}, nil
+	}
+	prev, err := db.readAt(selfIndex - 1)
+	if err != nil {
+		return types.BlockSeal{}, fmt.Errorf("cannot find previous derived before %s: %w", derived, err)
+	}
+	return prev.derived, nil
+}
+
 // Latest returns the last known values:
 // derivedFrom: the L1 block that the L2 block is safe for (not necessarily the first, multiple L2 blocks may be derived from the same L1 block).
 // derived: the L2 block that was derived (not necessarily the first, the L1 block may have been empty and repeated the last safe L2 block).
 func (db *DB) Latest() (derivedFrom types.BlockSeal, derived types.BlockSeal, err error) {
-	db.rwLock.Lock()
-	defer db.rwLock.Unlock()
+	db.rwLock.RLock()
+	defer db.rwLock.RUnlock()
 	return db.latest()
 }
 
@@ -77,7 +114,7 @@ func (db *DB) Latest() (derivedFrom types.BlockSeal, derived types.BlockSeal, er
 func (db *DB) latest() (derivedFrom types.BlockSeal, derived types.BlockSeal, err error) {
 	lastIndex := db.store.LastEntryIdx()
 	if lastIndex < 0 {
-		return types.BlockSeal{}, types.BlockSeal{}, entrydb.ErrFuture
+		return types.BlockSeal{}, types.BlockSeal{}, types.ErrFuture
 	}
 	last, err := db.readAt(lastIndex)
 	if err != nil {
@@ -96,11 +133,30 @@ func (db *DB) LastDerivedAt(derivedFrom eth.BlockID) (derived types.BlockSeal, e
 	}
 	if link.derivedFrom.ID() != derivedFrom {
 		return types.BlockSeal{}, fmt.Errorf("searched for last derived-from %s but found %s: %w",
-			derivedFrom, link.derivedFrom, entrydb.ErrConflict)
+			derivedFrom, link.derivedFrom, types.ErrConflict)
 	}
 	return link.derived, nil
 }
 
+// NextDerived finds the next L2 block after derived, and what it was derived from
+func (db *DB) NextDerived(derived eth.BlockID) (derivedFrom types.BlockSeal, nextDerived types.BlockSeal, err error) {
+	db.rwLock.RLock()
+	defer db.rwLock.RUnlock()
+	// get the last time this L2 block was seen.
+	selfIndex, self, err := db.lastDerivedFrom(derived.Number)
+	if err != nil {
+		return types.BlockSeal{}, types.BlockSeal{}, fmt.Errorf("failed to find derived %d: %w", derived.Number, err)
+	}
+	if self.derived.ID() != derived {
+		return types.BlockSeal{}, types.BlockSeal{}, fmt.Errorf("found %s, but expected %s: %w", self.derived, derived, types.ErrConflict)
+	}
+	next, err := db.readAt(selfIndex + 1)
+	if err != nil {
+		return types.BlockSeal{}, types.BlockSeal{}, fmt.Errorf("cannot find next derived after %s: %w", derived, err)
+	}
+	return next.derivedFrom, next.derived, nil
+}
+
 // DerivedFrom determines where a L2 block was first derived from.
 // (a L2 block may repeat if the following L1 blocks are empty and don't produce additional L2 blocks)
 func (db *DB) DerivedFrom(derived eth.BlockID) (derivedFrom types.BlockSeal, err error) {
@@ -112,17 +168,94 @@ func (db *DB) DerivedFrom(derived eth.BlockID) (derivedFrom types.BlockSeal, err
 	}
 	if link.derived.ID() != derived {
 		return types.BlockSeal{}, fmt.Errorf("searched for first derived %s but found %s: %w",
-			derived, link.derived, entrydb.ErrConflict)
+			derived, link.derived, types.ErrConflict)
 	}
 	return link.derivedFrom, nil
 }
 
+func (db *DB) PreviousDerivedFrom(derivedFrom eth.BlockID) (prevDerivedFrom types.BlockSeal, err error) {
+	db.rwLock.RLock()
+	defer db.rwLock.RUnlock()
+	// get the last time this L1 block was seen.
+	selfIndex, self, err := db.firstDerivedAt(derivedFrom.Number)
+	if err != nil {
+		return types.BlockSeal{}, fmt.Errorf("failed to find derived %d: %w", derivedFrom.Number, err)
+	}
+	if self.derivedFrom.ID() != derivedFrom {
+		return types.BlockSeal{}, fmt.Errorf("found %s, but expected %s: %w", self.derivedFrom, derivedFrom, types.ErrConflict)
+	}
+	if selfIndex == 0 { // genesis block has a zeroed block as parent block
+		return types.BlockSeal{}, nil
+	}
+	prev, err := db.readAt(selfIndex - 1)
+	if err != nil {
+		return types.BlockSeal{}, fmt.Errorf("cannot find previous derived before %s: %w", derivedFrom, err)
+	}
+	return prev.derivedFrom, nil
+}
+
+// NextDerivedFrom finds the next L1 block after derivedFrom
+func (db *DB) NextDerivedFrom(derivedFrom eth.BlockID) (nextDerivedFrom types.BlockSeal, err error) {
+	db.rwLock.RLock()
+	defer db.rwLock.RUnlock()
+	selfIndex, self, err := db.lastDerivedAt(derivedFrom.Number)
+	if err != nil {
+		return types.BlockSeal{}, fmt.Errorf("failed to find derived-from %d: %w", derivedFrom.Number, err)
+	}
+	if self.derivedFrom.ID() != derivedFrom {
+		return types.BlockSeal{}, fmt.Errorf("found %s, but expected %s: %w", self.derivedFrom, derivedFrom, types.ErrConflict)
+	}
+	next, err := db.readAt(selfIndex + 1)
+	if err != nil {
+		return types.BlockSeal{}, fmt.Errorf("cannot find next derived-from after %s: %w", derivedFrom, err)
+	}
+	return next.derivedFrom, nil
+}
+
+// FirstAfter determines the next entry after the given pair of derivedFrom, derived.
+// Either one or both of the two entries will be an increment by 1
+func (db *DB) FirstAfter(derivedFrom, derived eth.BlockID) (nextDerivedFrom, nextDerived types.BlockSeal, err error) {
+	db.rwLock.RLock()
+	defer db.rwLock.RUnlock()
+	selfIndex, selfLink, err := db.lookup(derivedFrom.Number, derived.Number)
+	if err != nil {
+		return types.BlockSeal{}, types.BlockSeal{}, err
+	}
+	if selfLink.derivedFrom.ID() != derivedFrom {
+		return types.BlockSeal{}, types.BlockSeal{}, fmt.Errorf("DB has derived-from %s but expected %s: %w", selfLink.derivedFrom, derivedFrom, types.ErrConflict)
+	}
+	if selfLink.derived.ID() != derived {
+		return types.BlockSeal{}, types.BlockSeal{}, fmt.Errorf("DB has derived %s but expected %s: %w", selfLink.derived, derived, types.ErrConflict)
+	}
+	next, err := db.readAt(selfIndex + 1)
+	if err != nil {
+		return types.BlockSeal{}, types.BlockSeal{}, err
+	}
+	return next.derivedFrom, next.derived, nil
+}
+
+func (db *DB) lastDerivedFrom(derived uint64) (entrydb.EntryIdx, LinkEntry, error) {
+	return db.find(true, func(link LinkEntry) int {
+		return cmp.Compare(derived, link.derived.Number)
+	})
+}
+
 func (db *DB) firstDerivedFrom(derived uint64) (entrydb.EntryIdx, LinkEntry, error) {
 	return db.find(false, func(link LinkEntry) int {
 		return cmp.Compare(link.derived.Number, derived)
 	})
 }
 
+func (db *DB) lookup(derivedFrom, derived uint64) (entrydb.EntryIdx, LinkEntry, error) {
+	return db.find(false, func(link LinkEntry) int {
+		res := cmp.Compare(link.derived.Number, derived)
+		if res == 0 {
+			return cmp.Compare(link.derivedFrom.Number, derivedFrom)
+		}
+		return res
+	})
+}
+
 func (db *DB) lastDerivedAt(derivedFrom uint64) (entrydb.EntryIdx, LinkEntry, error) {
 	// Reverse: prioritize the last entry.
 	return db.find(true, func(link LinkEntry) int {
@@ -130,13 +263,19 @@ func (db *DB) lastDerivedAt(derivedFrom uint64) (entrydb.EntryIdx, LinkEntry, er
 	})
 }
 
+func (db *DB) firstDerivedAt(derivedFrom uint64) (entrydb.EntryIdx, LinkEntry, error) {
+	return db.find(false, func(link LinkEntry) int {
+		return cmp.Compare(link.derivedFrom.Number, derivedFrom)
+	})
+}
+
 // find finds the first entry for which cmpFn(link) returns 0.
 // The cmpFn entries to the left should return -1, entries to the right 1.
 // If reverse, the cmpFn should be flipped too, and the last entry for which cmpFn(link) is 0 will be found.
 func (db *DB) find(reverse bool, cmpFn func(link LinkEntry) int) (entrydb.EntryIdx, LinkEntry, error) {
 	n := db.store.Size()
 	if n == 0 {
-		return -1, LinkEntry{}, entrydb.ErrFuture
+		return -1, LinkEntry{}, types.ErrFuture
 	}
 	var searchErr error
 	// binary-search for the smallest index i for which cmp(i) >= 0
@@ -157,9 +296,9 @@ func (db *DB) find(reverse bool, cmpFn func(link LinkEntry) int) (entrydb.EntryI
 	}
 	if result == int(n) {
 		if reverse {
-			return -1, LinkEntry{}, fmt.Errorf("no entry found: %w", entrydb.ErrSkipped)
+			return -1, LinkEntry{}, fmt.Errorf("no entry found: %w", types.ErrSkipped)
 		} else {
-			return -1, LinkEntry{}, fmt.Errorf("no entry found: %w", entrydb.ErrFuture)
+			return -1, LinkEntry{}, fmt.Errorf("no entry found: %w", types.ErrFuture)
 		}
 	}
 	if reverse {
@@ -171,9 +310,9 @@ func (db *DB) find(reverse bool, cmpFn func(link LinkEntry) int) (entrydb.EntryI
 	}
 	if cmpFn(link) != 0 {
 		if reverse {
-			return -1, LinkEntry{}, fmt.Errorf("lowest entry %s is too high: %w", link, entrydb.ErrFuture)
+			return -1, LinkEntry{}, fmt.Errorf("lowest entry %s is too high: %w", link, types.ErrFuture)
 		} else {
-			return -1, LinkEntry{}, fmt.Errorf("lowest entry %s is too high: %w", link, entrydb.ErrSkipped)
+			return -1, LinkEntry{}, fmt.Errorf("lowest entry %s is too high: %w", link, types.ErrSkipped)
 		}
 	}
 	if cmpFn(link) != 0 {
@@ -187,6 +326,9 @@ func (db *DB) find(reverse bool, cmpFn func(link LinkEntry) int) (entrydb.EntryI
 func (db *DB) readAt(i entrydb.EntryIdx) (LinkEntry, error) {
 	entry, err := db.store.Read(i)
 	if err != nil {
+		if err == io.EOF {
+			return LinkEntry{}, types.ErrFuture
+		}
 		return LinkEntry{}, err
 	}
 	var out LinkEntry

op-supervisor/supervisor/backend/db/fromda/db_test.go

@@ -15,7 +15,6 @@ import (
 
 	"github.com/ethereum-optimism/optimism/op-service/eth"
 	"github.com/ethereum-optimism/optimism/op-service/testlog"
-	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/entrydb"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/types"
 )
 
@@ -74,16 +73,31 @@ func TestEmptyDB(t *testing.T) {
 		func(t *testing.T, db *DB, m *stubMetrics) {},
 		func(t *testing.T, db *DB, m *stubMetrics) {
 			_, _, err := db.Latest()
-			require.ErrorIs(t, err, entrydb.ErrFuture)
+			require.ErrorIs(t, err, types.ErrFuture)
 
-			_, _, err = db.Latest()
-			require.ErrorIs(t, err, entrydb.ErrFuture)
+			_, _, err = db.First()
+			require.ErrorIs(t, err, types.ErrFuture)
 
 			_, err = db.LastDerivedAt(eth.BlockID{})
-			require.ErrorIs(t, err, entrydb.ErrFuture)
+			require.ErrorIs(t, err, types.ErrFuture)
 
 			_, err = db.DerivedFrom(eth.BlockID{})
-			require.ErrorIs(t, err, entrydb.ErrFuture)
+			require.ErrorIs(t, err, types.ErrFuture)
+
+			_, err = db.PreviousDerived(eth.BlockID{})
+			require.ErrorIs(t, err, types.ErrFuture)
+
+			_, _, err = db.NextDerived(eth.BlockID{})
+			require.ErrorIs(t, err, types.ErrFuture)
+
+			_, err = db.PreviousDerivedFrom(eth.BlockID{})
+			require.ErrorIs(t, err, types.ErrFuture)
+
+			_, err = db.NextDerivedFrom(eth.BlockID{})
+			require.ErrorIs(t, err, types.ErrFuture)
+
+			_, _, err = db.FirstAfter(eth.BlockID{}, eth.BlockID{})
+			require.ErrorIs(t, err, types.ErrFuture)
 		})
 }
 
@@ -129,23 +143,63 @@ func TestSingleEntryDB(t *testing.T) {
 			require.Equal(t, expectedDerivedFrom, derivedFrom)
 			require.Equal(t, expectedDerived, derived)
 
+			derivedFrom, derived, err = db.First()
+			require.NoError(t, err)
+			require.Equal(t, expectedDerivedFrom, derivedFrom)
+			require.Equal(t, expectedDerived, derived)
+
 			derived, err = db.LastDerivedAt(expectedDerivedFrom.ID())
 			require.NoError(t, err)
 			require.Equal(t, expectedDerived, derived)
 
 			_, err = db.LastDerivedAt(eth.BlockID{Hash: common.Hash{0xaa}, Number: expectedDerivedFrom.Number})
-			require.ErrorIs(t, err, entrydb.ErrConflict)
+			require.ErrorIs(t, err, types.ErrConflict)
+
+			// No block known, yet, after the given block pair
+			_, _, err = db.FirstAfter(derivedFrom.ID(), derived.ID())
+			require.ErrorIs(t, err, types.ErrFuture)
+
+			// Not after a non-existent block pair
+			_, _, err = db.FirstAfter(eth.BlockID{Hash: common.Hash{0xaa}, Number: expectedDerivedFrom.Number}, expectedDerived.ID())
+			require.ErrorIs(t, err, types.ErrConflict)
+			_, _, err = db.FirstAfter(expectedDerivedFrom.ID(), eth.BlockID{Hash: common.Hash{0xaa}, Number: expectedDerived.Number})
+			require.ErrorIs(t, err, types.ErrConflict)
 
 			derivedFrom, err = db.DerivedFrom(expectedDerived.ID())
 			require.NoError(t, err)
 			require.Equal(t, expectedDerivedFrom, derivedFrom)
 
 			_, err = db.DerivedFrom(eth.BlockID{Hash: common.Hash{0xbb}, Number: expectedDerived.Number})
-			require.ErrorIs(t, err, entrydb.ErrConflict)
+			require.ErrorIs(t, err, types.ErrConflict)
+
+			prev, err := db.PreviousDerived(expectedDerived.ID())
+			require.NoError(t, err)
+			require.Equal(t, types.BlockSeal{}, prev, "zeroed seal before first entry")
+
+			_, _, err = db.NextDerived(expectedDerived.ID())
+			require.ErrorIs(t, err, types.ErrFuture)
+
+			// if 1 was the first inserted entry, then we skipped 0
+			_, _, err = db.NextDerived(mockL2(0).ID())
+			require.ErrorIs(t, err, types.ErrSkipped)
+
+			prev, err = db.PreviousDerivedFrom(expectedDerivedFrom.ID())
+			require.NoError(t, err)
+			require.Equal(t, types.BlockSeal{}, prev, "zeroed seal before first entry")
+
+			_, err = db.NextDerivedFrom(expectedDerivedFrom.ID())
+			require.ErrorIs(t, err, types.ErrFuture)
+
+			// if 1 was the first inserted entry, then we skipped 0
+			_, err = db.NextDerivedFrom(mockL1(0).ID())
+			require.ErrorIs(t, err, types.ErrSkipped)
+
+			_, _, err = db.FirstAfter(expectedDerivedFrom.ID(), expectedDerived.ID())
+			require.ErrorIs(t, err, types.ErrFuture)
 		})
 }
 
-func TestTwoEntryDB(t *testing.T) {
+func TestThreeEntryDB(t *testing.T) {
 	l1Block0 := mockL1(0)
 	l1Block1 := mockL1(1)
 	l1Block2 := mockL1(2)
@@ -165,19 +219,24 @@ func TestTwoEntryDB(t *testing.T) {
 		require.Equal(t, l1Block2, derivedFrom)
 		require.Equal(t, l2Block2, derived)
 
+		derivedFrom, derived, err = db.First()
+		require.NoError(t, err)
+		require.Equal(t, l1Block0, derivedFrom)
+		require.Equal(t, l2Block0, derived)
+
 		derived, err = db.LastDerivedAt(l1Block2.ID())
 		require.NoError(t, err)
 		require.Equal(t, l2Block2, derived)
 
 		_, err = db.LastDerivedAt(eth.BlockID{Hash: common.Hash{0xaa}, Number: l1Block2.Number})
-		require.ErrorIs(t, err, entrydb.ErrConflict)
+		require.ErrorIs(t, err, types.ErrConflict)
 
 		derivedFrom, err = db.DerivedFrom(l2Block2.ID())
 		require.NoError(t, err)
 		require.Equal(t, l1Block2, derivedFrom)
 
 		_, err = db.DerivedFrom(eth.BlockID{Hash: common.Hash{0xbb}, Number: l2Block2.Number})
-		require.ErrorIs(t, err, entrydb.ErrConflict)
+		require.ErrorIs(t, err, types.ErrConflict)
 
 		derived, err = db.LastDerivedAt(l1Block1.ID())
 		require.NoError(t, err)
@@ -194,6 +253,67 @@ func TestTwoEntryDB(t *testing.T) {
 		derivedFrom, err = db.DerivedFrom(l2Block0.ID())
 		require.NoError(t, err)
 		require.Equal(t, l1Block0, derivedFrom)
+
+		derived, err = db.PreviousDerived(l2Block0.ID())
+		require.NoError(t, err)
+		require.Equal(t, types.BlockSeal{}, derived)
+
+		derived, err = db.PreviousDerived(l2Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block0, derived)
+
+		derived, err = db.PreviousDerived(l2Block2.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block1, derived)
+
+		derivedFrom, derived, err = db.NextDerived(l2Block0.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block1, derived)
+		require.Equal(t, l1Block1, derivedFrom)
+
+		derivedFrom, derived, err = db.NextDerived(l2Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block2, derived)
+		require.Equal(t, l1Block2, derivedFrom)
+
+		_, _, err = db.NextDerived(l2Block2.ID())
+		require.ErrorIs(t, err, types.ErrFuture)
+
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block0.ID())
+		require.NoError(t, err)
+		require.Equal(t, types.BlockSeal{}, derivedFrom)
+
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block0, derivedFrom)
+
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block2.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+
+		derivedFrom, err = db.NextDerivedFrom(l1Block0.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+
+		derivedFrom, err = db.NextDerivedFrom(l1Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block2, derivedFrom)
+
+		_, err = db.NextDerivedFrom(l1Block2.ID())
+		require.ErrorIs(t, err, types.ErrFuture)
+
+		_, _, err = db.FirstAfter(l1Block2.ID(), l2Block2.ID())
+		require.ErrorIs(t, err, types.ErrFuture)
+
+		derivedFrom, derived, err = db.FirstAfter(l1Block0.ID(), l2Block0.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		require.Equal(t, l2Block1, derived)
+
+		derivedFrom, derived, err = db.FirstAfter(l1Block1.ID(), l2Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block2, derivedFrom)
+		require.Equal(t, l2Block2, derived)
 	})
 }
 
@@ -249,6 +369,65 @@ func TestFastL2Batcher(t *testing.T) {
 		require.NoError(t, err)
 		require.Equal(t, l2Block4, derived)
 
+		derived, err = db.PreviousDerived(l2Block5.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block4, derived)
+		derived, err = db.PreviousDerived(l2Block4.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block3, derived)
+		derived, err = db.PreviousDerived(l2Block3.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block2, derived)
+		derived, err = db.PreviousDerived(l2Block2.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block1, derived)
+		derived, err = db.PreviousDerived(l2Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block0, derived)
+
+		derivedFrom, derived, err = db.NextDerived(l2Block0.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		require.Equal(t, l2Block1, derived)
+		derivedFrom, derived, err = db.NextDerived(l2Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		require.Equal(t, l2Block2, derived)
+		derivedFrom, derived, err = db.NextDerived(l2Block2.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		require.Equal(t, l2Block3, derived)
+		derivedFrom, derived, err = db.NextDerived(l2Block3.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		require.Equal(t, l2Block4, derived)
+		derivedFrom, derived, err = db.NextDerived(l2Block4.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block2, derivedFrom) // derived from later L1 block
+		require.Equal(t, l2Block5, derived)
+		_, _, err = db.NextDerived(l2Block5.ID())
+		require.ErrorIs(t, err, types.ErrFuture)
+
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block2.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block0, derivedFrom)
+
+		derivedFrom, err = db.NextDerivedFrom(l1Block0.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		derivedFrom, err = db.NextDerivedFrom(l1Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block2, derivedFrom)
+		_, err = db.NextDerivedFrom(l1Block2.ID())
+		require.ErrorIs(t, err, types.ErrFuture)
+
+		derivedFrom, derived, err = db.FirstAfter(l1Block1.ID(), l2Block2.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom) // no increment in L1 yet, the next after is L2 block 3
+		require.Equal(t, l2Block3, derived)
 	})
 }
 
@@ -299,6 +478,60 @@ func TestSlowL2Batcher(t *testing.T) {
 		derivedFrom, err = db.DerivedFrom(l2Block1.ID())
 		require.NoError(t, err)
 		require.Equal(t, l1Block1, derivedFrom)
+
+		derived, err = db.PreviousDerived(l2Block2.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block1, derived)
+		derived, err = db.PreviousDerived(l2Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l2Block0, derived)
+
+		derivedFrom, derived, err = db.NextDerived(l2Block0.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		require.Equal(t, l2Block1, derived)
+		derivedFrom, derived, err = db.NextDerived(l2Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block5, derivedFrom)
+		require.Equal(t, l2Block2, derived)
+		_, _, err = db.NextDerived(l2Block2.ID())
+		require.ErrorIs(t, err, types.ErrFuture)
+
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block5.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block4, derivedFrom)
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block4.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block3, derivedFrom)
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block3.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block2, derivedFrom)
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block2.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		derivedFrom, err = db.PreviousDerivedFrom(l1Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block0, derivedFrom)
+
+		derivedFrom, err = db.NextDerivedFrom(l1Block0.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block1, derivedFrom)
+		derivedFrom, err = db.NextDerivedFrom(l1Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block2, derivedFrom)
+		derivedFrom, err = db.NextDerivedFrom(l1Block2.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block3, derivedFrom)
+		derivedFrom, err = db.NextDerivedFrom(l1Block4.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block5, derivedFrom)
+		_, err = db.NextDerivedFrom(l1Block5.ID())
+		require.ErrorIs(t, err, types.ErrFuture)
+
+		derivedFrom, derived, err = db.FirstAfter(l1Block2.ID(), l2Block1.ID())
+		require.NoError(t, err)
+		require.Equal(t, l1Block3, derivedFrom)
+		require.Equal(t, l2Block1, derived) // no increment in L2 yet, the next after is L1 block 3
 	})
 }
 
@@ -378,17 +611,17 @@ func testManyEntryDB(t *testing.T, offsetL1 uint64, offsetL2 uint64) {
 		// if not started at genesis, try to read older data, assert it's unavailable.
 		if offsetL1 > 0 {
 			_, err := db.LastDerivedAt(mockL1(0).ID())
-			require.ErrorIs(t, err, entrydb.ErrSkipped)
+			require.ErrorIs(t, err, types.ErrSkipped)
 
 			_, err = db.LastDerivedAt(mockL1(offsetL1 - 1).ID())
-			require.ErrorIs(t, err, entrydb.ErrSkipped)
+			require.ErrorIs(t, err, types.ErrSkipped)
 		}
 		if offsetL2 > 0 {
 			_, err := db.DerivedFrom(mockL2(0).ID())
-			require.ErrorIs(t, err, entrydb.ErrSkipped)
+			require.ErrorIs(t, err, types.ErrSkipped)
 
 			_, err = db.DerivedFrom(mockL2(offsetL2 - 1).ID())
-			require.ErrorIs(t, err, entrydb.ErrSkipped)
+			require.ErrorIs(t, err, types.ErrSkipped)
 		}
 	})
 }
@@ -425,7 +658,7 @@ func TestRewind(t *testing.T) {
 		require.Equal(t, l2Block2, derived)
 
 		// Rewind to the future
-		require.ErrorIs(t, db.Rewind(6), entrydb.ErrFuture)
+		require.ErrorIs(t, db.Rewind(6), types.ErrFuture)
 
 		// Rewind to the exact block we're at
 		require.NoError(t, db.Rewind(l1Block5.Number))

op-supervisor/supervisor/backend/db/fromda/entry.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"io"
 
-	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/entrydb"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/types"
 )
 
@@ -57,10 +56,10 @@ func (d LinkEntry) String() string {
 
 func (d *LinkEntry) decode(e Entry) error {
 	if e.Type() != DerivedFromV0 {
-		return fmt.Errorf("%w: unexpected entry type: %s", entrydb.ErrDataCorruption, e.Type())
+		return fmt.Errorf("%w: unexpected entry type: %s", types.ErrDataCorruption, e.Type())
 	}
 	if [3]byte(e[1:4]) != ([3]byte{}) {
-		return fmt.Errorf("%w: expected empty data, to pad entry size to round number: %x", entrydb.ErrDataCorruption, e[1:4])
+		return fmt.Errorf("%w: expected empty data, to pad entry size to round number: %x", types.ErrDataCorruption, e[1:4])
 	}
 	offset := 4
 	d.derivedFrom.Number = binary.BigEndian.Uint64(e[offset : offset+8])

op-supervisor/supervisor/backend/db/fromda/update.go

@@ -4,7 +4,6 @@ import (
 	"fmt"
 
 	"github.com/ethereum-optimism/optimism/op-service/eth"
-	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/entrydb"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/types"
 )
 
@@ -60,19 +59,19 @@ func (db *DB) AddDerived(derivedFrom eth.BlockRef, derived eth.BlockRef) error {
 		// I.e. we encountered an empty L1 block, and the same L2 block continues to be the last block that was derived from it.
 		if lastDerived.Hash != derived.Hash {
 			return fmt.Errorf("derived block %s conflicts with known derived block %s at same height: %w",
-				derived, lastDerived, entrydb.ErrConflict)
+				derived, lastDerived, types.ErrConflict)
 		}
 	} else if lastDerived.Number+1 == derived.Number {
 		if lastDerived.Hash != derived.ParentHash {
 			return fmt.Errorf("derived block %s (parent %s) does not build on %s: %w",
-				derived, derived.ParentHash, lastDerived, entrydb.ErrConflict)
+				derived, derived.ParentHash, lastDerived, types.ErrConflict)
 		}
 	} else if lastDerived.Number+1 < derived.Number {
 		return fmt.Errorf("derived block %s (parent: %s) is too new, expected to build on top of %s: %w",
-			derived, derived.ParentHash, lastDerived, entrydb.ErrOutOfOrder)
+			derived, derived.ParentHash, lastDerived, types.ErrOutOfOrder)
 	} else {
 		return fmt.Errorf("derived block %s is older than current derived block %s: %w",
-			derived, lastDerived, entrydb.ErrOutOfOrder)
+			derived, lastDerived, types.ErrOutOfOrder)
 	}
 
 	// Check derived-from relation: multiple L2 blocks may be derived from the same L1 block. But everything in sequence.
@@ -80,22 +79,22 @@ func (db *DB) AddDerived(derivedFrom eth.BlockRef, derived eth.BlockRef) error {
 		// Same block height? Then it must be the same block.
 		if lastDerivedFrom.Hash != derivedFrom.Hash {
 			return fmt.Errorf("cannot add block %s as derived from %s, expected to be derived from %s at this block height: %w",
-				derived, derivedFrom, lastDerivedFrom, entrydb.ErrConflict)
+				derived, derivedFrom, lastDerivedFrom, types.ErrConflict)
 		}
 	} else if lastDerivedFrom.Number+1 == derivedFrom.Number {
 		// parent hash check
 		if lastDerivedFrom.Hash != derivedFrom.ParentHash {
 			return fmt.Errorf("cannot add block %s as derived from %s (parent %s) derived on top of %s: %w",
-				derived, derivedFrom, derivedFrom.ParentHash, lastDerivedFrom, entrydb.ErrConflict)
+				derived, derivedFrom, derivedFrom.ParentHash, lastDerivedFrom, types.ErrConflict)
 		}
 	} else if lastDerivedFrom.Number+1 < derivedFrom.Number {
 		// adding block that is derived from something too far into the future
 		return fmt.Errorf("cannot add block %s as derived from %s, still deriving from %s: %w",
-			derived, derivedFrom, lastDerivedFrom, entrydb.ErrOutOfOrder)
+			derived, derivedFrom, lastDerivedFrom, types.ErrOutOfOrder)
 	} else {
 		// adding block that is derived from something too old
 		return fmt.Errorf("cannot add block %s as derived from %s, deriving already at %s: %w",
-			derived, derivedFrom, lastDerivedFrom, entrydb.ErrOutOfOrder)
+			derived, derivedFrom, lastDerivedFrom, types.ErrOutOfOrder)
 	}
 
 	link := LinkEntry{

op-supervisor/supervisor/backend/db/fromda/update_test.go

@@ -7,7 +7,6 @@ import (
 
 	"github.com/ethereum/go-ethereum/common"
 
-	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/entrydb"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/types"
 )
 
@@ -42,14 +41,14 @@ func TestBadUpdates(t *testing.T) {
 		{
 			name: "add on old derivedFrom",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(bDerivedFrom, aDerivedFrom.Hash), toRef(dDerived, cDerived.Hash)), entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, db.AddDerived(toRef(bDerivedFrom, aDerivedFrom.Hash), toRef(dDerived, cDerived.Hash)), types.ErrOutOfOrder)
 			},
 			assertFn: noChange,
 		},
 		{
 			name: "repeat parent derivedFrom",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(cDerivedFrom, bDerivedFrom.Hash), toRef(dDerived, cDerived.Hash)), entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, db.AddDerived(toRef(cDerivedFrom, bDerivedFrom.Hash), toRef(dDerived, cDerived.Hash)), types.ErrOutOfOrder)
 			},
 			assertFn: noChange,
 		},
@@ -60,14 +59,14 @@ func TestBadUpdates(t *testing.T) {
 					Hash:      common.Hash{0xba, 0xd},
 					Number:    dDerivedFrom.Number,
 					Timestamp: dDerivedFrom.Timestamp,
-				}, cDerivedFrom.Hash), toRef(eDerived, dDerived.Hash)), entrydb.ErrConflict)
+				}, cDerivedFrom.Hash), toRef(eDerived, dDerived.Hash)), types.ErrConflict)
 			},
 			assertFn: noChange,
 		},
 		{
 			name: "DerivedFrom with conflicting parent root, same L1 height, new L2: accepted, L1 parent-hash is used only on L1 increments.",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.NoError(t, db.AddDerived(toRef(dDerivedFrom, common.Hash{0x42}), toRef(eDerived, dDerived.Hash)), entrydb.ErrConflict)
+				require.NoError(t, db.AddDerived(toRef(dDerivedFrom, common.Hash{0x42}), toRef(eDerived, dDerived.Hash)), types.ErrConflict)
 			},
 			assertFn: func(t *testing.T, db *DB, m *stubMetrics) {
 				derivedFrom, derived, err := db.Latest()
@@ -79,28 +78,28 @@ func TestBadUpdates(t *testing.T) {
 		{
 			name: "Conflicting derivedFrom parent root, new L1 height, same L2",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(eDerivedFrom, common.Hash{0x42}), toRef(dDerived, cDerived.Hash)), entrydb.ErrConflict)
+				require.ErrorIs(t, db.AddDerived(toRef(eDerivedFrom, common.Hash{0x42}), toRef(dDerived, cDerived.Hash)), types.ErrConflict)
 			},
 			assertFn: noChange,
 		},
 		{
 			name: "add on too new derivedFrom (even if parent-hash looks correct)",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(fDerivedFrom, dDerivedFrom.Hash), toRef(eDerived, dDerived.Hash)), entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, db.AddDerived(toRef(fDerivedFrom, dDerivedFrom.Hash), toRef(eDerived, dDerived.Hash)), types.ErrOutOfOrder)
 			},
 			assertFn: noChange,
 		},
 		{
 			name: "add on old derivedFrom (even if parent-hash looks correct)",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(cDerivedFrom, bDerivedFrom.Hash), toRef(cDerived, dDerived.Hash)), entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, db.AddDerived(toRef(cDerivedFrom, bDerivedFrom.Hash), toRef(cDerived, dDerived.Hash)), types.ErrOutOfOrder)
 			},
 			assertFn: noChange,
 		},
 		{
 			name: "add on even older derivedFrom",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(bDerivedFrom, aDerivedFrom.Hash), toRef(dDerived, cDerived.Hash)), entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, db.AddDerived(toRef(bDerivedFrom, aDerivedFrom.Hash), toRef(dDerived, cDerived.Hash)), types.ErrOutOfOrder)
 			},
 			assertFn: noChange,
 		},
@@ -111,14 +110,14 @@ func TestBadUpdates(t *testing.T) {
 					Hash:      common.Hash{0x42},
 					Number:    dDerived.Number,
 					Timestamp: dDerived.Timestamp,
-				}, cDerived.Hash)), entrydb.ErrConflict)
+				}, cDerived.Hash)), types.ErrConflict)
 			},
 			assertFn: noChange,
 		},
 		{
 			name: "add derived with conflicting parent hash, new L1 height, same L2 height: accepted, L2 parent-hash is only checked on L2 increments.",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.NoError(t, db.AddDerived(toRef(eDerivedFrom, dDerivedFrom.Hash), toRef(dDerived, common.Hash{0x42})), entrydb.ErrConflict)
+				require.NoError(t, db.AddDerived(toRef(eDerivedFrom, dDerivedFrom.Hash), toRef(dDerived, common.Hash{0x42})), types.ErrConflict)
 			},
 			assertFn: func(t *testing.T, db *DB, m *stubMetrics) {
 				derivedFrom, derived, err := db.Latest()
@@ -130,28 +129,28 @@ func TestBadUpdates(t *testing.T) {
 		{
 			name: "add derived with conflicting parent hash, same L1 height, new L2 height",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(eDerived, common.Hash{0x42})), entrydb.ErrConflict)
+				require.ErrorIs(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(eDerived, common.Hash{0x42})), types.ErrConflict)
 			},
 			assertFn: noChange,
 		},
 		{
 			name: "add on too new derived (even if parent-hash looks correct)",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(fDerived, dDerived.Hash)), entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(fDerived, dDerived.Hash)), types.ErrOutOfOrder)
 			},
 			assertFn: noChange,
 		},
 		{
 			name: "add on old derived (even if parent-hash looks correct)",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(cDerived, bDerived.Hash)), entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(cDerived, bDerived.Hash)), types.ErrOutOfOrder)
 			},
 			assertFn: noChange,
 		},
 		{
 			name: "add on even older derived",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(bDerived, aDerived.Hash)), entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(bDerived, aDerived.Hash)), types.ErrOutOfOrder)
 			},
 			assertFn: noChange,
 		},
@@ -159,7 +158,7 @@ func TestBadUpdates(t *testing.T) {
 			name: "repeat self, silent no-op",
 			setupFn: func(t *testing.T, db *DB, m *stubMetrics) {
 				pre := m.DBDerivedEntryCount
-				require.NoError(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(dDerived, cDerived.Hash)), entrydb.ErrOutOfOrder)
+				require.NoError(t, db.AddDerived(toRef(dDerivedFrom, cDerivedFrom.Hash), toRef(dDerived, cDerived.Hash)), types.ErrOutOfOrder)
 				require.Equal(t, pre, m.DBDerivedEntryCount)
 			},
 			assertFn: noChange,

op-supervisor/supervisor/backend/db/logs/db.go

@@ -139,8 +139,8 @@ func (db *DB) FindSealedBlock(number uint64) (seal types.BlockSeal, err error) {
 	db.rwLock.RLock()
 	defer db.rwLock.RUnlock()
 	iter, err := db.newIteratorAt(number, 0)
-	if errors.Is(err, entrydb.ErrFuture) {
-		return types.BlockSeal{}, fmt.Errorf("block %d is not known yet: %w", number, entrydb.ErrFuture)
+	if errors.Is(err, types.ErrFuture) {
+		return types.BlockSeal{}, fmt.Errorf("block %d is not known yet: %w", number, types.ErrFuture)
 	} else if err != nil {
 		return types.BlockSeal{}, fmt.Errorf("failed to find sealed block %d: %w", number, err)
 	}
@@ -162,6 +162,89 @@ func (db *DB) FindSealedBlock(number uint64) (seal types.BlockSeal, err error) {
 	}, nil
 }
 
+// StartingBlock returns the first block seal in the DB, if any.
+func (db *DB) StartingBlock() (seal types.BlockSeal, err error) {
+	db.rwLock.RLock()
+	defer db.rwLock.RUnlock()
+	iter := db.newIterator(0)
+	if err := iter.NextBlock(); err != nil {
+		return types.BlockSeal{}, err
+	}
+	h, n, _ := iter.SealedBlock()
+	t, _ := iter.SealedTimestamp()
+	return types.BlockSeal{
+		Hash:      h,
+		Number:    n,
+		Timestamp: t,
+	}, err
+}
+
+// OpenBlock returns the Executing Messages for the block at the given number.
+// it returns identification of the block, the parent block, and the executing messages.
+func (db *DB) OpenBlock(blockNum uint64) (ref eth.BlockRef, logCount uint32, execMsgs map[uint32]*types.ExecutingMessage, retErr error) {
+	db.rwLock.RLock()
+	defer db.rwLock.RUnlock()
+
+	if blockNum == 0 {
+		seal, err := db.StartingBlock()
+		if err != nil {
+			retErr = err
+			return
+		}
+		ref = eth.BlockRef{
+			Hash:       seal.Hash,
+			Number:     seal.Number,
+			ParentHash: common.Hash{},
+			Time:       seal.Timestamp,
+		}
+		logCount = 0
+		execMsgs = nil
+		return
+	}
+
+	// start at the first log (if any) after the block-seal of the parent block
+	blockIter, err := db.newIteratorAt(blockNum-1, 0)
+	if err != nil {
+		retErr = err
+		return
+	}
+	// register the parent block
+	parentHash, _, ok := blockIter.SealedBlock()
+	if ok {
+		ref.ParentHash = parentHash
+	}
+	// walk to the end of the block, and remember what we see in the block.
+	logCount = 0
+	execMsgs = make(map[uint32]*types.ExecutingMessage, 0)
+	retErr = blockIter.TraverseConditional(func(state IteratorState) error {
+		_, logIndex, ok := state.InitMessage()
+		if ok {
+			logCount = logIndex + 1
+		}
+		if m := state.ExecMessage(); m != nil {
+			execMsgs[logIndex] = m
+		}
+		h, n, ok := state.SealedBlock()
+		if !ok {
+			return nil
+		}
+		if n == blockNum {
+			ref.Number = n
+			ref.Hash = h
+			ref.Time, _ = state.SealedTimestamp()
+			return types.ErrStop
+		}
+		if n > blockNum {
+			return fmt.Errorf("expected to run into block %d, but did not find it, found %d: %w", blockNum, n, types.ErrDataCorruption)
+		}
+		return nil
+	})
+	if errors.Is(retErr, types.ErrStop) {
+		retErr = nil
+	}
+	return
+}
+
 // LatestSealedBlockNum returns the block number of the block that was last sealed,
 // or ok=false if there is no sealed block (i.e. empty DB)
 func (db *DB) LatestSealedBlockNum() (n uint64, ok bool) {
@@ -213,21 +296,21 @@ func (db *DB) Contains(blockNum uint64, logIdx uint32, logHash common.Hash) (typ
 			return nil
 		}
 		if n == blockNum {
-			return entrydb.ErrStop
+			return types.ErrStop
 		}
 		if n > blockNum {
-			return entrydb.ErrDataCorruption
+			return types.ErrDataCorruption
 		}
 		return nil
 	})
 	if err == nil {
 		panic("expected iterator to stop with error")
 	}
-	if errors.Is(err, entrydb.ErrFuture) {
+	if errors.Is(err, types.ErrFuture) {
 		// Log is known, but as part of an unsealed block.
 		return types.BlockSeal{}, nil
 	}
-	if errors.Is(err, entrydb.ErrStop) {
+	if errors.Is(err, types.ErrStop) {
 		h, n, _ := iter.SealedBlock()
 		timestamp, _ := iter.SealedTimestamp()
 		return types.BlockSeal{
@@ -241,12 +324,12 @@ func (db *DB) Contains(blockNum uint64, logIdx uint32, logHash common.Hash) (typ
 
 func (db *DB) findLogInfo(blockNum uint64, logIdx uint32) (common.Hash, Iterator, error) {
 	if blockNum == 0 {
-		return common.Hash{}, nil, entrydb.ErrConflict // no logs in block 0
+		return common.Hash{}, nil, types.ErrConflict // no logs in block 0
 	}
 	// blockNum-1, such that we find a log that came after the parent num-1 was sealed.
 	// logIdx, such that all entries before logIdx can be skipped, but logIdx itself is still readable.
 	iter, err := db.newIteratorAt(blockNum-1, logIdx)
-	if errors.Is(err, entrydb.ErrFuture) {
+	if errors.Is(err, types.ErrFuture) {
 		db.log.Trace("Could not find log yet", "blockNum", blockNum, "logIdx", logIdx)
 		return common.Hash{}, nil, err
 	} else if err != nil {
@@ -261,7 +344,7 @@ func (db *DB) findLogInfo(blockNum uint64, logIdx uint32) (common.Hash, Iterator
 	} else if x < blockNum-1 {
 		panic(fmt.Errorf("bug in newIteratorAt, expected to have found parent block %d but got %d", blockNum-1, x))
 	} else if x > blockNum-1 {
-		return common.Hash{}, nil, fmt.Errorf("log does not exist, found next block already: %w", entrydb.ErrConflict)
+		return common.Hash{}, nil, fmt.Errorf("log does not exist, found next block already: %w", types.ErrConflict)
 	}
 	logHash, x, ok := iter.InitMessage()
 	if !ok {
@@ -282,7 +365,7 @@ func (db *DB) newIteratorAt(blockNum uint64, logIndex uint32) (*iterator, error)
 	searchCheckpointIndex, err := db.searchCheckpoint(blockNum, logIndex)
 	if errors.Is(err, io.EOF) {
 		// Did not find a checkpoint to start reading from so the log cannot be present.
-		return nil, entrydb.ErrFuture
+		return nil, types.ErrFuture
 	} else if err != nil {
 		return nil, err
 	}
@@ -298,9 +381,9 @@ func (db *DB) newIteratorAt(blockNum uint64, logIndex uint32) (*iterator, error)
 		if _, n, ok := iter.SealedBlock(); ok && n == blockNum { // we may already have it exactly
 			break
 		}
-		if err := iter.NextBlock(); errors.Is(err, entrydb.ErrFuture) {
+		if err := iter.NextBlock(); errors.Is(err, types.ErrFuture) {
 			db.log.Trace("ran out of data, could not find block", "nextIndex", iter.NextIndex(), "target", blockNum)
-			return nil, entrydb.ErrFuture
+			return nil, types.ErrFuture
 		} else if err != nil {
 			db.log.Error("failed to read next block", "nextIndex", iter.NextIndex(), "target", blockNum, "err", err)
 			return nil, err
@@ -314,7 +397,7 @@ func (db *DB) newIteratorAt(blockNum uint64, logIndex uint32) (*iterator, error)
 			continue
 		}
 		if num != blockNum { // block does not contain
-			return nil, fmt.Errorf("looking for %d, but already at %d: %w", blockNum, num, entrydb.ErrConflict)
+			return nil, fmt.Errorf("looking for %d, but already at %d: %w", blockNum, num, types.ErrConflict)
 		}
 		break
 	}
@@ -323,7 +406,7 @@ func (db *DB) newIteratorAt(blockNum uint64, logIndex uint32) (*iterator, error)
 	// so two logs before quiting (and not 3 to then quit after).
 	for iter.current.logsSince < logIndex {
 		if err := iter.NextInitMsg(); err == io.EOF {
-			return nil, entrydb.ErrFuture
+			return nil, types.ErrFuture
 		} else if err != nil {
 			return nil, err
 		}
@@ -333,7 +416,7 @@ func (db *DB) newIteratorAt(blockNum uint64, logIndex uint32) (*iterator, error)
 		}
 		if num > blockNum {
 			// we overshot, the block did not contain as many seen log events as requested
-			return nil, entrydb.ErrConflict
+			return nil, types.ErrConflict
 		}
 		_, idx, ok := iter.InitMessage()
 		if !ok {
@@ -367,7 +450,7 @@ func (db *DB) newIterator(index entrydb.EntryIdx) *iterator {
 // Returns the index of the searchCheckpoint to begin reading from or an error.
 func (db *DB) searchCheckpoint(sealedBlockNum uint64, logsSince uint32) (entrydb.EntryIdx, error) {
 	if db.lastEntryContext.nextEntryIndex == 0 {
-		return 0, entrydb.ErrFuture // empty DB, everything is in the future
+		return 0, types.ErrFuture // empty DB, everything is in the future
 	}
 	n := (db.lastEntryIdx() / searchCheckpointFrequency) + 1
 	// Define: x is the array of known checkpoints
@@ -404,7 +487,7 @@ func (db *DB) searchCheckpoint(sealedBlockNum uint64, logsSince uint32) (entrydb
 	if checkpoint.blockNum > sealedBlockNum ||
 		(checkpoint.blockNum == sealedBlockNum && checkpoint.logsSince > logsSince) {
 		return 0, fmt.Errorf("missing data, earliest search checkpoint is %d with %d logs, cannot find something before or at %d with %d logs: %w",
-			checkpoint.blockNum, checkpoint.logsSince, sealedBlockNum, logsSince, entrydb.ErrSkipped)
+			checkpoint.blockNum, checkpoint.logsSince, sealedBlockNum, logsSince, types.ErrSkipped)
 	}
 	return result, nil
 }

op-supervisor/supervisor/backend/db/logs/db_test.go

@@ -89,8 +89,8 @@ func TestLatestSealedBlockNum(t *testing.T) {
 				require.False(t, ok, "empty db expected")
 				require.Zero(t, n)
 				idx, err := db.searchCheckpoint(0, 0)
-				require.ErrorIs(t, err, entrydb.ErrFuture, "no checkpoint in empty db")
-				require.ErrorIs(t, err, entrydb.ErrFuture, "no checkpoint in empty db")
+				require.ErrorIs(t, err, types.ErrFuture, "no checkpoint in empty db")
+				require.ErrorIs(t, err, types.ErrFuture, "no checkpoint in empty db")
 				require.Zero(t, idx)
 			})
 	})
@@ -107,6 +107,14 @@ func TestLatestSealedBlockNum(t *testing.T) {
 				idx, err := db.searchCheckpoint(0, 0)
 				require.NoError(t, err)
 				require.Zero(t, idx, "genesis block as checkpoint 0")
+
+				// Test if we can open the genesis block
+				ref, logCount, execMsgs, err := db.OpenBlock(0)
+				require.NoError(t, err)
+				require.Empty(t, execMsgs)
+				require.Zero(t, logCount)
+				require.Equal(t, genesis, ref.ID())
+				require.Equal(t, uint64(5000), ref.Time)
 			})
 	})
 	t.Run("Later genesis case", func(t *testing.T) {
@@ -123,8 +131,16 @@ func TestLatestSealedBlockNum(t *testing.T) {
 				require.NoError(t, err)
 				require.Zero(t, idx, "anchor block as checkpoint 0")
 				_, err = db.searchCheckpoint(0, 0)
-				require.ErrorIs(t, err, entrydb.ErrSkipped, "no checkpoint before genesis")
-				require.ErrorIs(t, err, entrydb.ErrSkipped, "no checkpoint before genesis")
+				require.ErrorIs(t, err, types.ErrSkipped, "no checkpoint before genesis")
+				require.ErrorIs(t, err, types.ErrSkipped, "no checkpoint before genesis")
+
+				// Test if we can open the starting block
+				_, _, _, err = db.OpenBlock(genesis.Number)
+				// no data to find the parent-hash.
+				// OpenBlock cannot start from the first entry, when not 0.
+				// To start at a non-zero block, index the seal of the parent-block block before it,
+				// and then that parent-hash will be available.
+				require.ErrorIs(t, err, types.ErrSkipped)
 			})
 	})
 	t.Run("Block 1 case", func(t *testing.T) {
@@ -142,6 +158,22 @@ func TestLatestSealedBlockNum(t *testing.T) {
 				idx, err := db.searchCheckpoint(block1.Number, 0)
 				require.NoError(t, err)
 				require.Equal(t, entrydb.EntryIdx(0), idx, "checkpoint 0 still for block 1")
+
+				// Test if we can open the starting block
+				ref, logCount, execMsgs, err := db.OpenBlock(genesis.Number)
+				require.NoError(t, err)
+				require.Empty(t, execMsgs)
+				require.Zero(t, logCount)
+				require.Equal(t, genesis, ref.ID())
+				require.Equal(t, uint64(5000), ref.Time)
+
+				// Test if we can open the first block after genesis
+				ref, logCount, execMsgs, err = db.OpenBlock(block1.Number)
+				require.NoError(t, err)
+				require.Empty(t, execMsgs)
+				require.Zero(t, logCount)
+				require.Equal(t, block1, ref.ID())
+				require.Equal(t, uint64(5001), ref.Time)
 			})
 	})
 	t.Run("Using checkpoint case", func(t *testing.T) {
@@ -151,7 +183,7 @@ func TestLatestSealedBlockNum(t *testing.T) {
 				require.NoError(t, db.SealBlock(common.Hash{}, genesis, 5000), "seal genesis")
 				for i := 1; i <= 260; i++ {
 					id := eth.BlockID{Hash: createHash(i), Number: uint64(i)}
-					require.NoError(t, db.SealBlock(createHash(i-1), id, 5001), "seal block %d", i)
+					require.NoError(t, db.SealBlock(createHash(i-1), id, 5000+uint64(i)), "seal block %d", i)
 				}
 			},
 			func(t *testing.T, db *DB, m *stubMetrics) {
@@ -164,6 +196,14 @@ func TestLatestSealedBlockNum(t *testing.T) {
 				// It costs 2 entries per block, so if we add more than 1 checkpoint worth of blocks,
 				// then we get to checkpoint 2
 				require.Equal(t, entrydb.EntryIdx(searchCheckpointFrequency*2), idx, "checkpoint 1 reached")
+
+				// Test if we can open the block
+				ref, logCount, execMsgs, err := db.OpenBlock(n)
+				require.NoError(t, err)
+				require.Empty(t, execMsgs)
+				require.Zero(t, logCount)
+				require.Equal(t, createHash(int(n)), ref.Hash)
+				require.Equal(t, uint64(5000)+n, ref.Time)
 			})
 	})
 }
@@ -176,8 +216,8 @@ func TestAddLog(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				genesis := eth.BlockID{Hash: createHash(15), Number: 0}
 				err := db.AddLog(createHash(1), genesis, 0, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
 			})
 	})
 
@@ -192,6 +232,12 @@ func TestAddLog(t *testing.T) {
 			},
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				requireContains(t, db, 16, 0, createHash(1))
+
+				ref, logCount, execMsgs, err := db.OpenBlock(16)
+				require.NoError(t, err)
+				require.Empty(t, execMsgs)
+				require.Equal(t, uint32(1), logCount)
+				require.Equal(t, eth.BlockRef{Hash: createHash(16), Number: 16, ParentHash: createHash(15), Time: 5001}, ref)
 			})
 	})
 
@@ -221,6 +267,18 @@ func TestAddLog(t *testing.T) {
 				requireContains(t, db, 16, 0, createHash(1))
 				requireContains(t, db, 16, 1, createHash(2))
 				requireContains(t, db, 16, 2, createHash(3))
+
+				ref, logCount, execMsgs, err := db.OpenBlock(13)
+				require.NoError(t, err)
+				require.Empty(t, execMsgs)
+				require.Equal(t, uint32(0), logCount)
+				require.Equal(t, eth.BlockRef{Hash: createHash(13), Number: 13, ParentHash: createHash(12), Time: 5013}, ref)
+
+				ref, logCount, execMsgs, err = db.OpenBlock(16)
+				require.NoError(t, err)
+				require.Empty(t, execMsgs)
+				require.Equal(t, uint32(3), logCount)
+				require.Equal(t, eth.BlockRef{Hash: createHash(16), Number: 16, ParentHash: createHash(15), Time: 5016}, ref)
 			})
 	})
 
@@ -267,8 +325,8 @@ func TestAddLog(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				bl14 := eth.BlockID{Hash: createHash(14), Number: 14}
 				err := db.SealBlock(createHash(13), bl14, 5000)
-				require.ErrorIs(t, err, entrydb.ErrConflict)
-				require.ErrorIs(t, err, entrydb.ErrConflict)
+				require.ErrorIs(t, err, types.ErrConflict)
+				require.ErrorIs(t, err, types.ErrConflict)
 			})
 	})
 
@@ -285,8 +343,8 @@ func TestAddLog(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				onto := eth.BlockID{Hash: createHash(14), Number: 14}
 				err := db.AddLog(createHash(1), onto, 0, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder, "cannot build logs on 14 when 15 is already sealed")
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder, "cannot build logs on 14 when 15 is already sealed")
+				require.ErrorIs(t, err, types.ErrOutOfOrder, "cannot build logs on 14 when 15 is already sealed")
+				require.ErrorIs(t, err, types.ErrOutOfOrder, "cannot build logs on 14 when 15 is already sealed")
 			})
 	})
 
@@ -302,8 +360,8 @@ func TestAddLog(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				bl15 := eth.BlockID{Hash: createHash(15), Number: 15}
 				err := db.AddLog(createHash(1), bl15, 0, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder, "already at log index 2")
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder, "already at log index 2")
+				require.ErrorIs(t, err, types.ErrOutOfOrder, "already at log index 2")
+				require.ErrorIs(t, err, types.ErrOutOfOrder, "already at log index 2")
 			})
 	})
 
@@ -318,8 +376,8 @@ func TestAddLog(t *testing.T) {
 			},
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				err := db.AddLog(createHash(1), eth.BlockID{Hash: createHash(16), Number: 16}, 0, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
 			})
 	})
 
@@ -335,8 +393,8 @@ func TestAddLog(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				bl15 := eth.BlockID{Hash: createHash(15), Number: 15}
 				err := db.AddLog(createHash(1), bl15, 1, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder, "already at log index 2")
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder, "already at log index 2")
+				require.ErrorIs(t, err, types.ErrOutOfOrder, "already at log index 2")
+				require.ErrorIs(t, err, types.ErrOutOfOrder, "already at log index 2")
 			})
 	})
 
@@ -352,8 +410,8 @@ func TestAddLog(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				bl15 := eth.BlockID{Hash: createHash(16), Number: 16}
 				err := db.AddLog(createHash(1), bl15, 2, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
 			})
 	})
 
@@ -368,8 +426,8 @@ func TestAddLog(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				bl15 := eth.BlockID{Hash: createHash(15), Number: 15}
 				err := db.AddLog(createHash(1), bl15, 2, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
 			})
 	})
 
@@ -382,8 +440,8 @@ func TestAddLog(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				bl15 := eth.BlockID{Hash: createHash(15), Number: 15}
 				err := db.AddLog(createHash(1), bl15, 5, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
 			})
 	})
 
@@ -404,8 +462,8 @@ func TestAddLog(t *testing.T) {
 				err = db.SealBlock(bl15.Hash, bl16, 5001)
 				require.NoError(t, err)
 				err = db.AddLog(createHash(1), bl16, 1, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
 			})
 	})
 
@@ -701,6 +759,14 @@ func TestExecutes(t *testing.T) {
 
 			// 51 only contained 3 logs, not 4
 			requireConflicts(t, db, 51, 3, createHash(2))
+
+			// 51 contains an executing message, and 2 other non-executing logs
+			ref, logCount, execMsgs, err := db.OpenBlock(51)
+			require.NoError(t, err)
+			require.Len(t, execMsgs, 1)
+			require.Equal(t, &execMsg1, execMsgs[1])
+			require.Equal(t, uint32(3), logCount)
+			require.Equal(t, eth.BlockRef{Hash: createHash(51), Number: 51, ParentHash: createHash(50), Time: 5001}, ref)
 		})
 }
 
@@ -710,9 +776,9 @@ func TestGetBlockInfo(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {},
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				_, err := db.FindSealedBlock(10)
-				require.ErrorIs(t, err, entrydb.ErrFuture)
+				require.ErrorIs(t, err, types.ErrFuture)
 				_, err = db.FindSealedBlock(10)
-				require.ErrorIs(t, err, entrydb.ErrFuture)
+				require.ErrorIs(t, err, types.ErrFuture)
 			})
 	})
 
@@ -727,9 +793,9 @@ func TestGetBlockInfo(t *testing.T) {
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				// if the DB starts at 11, then shouldn't find 10
 				_, err := db.FindSealedBlock(10)
-				require.ErrorIs(t, err, entrydb.ErrSkipped)
+				require.ErrorIs(t, err, types.ErrSkipped)
 				_, err = db.FindSealedBlock(10)
-				require.ErrorIs(t, err, entrydb.ErrSkipped)
+				require.ErrorIs(t, err, types.ErrSkipped)
 			})
 	})
 
@@ -772,8 +838,8 @@ func requireConflicts(t *testing.T, db *DB, blockNum uint64, logIdx uint32, logH
 	m, ok := db.m.(*stubMetrics)
 	require.True(t, ok, "Did not get the expected metrics type")
 	_, err := db.Contains(blockNum, logIdx, logHash)
-	require.ErrorIs(t, err, entrydb.ErrConflict, "canonical chain must not include this log")
-	require.ErrorIs(t, err, entrydb.ErrConflict, "canonical chain must not include this log")
+	require.ErrorIs(t, err, types.ErrConflict, "canonical chain must not include this log")
+	require.ErrorIs(t, err, types.ErrConflict, "canonical chain must not include this log")
 	require.LessOrEqual(t, m.entriesReadForSearch, int64(searchCheckpointFrequency*2), "Should not need to read more than between two checkpoints")
 }
 
@@ -781,8 +847,8 @@ func requireFuture(t *testing.T, db *DB, blockNum uint64, logIdx uint32, logHash
 	m, ok := db.m.(*stubMetrics)
 	require.True(t, ok, "Did not get the expected metrics type")
 	_, err := db.Contains(blockNum, logIdx, logHash)
-	require.ErrorIs(t, err, entrydb.ErrFuture, "canonical chain does not yet include this log")
-	require.ErrorIs(t, err, entrydb.ErrFuture, "canonical chain does not yet include this log")
+	require.ErrorIs(t, err, types.ErrFuture, "canonical chain does not yet include this log")
+	require.ErrorIs(t, err, types.ErrFuture, "canonical chain does not yet include this log")
 	require.LessOrEqual(t, m.entriesReadForSearch, int64(searchCheckpointFrequency*2), "Should not need to read more than between two checkpoints")
 }
 
@@ -943,11 +1009,11 @@ func TestRewind(t *testing.T) {
 	t.Run("WhenEmpty", func(t *testing.T) {
 		runDBTest(t, func(t *testing.T, db *DB, m *stubMetrics) {},
 			func(t *testing.T, db *DB, m *stubMetrics) {
-				require.ErrorIs(t, db.Rewind(100), entrydb.ErrFuture)
-				require.ErrorIs(t, db.Rewind(100), entrydb.ErrFuture)
+				require.ErrorIs(t, db.Rewind(100), types.ErrFuture)
+				require.ErrorIs(t, db.Rewind(100), types.ErrFuture)
 				// Genesis is a block to, not present in an empty DB
-				require.ErrorIs(t, db.Rewind(0), entrydb.ErrFuture)
-				require.ErrorIs(t, db.Rewind(0), entrydb.ErrFuture)
+				require.ErrorIs(t, db.Rewind(0), types.ErrFuture)
+				require.ErrorIs(t, db.Rewind(0), types.ErrFuture)
 			})
 	})
 
@@ -965,8 +1031,8 @@ func TestRewind(t *testing.T) {
 				require.NoError(t, db.SealBlock(bl51.Hash, bl52, 504))
 				require.NoError(t, db.AddLog(createHash(4), bl52, 0, nil))
 				// cannot rewind to a block that is not sealed yet
-				require.ErrorIs(t, db.Rewind(53), entrydb.ErrFuture)
-				require.ErrorIs(t, db.Rewind(53), entrydb.ErrFuture)
+				require.ErrorIs(t, db.Rewind(53), types.ErrFuture)
+				require.ErrorIs(t, db.Rewind(53), types.ErrFuture)
 			},
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				requireContains(t, db, 51, 0, createHash(1))
@@ -985,8 +1051,8 @@ func TestRewind(t *testing.T) {
 				require.NoError(t, db.AddLog(createHash(1), bl50, 0, nil))
 				require.NoError(t, db.AddLog(createHash(2), bl50, 1, nil))
 				// cannot go back to an unknown block
-				require.ErrorIs(t, db.Rewind(25), entrydb.ErrSkipped)
-				require.ErrorIs(t, db.Rewind(25), entrydb.ErrSkipped)
+				require.ErrorIs(t, db.Rewind(25), types.ErrSkipped)
+				require.ErrorIs(t, db.Rewind(25), types.ErrSkipped)
 			},
 			func(t *testing.T, db *DB, m *stubMetrics) {
 				requireContains(t, db, 51, 0, createHash(1))
@@ -1111,14 +1177,14 @@ func TestRewind(t *testing.T) {
 				bl29 := eth.BlockID{Hash: createHash(29), Number: 29}
 				// 29 was deleted
 				err := db.AddLog(createHash(2), bl29, 1, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder, "Cannot add log on removed block")
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder, "Cannot add log on removed block")
+				require.ErrorIs(t, err, types.ErrOutOfOrder, "Cannot add log on removed block")
+				require.ErrorIs(t, err, types.ErrOutOfOrder, "Cannot add log on removed block")
 				// 15 is older, we have up to 16
 				bl15 := eth.BlockID{Hash: createHash(15), Number: 15}
 				// try to add a third log to 15
 				err = db.AddLog(createHash(10), bl15, 2, nil)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
-				require.ErrorIs(t, err, entrydb.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
+				require.ErrorIs(t, err, types.ErrOutOfOrder)
 				bl16 := eth.BlockID{Hash: createHash(16), Number: 16}
 				// try to add a log to 17, on top of 16
 				err = db.AddLog(createHash(42), bl16, 0, nil)

op-supervisor/supervisor/backend/db/logs/entries.go

@@ -6,7 +6,6 @@ import (
 
 	"github.com/ethereum/go-ethereum/common"
 
-	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/entrydb"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/types"
 )
 
@@ -29,7 +28,7 @@ func newSearchCheckpoint(blockNum uint64, logsSince uint32, timestamp uint64) se
 
 func newSearchCheckpointFromEntry(data Entry) (searchCheckpoint, error) {
 	if data.Type() != TypeSearchCheckpoint {
-		return searchCheckpoint{}, fmt.Errorf("%w: attempting to decode search checkpoint but was type %s", entrydb.ErrDataCorruption, data.Type())
+		return searchCheckpoint{}, fmt.Errorf("%w: attempting to decode search checkpoint but was type %s", types.ErrDataCorruption, data.Type())
 	}
 	return searchCheckpoint{
 		blockNum:  binary.LittleEndian.Uint64(data[1:9]),
@@ -59,7 +58,7 @@ func newCanonicalHash(hash common.Hash) canonicalHash {
 
 func newCanonicalHashFromEntry(data Entry) (canonicalHash, error) {
 	if data.Type() != TypeCanonicalHash {
-		return canonicalHash{}, fmt.Errorf("%w: attempting to decode canonical hash but was type %s", entrydb.ErrDataCorruption, data.Type())
+		return canonicalHash{}, fmt.Errorf("%w: attempting to decode canonical hash but was type %s", types.ErrDataCorruption, data.Type())
 	}
 	return newCanonicalHash(common.Hash(data[1:33])), nil
 }
@@ -78,7 +77,7 @@ type initiatingEvent struct {
 
 func newInitiatingEventFromEntry(data Entry) (initiatingEvent, error) {
 	if data.Type() != TypeInitiatingEvent {
-		return initiatingEvent{}, fmt.Errorf("%w: attempting to decode initiating event but was type %s", entrydb.ErrDataCorruption, data.Type())
+		return initiatingEvent{}, fmt.Errorf("%w: attempting to decode initiating event but was type %s", types.ErrDataCorruption, data.Type())
 	}
 	flags := data[1]
 	return initiatingEvent{
@@ -109,7 +108,7 @@ func (i initiatingEvent) encode() Entry {
 }
 
 type executingLink struct {
-	chain     uint32
+	chain     uint32 // chain index, not a chain ID
 	blockNum  uint64
 	logIdx    uint32
 	timestamp uint64
@@ -120,7 +119,7 @@ func newExecutingLink(msg types.ExecutingMessage) (executingLink, error) {
 		return executingLink{}, fmt.Errorf("log idx is too large (%v)", msg.LogIdx)
 	}
 	return executingLink{
-		chain:     msg.Chain,
+		chain:     uint32(msg.Chain),
 		blockNum:  msg.BlockNum,
 		logIdx:    msg.LogIdx,
 		timestamp: msg.Timestamp,
@@ -129,7 +128,7 @@ func newExecutingLink(msg types.ExecutingMessage) (executingLink, error) {
 
 func newExecutingLinkFromEntry(data Entry) (executingLink, error) {
 	if data.Type() != TypeExecutingLink {
-		return executingLink{}, fmt.Errorf("%w: attempting to decode executing link but was type %s", entrydb.ErrDataCorruption, data.Type())
+		return executingLink{}, fmt.Errorf("%w: attempting to decode executing link but was type %s", types.ErrDataCorruption, data.Type())
 	}
 	timestamp := binary.LittleEndian.Uint64(data[16:24])
 	return executingLink{
@@ -166,7 +165,7 @@ func newExecutingCheck(hash common.Hash) executingCheck {
 
 func newExecutingCheckFromEntry(data Entry) (executingCheck, error) {
 	if data.Type() != TypeExecutingCheck {
-		return executingCheck{}, fmt.Errorf("%w: attempting to decode executing check but was type %s", entrydb.ErrDataCorruption, data.Type())
+		return executingCheck{}, fmt.Errorf("%w: attempting to decode executing check but was type %s", types.ErrDataCorruption, data.Type())
 	}
 	return newExecutingCheck(common.Hash(data[1:33])), nil
 }

op-supervisor/supervisor/backend/db/logs/iterator.go

@@ -41,7 +41,7 @@ type traverseConditionalFn func(state IteratorState) error
 func (i *iterator) End() error {
 	for {
 		_, err := i.next()
-		if errors.Is(err, entrydb.ErrFuture) {
+		if errors.Is(err, types.ErrFuture) {
 			return nil
 		} else if err != nil {
 			return err
@@ -49,7 +49,7 @@ func (i *iterator) End() error {
 	}
 }
 
-// NextInitMsg returns the next initiating message in the iterator.
+// NextInitMsg advances the iterator until it reads the next Initiating Message into the current state.
 // It scans forward until it finds and fully reads an initiating event, skipping any blocks.
 func (i *iterator) NextInitMsg() error {
 	seenLog := false
@@ -73,9 +73,8 @@ func (i *iterator) NextInitMsg() error {
 	}
 }
 
-// NextExecMsg returns the next executing message in the iterator.
+// NextExecMsg advances the iterator until it reads the next Executing Message into the current state.
 // It scans forward until it finds and fully reads an initiating event, skipping any blocks.
-// This does not stay at the executing message of the current initiating message, if there is any.
 func (i *iterator) NextExecMsg() error {
 	for {
 		err := i.NextInitMsg()
@@ -88,7 +87,7 @@ func (i *iterator) NextExecMsg() error {
 	}
 }
 
-// NextBlock returns the next block in the iterator.
+// NextBlock advances the iterator until it reads the next block into the current state.
 // It scans forward until it finds and fully reads a block, skipping any events.
 func (i *iterator) NextBlock() error {
 	seenBlock := false
@@ -134,7 +133,7 @@ func (i *iterator) next() (EntryType, error) {
 	entry, err := i.db.store.Read(index)
 	if err != nil {
 		if errors.Is(err, io.EOF) {
-			return 0, entrydb.ErrFuture
+			return 0, types.ErrFuture
 		}
 		return 0, fmt.Errorf("failed to read entry %d: %w", index, err)
 	}

op-supervisor/supervisor/backend/db/logs/state.go

@@ -200,7 +200,7 @@ func (l *logContext) processEntry(entry Entry) error {
 			return err
 		}
 		l.execMsg = &types.ExecutingMessage{
-			Chain:     link.chain,
+			Chain:     types.ChainIndex(link.chain), // TODO(#11105): translate chain ID to chain index
 			BlockNum:  link.blockNum,
 			LogIdx:    link.logIdx,
 			Timestamp: link.timestamp,
@@ -352,13 +352,13 @@ func (l *logContext) SealBlock(parent common.Hash, upd eth.BlockID, timestamp ui
 			return err
 		}
 		if l.blockHash != parent {
-			return fmt.Errorf("%w: cannot apply block %s (parent %s) on top of %s", entrydb.ErrConflict, upd, parent, l.blockHash)
+			return fmt.Errorf("%w: cannot apply block %s (parent %s) on top of %s", types.ErrConflict, upd, parent, l.blockHash)
 		}
 		if l.blockHash != (common.Hash{}) && l.blockNum+1 != upd.Number {
-			return fmt.Errorf("%w: cannot apply block %d on top of %d", entrydb.ErrConflict, upd.Number, l.blockNum)
+			return fmt.Errorf("%w: cannot apply block %d on top of %d", types.ErrConflict, upd.Number, l.blockNum)
 		}
 		if l.timestamp > timestamp {
-			return fmt.Errorf("%w: block timestamp %d must be equal or larger than current timestamp %d", entrydb.ErrConflict, timestamp, l.timestamp)
+			return fmt.Errorf("%w: block timestamp %d must be equal or larger than current timestamp %d", types.ErrConflict, timestamp, l.timestamp)
 		}
 	}
 	l.blockHash = upd.Hash
@@ -375,28 +375,28 @@ func (l *logContext) SealBlock(parent common.Hash, upd eth.BlockID, timestamp ui
 // The parent-block that the log comes after must be applied with ApplyBlock first.
 func (l *logContext) ApplyLog(parentBlock eth.BlockID, logIdx uint32, logHash common.Hash, execMsg *types.ExecutingMessage) error {
 	if parentBlock == (eth.BlockID{}) {
-		return fmt.Errorf("genesis does not have logs: %w", entrydb.ErrOutOfOrder)
+		return fmt.Errorf("genesis does not have logs: %w", types.ErrOutOfOrder)
 	}
 	if err := l.inferFull(); err != nil { // ensure we can start applying
 		return err
 	}
 	if !l.hasCompleteBlock() {
 		if l.blockNum == 0 {
-			return fmt.Errorf("%w: should not have logs in block 0", entrydb.ErrOutOfOrder)
+			return fmt.Errorf("%w: should not have logs in block 0", types.ErrOutOfOrder)
 		} else {
 			return errors.New("cannot append log before last known block is sealed")
 		}
 	}
 	// check parent block
 	if l.blockHash != parentBlock.Hash {
-		return fmt.Errorf("%w: log builds on top of block %s, but have block %s", entrydb.ErrOutOfOrder, parentBlock, l.blockHash)
+		return fmt.Errorf("%w: log builds on top of block %s, but have block %s", types.ErrOutOfOrder, parentBlock, l.blockHash)
 	}
 	if l.blockNum != parentBlock.Number {
-		return fmt.Errorf("%w: log builds on top of block %d, but have block %d", entrydb.ErrOutOfOrder, parentBlock.Number, l.blockNum)
+		return fmt.Errorf("%w: log builds on top of block %d, but have block %d", types.ErrOutOfOrder, parentBlock.Number, l.blockNum)
 	}
 	// check if log fits on top. The length so far == the index of the next log.
 	if logIdx != l.logsSince {
-		return fmt.Errorf("%w: expected event index %d, cannot append %d", entrydb.ErrOutOfOrder, l.logsSince, logIdx)
+		return fmt.Errorf("%w: expected event index %d, cannot append %d", types.ErrOutOfOrder, l.logsSince, logIdx)
 	}
 	l.logHash = logHash
 	l.execMsg = execMsg

op-supervisor/supervisor/backend/db/query.go

@@ -7,7 +7,6 @@ import (
 	"github.com/ethereum/go-ethereum/common"
 
 	"github.com/ethereum-optimism/optimism/op-service/eth"
-	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/entrydb"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/backend/db/logs"
 	"github.com/ethereum-optimism/optimism/op-supervisor/supervisor/types"
 )
@@ -18,7 +17,7 @@ func (db *ChainsDB) FindSealedBlock(chain types.ChainID, number uint64) (seal ty
 
 	logDB, ok := db.logDBs[chain]
 	if !ok {
-		return types.BlockSeal{}, fmt.Errorf("%w: %v", ErrUnknownChain, chain)
+		return types.BlockSeal{}, fmt.Errorf("%w: %v", types.ErrUnknownChain, chain)
 	}
 	return logDB.FindSealedBlock(number)
 }
@@ -37,17 +36,69 @@ func (db *ChainsDB) LatestBlockNum(chain types.ChainID) (num uint64, ok bool) {
 	return logDB.LatestSealedBlockNum()
 }
 
+func (db *ChainsDB) IsCrossUnsafe(chainID types.ChainID, block eth.BlockID) error {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+	v, ok := db.crossUnsafe[chainID]
+	if !ok {
+		return types.ErrUnknownChain
+	}
+	if v == (types.BlockSeal{}) {
+		return types.ErrFuture
+	}
+	if block.Number > v.Number {
+		return types.ErrFuture
+	}
+	// TODO(#11693): make cross-unsafe reorg safe
+	return nil
+}
+
+func (db *ChainsDB) ParentBlock(chainID types.ChainID, parentOf eth.BlockID) (parent eth.BlockID, err error) {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+	logDB, ok := db.logDBs[chainID]
+	if !ok {
+		return eth.BlockID{}, types.ErrUnknownChain
+	}
+	if parentOf.Number == 0 {
+		return eth.BlockID{}, nil
+	}
+	// TODO(#11693): make parent-lookup reorg safe
+	got, err := logDB.FindSealedBlock(parentOf.Number - 1)
+	if err != nil {
+		return eth.BlockID{}, err
+	}
+	return got.ID(), nil
+}
+
+func (db *ChainsDB) IsLocalUnsafe(chainID types.ChainID, block eth.BlockID) error {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+	logDB, ok := db.logDBs[chainID]
+	if !ok {
+		return types.ErrUnknownChain
+	}
+	got, err := logDB.FindSealedBlock(block.Number)
+	if err != nil {
+		return err
+	}
+	if got.ID() != block {
+		return fmt.Errorf("found %s but was looking for unsafe block %s: %w", got, block, types.ErrConflict)
+	}
+	return nil
+}
+
 func (db *ChainsDB) LocalUnsafe(chainID types.ChainID) (types.BlockSeal, error) {
 	db.mu.RLock()
 	defer db.mu.RUnlock()
 
 	eventsDB, ok := db.logDBs[chainID]
 	if !ok {
-		return types.BlockSeal{}, ErrUnknownChain
+		return types.BlockSeal{}, types.ErrUnknownChain
 	}
 	n, ok := eventsDB.LatestSealedBlockNum()
 	if !ok {
-		return types.BlockSeal{}, entrydb.ErrFuture
+		return types.BlockSeal{}, types.ErrFuture
 	}
 	return eventsDB.FindSealedBlock(n)
 }
@@ -58,7 +109,7 @@ func (db *ChainsDB) CrossUnsafe(chainID types.ChainID) (types.BlockSeal, error)
 
 	result, ok := db.crossUnsafe[chainID]
 	if !ok {
-		return types.BlockSeal{}, ErrUnknownChain
+		return types.BlockSeal{}, types.ErrUnknownChain
 	}
 	// Fall back to cross-safe if cross-unsafe is not known yet
 	if result == (types.BlockSeal{}) {
@@ -77,7 +128,7 @@ func (db *ChainsDB) LocalSafe(chainID types.ChainID) (derivedFrom types.BlockSea
 
 	localDB, ok := db.localDBs[chainID]
 	if !ok {
-		return types.BlockSeal{}, types.BlockSeal{}, ErrUnknownChain
+		return types.BlockSeal{}, types.BlockSeal{}, types.ErrUnknownChain
 	}
 	return localDB.Latest()
 }
@@ -88,7 +139,7 @@ func (db *ChainsDB) CrossSafe(chainID types.ChainID) (derivedFrom types.BlockSea
 
 	crossDB, ok := db.crossDBs[chainID]
 	if !ok {
-		return types.BlockSeal{}, types.BlockSeal{}, ErrUnknownChain
+		return types.BlockSeal{}, types.BlockSeal{}, types.ErrUnknownChain
 	}
 	return crossDB.Latest()
 }
@@ -111,7 +162,7 @@ func (db *ChainsDB) Finalized(chainID types.ChainID) (types.BlockSeal, error) {
 func (db *ChainsDB) LastDerivedFrom(chainID types.ChainID, derivedFrom eth.BlockID) (derived types.BlockSeal, err error) {
 	crossDB, ok := db.crossDBs[chainID]
 	if !ok {
-		return types.BlockSeal{}, ErrUnknownChain
+		return types.BlockSeal{}, types.ErrUnknownChain
 	}
 	return crossDB.LastDerivedAt(derivedFrom)
 }
@@ -122,7 +173,7 @@ func (db *ChainsDB) DerivedFrom(chainID types.ChainID, derived eth.BlockID) (der
 
 	localDB, ok := db.localDBs[chainID]
 	if !ok {
-		return types.BlockSeal{}, ErrUnknownChain
+		return types.BlockSeal{}, types.ErrUnknownChain
 	}
 	return localDB.DerivedFrom(derived)
 }
@@ -135,11 +186,168 @@ func (db *ChainsDB) Check(chain types.ChainID, blockNum uint64, logIdx uint32, l
 
 	logDB, ok := db.logDBs[chain]
 	if !ok {
-		return types.BlockSeal{}, fmt.Errorf("%w: %v", ErrUnknownChain, chain)
+		return types.BlockSeal{}, fmt.Errorf("%w: %v", types.ErrUnknownChain, chain)
 	}
 	return logDB.Contains(blockNum, logIdx, logHash)
 }
 
+// OpenBlock returns the Executing Messages for the block at the given number on the given chain.
+// it routes the request to the appropriate logDB.
+func (db *ChainsDB) OpenBlock(chainID types.ChainID, blockNum uint64) (seal eth.BlockRef, logCount uint32, execMsgs map[uint32]*types.ExecutingMessage, err error) {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+
+	logDB, ok := db.logDBs[chainID]
+	if !ok {
+		return eth.BlockRef{}, 0, nil, types.ErrUnknownChain
+	}
+	return logDB.OpenBlock(blockNum)
+}
+
+// LocalDerivedFrom returns the block that the given block was derived from, if it exists in the local derived-from storage.
+// it routes the request to the appropriate localDB.
+func (db *ChainsDB) LocalDerivedFrom(chain types.ChainID, derived eth.BlockID) (derivedFrom types.BlockSeal, err error) {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+
+	lDB, ok := db.localDBs[chain]
+	if !ok {
+		return types.BlockSeal{}, types.ErrUnknownChain
+	}
+	return lDB.DerivedFrom(derived)
+}
+
+// CrossDerivedFrom returns the block that the given block was derived from, if it exists in the cross derived-from storage.
+// it routes the request to the appropriate crossDB.
+func (db *ChainsDB) CrossDerivedFrom(chain types.ChainID, derived eth.BlockID) (derivedFrom types.BlockSeal, err error) {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+
+	xDB, ok := db.crossDBs[chain]
+	if !ok {
+		return types.BlockSeal{}, types.ErrUnknownChain
+	}
+	return xDB.DerivedFrom(derived)
+}
+
+// CandidateCrossSafe returns the candidate local-safe block that may become cross-safe.
+//
+// This returns ErrFuture if no block is known yet.
+//
+// Or ErrConflict if there is an inconsistency between the local-safe and cross-safe DB.
+//
+// Or ErrOutOfScope, with non-zero derivedFromScope,
+// if additional L1 data is needed to cross-verify the candidate L2 block.
+func (db *ChainsDB) CandidateCrossSafe(chain types.ChainID) (derivedFromScope, crossSafe eth.BlockRef, err error) {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+
+	xDB, ok := db.crossDBs[chain]
+	if !ok {
+		return eth.BlockRef{}, eth.BlockRef{}, types.ErrUnknownChain
+	}
+
+	lDB, ok := db.localDBs[chain]
+	if !ok {
+		return eth.BlockRef{}, eth.BlockRef{}, types.ErrUnknownChain
+	}
+
+	// Example:
+	// A B C D      <- L1
+	// 1     2      <- L2
+	// return:
+	// (A, 0) -> initial scope, no L2 block yet. Genesis found to be cross-safe
+	// (A, 1) -> 1 is determined cross-safe, won't be a candidate anymore after. 2 is the new candidate
+	// (B, 2) -> 2 is out of scope, go to B
+	// (C, 2) -> 2 is out of scope, go to C
+	// (D, 2) -> 2 is in scope, stay on D, promote candidate to cross-safe
+	// (D, 3) -> look at 3 next, see if we have to bump L1 yet, try with same L1 scope first
+
+	crossDerivedFrom, crossDerived, err := xDB.Latest()
+	if err != nil {
+		if errors.Is(err, types.ErrFuture) {
+			// If we do not have any cross-safe block yet, then return the first local-safe block.
+			derivedFrom, derived, err := lDB.First()
+			if err != nil {
+				return eth.BlockRef{}, eth.BlockRef{}, fmt.Errorf("failed to find first local-safe block: %w", err)
+			}
+			// First block has no parent
+			return derivedFrom.WithParent(eth.BlockID{}),
+				derived.WithParent(eth.BlockID{}), nil
+		}
+		return eth.BlockRef{}, eth.BlockRef{}, err
+	}
+	// Find the local-safe block that comes right after the last seen cross-safe block.
+	// Just L2 block by block traversal, conditional on being local-safe.
+	// This will be the candidate L2 block to promote.
+
+	// While the local-safe block isn't cross-safe given limited L1 scope, we'll keep bumping the L1 scope,
+	// And update cross-safe accordingly.
+	// This method will keep returning the latest known scope that has been verified to be cross-safe.
+	candidateFrom, candidate, err := lDB.NextDerived(crossDerived.ID())
+	if err != nil {
+		return eth.BlockRef{}, eth.BlockRef{}, err
+	}
+
+	candidateRef := candidate.WithParent(crossDerived.ID())
+
+	parentDerivedFrom, err := lDB.PreviousDerivedFrom(candidateFrom.ID())
+	if err != nil {
+		return eth.BlockRef{}, eth.BlockRef{}, fmt.Errorf("failed to find parent-block of derived-from %s: %w", candidateFrom, err)
+	}
+	candidateFromRef := candidateFrom.WithParent(parentDerivedFrom.ID())
+
+	// Allow increment of DA by 1, if we know the floor (due to local safety) is 1 ahead of the current cross-safe L1 scope.
+	if candidateFrom.Number > crossDerivedFrom.Number+1 {
+		// If we are not ready to process the candidate block,
+		// then we need to stick to the current scope, so the caller can bump up from there.
+		parent, err := lDB.PreviousDerivedFrom(crossDerivedFrom.ID())
+		if err != nil {
+			return eth.BlockRef{}, eth.BlockRef{}, fmt.Errorf("failed to find parent-block of cross-derived-from %s: %w",
+				crossDerivedFrom, err)
+		}
+		crossDerivedFromRef := crossDerivedFrom.WithParent(parent.ID())
+		return crossDerivedFromRef, eth.BlockRef{},
+			fmt.Errorf("candidate is from %s, while current scope is %s: %w",
+				candidateFrom, crossDerivedFrom, types.ErrOutOfScope)
+	}
+	return candidateFromRef, candidateRef, nil
+}
+
+func (db *ChainsDB) PreviousDerived(chain types.ChainID, derived eth.BlockID) (prevDerived types.BlockSeal, err error) {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+	lDB, ok := db.localDBs[chain]
+	if !ok {
+		return types.BlockSeal{}, types.ErrUnknownChain
+	}
+	return lDB.PreviousDerived(derived)
+}
+
+func (db *ChainsDB) PreviousDerivedFrom(chain types.ChainID, derivedFrom eth.BlockID) (prevDerivedFrom types.BlockSeal, err error) {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+	lDB, ok := db.localDBs[chain]
+	if !ok {
+		return types.BlockSeal{}, types.ErrUnknownChain
+	}
+	return lDB.PreviousDerivedFrom(derivedFrom)
+}
+
+func (db *ChainsDB) NextDerivedFrom(chain types.ChainID, derivedFrom eth.BlockID) (after eth.BlockRef, err error) {
+	db.mu.RLock()
+	defer db.mu.RUnlock()
+	lDB, ok := db.localDBs[chain]
+	if !ok {
+		return eth.BlockRef{}, types.ErrUnknownChain
+	}
+	v, err := lDB.NextDerivedFrom(derivedFrom)
+	if err != nil {
+		return eth.BlockRef{}, err
+	}
+	return v.WithParent(derivedFrom), nil
+}
+
 // Safest returns the strongest safety level that can be guaranteed for the given log entry.
 // it assumes the log entry has already been checked and is valid, this function only checks safety levels.
 // Cross-safety levels are all considered to be more safe than any form of local-safety.
@@ -181,7 +389,7 @@ func (db *ChainsDB) Safest(chainID types.ChainID, blockNum uint64, index uint32)
 func (db *ChainsDB) IteratorStartingAt(chain types.ChainID, sealedNum uint64, logIndex uint32) (logs.Iterator, error) {
 	logDB, ok := db.logDBs[chain]
 	if !ok {
-		return nil, fmt.Errorf("%w: %v", ErrUnknownChain, chain)
+		return nil, fmt.Errorf("%w: %v", types.ErrUnknownChain, chain)
 	}
 	return logDB.IteratorStartingAt(sealedNum, logIndex)
 }

op-supervisor/supervisor/backend/db/update.go

@@ -20,7 +20,7 @@ func (db *ChainsDB) AddLog(
 
 	logDB, ok := db.logDBs[chain]
 	if !ok {
-		return fmt.Errorf("cannot AddLog: %w: %v", ErrUnknownChain, chain)
+		return fmt.Errorf("cannot AddLog: %w: %v", types.ErrUnknownChain, chain)
 	}
 	return logDB.AddLog(logHash, parentBlock, logIdx, execMsg)
 }
@@ -31,8 +31,9 @@ func (db *ChainsDB) SealBlock(chain types.ChainID, block eth.BlockRef) error {
 
 	logDB, ok := db.logDBs[chain]
 	if !ok {
-		return fmt.Errorf("cannot SealBlock: %w: %v", ErrUnknownChain, chain)
+		return fmt.Errorf("cannot SealBlock: %w: %v", types.ErrUnknownChain, chain)
 	}
+	db.logger.Debug("Updating local unsafe", "chain", chain, "block", block)
 	err := logDB.SealBlock(block.ParentHash, block.ID(), block.Time)
 	if err != nil {
 		return fmt.Errorf("failed to seal block %v: %w", block, err)
@@ -46,7 +47,7 @@ func (db *ChainsDB) Rewind(chain types.ChainID, headBlockNum uint64) error {
 
 	logDB, ok := db.logDBs[chain]
 	if !ok {
-		return fmt.Errorf("cannot Rewind: %w: %s", ErrUnknownChain, chain)
+		return fmt.Errorf("cannot Rewind: %w: %s", types.ErrUnknownChain, chain)
 	}
 	return logDB.Rewind(headBlockNum)
 }
@@ -57,8 +58,9 @@ func (db *ChainsDB) UpdateLocalSafe(chain types.ChainID, derivedFrom eth.BlockRe
 
 	localDB, ok := db.localDBs[chain]
 	if !ok {
-		return fmt.Errorf("cannot UpdateLocalSafe: %w: %v", ErrUnknownChain, chain)
+		return fmt.Errorf("cannot UpdateLocalSafe: %w: %v", types.ErrUnknownChain, chain)
 	}
+	db.logger.Debug("Updating local safe", "chain", chain, "derivedFrom", derivedFrom, "lastDerived", lastDerived)
 	return localDB.AddDerived(derivedFrom, lastDerived)
 }
 
@@ -67,8 +69,9 @@ func (db *ChainsDB) UpdateCrossUnsafe(chain types.ChainID, crossUnsafe types.Blo
 	defer db.mu.RUnlock()
 
 	if _, ok := db.crossUnsafe[chain]; !ok {
-		return fmt.Errorf("cannot UpdateCrossUnsafe: %w: %s", ErrUnknownChain, chain)
+		return fmt.Errorf("cannot UpdateCrossUnsafe: %w: %s", types.ErrUnknownChain, chain)
 	}
+	db.logger.Debug("Updating cross unsafe", "chain", chain, "crossUnsafe", crossUnsafe)
 	db.crossUnsafe[chain] = crossUnsafe
 	return nil
 }
@@ -79,8 +82,9 @@ func (db *ChainsDB) UpdateCrossSafe(chain types.ChainID, l1View eth.BlockRef, la
 
 	crossDB, ok := db.crossDBs[chain]
 	if !ok {
-		return fmt.Errorf("cannot UpdateCrossSafe: %w: %s", ErrUnknownChain, chain)
+		return fmt.Errorf("cannot UpdateCrossSafe: %w: %s", types.ErrUnknownChain, chain)
 	}
+	db.logger.Debug("Updating cross safe", "chain", chain, "l1View", l1View, "lastCrossDerived", lastCrossDerived)
 	return crossDB.AddDerived(l1View, lastCrossDerived)
 }
 
@@ -91,6 +95,7 @@ func (db *ChainsDB) UpdateFinalizedL1(finalized eth.BlockRef) error {
 	if db.finalizedL1.Number > finalized.Number {
 		return fmt.Errorf("cannot rewind finalized L1 head from %s to %s", db.finalizedL1, finalized)
 	}
+	db.logger.Debug("Updating finalized L1", "finalizedL1", finalized)
 	db.finalizedL1 = finalized
 	return nil
 }

op-supervisor/supervisor/backend/processors/contracts/l2inbox.go

@@ -76,7 +76,7 @@ func (i *CrossL2Inbox) DecodeExecutingMessageLog(l *ethTypes.Log) (types.Executi
 	}
 	hash := payloadHashToLogHash(msgHash, identifier.Origin)
 	return types.ExecutingMessage{
-		Chain:     chainID,
+		Chain:     types.ChainIndex(chainID), // TODO(#11105): translate chain ID to chain index
 		Hash:      hash,
 		BlockNum:  identifier.BlockNumber.Uint64(),
 		LogIdx:    uint32(identifier.LogIndex.Uint64()),

op-supervisor/supervisor/backend/processors/contracts/l2inbox_test.go

@@ -20,14 +20,14 @@ func TestDecodeExecutingMessageEvent(t *testing.T) {
 	payload := bytes.Repeat([]byte{0xaa, 0xbb}, 50)
 	payloadHash := crypto.Keccak256Hash(payload)
 	expected := types.ExecutingMessage{
-		Chain:     42424,
+		Chain:     42424, // TODO(#11105): translate chain ID to chain index
 		BlockNum:  12345,
 		LogIdx:    98,
 		Timestamp: 9578295,
 	}
 	contractIdent := contractIdentifier{
 		Origin:      common.Address{0xbb, 0xcc},
-		ChainId:     new(big.Int).SetUint64(uint64(expected.Chain)),
+		ChainId:     new(big.Int).SetUint64(uint64(expected.Chain)), // TODO(#11105): translate chain ID to chain index
 		BlockNumber: new(big.Int).SetUint64(expected.BlockNum),
 		Timestamp:   new(big.Int).SetUint64(expected.Timestamp),
 		LogIndex:    new(big.Int).SetUint64(uint64(expected.LogIdx)),

op-supervisor/supervisor/backend/db/entrydb/error.go → op-supervisor/supervisor/types/error.go

-package entrydb
+package types
 
 import "errors"
 
@@ -17,4 +17,11 @@ var (
 	ErrConflict = errors.New("conflicting data")
 	// ErrStop can be used in iterators to indicate iteration has to stop
 	ErrStop = errors.New("iter stop")
+	// ErrOutOfScope is when data is accessed, but access is not allowed, because of a limited scope.
+	// E.g. when limiting scope to L2 blocks derived from a specific subset of the L1 chain.
+	ErrOutOfScope = errors.New("out of scope")
+	// ErrUnknownChain is when a chain is unknown, not in the dependency set.
+	ErrUnknownChain = errors.New("unknown chain")
+	// ErrNoRPCSource happens when a sub-service needs an RPC data source, but is not configured with one.
+	ErrNoRPCSource = errors.New("no RPC client configured")
 )

op-supervisor/supervisor/types/types.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"math"
 	"math/big"
+	"strconv"
 
 	"github.com/holiman/uint256"
 
@@ -15,8 +16,28 @@ import (
 	"github.com/ethereum-optimism/optimism/op-service/eth"
 )
 
+// ChainIndex represents the lifetime of a chain in a dependency set.
+type ChainIndex uint32
+
+func (ci ChainIndex) String() string {
+	return strconv.FormatUint(uint64(ci), 10)
+}
+
+func (ci ChainIndex) MarshalText() ([]byte, error) {
+	return []byte(ci.String()), nil
+}
+
+func (ci *ChainIndex) UnmarshalText(data []byte) error {
+	v, err := strconv.ParseUint(string(data), 10, 32)
+	if err != nil {
+		return err
+	}
+	*ci = ChainIndex(v)
+	return nil
+}
+
 type ExecutingMessage struct {
-	Chain     uint32 // same as ChainID for now, but will be indirect, i.e. translated to full ID, later
+	Chain     ChainIndex // same as ChainID for now, but will be indirect, i.e. translated to full ID, later
 	BlockNum  uint64
 	LogIdx    uint32
 	Timestamp uint64
@@ -24,7 +45,7 @@ type ExecutingMessage struct {
 }
 
 func (s *ExecutingMessage) String() string {
-	return fmt.Sprintf("ExecMsg(chain: %d, block: %d, log: %d, time: %d, logHash: %s)",
+	return fmt.Sprintf("ExecMsg(chainIndex: %s, block: %d, log: %d, time: %d, logHash: %s)",
 		s.Chain, s.BlockNum, s.LogIdx, s.Timestamp, s.Hash)
 }
 
@@ -208,3 +229,25 @@ func (s BlockSeal) String() string {
 func (s BlockSeal) ID() eth.BlockID {
 	return eth.BlockID{Hash: s.Hash, Number: s.Number}
 }
+
+func (s BlockSeal) WithParent(parent eth.BlockID) eth.BlockRef {
+	// prevent parent attachment if the parent is not the previous block,
+	// and the block is not the genesis block
+	if s.Number != parent.Number+1 && s.Number != 0 {
+		panic(fmt.Errorf("invalid parent block %s to combine with %s", parent, s))
+	}
+	return eth.BlockRef{
+		Hash:       s.Hash,
+		Number:     s.Number,
+		ParentHash: parent.Hash,
+		Time:       s.Timestamp,
+	}
+}
+
+func BlockSealFromRef(ref eth.BlockRef) BlockSeal {
+	return BlockSeal{
+		Hash:      ref.Hash,
+		Number:    ref.Number,
+		Timestamp: ref.Time,
+	}
+}