EIP-7547 engine API changes

src/engine/experimental/eip7547.md

@@ -0,0 +1,101 @@
+# 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 -->
+
+- [Constants](#constants)
+- [Structures](#structures)
+  - [InclusionListSummaryEntryV1](#inclusionlistsummaryentryv1)
+  - [InclusionListSummaryV1](#inclusionlistsummaryv1)
+  - [InclusionListStatusV1](#inclusionliststatusv1)
+- [Methods](#methods)
+  - [engine_newInclusionListV1](#engine_newinclusionlistv1)
+    - [Request](#request)
+    - [Response](#response)
+    - [Specification](#specification)
+  - [engine_getInclusionListV1](#engine_getinclusionlistv1)
+    - [Request](#request-1)
+    - [Response](#response-1)
+    - [Specification](#specification-1)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Constants
+
+| Name | Value |
+| - | - |
+| `INCLUSION_LIST_MAX_GAS` |  `uint64(4194304) = 2**22` |
+
+## Structures 
+
+### InclusionListSummaryEntryV1
+
+This structure contains the details of each inclusion list entry.
+
+- `address` : `DATA`, 20 Bytes
+- `nonce` : `QUANTITY`, 64 Bits
+
+### InclusionListSummaryV1
+
+This structure contains the inclusion list summary.
+
+- `slot` : `QUANTITY`, 64 Bits
+- `proposer_index`: `QUANTITY`, 64 Bits
+- `parent_hash`: `DATA`, 32 Bytes
+- `summary`: `Array of InclusionListSummaryEntryV1`, Array of entries that must be satisfied.
+
+### InclusionListStatusV1
+
+This structure contains the result of processing an inclusion list. The fields are encoded as follows:
+
+- `status`: `enum` - `"VALID" | "INVALID" | "SYNCING" | "ACCEPTED"`
+- `validationError`: `String|null` - a message providing additional details on the validation error if the payload is classified as `INVALID`.
+
+## Methods
+
+### engine_newInclusionListV1
+
+#### Request
+
+* method: `engine_newInclusionListV1`
+* params:
+  1. `inclusionListSummary`: `InclusionListSummaryV1` - Summary.
+  2. `inclusionListTransactions`: `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)
+* timeout: 1s
+
+#### Response
+
+* result: [`InclusionListStatusV1`](./#inclusionliststatusv1).
+* error: code and message set in case an exception happens while processing the inclusion list.
+
+#### Specification
+
+1. Client software **MUST** validate the inclusion list transactions are valid (correct nonce and sufficient base fee) given the parent block hash specified. If the parent block is not available, return false.
+2. Client software **MUST** validate that the sum of inclusion list transactions gas does not exceed `INCLUSION_LIST_MAX_GAS`.   
+3. Client software **MUST** validate that the summary and transactions are the same length.
+4. Client software **MUST** validate that the order of the summary entries matches the order of the transactions.
+
+### engine_getInclusionListV1
+
+#### Request
+
+* method: `engine_getInclusionListV1`
+* timeout: 1s
+
+#### Response
+
+* result: `object`
+  - `inclusionListSummary`: `InclusionListSummaryV1` - Summary.
+  - `inclusionListTransactions`: `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 and according to the config specifications.
+2. Client software **MUST** broadcast their inclusion list in addition to the full beacon block during their block proposal.