From 4bbd6d1f24f97bf1e03c0d23fecb4269cd2b2ea0 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 14 Dec 2024 22:50:25 +0900 Subject: [PATCH 01/22] 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 7854b10c279740f3ee1f6fe1280f863c159080fc Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Thu, 9 Jan 2025 16:34:29 +0900 Subject: [PATCH 02/22] 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 7ca69971594c8ad7558f4c0e519eb77b3e67999b Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sun, 19 Jan 2025 13:59:44 +0900 Subject: [PATCH 03/22] 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 44cb2c1739f973ecb5889c6df67d2c5d02c9f1db Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 29 Mar 2025 20:06:08 +0900 Subject: [PATCH 04/22] 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 011713fd2dcd0c974bcd7b0487c0d980d65969cc Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Wed, 30 Apr 2025 16:00:04 +0900 Subject: [PATCH 05/22] 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 eabca930a9691a86e2c57e6bd40d1232e64aac17 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Wed, 18 Jun 2025 19:00:50 +0200 Subject: [PATCH 06/22] 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 From d82a82d191b57a087121e5024d9a91a079066323 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Thu, 14 Aug 2025 22:43:41 +0900 Subject: [PATCH 07/22] Reflect changes in the queue --- src/engine/common.md | 1 + src/engine/experimental/eip7805.md | 72 +++++++++++++++++++----------- 2 files changed, 46 insertions(+), 27 deletions(-) diff --git a/src/engine/common.md b/src/engine/common.md index 64ca875f5..836af0449 100644 --- a/src/engine/common.md +++ b/src/engine/common.md @@ -100,6 +100,7 @@ The list of error codes introduced by this specification can be found below. | -38004 | Too large request | Number of requested entities is too large. | | -38005 | Unsupported fork | Payload belongs to a fork that is not supported. | | -38006 | Too deep reorg | Reorg depth exceeds limitation. | +| -38007 | 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. diff --git a/src/engine/experimental/eip7805.md b/src/engine/experimental/eip7805.md index 678eb2425..0773d3270 100644 --- a/src/engine/experimental/eip7805.md +++ b/src/engine/experimental/eip7805.md @@ -10,6 +10,10 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec - [Constants](#constants) +- [Structures](#structures) + - [PayloadAttributesV4](#payloadattributesv4) +- [Routines](#routines) + - [Payload building](#payload-building) - [Methods](#methods) - [engine_newPayloadV5](#engine_newpayloadv5) - [Request](#request) @@ -19,11 +23,10 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine_updatePayloadWithInclusionListV1](#engine_updatepayloadwithinclusionlistv1) + - [engine_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4) - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) - - [Update the methods of previous forks](#update-the-methods-of-previous-forks) @@ -33,11 +36,32 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec | - | - | | `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 `inclusionList`. +Method parameter list is extended with `inclusionListTransactions`. #### Request @@ -47,17 +71,20 @@ Method parameter list is extended with `inclusionList`. 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). + 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 -Refer to the response for [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4). +* 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: 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`. +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 @@ -70,7 +97,7 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m #### Response -* 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). +* 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 @@ -81,35 +108,26 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m 3. Client software **MUST NOT** include any [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#blob-transaction) within the provided list. -### engine_updatePayloadWithInclusionListV1 +4. Client software **MUST** return `-38007: Unknown parent` error if a block with the given `parentHash` does not exist. + +### engine_forkchoiceUpdatedV4 #### Request -* method: `engine_updatePayloadWithInclusionListV1` +* method: `engine_forkchoiceUpdatedV4` * params: - 1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process. - 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 + 1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#forkchoicestatev1). + 2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV4`](#payloadattributesv4) or `null`. +* timeout: 8s #### Response -* 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. +Refer to the response for [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3). #### 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. - -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). - -For the following methods: - -- [`engine_newPayloadV4`](./prague.md#engine_newpayloadV4) +This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) with the following changes to the processing flow: -a validation **MUST** be added: +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. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload or payloadAttributes greater or equal to the FOCIL activation timestamp. + 1. `payloadAttributes` matches the [`PayloadAttributesV4`](#payloadattributesv4) structure, return `-38003: Invalid payload attributes` on failure. From 06a2a6e4696b05447f7b0e4f20b88881b10544c1 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 21 Mar 2026 00:44:37 +0900 Subject: [PATCH 08/22] Revamp and rebase to Bogota --- .../{experimental/eip7805.md => bogota.md} | 77 ++++++++++++------- 1 file changed, 51 insertions(+), 26 deletions(-) rename src/engine/{experimental/eip7805.md => bogota.md} (54%) diff --git a/src/engine/experimental/eip7805.md b/src/engine/bogota.md similarity index 54% rename from src/engine/experimental/eip7805.md rename to src/engine/bogota.md index 0773d3270..fd999e23d 100644 --- a/src/engine/experimental/eip7805.md +++ b/src/engine/bogota.md @@ -1,8 +1,8 @@ -# Engine API -- EIP-7805 +# Engine API -- Bogota -Engine API changes introduced in EIP-7805. +Engine API changes introduced in Bogota. -This specification is based on and extends [Engine API - Osaka](./osaka.md) specification. +This specification is based on and extends [Engine API - Amsterdam](./amsterdam.md) specification. ## Table of contents @@ -11,11 +11,11 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec - [Constants](#constants) - [Structures](#structures) - - [PayloadAttributesV4](#payloadattributesv4) + - [PayloadAttributesV5](#payloadattributesv5) - [Routines](#routines) - [Payload building](#payload-building) - [Methods](#methods) - - [engine_newPayloadV5](#engine_newpayloadv5) + - [engine_newPayloadV6](#engine_newpayloadv6) - [Request](#request) - [Response](#response) - [Specification](#specification) @@ -23,10 +23,12 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec - [Request](#request-1) - [Response](#response-1) - [Specification](#specification-1) - - [engine_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4) + - [engine_forkchoiceUpdatedV5](#engine_forkchoiceupdatedv5) - [Request](#request-2) - [Response](#response-2) - [Specification](#specification-2) + - [Update the methods of previous forks](#update-the-methods-of-previous-forks) + - [Amsterdam API](#amsterdam-api) @@ -38,15 +40,16 @@ This specification is based on and extends [Engine API - Osaka](./osaka.md) spec ## Structures -### PayloadAttributesV4 +### PayloadAttributesV5 -This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends a single field: `inclusionListTransactions`. +This structure has the syntax of [`PayloadAttributesV4`](./amsterdam.md#payloadattributesv4) 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. +- `slotNumber`: `QUANTITY`, 64 Bits - value for the `slotNumber` field of the new payload - `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 @@ -55,19 +58,19 @@ This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattr 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). +1. Client software **SHOULD** take `inclusionListTransactions` into account during the payload build process. The built `ExecutionPayload` **MUST** satisfy the inclusion list constraints with respect to `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). ## Methods -### engine_newPayloadV5 +### engine_newPayloadV6 Method parameter list is extended with `inclusionListTransactions`. #### Request -* method: `engine_newPayloadV5` +* method: `engine_newPayloadV6` * params: - 1. `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3). + 1. `executionPayload`: [`ExecutionPayloadV4`](./amsterdam.md#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. 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. @@ -82,9 +85,11 @@ Method parameter list is extended with `inclusionListTransactions`. #### Specification -This method follows the same specification as [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4) with the following changes: +This method follows the same specification as [`engine_newPayloadV5`](./amsterdam.md#engine_newpayloadv5) 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). +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Bogota fork. + +2. 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 @@ -92,42 +97,62 @@ This method follows the same specification as [`engine_newPayloadV4`](./prague.m * method: `engine_getInclusionListV1` * params: - 1. `parentHash`: `DATA`, 32 Bytes - parent hash which returned inclusion list should be built upon. + 1. `parentHash`: `DATA`, 32 Bytes - block hash of the parent block upon which the inclusion list should be built. + * 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). +* result: `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. +1. Client software **MUST** return `-38007: Unknown parent` error if a block with the given `parentHash` does not exist. -2. Client software **MUST** provide a list of transactions within upperbound `MAX_BYTES_PER_INCLUSION_LIST`. +2. Client software **MUST** provide a list of transactions for the inclusion list based on the local view of the mempool. The strategy for selecting which transactions to include is implementation dependent. -3. Client software **MUST NOT** include any [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#blob-transaction) within the provided list. +3. Client software **MUST** ensure the byte length of the RLP encoding of the returned transaction list does not exceed `MAX_BYTES_PER_INCLUSION_LIST`. -4. Client software **MUST** return `-38007: Unknown parent` error if a block with the given `parentHash` does not exist. +4. Client software **MUST NOT** include any [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#blob-transaction) in the returned transaction list. -### engine_forkchoiceUpdatedV4 +### engine_forkchoiceUpdatedV5 #### Request -* method: `engine_forkchoiceUpdatedV4` +* method: `engine_forkchoiceUpdatedV5` * params: 1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#forkchoicestatev1). - 2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV4`](#payloadattributesv4) or `null`. + 2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV5`](#payloadattributesv5) or `null`. * timeout: 8s #### Response -Refer to the response for [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3). +Refer to the response for [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4). #### Specification -This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) with the following changes to the processing flow: +This method follows the same specification as [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4) 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. + 1. `payloadAttributes` matches the [`PayloadAttributesV5`](#payloadattributesv5) structure, return `-38003: Invalid payload attributes` on failure. + + 2. `payloadAttributes.timestamp` does not fall within the time frame of the Bogota fork, return `-38005: Unsupported fork` on failure. + + 3. `payloadAttributes.timestamp` is greater than `timestamp` of a block referenced by `forkchoiceState.headBlockHash`, return `-38003: Invalid payload attributes` on failure. + + 4. If any of the above checks fails, the `forkchoiceState` update **MUST NOT** be rolled back. + +### Update the methods of previous forks + +#### Amsterdam API + +For the following methods: + +- [`engine_newPayloadV5`](./amsterdam.md#engine_newpayloadv5) +- [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4) + +a validation **MUST** be added: + +1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload is greater than or equal to the Bogota activation timestamp. From 37e6278389183cf28a56c3b70b3d4142e6264ce6 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 25 Apr 2026 00:43:48 +0900 Subject: [PATCH 09/22] Reflect #786 to Botoga --- src/engine/bogota.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index fd999e23d..a7aa2961f 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -134,7 +134,7 @@ Refer to the response for [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_f This method follows the same specification as [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4) 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. Extend point (8) 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 [`PayloadAttributesV5`](#payloadattributesv5) structure, return `-38003: Invalid payload attributes` on failure. From 3cb94d5d10c752264c62be36202f390e5010772d Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Tue, 26 May 2026 15:44:46 +0900 Subject: [PATCH 10/22] Remove redundant `status` modification statement --- src/engine/bogota.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index a7aa2961f..2bfaeb21b 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -79,7 +79,6 @@ Method parameter list is extended with `inclusionListTransactions`. #### 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. From 660fe42783a3220abc594aa8dea2eb7d780432e8 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Tue, 26 May 2026 15:45:09 +0900 Subject: [PATCH 11/22] Use `blockHash` instead of `parentHash` --- src/engine/bogota.md | 4 ++-- src/engine/common.md | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index 2bfaeb21b..d797c5093 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -96,7 +96,7 @@ This method follows the same specification as [`engine_newPayloadV5`](./amsterda * method: `engine_getInclusionListV1` * params: - 1. `parentHash`: `DATA`, 32 Bytes - block hash of the parent block upon which the inclusion list should be built. + 1. `blockHash`: `DATA`, 32 Bytes - block hash of the block upon which the inclusion list should be built. * timeout: 1s @@ -107,7 +107,7 @@ This method follows the same specification as [`engine_newPayloadV5`](./amsterda #### Specification -1. Client software **MUST** return `-38007: Unknown parent` error if a block with the given `parentHash` does not exist. +1. Client software **MUST** return `-38001: Unknown payload` error if a block with the given `blockHash` does not exist. 2. Client software **MUST** provide a list of transactions for the inclusion list based on the local view of the mempool. The strategy for selecting which transactions to include is implementation dependent. diff --git a/src/engine/common.md b/src/engine/common.md index 836af0449..64ca875f5 100644 --- a/src/engine/common.md +++ b/src/engine/common.md @@ -100,7 +100,6 @@ The list of error codes introduced by this specification can be found below. | -38004 | Too large request | Number of requested entities is too large. | | -38005 | Unsupported fork | Payload belongs to a fork that is not supported. | | -38006 | Too deep reorg | Reorg depth exceeds limitation. | -| -38007 | 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. From 259d803619a0fb7975262b6c7e565bba815a84fa Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Tue, 26 May 2026 15:55:46 +0900 Subject: [PATCH 12/22] Reflect #774 to Botoga --- src/engine/bogota.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index d797c5093..572f9d811 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -123,6 +123,7 @@ This method follows the same specification as [`engine_newPayloadV5`](./amsterda * params: 1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#forkchoicestatev1). 2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV5`](#payloadattributesv5) or `null`. + 3. `custodyColumns`: `DATA|null`, 16 Bytes - Interpreted as a bitarray of length `CELLS_PER_EXT_BLOB` indicating which column indices form the CL's custody set, or `null` if the CL does not provide custody services. * timeout: 8s #### Response From cbcb25735d0b40f5bf7e0a27dbd5727b0e5eff58 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Tue, 26 May 2026 15:56:25 +0900 Subject: [PATCH 13/22] Reflect #796 to Botoga --- src/engine/bogota.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index 572f9d811..7f59167d2 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -50,6 +50,7 @@ This structure has the syntax of [`PayloadAttributesV4`](./amsterdam.md#payloada - `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. - `slotNumber`: `QUANTITY`, 64 Bits - value for the `slotNumber` field of the new payload +- `targetGasLimit`: `QUANTITY`, 64 Bits - target value for the `gasLimit` field of the new payload - `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 From d2f26ef64ff2b6867c408f8ffe5e9a17fdee40bb Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Tue, 26 May 2026 18:00:28 +0900 Subject: [PATCH 14/22] Add RPC schemas for Bogota --- src/engine/openrpc/methods/forkchoice.yaml | 35 ++++++++++++++++ .../openrpc/methods/inclusion_list.yaml | 19 +++++++++ src/engine/openrpc/methods/payload.yaml | 41 +++++++++++++++++++ src/engine/openrpc/schemas/forkchoice.yaml | 32 +++++++++++++++ src/engine/openrpc/schemas/payload.yaml | 16 ++++++++ 5 files changed, 143 insertions(+) create mode 100644 src/engine/openrpc/methods/inclusion_list.yaml diff --git a/src/engine/openrpc/methods/forkchoice.yaml b/src/engine/openrpc/methods/forkchoice.yaml index ce3de624a..30e6c8e70 100644 --- a/src/engine/openrpc/methods/forkchoice.yaml +++ b/src/engine/openrpc/methods/forkchoice.yaml @@ -196,3 +196,38 @@ message: Unsupported fork - code: -38006 message: Too deep reorg +- name: engine_forkchoiceUpdatedV5 + summary: Updates the forkchoice state + externalDocs: + description: Method specification + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/bogota.md#engine_forkchoiceupdatedv5 + params: + - name: Forkchoice state + required: true + schema: + $ref: '#/components/schemas/ForkchoiceStateV1' + - name: Payload attributes + required: false + schema: + $ref: '#/components/schemas/PayloadAttributesV5' + - name: Custody columns + required: false + schema: + oneOf: + - $ref: '#/components/schemas/bytes16' + - type: 'null' + result: + name: Response object + schema: + $ref: '#/components/schemas/ForkchoiceUpdatedResponseV1' + errors: + - code: -38002 + message: Invalid forkchoice state + - code: -38003 + message: Invalid payload attributes + - code: -32602 + message: Invalid params + - code: -38005 + message: Unsupported fork + - code: -38006 + message: Too deep reorg diff --git a/src/engine/openrpc/methods/inclusion_list.yaml b/src/engine/openrpc/methods/inclusion_list.yaml new file mode 100644 index 000000000..00420821c --- /dev/null +++ b/src/engine/openrpc/methods/inclusion_list.yaml @@ -0,0 +1,19 @@ +- name: engine_getInclusionListV1 + summary: Obtains an inclusion list built upon the given block hash + externalDocs: + description: Method specification + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/bogota.md#engine_getinclusionlistv1 + params: + - name: Block hash + required: true + schema: + $ref: '#/components/schemas/hash32' + result: + name: Inclusion list transactions + schema: + type: array + items: + $ref: '#/components/schemas/bytes' + errors: + - code: -38001 + message: Unknown payload diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml index 7335ae4ad..757ffe68a 100644 --- a/src/engine/openrpc/methods/payload.yaml +++ b/src/engine/openrpc/methods/payload.yaml @@ -1070,6 +1070,47 @@ status: VALID latestValidHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858' validationError: null +- name: engine_newPayloadV6 + summary: Runs execution payload validation + externalDocs: + description: Method specification + url: https://github.com/ethereum/execution-apis/blob/main/src/engine/bogota.md#engine_newpayloadv6 + params: + - name: Execution payload + required: true + schema: + $ref: '#/components/schemas/ExecutionPayloadV4' + - name: Expected blob versioned hashes + required: true + schema: + type: array + items: + $ref: '#/components/schemas/hash32' + - name: Parent beacon block root + required: true + schema: + $ref: '#/components/schemas/hash32' + - name: Execution requests + required: true + schema: + type: array + items: + $ref: '#/components/schemas/bytes' + - name: Inclusion list transactions + required: true + schema: + type: array + items: + $ref: '#/components/schemas/bytes' + result: + name: Payload status + schema: + $ref: '#/components/schemas/PayloadStatusInclusionListUnsatisfied' + errors: + - code: -32602 + message: Invalid params + - code: -38005 + message: Unsupported fork - name: engine_getPayloadV6 summary: Obtains execution payload from payload build process externalDocs: diff --git a/src/engine/openrpc/schemas/forkchoice.yaml b/src/engine/openrpc/schemas/forkchoice.yaml index af9f7d067..b893deb93 100644 --- a/src/engine/openrpc/schemas/forkchoice.yaml +++ b/src/engine/openrpc/schemas/forkchoice.yaml @@ -113,3 +113,35 @@ PayloadAttributesV4: targetGasLimit: title: Target gas limit $ref: '#/components/schemas/uint64' +PayloadAttributesV5: + title: Payload attributes object V5 + type: object + required: + - timestamp + - prevRandao + - suggestedFeeRecipient + - withdrawals + - parentBeaconBlockRoot + - slotNumber + - targetGasLimit + - inclusionListTransactions + properties: + timestamp: + $ref: '#/components/schemas/PayloadAttributesV4/properties/timestamp' + prevRandao: + $ref: '#/components/schemas/PayloadAttributesV4/properties/prevRandao' + suggestedFeeRecipient: + $ref: '#/components/schemas/PayloadAttributesV4/properties/suggestedFeeRecipient' + withdrawals: + $ref: '#/components/schemas/PayloadAttributesV4/properties/withdrawals' + parentBeaconBlockRoot: + $ref: '#/components/schemas/PayloadAttributesV4/properties/parentBeaconBlockRoot' + slotNumber: + $ref: '#/components/schemas/PayloadAttributesV4/properties/slotNumber' + targetGasLimit: + $ref: '#/components/schemas/PayloadAttributesV4/properties/targetGasLimit' + inclusionListTransactions: + title: Inclusion list transactions + type: array + items: + $ref: '#/components/schemas/bytes' diff --git a/src/engine/openrpc/schemas/payload.yaml b/src/engine/openrpc/schemas/payload.yaml index 182e2ce40..eb80f4215 100644 --- a/src/engine/openrpc/schemas/payload.yaml +++ b/src/engine/openrpc/schemas/payload.yaml @@ -48,6 +48,22 @@ PayloadStatusNoInvalidBlockHash: $ref: '#/components/schemas/PayloadStatusV1/properties/latestValidHash' validationError: $ref: '#/components/schemas/PayloadStatusV1/properties/validationError' +PayloadStatusInclusionListUnsatisfied: + $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash' + title: Payload status object appending INCLUSION_LIST_UNSATISFIED status + properties: + status: + $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/status' + enum: + - VALID + - INVALID + - SYNCING + - ACCEPTED + - INCLUSION_LIST_UNSATISFIED + latestValidHash: + $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/latestValidHash' + validationError: + $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/validationError' ExecutionPayloadV1: title: Execution payload object V1 type: object From 563e36e6888a16491d865dbf2a8dce2dbf5ba750 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Wed, 27 May 2026 18:35:41 +0900 Subject: [PATCH 15/22] Add getinclusionlistv and getInclusionListV to wordlist --- wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/wordlist.txt b/wordlist.txt index bbdd4cfdc..2c9d2a76c 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -46,6 +46,8 @@ FP getblobsbundlev getblobsv getclientversionv +getinclusionlistv +getInclusionListV graphql gwei https From 62de4bde76ca5797bebe41f7af0db3d3fffff9a9 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Wed, 27 May 2026 22:17:59 +0900 Subject: [PATCH 16/22] `INCLUSION_LIST_UNSATISFIED` payloads are a subset of `VALID` payloads --- src/engine/bogota.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index 7f59167d2..f27dfbe6b 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -89,7 +89,7 @@ This method follows the same specification as [`engine_newPayloadV5`](./amsterda 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Bogota fork. -2. 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). +2. Client software **MUST** return `{status: INCLUSION_LIST_UNSATISFIED, latestValidHash: null, validationError: null}` if `executionPayload` passed [payload validation](./paris.md#payload-validation) process and deemed `VALID` but 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 From 9a5c295e774102aa3ac15b50cd3e15421950d5d2 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 27 Jun 2026 12:35:27 +0900 Subject: [PATCH 17/22] Specify to must consider IL transactions while building a payload --- src/engine/bogota.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index f27dfbe6b..b5c8e0930 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -59,7 +59,7 @@ This structure has the syntax of [`PayloadAttributesV4`](./amsterdam.md#payloada 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 `inclusionListTransactions` into account during the payload build process. The built `ExecutionPayload` **MUST** satisfy the inclusion list constraints with respect to `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). +1. Client software **MUST** take `inclusionListTransactions` into account during the payload build process. The built `ExecutionPayload` **MUST** satisfy the inclusion list constraints with respect to `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). ## Methods From 59f7803673bb5e4ee9297d990b328fe520146be7 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 27 Jun 2026 12:31:52 +0900 Subject: [PATCH 18/22] Add PayloadStatusV2 --- src/engine/bogota.md | 12 ++++++++++++ src/engine/openrpc/methods/forkchoice.yaml | 2 +- src/engine/openrpc/methods/payload.yaml | 2 +- src/engine/openrpc/schemas/forkchoice.yaml | 14 +++++++++++++- src/engine/openrpc/schemas/payload.yaml | 13 +++++-------- 5 files changed, 32 insertions(+), 11 deletions(-) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index b5c8e0930..c3b0c56b3 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -12,6 +12,7 @@ This specification is based on and extends [Engine API - Amsterdam](./amsterdam. - [Constants](#constants) - [Structures](#structures) - [PayloadAttributesV5](#payloadattributesv5) + - [PayloadStatusV2](#payloadstatusv2) - [Routines](#routines) - [Payload building](#payload-building) - [Methods](#methods) @@ -53,6 +54,17 @@ This structure has the syntax of [`PayloadAttributesV4`](./amsterdam.md#payloada - `targetGasLimit`: `QUANTITY`, 64 Bits - target value for the `gasLimit` field of the new payload - `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). +### PayloadStatusV2 + +This structure has the syntax of `PayloadStatusV1` and appends a single field: `latestInclusionListSatisfiedHash` + +- `status`: `enum` - `"VALID" | "INVALID" | "SYNCING" | "ACCEPTED"` +- `latestValidHash`: `DATA|null`, 32 Bytes - the hash of the most recent *valid* block in the branch defined by payload and its ancestors +- `validationError`: `String|null` - a message providing additional details on the validation error if the payload is classified as `INVALID`. +- `latestInclusionListSatisfiedHash`: `DATA|null`, 32 Bytes - the hash of the most recent block that *satisfied the inclusion list constraints* in the branch defined by payload and its ancestors + +*Note:* `latestInclusionListSatisfiedHash` does not imply that all its ancestors have satisfied the inclusion list constraints. + ## Routines ### Payload building diff --git a/src/engine/openrpc/methods/forkchoice.yaml b/src/engine/openrpc/methods/forkchoice.yaml index 30e6c8e70..badee9ff3 100644 --- a/src/engine/openrpc/methods/forkchoice.yaml +++ b/src/engine/openrpc/methods/forkchoice.yaml @@ -219,7 +219,7 @@ result: name: Response object schema: - $ref: '#/components/schemas/ForkchoiceUpdatedResponseV1' + $ref: '#/components/schemas/ForkchoiceUpdatedResponseV2' errors: - code: -38002 message: Invalid forkchoice state diff --git a/src/engine/openrpc/methods/payload.yaml b/src/engine/openrpc/methods/payload.yaml index 757ffe68a..52363740e 100644 --- a/src/engine/openrpc/methods/payload.yaml +++ b/src/engine/openrpc/methods/payload.yaml @@ -1105,7 +1105,7 @@ result: name: Payload status schema: - $ref: '#/components/schemas/PayloadStatusInclusionListUnsatisfied' + $ref: '#/components/schemas/PayloadStatusV2' errors: - code: -32602 message: Invalid params diff --git a/src/engine/openrpc/schemas/forkchoice.yaml b/src/engine/openrpc/schemas/forkchoice.yaml index b893deb93..542d44954 100644 --- a/src/engine/openrpc/schemas/forkchoice.yaml +++ b/src/engine/openrpc/schemas/forkchoice.yaml @@ -16,7 +16,7 @@ ForkchoiceStateV1: title: Finalized block hash $ref: '#/components/schemas/hash32' ForkchoiceUpdatedResponseV1: - title: Forkchoice updated response + title: Forkchoice updated response object V1 type: object required: - payloadStatus @@ -27,6 +27,18 @@ ForkchoiceUpdatedResponseV1: payloadId: title: Payload id $ref: '#/components/schemas/bytes8' +ForkchoiceUpdatedResponseV2: + title: Forkchoice updated response object V2 + type: object + required: + - payloadStatus + properties: + payloadStatus: + title: Payload status + $ref: '#/components/schemas/PayloadStatusV2' + payloadId: + title: Payload id + $ref: '#/components/schemas/bytes8' PayloadAttributesV1: title: Payload attributes object V1 type: object diff --git a/src/engine/openrpc/schemas/payload.yaml b/src/engine/openrpc/schemas/payload.yaml index eb80f4215..6840ccbd2 100644 --- a/src/engine/openrpc/schemas/payload.yaml +++ b/src/engine/openrpc/schemas/payload.yaml @@ -48,22 +48,19 @@ PayloadStatusNoInvalidBlockHash: $ref: '#/components/schemas/PayloadStatusV1/properties/latestValidHash' validationError: $ref: '#/components/schemas/PayloadStatusV1/properties/validationError' -PayloadStatusInclusionListUnsatisfied: +PayloadStatusV2: $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash' - title: Payload status object appending INCLUSION_LIST_UNSATISFIED status + title: Payload status object V2 properties: status: $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/status' - enum: - - VALID - - INVALID - - SYNCING - - ACCEPTED - - INCLUSION_LIST_UNSATISFIED latestValidHash: $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/latestValidHash' validationError: $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/validationError' + latestInclusionListSatisfiedHash: + title: The hash of the most recent inclusion list satisfied block + $ref: '#/components/schemas/hash32' ExecutionPayloadV1: title: Execution payload object V1 type: object From e38c9562613be40e0c36e550d0b33e86165a18c9 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 27 Jun 2026 12:34:58 +0900 Subject: [PATCH 19/22] Use PayloadStatusV2 in Bogota --- src/engine/bogota.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index c3b0c56b3..31e3d7aa0 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -91,8 +91,7 @@ Method parameter list is extended with `inclusionListTransactions`. #### Response -* result: [`PayloadStatusV1`](./paris.md#payloadstatusv1), values of the `status` field are modified in the following way: - - `INCLUSION_LIST_UNSATISFIED` status value is appended. +* result: [`PayloadStatusV2`](#payloadstatusv2) * error: code and message set in case an exception happens while processing the payload. #### Specification @@ -141,7 +140,10 @@ This method follows the same specification as [`engine_newPayloadV5`](./amsterda #### Response -Refer to the response for [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4). +* result: `object` + - `payloadStatus`: [`PayloadStatusV2`](#payloadstatusv2), with the same `status` value restrictions as [`engine_forkchoiceUpdatedV4`](./amsterdam.md#engine_forkchoiceupdatedv4). + - `payloadId`: `DATA|null`, 8 Bytes - identifier of the payload build process or `null` +* error: code and message set in case an exception happens while the validating payload, updating the forkchoice or initiating the payload build process. #### Specification From ca05274c1e18f70fc92dd794a6025e513ee64f90 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 27 Jun 2026 12:37:11 +0900 Subject: [PATCH 20/22] Specify IL enforcement during the payload validation process --- src/engine/bogota.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index 31e3d7aa0..60b9e0fd1 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -67,6 +67,21 @@ This structure has the syntax of `PayloadStatusV1` and appends a single field: ` ## Routines +### Payload validation + +This routine follows the same specification as [Payload validation](./paris.md#payload-validation) with the following changes to the processing flow: + +1. Extend point (3) of the [Payload validation](./paris.md#payload-validation) by defining the additional response field that **MUST** be returned by the validation process: + + 1. The response **MUST** contain `{latestInclusionListSatisfiedHash: satisfiedHash}` where `satisfiedHash` **MUST** be: + - The block hash of the most recent valid block in the branch defined by the payload and its ancestors for which payload validation satisfied the inclusion list constraints with respect to the corresponding `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). + + 2. Inclusion list satisfaction **MUST** be determined only for payloads deemed `VALID`. + +2. Extend point (4) of the [Payload validation](./paris.md#payload-validation) by defining the idempotency of inclusion list satisfaction: + + 1. Whether a payload satisfies the inclusion list constraints **MAY** change between validations when different `inclusionListTransactions` are provided. The value of `latestInclusionListSatisfiedHash` **MAY** change accordingly. + ### Payload building This routine follows the same specification as [Payload building](./paris.md#payload-building) with the following changes to the processing flow: From 65191fcc4e5ebb5f769f86c76efe443f043fa485 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Sat, 27 Jun 2026 12:37:34 +0900 Subject: [PATCH 21/22] Specify IL enforcement for different branches --- src/engine/bogota.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index 60b9e0fd1..02dc83add 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -14,6 +14,7 @@ This specification is based on and extends [Engine API - Amsterdam](./amsterdam. - [PayloadAttributesV5](#payloadattributesv5) - [PayloadStatusV2](#payloadstatusv2) - [Routines](#routines) + - [Payload validation](#payload-validation) - [Payload building](#payload-building) - [Methods](#methods) - [engine_newPayloadV6](#engine_newpayloadv6) @@ -115,7 +116,9 @@ This method follows the same specification as [`engine_newPayloadV5`](./amsterda 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Bogota fork. -2. Client software **MUST** return `{status: INCLUSION_LIST_UNSATISFIED, latestValidHash: null, validationError: null}` if `executionPayload` passed [payload validation](./paris.md#payload-validation) process and deemed `VALID` but fails to satisfy the inclusion list constraints with respect to `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). +2. Client software **MUST** store `inclusionListTransactions` for a payload with `ACCEPTED` status. Client software **MUST** use the stored `inclusionListTransactions` when the payload is later validated. + +3. Client software **MUST** set `latestInclusionListSatisfiedHash` to `null` when returning a payload status not obtained from the [Payload validation](#payload-validation) process. ### engine_getInclusionListV1 @@ -170,9 +173,11 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV4`](./a 2. `payloadAttributes.timestamp` does not fall within the time frame of the Bogota fork, return `-38005: Unsupported fork` on failure. - 3. `payloadAttributes.timestamp` is greater than `timestamp` of a block referenced by `forkchoiceState.headBlockHash`, return `-38003: Invalid payload attributes` on failure. +2. Extend point (9) of the `engine_forkchoiceUpdatedV1` [specification](./paris.md#specification-1) by defining `payloadStatus.latestInclusionListSatisfiedHash`: + + 1. If `payloadStatus.latestValidHash` is the hash of a valid payload, `payloadStatus.latestInclusionListSatisfiedHash` **MUST** be the block hash of the most recent valid block in the branch defined by `payloadStatus.latestValidHash` and its ancestors for which payload validation satisfied the inclusion list constraints with respect to the corresponding `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). - 4. If any of the above checks fails, the `forkchoiceState` update **MUST NOT** be rolled back. + 2. Otherwise, `payloadStatus.latestInclusionListSatisfiedHash` **MUST** be `null`. ### Update the methods of previous forks From a56ea08b51a7664b886305c03408081ecabdc1b1 Mon Sep 17 00:00:00 2001 From: Jihoon Song Date: Tue, 30 Jun 2026 18:05:44 +0900 Subject: [PATCH 22/22] Replace `latestInclusionListSatisfiedHash` with `inclusionListSatisfied` --- src/engine/bogota.md | 36 ++++++++----------------- src/engine/openrpc/schemas/payload.yaml | 8 +++--- 2 files changed, 16 insertions(+), 28 deletions(-) diff --git a/src/engine/bogota.md b/src/engine/bogota.md index 02dc83add..816894f18 100644 --- a/src/engine/bogota.md +++ b/src/engine/bogota.md @@ -14,7 +14,6 @@ This specification is based on and extends [Engine API - Amsterdam](./amsterdam. - [PayloadAttributesV5](#payloadattributesv5) - [PayloadStatusV2](#payloadstatusv2) - [Routines](#routines) - - [Payload validation](#payload-validation) - [Payload building](#payload-building) - [Methods](#methods) - [engine_newPayloadV6](#engine_newpayloadv6) @@ -57,32 +56,15 @@ This structure has the syntax of [`PayloadAttributesV4`](./amsterdam.md#payloada ### PayloadStatusV2 -This structure has the syntax of `PayloadStatusV1` and appends a single field: `latestInclusionListSatisfiedHash` +This structure has the syntax of `PayloadStatusV1` and appends a single field: `inclusionListSatisfied` - `status`: `enum` - `"VALID" | "INVALID" | "SYNCING" | "ACCEPTED"` - `latestValidHash`: `DATA|null`, 32 Bytes - the hash of the most recent *valid* block in the branch defined by payload and its ancestors - `validationError`: `String|null` - a message providing additional details on the validation error if the payload is classified as `INVALID`. -- `latestInclusionListSatisfiedHash`: `DATA|null`, 32 Bytes - the hash of the most recent block that *satisfied the inclusion list constraints* in the branch defined by payload and its ancestors - -*Note:* `latestInclusionListSatisfiedHash` does not imply that all its ancestors have satisfied the inclusion list constraints. +- `inclusionListSatisfied`: `BOOLEAN|null` - whether the payload satisfied the inclusion list constraints if it is deemed `VALID`; `null` otherwise. ## Routines -### Payload validation - -This routine follows the same specification as [Payload validation](./paris.md#payload-validation) with the following changes to the processing flow: - -1. Extend point (3) of the [Payload validation](./paris.md#payload-validation) by defining the additional response field that **MUST** be returned by the validation process: - - 1. The response **MUST** contain `{latestInclusionListSatisfiedHash: satisfiedHash}` where `satisfiedHash` **MUST** be: - - The block hash of the most recent valid block in the branch defined by the payload and its ancestors for which payload validation satisfied the inclusion list constraints with respect to the corresponding `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). - - 2. Inclusion list satisfaction **MUST** be determined only for payloads deemed `VALID`. - -2. Extend point (4) of the [Payload validation](./paris.md#payload-validation) by defining the idempotency of inclusion list satisfaction: - - 1. Whether a payload satisfies the inclusion list constraints **MAY** change between validations when different `inclusionListTransactions` are provided. The value of `latestInclusionListSatisfiedHash` **MAY** change accordingly. - ### Payload building This routine follows the same specification as [Payload building](./paris.md#payload-building) with the following changes to the processing flow: @@ -116,9 +98,13 @@ This method follows the same specification as [`engine_newPayloadV5`](./amsterda 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Bogota fork. -2. Client software **MUST** store `inclusionListTransactions` for a payload with `ACCEPTED` status. Client software **MUST** use the stored `inclusionListTransactions` when the payload is later validated. +2. Client software **MUST** set `inclusionListSatisfied` in the following way: + + 1. If the payload is deemed `VALID`, `inclusionListSatisfied` **MUST** be set to whether the payload satisfied the inclusion list constraints. + + 2. Otherwise, `inclusionListSatisfied` **MUST** be `null`. -3. Client software **MUST** set `latestInclusionListSatisfiedHash` to `null` when returning a payload status not obtained from the [Payload validation](#payload-validation) process. +3. Client software **MUST** retain `inclusionListTransactions` for a payload with `ACCEPTED` status. Client software **MAY** discard them once the payload is no longer the tip of a branch. Client software **MUST** use the retained `inclusionListTransactions` if it later checks whether the payload satisfies the inclusion list constraints. ### engine_getInclusionListV1 @@ -173,11 +159,11 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV4`](./a 2. `payloadAttributes.timestamp` does not fall within the time frame of the Bogota fork, return `-38005: Unsupported fork` on failure. -2. Extend point (9) of the `engine_forkchoiceUpdatedV1` [specification](./paris.md#specification-1) by defining `payloadStatus.latestInclusionListSatisfiedHash`: +2. Extend point (9) of the `engine_forkchoiceUpdatedV1` [specification](./paris.md#specification-1) by defining `payloadStatus.inclusionListSatisfied`: - 1. If `payloadStatus.latestValidHash` is the hash of a valid payload, `payloadStatus.latestInclusionListSatisfiedHash` **MUST** be the block hash of the most recent valid block in the branch defined by `payloadStatus.latestValidHash` and its ancestors for which payload validation satisfied the inclusion list constraints with respect to the corresponding `inclusionListTransactions` as defined in [EIP-7805](https://eips.ethereum.org/EIPS/eip-7805). + 1. If the payload referenced by `forkchoiceState.headBlockHash` is deemed `VALID`, `payloadStatus.inclusionListSatisfied` **MUST** be set to whether the payload satisfied the inclusion list constraints. - 2. Otherwise, `payloadStatus.latestInclusionListSatisfiedHash` **MUST** be `null`. + 2. Otherwise, `payloadStatus.inclusionListSatisfied` **MUST** be `null`. ### Update the methods of previous forks diff --git a/src/engine/openrpc/schemas/payload.yaml b/src/engine/openrpc/schemas/payload.yaml index 6840ccbd2..66b900ffd 100644 --- a/src/engine/openrpc/schemas/payload.yaml +++ b/src/engine/openrpc/schemas/payload.yaml @@ -58,9 +58,11 @@ PayloadStatusV2: $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/latestValidHash' validationError: $ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash/properties/validationError' - latestInclusionListSatisfiedHash: - title: The hash of the most recent inclusion list satisfied block - $ref: '#/components/schemas/hash32' + inclusionListSatisfied: + title: Whether the payload satisfied the inclusion list constraints + oneOf: + - type: boolean + - type: 'null' ExecutionPayloadV1: title: Execution payload object V1 type: object