Add initial FOCIL spec

src/engine/common.md

@@ -99,6 +99,7 @@ The list of error codes introduced by this specification can be found below.
 | -38003 | Invalid payload attributes | Payload attributes are invalid / inconsistent. |
 | -38004 | Too large request | Number of requested entities is too large. |
 | -38005 | Unsupported fork | Payload belongs to a fork that is not supported. |
+| -38006 | Unknown parent | Parent does not exist / is not available. |
 
 Each error returns a `null` `data` value, except `-32000` which returns the `data` object with a `err` member that explains the error encountered.
 

src/engine/experimental/eip7805.md

@@ -0,0 +1,133 @@
+# Engine API -- EIP-7805
+
+Engine API changes introduced in EIP-7805.
+
+This specification is based on and extends [Engine API - Osaka](./osaka.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)
+  - [PayloadAttributesV4](#payloadattributesv4)
+- [Routines](#routines)
+  - [Payload building](#payload-building)
+- [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_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4)
+    - [Request](#request-2)
+    - [Response](#response-2)
+    - [Specification](#specification-2)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Constants
+
+| Name | Value |
+| - | - |
+| `MAX_BYTES_PER_INCLUSION_LIST` |  `uint64(8192) = 2**13` |
+
+## Structures
+
+### PayloadAttributesV4
+
+This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends a single field: `inclusionListTransactions`.
+
+- `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.
+- `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).
+
+## Routines
+
+### Payload building
+
+This routine follows the same specification as [Payload building](./paris.md#payload-building) with the following changes to the processing flow:
+
+1. Client software **SHOULD** take `payloadAttributes.inclusionList` into account during the payload build process. The built `ExecutionPayload` **MUST** satisfy the inclusion list constraints with respect to `payloadAttributes.inclusionList` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805).
+
+## Methods
+
+### engine_newPayloadV5
+
+Method parameter list is extended with `inclusionListTransactions`.
+
+#### 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. `executionRequests`: `Array of DATA` - List of execution layer triggered requests. Each list element is a `requests` byte array as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). The first byte of each element is the `request_type` and the remaining bytes are the `request_data`. Elements of the list **MUST** be ordered by `request_type` in ascending order. Elements with empty `request_data` **MUST** be excluded from the list.
+  5. `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).
+
+#### Response
+
+* result: [`PayloadStatusV1`](./paris.md#payloadstatusv1), values of the `status` field are modified in the following way:
+  - `INVALID_BLOCK_HASH` status value is supplanted by `INVALID`.
+  - `INCLUSION_LIST_UNSATISFIED` status value is appended.
+* error: code and message set in case an exception happens while processing the payload.
+
+#### Specification
+
+This method follows the same specification as [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4) with the following changes:
+
+1. Client software **MUST** return `{status: INCLUSION_LIST_UNSATISFIED, latestValidHash: null, validationError: null}` if `executionPayload` fails to satisfy the inclusion list constraints with respect to `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805).
+
+### 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: `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** provide a list of transactions within upperbound `MAX_BYTES_PER_INCLUSION_LIST`.
+
+3. Client software **MUST NOT** include any [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#blob-transaction) within the provided list.
+
+4. Client software **MUST** return `-38006: Unknown parent` error if a block with the given `parentHash` does not exist.
+
+### 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_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3).
+
+#### Specification
+
+This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) with the following changes to the processing flow:
+
+1. Extend point (7) of the `engine_forkchoiceUpdatedV1` [specification](./paris.md#specification-1) by defining the following sequence of checks that **MUST** be run over `payloadAttributes`:
+
+    1. `payloadAttributes` matches the [`PayloadAttributesV4`](#payloadattributesv4) structure, return `-38003: Invalid payload attributes` on failure.