feat: range sync envelope support for Gloas (supersedes #9155)

Range sync now fetches and validates execution payload envelopes alongside
blocks for Gloas forks. With deferred processing, blocks can sync
optimistically without envelopes, but envelopes are fetched in parallel
for fork-choice FULL/EMPTY variant accuracy.

Changes:
- Batch carries payloadEnvelopes across all state transitions
- downloadByRange fetches envelopes via sendExecutionPayloadEnvelopesByRange
- validateEnvelopesByRangeResponse verifies beaconBlockRoot matches blocks
- processChainSegment accepts payloadEnvelopes parameter
- SyncChainFns types updated for envelope data flow
- Add INVALID_ENVELOPE_BEACON_BLOCK_ROOT error code

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ensi321

packages/beacon-node/src/chain/blocks/importExecutionPayload.ts

@@ -153,7 +153,12 @@ export async function importExecutionPayload(
 
   // 5a. Pure envelope verification (no state mutation)
   try {
-    blockState.verifyExecutionPayloadEnvelope(signedEnvelope, {verifySignature: false});
+    // When validSignature is true, the envelope came from gossip/API where both
+    // signature and executionRequestsRoot were already verified — skip re-hashing
+    blockState.verifyExecutionPayloadEnvelope(signedEnvelope, {
+      verifySignature: false,
+      verifyExecutionRequestsRoot: !opts.validSignature,
+    });
   } catch (e) {
     throw new PayloadError(
       {

packages/beacon-node/src/chain/chain.ts

@@ -73,6 +73,7 @@ import {BlockProcessor, ImportBlockOpts} from "./blocks/index.js";
 import {PayloadEnvelopeProcessor} from "./blocks/payloadEnvelopeProcessor.js";
 import {ImportPayloadOpts} from "./blocks/types.js";
 import {persistBlockInput} from "./blocks/writeBlockInputToDb.js";
+import {PayloadEnvelopeInputSource} from "./blocks/payloadEnvelopeInput/types.js";
 import {persistPayloadEnvelopeInput} from "./blocks/writePayloadEnvelopeInputToDb.js";
 import {BlsMultiThreadWorkerPool, BlsSingleThreadVerifier, IBlsVerifier} from "./bls/index.js";
 import {ColumnReconstructionTracker} from "./ColumnReconstructionTracker.js";
@@ -1100,8 +1101,35 @@ export class BeaconChain implements IBeaconChain {
     return this.blockProcessor.processBlocksJob([block], opts);
   }
 
-  async processChainSegment(blocks: IBlockInput[], opts?: ImportBlockOpts): Promise<void> {
-    return this.blockProcessor.processBlocksJob(blocks, opts);
+  async processChainSegment(
+    blocks: IBlockInput[],
+    payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null,
+    opts?: ImportBlockOpts
+  ): Promise<void> {
+    await this.blockProcessor.processBlocksJob(blocks, opts);
+
+    // After blocks are imported, add downloaded envelopes to their PayloadEnvelopeInput
+    // and trigger processing. Each block's importBlock() already created a PayloadEnvelopeInput
+    // in seenPayloadEnvelopeInputCache.
+    if (payloadEnvelopes) {
+      for (const [slot, envelope] of payloadEnvelopes) {
+        const blockRootHex = toRootHex(envelope.message.beaconBlockRoot);
+        const payloadInput = this.seenPayloadEnvelopeInputCache.get(blockRootHex);
+        if (!payloadInput || payloadInput.hasPayloadEnvelope()) continue;
+
+        payloadInput.addPayloadEnvelope({
+          envelope,
+          source: PayloadEnvelopeInputSource.byRange,
+          seenTimestampSec: Date.now() / 1000,
+        });
+
+        if (payloadInput.isComplete()) {
+          this.processExecutionPayload(payloadInput, {validSignature: false}).catch((e) => {
+            this.logger.debug("Error processing envelope from range sync", {slot, root: blockRootHex}, e as Error);
+          });
+        }
+      }
+    }
   }
 
   async processExecutionPayload(payloadInput: PayloadEnvelopeInput, opts?: ImportPayloadOpts): Promise<void> {

packages/beacon-node/src/chain/interface.ts

@@ -248,7 +248,11 @@ export interface IBeaconChain {
   /** Process a block until complete */
   processBlock(block: IBlockInput, opts?: ImportBlockOpts): Promise<void>;
   /** Process a chain of blocks until complete */
-  processChainSegment(blocks: IBlockInput[], opts?: ImportBlockOpts): Promise<void>;
+  processChainSegment(
+    blocks: IBlockInput[],
+    payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null,
+    opts?: ImportBlockOpts
+  ): Promise<void>;
 
   /** Process execution payload envelope: verify, import to fork choice, and persist to DB */
   processExecutionPayload(payloadInput: PayloadEnvelopeInput, opts?: ImportPayloadOpts): Promise<void>;

packages/beacon-node/src/sync/range/batch.ts

@@ -1,6 +1,6 @@
 import {ChainForkConfig} from "@lodestar/config";
-import {ForkName, isForkPostDeneb, isForkPostFulu} from "@lodestar/params";
-import {Epoch, RootHex, Slot, phase0} from "@lodestar/types";
+import {ForkName, isForkPostDeneb, isForkPostFulu, isForkPostGloas} from "@lodestar/params";
+import {Epoch, RootHex, Slot, gloas, phase0} from "@lodestar/types";
 import {LodestarError} from "@lodestar/utils";
 import {isBlockInputColumns} from "../../chain/blocks/blockInput/blockInput.js";
 import {IBlockInput} from "../../chain/blocks/blockInput/types.js";
@@ -46,19 +46,21 @@ export type Attempt = {
 export type AwaitingDownloadState = {
   status: BatchStatus.AwaitingDownload;
   blocks: IBlockInput[];
+  payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null;
 };
 
 export type DownloadSuccessState = {
   status: BatchStatus.AwaitingProcessing;
   blocks: IBlockInput[];
+  payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null;
 };
 
 export type BatchState =
   | AwaitingDownloadState
-  | {status: BatchStatus.Downloading; peer: PeerIdStr; blocks: IBlockInput[]}
+  | {status: BatchStatus.Downloading; peer: PeerIdStr; blocks: IBlockInput[]; payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null}
   | DownloadSuccessState
-  | {status: BatchStatus.Processing; blocks: IBlockInput[]; attempt: Attempt}
-  | {status: BatchStatus.AwaitingValidation; blocks: IBlockInput[]; attempt: Attempt};
+  | {status: BatchStatus.Processing; blocks: IBlockInput[]; payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null; attempt: Attempt}
+  | {status: BatchStatus.AwaitingValidation; blocks: IBlockInput[]; payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null; attempt: Attempt};
 
 export type BatchMetadata = {
   startEpoch: Epoch;
@@ -85,7 +87,7 @@ export class Batch {
   /** Block, blob and column requests that are used to determine the best peer and are used in downloadByRange */
   requests: DownloadByRangeRequests;
   /** State of the batch. */
-  state: BatchState = {status: BatchStatus.AwaitingDownload, blocks: []};
+  state: BatchState = {status: BatchStatus.AwaitingDownload, blocks: [], payloadEnvelopes: null};
   /** Peers that provided good data */
   goodPeers: PeerIdStr[] = [];
   /** The `Attempts` that have been made and failed to send us this batch. */
@@ -129,6 +131,10 @@ export class Batch {
         count: this.count,
         step: 1,
       };
+      const envelopesRequest: gloas.ExecutionPayloadEnvelopesByRangeRequest | undefined = isForkPostGloas(this.forkName)
+        ? {startSlot: this.startSlot, count: this.count}
+        : undefined;
+
       if (isForkPostFulu(this.forkName) && withinValidRequestWindow) {
         return {
           blocksRequest,
@@ -137,6 +143,7 @@ export class Batch {
             count: this.count,
             columns: this.custodyConfig.sampledColumns,
           },
+          envelopesRequest,
         };
       }
       if (isForkPostDeneb(this.forkName) && withinValidRequestWindow) {
@@ -146,10 +153,12 @@ export class Batch {
             startSlot: this.startSlot,
             count: this.count,
           },
+          envelopesRequest,
         };
       }
       return {
         blocksRequest,
+        envelopesRequest,
       };
     }
 
@@ -186,6 +195,18 @@ export class Batch {
       }
     }
 
+    // Track envelope start slot for post-Gloas forks
+    let envelopeStartSlot = this.startSlot;
+    if (isForkPostGloas(this.forkName)) {
+      for (const blockInput of blocks) {
+        const blockSlot = blockInput.slot;
+        // Envelopes track separately - advance start slot for contiguous downloaded envelopes
+        if (envelopeStartSlot === blockSlot) {
+          envelopeStartSlot = blockSlot + 1;
+        }
+      }
+    }
+
     // if the blockStartSlot or dataStartSlot is after the desired endSlot then no request will be made for the batch
     // because it is complete
     const endSlot = this.startSlot + this.count - 1;
@@ -216,6 +237,13 @@ export class Batch {
       // dataSlot will still have a value but do not create a request for preDeneb forks
     }
 
+    if (isForkPostGloas(this.forkName) && envelopeStartSlot <= endSlot) {
+      requests.envelopesRequest = {
+        startSlot: envelopeStartSlot,
+        count: endSlot - envelopeStartSlot + 1,
+      };
+    }
+
     return requests;
   }
 
@@ -263,6 +291,10 @@ export class Batch {
     return this.state.blocks;
   }
 
+  getPayloadEnvelopes(): Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null {
+    return this.state.payloadEnvelopes;
+  }
+
   /**
    * AwaitingDownload -> Downloading
    */
@@ -271,13 +303,13 @@ export class Batch {
       throw new BatchError(this.wrongStatusErrorType(BatchStatus.AwaitingDownload));
     }
 
-    this.state = {status: BatchStatus.Downloading, peer, blocks: this.state.blocks};
+    this.state = {status: BatchStatus.Downloading, peer, blocks: this.state.blocks, payloadEnvelopes: this.state.payloadEnvelopes};
   }
 
   /**
    * Downloading -> AwaitingProcessing
    */
-  downloadingSuccess(peer: PeerIdStr, blocks: IBlockInput[]): DownloadSuccessState {
+  downloadingSuccess(peer: PeerIdStr, blocks: IBlockInput[], payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null): DownloadSuccessState {
     if (this.state.status !== BatchStatus.Downloading) {
       throw new BatchError(this.wrongStatusErrorType(BatchStatus.Downloading));
     }
@@ -305,11 +337,13 @@ export class Batch {
         status: this.state.status,
       });
     }
+    const newPayloadEnvelopes = payloadEnvelopes ?? this.state.payloadEnvelopes;
+
     if (allComplete) {
-      this.state = {status: BatchStatus.AwaitingProcessing, blocks};
+      this.state = {status: BatchStatus.AwaitingProcessing, blocks, payloadEnvelopes: newPayloadEnvelopes};
     } else {
       this.requests = this.getRequests(blocks);
-      this.state = {status: BatchStatus.AwaitingDownload, blocks};
+      this.state = {status: BatchStatus.AwaitingDownload, blocks, payloadEnvelopes: newPayloadEnvelopes};
     }
 
     return this.state as DownloadSuccessState;
@@ -328,25 +362,26 @@ export class Batch {
       throw new BatchError(this.errorType({code: BatchErrorCode.MAX_DOWNLOAD_ATTEMPTS}));
     }
 
-    this.state = {status: BatchStatus.AwaitingDownload, blocks: this.state.blocks};
+    this.state = {status: BatchStatus.AwaitingDownload, blocks: this.state.blocks, payloadEnvelopes: this.state.payloadEnvelopes};
   }
 
   /**
    * AwaitingProcessing -> Processing
    */
-  startProcessing(): IBlockInput[] {
+  startProcessing(): {blocks: IBlockInput[]; payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null} {
     if (this.state.status !== BatchStatus.AwaitingProcessing) {
       throw new BatchError(this.wrongStatusErrorType(BatchStatus.AwaitingProcessing));
     }
 
     const blocks = this.state.blocks;
+    const payloadEnvelopes = this.state.payloadEnvelopes;
     const hash = hashBlocks(blocks, this.config); // tracks blocks to report peer on processing error
     // Reset goodPeers in case another download attempt needs to be made.  When Attempt is successful or not the peers
     // that the data came from will be handled by the Attempt that goes for processing
     const peers = this.goodPeers;
     this.goodPeers = [];
-    this.state = {status: BatchStatus.Processing, blocks, attempt: {peers, hash}};
-    return blocks;
+    this.state = {status: BatchStatus.Processing, blocks, payloadEnvelopes, attempt: {peers, hash}};
+    return {blocks, payloadEnvelopes};
   }
 
   /**
@@ -357,7 +392,7 @@ export class Batch {
       throw new BatchError(this.wrongStatusErrorType(BatchStatus.Processing));
     }
 
-    this.state = {status: BatchStatus.AwaitingValidation, blocks: this.state.blocks, attempt: this.state.attempt};
+    this.state = {status: BatchStatus.AwaitingValidation, blocks: this.state.blocks, payloadEnvelopes: this.state.payloadEnvelopes, attempt: this.state.attempt};
   }
 
   /**
@@ -408,7 +443,7 @@ export class Batch {
 
     // remove any downloaded blocks and re-attempt
     // TODO(fulu): need to remove the bad blocks from the SeenBlockInputCache
-    this.state = {status: BatchStatus.AwaitingDownload, blocks: []};
+    this.state = {status: BatchStatus.AwaitingDownload, blocks: [], payloadEnvelopes: null};
   }
 
   private onProcessingError(attempt: Attempt): void {
@@ -419,7 +454,7 @@ export class Batch {
 
     // remove any downloaded blocks and re-attempt
     // TODO(fulu): need to remove the bad blocks from the SeenBlockInputCache
-    this.state = {status: BatchStatus.AwaitingDownload, blocks: []};
+    this.state = {status: BatchStatus.AwaitingDownload, blocks: [], payloadEnvelopes: null};
   }
 
   /** Helper to construct typed BatchError. Stack traces are correct as the error is thrown above */

packages/beacon-node/src/sync/range/chain.ts

@@ -1,5 +1,5 @@
 import {ChainForkConfig} from "@lodestar/config";
-import {Epoch, Root, Slot} from "@lodestar/types";
+import {Epoch, Root, Slot, gloas} from "@lodestar/types";
 import {ErrorAborted, LodestarError, Logger, toRootHex} from "@lodestar/utils";
 import {isBlockInputBlobs, isBlockInputColumns} from "../../chain/blocks/blockInput/blockInput.js";
 import {BlockInputErrorCode} from "../../chain/blocks/blockInput/errors.js";
@@ -44,13 +44,19 @@ export type SyncChainFns = {
    * Must return if ALL blocks are processed successfully
    * If SOME blocks are processed must throw BlockProcessorError()
    */
-  processChainSegment: (blocks: IBlockInput[], syncType: RangeSyncType) => Promise<void>;
+  processChainSegment: (
+    blocks: IBlockInput[],
+    payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null,
+    syncType: RangeSyncType
+  ) => Promise<void>;
   /** Must download blocks, and validate their range */
   downloadByRange: (
     peer: PeerSyncMeta,
     batch: Batch,
     syncType: RangeSyncType
-  ) => Promise<WarnResult<IBlockInput[], DownloadByRangeError>>;
+  ) => Promise<
+    WarnResult<{blocks: IBlockInput[]; payloadEnvelopes: Map<Slot, gloas.SignedExecutionPayloadEnvelope> | null}, DownloadByRangeError>
+  >;
   /** Report peer for negative actions. Decouples from the full network instance */
   reportPeer: (peer: PeerIdStr, action: PeerAction, actionName: string) => void;
   /** Gets current peer custodyColumns and earliestAvailableSlot */
@@ -516,7 +522,8 @@ export class SyncChain {
         });
         this.metrics?.syncRange.downloadByRange.success.inc();
         const {warnings, result} = res.result;
-        const downloadSuccessOutput = batch.downloadingSuccess(peer.peerId, result);
+        const {blocks: downloadedBlocks, payloadEnvelopes} = result;
+        const downloadSuccessOutput = batch.downloadingSuccess(peer.peerId, downloadedBlocks, payloadEnvelopes);
         const logMeta: Record<string, number> = {
           blockCount: downloadSuccessOutput.blocks.length,
         };
@@ -578,10 +585,10 @@ export class SyncChain {
    * Sends `batch` to the processor. Note: batch may be empty
    */
   private async processBatch(batch: Batch): Promise<void> {
-    const blocks = batch.startProcessing();
+    const {blocks, payloadEnvelopes} = batch.startProcessing();
 
     // wrapError ensures to never call both batch success() and batch error()
-    const res = await wrapError(this.processChainSegment(blocks, this.syncType));
+    const res = await wrapError(this.processChainSegment(blocks, payloadEnvelopes, this.syncType));
 
     if (!res.err) {
       batch.processingSuccess();

packages/beacon-node/src/sync/range/range.ts

@@ -172,7 +172,11 @@ export class RangeSync extends (EventEmitter as {new (): RangeSyncEmitter}) {
   }
 
   /** Convenience method for `SyncChain` */
-  private processChainSegment: SyncChainFns["processChainSegment"] = async (blocks, syncType) => {
+  private processChainSegment: SyncChainFns["processChainSegment"] = async (
+    blocks,
+    payloadEnvelopes,
+    syncType
+  ) => {
     // Not trusted, verify signatures
     const flags: ImportBlockOpts = {
       // Only skip importing attestations for finalized sync. For head sync attestation are valuable.
@@ -194,7 +198,7 @@ export class RangeSync extends (EventEmitter as {new (): RangeSyncEmitter}) {
       // Should only be used for debugging or testing
       for (const block of blocks) await this.chain.processBlock(block, flags);
     } else {
-      await this.chain.processChainSegment(blocks, flags);
+      await this.chain.processChainSegment(blocks, payloadEnvelopes, flags);
     }
   };
 
@@ -209,13 +213,14 @@ export class RangeSync extends (EventEmitter as {new (): RangeSyncEmitter}) {
       peerDasMetrics: this.chain.metrics?.peerDas,
       ...batch.getRequestsForPeer(peer),
     });
-    const cached = cacheByRangeResponses({
+    const {responses, payloadEnvelopes} = result;
+    const blocks = cacheByRangeResponses({
       cache: this.chain.seenBlockInputCache,
       peerIdStr: peer.peerId,
-      responses: result,
+      responses,
       batchBlocks,
     });
-    return {result: cached, warnings};
+    return {result: {blocks, payloadEnvelopes}, warnings};
   };
 
   private pruneBlockInputs: SyncChainFns["pruneBlockInputs"] = (blocks: IBlockInput[]) => {