From cd7d992524185958124a8289c8f914ffbd77cf03 Mon Sep 17 00:00:00 2001 From: lightclient Date: Thu, 18 Jul 2024 12:51:32 -0600 Subject: [PATCH 1/7] engine: unify request objects --- src/engine/prague.md | 45 ++++++++++++++------------------------------ 1 file changed, 14 insertions(+), 31 deletions(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index 688c6abb0..ce103c64c 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -10,9 +10,7 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [Structures](#structures) - - [DepositRequestV1](#depositrequestv1) - - [WithdrawalRequestV1](#withdrawalrequestv1) - - [ConsolidationRequestV1](#consolidationrequestv1) + - [RequestV1](#requestv1) - [ExecutionPayloadV4](#executionpayloadv4) - [ExecutionPayloadBodyV2](#executionpayloadbodyv2) - [Methods](#methods) @@ -38,39 +36,28 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp ## Structures -### DepositRequestV1 -This structure maps onto the deposit object from [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110). +### RequestV1 + +This structure maps onto the amalgamation of the deposit object from [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110), withdrawal request from [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002), and the consolidation request from [EIP-7251](https://eips.ethereum.org/EIPS/eip-7251). + The fields are encoded as follows: +- `type`: `QUANTITY`, 64 bits - [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685) type byte to identify the request - `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 +*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`. +This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field `requests`. - `parentHash`: `DATA`, 32 Bytes - `feeRecipient`: `DATA`, 20 Bytes @@ -89,19 +76,15 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay - `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. +- `requests`: `Array of RequestV1` - Array of request objects ### ExecutionPayloadBodyV2 -This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#executionpayloadv1) and appends the new fields: `depositRequests` and `withdrawalRequests`. +This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#executionpayloadv1) and appends the new field `requests`. - `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. -- `consolidationRequests`: `Array of ConsolidationRequestV1` - Array of consolidation requests, each object is an `OBJECT` containing the fields of a `ConsolidationRequestV1` structure. +- `requests`: `Array of RequestV1` - Array of requests, each object is an `OBJECT` containing the fields of a `RequestV1` structure. ## Methods @@ -173,7 +156,7 @@ The response of this method is updated with [`ExecutionPayloadBodyV2`](#executio 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. +1. Client software **MUST** set `requests` field to `null` for bodies of pre-Prague blocks. ### engine_getPayloadBodiesByRangeV2 @@ -196,7 +179,7 @@ The response of this method is updated with [`ExecutionPayloadBodyV2`](#executio This method follows the same specification as [`engine_getPayloadBodiesByRangeV2`](./shanghai.md#engine_getpayloadbodiesbyrangev1) with the addition of the following: -1. Client software **MUST** set `depositRequests` and `withdrawalRequests` fields to `null` for bodies of pre-Prague blocks. +1. Client software **MUST** set `requests` field to `null` for bodies of pre-Prague blocks. ### Update the methods of previous forks From 5c357e0b172d340fa31af4f3d6ab162cfeab5e33 Mon Sep 17 00:00:00 2001 From: lightclient Date: Wed, 21 Aug 2024 07:32:10 -0600 Subject: [PATCH 2/7] engine: rename request to execution request --- src/engine/prague.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index ce103c64c..2b7d8d958 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -10,7 +10,7 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [Structures](#structures) - - [RequestV1](#requestv1) + - [ExecutionRequestV1](#requestv1) - [ExecutionPayloadV4](#executionpayloadv4) - [ExecutionPayloadBodyV2](#executionpayloadbodyv2) - [Methods](#methods) @@ -36,7 +36,7 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp ## Structures -### RequestV1 +### ExecutionRequestV1 This structure maps onto the amalgamation of the deposit object from [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110), withdrawal request from [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002), and the consolidation request from [EIP-7251](https://eips.ethereum.org/EIPS/eip-7251). @@ -76,7 +76,7 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay - `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 -- `requests`: `Array of RequestV1` - Array of request objects +- `requests`: `Array of ExecutionRequestV1` - Array of request objects ### ExecutionPayloadBodyV2 @@ -84,7 +84,7 @@ This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#execut - `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. -- `requests`: `Array of RequestV1` - Array of requests, each object is an `OBJECT` containing the fields of a `RequestV1` structure. +- `requests`: `Array of ExecutionRequestV1` - Array of requests, each object is an `OBJECT` containing the fields of a `ExecutionRequestV1` structure. ## Methods From 581098a5332e58425438e97c283be038c78dc2fa Mon Sep 17 00:00:00 2001 From: Felix Lange Date: Wed, 4 Sep 2024 13:51:27 +0200 Subject: [PATCH 3/7] engine: send requests as DATA --- src/engine/prague.md | 23 ++--------------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index 2b7d8d958..58704992d 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -10,7 +10,6 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [Structures](#structures) - - [ExecutionRequestV1](#requestv1) - [ExecutionPayloadV4](#executionpayloadv4) - [ExecutionPayloadBodyV2](#executionpayloadbodyv2) - [Methods](#methods) @@ -36,25 +35,6 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp ## Structures -### ExecutionRequestV1 - -This structure maps onto the amalgamation of the deposit object from [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110), withdrawal request from [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002), and the consolidation request from [EIP-7251](https://eips.ethereum.org/EIPS/eip-7251). - -The fields are encoded as follows: - -- `type`: `QUANTITY`, 64 bits - [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685) type byte to identify the request -- `pubkey`: `DATA`, 48 Bytes -- `withdrawalCredentials`: `DATA`, 32 Bytes -- `amount`: `QUANTITY`, 64 Bits -- `signature`: `DATA`, 96 Bytes -- `index`: `QUANTITY`, 64 Bits -- `sourceAddress`: `DATA`, 20 Bytes -- `validatorPubkey`: `DATA`, 48 Bytes -- `sourcePubkey`: `DATA`, 48 Bytes -- `targetPubkey`: `DATA`, 48 Bytes - -*Note:* The `amount` value is represented in Gwei. - ### ExecutionPayloadV4 This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field `requests`. @@ -84,7 +64,8 @@ This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#execut - `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. -- `requests`: `Array of ExecutionRequestV1` - Array of requests, each object is an `OBJECT` containing the fields of a `ExecutionRequestV1` structure. +- `requests`: `Array of ExecutionRequestV1` - Array of requests, each element is a byte list (`DATA`) containing +`request_type || request_data` as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). ## Methods From b62e8a8d6cee28f6874c64aca0da079081dc8533 Mon Sep 17 00:00:00 2001 From: Felix Lange Date: Thu, 5 Sep 2024 16:16:10 +0200 Subject: [PATCH 4/7] Update src/engine/prague.md Co-authored-by: Mikhail Kalinin --- src/engine/prague.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index 58704992d..05345fd3d 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -64,7 +64,7 @@ This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#execut - `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. -- `requests`: `Array of ExecutionRequestV1` - Array of requests, each element is a byte list (`DATA`) containing +- `requests`: `Array of DATA` - Array of requests, each element is a byte list (`DATA`) containing `request_type || request_data` as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). ## Methods From f9e8c2f88a5f4904e4a8b96f695d2c25101f227a Mon Sep 17 00:00:00 2001 From: Felix Lange Date: Thu, 5 Sep 2024 23:44:13 +0200 Subject: [PATCH 5/7] Update src/engine/prague.md Co-authored-by: Mikhail Kalinin --- src/engine/prague.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/engine/prague.md b/src/engine/prague.md index d54db9317..b2015ba83 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -56,7 +56,8 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay - `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 -- `requests`: `Array of ExecutionRequestV1` - Array of request objects +- `requests`: `Array of DATA` - Array of request objects, each element is a byte list (`DATA`) containing + `request_type || request_data` as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). ### ExecutionPayloadBodyV2 From cb096d32a1c40eeffa53f5a8c9dc3a0ea635da6d Mon Sep 17 00:00:00 2001 From: Felix Lange Date: Thu, 12 Sep 2024 23:15:15 +0200 Subject: [PATCH 6/7] engine: add note about request ordering --- src/engine/prague.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/engine/prague.md b/src/engine/prague.md index b2015ba83..6ae33f309 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -58,6 +58,7 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay - `excessBlobGas`: `QUANTITY`, 64 Bits - `requests`: `Array of DATA` - Array of request objects, each element is a byte list (`DATA`) containing `request_type || request_data` as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). + - The requests MUST be provided in the same order which was used to compute `blockHash`. ### ExecutionPayloadBodyV2 From 9231cf21745bcc22d157cf24240313b5c7ce3aee Mon Sep 17 00:00:00 2001 From: Felix Lange Date: Thu, 12 Sep 2024 23:22:47 +0200 Subject: [PATCH 7/7] engine: more notes about requests --- src/engine/prague.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/engine/prague.md b/src/engine/prague.md index 6ae33f309..cf8b300a5 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -59,6 +59,8 @@ This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpay - `requests`: `Array of DATA` - Array of request objects, each element is a byte list (`DATA`) containing `request_type || request_data` as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). - The requests MUST be provided in the same order which was used to compute `blockHash`. + - When processing the payload, the consensus-layer client MUST verify that requests are provided in ascending `request_type` order. + - The consensus layer MUST reject payloads containing undefined `request_type`s. Notably this includes request types defined in a future fork, i.e. it must verify the requests of the payload are defined for the fork it uses. ### ExecutionPayloadBodyV2