@lodestar/beacon-node 1.43.0-dev.a140dd987e → 1.43.0-dev.a45ba75824

package/src/sync/range/batch.ts

@@ -1,10 +1,11 @@
 import {ChainForkConfig} from "@lodestar/config";
-import {ForkName, isForkPostDeneb, isForkPostFulu} from "@lodestar/params";
+import {ForkName, isForkPostDeneb, isForkPostFulu, isForkPostGloas} from "@lodestar/params";
 import {Epoch, RootHex, Slot, phase0} from "@lodestar/types";
-import {LodestarError} from "@lodestar/utils";
+import {LodestarError, prettyPrintIndices} from "@lodestar/utils";
 import {isBlockInputColumns} from "../../chain/blocks/blockInput/blockInput.js";
 import {IBlockInput} from "../../chain/blocks/blockInput/types.js";
 import {isDaOutOfRange} from "../../chain/blocks/blockInput/utils.js";
+import {PayloadEnvelopeInput} from "../../chain/blocks/payloadEnvelopeInput/payloadEnvelopeInput.js";
 import {BlockError, BlockErrorCode} from "../../chain/errors/index.js";
 import {PeerSyncMeta} from "../../network/peers/peersData.js";
 import {IClock} from "../../util/clock.js";
@@ -46,25 +47,68 @@ export type Attempt = {
 export type AwaitingDownloadState = {
   status: BatchStatus.AwaitingDownload;
   blocks: IBlockInput[];
+  payloadEnvelopes: Map<Slot, PayloadEnvelopeInput> | null;
 };
 
 export type DownloadSuccessState = {
   status: BatchStatus.AwaitingProcessing;
   blocks: IBlockInput[];
+  payloadEnvelopes: Map<Slot, PayloadEnvelopeInput> | null;
 };
 
 export type BatchState =
   | AwaitingDownloadState
-  | {status: BatchStatus.Downloading; peer: PeerIdStr; blocks: IBlockInput[]}
+  | {
+      status: BatchStatus.Downloading;
+      peer: PeerIdStr;
+      blocks: IBlockInput[];
+      payloadEnvelopes: Map<Slot, PayloadEnvelopeInput> | null;
+    }
   | DownloadSuccessState
-  | {status: BatchStatus.Processing; blocks: IBlockInput[]; attempt: Attempt}
-  | {status: BatchStatus.AwaitingValidation; blocks: IBlockInput[]; attempt: Attempt};
+  | {
+      status: BatchStatus.Processing;
+      blocks: IBlockInput[];
+      payloadEnvelopes: Map<Slot, PayloadEnvelopeInput> | null;
+      attempt: Attempt;
+    }
+  | {
+      status: BatchStatus.AwaitingValidation;
+      blocks: IBlockInput[];
+      payloadEnvelopes: Map<Slot, PayloadEnvelopeInput> | null;
+      attempt: Attempt;
+    };
 
 export type BatchMetadata = {
+  // Batch-level slot window (always present)
   startEpoch: Epoch;
+  startSlot: Slot;
+  count: number;
   status: BatchStatus;
+
+  // Per-type outstanding request shapes; only present when that sub-request exists.
+  // Format: "startSlot=<n>,count=<n>" (plus ",cols=<indices>" for columns).
+  blocksReq?: string;
+  blobsReq?: string;
+  columnsReq?: string;
+  envelopesReq?: string;
+
+  // Retry counters
+  downloadAttempts: number;
+  processingAttempts: number;
+
+  // Cumulative peer attribution for failed attempts (only present when non-empty)
+  failedDownloadPeers?: string;
+  failedProcessingPeers?: string;
 };
 
+function formatRangeReq(req: {startSlot: Slot; count: number}): string {
+  return `startSlot=${req.startSlot},count=${req.count}`;
+}
+
+function formatColumnsReq(req: {startSlot: Slot; count: number; columns: number[]}): string {
+  return `startSlot=${req.startSlot},count=${req.count},cols=${prettyPrintIndices(req.columns)}`;
+}
+
 /**
  * Batches are downloaded at the first block of the epoch.
  *
@@ -85,7 +129,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,35 +173,33 @@ export class Batch {
         count: this.count,
         step: 1,
       };
-      if (isForkPostFulu(this.forkName) && withinValidRequestWindow) {
-        return {
-          blocksRequest,
-          columnsRequest: {
-            startSlot: this.startSlot,
-            count: this.count,
-            columns: this.custodyConfig.sampledColumns,
-          },
-        };
+      const requests: DownloadByRangeRequests = {blocksRequest};
+
+      // Post-Gloas envelopes are required for block processing, independent of DA retention window.
+      if (isForkPostGloas(this.forkName)) {
+        requests.envelopesRequest = {startSlot: this.startSlot, count: this.count};
       }
-      if (isForkPostDeneb(this.forkName) && withinValidRequestWindow) {
-        return {
-          blocksRequest,
-          blobsRequest: {
-            startSlot: this.startSlot,
-            count: this.count,
-          },
+
+      if (isForkPostFulu(this.forkName) && withinValidRequestWindow) {
+        requests.columnsRequest = {
+          startSlot: this.startSlot,
+          count: this.count,
+          columns: this.custodyConfig.sampledColumns,
         };
+      } else if (isForkPostDeneb(this.forkName) && withinValidRequestWindow) {
+        requests.blobsRequest = {startSlot: this.startSlot, count: this.count};
       }
-      return {
-        blocksRequest,
-      };
+
+      return requests;
     }
 
     // subsequent request where part of the epoch has already been downloaded. Need to figure out what is the beginning
     // of the range where download needs to resume
     let blockStartSlot = this.startSlot;
     let dataStartSlot = this.startSlot;
+    let envelopeStartSlot = this.startSlot;
     const neededColumns = new Set<number>();
+    const envelopesBySlot = this.state.payloadEnvelopes ?? new Map<Slot, PayloadEnvelopeInput>();
 
     // ensure blocks are in slot-wise order
     for (const blockInput of blocks) {
@@ -175,6 +217,13 @@ export class Batch {
       if (blockInput.hasBlock() && blockStartSlot === blockSlot) {
         blockStartSlot = blockSlot + 1;
       }
+      if (
+        blockInput.hasBlock() &&
+        envelopeStartSlot === blockSlot &&
+        envelopesBySlot.get(blockSlot)?.hasPayloadEnvelope()
+      ) {
+        envelopeStartSlot = blockSlot + 1;
+      }
       if (!blockInput.hasAllData()) {
         if (isBlockInputColumns(blockInput)) {
           for (const index of blockInput.getMissingSampledColumnMeta().missing) {
@@ -216,6 +265,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;
   }
 
@@ -256,13 +312,36 @@ export class Batch {
   }
 
   getMetadata(): BatchMetadata {
-    return {startEpoch: this.startEpoch, status: this.state.status};
+    const {blocksRequest, blobsRequest, columnsRequest, envelopesRequest} = this.requests;
+    const failedProcessingPeerList = this.failedProcessingAttempts.flatMap((a) => a.peers);
+    return {
+      startEpoch: this.startEpoch,
+      startSlot: this.startSlot,
+      count: this.count,
+      status: this.state.status,
+      ...(blocksRequest && {blocksReq: formatRangeReq(blocksRequest)}),
+      ...(blobsRequest && {blobsReq: formatRangeReq(blobsRequest)}),
+      ...(columnsRequest && {columnsReq: formatColumnsReq(columnsRequest)}),
+      ...(envelopesRequest && {envelopesReq: formatRangeReq(envelopesRequest)}),
+      downloadAttempts: this.failedDownloadAttempts.length,
+      processingAttempts: this.failedProcessingAttempts.length,
+      ...(this.failedDownloadAttempts.length > 0 && {
+        failedDownloadPeers: this.failedDownloadAttempts.join(","),
+      }),
+      ...(failedProcessingPeerList.length > 0 && {
+        failedProcessingPeers: failedProcessingPeerList.join(","),
+      }),
+    };
   }
 
   getBlocks(): IBlockInput[] {
     return this.state.blocks;
   }
 
+  getPayloadEnvelopes(): Map<Slot, PayloadEnvelopeInput> | null {
+    return this.state.payloadEnvelopes;
+  }
+
   /**
    * AwaitingDownload -> Downloading
    */
@@ -271,13 +350,22 @@ 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, PayloadEnvelopeInput> | null
+  ): DownloadSuccessState {
     if (this.state.status !== BatchStatus.Downloading) {
       throw new BatchError(this.wrongStatusErrorType(BatchStatus.Downloading));
     }
@@ -305,11 +393,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 +418,34 @@ 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, PayloadEnvelopeInput> | null;
+    peers: PeerIdStr[];
+  } {
     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, peers};
   }
 
   /**
@@ -357,7 +456,12 @@ 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 +512,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,12 +523,12 @@ 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 */
   private errorType(type: BatchErrorType): BatchErrorType & BatchErrorMetadata {
-    return {...type, ...this.getMetadata()};
+    return {...type, startEpoch: this.startEpoch, status: this.state.status};
   }
 
   private wrongStatusErrorType(expectedStatus: BatchStatus): BatchErrorType & BatchErrorMetadata {

package/src/sync/range/chain.ts

@@ -1,9 +1,10 @@
 import {ChainForkConfig} from "@lodestar/config";
 import {Epoch, Root, Slot} from "@lodestar/types";
-import {ErrorAborted, LodestarError, Logger, toRootHex} from "@lodestar/utils";
+import {ErrorAborted, LodestarError, Logger, prettyPrintIndices, toRootHex} from "@lodestar/utils";
 import {isBlockInputBlobs, isBlockInputColumns} from "../../chain/blocks/blockInput/blockInput.js";
 import {BlockInputErrorCode} from "../../chain/blocks/blockInput/errors.js";
 import {IBlockInput} from "../../chain/blocks/blockInput/types.js";
+import {PayloadEnvelopeInput} from "../../chain/blocks/payloadEnvelopeInput/payloadEnvelopeInput.js";
 import {BlobSidecarErrorCode} from "../../chain/errors/blobSidecarError.js";
 import {DataColumnSidecarErrorCode} from "../../chain/errors/dataColumnSidecarError.js";
 import {Metrics} from "../../metrics/metrics.js";
@@ -44,13 +45,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, PayloadEnvelopeInput> | 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, PayloadEnvelopeInput> | 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 */
@@ -215,12 +222,14 @@ export class SyncChain {
    */
   stopSyncing(): void {
     this.status = SyncChainStatus.Stopped;
+    this.logger.debug("SyncChain stopSyncing", {id: this.logId});
   }
 
   /**
    * Permanently remove this chain. Throws the main AsyncIterable
    */
   remove(): void {
+    this.logger.debug("SyncChain remove", {id: this.logId});
     this.batchProcessor.end(new ErrorAborted("SyncChain"));
   }
 
@@ -516,7 +525,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,
         };
@@ -526,7 +536,7 @@ export class SyncChain {
             this.metrics?.syncRange.downloadByRange.warn.inc({client: peer.client, code: warning.type.code});
             this.logger.debug(
               "Batch downloaded with warning",
-              {id: this.logId, epoch: batch.startEpoch, ...logMeta, peer: prettyPrintPeerIdStr(peer.peerId)},
+              {id: this.logId, ...batch.getMetadata(), ...logMeta, peer: prettyPrintPeerIdStr(peer.peerId)},
               warning
             );
           }
@@ -552,10 +562,17 @@ export class SyncChain {
           // the flow will continue to call triggerBatchDownloader() below
         }
 
+        const blockSlots = downloadSuccessOutput.blocks.map((b) => b.slot);
+        const envelopeSlots = downloadSuccessOutput.payloadEnvelopes
+          ? Array.from(downloadSuccessOutput.payloadEnvelopes.keys())
+          : null;
+
         this.logger.debug(logMessage, {
           id: this.logId,
-          epoch: batch.startEpoch,
+          ...batch.getMetadata(),
           ...logMeta,
+          blockSlots: prettyPrintIndices(blockSlots),
+          ...(envelopeSlots ? {envelopeSlots: prettyPrintIndices(envelopeSlots)} : {}),
           peer: prettyPrintPeerIdStr(peer.peerId),
         });
       }
@@ -578,13 +595,24 @@ 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, peers} = batch.startProcessing();
+
+    const logCtx = {
+      id: this.logId,
+      ...batch.getMetadata(),
+      blockCount: blocks.length,
+      blockSlots: prettyPrintIndices(blocks.map((b) => b.slot)),
+      ...(payloadEnvelopes ? {envelopeSlots: prettyPrintIndices(Array.from(payloadEnvelopes.keys()))} : {}),
+      peers: peers.map(prettyPrintPeerIdStr).join(","),
+    };
+    this.logger.verbose("Processing batch", logCtx);
 
     // 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();
+      this.logger.verbose("Processed batch", {...logCtx, ...batch.getMetadata()});
 
       // If the processed batch is not empty, validate previous AwaitingValidation blocks.
       if (blocks.length > 0) {
@@ -594,7 +622,7 @@ export class SyncChain {
       // Potentially process next AwaitingProcessing batch
       this.triggerBatchProcessor();
     } else {
-      this.logger.verbose("Batch process error", {id: this.logId, ...batch.getMetadata()}, res.err);
+      this.logger.verbose("Batch process error", logCtx, res.err);
       batch.processingError(res.err); // Throws after MAX_BATCH_PROCESSING_ATTEMPTS
 
       // At least one block was successfully verified and imported, so we can be sure all

package/src/sync/range/range.ts

@@ -172,7 +172,7 @@ 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.
@@ -192,9 +192,15 @@ export class RangeSync extends (EventEmitter as {new (): RangeSyncEmitter}) {
 
     if (this.opts?.disableProcessAsChainSegment) {
       // Should only be used for debugging or testing
-      for (const block of blocks) await this.chain.processBlock(block, flags);
+      for (const block of blocks) {
+        await this.chain.processBlock(block, flags);
+        const payloadEnvelope = payloadEnvelopes?.get(block.slot);
+        if (payloadEnvelope) {
+          await this.chain.processExecutionPayload(payloadEnvelope);
+        }
+      }
     } else {
-      await this.chain.processChainSegment(blocks, flags);
+      await this.chain.processChainSegment(blocks, payloadEnvelopes, flags);
     }
   };
 
@@ -209,13 +215,19 @@ export class RangeSync extends (EventEmitter as {new (): RangeSyncEmitter}) {
       peerDasMetrics: this.chain.metrics?.peerDas,
       ...batch.getRequestsForPeer(peer),
     });
-    const cached = cacheByRangeResponses({
+    const {responses, payloadEnvelopes: downloadedPayloadEnvelopes} = result;
+    const {blocks, payloadEnvelopes} = cacheByRangeResponses({
       cache: this.chain.seenBlockInputCache,
+      seenPayloadEnvelopeInputCache: this.chain.seenPayloadEnvelopeInputCache,
       peerIdStr: peer.peerId,
-      responses: result,
+      responses,
       batchBlocks,
+      downloadedPayloadEnvelopes,
+      existingPayloadEnvelopes: batch.getPayloadEnvelopes(),
+      custodyConfig: this.chain.custodyConfig,
+      seenTimestampSec: Date.now() / 1000,
     });
-    return {result: cached, warnings};
+    return {result: {blocks, payloadEnvelopes}, warnings};
   };
 
   private pruneBlockInputs: SyncChainFns["pruneBlockInputs"] = (blocks: IBlockInput[]) => {

package/src/sync/types.ts

@@ -1,5 +1,8 @@
 import {RootHex, Slot} from "@lodestar/types";
+import {SignedExecutionPayloadEnvelope} from "@lodestar/types/gloas";
+import {toRootHex} from "@lodestar/utils";
 import {IBlockInput} from "../chain/blocks/blockInput/index.js";
+import {PayloadEnvelopeInput} from "../chain/blocks/payloadEnvelopeInput/payloadEnvelopeInput.js";
 
 export enum PendingBlockType {
   /**
@@ -26,6 +29,14 @@ export enum PendingBlockInputStatus {
   processing = "processing",
 }
 
+export enum PendingPayloadInputStatus {
+  pending = "pending",
+  fetching = "fetching",
+  waitingForBlock = "waiting_for_block",
+  downloaded = "downloaded",
+  processing = "processing",
+}
+
 export type PendingBlockInput = {
   status: PendingBlockInputStatus;
   blockInput: IBlockInput;
@@ -44,10 +55,47 @@ export type PendingRootHex = {
 
 export type BlockInputSyncCacheItem = PendingBlockInput | PendingRootHex;
 
+export type PendingPayloadInput = {
+  status:
+    | PendingPayloadInputStatus.pending
+    | PendingPayloadInputStatus.fetching
+    | PendingPayloadInputStatus.downloaded
+    | PendingPayloadInputStatus.processing;
+  payloadInput: PayloadEnvelopeInput;
+  timeAddedSec: number;
+  timeSyncedSec?: number;
+  peerIdStrings: Set<string>;
+};
+
+export type PendingPayloadRootHex = {
+  status: PendingPayloadInputStatus.pending | PendingPayloadInputStatus.fetching;
+  rootHex: RootHex;
+  timeAddedSec: number;
+  timeSyncedSec?: number;
+  peerIdStrings: Set<string>;
+};
+
+export type PendingPayloadEnvelope = {
+  status: PendingPayloadInputStatus.waitingForBlock;
+  envelope: SignedExecutionPayloadEnvelope;
+  timeAddedSec: number;
+  peerIdStrings: Set<string>;
+};
+
+export type PayloadSyncCacheItem = PendingPayloadInput | PendingPayloadRootHex | PendingPayloadEnvelope;
+
 export function isPendingBlockInput(pending: BlockInputSyncCacheItem): pending is PendingBlockInput {
   return "blockInput" in pending;
 }
 
+export function isPendingPayloadInput(pending: PayloadSyncCacheItem): pending is PendingPayloadInput {
+  return "payloadInput" in pending;
+}
+
+export function isPendingPayloadEnvelope(pending: PayloadSyncCacheItem): pending is PendingPayloadEnvelope {
+  return "envelope" in pending;
+}
+
 export function getBlockInputSyncCacheItemRootHex(block: BlockInputSyncCacheItem): RootHex {
   return isPendingBlockInput(block) ? block.blockInput.blockRootHex : block.rootHex;
 }
@@ -55,3 +103,27 @@ export function getBlockInputSyncCacheItemRootHex(block: BlockInputSyncCacheItem
 export function getBlockInputSyncCacheItemSlot(block: BlockInputSyncCacheItem): Slot | string {
   return isPendingBlockInput(block) ? block.blockInput.slot : "unknown";
 }
+
+export function getPayloadSyncCacheItemRootHex(payload: PayloadSyncCacheItem): RootHex {
+  if (isPendingPayloadInput(payload)) {
+    return payload.payloadInput.blockRootHex;
+  }
+
+  if (isPendingPayloadEnvelope(payload)) {
+    return toRootHex(payload.envelope.message.beaconBlockRoot);
+  }
+
+  return payload.rootHex;
+}
+
+export function getPayloadSyncCacheItemSlot(payload: PayloadSyncCacheItem): Slot | string {
+  if (isPendingPayloadInput(payload)) {
+    return payload.payloadInput.slot;
+  }
+
+  if (isPendingPayloadEnvelope(payload)) {
+    return payload.envelope.message.payload.slotNumber;
+  }
+
+  return "unknown";
+}