Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extend Deneb with Execution layer cross-validation #557

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Extend Deneb with Execution layer cross-validation #557

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3c3b18e
Add engine_executeStatelessPayloadV3
dapplion Jun 26, 2024
eac8b01
Add engine_newPayloadWithWitnessV3
dapplion Jun 26, 2024
e494f24
Add to wordlist
dapplion Jun 26, 2024
e45a868
Update spec
dapplion Jun 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 75 additions & 1 deletion src/engine/cancun.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md
- [ExecutionPayloadV3](#executionpayloadv3)
- [BlobsBundleV1](#blobsbundlev1)
- [PayloadAttributesV3](#payloadattributesv3)
- [StatelessPayloadStatusV1](#statelesspayloadstatusv1)
- [PayloadStatusWithWitnessV1](#payloadstatuswithwitnessv1)
- [Methods](#methods)
- [engine_newPayloadV3](#engine_newpayloadv3)
- [Request](#request)
Expand All @@ -26,7 +28,16 @@ This specification is based on and extends [Engine API - Shanghai](./shanghai.md
- [Request](#request-2)
- [Response](#response-2)
- [Specification](#specification-2)
- [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)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Expand Down Expand Up @@ -74,6 +85,21 @@ 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.

### 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@karalabe could you please share more info about why latestValidHash can not work in the case of stateless execution?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's no local chain. Stateless execution is stateless. Here's the input, here's the output. Forget we ever talked.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's more akin to a library verifying an execution than a full node being on the other side.

- `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`: `DATA` - Opaque blob containing witness data RLP encoded.

## Methods

### engine_newPayloadV3
Expand Down Expand Up @@ -170,6 +196,54 @@ 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

* 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`: `DATA`, - Opaque blob containing witness data RLP encoded.

#### 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:
Expand All @@ -192,4 +266,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.
1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the Cancun activation timestamp.
4 changes: 3 additions & 1 deletion wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,4 +63,6 @@ src
https
forkchoiceupdatedresponsev
exitv
depositreceiptv
depositreceiptv
payloadstatuswithwitnessv
newpayloadwithwitnessv
Loading