Engine API: initial draft of EIP-6110 spec

src/engine/experimental/eip6110.md

@@ -0,0 +1,99 @@
+# Engine API -- EIP-6110
+
+Engine API changes introduced in EIP-6110.
+
+## 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)
+  - [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)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## 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).
+