From 198c96b2342226ce4ab6aa30a86eec44635af7ee Mon Sep 17 00:00:00 2001 From: inphi Date: Wed, 9 Nov 2022 20:54:39 -0500 Subject: [PATCH 1/4] Extend EIP-4844 to include withdrawals --- src/engine/blob-extension.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/src/engine/blob-extension.md b/src/engine/blob-extension.md index 9e8f0cd9..247b67c1 100644 --- a/src/engine/blob-extension.md +++ b/src/engine/blob-extension.md @@ -5,6 +5,27 @@ This extension is backwards-compatible, but not part of the initial Engine API. ## Structures +### ExecutionPayloadV2 + +This structure is extended to include a single field: `excessDataGas`. + +- `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. +- `excessDataGas`: `QUANTITY`, 256 bits + ### BlobsBundleV1 The fields are encoded as follows: @@ -20,7 +41,7 @@ The fields are encoded as follows: This method retrieves the blobs and their respective KZG commitments corresponding to the `versioned_hashes` included in the blob transactions of the referenced execution payload. -This method may be combined with `engine_getPayloadV1` into a `engine_getPayloadV2` in a later stage of EIP-4844. +This method may be combined with `engine_getPayloadV2`. The separation of concerns aims to minimize changes during the testing phase of the EIP. #### Request @@ -37,7 +58,7 @@ The separation of concerns aims to minimize changes during the testing phase of #### Specification 1. Given the `payloadId` client software **MUST** return the blobs bundle corresponding to the most recent version of the payload that was served with `engine_getPayload`, if any, - and halt any further changes to the payload. The `engine_getBlobsBundleV1` and `engine_getPayloadV1` results **MUST** be consistent as outlined in items 3, 4 and 5 below. + and halt any further changes to the payload. The `engine_getBlobsBundleV1` and `engine_getPayloadV2` results **MUST** be consistent as outlined in items 3, 4 and 5 below. 2. The call **MUST** return `-32001: Unknown payload` error if the build process identified by the `payloadId` does not exist. Note that a payload without any blobs **MUST** return an empty `blobs` and `kzgs` list, not an error. From c19a19804981a61cace95966020fcbf7f11f59a3 Mon Sep 17 00:00:00 2001 From: inphi Date: Mon, 28 Nov 2022 13:53:21 -0500 Subject: [PATCH 2/4] Reference v2 apis; reorder fields --- src/engine/blob-extension.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/src/engine/blob-extension.md b/src/engine/blob-extension.md index 247b67c1..cef24ebc 100644 --- a/src/engine/blob-extension.md +++ b/src/engine/blob-extension.md @@ -1,3 +1,21 @@ + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Shard Blob Extension](#shard-blob-extension) + - [Structures](#structures) + - [ExecutionPayloadV2](#executionpayloadv2) + - [BlobsBundleV1](#blobsbundlev1) + - [Methods](#methods) + - [engine_newPayloadV2](#engine_newpayloadv2) + - [engine_getPayloadV2](#engine_getpayloadv2) + - [engine_getBlobsBundleV1](#engine_getblobsbundlev1) + - [Request](#request) + - [Response](#response) + - [Specification](#specification) + + + # Shard Blob Extension This is an extension specific to [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) to the `core` methods as defined in the [Engine API](./specification.md). @@ -7,7 +25,7 @@ This extension is backwards-compatible, but not part of the initial Engine API. ### ExecutionPayloadV2 -This structure is extended to include a single field: `excessDataGas`. +This existing structure is extended to include a single field: `excessDataGas`. All APIs referencing the `ExecutionPayloadV2` in the [original Engine API](./specification.md) must use this extended structure instead. - `parentHash`: `DATA`, 32 Bytes - `feeRecipient`: `DATA`, 20 Bytes @@ -21,10 +39,10 @@ This structure is extended to include a single field: `excessDataGas`. - `timestamp`: `QUANTITY`, 64 Bits - `extraData`: `DATA`, 0 to 32 Bytes - `baseFeePerGas`: `QUANTITY`, 256 Bits +- `excessDataGas`: `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. -- `excessDataGas`: `QUANTITY`, 256 bits ### BlobsBundleV1 @@ -36,6 +54,14 @@ The fields are encoded as follows: ## Methods +### engine_newPayloadV2 + +This method parameter updated to accept the extended EIP-4844 `ExecutionPayloadV2` structure. + +### engine_getPayloadV2 + +This method is extended to return the extended EIP-4844 `ExecutionPayloadV2` structure. + ### engine_getBlobsBundleV1 This method retrieves the blobs and their respective KZG commitments corresponding to the `versioned_hashes` From 6ecb048b5fe543912d613754e695a03fb53bb519 Mon Sep 17 00:00:00 2001 From: inphi Date: Tue, 29 Nov 2022 15:35:13 -0500 Subject: [PATCH 3/4] update wordlist for spellcheck --- wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/wordlist.txt b/wordlist.txt index a38207e4..5ff2b089 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -48,3 +48,4 @@ besu graphql gwei withdrawalv +DocToc From ff95a01d34bcf4e0fb945baffc135271d84611c5 Mon Sep 17 00:00:00 2001 From: inphi Date: Mon, 5 Dec 2022 15:16:28 -0500 Subject: [PATCH 4/4] V3 naming for 4844 types/methods --- src/engine/blob-extension.md | 53 ++++++++++++++++++++++++++++-------- 1 file changed, 42 insertions(+), 11 deletions(-) diff --git a/src/engine/blob-extension.md b/src/engine/blob-extension.md index cef24ebc..700e5dd9 100644 --- a/src/engine/blob-extension.md +++ b/src/engine/blob-extension.md @@ -4,15 +4,21 @@ - [Shard Blob Extension](#shard-blob-extension) - [Structures](#structures) - - [ExecutionPayloadV2](#executionpayloadv2) + - [ExecutionPayloadV3](#executionpayloadv3) - [BlobsBundleV1](#blobsbundlev1) - [Methods](#methods) - - [engine_newPayloadV2](#engine_newpayloadv2) - - [engine_getPayloadV2](#engine_getpayloadv2) - - [engine_getBlobsBundleV1](#engine_getblobsbundlev1) + - [engine_newPayloadV3](#engine_newpayloadv3) - [Request](#request) - - [Response](#response) - [Specification](#specification) + - [Response](#response) + - [engine_getPayloadV3](#engine_getpayloadv3) + - [Request](#request-1) + - [Response](#response-1) + - [Specification](#specification-1) + - [engine_getBlobsBundleV1](#engine_getblobsbundlev1) + - [Request](#request-2) + - [Response](#response-2) + - [Specification](#specification-2) @@ -23,9 +29,9 @@ This extension is backwards-compatible, but not part of the initial Engine API. ## Structures -### ExecutionPayloadV2 +### ExecutionPayloadV3 -This existing structure is extended to include a single field: `excessDataGas`. All APIs referencing the `ExecutionPayloadV2` in the [original Engine API](./specification.md) must use this extended structure instead. +This structure has the syntax of `ExecutionPayloadV2` and appends a single field: `excessDataGas`. - `parentHash`: `DATA`, 32 Bytes - `feeRecipient`: `DATA`, 20 Bytes @@ -54,13 +60,38 @@ The fields are encoded as follows: ## Methods -### engine_newPayloadV2 +### engine_newPayloadV3 + +#### Request + +* method: `engine_newPayloadV3` +* params: + 1. [`ExecutionPayloadV3`](#ExecutionPayloadV3) + +#### Specification + +Refer to the specification for `engine_newPayloadV2`. -This method parameter updated to accept the extended EIP-4844 `ExecutionPayloadV2` structure. +#### Response -### engine_getPayloadV2 +Refer to the response for `engine_newPayloadV2`. + +### engine_getPayloadV3 + +#### Request + +* method: `engine_getPayloadV3` +* params: + 1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process + +#### Response + +* result: [`ExecutionPayloadV3`](#ExecutionPayloadV3) +* error: code and message set in case an exception happens while getting the payload. + +#### Specification -This method is extended to return the extended EIP-4844 `ExecutionPayloadV2` structure. +Refer to the specification for `engine_getPayloadV2`. ### engine_getBlobsBundleV1