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: break down the spec by fork scopes #327

Merged
merged 4 commits into from
Dec 20, 2022
Merged

Engine API: break down the spec by fork scopes #327

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6dcd49a
Decouple shanghai spec
mkalinin Nov 16, 2022
3da8b44
Rip Paris out of the main spec
mkalinin Dec 9, 2022
1489a3d
Add experimental/
mkalinin Dec 19, 2022
68c0a26
Merge branch 'main' into shanghai
mkalinin Dec 19, 2022
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
130 changes: 130 additions & 0 deletions src/engine/shanghai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# Shanghai -- Engine API

## Table of contents

<!-- 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)
- [WithdrawalV1](#withdrawalv1)
- [ExecutionPayloadV2](#executionpayloadv2)
- [PayloadAttributesV2](#payloadattributesv2)
- [Methods](#methods)
- [engine_newPayloadV2](#engine_newpayloadv2)
- [Request](#request)
- [Response](#response)
- [Specification](#specification)
- [engine_forkchoiceUpdatedV2](#engine_forkchoiceupdatedv2)
- [Request](#request-1)
- [Response](#response-1)
- [Specification](#specification-1)
- [engine_getPayloadV2](#engine_getpayloadv2)
- [Request](#request-2)
- [Response](#response-2)
- [Specification](#specification-2)

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

## Structures

### WithdrawalV1

This structure maps onto the validator withdrawal object from the beacon chain spec.
The fields are encoded as follows:

- `index`: `QUANTITY`, 64 Bits
- `validatorIndex`: `QUANTITY`, 64 Bits
- `address`: `DATA`, 20 Bytes
- `amount`: `QUANTITY`, 256 Bits

*Note*: the `amount` value is represented on the beacon chain as a little-endian value in units of Gwei, whereas the `amount` in this structure *MUST* be converted to a big-endian value in units of Wei.

### ExecutionPayloadV2

This structure has the syntax of `ExecutionPayloadV1` and appends a single field: `withdrawals`.

- `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.

### PayloadAttributesV2

This structure has the syntax of `PayloadAttributesV1` and appends a single field: `withdrawals`.

- `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload
- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload
- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.

## Methods

### engine_newPayloadV2

#### Request

* method: `engine_newPayloadV2`
* params:
1. [`ExecutionPayloadV2`](#ExecutionPayloadV2)

#### Response

Refer to the response for [`engine_newPayloadV1`](./specification.md#engine_newpayloadv1).

#### Specification

This method follows the same specification as [`engine_newPayloadV1`](./specification.md#engine_newpayloadv1) with the exception of the following:

1. If withdrawal functionality is activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payload.withdrawals` is `null`.
Similarly, if the functionality is not activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payloadAttributes.withdrawals` is not `null`.
Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value.
Refer to the validity conditions for [`engine_newPayloadV1`](./specification.md#engine_newpayloadv1) to specification of the appropriate `latestValidHash` value.

### engine_forkchoiceUpdatedV2

#### Request

* method: "engine_forkchoiceUpdatedV2"
* params:
1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](./specification.md#ForkchoiceStateV1)
2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV2`](#PayloadAttributesV2) or `null`

#### Response

Refer to the response for [`engine_forkchoiceUpdatedV1`](./specification.md#engine_forkchoiceupdatedv1).

#### Specification

This method follows the same specification as [`engine_forkchoiceUpdatedV1`](./specification.md#engine_forkchoiceupdatedv1) with the exception of the following:

1. If withdrawal functionality is activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is `null`.
Similarly, if the functionality is not activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is not `null`.
Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value.

### engine_getPayloadV2

#### Request

* method: `engine_getPayloadV2`
* params:
1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process

#### Response

* result: [`ExecutionPayloadV2`](#ExecutionPayloadV2)
* error: code and message set in case an exception happens while getting the payload.

#### Specification

Refer to the specification for [`engine_getPayloadV1`](./specification.md#engine_getpayloadv1).
121 changes: 3 additions & 118 deletions src/engine/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,8 @@ This document specifies the Engine API methods that the Consensus Layer uses to
- [Timeouts](#timeouts)
- [Structures](#structures)
- [ExecutionPayloadV1](#executionpayloadv1)
- [WithdrawalV1](#withdrawalv1)
- [ExecutionPayloadV2](#executionpayloadv2)
- [ForkchoiceStateV1](#forkchoicestatev1)
- [PayloadAttributesV1](#payloadattributesv1)
- [PayloadAttributesV2](#payloadattributesv2)
- [PayloadStatusV1](#payloadstatusv1)
- [TransitionConfigurationV1](#transitionconfigurationv1)
- [Routines](#routines)
Expand All @@ -32,30 +29,18 @@ This document specifies the Engine API methods that the Consensus Layer uses to
- [Request](#request)
- [Response](#response)
- [Specification](#specification)
- [engine_newPayloadV2](#engine_newpayloadv2)
- [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1)
- [Request](#request-1)
- [Response](#response-1)
- [Specification](#specification-1)
- [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1)
- [engine_getPayloadV1](#engine_getpayloadv1)
- [Request](#request-2)
- [Response](#response-2)
- [Specification](#specification-2)
- [engine_forkchoiceUpdatedV2](#engine_forkchoiceupdatedv2)
- [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1)
- [Request](#request-3)
- [Response](#response-3)
- [Specification](#specification-3)
- [engine_getPayloadV1](#engine_getpayloadv1)
- [Request](#request-4)
- [Response](#response-4)
- [Specification](#specification-4)
- [engine_getPayloadV2](#engine_getpayloadv2)
- [Request](#request-5)
- [Response](#response-5)
- [Specification](#specification-5)
- [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1)
- [Request](#request-6)
- [Response](#response-6)
- [Specification](#specification-6)

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

Expand Down Expand Up @@ -189,38 +174,6 @@ This structure maps on the [`ExecutionPayload`](https://github.com/ethereum/cons
- `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)

### WithdrawalV1

This structure maps onto the validator withdrawal object from the beacon chain spec.
The fields are encoded as follows:

- `index`: `QUANTITY`, 64 Bits
- `validatorIndex`: `QUANTITY`, 64 Bits
- `address`: `DATA`, 20 Bytes
- `amount`: `QUANTITY`, 256 Bits

*Note*: the `amount` value is represented on the beacon chain as a little-endian value in units of Gwei, whereas the `amount` in this structure *MUST* be converted to a big-endian value in units of Wei.

### ExecutionPayloadV2

This structure has the syntax of `ExecutionPayloadV1` and appends a single field: `withdrawals`.

- `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.

### ForkchoiceStateV1

This structure encapsulates the fork choice state. The fields are encoded as follows:
Expand All @@ -239,15 +192,6 @@ This structure contains the attributes required to initiate a payload build proc
- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload
- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload

### PayloadAttributesV2

This structure has the syntax of `PayloadAttributesV1` and appends a single field: `withdrawals`.

- `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload
- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload
- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.

### PayloadStatusV1

This structure contains the result of processing a payload. The fields are encoded as follows:
Expand Down Expand Up @@ -348,27 +292,6 @@ The payload build process is specified as follows:

6. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.

### engine_newPayloadV2

#### Request

* method: `engine_newPayloadV2`
* params:
1. [`ExecutionPayloadV2`](#ExecutionPayloadV2)

#### Response

Refer to the response for [`engine_newPayloadV1`](#engine_newpayloadv1).

#### Specification

This method follows the same specification as [`engine_newPayloadV1`](#engine_newpayloadv1) with the exception of the following:

1. If withdrawal functionality is activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payload.withdrawals` is `null`.
Similarly, if the functionality is not activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payloadAttributes.withdrawals` is not `null`.
Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value.
Refer to the validity conditions for [`engine_newPayloadV1`](#engine_newpayloadv1) to specification of the appropriate `latestValidHash` value.

### engine_forkchoiceUpdatedV1

#### Request
Expand Down Expand Up @@ -420,27 +343,6 @@ This method follows the same specification as [`engine_newPayloadV1`](#engine_ne

10. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.

### engine_forkchoiceUpdatedV2

#### Request

* method: "engine_forkchoiceUpdatedV2"
* params:
1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](#ForkchoiceStateV1)
2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV2`](#PayloadAttributesV2) or `null`

#### Response

Refer to the response for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1).

#### Specification

This method follows the same specification as [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1) with the exception of the following:

1. If withdrawal functionality is activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is `null`.
Similarly, if the functionality is not activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is not `null`.
Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value.

### engine_getPayloadV1

#### Request
Expand All @@ -463,23 +365,6 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV1`](#en

3. Client software **MAY** stop the corresponding build process after serving this call.

### engine_getPayloadV2

#### Request

* method: `engine_getPayloadV2`
* params:
1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process

#### Response

* result: [`ExecutionPayloadV2`](#ExecutionPayloadV2)
* error: code and message set in case an exception happens while getting the payload.

#### Specification

Refer to the specification for [`engine_getPayloadV1`](#engine_getpayloadv1).

### engine_exchangeTransitionConfigurationV1

#### Request
Expand Down