engine: Make execution requests a sidecar, take 2 (#591)

* engine: extract execution requests from payload

* add executionrequestsv to wordlist

* update engine_getPayloadV4

* Make execution requests a sidecar, take 2

* Turn executionRequests into a sequence of bytes

* Simplify wording

* Clean up wordlist

* Applied suggestions by @marioevz

Co-authored-by: Mario Vega <[email protected]>

* Switch to the nested list representation

* Fix typo

* Apply suggestions from @lucassaldanha

Co-authored-by: Lucas Saldanha <[email protected]>

* Switch getPayloadV4 response to ExecutionPayloadV3

* Replace hash with full executionRequests object for newPayloadV4

* Fix the newPayloadV4 note

* Mention that requestType byte isn't part of encoding

* Mention SSZ encoding in the executionRequests list

* Apply suggestions from @lucassaldanha

Co-authored-by: Lucas Saldanha <[email protected]>

* Update payload.yaml examples

* Drop 32 bytes len from executionRequests definition

* engine: clarification on requests

---------

Co-authored-by: Roman Krasiuk <[email protected]>
Co-authored-by: Mario Vega <[email protected]>
Co-authored-by: Lucas Saldanha <[email protected]>
Co-authored-by: lightclient <[email protected]>

Author: 5 people

src/engine/openrpc/methods/payload.yaml

@@ -243,80 +243,6 @@ ExecutionPayloadV3:
     excessBlobGas:
       title: Excess blob gas
       $ref: '#/components/schemas/uint64'
-ExecutionPayloadV4:
-  title: Execution payload object V4
-  type: object
-  required:
-    - parentHash
-    - feeRecipient
-    - stateRoot
-    - receiptsRoot
-    - logsBloom
-    - prevRandao
-    - blockNumber
-    - gasLimit
-    - gasUsed
-    - timestamp
-    - extraData
-    - baseFeePerGas
-    - blockHash
-    - transactions
-    - withdrawals
-    - blobGasUsed
-    - excessBlobGas
-    - depositRequests
-    - withdrawalRequests
-    - consolidationRequests
-  properties:
-    parentHash:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/parentHash'
-    feeRecipient:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/feeRecipient'
-    stateRoot:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/stateRoot'
-    receiptsRoot:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/receiptsRoot'
-    logsBloom:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/logsBloom'
-    prevRandao:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/prevRandao'
-    blockNumber:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/blockNumber'
-    gasLimit:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/gasLimit'
-    gasUsed:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/gasUsed'
-    timestamp:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/timestamp'
-    extraData:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/extraData'
-    baseFeePerGas:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/baseFeePerGas'
-    blockHash:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/blockHash'
-    transactions:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/transactions'
-    withdrawals:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/withdrawals'
-    blobGasUsed:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/blobGasUsed'
-    excessBlobGas:
-      $ref: '#/components/schemas/ExecutionPayloadV3/properties/excessBlobGas'
-    depositRequests:
-      title: Deposit requests
-      type: array
-      items:
-        $ref: '#/components/schemas/DepositRequestV1'
-    withdrawalRequests:
-      title: Withdrawals requests
-      type: array
-      items:
-        $ref: '#/components/schemas/WithdrawalRequestV1'
-    consolidationRequests:
-      title: Consolidation requests
-      type: array
-      items:
-        $ref: '#/components/schemas/ConsolidationRequestV1'
 ExecutionPayloadBodyV1:
   title: Execution payload body object V1
   type: object

src/engine/openrpc/schemas/payload.yaml

@@ -9,11 +9,6 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Structures](#structures)
-  - [DepositRequestV1](#depositrequestv1)
-  - [WithdrawalRequestV1](#withdrawalrequestv1)
-  - [ConsolidationRequestV1](#consolidationrequestv1)
-  - [ExecutionPayloadV4](#executionpayloadv4)
 - [Methods](#methods)
   - [engine_newPayloadV4](#engine_newpayloadv4)
     - [Request](#request)
@@ -27,76 +22,20 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Structures
-
-### DepositRequestV1
-This structure maps onto the deposit object from [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110).
-The fields are encoded as follows:
-
-- `pubkey`: `DATA`, 48 Bytes
-- `withdrawalCredentials`: `DATA`, 32 Bytes
-- `amount`: `QUANTITY`, 64 Bits
-- `signature`: `DATA`, 96 Bytes
-- `index`: `QUANTITY`, 64 Bits
-
-*Note:* The `amount` value is represented in Gwei.
-
-### WithdrawalRequestV1
-This structure maps onto the withdrawal request from [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002).
-The fields are encoded as follows:
-
-- `sourceAddress`: `DATA`, 20 Bytes
-- `validatorPubkey`: `DATA`, 48 Bytes
-- `amount`: `QUANTITY`, 64 Bits
-
-*Note:* The `amount` value is represented in Gwei.
-
-### ConsolidationRequestV1
-This structure maps onto the consolidation request from [EIP-7251](https://eips.ethereum.org/EIPS/eip-7251).
-The fields are encoded as follows:
-
-- `sourceAddress`: `DATA`, 20 Bytes
-- `sourcePubkey`: `DATA`, 48 Bytes
-- `targetPubkey`: `DATA`, 48 Bytes
-
-### ExecutionPayloadV4
-
-This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new fields: `depositRequests` and `withdrawalRequests`.
-
-- `parentHash`: `DATA`, 32 Bytes
-- `feeRecipient`:  `DATA`, 20 Bytes
-- `stateRoot`: `DATA`, 32 Bytes
-- `receiptsRoot`: `DATA`, 32 Bytes
-- `logsBloom`: `DATA`, 256 Bytes
-- `prevRandao`: `DATA`, 32 Bytes
-- `blockNumber`: `QUANTITY`, 64 Bits
-- `gasLimit`: `QUANTITY`, 64 Bits
-- `gasUsed`: `QUANTITY`, 64 Bits
-- `timestamp`: `QUANTITY`, 64 Bits
-- `extraData`: `DATA`, 0 to 32 Bytes
-- `baseFeePerGas`: `QUANTITY`, 256 Bits
-- `blockHash`: `DATA`, 32 Bytes
-- `transactions`: `Array of DATA` - Array of transaction objects, each object is a byte list (`DATA`) representing `TransactionType || TransactionPayload` or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718)
-- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
-- `blobGasUsed`: `QUANTITY`, 64 Bits
-- `excessBlobGas`: `QUANTITY`, 64 Bits
-- `depositRequests`: `Array of DepositRequestV1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositRequestV1` structure.
-- `withdrawalRequests`: `Array of WithdrawalRequestV1` - Array of withdrawal requests, each object is an `OBJECT` containing the fields of a `WithdrawalRequestV1` structure.
-- `consolidationRequests`: `Array of ConsolidationRequestV1` - Array of consolidation requests, each object is an `OBJECT` containing the fields of a `ConsolidationRequestV1` structure.
-
 ## Methods
 
 ### engine_newPayloadV4
 
-The request of this method is updated with [`ExecutionPayloadV4`](#ExecutionPayloadV4).
+Method parameter list is extended with `executionRequests`.
 
 #### Request
 
 * method: `engine_newPayloadV4`
 * params:
-  1. `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4).
+  1. `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3).
   2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate.
   3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
+  4. `executionRequests`: `Array of DATA` - List of execution layer triggered requests. Each list element is the corresponding request type's `request_data` as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). Elements of the list **MUST** be ordered by `request_type` in ascending order.
 
 #### Response
 
@@ -108,9 +47,14 @@ This method follows the same specification as [`engine_newPayloadV3`](./cancun.m
 
 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Prague fork.
 
+2. Given the `executionRequests`, client software **MUST** compute the execution requests commitment
+and incorporate it into the `blockHash` validation process.
+That is, if the computed commitment does not match the corresponding commitment in the execution layer block header,
+the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`.
+
 ### engine_getPayloadV4
 
-The response of this method is updated with [`ExecutionPayloadV4`](#ExecutionPayloadV4).
+The response of this method is extended with the `executionRequests` field.
 
 #### Request
 
@@ -122,10 +66,11 @@ The response of this method is updated with [`ExecutionPayloadV4`](#ExecutionPay
 #### Response
 
 * result: `object`
-  - `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4)
+  - `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3)
   - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
   - `blobsBundle`: [`BlobsBundleV1`](#BlobsBundleV1) - Bundle with data corresponding to blob transactions included into `executionPayload`
   - `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the execution layer to use this `executionPayload` instead of an externally provided one
+  - `executionRequests`: `Array of DATA` - Execution layer triggered requests obtained from the `executionPayload` transaction execution.
 * error: code and message set in case an exception happens while getting the payload.
 
 #### Specification
@@ -134,6 +79,8 @@ This method follows the same specification as [`engine_getPayloadV3`](./cancun.m
 
 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload does not fall within the time frame of the Prague fork.
 
+2. The call **MUST** return `executionRequests` list representing execution layer triggered requests obtained from the `executionPayload` transaction execution. Each element of the list corresponds to the request type's `request_data` as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). Elements of the list **MUST** be ordered by `request_type` in ascending order.
+
 ### Update the methods of previous forks
 
 This document defines how Prague payload should be handled by the [`Cancun API`](./cancun.md).

src/engine/prague.md

@@ -68,4 +68,3 @@ src
 https
 forkchoiceupdatedresponsev
 exitv
-depositreceiptv