feat(forkchoice): implement the forkchoice module

[GrapeBaBa]

Motivation

Lodestar-z currently lacks a fork-choice implementation. This implementation targets Lodestar's unstable branch, which includes the upcoming Gloas/ePBS fork with payload-timeliness and builder-boost mechanics.

Description

• proto_array.zig — ProtoArray implementing LMD-GHOST: findHead, applyScoreChanges, onBlock, onAttestation, node viability/best-child comparison, maybePrune, isDescendant, and ePBS payload status tracking
• fork_choice.zig — ForkChoice orchestrator: checkpoint management, onBlock/onAttestation with full validation, proposer boost/reorg logic, getHead, updateTime, ancestor queries, and debug/export methods
• compute_deltas.zig — Vote-weight delta computation from attestation changes
• vote_tracker.zig — Per-validator vote tracking (current/next root + epoch)
• store.zig — ForkChoiceStore holding justified/finalized checkpoints, equivocation tracking, proposer boost state

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request lays the groundwork for the forkchoice module, a critical component for determining the canonical chain in a blockchain network. It introduces the necessary data structures and initial logic required to manage the block tree, track validator votes, and compute block weights, which are fundamental for implementing the LMD-GHOST consensus algorithm.

Highlights

• New Module Introduction: Introduced the foundational forkchoice module, including core data structures and logic for block processing and validator vote tracking.
• Build System Integration: Integrated the new forkchoice module into the build system (build.zig and zbuild.zon), enabling its compilation and testing.
• Core Data Structures and Logic: Defined key constants and types within the forkchoice module, such as ProtoBlock, ProtoNode, ExecutionStatus, and VoteTracker, which are essential for the LMD-GHOST consensus algorithm.
• Configuration Update: Added PTC_SIZE constant to src/preset/preset.zig for both Mainnet and Minimal configurations.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• build.zig
  • Added the fork_choice module to the build system.
  • Configured test targets for the fork_choice module.
  • Added imports for the fork_choice module.
• src/fork_choice/compute_deltas.zig
  • Added a new file implementing the computeDeltas function, which calculates per-node weight deltas based on vote changes and balance updates, handling equivocating validators.
• src/fork_choice/proto_node.zig
  • Added a new file defining ProtoBlock and ProtoNode structures, along with ExecutionStatus, DataAvailabilityStatus, PayloadStatus, and error types relevant to fork choice.
• src/fork_choice/root.zig
  • Added a new root file for the fork_choice module, exporting its public components.
• src/fork_choice/vote_tracker.zig
  • Added a new file defining VoteTracker and Votes structures for efficient storage and management of validator votes.
• src/preset/preset.zig
  • Added PTC_SIZE constant to PresetMainnet and PresetMinimal structs.
• zbuild.zon
  • Added the fork_choice module definition and its imports.

Activity

• No activity has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new forkchoice module, which is a substantial and well-implemented feature. The code quality is high, with good use of data structures for performance (like SoA in vote_tracker.zig) and comprehensive tests. My review focuses on the compute_deltas.zig file, where I've identified a critical correctness issue regarding a type mismatch, a violation of the function length limit as per the style guide, and some opportunities to improve clarity by splitting compound conditions. I also noted a minor memory leak in the test setup. The rest of the new modules are well-structured and adhere to the repository's style guide.

[lodekeeper-z]

Hey @GrapeBaBa — CI is failing with unable to load 'src/fork_choice/proto_node.zig': FileNotFound. Looks like the latest commit removed/renamed proto_node.zig but root.zig still imports it. Quick fix should unblock CI 👍

[lodekeeper-z]

Thorough review of the forkchoice module. Impressive scope — 6.3k lines covering the core DAG (ProtoArray), LMD-GHOST weight computation, Gloas ePBS multi-node model, PTC voting, and optimistic sync. The test suite is comprehensive with good coverage of Gloas variant linking and weight propagation.

Main blockers are the CI-breaking import and a couple of type mismatches that will prevent compilation. Architecture concerns are lower priority but worth discussing before this moves out of draft.

See inline comments for details.

[lodekeeper-z]

🟡 ForkChoiceStore overlaps significantly with ForkChoice

Both structs track:

• justified/finalized checkpoints
• equivocating indices
• current slot
• justified balances

ForkChoice has its own checkpoint management (updateJustifiedCheckpoint, updateFinalizedCheckpoint, updateUnrealizedCheckpoints) and ForkChoiceStore has setJustified, setFinalizedCheckpoint.

Is the intent that ForkChoiceStore replaces the checkpoint management in ForkChoice, or do they serve different layers? If ForkChoiceStore is the high-level store (matching the spec's Store) and ForkChoice is the lower-level ProtoArray wrapper, the boundary should be clearer — currently both could manage the same state independently.

[GrapeBaBa]

this is intentional

[lodekeeper-z]

Got it — makes sense as a deliberate two-layer design. ForkChoiceStore = spec Store (high-level checkpoint management), ForkChoice = ProtoArray wrapper (weight/head computation). The overlap is intentional separation of concerns. 👍

[lodekeeper-z]

🟡 onBlockPreGloas allows orphan blocks (unknown parent)

node.parent = self.getNodeIndexByRootAndStatus(block.parent_root, .full);

If the parent root is not in the DAG, node.parent is null and the block is silently inserted as an orphan. This is fine for genesis, but for non-genesis blocks it means:

1. The block won't participate in weight propagation (no parent to propagate to)
2. It won't be prunable via finalization ancestry

The Lodestar TS implementation rejects blocks with unknown parents in onBlock. The ForkChoice.onBlock wrapper does validate this, but ProtoArray.onBlock doesn't — so direct callers of ProtoArray could insert orphans.

Consider: should ProtoArray enforce this invariant, or is it intentionally delegated to the ForkChoice layer?

[GrapeBaBa]

This is same with TS implementation, @lodekeeper-z can you recheck?

[lodekeeper-z]

You're right — I rechecked. TS ProtoArray.onBlock does allow orphan insertion (line 455: // else: parent doesn't exist, parentIndex remains undefined). The parent validation happens at the ForkChoice layer, not ProtoArray. Same pattern here. Thanks for the correction.

[lodekeeper-z]

You're right — I rechecked. TS ProtoArray.onBlock does allow orphan insertion (line 455: // else: parent doesn't exist, parentIndex remains undefined). The parent validation happens at the ForkChoice layer, not ProtoArray. Same pattern here. Thanks for the correction.

[Copilot]

Pull request overview

This PR introduces a new fork_choice Zig module (plus benches + CI coverage) and extends the codebase to recognize the new gloas fork (ePBS) across config, types, and state-transition helpers.

Changes:

• Add a full src/fork_choice implementation (store/votes/proto-array integration, attestation + block handling) plus benchmarks and CI test target.
• Add gloas fork support across consensus_types, fork_types, spec test runner utilities, and config/fork sequencing.
• Update state transition utilities and block processing to account for ePBS behavior (no blinded blocks, payload decoupling, execution request relocation).

Reviewed changes

Copilot reviewed 44 out of 46 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
zbuild.zon	Register fork_choice module + benches
test/spec/test_case.zig	Add gloas SSZ test-case loading/deinit
test/spec/runner/sanity.zig	Support gloas blocks in runner
src/state_transition/utils/execution.zig	ePBS execution-enabled semantics for gloas+
src/state_transition/utils/epoch.zig	Add computeSlotsSinceEpochStart helper
src/state_transition/test_utils/generate_state.zig	Add config generation for gloas
src/state_transition/state_transition.zig	Disallow blinded blocks for gloas+
src/state_transition/root.zig	Export new epoch/balance Rc helpers
src/state_transition/block/slash_validator.zig	Extend Electra slashing constants to gloas
src/state_transition/block/process_operations.zig	Skip execution_requests for gloas+
src/state_transition/block/process_block.zig	Skip exec payload processing for gloas+
src/preset/preset.zig	Add ePBS-related preset constants
src/fork_types/root.zig	Export new Any* wrapper types
src/fork_types/fork_types.zig	Map ForkSeq.gloas to consensus types
src/fork_types/beacon_state.zig	Enable fulu -> gloas state upgrade
src/fork_types/beacon_block.zig	Enforce no blinded / no payload fields in gloas+
src/fork_types/any_indexed_attestation.zig	New AnyIndexedAttestation wrapper
src/fork_types/any_execution_payload.zig	Treat gloas like deneb-header variant
src/fork_types/any_beacon_state.zig	Add gloas state + payload availability accessor
src/fork_types/any_beacon_block.zig	Add gloas full block variants
src/fork_types/any_attester_slashing.zig	Add AnyAttesterSlashing wrapper helpers
src/fork_choice/vote_tracker.zig	New SoA votes storage + tests
src/fork_choice/store.zig	New fork-choice store + Rc balance handling
src/fork_choice/root.zig	Export fork-choice public API surface
src/fork_choice/fork_choice.zig	Core fork-choice implementation + tests
src/fork_choice/compute_deltas.zig	New delta computation + tests
src/consensus_types/root.zig	Export gloas consensus types
src/consensus_types/gloas.zig	New gloas SSZ types (ePBS)
src/config/networks/sepolia.zig	Add gloas fork fields (disabled epoch)
src/config/networks/minimal.zig	Add gloas fork fields + timing params
src/config/networks/mainnet.zig	Add gloas fork fields + timing params
src/config/networks/hoodi.zig	Add gloas fork fields (disabled epoch)
src/config/networks/gnosis.zig	Add gloas fork fields + timing params
src/config/networks/chiado.zig	Add gloas fork fields (disabled epoch)
src/config/fork_seq.zig	Add ForkSeq.gloas
src/config/ChainConfig.zig	Add Gloas + slot timing config fields
src/config/BeaconConfig.zig	Add Gloas fork info + timing helpers
build.zig	Add fork_choice module, tests, and benches
bindings/napi/BeaconStateView.zig	Disallow blinded blocks for gloas+
bench/state_transition/process_block.zig	Skip exec/withdrawals benches for gloas+
bench/fork_choice/util.zig	Shared fork-choice bench initialization
bench/fork_choice/update_head.zig	New fork-choice update-head benchmark
bench/fork_choice/on_attestation.zig	New fork-choice onAttestation benchmark
bench/fork_choice/compute_deltas.zig	New computeDeltas benchmark harness
.github/workflows/CI.yml	Run fork-choice tests in CI

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

addLatestMessage rejects/accepts votes based on computeEpochAtSlot(next_slot), but this function now stores next_slot (Gloas LatestMessage {slot, root}). Comparing epochs will incorrectly reject newer votes within the same epoch (common case), preventing votes from updating until the epoch boundary. Use a slot comparison (e.g. accept when next_slot > existing_next_slot, plus INIT_VOTE_SLOT special-case) to properly filter stale votes.

Suggested change

	// Accept vote if it's the first vote (INIT_VOTE_SLOT) or epoch advances.
	if (existing_next_slot == INIT_VOTE_SLOT or computeEpochAtSlot(next_slot) > computeEpochAtSlot(existing_next_slot)) {
	fields.next_indices[validator_index] = @intCast(next_index);
	fields.next_slots[validator_index] = next_slot;
	}
	// else it's an old vote, don't count it.
	// Accept vote if it's the first vote (INIT_VOTE_SLOT) or the new vote has a higher slot.
	if (existing_next_slot == INIT_VOTE_SLOT or next_slot > existing_next_slot) {
	fields.next_indices[validator_index] = @intCast(next_index);
	fields.next_slots[validator_index] = next_slot;
	}
	// else it's an old or equal-slot vote, don't count it.

[Copilot]

processAttestationQueue assumes queued_attestations.iterator() yields entries in increasing att_slot order (it breaks on the first att_slot >= current_slot and then removes remove_count entries from the front). std.AutoArrayHashMapUnmanaged iteration order is insertion order, not key-sorted, so out-of-order slot insertions can cause eligible past-slot attestations to be skipped and/or the wrong slots to be removed. Iterate all entries and remove by key (or maintain a separate sorted structure / ensure sorted insertion explicitly) instead of relying on front-ordered removal + early break.

[Copilot]

Type mismatch: executionPayloadAvailability expects index: usize (see AnyBeaconState.executionPayloadAvailability), but checkpoint_slot % preset.SLOTS_PER_HISTORICAL_ROOT is a Slot/u64. Zig requires an explicit cast here; as written this should not compile. Cast the modulo result to usize (with a safety assertion if desired) before calling executionPayloadAvailability.

Suggested change

	const payload_available = state.state.executionPayloadAvailability(
	checkpoint_slot % preset.SLOTS_PER_HISTORICAL_ROOT,
	const payload_index = @intCast(usize, checkpoint_slot % preset.SLOTS_PER_HISTORICAL_ROOT);
	const payload_available = state.state.executionPayloadAvailability(
	payload_index,

[wemeetagain]

Looks really good. Tracks closely with the typescript version.

[nflaig]

@GrapeBaBa I see this references my lodestar PR, can you please explain what this regression test covers, maybe we should add it to lodestar-ts side too? if we wanna add a more high level test can you explain in which scenario this was relevant seems like without this hasPayload check we'd pick a different head?

[GrapeBaBa]

same, this kind of comment should not exist, and lodekeep-z explain it, this looks like a X do Y test you mentioned, need changed later

[nflaig]

@GrapeBaBa so FULL is a child of EMPTY?

[GrapeBaBa]

this ascii is wrong, and I should already cleaned up comments like Upstream: lodestar #9209, these were left out