Skip to content

Add support for engine_forkchoiceUpdatedV5 - #9935

Merged
mergify[bot] merged 23 commits into
sigp:unstablefrom
conache:focil-add-forkchoiceupdated-v5
Sep 16, 2026
Merged

mergify[bot] merged 23 commits into
sigp:unstablefrom
conache:focil-add-forkchoiceupdated-v5

Conversation

@conache

@conache conache commented Aug 29, 2026

Copy link
Copy Markdown

Issue Addressed

Part of the FOCIL implementation. This PR adds the engine_forkchoiceUpdatedV5 (execution api spec) engine API integration, which enables specifying an inclusion list to the execution client when requesting a payload to be built.

Proposed Changes

  • Add PayloadAttributesV5, which extends V4 with inclusion_list_transactions (spec)
  • Add engine_forkchoiceUpdatedV5 support to the engine API module and expose the capability through exchange_capabilities
  • Handle the response's PayloadStatusV2, which appends the inclusionListSatisfied field (per spec)
  • Send V5 attributes for Heze slots. Note that custody_columns is sent as null, matching the consensus specs
  • Add mock execution engine support, rejecting V4 attributes from Heze onwards
  • Add Heze boundary tests for preparing a payload, checking if the fcU request that the mock receives is the expected one

Additional Info

  • inclusion_list_transactions is sent empty for now; populating it from the inclusion list store will be added in a follow-up PR

@conache
conache marked this pull request as ready for review August 29, 2026 14:31
@conache
conache force-pushed the focil-add-forkchoiceupdated-v5 branch from dca5c6a to 73bfb17 Compare September 2, 2026 17:08
Comment on lines 117 to 124
#[derive(Clone, Debug, PartialEq)]
pub struct PayloadStatusV1 {
pub status: PayloadStatusV1Status,
pub latest_valid_hash: Option<ExecutionBlockHash>,
pub validation_error: Option<String>,
/// [New in Heze:EIP-7805] Only populated from `engine_forkchoiceUpdatedV5` onwards.
pub inclusion_list_satisfied: Option<bool>,
}

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This struct is now compliant with PayloadStatusV2 (per spec), however, I still kept its initial V1 naming because V2 only appends a nullable field, so this type can represent both versions. Though, I'm a bit concerned that using the initial naming could be confusing.

Not sure what is the best/clearer option here:

  • keeping it as is
  • renaming it to PayloadStatusV2
  • having a versioned PayloadStatus superstruct

Open to suggestions here

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since its a optional field im not sure we need the superstruct.

maybe just to be a bit more explicit we can add a type alias type PayloadStatusV2 = PayloadStatusV1

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added PayloadStatusV2 as a type alias in 3bb6508

@eserilev eserilev added heze ready-for-review The code is ready for review labels Sep 2, 2026
@mergify

mergify Bot commented Sep 3, 2026

Copy link
Copy Markdown

This pull request has merge conflicts. Could you please resolve them @conache? 🙏

@mergify mergify Bot added waiting-on-author The reviewer has suggested changes and awaits thier implementation. and removed ready-for-review The code is ready for review labels Sep 3, 2026
@conache
conache force-pushed the focil-add-forkchoiceupdated-v5 branch from 487c39b to 314ef99 Compare September 4, 2026 08:08
conache added a commit to conache/lighthouse that referenced this pull request Sep 5, 2026

@rahulbarmann rahulbarmann left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

the only overlap with #10017 is PayloadStatusV1, I've already switched mine onto JsonPayloadStatusV2 so it should be a trivial conflict for whoever merges second

Comment on lines +937 to +945
@@ -940,6 +942,7 @@ impl<E: EthSpec> MockBuilder<E> {
Some(head_block_root),
Some(slot.as_u64()),
None, // TODO(gloas): pass target_gas_limit
None,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we are still using PayloadAttributes V4 in the heze case here, since we are passing None for IL. we should add a TODO here at least

Or just pass in Some(ProgressiveTransactions::empty()) for the heze variant

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh, right! I added a dedicated Heze arm passing Some(ProgressiveTransactions::empty()) (in aa26e96), but we still need to provide a value for target_gas_limit to use PayloadAttributes V5. I'm not sure what the best value to use here is, so I left a todo comment for it, as we do for the Gloas variant for now

Comment on lines 117 to 124
#[derive(Clone, Debug, PartialEq)]
pub struct PayloadStatusV1 {
pub status: PayloadStatusV1Status,
pub latest_valid_hash: Option<ExecutionBlockHash>,
pub validation_error: Option<String>,
/// [New in Heze:EIP-7805] Only populated from `engine_forkchoiceUpdatedV5` onwards.
pub inclusion_list_satisfied: Option<bool>,
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since its a optional field im not sure we need the superstruct.

maybe just to be a bit more explicit we can add a type alias type PayloadStatusV2 = PayloadStatusV1

@conache
conache requested a review from eserilev September 16, 2026 12:49
@eserilev eserilev added ready-for-merge This PR is ready to merge. and removed waiting-on-author The reviewer has suggested changes and awaits thier implementation. labels Sep 16, 2026

@eserilev eserilev left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@mergify mergify Bot added the queued label Sep 16, 2026
@mergify

mergify Bot commented Sep 16, 2026

Copy link
Copy Markdown

Merge Queue Status

  • Entered queue2026-09-16 17:22 UTC · Rule: default · triggered by rule Add ready-to-merge labeled PRs to merge queue
  • Checks passed · on draft merge queue: checking #9935 on unstable (0dfcd45) #10064
  • Merged2026-09-16 17:55 UTC · at 000c8a227c5a85dc7698c4035c1cc810a0f0bf70 · squash

This pull request spent 33 minutes 28 seconds in the queue, including 28 minutes 59 seconds running CI.

Required conditions to merge

@mergify
mergify Bot merged commit 000c8a2 into sigp:unstable Sep 16, 2026
39 checks passed
@mergify mergify Bot removed the queued label Sep 16, 2026
@conache
conache deleted the focil-add-forkchoiceupdated-v5 branch September 16, 2026 19:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

heze ready-for-merge This PR is ready to merge.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants