From 3c3b18ebabd5678ee57b01c74bef70dd7ac5bbbb Mon Sep 17 00:00:00 2001 From: dapplion <35266934+dapplion@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:04:08 +0200 Subject: [PATCH 1/4] Add engine_executeStatelessPayloadV3 --- src/engine/cancun.md | 55 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/src/engine/cancun.md b/src/engine/cancun.md index b37a669c2..19ac1d1d7 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -13,6 +13,8 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md - [ExecutionPayloadV3](#executionpayloadv3) - [BlobsBundleV1](#blobsbundlev1) - [PayloadAttributesV3](#payloadattributesv3) + - [StatelessWitnessV1](#statelesswitnessv1) + - [StatelessPayloadStatusV1](#statelesspayloadstatusv1) - [Methods](#methods) - [engine_newPayloadV3](#engine_newpayloadv3) - [Request](#request) @@ -26,7 +28,12 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) + - [engine_executeStatelessPayloadV3](#engine_executestatelesspayloadv3) + - [Request](#request-3) + - [Response](#response-3) + - [Specification](#specification-3) - [Deprecate `engine_exchangeTransitionConfigurationV1`](#deprecate-engine_exchangetransitionconfigurationv1) + - [Update the methods of previous forks](#update-the-methods-of-previous-forks) @@ -74,6 +81,23 @@ This structure has the syntax of [`PayloadAttributesV2`](./shanghai.md#payloadat - `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. - `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block. +### StatelessWitnessV1 + +The fields are encoded as follows: + +- `headers`: `Array of DATA` - Array of header objects, each object is a byte list (`DATA`) representing an RLP encoded header. +- `codes`: `Array of DATA` - Array of TODO `["0xcode1", "0xcode2", ...]` +- `state`: `Array of DATA` - Array of TODO `["0xnode1", "0xnode2", ...]` + +### StatelessPayloadStatusV1 + +This structure contains the result of processing a payload. The fields are encoded as follows: + +- `status`: `enum` - `"VALID" | "INVALID"` +- `stateRoot`: `DATA|null`, 32 Bytes - the state root of the most recent *valid* block in the branch defined by payload and its ancestors +- `receiptsRoot`: `DATA|null`, 32 Bytes - the receipts root of the most recent *valid* block in the branch defined by payload and its ancestors +- `validationError`: `String|null` - a message providing additional details on the validation error if the payload is classified as `INVALID` or `INVALID_BLOCK_HASH`. + ## Methods ### engine_newPayloadV3 @@ -170,6 +194,35 @@ Refer to the specification for [`engine_getPayloadV2`](./shanghai.md#engine_getp 5. Client software **MAY** use any heuristics to decide whether to set `shouldOverrideBuilder` flag or not. If client software does not implement any heuristic this flag **SHOULD** be set to `false`. +### engine_executeStatelessPayloadV3 + +#### Request + +* method: `engine_executeStatelessPayloadV3` +* params: + 1. `executionPayload`: [`ExecutionPayloadV3`](#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. `statelessWitness`: [`StatelessWitnessV1`](#StatelessWitnessV1). + +#### Response + +* result: [`StatelessPayloadStatusV1`](#StatelessPayloadStatusV1), values of the `status` field are restricted in the following way: + - `INVALID_BLOCK_HASH` status value is supplanted by `INVALID`. +* error: code and message set in case an exception happens while processing the payload. + +#### Specification + +1. Client software **MUST** execute the payload using the provided witness and return the resulting state and receipt roots. Client software **MUST NOT** do any local chain checks. + +2. Client software **MUST** respond to this method call in the following way: + * `{status: VALID, validationError: null}` if the payload executes successfully + * `{status: INVALID, validationError: errorMessage | null}` if the payload can't be executed + +3. Given the expected array of blob versioned hashes client software **MUST** run its validation by taking the following steps: + 1. Obtain the actual array by concatenating blob versioned hashes lists (`tx.blob_versioned_hashes`) of each [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#new-transaction-type) included in the payload, respecting the order of inclusion. If the payload has no blob transactions the expected array **MUST** be `[]`. + 2. Return `{status: INVALID, validationError: errorMessage | null}` if the expected and the actual arrays don't match. + ### Deprecate `engine_exchangeTransitionConfigurationV1` This document introduces deprecation of [`engine_exchangeTransitionConfigurationV1`](./paris.md#engine_exchangetransitionconfigurationv1). The deprecation is specified as follows: @@ -192,4 +245,4 @@ For the following methods: a validation **MUST** be added: -1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the Cancun activation timestamp. \ No newline at end of file +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the Cancun activation timestamp. From eac8b017afb64edc085056e9235bd0224783524b Mon Sep 17 00:00:00 2001 From: dapplion <35266934+dapplion@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:19:19 +0200 Subject: [PATCH 2/4] Add engine_newPayloadWithWitnessV3 --- src/engine/cancun.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/src/engine/cancun.md b/src/engine/cancun.md index 19ac1d1d7..98f5ccf15 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -15,6 +15,7 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md - [PayloadAttributesV3](#payloadattributesv3) - [StatelessWitnessV1](#statelesswitnessv1) - [StatelessPayloadStatusV1](#statelesspayloadstatusv1) + - [PayloadStatusWithWitnessV1](#payloadstatuswithwitnessv1) - [Methods](#methods) - [engine_newPayloadV3](#engine_newpayloadv3) - [Request](#request) @@ -28,10 +29,14 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) - - [engine_executeStatelessPayloadV3](#engine_executestatelesspayloadv3) + - [engine_newPayloadWithWitnessV3](#engine_newpayloadwithwitnessv3) - [Request](#request-3) - [Response](#response-3) - [Specification](#specification-3) + - [engine_executeStatelessPayloadV3](#engine_executestatelesspayloadv3) + - [Request](#request-4) + - [Response](#response-4) + - [Specification](#specification-4) - [Deprecate `engine_exchangeTransitionConfigurationV1`](#deprecate-engine_exchangetransitionconfigurationv1) - [Update the methods of previous forks](#update-the-methods-of-previous-forks) @@ -98,6 +103,12 @@ This structure contains the result of processing a payload. The fields are encod - `receiptsRoot`: `DATA|null`, 32 Bytes - the receipts root of the most recent *valid* block in the branch defined by payload and its ancestors - `validationError`: `String|null` - a message providing additional details on the validation error if the payload is classified as `INVALID` or `INVALID_BLOCK_HASH`. +### PayloadStatusWithWitnessV1 + +This structure has the syntax of [`PayloadStatusV1`](./paris.md#payloadstatusv1) and appends a single field: `witness`. + +- `witness`: `StatelessWitnessV1` - `OBJECT` containing the fields of a `StatelessWitnessV1` structure. + ## Methods ### engine_newPayloadV3 @@ -194,6 +205,25 @@ Refer to the specification for [`engine_getPayloadV2`](./shanghai.md#engine_getp 5. Client software **MAY** use any heuristics to decide whether to set `shouldOverrideBuilder` flag or not. If client software does not implement any heuristic this flag **SHOULD** be set to `false`. +### engine_newPayloadWithWitnessV3 + +#### Request + +* method: `engine_newPayloadWithWitnessV3` + +Refer to the params for [`engine_newPayloadV3`](#engine_newpayloadv3). + +#### Response + +* result: [`PayloadStatusWithWitnessV1`](#PayloadStatusWithWitnessV1) +* error: code and message set in case an exception happens while processing the payload. + +#### Specification + +This method follows the same specification as [`engine_newPayloadV3`](#engine_newpayloadv3) with the addition of the following: + +1. Client software **MUST** trigger stateless witness creation during payload execution + ### engine_executeStatelessPayloadV3 #### Request From e494f2463bf09b50b4d45e398c9b9cd105d83628 Mon Sep 17 00:00:00 2001 From: dapplion <35266934+dapplion@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:42:11 +0200 Subject: [PATCH 3/4] Add to wordlist --- wordlist.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/wordlist.txt b/wordlist.txt index 033edc2d2..debf51dda 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -63,4 +63,7 @@ src https forkchoiceupdatedresponsev exitv -depositreceiptv \ No newline at end of file +depositreceiptv +statelesswitnessv +payloadstatuswithwitnessv +newpayloadwithwitnessv From e45a86871b8e116d0329557acc8254e205cdd710 Mon Sep 17 00:00:00 2001 From: dapplion <35266934+dapplion@users.noreply.github.com> Date: Fri, 28 Jun 2024 15:43:11 +0200 Subject: [PATCH 4/4] Update spec --- src/engine/cancun.md | 13 ++----------- wordlist.txt | 1 - 2 files changed, 2 insertions(+), 12 deletions(-) diff --git a/src/engine/cancun.md b/src/engine/cancun.md index 98f5ccf15..a1e55a2ce 100644 --- a/src/engine/cancun.md +++ b/src/engine/cancun.md @@ -13,7 +13,6 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md - [ExecutionPayloadV3](#executionpayloadv3) - [BlobsBundleV1](#blobsbundlev1) - [PayloadAttributesV3](#payloadattributesv3) - - [StatelessWitnessV1](#statelesswitnessv1) - [StatelessPayloadStatusV1](#statelesspayloadstatusv1) - [PayloadStatusWithWitnessV1](#payloadstatuswithwitnessv1) - [Methods](#methods) @@ -86,14 +85,6 @@ This structure has the syntax of [`PayloadAttributesV2`](./shanghai.md#payloadat - `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure. - `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block. -### StatelessWitnessV1 - -The fields are encoded as follows: - -- `headers`: `Array of DATA` - Array of header objects, each object is a byte list (`DATA`) representing an RLP encoded header. -- `codes`: `Array of DATA` - Array of TODO `["0xcode1", "0xcode2", ...]` -- `state`: `Array of DATA` - Array of TODO `["0xnode1", "0xnode2", ...]` - ### StatelessPayloadStatusV1 This structure contains the result of processing a payload. The fields are encoded as follows: @@ -107,7 +98,7 @@ This structure contains the result of processing a payload. The fields are encod This structure has the syntax of [`PayloadStatusV1`](./paris.md#payloadstatusv1) and appends a single field: `witness`. -- `witness`: `StatelessWitnessV1` - `OBJECT` containing the fields of a `StatelessWitnessV1` structure. +- `witness`: `DATA` - Opaque blob containing witness data RLP encoded. ## Methods @@ -233,7 +224,7 @@ This method follows the same specification as [`engine_newPayloadV3`](#engine_ne 1. `executionPayload`: [`ExecutionPayloadV3`](#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. `statelessWitness`: [`StatelessWitnessV1`](#StatelessWitnessV1). + 4. `statelessWitness`: `DATA`, - Opaque blob containing witness data RLP encoded. #### Response diff --git a/wordlist.txt b/wordlist.txt index debf51dda..a603019c3 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -64,6 +64,5 @@ https forkchoiceupdatedresponsev exitv depositreceiptv -statelesswitnessv payloadstatuswithwitnessv newpayloadwithwitnessv