Supervisor

Table of Contents

Overview
RPC API

Overview

The supervisor is an implementation detail of OP Stack native interop and is not the only architecture that can be used to implement it. The supervisor is responsible for indexing data from all of the chains in a cluster so that the safety level of executing messages can quickly be determined.

RPC API

Common types

`Identifier`

The identifier of a message. Corresponds to an Identifier.

Object:

origin: Address
blockNumber: HexUint64
logIndex: HexUint64
timestamp: HexUint64
chainID: ChainID

`Message`

Describes an initiating message.

Object:

identifier: Identifier - identifier of the message
payloadHash: Hash - keccak256 hash of the message-payload bytes

`ExecutingDescriptor`

Describes the context for message verification. Specifically, this helps apply message-expiry rules on message checks.

Object:

timestamp: HexUint64 - expected timestamp during message execution.
timeout: HexUint64 - optional, requests verification to still hold at timestamp+timeout (inclusive). The message expiry-window may invalidate messages. Default interpretation is a 0 timeout: what is valid at timestamp may not be valid at timestamp+1.

`HexUint64`

STRING: Hex-encoded big-endian number, variable length up to 64 bits, prefixed with 0x.

`Int`

NUMBER: Regular JSON number, always integer. Assumed to always fit in 51 bits.

`ChainID`

STRING: Hex-encoded big-endian number, variable length up to 256 bits, prefixed with 0x.

`Hash`

STRING: Hex-encoded, fixed-length, representing 32 bytes, prefixed with 0x.

`Bytes`

STRING: Hex-encoded, variable length (always full bytes, no odd number of nibbles), representing a bytes list, prefixed with 0x.

`BlockID`

Describes a block.

OBJECT:

hash: Hash - block hash
number: Int - block number

`BlockRef`

Describes a block.

OBJECT:

hash: Hash - block hash
number: Int - block number
parentHash: Hash - block parent-hash
timestamp: Int - block timestamp

`DerivedIDPair`

A pair of block identifiers, linking a derived block to the source block from which it was derived.

OBJECT:

source: BlockID - The block ID of the source block.
derived: BlockID - The block ID of the derived block.

`ChainRootInfo`

OBJECT:

chainId: HexUint64 - The chain ID (Note: this is changing to ChainID soon)
canonical: Hash - output root at the latest canonical block
pending: Bytes - output root preimage

`SupervisorSyncStatus`

Describes the sync status of the Supervisor component. Fields minSyncedL1, safeTimestamp and finalizedTimestamp are set as the minimum value among chains in chains.

OBJECT:

minSyncedL1: BlockRef - block ref to the synced L1 block
safeTimestamp: Int - safe timestamp
finalizedTimestamp: Int - finalized timestamp
chains: OBJECT with ChainID keys and SupervisorChainSyncStatus values

Note:
If minSyncedL1 does not exist, it MUST be represented as a BlockRef with a hash and parentHash of
0x0000000000000000000000000000000000000000000000000000000000000000, a number of 0,
and a timestamp of 0.

`SupervisorChainSyncStatus`

Describes the sync status for a specific chain

OBJECT:

localUnsafe: BlockRef - local-unsafe ref for the given chain
localSafe: BlockID - local-safe ref for the given chain
crossUnsafe: BlockID - cross-unsafe ref for the given chain
safe: BlockID - cross-safe ref for the given chain
finalized: BlockID - finalized ref for the given chain

Note:
For the fields localSafe, crossUnsafe, safe, and finalized, if the referenced block does not exist yet,
the BlockID MUST be represented with a hash of
0x0000000000000000000000000000000000000000000000000000000000000000 and a number of 0.

`SuperRootResponse`

OBJECT:

crossSafeDerivedFrom: BlockID - common derived-from where all chains are cross-safe
timestamp: Int - The timestamp of the super root
superRoot: Hash - The root of the super root
version: Int - The version of the response
chains: ARRAY of ChainRootInfo - List of chains included in the super root

`SafetyLevel`

The safety level of the message. Corresponds to a verifier SafetyLevel.

STRING, one of:

invalid
unsafe: matching local-unsafe, equivalent to safety of the latest RPC label.
cross-unsafe
local-safe
safe: matching cross-safe, named safe to match the RPC label.
finalized

Methods

`supervisor_crossDerivedToSource`

Parameters:

chainID: ChainID
derived: BlockID

Returns: derivedFrom BlockRef

`supervisor_localUnsafe`

Parameters:

chainID: ChainID

Returns: BlockID

`supervisor_localSafe`

Parameters:

chainID: ChainID

Returns: DerivedIDPair

`supervisor_crossSafe`

Parameters:

chainID: ChainID

Returns: DerivedIDPair

`supervisor_finalized`

Parameters:

chainID: ChainID

Returns: BlockID

`supervisor_finalizedL1`

Parameters: (none)

Returns: BlockRef

`supervisor_superRootAtTimestamp`

Retrieves the super root state at the specified timestamp, which represents the global state across all monitored chains.

Parameters:

timestamp: HexUint64

Returns: SuperRootResponse

`supervisor_syncStatus`

Parameters: (none)

Returns: SupervisorSyncStatus. Throws: Some error if set of supervised chains is empty.

`supervisor_allSafeDerivedAt`

Returns the last derived block for each chain, from the given L1 block.

Parameters:

derivedFrom: BlockID

Returns: derived blocks, mapped in a OBJECT:

key: ChainID
value: BlockID

`supervisor_checkAccessList`

Verifies if an access-list, as defined in EIP-2930, references only valid messages. Message execution in the CrossL2Inbox that is statically declared in the access-list will not revert.

Access-list contents

Only the CrossL2Inbox subset of the access-list in the transaction is required, storage-access by other addresses is not included.

Note that an access-list can contain multiple different storage key lists for the CrossL2Inbox address. All storage keys applicable to the CrossL2Inbox MUST be joined together (preserving ordering), missing storage-keys breaks inbox safety.

ALL storage-keys in the access-list for the CrossL2Inbox MUST be checked. If there is any unrecognized or invalid key, the access-list check MUST fail.

Access-list execution context

The provided execution-context is used to determine validity relative to the provided time constraints, see timestamp invariants.

Since messages expire, validity is not definitive. To reserve validity for a longer time range, a non-zero timeout value can be used. See ExecutingDescriptor documentation.

As block-builder a timeout of 0 should be used.

As transaction pre-verifier, a timeout of 86400 (1 day) should be used. The transaction should be re-verified or dropped after this time duration, as it can no longer be safely included in the block due to message-expiry.

Access-list checks

The access-list check errors are not definite state-transition blockers, the RPC based checks can be extra conservative. I.e. a message that is uncertain to meet the requested safety level may be denied. Specifically, no attempt may be made to verify messages that are initiated and executed within the same timestamp, these are invalid by default. Advanced block-builders may still choose to include these messages by verifying the intra-block constraints.

`supervisor_checkAccessList` contents

Parameters:

inboxEntries: ARRAY of Hash - statically declared CrossL2Inbox access entries.
minSafety: SafetyLevel - minimum required safety, one of:
- unsafe: the message exists.
- cross-unsafe: the message exists in a cross-unsafe block.
- local-safe: the message exists in a local-safe block, not yet cross-verified.
- safe: the message exists in a derived block that is cross-verified.
- finalized: the message exists in a finalized block.
- Other safety levels are invalid and result in an error.
executingDescriptor: ExecutingDescriptor - applies as execution-context to all messages.

Returns: void if all inboxEntries meet minSafety, otherwise RPC error. (Protocol specific errors of this method are exhaustively coded)(#json-rpc-error-codes). Examples of protocol errors are, errors due to minSafety not being met by one or more of the access entries, or, the inboxEntries list may be incomplete or malformed w.r.t. the list of messages it should map to.

Data Availability Errors

The Supervisor RPC API data availability errors use a 6-digit error code system that extends standard JSON-RPC error codes while providing additional categorization based on gRPC status codes.

JSON-RPC Error Codes

An extra digit, ensures error codes don't interfere with standard 5-digit Ethereum JSON-RPC Errors.

Error Code Structure

Superchain data availability RPC error codes follow this structure:

First 2 digits: 32 (indicating server error, matching JSON-RPC conventions)
Middle 2 digits: gRPC status code category (01-16, zero-padded)
Last 2 digits: Specific error index within that category (00-99)

For gRPC status codes reference, see gRPC Status Codes.

Error Codes

-3204`XX` `DEADLINE_EXCEEDED` errors

-320400 `UNINITIALIZED_CHAIN_DATABASE`

Happens when a chain database is not initialized yet.

-3205`XX` `NOT_FOUND` errors

-320500 `SKIPPED_DATA`

Happens when we try to retrieve data that is not available (pruned). It may also happen if we erroneously skip data, that was not considered a conflict, if the DB is corrupted.

-320501 `UNKNOWN_CHAIN`

Happens when a chain is unknown, not in the dependency set.

-3206`XX` `ALREADY_EXISTS` errors

-320600 `CONFLICTING_DATA`

Happens when we know for sure that there is different canonical data.

-320601 `INEFFECTIVE_DATA`

Happens when data is accepted as compatible, but did not change anything. This happens when a node is deriving an L2 block we already know of being derived from the given source, but without path to skip forward to newer source blocks without doing the known derivation work first.

OP Stack Specification