Supervisor: Safety Index

[axelKingsley]

What

Replaces the following components:

• Safety Checker
• Chain Tracker infrastructure

With "Safety Index", located in safety package.

Safety Index

Safety index takes updates to Local safties for all chains, as well as Finality. It uses those signals to advance the x-safety for all chains as well.

Callers can access the Safety Index's local and cross safety indexes, and will get HeadPointers in return, which point into the database.

Safety Index manages its unsafe and safe pointers as Views

Views

Views are a new wrapper around iterators which are safety-processing specific. They contain a "Local" pointer which represents the starting point of their processing, and an iterator which represents the extent of their processing.

In effect, each view holds the imperatively set local safety index, and holds the cross-safety index by using the iterator's TraverseConditional.

Each type of safety has its own type of conditional traversal for x-heads. Unsafe simply advances to the first non-validating executing message within the local range. Safe, on the other hand, has a more complex check against the L1 block references stored

TraverseConditional

Iterators now support a generic way of advancing. By providing a function which acts on the iterator's state, callers can automatically advance their index as far as possible.

Integration

• SafetyIndex is now wired in to ChainsDB
• ChainsDB triggers an unsafe-head update once done Sealing the block into the logsDB
• Debug logging emitted during TestInteropTrivial reveals the unsafe processor is working

Deletion

I deleted SafetyCheckers and all things HeadStorage related, as SafetyIndex replaces these structures. I wrote a new Safest method for the ChainsDB to consult Safety Indexes for the API, but otherwise everything disconnected as hoped-for.

Future Integration

We are changing the data-flow so that nodes push their data into the supervisor. When this happens, we'll also call the update safe and update finalized flows.

Integration Results

Currently we only have unsafe data coming in because the ingestion is wrongly trying to get data from geth. @protolambda is working on changes for that, but in the meantime, here are some logs demonstrating that a new write to the logs database updated one Local Head, and triggered the Cross-Head update of two chains:

    safety.go:87:               DEBUG[09-26|15:42:07.955] Updated local unsafe head                role=supervisor chainID=900200 local="{LastSealedBlockHash:0xd0f6763efe80a1a7a484f17973380e2e2dc2338ecb939f4f4d83662b353aeb73 LastSealedBlockNum:33 LastSealedTimestamp:1727383328 LogsSince:0}"
    safety.go:99:               DEBUG[09-26|15:42:07.955] Updated cross unsafe head                role=supervisor chainID=900200 cross="{LastSealedBlockHash:0xd0f6763efe80a1a7a484f17973380e2e2dc2338ecb939f4f4d83662b353aeb73 LastSealedBlockNum:33 LastSealedTimestamp:1727383328 LogsSince:0}"
    safety.go:99:               DEBUG[09-26|15:42:07.955] Updated cross unsafe head                role=supervisor chainID=900201 cross="{LastSealedBlockHash:0x569d3b254cd03e00922d68b1a5899b9ff160ae7b00c87ee6f3ab51e5cc68cae0 LastSealedBlockNum:33 LastSealedTimestamp:1727383328 LogsSince:0}"

Tests

• Existing/Implicit Tests. New Tests WIP.

Indexes, Iterators, Pointers, Views, Oh My!

Here's a rundown of the different structures we are using to serve data out of the logs database:

The Database Itself

The Logs Database is a fixed-width append only database with regular checkpointing. The data stored is the log event data (or lack thereof) for every block in order, including detailed information about executing messages.

Indicies

An entrydb.EntryIdx is a uint64 which specifies an exact row into the database structure. With enough context, the data at that position could be read, but indexes are primitives.

Iterators

Iterators represent a read-head on the database. They can advance forward, and can read out the various data-types stored in the database. They consume rows of the database to advance an internal state machine (called logContext)
**Log Contexts represent the state-relevant parameters for the iterator, including its position, last observed block-hash, etc.

Iterators become extra flexible with the use of TraverseConditional, which takes a function that will process the iteratorState until your given function returns an error.

Head Pointers

HeadPointers are logical references into the database. They contain the last sealed block number, and an offset called LogsSince. They can answer basic inequality questions about if another Head Pointer is behind it, or if it's sealed in relation to it.

Views

Views are evaluators on the database, and in particular they are created to maintain "x-head" values. They do the following:

• Store "Local Head" as a HeadPointer
• Process, which advances an Iterator through Executing Events and runs a configured Validity Check on them, stopping when an error is encountered. The Local Head Pointer is used in these functions while the iterator processes through data, for range-checking.

Views return Local and Cross values by returning a Head Pointer, or by transforming the iterator into a Head Pointer.

[protolambda]

Good progress, will need more testing next week, but already closer to getting e2e safety-increments running correctly.

[semgrep-app]

Semgrep found 2 sol-style-require-reason findings:

• packages/contracts-bedrock/scripts/deploy/Deploy.s.sol
  • L1244 - Triage
  • L1328 - Triage

require() must include a reason string

_{Ignore this finding from sol-style-require-reason.}