EIP-7547 engine API changes

src/engine/eip7547.md

@@ -0,0 +1,165 @@
+# Engine API -- EIP7547
+
+Engine API changes introduced in EIP7547.
+
+This specification is based on and extends [Engine API - Cancun](./cancun.md) specification.
+
+## 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)
+  - [InclusionListEntryV1](#inclusionlistentryv1)
+  - [ExecutionPayloadV4](#executionpayloadv4)
+  - [PayloadAttributesV4](#payloadattributesv4)
+- [Methods](#methods)
+  - [engine_newPayloadV4](#engine_newpayloadv4)
+    - [Request](#request)
+    - [Response](#response)
+    - [Specification](#specification)
+  - [engine_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4)
+    - [Request](#request-1)
+    - [Response](#response-1)
+    - [Specification](#specification-1)
+  - [engine_getPayloadV4](#engine_getpayloadv4)
+    - [Request](#request-2)
+    - [Response](#response-2)
+    - [Specification](#specification-2)
+  - [engine_getInclusionListV1](#engine_getinclusionlistv1)
+    - [Request](#request-3)
+    - [Response](#response-3)
+    - [Specification](#specification-3)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Structures
+
+### InclusionListEntryV1
+
+The fields are encoded as follows:
+
+- `address`: `DATA` - 20 byte address of the entry.
+- `gasLimit`: `DATA` - 32 byte max amount of gas consumed by the transaction.
+
+### ExecutionPayloadV4
+
+This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new fields: `inclusionListSummary` and `inclusionListExclusions`.
+
+- `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.
+- `blobGasUsed`: `QUANTITY`, 64 Bits
+- `excessBlobGas`: `QUANTITY`, 64 Bits
+- `inclusionListSummary`: `Array of InclusionListEntryV1` - Array of entries, each object is an `OBJECT` containing the fields in `InclusionListEntryV1` structure.
+- `inclusionListExclusions`: `Array of QUANTITY` - Array of 64 bit unsigned ints which represent the indices of the entries in the summary that are already satisfied.
+
+### PayloadAttributesV4
+
+This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends the new fields: `inclusionListTransactions` and `inclusionListExclusions`.
+
+- `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.
+- `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
+- `inclusionListTransations`: `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)
+- `inclusionListExclusions`: `Array of QUANTITY` - Array of 64 bit unsigned ints which represent the indices of the entries in the summary that are already satisfied.
+
+## Methods
+
+### engine_newPayloadV4
+
+#### Request
+
+* method: `engine_newPayloadV4`
+* params:
+  1. `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4).
+  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.
+
+#### Response
+
+Refer to the response for [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2).
+
+#### Specification
+
+This method follows the same specification as [`engine_newPayloadV3`](./shanghai.md#engine_newpayloadv3) with the addition of the following:
+
+1. Client software **MUST** check that provided inclusion list summary is satisfied. Each entry in the summary must either below to the exclusion list or have a transaction in the payload from that address.
+
+### engine_forkchoiceUpdatedV4
+
+#### Request
+
+* method: `engine_forkchoiceUpdatedV4`
+* params:
+  1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#ForkchoiceStateV1).
+  2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV4`](#payloadattributesv4) or `null`.
+* timeout: 8s
+
+#### Response
+
+Refer to the response for [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_forkchoiceupdatedv2).
+
+#### Specification
+
+This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) with the addition of the following:
+
+1. Client software **MUST** begin building the inclusion list if the `payloadAttributes` are supplied.
+
+### engine_getPayloadV4
+
+The response of this method is extended to have the [`ExecutionPayloadV4`](#executionpayloadv4) type.
+
+#### Request
+
+* method: `engine_getPayloadV4`
+* params:
+  1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
+* timeout: 1s
+
+#### Response
+
+* result: `object`
+  - `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4)
+  - `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
+  - `blobsBundle`: [`BlobsBundleV1`](#BlobsBundleV1) - Bundle with data corresponding to blob transactions included into `executionPayload`
+  - `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the execution layer to use this `executionPayload` instead of an externally provided one
+* error: code and message set in case an exception happens while getting the payload.
+
+#### Specification
+
+Refer to the specification for [`engine_getPayloadV3`](./cancun.md#engine_getpayloadv3).
+
+### engine_getInclusionListV1
+
+#### Request
+
+* method: `engine_getInclusionListV1`
+* params:
+  1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
+* timeout: 1s
+
+#### Response
+
+* result: `object`
+  - `inclusionListSummary`: `Array of InclusionListEntryV1` - Array of entries, each object is an `OBJECT` containing the fields in `InclusionListEntryV1` structure.
+  - `inclusionListTransations`: `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)
+* error: code and message set in case an exception happens while getting the inclusion list.
+
+#### Specification
+
+1. Client software **MUST** provide a list of transactions for the inclusion list based on local view of the mempool.