Skip to content

feat: gloas range sync#8988

Draft
twoeths wants to merge 14 commits intoepbs-devnet-0from
te/epbs-devnet-0_syncing
Draft

feat: gloas range sync#8988
twoeths wants to merge 14 commits intoepbs-devnet-0from
te/epbs-devnet-0_syncing

Conversation

@twoeths
Copy link
Contributor

@twoeths twoeths commented Mar 5, 2026

Motivation

  • implement range sync for gloas

Description

  • update "downloadByRange" pipeline
  • implement `processChainSegment"

AI Assistance Disclosure

implement with Codex

@gemini-code-assist
Copy link
Contributor

Summary of Changes

Hello, 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 significantly upgrades the beacon node's synchronization capabilities by integrating support for the Gloas fork's execution payload envelopes. It introduces a new network protocol for fetching these envelopes by range and refactors the block processing pipeline to incorporate their validation and state transition. These changes are crucial for ensuring the node can correctly sync and process blocks once the Gloas fork activates, maintaining data integrity and network compatibility.

Highlights

  • Gloas Range Sync Implementation: Introduced the capability to synchronize execution payload envelopes by range for the upcoming Gloas fork, enhancing the beacon node's ability to fetch and process these critical data structures efficiently.
  • New Network Protocol: Added a new ExecutionPayloadEnvelopesByRange request-response protocol to the network layer, allowing peers to request and serve execution payload envelopes for a specified slot range.
  • Updated Block Processing Pipeline: Modified the core block processing and verification logic to accept and validate execution payload envelopes alongside blocks, ensuring their integrity and correct integration into the chain state during synchronization.
  • Enhanced Data Column Sidecar Validation: Adjusted the validation process for data column sidecars to differentiate between Fulu and Gloas fork types, accommodating the specific requirements and structure of Gloas data column sidecars, including skipping proposer signature verification for post-Gloas sidecars.

🧠 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
  • packages/beacon-node/src/api/impl/beacon/blocks/index.ts
    • Updated verifyBlocksInEpoch call to include a null argument for new envelope parameter.
  • packages/beacon-node/src/chain/blocks/index.ts
    • Imported Slot and gloas types.
    • Modified BlockProcessor's jobQueue and processBlocksJob to accept an optional envelopes map.
    • Updated processBlocks function signature to include envelopes parameter.
    • Passed envelopes to verifyBlocksInEpoch within processBlocks.
  • packages/beacon-node/src/chain/blocks/verifyBlock.ts
    • Imported Slot and gloas types.
    • Modified verifyBlocksInEpoch function signature to include envelopes parameter.
    • Passed envelopes to verifyBlocksExecutionPayload and verifyBlocksStateTransitionOnly.
  • packages/beacon-node/src/chain/blocks/verifyBlocksExecutionPayloads.ts
    • Imported ForkPostDeneb, SignedBeaconBlock, Slot, gloas, isGloasBeaconBlock, kzgCommitmentToVersionedHash, and getBlobKzgCommitments.
    • Modified verifyBlocksExecutionPayload to accept envelopes.
    • Modified verifyBlockExecutionPayload to accept signedEnvelope.
    • Updated logic to determine executionPayload source from either block body or provided signedEnvelope.
    • Adjusted versionedHashes and executionRequests extraction for gloas blocks.
    • Updated getSegmentErrorResponse to handle envelopes and extract executionBlockHash for gloas blocks.
  • packages/beacon-node/src/chain/blocks/verifyBlocksSignatures.ts
    • Imported PublicKey, CachedBeaconStateGloas, createSingleSignatureSetFromComponents, getExecutionPayloadEnvelopeSigningRoot, and BUILDER_INDEX_SELF_BUILD.
    • Modified verifyBlocksSignatures to accept envelopes.
    • Added logic to verify ExecutionPayloadEnvelope signatures for gloas blocks.
    • Implemented verifyExecutionPayloadEnvelopeSignature function.
  • packages/beacon-node/src/chain/blocks/verifyBlocksStateTransitionOnly.ts
    • Imported CachedBeaconStateGloas, processExecutionPayloadEnvelope, Slot, gloas, and isGloasBeaconBlock.
    • Modified verifyBlocksStateTransitionOnly to accept envelopes.
    • Added logic to process ExecutionPayloadEnvelope during state transition for gloas blocks.
  • packages/beacon-node/src/chain/chain.ts
    • Added getSerializedExecutionPayloadEnvelope method to retrieve serialized envelopes.
    • Overloaded processChainSegment to optionally accept an envelopes map.
    • Updated processChainSegment implementation to pass envelopes to the block processor.
  • packages/beacon-node/src/chain/interface.ts
    • Added getSerializedExecutionPayloadEnvelope to IBeaconChain interface.
    • Overloaded processChainSegment in IBeaconChain interface to include envelopes.
  • packages/beacon-node/src/chain/validation/dataColumnSidecar.ts
    • Imported DataColumnSidecars, deneb, and isGloasDataColumnSidecar.
    • Modified validateBlockDataColumnSidecars to accept blockKzgCommitments.
    • Updated validation logic to differentiate between fulu and gloas data column sidecars.
    • Removed redundant kzgCommitments.length check for gloas sidecars.
    • Adjusted signature verification for gloas sidecars to skip proposer signature verification.
  • packages/beacon-node/src/network/interface.ts
    • Added sendExecutionPayloadEnvelopesByRange method to INetwork interface.
  • packages/beacon-node/src/network/network.ts
    • Implemented sendExecutionPayloadEnvelopesByRange using collectMaxResponseTyped.
  • packages/beacon-node/src/network/reqresp/ReqRespBeaconNode.ts
    • Registered ExecutionPayloadEnvelopesByRange protocol for the gloas fork.
  • packages/beacon-node/src/network/reqresp/handlers/executionPayloadEnvelopesByRange.ts
    • Added new file implementing onExecutionPayloadEnvelopesByRange handler.
    • Implemented logic to serve execution payload envelopes by range from the database and chain cache.
  • packages/beacon-node/src/network/reqresp/handlers/index.ts
    • Imported and registered onExecutionPayloadEnvelopesByRange handler.
  • packages/beacon-node/src/network/reqresp/protocols.ts
    • Added ExecutionPayloadEnvelopesByRange protocol definition.
  • packages/beacon-node/src/network/reqresp/rateLimit.ts
    • Added rate limiting configuration for ExecutionPayloadEnvelopesByRange requests.
  • packages/beacon-node/src/network/reqresp/types.ts
    • Imported ForkPostFulu and isForkPostFulu.
    • Added ExecutionPayloadEnvelopesByRange to ReqRespMethod enum.
    • Included ExecutionPayloadEnvelopesByRangeRequest in RequestBodyByMethod and responseSszTypeByMethod.
    • Added onlyPostFuluFork helper function.
  • packages/beacon-node/src/sync/range/batch.ts
    • Imported isForkPostGloas and gloas types.
    • Modified BatchState types to include an optional envelopes map.
    • Updated Batch constructor and state transition methods (downloadingSuccess, startProcessing, processingSuccess, processingError, validationError) to manage envelopes.
    • Added envelopesRequest to DownloadByRangeRequests in getRequests and getRequestsForPeer.
  • packages/beacon-node/src/sync/range/chain.ts
    • Imported gloas type.
    • Modified SyncChainFns interface for processChainSegment and downloadByRange to include envelopes.
    • Updated downloadingSuccess and processBatch to handle envelopes.
  • packages/beacon-node/src/sync/range/range.ts
    • Updated processChainSegment and downloadByRange implementations to pass/receive envelopes.
  • packages/beacon-node/src/sync/utils/downloadByRange.ts
    • Imported DataColumnSidecars, gloas, and isGloasDataColumnSidecar.
    • Added envelopesRequest to DownloadByRangeRequests.
    • Added signedEnvelopes to DownloadByRangeResponses.
    • Modified CacheByRangeResponsesProps to include batchEnvelops.
    • Introduced DownloadByRangeResult type.
    • Modified cacheByRangeResponses to handle envelopes and return DownloadByRangeResult.
    • Modified requestByRange to send ExecutionPayloadEnvelopesByRange requests.
    • Modified validateResponses to include envelopesRequest and signedEnvelopes, and added validateEnvelopesByRangeResponse.
    • Added validateEnvelopesByRangeResponse function.
    • Updated validateColumnsByRangeResponse to handle gloas data column sidecars and blockKzgCommitments.
    • Updated requestsLogMeta to include envelopeStartSlot and envelopeCount.
    • Added new DownloadByRangeErrorCode values for envelope validation.
  • packages/beacon-node/src/sync/utils/downloadByRoot.ts
    • Modified fetchAndValidateColumns to pass blockKzgCommitments to validateBlockDataColumnSidecars.
  • packages/beacon-node/test/unit/sync/range/chain.test.ts
    • Updated test mocks for downloadByRange and processChainSegment to reflect the new envelopes parameter.
  • packages/types/src/gloas/sszTypes.ts
    • Added ExecutionPayloadEnvelopesByRangeRequest SSZ type definition.
  • packages/types/src/gloas/types.ts
    • Added ExecutionPayloadEnvelopesByRangeRequest type.
Activity
  • The pull request was created to implement range synchronization for the Gloas fork.
  • The author explicitly stated that the implementation was assisted by Codex, an AI tool.
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.

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

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

Code Review

This pull request introduces support for gloas range sync by integrating handling of execution payload envelopes throughout the block processing and networking stack. However, a critical security flaw was identified: the importExecutionPayloadEnvelope function, used by both the API and potentially gossip handlers, does not perform BLS signature verification, which bypasses a fundamental security guarantee. It is imperative to add signature verification to this function before merging. Additionally, improvements are needed for code clarity in argument handling for an overloaded function and to add a defensive type check to prevent potential runtime errors.

I am having trouble creating individual review comments. Click here to see my feedback.

packages/beacon-node/src/chain/chain.ts (1082-1096)

medium

The logic to handle the overloaded signatures of processChainSegment is a bit dense and could be hard to follow. Consider refactoring for improved readability by explicitly handling the different argument combinations.

  async processChainSegment(
    blocks: IBlockInput[],
    envelopesOrOpts?: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null | ImportBlockOpts,
    opts?: ImportBlockOpts
  ): Promise<void> {
    let envelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null = null;
    let importOpts: ImportBlockOpts | undefined;

    if (envelopesOrOpts instanceof Map || envelopesOrOpts === null) {
      envelopes = envelopesOrOpts;
      importOpts = opts;
    } else {
      importOpts = envelopesOrOpts;
    }

    return this.blockProcessor.processBlocksJob(blocks, importOpts, envelopes);
  }

packages/beacon-node/src/sync/utils/downloadByRange.ts (554)

medium

The code directly casts block.message.body to gloas.BeaconBlockBody. While it's expected that a block with an envelope is a gloas block, adding a type check with isGloasBeaconBlock would make the code safer and prevent potential runtime errors if a non-gloas block is somehow passed with an envelope.

    if (!isGloasBeaconBlock(block.message)) {
      // This should not happen if an envelope is present
      throw new Error(`Block at slot ${block.message.slot} is not a gloas block but has an envelope`);
    }
    const bid = block.message.body.signedExecutionPayloadBid.message;

@ensi321
Copy link
Contributor

ensi321 commented Mar 5, 2026

Should we target epbs-devnet-0 for new gloas features or unstable then epbs-devnet-0 @nflaig ?

@nflaig
Copy link
Member

nflaig commented Mar 5, 2026

Should we target epbs-devnet-0 for new gloas features or unstable then epbs-devnet-0 @nflaig ?

depends on the change, we can test it first on the epbs-devnet-0 branch in case of this PR, generally should target unstable

@twoeths
Copy link
Contributor Author

twoeths commented Mar 6, 2026

Should we target epbs-devnet-0 for new gloas features or unstable then epbs-devnet-0 @nflaig ?

depends on the change, we can test it first on the epbs-devnet-0 branch in case of this PR, generally should target unstable

in that case I'd separate to multiple PRs to make it easier to review because it has different concerns
my main goal is to be able to do gloas range sync and confirm through finalizedSync.test.ts e2e test

…8995)

## Summary
This PR packages **local range-sync hardening** that is valid
independent of devnet-specific peer behavior.

Notably, this PR does **not** switch range sync to a by-root strategy.

### Included
- Treat req/resp rate-limit server errors as transient in peer scoring
(no downscore for rate-limit responses).
- Range sync batch retry hardening:
  - avoid counting transient download errors toward max-attempt failure,
- add retry delay for transient req/resp/rate-limit paths to avoid hot
retry loops.
- Add peer quarantine for repeated post-fork download error patterns
(2-strike threshold before quarantine).
- Ensure post-Gloas envelope requests are still made even when column
request window is out-of-range.
- Harden envelope validation:
- require envelope presence for every validated block slot in request
range (`ENVELOPE_MISSING_FOR_BLOCK`),
  - keep block/envelope consistency checks.
- Make multi-request req/resp fanout safer by awaiting all in-flight
requests (`Promise.allSettled`) before rethrowing first failure.

### Tests
- `pnpm lint`
- `pnpm vitest
packages/beacon-node/test/unit/network/reqresp/score.test.ts
packages/beacon-node/test/unit/sync/range/batch.test.ts
packages/beacon-node/test/unit/sync/utils/requestByRange.test.ts
packages/beacon-node/test/unit/sync/utils/downloadByRange.test.ts`

## Notes
This is intentionally scoped to mergeable local robustness improvements
and excludes investigation-only by-root range-sync experiments.

---------

Co-authored-by: lodekeeper <lodekeeper@users.noreply.github.com>
@nflaig
Copy link
Member

nflaig commented Mar 6, 2026

I have merged this PR into the epbs-devnet-0 branch via be0b39f, we can revert that again and merge your branch, or we just keep as is and retarget it against unstable once that's feasible, will likely need the envelope input changes first

@twoeths
Copy link
Contributor Author

twoeths commented Mar 9, 2026

I have merged this PR into the epbs-devnet-0 branch via be0b39f, we can revert that again and merge your branch, or we just keep as is and retarget it against unstable once that's feasible, will likely need the envelope input changes first

no need to merge this branch, let's keep this PR as draft and cherry-pick each different parts to unstable later
already had #8996 in progress

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants