From 20c5b46a43f908a9713afd127669b054efb29a45 Mon Sep 17 00:00:00 2001 From: Julian Meyer Date: Fri, 17 Jan 2025 12:34:14 -0800 Subject: [PATCH 1/5] feat: update spec to use v4 payload methods for isthmus --- specs/protocol/derivation.md | 10 +++++++--- specs/protocol/exec-engine.md | 19 +++++++++++++++++++ specs/protocol/isthmus/exec-engine.md | 6 +++--- 3 files changed, 29 insertions(+), 6 deletions(-) diff --git a/specs/protocol/derivation.md b/specs/protocol/derivation.md index 138353dad..9dda3af63 100644 --- a/specs/protocol/derivation.md +++ b/specs/protocol/derivation.md @@ -748,12 +748,13 @@ To interact with the engine, the [execution engine API][exec-engine] is used, wi - `engine_newPayload` - [`engine_newPayloadV2`] — executes a Bedrock/Canyon/Delta execution payload to create a block. - [`engine_newPayloadV3`] — executes an Ecotone execution payload to create a block. + - [`engine_newPayloadV4`] - executes an Isthmus execution payload to create a block. -The current version of `op-node` uses the `v3` Engine API RPC methods as well as `engine_newPayloadV2`, due to -`engine_newPayloadV3` only supporting Ecotone execution payloads. Both `engine_forkchoiceUpdatedV3` and +The current version of `op-node` uses the `v4` Engine API RPC methods as well as `engine_newPayloadV3`, due to +`engine_newPayloadV4` only supporting Isthmus execution payloads. Both `engine_forkchoiceUpdatedV3` and `engine_getPayloadV3` are backwards compatible with Bedrock, Canyon & Delta payloads. -Prior versions of `op-node` used `v2` and `v1` methods. +Prior versions of `op-node` used `v3`, `v2` and `v1` methods. [`engine_forkchoiceUpdatedV2`]: exec-engine.md#engine_forkchoiceupdatedv2 [`engine_forkchoiceUpdatedV3`]: exec-engine.md#engine_forkchoiceupdatedv3 @@ -761,6 +762,7 @@ Prior versions of `op-node` used `v2` and `v1` methods. [`engine_getPayloadV3`]: exec-engine.md#engine_getpayloadv3 [`engine_newPayloadV2`]: exec-engine.md#engine_newpayloadv2 [`engine_newPayloadV3`]: exec-engine.md#engine_newpayloadv3 +[`engine_newPayloadV4`]: exec-engine.md#engine_newpayloadv4 The execution payload is an object of type [`ExecutionPayloadV3`][eth-payload]. @@ -887,6 +889,8 @@ The payload is then processed with a sequence of: - Ecotone Payloads - `engine_newPayloadV3`: process the payload. It does not become canonical yet. - `engine_forkchoiceUpdatedV3`: make the payload the canonical unsafe L2 head, and keep the safe/finalized L2 heads. +- Isthmus Payloads + - `engine_newPayloadV4`: process the payload. It does not become canonical yet. Engine API Error handling: diff --git a/specs/protocol/exec-engine.md b/specs/protocol/exec-engine.md index 57a35345f..ce1120641 100644 --- a/specs/protocol/exec-engine.md +++ b/specs/protocol/exec-engine.md @@ -21,8 +21,10 @@ - [Extended PayloadAttributesV3](#extended-payloadattributesv3) - [`engine_newPayloadV2`](#engine_newpayloadv2) - [`engine_newPayloadV3`](#engine_newpayloadv3) + - [`engine_newPayloadV4`](#engine_newpayloadv4) - [`engine_getPayloadV2`](#engine_getpayloadv2) - [`engine_getPayloadV3`](#engine_getpayloadv3) + - [`engine_getPayloadV4`](#engine_getpayloadv4) - [Extended Response](#extended-response) - [`engine_signalSuperchainV1`](#engine_signalsuperchainv1) - [Networking](#networking) @@ -299,6 +301,16 @@ 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. There are no +modifications to this API. +`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]. @@ -328,6 +340,13 @@ The [response][GetPayloadV3Response] is extended to: 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: diff --git a/specs/protocol/isthmus/exec-engine.md b/specs/protocol/isthmus/exec-engine.md index e1eaf905a..c3f076021 100644 --- a/specs/protocol/isthmus/exec-engine.md +++ b/specs/protocol/isthmus/exec-engine.md @@ -20,7 +20,7 @@ - [Block Body Withdrawals List](#block-body-withdrawals-list) - [Engine API Updates](#engine-api-updates) - [Update to `ExecutableData`](#update-to-executabledata) - - [`engine_newPayloadV3` API](#engine_newpayloadv3-api) + - [`engine_newPayloadv4` API](#engine_newpayloadv4-api) @@ -137,7 +137,7 @@ Withdrawals list in the block body is encoded as an empty RLP list. `ExecutableData` will contain an extra field for `withdrawalsRoot` after Isthmus hard fork. -### `engine_newPayloadV3` API +### `engine_newPayloadV4` API -Post Isthmus, `engine_newPayloadV3` will be used with the additional `ExecutionPayload` attribute. This attribute +Post Isthmus, `engine_newPayloadV4` will be used with the additional `ExecutionPayload` attribute. This attribute is omitted prior to Isthmus. From 40562fadbc81fcf25fb5915b011cdf9b19a557e7 Mon Sep 17 00:00:00 2001 From: Julian Meyer Date: Tue, 21 Jan 2025 13:36:07 -0800 Subject: [PATCH 2/5] Lint and specify v3 or v2 could be used --- specs/protocol/derivation.md | 6 +++--- specs/protocol/exec-engine.md | 1 - 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/specs/protocol/derivation.md b/specs/protocol/derivation.md index 9dda3af63..8bd4bc375 100644 --- a/specs/protocol/derivation.md +++ b/specs/protocol/derivation.md @@ -750,9 +750,9 @@ To interact with the engine, the [execution engine API][exec-engine] is used, wi - [`engine_newPayloadV3`] — executes an Ecotone execution payload to create a block. - [`engine_newPayloadV4`] - executes an Isthmus execution payload to create a block. -The current version of `op-node` uses the `v4` Engine API RPC methods as well as `engine_newPayloadV3`, due to -`engine_newPayloadV4` only supporting Isthmus execution payloads. Both `engine_forkchoiceUpdatedV3` and -`engine_getPayloadV3` are backwards compatible with Bedrock, Canyon & Delta payloads. +The current version of `op-node` uses the `v4` Engine API RPC methods as well as `engine_newPayloadV3` and +`engine_newPayloadV2`, due to `engine_newPayloadV4` only supporting Isthmus execution payloads. Both `engine_forkchoiceUpdatedV4` and `engine_getPayloadV4` are backwards compatible with Ecotone, Bedrock, +Canyon & Delta payloads. Prior versions of `op-node` used `v3`, `v2` and `v1` methods. diff --git a/specs/protocol/exec-engine.md b/specs/protocol/exec-engine.md index ce1120641..a1d95f537 100644 --- a/specs/protocol/exec-engine.md +++ b/specs/protocol/exec-engine.md @@ -346,7 +346,6 @@ In Ecotone it MUST be set to the parentBeaconBlockRoot from the L1 Origin block 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: From ddbe46dc5c97b52049636a233ac439050c52d6b7 Mon Sep 17 00:00:00 2001 From: Julian Meyer Date: Tue, 21 Jan 2025 13:59:23 -0800 Subject: [PATCH 3/5] Fix lint --- specs/protocol/derivation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specs/protocol/derivation.md b/specs/protocol/derivation.md index 8bd4bc375..4c69af1d7 100644 --- a/specs/protocol/derivation.md +++ b/specs/protocol/derivation.md @@ -751,7 +751,8 @@ To interact with the engine, the [execution engine API][exec-engine] is used, wi - [`engine_newPayloadV4`] - executes an Isthmus execution payload to create a block. The current version of `op-node` uses the `v4` Engine API RPC methods as well as `engine_newPayloadV3` and -`engine_newPayloadV2`, due to `engine_newPayloadV4` only supporting Isthmus execution payloads. Both `engine_forkchoiceUpdatedV4` and `engine_getPayloadV4` are backwards compatible with Ecotone, Bedrock, +`engine_newPayloadV2`, due to `engine_newPayloadV4` only supporting Isthmus execution payloads. Both +`engine_forkchoiceUpdatedV4` and `engine_getPayloadV4` are backwards compatible with Ecotone, Bedrock, Canyon & Delta payloads. Prior versions of `op-node` used `v3`, `v2` and `v1` methods. From ed9455527e1a94b95511499c50a988bff5dc622c Mon Sep 17 00:00:00 2001 From: Julian Meyer Date: Wed, 22 Jan 2025 09:27:20 -0800 Subject: [PATCH 4/5] Fix toc name --- specs/protocol/isthmus/exec-engine.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/protocol/isthmus/exec-engine.md b/specs/protocol/isthmus/exec-engine.md index c3f076021..b099dd24e 100644 --- a/specs/protocol/isthmus/exec-engine.md +++ b/specs/protocol/isthmus/exec-engine.md @@ -20,7 +20,7 @@ - [Block Body Withdrawals List](#block-body-withdrawals-list) - [Engine API Updates](#engine-api-updates) - [Update to `ExecutableData`](#update-to-executabledata) - - [`engine_newPayloadv4` API](#engine_newpayloadv4-api) + - [`engine_newPayloadV4` API](#engine_newpayloadv4-api) From 4ae97b7a079956ed8f2490f1302595bcb67f9e5f Mon Sep 17 00:00:00 2001 From: Julian Meyer Date: Wed, 22 Jan 2025 09:27:55 -0800 Subject: [PATCH 5/5] Fix toc --- specs/protocol/exec-engine.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/protocol/exec-engine.md b/specs/protocol/exec-engine.md index a1d95f537..14b32e3ad 100644 --- a/specs/protocol/exec-engine.md +++ b/specs/protocol/exec-engine.md @@ -24,8 +24,8 @@ - [`engine_newPayloadV4`](#engine_newpayloadv4) - [`engine_getPayloadV2`](#engine_getpayloadv2) - [`engine_getPayloadV3`](#engine_getpayloadv3) - - [`engine_getPayloadV4`](#engine_getpayloadv4) - [Extended Response](#extended-response) + - [`engine_getPayloadV4`](#engine_getpayloadv4) - [`engine_signalSuperchainV1`](#engine_signalsuperchainv1) - [Networking](#networking) - [Sync](#sync)