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

Jump to bottom

Engine API: Version -> Type Renaming for Static Data Structure Suffixes #369

Closed
wants to merge 14 commits into from
Closed

Engine API: Version -> Type Renaming for Static Data Structure Suffixes #369

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
34912d8
Engine API: separated version and type sections in the common definit…
holgerd77 Jan 25, 2023
6f320ff
Engine API: ExecutionPayloadV1 -> ExecutionPayloadType1
holgerd77 Jan 25, 2023
23d1bcc
Engine API: ForkchoiceStateV1 -> ForkchoiceStateType1
holgerd77 Jan 25, 2023
8763f81
Engine API: PayloadAttributesV1 -> PayloadAttributesType1
holgerd77 Jan 25, 2023
db1aa1c
Engine API: PayloadStatusV1 -> PayloadStatusType1
holgerd77 Jan 25, 2023
d5f12a1
Engine API: TransitionConfigurationV1 -> TransitionConfigurationType1
holgerd77 Jan 25, 2023
f2dbc3f
Engine API: WithdrawalV1 -> WithdrawalType1
holgerd77 Jan 25, 2023
9225181
Engine API: ExecutionPayloadV2 -> ExecutionPayloadType2
holgerd77 Jan 25, 2023
478a170
Engine API: ExecutionPayloadBodyV1 -> ExecutionPayloadBodyType1
holgerd77 Jan 25, 2023
e244def
Engine API: PayloadAttributesV2 -> PayloadAttributesType2
holgerd77 Jan 25, 2023
cf157ba
Engine API: ExecutionPayloadV3 -> ExecutionPayloadType3
holgerd77 Jan 25, 2023
1d9b5db
Engine API: BlobsBundleV1 -> BlobsBundleType1
holgerd77 Jan 25, 2023
9a9d35c
Engine API: DepositV1 -> DepositType1
holgerd77 Jan 25, 2023
56732ee
Engine API: ExecutionPayloadV6110 -> ExecutionPayloadType6110
holgerd77 Jan 25, 2023
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
39 changes: 26 additions & 13 deletions src/engine/common.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,17 @@ This document specifies common definitions and requirements affecting Engine API
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Underlying protocol](#underlying-protocol)
- [Authentication](#authentication)
- [Versioning](#versioning)
- [Message ordering](#message-ordering)
- [Load-balancing and advanced configurations](#load-balancing-and-advanced-configurations)
- [Errors](#errors)
- [Timeouts](#timeouts)
- [Encoding](#encoding)
- [Engine API -- Common Definitions](#engine-api----common-definitions)
- [Table of contents](#table-of-contents)
- [Underlying protocol](#underlying-protocol)
- [Authentication](#authentication)
- [Method Versioning](#method-versioning)
- [Structure Types](#structure-types)
- [Message ordering](#message-ordering)
- [Load-balancing and advanced configurations](#load-balancing-and-advanced-configurations)
- [Errors](#errors)
- [Timeouts](#timeouts)
- [Encoding](#encoding)

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

Expand Down Expand Up @@ -46,18 +49,28 @@ These methods are described in [Ethereum JSON-RPC Specification][json-rpc-spec].
Engine API uses JWT authentication enabled by default.
JWT authentication is specified in [Authentication](./authentication.md) document.

## Versioning
## Method Versioning

The versioning of the Engine API is defined as follows:

* The version of each method and structure is independent from versions of other methods and structures.
* The `VX`, where the `X` is the number of the version, is suffixed to the name of each method and structure.
* The version of a method or a structure **MUST** be incremented by one if any of the following is changed:
* The version of each method is independent from versions of other methods or numbers of structural types.
* The `VX`, where the `X` is the number of the version, is suffixed to the name of each method.
* The version of a method **MUST** be incremented by one if any of the following is changed:
* a set of method parameters
* a method response value
* a method behavior
* The specification **MAY** reference a method without the version suffix e.g. `engine_newPayload`. These statements should be read as related to all versions of the referenced method.

## Structure Types

Structural types of the Engine API are defined as follows:

* Types for a structure are numbered for differentiation
* The type number of each structure is independent from numbers of other structural types or versions of methods.
* The `TypeX`, where the `X` is the number of the type, is suffixed to the name of each structure.
* The type of a a structure **MUST** be incremented by one if any of the following is changed:
* a set of structure fields
* The specification **MAY** reference a method or a structure without the version suffix e.g. `engine_newPayload`. These statements should be read as related to all versions of the referenced method or structure.
* The specification **MAY** reference a structure without the type suffix e.g. `ExecutionPayload`. These statements should be read as related to all available types of the referenced structure.

## Message ordering

Expand Down
42 changes: 21 additions & 21 deletions src/engine/experimental/blob-extension.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@

- [Shard Blob Extension](#shard-blob-extension)
- [Structures](#structures)
- [ExecutionPayloadV3](#executionpayloadv3)
- [BlobsBundleV1](#blobsbundlev1)
- [ExecutionPayloadType3](#executionpayloadtype3)
- [BlobsBundleType1](#blobsbundletype1)
- [Methods](#methods)
- [engine_newPayloadV3](#engine_newpayloadv3)
- [engine\_newPayloadV3](#engine_newpayloadv3)
- [Request](#request)
- [Specification](#specification)
- [Response](#response)
- [engine_getPayloadV3](#engine_getpayloadv3)
- [engine\_getPayloadV3](#engine_getpayloadv3)
- [Request](#request-1)
- [Response](#response-1)
- [Specification](#specification-1)
- [engine_getBlobsBundleV1](#engine_getblobsbundlev1)
- [engine\_getBlobsBundleType1](#engine_getblobsbundletype1)
- [Request](#request-2)
- [Response](#response-2)
- [Specification](#specification-2)
Expand All @@ -29,9 +29,9 @@ This extension is backwards-compatible, but not part of the initial Engine API.

## Structures

### ExecutionPayloadV3
### ExecutionPayloadType3

This structure has the syntax of `ExecutionPayloadV2` and appends a single field: `excessDataGas`.
This structure has the syntax of `ExecutionPayloadType2` and appends a single field: `excessDataGas`.

- `parentHash`: `DATA`, 32 Bytes
- `feeRecipient`: `DATA`, 20 Bytes
Expand All @@ -48,9 +48,9 @@ This structure has the syntax of `ExecutionPayloadV2` and appends a single field
- `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.
- `withdrawals`: `Array of WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure.

### BlobsBundleV1
### BlobsBundleType1

The fields are encoded as follows:

Expand All @@ -66,10 +66,10 @@ The fields are encoded as follows:

* method: `engine_newPayloadV3`
* params:
1. [`ExecutionPayloadV1`](../paris.md#ExecutionPayloadV1) | [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3), where:
- `ExecutionPayloadV1` **MUST** be used if the `timestamp` value is lower than the Shanghai timestamp,
- `ExecutionPayloadV2` **MUST** be used if the `timestamp` value is greater or equal to the Shanghai and lower than the EIP-4844 activation timestamp,
- `ExecutionPayloadV3` **MUST** be used if the `timestamp` value is greater or equal to the EIP-4844 activation timestamp,
1. [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadType3`](#ExecutionPayloadType3), where:
- `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the Shanghai timestamp,
- `ExecutionPayloadType2` **MUST** be used if the `timestamp` value is greater or equal to the Shanghai and lower than the EIP-4844 activation timestamp,
- `ExecutionPayloadType3` **MUST** be used if the `timestamp` value is greater or equal to the EIP-4844 activation timestamp,
- Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call.

#### Specification
Expand All @@ -92,18 +92,18 @@ Refer to the response for `engine_newPayloadV2`.
#### Response

* result: `object`
- `executionPayload`: [`ExecutionPayloadV1`](../paris.md#ExecutionPayloadV1) | [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV3`](#ExecutionPayloadV3) where:
- `ExecutionPayloadV1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp
- `ExecutionPayloadV2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp and lower than the EIP-4844 activation timestamp
- `ExecutionPayloadV3` **MUST** be returned if the payload `timestamp` is greater or equal to the EIP-4844 activation timestamp
- `executionPayload`: [`ExecutionPayloadType1`](../paris.md#ExecutionPayloadType1) | [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadType3`](#ExecutionPayloadType3) where:
- `ExecutionPayloadType1` **MUST** be returned if the payload `timestamp` is lower than the Shanghai timestamp
- `ExecutionPayloadType2` **MUST** be returned if the payload `timestamp` is greater or equal to the Shanghai timestamp and lower than the EIP-4844 activation timestamp
- `ExecutionPayloadType3` **MUST** be returned if the payload `timestamp` is greater or equal to the EIP-4844 activation timestamp
- `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
* error: code and message set in case an exception happens while getting the payload.

#### Specification

Refer to the specification for `engine_getPayloadV2`.

### engine_getBlobsBundleV1
### engine_getBlobsBundleType1
Copy link
Collaborator

Choose a reason for hiding this comment

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

Shouldn't we distinct method versions from structure types? I.e. shouldn't methods always be suffixed with VX?


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.
Expand All @@ -113,20 +113,20 @@ The separation of concerns aims to minimize changes during the testing phase of

#### Request

* method: `engine_getBlobsBundleV1`
* method: `engine_getBlobsBundleType1`
* params:
1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
* timeout: 1s

#### Response

* result: [`BlobsBundleV1`](#BlobsBundleV1)
* result: [`BlobsBundleType1`](#BlobsBundleType1)
* error: code and message set in case an exception happens while getting the blobs bundle.

#### 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_getPayloadV2` results **MUST** be consistent as outlined in items 3, 4 and 5 below.
and halt any further changes to the payload. The `engine_getBlobsBundleType1` 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.

Expand Down
44 changes: 23 additions & 21 deletions src/engine/experimental/eip6110.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,24 +7,26 @@ Engine API changes introduced in EIP-6110.
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Structures](#structures)
- [DepositV1](#depositv1)
- [ExecutionPayloadV6110](#executionpayloadv6110)
- [Methods](#methods)
- [engine_newPayloadV6110](#engine_newpayloadv6110)
- [Request](#request)
- [Response](#response)
- [Specification](#specification)
- [engine_getPayloadV6110](#engine_getpayloadv6110)
- [Request](#request-1)
- [Response](#response-1)
- [Specification](#specification-1)
- [Engine API -- EIP-6110](#engine-api----eip-6110)
- [Table of contents](#table-of-contents)
- [Structures](#structures)
- [DepositType1](#deposittype1)
- [ExecutionPayloadType6110](#executionpayloadtype6110)
- [Methods](#methods)
- [engine\_newPayloadV6110](#engine_newpayloadv6110)
- [Request](#request)
- [Response](#response)
- [Specification](#specification)
- [engine\_getPayloadV6110](#engine_getpayloadv6110)
- [Request](#request-1)
- [Response](#response-1)
- [Specification](#specification-1)

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

## Structures

### DepositV1
### DepositType1
This structure maps onto the deposit object from [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110).
The fields are encoded as follows:

Expand All @@ -36,9 +38,9 @@ The fields are encoded as follows:

*Note:* The `amount` value is represented in Gwei.

### ExecutionPayloadV6110
### ExecutionPayloadType6110

This structure has the syntax of [`ExecutionPayloadV2`](../shanghai.md#executionpayloadv2) and appends a single field: `deposits`.
This structure has the syntax of [`ExecutionPayloadType2`](../shanghai.md#executionpayloadv2) and appends a single field: `deposits`.

- `parentHash`: `DATA`, 32 Bytes
- `feeRecipient`: `DATA`, 20 Bytes
Expand All @@ -54,8 +56,8 @@ This structure has the syntax of [`ExecutionPayloadV2`](../shanghai.md#execution
- `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.
- `deposits`: `Array of DepositV1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositV1` structure.
- `withdrawals`: `Array of WithdrawalType1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalType1` structure.
- `deposits`: `Array of DepositType1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositType1` structure.

## Methods

Expand All @@ -65,9 +67,9 @@ This structure has the syntax of [`ExecutionPayloadV2`](../shanghai.md#execution

* method: `engine_newPayloadV6110`
* params:
1. [`ExecutionPayloadV2`](../shanghai.md#ExecutionPayloadV2) | [`ExecutionPayloadV6110`](#ExecutionPayloadV6110), where:
- `ExecutionPayloadV1` **MUST** be used if the `timestamp` value is lower than the EIP-6110 activation timestamp,
- `ExecutionPayloadV6110` **MUST** be used if the `timestamp` value is greater or equal to the EIP-6110 activation timestamp,
1. [`ExecutionPayloadType2`](../shanghai.md#ExecutionPayloadType2) | [`ExecutionPayloadType6110`](#ExecutionPayloadType6110), where:
- `ExecutionPayloadType1` **MUST** be used if the `timestamp` value is lower than the EIP-6110 activation timestamp,
- `ExecutionPayloadType6110` **MUST** be used if the `timestamp` value is greater or equal to the EIP-6110 activation timestamp,
- Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call.
* timeout: 8s

Expand All @@ -91,7 +93,7 @@ This method follows the same specification as [`engine_newPayloadV2`](../shangha
#### Response

Refer to the response for [`engine_getPayloadV2`](../shanghai.md#engine_getpayloadv2) with the following change:
* `executionPayload` data structure is changed to [`ExecutionPayloadV6110`](#ExecutionPayloadV6110).
* `executionPayload` data structure is changed to [`ExecutionPayloadType6110`](#ExecutionPayloadType6110).

#### Specification

Expand Down
Loading