From c806cf330e8e949e24fd5895971529eb37156c65 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 14 Dec 2024 22:50:25 +0900 Subject: [PATCH 1/6] Add initial FOCIL spec --- src/engine/focil.md | 124 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 src/engine/focil.md diff --git a/src/engine/focil.md b/src/engine/focil.md new file mode 100644 index 000000000..39388e2a2 --- /dev/null +++ b/src/engine/focil.md @@ -0,0 +1,124 @@ +# 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 + + + + +- [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) + + + +## 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 + +Method parameter list is extended with `inclusionList`. + +#### 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. `inclusionList`: `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 + +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. From b727b7c66f45743d6ac08a9fa390336038b40e7a Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Thu, 9 Jan 2025 16:34:29 +0900 Subject: [PATCH 2/6] Move EIP-7805 spec under experimental folder --- src/engine/{focil.md => experimental/eip7805.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename src/engine/{focil.md => experimental/eip7805.md} (98%) diff --git a/src/engine/focil.md b/src/engine/experimental/eip7805.md similarity index 98% rename from src/engine/focil.md rename to src/engine/experimental/eip7805.md index 39388e2a2..0d4488313 100644 --- a/src/engine/focil.md +++ b/src/engine/experimental/eip7805.md @@ -1,6 +1,6 @@ -# Engine API -- FOCIL +# Engine API -- EIP-7805 -Engine API changes introduced in FOCIL. +Engine API changes introduced in EIP-7805. This specification is based on and extends [Engine API - Prague](./prague.md) specification. From 7d38fd71c163119f0ed40f9aa95084d16215ba4f Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sun, 19 Jan 2025 13:59:44 +0900 Subject: [PATCH 3/6] Use primitive type instead of new structures to not make dependency --- src/engine/experimental/eip7805.md | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/src/engine/experimental/eip7805.md b/src/engine/experimental/eip7805.md index 0d4488313..3f26c577d 100644 --- a/src/engine/experimental/eip7805.md +++ b/src/engine/experimental/eip7805.md @@ -10,9 +10,6 @@ This specification is based on and extends [Engine API - Prague](./prague.md) sp - [Constants](#constants) -- [Structures](#structures) - - [InclusionListV1](#inclusionlistv1) - - [UpdateInclusionListResponse](#updateinclusionlistresponse) - [Methods](#methods) - [engine_newPayloadV5](#engine_newpayloadv5) - [Request](#request) @@ -36,18 +33,6 @@ This specification is based on and extends [Engine API - Prague](./prague.md) sp | - | - | | `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 @@ -85,7 +70,7 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m #### Response -* result: [`InclusionListV1`](#InclusionListV1). +* result: `inclusionList`: `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 @@ -99,12 +84,12 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m * method: `engine_updatePayloadWithInclusionListV1` * params: 1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process. - 2. `inclusionList`: [`InclusionListV1`](#InclusionListV1). + 2. `inclusionList`: `inclusionList`: `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: [`UpdateInclusionListResponse`](#UpdateInclusionListResponse). +* result: `payloadId`: `DATA|null`, 8 Bytes - identifier of the payload build process or `null` * error: code and message set in case an exception happens while getting the inclusion list. #### Specification From a9292df894b00ebd2476fa80293222fc08e481c9 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 29 Mar 2025 20:06:08 +0900 Subject: [PATCH 4/6] Specify the upper bound of a list of inclusion lists --- src/engine/experimental/eip7805.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/engine/experimental/eip7805.md b/src/engine/experimental/eip7805.md index 3f26c577d..5621f6530 100644 --- a/src/engine/experimental/eip7805.md +++ b/src/engine/experimental/eip7805.md @@ -31,7 +31,7 @@ This specification is based on and extends [Engine API - Prague](./prague.md) sp | Name | Value | | - | - | -| `MaxBytesPerInclusionList` | `uint64(8192) = 2**13` | +| `MAX_BYTES_PER_INCLUSION_LIST` | `uint64(8192) = 2**13` | ## Methods @@ -77,6 +77,8 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m 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`. + ### engine_updatePayloadWithInclusionListV1 #### Request From b04e5327c2d402d1fb2d30ba211d193df9911bdb Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Wed, 30 Apr 2025 16:00:04 +0900 Subject: [PATCH 5/6] Add rules to ignore any blob transactions in the ILs --- src/engine/experimental/eip7805.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/engine/experimental/eip7805.md b/src/engine/experimental/eip7805.md index 5621f6530..c0c27deae 100644 --- a/src/engine/experimental/eip7805.md +++ b/src/engine/experimental/eip7805.md @@ -79,6 +79,8 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m 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. + ### engine_updatePayloadWithInclusionListV1 #### Request @@ -98,6 +100,8 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m 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. +2. Client software **SHOULD** ignore any [blob transactions](https://eips.ethereum.org/EIPS/eip-4844#blob-transaction) present in the `inclusionList` when updating the execution payload. + ### Update the methods of previous forks This document defines how FOCIL payload should be handled by the [`Prague API`](./prague.md). From 1c22e31fb7ffab128e48ba2b0b6da9d469382bbe Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Wed, 18 Jun 2025 19:00:50 +0200 Subject: [PATCH 6/6] Rebase onto Osaka --- src/engine/experimental/eip7805.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/experimental/eip7805.md b/src/engine/experimental/eip7805.md index c0c27deae..678eb2425 100644 --- a/src/engine/experimental/eip7805.md +++ b/src/engine/experimental/eip7805.md @@ -2,7 +2,7 @@ Engine API changes introduced in EIP-7805. -This specification is based on and extends [Engine API - Prague](./prague.md) specification. +This specification is based on and extends [Engine API - Osaka](./osaka.md) specification. ## Table of contents