From 50e108ed9c7c788e130d0b903af22e4ddbe0c92e Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Mon, 27 May 2024 18:49:37 +0600 Subject: [PATCH] Return and accept EL trigerred requests as a sidecar --- src/engine/prague.md | 104 +++++++------------------------------------ 1 file changed, 16 insertions(+), 88 deletions(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index aa0d666e..00fb7ee2 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -12,8 +12,6 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [Structures](#structures) - [DepositRequestV1](#depositrequestv1) - [WithdrawalRequestV1](#withdrawalrequestv1) - - [ExecutionPayloadV4](#executionpayloadv4) - - [ExecutionPayloadBodyV2](#executionpayloadbodyv2) - [Methods](#methods) - [engine_newPayloadV4](#engine_newpayloadv4) - [Request](#request) @@ -23,14 +21,6 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine_getPayloadBodiesByHashV2](#engine_getpayloadbodiesbyhashv2) - - [Request](#request-2) - - [Response](#response-2) - - [Specification](#specification-2) - - [engine_getPayloadBodiesByRangeV2](#engine_getpayloadbodiesbyrangev2) - - [Request](#request-3) - - [Response](#response-3) - - [Specification](#specification-3) - [Update the methods of previous forks](#update-the-methods-of-previous-forks) @@ -59,44 +49,11 @@ The fields are encoded as follows: *Note:* The `amount` value is represented in Gwei. -### 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. - -### ExecutionPayloadBodyV2 - -This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#executionpayloadv1) and appends the new fields: `depositRequests` and `withdrawalRequests`. - -- `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. -- `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. - ## Methods ### engine_newPayloadV4 -The request of this method is updated with [`ExecutionPayloadV4`](#ExecutionPayloadV4). +The request of this method is updated with [`ExecutionPayloadV3`](./cancun.md#ExecutionPayloadV4). #### Request @@ -105,6 +62,8 @@ The request of this method is updated with [`ExecutionPayloadV4`](#ExecutionPayl 1. `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4). 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. `expectedDepositRequests`: `Array of DepositRequestV1` - Array of expected deposit requests to validate. + 5. `expectedWithdrawalRequests`: `Array of WithdrawalRequestV1` - Array of expected withdrawal requests to validate. #### Response @@ -116,6 +75,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 expected array of deposit requests, client software **MUST** run its validation by taking the following steps: + 1. Obtain the actual deposit requests array as it is specified by the [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110). + 2. Return `{status: INVALID, latestValidHash: validHash, validationError: errorMessage | null}` if the expected and the actual arrays don't match. + +3. Given the expected array of withdrawal requests, client software **MUST** run its validation by taking the following steps: + 1. Obtain the actual withdrawal requests array as it is specified by the [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002). + 2. Return `{status: INVALID, latestValidHash: validHash, validationError: errorMessage | null}` if the expected and the actual arrays don't match. + ### engine_getPayloadV4 The response of this method is updated with [`ExecutionPayloadV4`](#ExecutionPayloadV4). @@ -132,8 +99,10 @@ The response of this method is updated with [`ExecutionPayloadV4`](#ExecutionPay * result: `object` - `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4) - `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` + - `blobsBundle`: [`BlobsBundleV1`](./cancun.md#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 + - `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. * error: code and message set in case an exception happens while getting the payload. #### Specification @@ -142,50 +111,9 @@ 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. -### engine_getPayloadBodiesByHashV2 - -The response of this method is updated with [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2). - -#### Request - -* method: `engine_getPayloadBodiesByHashV2` -* params: - 1. `Array of DATA`, 32 Bytes - Array of `block_hash` field values of the `ExecutionPayload` structure -* timeout: 10s - -#### Response - -* result: `Array of ExecutionPayloadBodyV2` - Array of [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2) objects. -* error: code and message set in case an exception happens while processing the method call. - -#### Specification - -This method follows the same specification as [`engine_getPayloadBodiesByHashV1`](./shanghai.md#engine_getpayloadbodiesbyhashv1) with the addition of the following: - -1. Client software **MUST** set `depositRequests` and `withdrawalRequests` fields to `null` for bodies of pre-Prague blocks. - -### engine_getPayloadBodiesByRangeV2 - -The response of this method is updated with [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2). - -#### Request - -* method: `engine_getPayloadBodiesByRangeV2` -* params: - 1. `start`: `QUANTITY`, 64 bits - Starting block number - 1. `count`: `QUANITTY`, 64 bits - Number of blocks to return -* timeout: 10s - -#### Response - -* result: `Array of ExecutionPayloadBodyV2` - Array of [`ExecutionPayloadBodyV2`](#executionpayloadbodyv2) objects. -* error: code and message set in case an exception happens while processing the method call. - -#### Specification - -This method follows the same specification as [`engine_getPayloadBodiesByRangeV2`](./shanghai.md#engine_getpayloadbodiesbyrangev1) with the addition of the following: +2. Client software **MUST** return `depositRequests` array obtained from the block execution according to the [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110) specification. -1. Client software **MUST** set `depositRequests` and `withdrawalRequests` fields to `null` for bodies of pre-Prague blocks. +3. Client software **MUST** return `withdrawalRequests` array obtained from the block execution according to the [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002) specification. ### Update the methods of previous forks