diff --git a/src/engine/experimental/eip6110.md b/src/engine/experimental/eip6110.md new file mode 100644 index 000000000..567ec0ebe --- /dev/null +++ b/src/engine/experimental/eip6110.md @@ -0,0 +1,99 @@ +# Engine API -- EIP-6110 + +Engine API changes introduced in EIP-6110. + +## Table of contents + + + + +- [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) + + + +## Structures + +### DepositV1 +This structure maps onto the deposit object from [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110). +The fields are encoded as follows: + +- `pubkey`: `DATA`, 48 Bytes +- `withdrawal_credentials`: `DATA`, 32 Bytes +- `amount`: `QUANTITY`, 64 Bits +- `signature`: `DATA`, 96 Bytes +- `index`: `QUANTITY`, 64 Bits + +*Note:* The `amount` value is represented in Gwei. + +### ExecutionPayloadV6110 + +This structure has the syntax of [`ExecutionPayloadV2`](../shanghai.md#executionpayloadv2) and appends a single field: `deposits`. + +- `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. +- `deposits`: `Array of DepositV1` - Array of deposits, each object is an `OBJECT` containing the fields of a `DepositV1` structure. + +## Methods + +### engine_newPayloadV6110 + +#### Request + +* 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, + - Client software **MUST** return `-32602: Invalid params` error if the wrong version of the structure is used in the method call. +* timeout: 8s + +#### Response + +Refer to the response for [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2). + +#### Specification + +This method follows the same specification as [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2). + +### engine_getPayloadV6110 + +#### Request + +* method: `engine_getPayloadV6110` +* params: + 1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process +* timeout: 1s + +#### Response + +Refer to the response for [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2) with the following change: +* `executionPayload` data structure is changed to [`ExecutionPayloadV6110`](#ExecutionPayloadV6110). + +#### Specification + +Refer to the specification for [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2). +