diff --git a/specs/interop/managed-node.md b/specs/interop/managed-node.md index b2a0de899..399d7639e 100644 --- a/specs/interop/managed-node.md +++ b/specs/interop/managed-node.md @@ -1,3 +1,5 @@ +> **Note:** This document has been moved to [specs/protocol/rpc/rpc-interop.md](../protocol/rpc/rpc-interop.md) + # Control flow between Supervisor and Managed node diff --git a/specs/interop/supervisor.md b/specs/interop/supervisor.md index 916414013..883314702 100644 --- a/specs/interop/supervisor.md +++ b/specs/interop/supervisor.md @@ -1,3 +1,5 @@ +> **Note:** This document has been moved to [specs/protocol/rpc/rpc-supervisor.md](../protocol/rpc/rpc-supervisor.md) + # Supervisor diff --git a/specs/protocol/SUMMURY.md b/specs/protocol/SUMMURY.md new file mode 100644 index 000000000..423b946bb --- /dev/null +++ b/specs/protocol/SUMMURY.md @@ -0,0 +1,5 @@ +- [RPC] + - [Supervisor RPC](protocol/rpc/rpc-supervisor.md) + - [Interop RPC](protocol/rpc/rpc-interop.md) + - [Optimism RPC](protocol/rpc/rpc-optimism.md) + - [Engine RPC](protocol/rpc/rpc-engine.md) diff --git a/specs/protocol/exec-engine.md b/specs/protocol/exec-engine.md index f9502e9ae..6fe0c4f5f 100644 --- a/specs/protocol/exec-engine.md +++ b/specs/protocol/exec-engine.md @@ -201,6 +201,8 @@ The two base fee values and their respective scalars can be accessed in two inte ## Engine API +> **Note:** This section has been moved to [specs/protocol/rpc/rpc-engine.md](rpc/rpc-engine.md) + ### `engine_forkchoiceUpdatedV2` This updates which L2 blocks the engine considers to be canonical (`forkchoiceState` argument), diff --git a/specs/protocol/rollup-node.md b/specs/protocol/rollup-node.md index 5794b9367..1e15a6f2c 100644 --- a/specs/protocol/rollup-node.md +++ b/specs/protocol/rollup-node.md @@ -65,66 +65,7 @@ For a complete specification of the L2 block derivation, refer to the [L2 block ## L2 Output RPC method -The Rollup node has its own RPC method, `optimism_outputAtBlock` which returns a 32 -byte hash corresponding to the [L2 output root](proposals.md#l2-output-commitment-construction). - -### Structures - -These define the types used by rollup node API methods. -The types defined here are extended from the [engine API specs][engine-structures]. - -#### BlockID - -- `hash`: `DATA`, 32 Bytes -- `number`: `QUANTITY`, 64 Bits - -#### L1BlockRef - -- `hash`: `DATA`, 32 Bytes -- `number`: `QUANTITY`, 64 Bits -- `parentHash`: `DATA`, 32 Bytes -- `timestamp`: `QUANTITY`, 64 Bits - -#### L2BlockRef - -- `hash`: `DATA`, 32 Bytes -- `number`: `QUANTITY`, 64 Bits -- `parentHash`: `DATA`, 32 Bytes -- `timestamp`: `QUANTITY`, 64 Bits -- `l1origin`: `BlockID` -- `sequenceNumber`: `QUANTITY`, 64 Bits - distance to first block of epoch - -#### SyncStatus - -Represents a snapshot of the rollup driver. - -- `current_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref). -- `current_l1_finalized`: `Object` - instance of [`L1BlockRef`](#l1blockref). -- `head_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref). -- `safe_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref). -- `finalized_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref). -- `unsafe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). -- `safe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). -- `finalized_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). -- `pending_safe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). -- `queued_unsafe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). - -### Output Method API - -The input and return types here are as defined by the [engine API specs][engine-structures]. - -[engine-structures]: https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#structures - -- method: `optimism_outputAtBlock` -- params: - 1. `blockNumber`: `QUANTITY`, 64 bits - L2 integer block number. -- returns: - 1. `version`: `DATA`, 32 Bytes - the output root version number, beginning with 0. - 1. `outputRoot`: `DATA`, 32 Bytes - the output root. - 1. `blockRef`: `Object` - instance of [`L2BlockRef`](#l2blockref). - 1. `withdrawalStorageRoot`: 32 bytes - storage root of the `L2toL1MessagePasser` contract. - 1. `stateRoot`: `DATA`: 32 bytes - the state root. - 1. `syncStatus`: `Object` - instance of [`SyncStatus`](#syncstatus). +> **Note:** This section has been moved to [specs/protocol/rpc/rpc-optimism.md](rpc/rpc-optimism.md) ## Protocol Version tracking diff --git a/specs/protocol/rpc/rpc-engine.md b/specs/protocol/rpc/rpc-engine.md new file mode 100644 index 000000000..7098aaede --- /dev/null +++ b/specs/protocol/rpc/rpc-engine.md @@ -0,0 +1,196 @@ +# Engine RPC + +> **Moved from:** [specs/protocol/exec-engine.md](../exec-engine.md) + +## Engine API + +### `engine_forkchoiceUpdatedV2` + +This updates which L2 blocks the engine considers to be canonical (`forkchoiceState` argument), +and optionally initiates block production (`payloadAttributes` argument). + +Within the rollup, the types of forkchoice updates translate as: + +- `headBlockHash`: block hash of the head of the canonical chain. Labeled `"unsafe"` in user JSON-RPC. + Nodes may apply L2 blocks out of band ahead of time, and then reorg when L1 data conflicts. +- `safeBlockHash`: block hash of the canonical chain, derived from L1 data, unlikely to reorg. +- `finalizedBlockHash`: irreversible block hash, matches lower boundary of the dispute period. + +To support rollup functionality, one backwards-compatible change is introduced +to [`engine_forkchoiceUpdatedV2`][engine_forkchoiceUpdatedV2]: the extended `PayloadAttributesV2` + +#### Extended PayloadAttributesV2 + +[`PayloadAttributesV2`][PayloadAttributesV2] is extended to: + +```js +PayloadAttributesV2: { + timestamp: QUANTITY + prevRandao: DATA (32 bytes) + suggestedFeeRecipient: DATA (20 bytes) + withdrawals: array of WithdrawalV1 + transactions: array of DATA + noTxPool: bool + gasLimit: QUANTITY or null +} +``` + +The type notation used here refers to the [HEX value encoding] used by the [Ethereum JSON-RPC API +specification][JSON-RPC-API], as this structure will need to be sent over JSON-RPC. `array` refers +to a JSON array. + +Each item of the `transactions` array is a byte list encoding a transaction: `TransactionType || +TransactionPayload` or `LegacyTransaction`, as defined in [EIP-2718][eip-2718]. +This is equivalent to the `transactions` field in [`ExecutionPayloadV2`][ExecutionPayloadV2] + +The `transactions` field is optional: + +- If empty or missing: no changes to engine behavior. The sequencers will (if enabled) build a block + by consuming transactions from the transaction pool. +- If present and non-empty: the payload MUST be produced starting with this exact list of transactions. + The [rollup driver][rollup-driver] determines the transaction list based on deterministic L1 inputs. + +The `noTxPool` is optional as well, and extends the `transactions` meaning: + +- If `false`, the execution engine is free to pack additional transactions from external sources like the tx pool + into the payload, after any of the `transactions`. This is the default behavior a L1 node implements. +- If `true`, the execution engine must not change anything about the given list of `transactions`. + +If the `transactions` field is present, the engine must execute the transactions in order and return `STATUS_INVALID` +if there is an error processing the transactions. It must return `STATUS_VALID` if all of the transactions could +be executed without error. **Note**: The state transition rules have been modified such that deposits will never fail +so if `engine_forkchoiceUpdatedV2` returns `STATUS_INVALID` it is because a batched transaction is invalid. + +The `gasLimit` is optional w.r.t. compatibility with L1, but required when used as rollup. +This field overrides the gas limit used during block-building. +If not specified as rollup, a `STATUS_INVALID` is returned. + +[rollup-driver]: rollup-node.md + +### `engine_forkchoiceUpdatedV3` + +See [`engine_forkchoiceUpdatedV2`](#engine_forkchoiceupdatedv2) for a description of the forkchoice updated method. +`engine_forkchoiceUpdatedV3` **must only be called with Ecotone payload.** + +To support rollup functionality, one backwards-compatible change is introduced +to [`engine_forkchoiceUpdatedV3`][engine_forkchoiceUpdatedV3]: the extended `PayloadAttributesV3` + +#### Extended PayloadAttributesV3 + +[`PayloadAttributesV3`][PayloadAttributesV3] is extended to: + +```js +PayloadAttributesV3: { + timestamp: QUANTITY + prevRandao: DATA (32 bytes) + suggestedFeeRecipient: DATA (20 bytes) + withdrawals: array of WithdrawalV1 + parentBeaconBlockRoot: DATA (32 bytes) + transactions: array of DATA + noTxPool: bool + gasLimit: QUANTITY or null + eip1559Params: DATA (8 bytes) or null +} +``` + +The requirements of this object are the same as extended [`PayloadAttributesV2`](#extended-payloadattributesv2) with +the addition of `parentBeaconBlockRoot` which is the parent beacon block root from the L1 origin block of the L2 block. + +Starting at Ecotone, the `parentBeaconBlockRoot` must be set to the L1 origin `parentBeaconBlockRoot`, +or a zero `bytes32` if the Dencun functionality with `parentBeaconBlockRoot` is not active on L1. + +Starting with Holocene, the `eip1559Params` field must encode the EIP1559 parameters. It must be `null` before. +See [Dynamic EIP-1559 Parameters](holocene/exec-engine.md#dynamic-eip-1559-parameters) for details. + +### `engine_newPayloadV2` + +No modifications to [`engine_newPayloadV2`][engine_newPayloadV2]. +Applies a L2 block to the engine state. + +### `engine_newPayloadV3` + +[`engine_newPayloadV3`][engine_newPayloadV3] applies an Ecotone L2 block to the engine state. There are no +modifications to this API. +`engine_newPayloadV3` **must only be called with Ecotone payload.** + +The additional parameters should be set as follows: + +- `expectedBlobVersionedHashes` MUST be an empty array. +- `parentBeaconBlockRoot` MUST be the parent beacon block root from the L1 origin block of the L2 block. + +### `engine_newPayloadV4` + +[`engine_newPayloadV4`][engine_newPayloadV4] applies an Isthmus L2 block to the engine state. +The `ExecutionPayload` parameter will contain an extra field, `withdrawalsRoot`, after the Isthmus hardfork. + +`engine_newPayloadV4` **must only be called with Isthmus payload.** + +The additional parameters should be set as follows: + +- `executionRequests` MUST be an empty array. + +### `engine_getPayloadV2` + +No modifications to [`engine_getPayloadV2`][engine_getPayloadV2]. +Retrieves a payload by ID, prepared by `engine_forkchoiceUpdatedV2` when called with `payloadAttributes`. + +### `engine_getPayloadV3` + +[`engine_getPayloadV3`][engine_getPayloadV3] retrieves a payload by ID, prepared by `engine_forkchoiceUpdatedV3` +when called with `payloadAttributes`. +`engine_getPayloadV3` **must only be called with Ecotone payload.** + +#### Extended Response + +The [response][GetPayloadV3Response] is extended to: + +```js +{ + executionPayload: ExecutionPayload + blockValue: QUANTITY + blobsBundle: BlobsBundle + shouldOverrideBuilder: BOOLEAN + parentBeaconBlockRoot: DATA (32 bytes) +} +``` + +[GetPayloadV3Response]: https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#response-2 + +In Ecotone it MUST be set to the parentBeaconBlockRoot from the L1 Origin block of the L2 block. + +### `engine_getPayloadV4` + +[`engine_getPayloadV4`][engine_getPayloadV4] retrieves a payload by ID, prepared by `engine_forkchoiceUpdatedV3` +when called with `payloadAttributes`. +`engine_getPayloadV4` **must only be called with Isthmus payload.** + +### `engine_signalSuperchainV1` + +Optional extension to the Engine API. Signals superchain information to the Engine: +V1 signals which protocol version is recommended and required. + +Types: + +```javascript +SuperchainSignal: { + recommended: ProtocolVersion; + required: ProtocolVersion; +} +``` + +`ProtocolVersion`: encoded for RPC as defined in +[Protocol Version format specification](superchain-upgrades.md#protocol-version-format). + +Parameters: + +- `signal`: `SuperchainSignal`, the signaled superchain information. + +Returns: + +- `ProtocolVersion`: the latest supported OP-Stack protocol version of the execution engine. + +The execution engine SHOULD warn the user when the recommended version is newer than +the current version supported by the execution engine. + +The execution engine SHOULD take safety precautions if it does not meet the required protocol version. +This may include halting the engine, with consent of the execution engine operator. diff --git a/specs/protocol/rpc/rpc-interop.md b/specs/protocol/rpc/rpc-interop.md new file mode 100644 index 000000000..a33a101d5 --- /dev/null +++ b/specs/protocol/rpc/rpc-interop.md @@ -0,0 +1,325 @@ +# Interop RPC + +> **Moved from:** [specs/interop/managed-node.md](../../interop/managed-node.md) + +# Control flow between Supervisor and Managed node + + + +**Table of Contents** + +- [Authentication](#authentication) +- [Node `->` Supervisor](#node---supervisor) + - [Reset](#reset) + - [UnsafeBlock](#unsafeblock) + - [DerivationUpdate](#derivationupdate) + - [DerivationOriginUpdate](#derivationoriginupdate) + - [ExhaustL1](#exhaustl1) + - [ReplaceBlock](#replaceblock) +- [Supervisor `->` Node](#supervisor---node) + - [Control Signals](#control-signals) + - [interop_pullEvent](#interop_pullevent) + - [interop_anchorPoint (Soon to be deprecated)](#interop_anchorpoint-soon-to-be-deprecated) + - [interop_invalidateBlock](#interop_invalidateblock) + - [interop_provideL1](#interop_providel1) + - [interop_reset](#interop_reset) + - [DB](#db) + - [interop_updateCrossSafe](#interop_updatecrosssafe) + - [interop_updateCrossUnsafe](#interop_updatecrossunsafe) + - [interop_updateFinalized](#interop_updatefinalized) + - [Sync Methods](#sync-methods) + - [interop_fetchReceipts](#interop_fetchreceipts) + - [interop_l2BlockRefByTimestamp](#interop_l2blockrefbytimestamp) + - [interop_blockRefByNumber](#interop_blockrefbynumber) + - [interop_chainID](#interop_chainid) + - [interop_outputV0AtTimestamp](#interop_outputv0attimestamp) + - [interop_pendingOutputV0AtTimestamp](#interop_pendingoutputv0attimestamp) +- [Types](#types) + + + +This section is based on the control flow between `managed` node and `supervisor`, described +[here](https://github.com/ethereum-optimism/optimism/blob/develop/op-supervisor/README.md). + +Whether the node and supervisor use a `pubsub` pattern or pulling events over HTTP is up to the implementation detail. +Both cases should be handled because `op-node` and `op-supervisor` can be using different client implementations. +In both the case, we use `event` based signaling of new information. Ideally, this should be done using bi-directional +RPC using web sockets. + +## Authentication + +Supervisor [initiates the connection](https://github.com/ethereum-optimism/optimism/issues/13182) to the node in order +to manage it. As supervisor does the dial in, for our context, it is the client and the node is the server. For the web +socket authentication, only the initial request is authenticated and a live socket is opened. +No re-authentication is needed during the lifetime of this socket. + +The authentication is performed using `JWT`. The construction of jwt is the same to the one +[used in Engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md). The path of +the file containing the jwt secret should be provided to the supervisor instance. + +## Node `->` Supervisor + +Events that a supervisor should subscribe to, originating from the node, handled by the supervisor. For the used types, +refer [this](#Types) section. + +Every event sent from the node is of type `ManagedEvent` whose fields are populated with the events that occurred. All +non-null events are sent at once. The other fields are omitted. + +```javascript +ManagedEvent { + Reset, + UnsafeBlock, + DerivationUpdate, + DerivationOriginUpdate, + ExhaustL1, + ReplaceBlock +} +``` + +Each field item is an event of the type as described below: + +### Reset + +```javascript +Reset: string +``` + +This is emitted when the node has determined that it needs a reset. It tells the supervisor to send the +[interop_reset](#interop_reset) event with the required parameters. + +### UnsafeBlock + +```javascript +UnsafeBlock: BlockRef //L2's BlockRef +``` + +New L2 unsafe block was processed, updating local-unsafe head. + +### DerivationUpdate + +```javascript +DerivationUpdate: DerivedBlockRefPair { + source: BlockRef //L1 + derived: BlockRef //Last L2 BlockRef +} +``` + +Signals that an L2 block is considered local-safe. + +### DerivationOriginUpdate + +```javascript +DerivationOriginUpdate: BlockRef +``` + +Signals that an L2 block is now local-safe because of the given L1 traversal. This would be accompanied with +`DerivationUpdate`. + +### ExhaustL1 + +```javascript +ExhaustL1: DerivedBlockRefPair { + source: BlockRef //Last L1 + derived: BlockRef //Last L2 BlockRef +} +``` + +Emitted when no more L1 Blocks are available. Ready to take new L1 blocks from supervisor. + +### ReplaceBlock + +```javascript +ReplaceBlock: BlockReplacement +``` + +Emitted when a block gets replaced for any reason. + +## Supervisor `->` Node + +Messages that a node should watch for, originating from supervisor, handled by node. This also includes control signals +that the supervisor can ask the node to perform. For the used types, refer [this](#types) section. + +*Note: Headings represent the actual name of the methods over RPC, payload is the serialized version of the given type.* + +`-> indicates return` + +### Control Signals + +RPC calls that are relevant to managing the node via supervisor. These are directly called by the supervisor. + +#### interop_pullEvent + +```javascript +payload() -> One of the event from node events (previous section). +``` + +When websocket is not available, supervisor can use this method to get the next event from node. + +#### interop_anchorPoint (Soon to be deprecated) + +```javascript +payload() -> DerivedBlockRefPair { + source: L1 BlockRef that rollup starts after (no derived transaction) + derived: L2 BlockRef that rollup starts from (no txn, pre-configuration state) +} +``` + +Returns the genesis block ref for L1 and L2 that the current node used as anchor point. +This method will soon be removed in favor of fetching the information from a supervisor specific rollup config. +(Once a spec is created about [this](https://github.com/ethereum-optimism/optimism/pull/16038) PR.) + +#### interop_invalidateBlock + +```javascript +payload (BlockSeal) //L2's Block +``` + +Based on some dependency or L1 changes, supervisor can instruct the L2 to invalidate a specific block. + +*(Suggestion: BlockSeal can be replaced with Hash, as only that is being used in op-node.)* + +#### interop_provideL1 + +```javascript +payload (BlockRef) //L1 Block +``` + +Supervisor sends the next L1 block to the node. Ideally sent after the node emits `exhausted-l1`. + +#### interop_reset + +```javascript +payload (lUnsafe, xUnsafe, lSafe, xSafe, finalized: BlockID) +``` + +Forces a reset to a specific local-unsafe/local-safe/finalized starting point only if the blocks did exist. Resets may +override local-unsafe, to reset the very end of the chain. Resets may override local-safe, since post-interop we need +the local-safe block derivation to continue. + +### DB + +RPC calls that a node should watch for, originating from supervisor that is called on DB updates for relevant block +safety info for a given chain and block. + +#### interop_updateCrossSafe + +```javascript +payload (derived: BlockID, source: BlockID) +``` + +Signal that a block can be promoted to cross-safe. + +#### interop_updateCrossUnsafe + +```javascript +payload (BlockID) +``` + +Signal that a block can be promoted to cross-unsafe. + +#### interop_updateFinalized + +```javascript +payload (BlockID) +``` + +Signal that a block can be marked as finalized. + +### Sync Methods + +RPC methods that are relevant for syncing the supervisor. These are directly called by the supervisor for fetching L2 +data. + +#### interop_fetchReceipts + +```javascript +payload (Hash) -> Receipts //L2 block hash +``` + +Fetches all transaction receipts in a given L2 block. + +#### interop_l2BlockRefByTimestamp + +```javascript +payload (uint64) -> BlockRef +``` + +Fetches L2 BlockRef of the block that occurred at given timestamp + +#### interop_blockRefByNumber + +```javascript +payload (uint64) -> BlockRef +``` + +Fetches the BlockRef from a given L2 block number + +#### interop_chainID + +```javascript +payload () -> string +``` + +Returns chainID of the L2 + +#### interop_outputV0AtTimestamp + +```javascript +payload (uint64) -> OutputV0 +``` + +Returns the state root, storage root and block hash for a given timestamp + +#### interop_pendingOutputV0AtTimestamp + +```javascript +payload (uint64) -> OutputV0 +``` + +Returns the optimistic output of the invalidated block from replacement + +**Note:** All events should return relevant error(s) in case of unsuccessful calls. + +## Types + +```javascript +Hash: 0x prefixed, hex encoded, fixed-length string representing 32 bytes + +BlockID { + hash: Hash + number: uint64 +} + +BlockSeal { + hash: Hash + number: uint64 + timestamp: uint64 +} + +BlockRef { + hash: Hash + number: uint64 + parentHash: Hash + timestamp: uint64 +} + +DerivedBlockRefPair { + source: BlockRef + derived: BlockRef +} + +BlockReplacement { + replacement: BlockRef + invalidated: Hash +} + +Receipts -> []Receipt + +Receipt -> op-geth/core/types/receipt + +OutputV0 { + stateRoot: Hash + messagePasserStorageRoot: Hash + blockHash: Hash +} +``` diff --git a/specs/protocol/rpc/rpc-optimism.md b/specs/protocol/rpc/rpc-optimism.md new file mode 100644 index 000000000..c91172684 --- /dev/null +++ b/specs/protocol/rpc/rpc-optimism.md @@ -0,0 +1,66 @@ +# Optimism RPC + +> **Moved from:** [specs/protocol/rollup-node.md](../rollup-node.md) + +## L2 Output RPC method + +The Rollup node has its own RPC method, `optimism_outputAtBlock` which returns a 32 +byte hash corresponding to the [L2 output root](proposals.md#l2-output-commitment-construction). + +### Structures + +These define the types used by rollup node API methods. +The types defined here are extended from the [engine API specs][engine-structures]. + +#### BlockID + +- `hash`: `DATA`, 32 Bytes +- `number`: `QUANTITY`, 64 Bits + +#### L1BlockRef + +- `hash`: `DATA`, 32 Bytes +- `number`: `QUANTITY`, 64 Bits +- `parentHash`: `DATA`, 32 Bytes +- `timestamp`: `QUANTITY`, 64 Bits + +#### L2BlockRef + +- `hash`: `DATA`, 32 Bytes +- `number`: `QUANTITY`, 64 Bits +- `parentHash`: `DATA`, 32 Bytes +- `timestamp`: `QUANTITY`, 64 Bits +- `l1origin`: `BlockID` +- `sequenceNumber`: `QUANTITY`, 64 Bits - distance to first block of epoch + +#### SyncStatus + +Represents a snapshot of the rollup driver. + +- `current_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref). +- `current_l1_finalized`: `Object` - instance of [`L1BlockRef`](#l1blockref). +- `head_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref). +- `safe_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref). +- `finalized_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref). +- `unsafe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). +- `safe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). +- `finalized_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). +- `pending_safe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). +- `queued_unsafe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref). + +### Output Method API + +The input and return types here are as defined by the [engine API specs][engine-structures]. + +[engine-structures]: https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#structures + +- method: `optimism_outputAtBlock` +- params: + 1. `blockNumber`: `QUANTITY`, 64 bits - L2 integer block number. +- returns: + 1. `version`: `DATA`, 32 Bytes - the output root version number, beginning with 0. + 1. `outputRoot`: `DATA`, 32 Bytes - the output root. + 1. `blockRef`: `Object` - instance of [`L2BlockRef`](#l2blockref). + 1. `withdrawalStorageRoot`: 32 bytes - storage root of the `L2toL1MessagePasser` contract. + 1. `stateRoot`: `DATA`: 32 bytes - the state root. + 1. `syncStatus`: `Object` - instance of [`SyncStatus`](#syncstatus). diff --git a/specs/protocol/rpc/rpc-supervisor.md b/specs/protocol/rpc/rpc-supervisor.md new file mode 100644 index 000000000..53f4206c6 --- /dev/null +++ b/specs/protocol/rpc/rpc-supervisor.md @@ -0,0 +1,69 @@ +# Supervisor RPC + +> **Moved from:** [specs/interop/supervisor.md](../../interop/supervisor.md) + +# Supervisor + + + +**Table of Contents** + +- [Overview](#overview) +- [RPC API](#rpc-api) + - [Common types](#common-types) + - [`Identifier`](#identifier) + - [`Message`](#message) + - [`ExecutingDescriptor`](#executingdescriptor) + - [`HexUint64`](#hexuint64) + - [`Int`](#int) + - [`ChainID`](#chainid) + - [`Hash`](#hash) + - [`Bytes`](#bytes) + - [`BlockID`](#blockid) + - [`BlockRef`](#blockref) + - [`DerivedIDPair`](#derivedidpair) + - [`ChainRootInfo`](#chainrootinfo) + - [`SupervisorSyncStatus`](#supervisorsyncstatus) + - [`SupervisorChainSyncStatus`](#supervisorchainsyncstatus) + - [`SuperRootResponse`](#superrootresponse) + - [`SafetyLevel`](#safetylevel) + - [Methods](#methods) + - [`supervisor_crossDerivedToSource`](#supervisor_crossderivedtosource) + - [`supervisor_localUnsafe`](#supervisor_localunsafe) + - [`supervisor_crossSafe`](#supervisor_crosssafe) + - [`supervisor_finalized`](#supervisor_finalized) + - [`supervisor_finalizedL1`](#supervisor_finalizedl1) + - [`supervisor_superRootAtTimestamp`](#supervisor_superrootattimestamp) + - [`supervisor_syncStatus`](#supervisor_syncstatus) + - [`supervisor_allSafeDerivedAt`](#supervisor_allsafederivedat) + - [`supervisor_checkAccessList`](#supervisor_checkaccesslist) + - [Access-list contents](#access-list-contents) + - [Access-list execution context](#access-list-execution-context) + - [Access-list checks](#access-list-checks) + - [`supervisor_checkAccessList` contents](#supervisor_checkaccesslist-contents) + - [Errors](#errors) + - [JSON-RPC Error Codes](#json-rpc-error-codes) + - [Error Code Structure](#error-code-structure) + - [Protocol Specific Error Codes](#protocol-specific-error-codes) + - [`-3204XX` `DEADLINE_EXCEEDED` errors](#-3204xx-deadline_exceeded-errors) + - [`-320400` `UNINITIALIZED_CHAIN_DATABASE`](#-320400-uninitialized_chain_database) + - [`-3205XX` `NOT_FOUND` errors](#-3205xx-not_found-errors) + - [`-320500` `SKIPPED_DATA`](#-320500-skipped_data) + - [`-320501` `UNKNOWN_CHAIN`](#-320501-unknown_chain) + - [`-3206XX` `ALREADY_EXISTS` errors](#-3206xx-already_exists-errors) + - [`-320600` `CONFLICTING_DATA`](#-320600-conflicting_data) + - [`-320601` `INEFFECTIVE_DATA`](#-320601-ineffective_data) + - [`-3209XX` `FAILED_PRECONDITION` errors](#-3209xx-failed_precondition-errors) + - [`-320900` `OUT_OF_ORDER`](#-320900-out_of_order) + - [`-320901` `AWAITING_REPLACEMENT_BLOCK`](#-320901-awaiting_replacement_block) + - [`-3210XX` `ABORTED` errors](#-3210xx-aborted-errors) + - [`-321000` `ITER_STOP`](#-321000-iter_stop) + - [`-3211XX` `OUT_OF_RANGE` errors](#-3211xx-out_of_range-errors) + - [`-321100` `OUT_OF_SCOPE`](#-321100-out_of_scope) + - [`-3212XX` `UNIMPLEMENTED` errors](#-3212xx-unimplemented-errors) + - [`-321200` `CANNOT_GET_PARENT_OF_FIRST_BLOCK_IN_DB`](#-321200-cannot_get_parent_of_first_block_in_db) + - [`-3214XX` `UNAVAILABLE` errors](#-3214xx-unavailable-errors) + - [`-321401` `FUTURE_DATA`](#-321401-future_data) + - [`-3215XX` `DATA_LOSS` errors](#-3215xx-data_loss-errors) + - [`-321500` `MISSED_DATA`](#-321500-missed_data) + - [`-321501` `DATA_CORRUPTION`](#-321501-data_corruption)