Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: update spec to use v4 payload methods for isthmus #525

Merged
merged 5 commits into from
Jan 22, 2025
Merged

feat: update spec to use v4 payload methods for isthmus #525

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
20c5b46
feat: update spec to use v4 payload methods for isthmus
meyer9 Jan 17, 2025
40562fa
Lint and specify v3 or v2 could be used
meyer9 Jan 21, 2025
ddbe46d
Fix lint
meyer9 Jan 21, 2025
ed94555
Fix toc name
meyer9 Jan 22, 2025
4ae97b7
Fix toc
meyer9 Jan 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions specs/protocol/derivation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -748,19 +748,22 @@ 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
`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 `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
[`engine_getPayloadV2`]: exec-engine.md#engine_getpayloadv2
[`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].

Expand Down Expand Up @@ -887,6 +890,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:

Expand Down
18 changes: 18 additions & 0 deletions specs/protocol/exec-engine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,11 @@
- [Extended PayloadAttributesV3](#extended-payloadattributesv3)
- [`engine_newPayloadV2`](#engine_newpayloadv2)
- [`engine_newPayloadV3`](#engine_newpayloadv3)
- [`engine_newPayloadV4`](#engine_newpayloadv4)
- [`engine_getPayloadV2`](#engine_getpayloadv2)
- [`engine_getPayloadV3`](#engine_getpayloadv3)
- [Extended Response](#extended-response)
- [`engine_getPayloadV4`](#engine_getpayloadv4)
- [`engine_signalSuperchainV1`](#engine_signalsuperchainv1)
- [Networking](#networking)
- [Sync](#sync)
Expand Down Expand Up @@ -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].
Expand Down Expand Up @@ -328,6 +340,12 @@ 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.**

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just need to remove this line to make ci pass.

Suggested change

### `engine_signalSuperchainV1`

Optional extension to the Engine API. Signals superchain information to the Engine:
Expand Down
6 changes: 3 additions & 3 deletions specs/protocol/isthmus/exec-engine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Expand Down Expand Up @@ -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.