Add initial FOCIL spec

src/engine/focil.md

@@ -0,0 +1,123 @@
+# Engine API -- FOCIL
+
+Engine API changes introduced in FOCIL.
+
+This specification is based on and extends [Engine API - Prague](./prague.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)
+  - [InclusionListV1](#inclusionlistv1)
+  - [UpdateInclusionListResponse](#updateinclusionlistresponse)
+- [Methods](#methods)
+  - [engine_newPayloadV5](#engine_newpayloadv5)
+    - [Request](#request)
+    - [Response](#response)
+    - [Specification](#specification)
+  - [engine_getInclusionListV1](#engine_getinclusionlistv1)
+    - [Request](#request-1)
+    - [Response](#response-1)
+    - [Specification](#specification-1)
+  - [engine_updatePayloadWithInclusionListV1](#engine_updatepayloadwithinclusionlistv1)
+    - [Request](#request-2)
+    - [Response](#response-2)
+    - [Specification](#specification-2)
+  - [Update the methods of previous forks](#update-the-methods-of-previous-forks)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Constants
+
+| Name | Value |
+| - | - |
+| `MaxBytesPerInclusionList` |  `uint64(8192) = 2**13` |
+
+## Structures
+
+### InclusionListV1
+
+This structure contains a list of transactions. The fields are encoded as follows:
+- `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)
+
+### UpdateInclusionListResponse
+
+This structure contains an identifier of the payload build process that is requested to update with the given inclusion list.
+- `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
+
+## Methods
+
+### engine_newPayloadV5
+
+The request of this method is updated with [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3).
+
+#### Request
+
+* method: `engine_newPayloadV5`
+* params:
+  1. `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3).
+  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.
+  4. `inclusionList`: [`InclusionListV1`](#InclusionListV1).
+
+#### Response
+
+Refer to the response for [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4).
+
+#### Specification
+
+This method follows the same specification as [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4) with the following changes:
+
+1. Client software **MUST** return `{status: INVALID_INCLUSION_LIST, latestValidHash: null, validationError: null}` if there are any transactions of `inclusionList` that are not part of the `executionPayload`, even if they can be appended at the end of the `executionPayload`.
+
+### engine_getInclusionListV1
+
+#### Request
+
+* method: `engine_getInclusionListV1`
+* params:
+  1. `parentHash`: `DATA`, 32 Bytes - parent hash which returned inclusion list should be built upon.
+* timeout: 1s
+
+#### Response
+
+* result: [`InclusionListV1`](#InclusionListV1).
+* 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.
+
+### engine_updatePayloadWithInclusionListV1
+
+#### Request
+
+* method: `engine_updatePayloadWithInclusionListV1`
+* params:
+  1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process.
+  2. `inclusionList`: [`InclusionListV1`](#InclusionListV1).
+* timeout: 1s
+
+#### Response
+
+* result: [`UpdateInclusionListResponse`](#UpdateInclusionListResponse).
+* error: code and message set in case an exception happens while getting the inclusion list.
+
+#### Specification
+
+1. Given the `payloadId` client software **MUST** update payload build process building with `inclusionList`. The transactions must be part of the execution payload unless it fails to be included at the end of it.
+
+### Update the methods of previous forks
+
+This document defines how FOCIL payload should be handled by the [`Prague API`](./prague.md).
+
+For the following methods:
+
+- [`engine_newPayloadV4`](./prague.md#engine_newpayloadV4)
+
+a validation **MUST** be added:
+
+1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the FOCIL activation timestamp.