engine: Make execution requests a sidecar, take 2

src/engine/openrpc/schemas/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/prague.md

@@ -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,21 @@ 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 `executionRequestsHash`.
 
 #### 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. `executionRequestsHash`: `DATA`, 32 Bytes - Hash of the execution layer triggered requests,
+computed as it is defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685).
 
 #### Response
 
@@ -108,9 +48,13 @@ 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. Client software **MUST** incorporate `executionRequestsHash` into the `blockHash` validation process.
+That is, if `executionRequestsHash` does not match the execution requests 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,12 @@ 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,
+each element of the list represents requests of a certain type encoded as it is defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685).
 * error: code and message set in case an exception happens while getting the payload.
 
 #### Specification
@@ -134,6 +80,10 @@ 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.
+The way the requests of different types are encoded and obtained from the execution is defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685).
+Elements of the `executionRequests` list **MUST** be ordered by the `requestType` (the first byte) in ascending order.
+
 ### Update the methods of previous forks
 
 This document defines how Prague payload should be handled by the [`Cancun API`](./cancun.md).

wordlist.txt

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