Merge pull request #6388 from ethereum-optimism/superchain-upgrades

specs: superchain target and protocol version

specs/README.md

@@ -15,7 +15,7 @@ that maintains 1:1 compatibility with Ethereum.
 - [Rollup Node](rollup-node.md)
 - [Rollup Node P2p](rollup-node-p2p.md)
 - [L2 Chain Derivation](derivation.md)
-- [Network Upgrades](network-upgrades.md)
+- [Superchain Upgrades](superchain-upgrades.md)
 - [System Config](system_config.md)
 - [Batch Submitter](batcher.md)
 - [Guaranteed Gas Market](guaranteed-gas-market.md)

specs/exec-engine.md

@@ -16,6 +16,7 @@
     - [Extended PayloadAttributesV1](#extended-payloadattributesv1)
   - [`engine_newPayloadV1`](#engine_newpayloadv1)
   - [`engine_getPayloadV1`](#engine_getpayloadv1)
+  - [`engine_signalSuperchainV1`](#engine_signalsuperchainv1)
 - [Networking](#networking)
 - [Sync](#sync)
   - [Happy-path sync](#happy-path-sync)
@@ -198,6 +199,37 @@ Applies a L2 block to the engine state.
 No modifications to [`engine_getPayloadV1`][engine_getPayloadV1].
 Retrieves a payload by ID, prepared by `engine_forkchoiceUpdatedV1` when called with `payloadAttributes`.
 
+### `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.
+
 ## Networking
 
 The execution engine can acquire all data through the rollup node, as derived from L1:

specs/network-upgrades.md

-# Network Upgrades
-
-Network upgrades, also known as forks or hardforks, implement consensus-breaking changes.
-These changes are transitioned into deterministically across all nodes through an activation rule.
-
-This document lists the network upgrades of the OP Stack, starting after the Bedrock upgrade.
-Prospective upgrades may be listed as proposals, but are not governed through these specifications.
-
-Activation rule parameters of network upgrades are configured in respective chain configurations,
-and not part of this specification.
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**
-
-- [Activation rules](#activation-rules)
-  - [L2 Block-number based activation](#l2-block-number-based-activation)
-  - [L2 Block-timestamp based activation](#l2-block-timestamp-based-activation)
-- [Post-Bedrock Network upgrades](#post-bedrock-network-upgrades)
-  - [Regolith](#regolith)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
-## Activation rules
-
-The below L2-block based activation rules may be applied in two contexts:
-
-- The rollup node, specified through the rollup configuration (known as `rollup.json`),
-  referencing L2 blocks (or block input-attributes) that pass through the derivation pipeline.
-- The execution engine, specified through the chain configuration (known as the `config` part of `genesis.json`),
-  referencing blocks or input-attributes that are part of, or applied to, the L2 chain.
-
-### L2 Block-number based activation
-
-Activation rule: `x != null && x >= upgradeNumber`
-
-Starting at, and including, the L2 `block` with `block.number == x`, the upgrade rules apply.
-If the upgrade block-number `x` is not specified in the configuration, the upgrade is ignored.
-
-This applies to the L2 block number, not to the L1-origin block number.
-This means that an L2 upgrade may be inactive, and then active, without changing the L1-origin.
-
-This block number based method has commonly been used in L1 up until the Bellatrix/Paris upgrade, a.k.a. The Merge,
-which was upgraded through special rules.
-
-### L2 Block-timestamp based activation
-
-Activation rule: `x != null && x >= upgradeTime`
-
-Starting at, and including, the L2 `block` with `block.timestamp == x`, the upgrade rules apply.
-If the upgrade block-timestamp `x` is not specified in the configuration, the upgrade is ignored.
-
-This applies to the L2 block timestamp, not to the L1-origin block timestamp.
-This means that an L2 upgrade may be inactive, and then active, without changing the L1-origin.
-
-This timestamp based method has become the default on L1 after the Bellatrix/Paris upgrade, a.k.a. The Merge,
-because it can be planned in accordance with beacon-chain epochs and slots.
-
-Note that the L2 version is not limited to timestamps that match L1 beacon-chain slots or epochs.
-A timestamp may be chosen to be synchronous with a specific slot or epoch on L1,
-but the matching L1-origin information may not be present at the time of activation on L2.
-
-## Post-Bedrock Network upgrades
-
-### Regolith
-
-The Regolith upgrade, named after a material best described as "deposited dust on top of a layer of bedrock",
-implements minor changes to deposit processing, based on reports of the Sherlock Audit-contest and findings in
-the Bedrock Optimism Goerli testnet.
-
-Summary of changes:
-
-- The `isSystemTx` boolean is disabled, system transactions now use the same gas accounting rules as regular deposits.
-- The actual deposit gas-usage is recorded in the receipt of the deposit transaction,
-  and subtracted from the L2 block gas-pool.
-  Unused gas of deposits is not refunded with ETH however, as it is burned on L1.
-- The `nonce` value of the deposit sender account, before the transaction state-transition, is recorded in a new
-  optional field (`depositNonce`), extending the transaction receipt (i.e. not present in pre-Regolith receipts).
-- The recorded deposit `nonce` is used to correct the transaction and receipt metadata in RPC responses,
-  including the `contractAddress` field of deposits that deploy contracts.
-- The `gas` and `depositNonce` data is committed to as part of the consensus-representation of the receipt,
-  enabling the data to be safely synced between independent L2 nodes.
-- The L1-cost function was corrected to more closely match pre-Bedrock behavior.
-
-The [deposit specification](./deposits.md) specifies the deposit changes of the Regolith upgrade in more detail.
-The [execution engine specification](./exec-engine.md) specifies the L1 cost function difference.
-
-The Regolith upgrade uses a *L2 block-timestamp* activation-rule, and is specified in both the
-rollup-node (`regolith_time`) and execution engine (`config.regolithTime`).

specs/rollup-node.md

@@ -24,6 +24,7 @@ currently only concerned with the specification of the rollup driver.
   - [Derivation](#derivation)
 - [L2 Output RPC method](#l2-output-rpc-method)
   - [Output Method API](#output-method-api)
+- [Protocol Version tracking](#protocol-version-tracking)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -72,3 +73,20 @@ The input and return types here are as defined by the [engine API specs][engine-
 - returns:
   1. `version`: `DATA`, 32 Bytes - the output root version number, beginning with 0.
   1. `l2OutputRoot`: `DATA`, 32 Bytes - the output root.
+
+## Protocol Version tracking
+
+The rollup-node should monitor the recommended and required protocol version by monitoring
+the Protocol Version contract on L1, as specified in the [Superchain Version Signaling specifications].
+
+[Superchain Version Signaling specifications]: ./superchain-upgrades.md#superchain-version-signaling
+
+This can be implemented through polling in the [Driver](#driver) loop.
+After polling the Protocol Version, the rollup node SHOULD communicate it with the execution-engine through an
+[`engine_signalSuperchainV1`](./exec-engine.md#enginesignalsuperchainv1) call.
+
+The rollup node SHOULD warn the user when the recommended version is newer than
+the current version supported by the rollup node.
+
+The rollup node SHOULD take safety precautions if it does not meet the required protocol version.
+This may include halting the engine, with consent of the rollup node operator.