chore: fork choice stores checkpoints with payload status - #8845
Merged
Conversation
Contributor
Summary of ChangesHello @ensi321, I'm Gemini Code Assist1! 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 refines the fork choice mechanism by integrating payload status directly into checkpoint management. By storing and utilizing the payload status (EMPTY or FULL) for justified and finalized checkpoints, the system can accurately determine the correct block variant, especially critical for the Gloas fork. This ensures consistency and correctness in block retrieval methods. Highlights
🧠 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
Using Gemini Code AssistThe 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
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 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
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request successfully updates the fork choice mechanism to store and use payload status for checkpoints, which is a crucial improvement for correctness, particularly with the Gloas fork. The introduction of CheckpointWithPayload and the getCheckpointPayloadStatus helper function are well-implemented, and the changes are consistently applied throughout the codebase, including the test files. I have one suggestion to refactor a section of the code to enhance maintainability by reducing duplication. Overall, this is a solid and well-executed change.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## nc/epbs-fc #8845 +/- ##
==============================================
+ Coverage 52.39% 52.40% +0.01%
==============================================
Files 848 848
Lines 63489 63464 -25
Branches 4689 4689
==============================================
- Hits 33263 33259 -4
+ Misses 30158 30137 -21
Partials 68 68 🚀 New features to boost your workflow:
|
twoeths
added a commit
that referenced
this pull request
Mar 19, 2026
## Summary This PR extends the **Gloas ePBS state cache architecture** to support dual state variants (block state and payload state) by threading the `payloadPresent` flag through the state cache layer, regeneration system, and archive store. ## Context Building on the fork choice changes in `nc/epbs-fc` (which stores checkpoints with payload status), this PR completes the state cache implementation for Gloas ePBS by: 1. Extending all checkpoint cache operations to track `payloadPresent` 2. Updating the regeneration layer to explicitly handle both state variants 3. Propagating payload status from block import through to checkpoint caching ## Key Changes ### 1. State Cache Type System Updates **`packages/beacon-node/src/chain/stateCache/types.ts`** (+208/-111 lines total across files): - Renamed `CheckpointHex` → `CheckpointHexPayload` with required `payloadPresent: boolean` field - Updated `CheckpointStateCache` interface methods to accept `payloadPresent` parameter: - `add(cp, state, payloadPresent)` - explicitly marks state variant when adding to cache - `getLatest(rootHex, maxEpoch, payloadPresent)` - retrieves specific state variant - `getOrReloadLatest(rootHex, maxEpoch, payloadPresent)` - reloads specific state variant from disk - `updatePreComputedCheckpoint(rootHex, epoch, payloadPresent)` - tracks payload status for pre-computed states - Kept `processState()` method signature unchanged (manages both variants internally) ### 2. PersistentCheckpointStateCache Implementation **`packages/beacon-node/src/chain/stateCache/persistentCheckpointsCache.ts`** (~289 lines modified): - Extended cache key format from `"epoch-rootHex"` to `"epoch-rootHex-payloadPresent"` - Updated `toCheckpointHexPayload()` helper to include payload status in keys - Modified all cache operations (add, get, getLatest, etc.) to handle dual state variants - Implemented logic to iterate both `payloadPresent` variants in `processPastEpoch()` for memory management - Updated cache metrics and debugging utilities to reflect dual state architecture ### 3. Regeneration Layer - Dual State Support **`packages/beacon-node/src/chain/regen/interface.ts`** & **`queued.ts`** & **`regen.ts`**: - Added `processPayloadState(payloadState)` method for explicit payload state caching (Gloas-only) - Called after `processExecutionPayloadEnvelope()` when payload is revealed - Complements `processState()` which handles block state caching - Updated `addCheckpointState(cp, state, payloadPresent)` to accept payload flag - Extended `updatePreComputedCheckpoint()` with `payloadPresent` parameter - Modified `getCheckpointState()` and related methods to pass `payloadPresent` through cache lookups ### 4. Block Import - Payload Status Propagation **`packages/beacon-node/src/chain/blocks/importBlock.ts`**: - Derive `payloadPresent` from block type: - **Pre-Gloas**: `payloadPresent = true` (execution payload embedded in block, always FULL variant) - **Post-Gloas**: `payloadPresent = false` (block state only, PENDING/EMPTY variant, payload not yet revealed) - Thread `payloadPresent` through checkpoint caching operations: - `regen.addCheckpointState(cp, checkpointState, payloadPresent)` ### 5. Archive Store - Historical State Management **`packages/beacon-node/src/chain/archiveStore/`**: - Updated `archiveStore.archiveState()` to accept `payloadPresent` parameter - Modified archival strategies (`frequencyStateArchiveStrategy`) to propagate payload status - Ensured historical states maintain proper metadata for state variant tracking ### 6. API & Validation Layer Updates **`packages/beacon-node/src/api/impl/`**: - Updated validator API to retrieve correct state variant with `payloadPresent` flag - Modified beacon state utilities to handle payload-aware checkpoint lookups - Ensured API endpoints return appropriate state variant based on block type ## Technical Details ### Checkpoint Key Format (Post-Gloas) ```typescript // Pre-Gloas (always single variant): "100-0x1234abcd" // epoch-rootHex // Post-Gloas (dual variants): "100-0x1234abcd-false" // epoch-rootHex-payloadPresent (block state) "100-0x1234abcd-true" // epoch-rootHex-payloadPresent (payload state) ``` ### State Variant Semantics - **Block State** (`payloadPresent = false`): State after processing beacon block, before execution payload - Only exists for Gloas blocks (PENDING/EMPTY variants) - **Payload State** (`payloadPresent = true`): State after processing execution payload - Exists for all pre-Gloas blocks (single variant) - Exists for Gloas blocks after payload revelation ## Migration & Compatibility - **Pre-Gloas blocks**: All state cache operations default to `payloadPresent = true` - **Backward compatibility**: Checkpoint cache can handle mix of pre-Gloas and post-Gloas states - **Cache key migration**: Existing cache entries remain valid (treated as `payloadPresent = true`) ## Depends On - `nc/epbs-fc` - Fork choice stores checkpoints with payload status (#8845) --- **AI Disclosure**: This PR was written primarily by Claude Code. --------- Co-authored-by: twoeths <10568965+twoeths@users.noreply.github.com> Co-authored-by: Tuyen Nguyen <twoeths@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Cayman <caymannava@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary of Changes
Overview
Updated fork choice to store and use payload status for both finalized and justified checkpoints. This ensures
getFinalizedBlock()andgetJustifiedBlock()return the correct block variant (EMPTY or FULL) based on checkpoint state.1. Added
CheckpointWithPayloadTypeNew type in
store.ts:This type extends
CheckpointWithHexwith apayloadStatusfield to track whether the checkpoint uses EMPTY or FULL block variant.2. Updated ForkChoiceStore
Constructor changes:
justifiedPayloadStatusandfinalizedPayloadStatusparametersCheckpointWithPayloadInterface changes:
finalizedCheckpointandunrealizedFinalizedCheckpoint→CheckpointWithPayloadjustifiedandunrealizedJustified→ useCheckpointWithPayload(via renamed types)3. Renamed Balance Types
CheckpointHexWithBalance→CheckpointWithPayloadAndBalanceCheckpointHexWithTotalBalance→CheckpointWithPayloadAndTotalBalanceBoth now use
CheckpointWithPayloadinstead ofCheckpointWithHex.4. Added
getCheckpointPayloadStatus()HelperPurpose: Determines payload status for a checkpoint by checking
state.executionPayloadAvailabilityLogic:
FULLstate.executionPayloadAvailabilityat checkpoint slotSignature:
5. Updated
onBlock()ProcessingFor justified checkpoint:
getCheckpointPayloadStatus()to compute payload statusCheckpointWithPayloadwith computed statusFor finalized checkpoint:
getCheckpointPayloadStatus()to compute payload statusCheckpointWithPayloadwith computed status6. Updated Fork Choice Methods
getFinalizedBlock():this.fcStore.finalizedCheckpoint.payloadStatusinstead of always usingPayloadStatus.FULLgetJustifiedBlock():this.fcStore.justified.checkpoint.payloadStatusinstead of always usingPayloadStatus.FULLgetFinalizedCheckpoint()andgetJustifiedCheckpoint():CheckpointWithPayload7. Updated Initialization
initializeForkChoiceFromFinalizedState():justifiedPayloadStatususinggetCheckpointPayloadStatus()finalizedPayloadStatususinggetCheckpointPayloadStatus()ForkChoiceStoreconstructorinitializeForkChoiceFromUnfinalizedState():ForkChoiceStoreconstructor