@lodestar/beacon-node 1.42.0-dev.5f2fffc2ce → 1.42.0-dev.7552832620

package/src/chain/blocks/importExecutionPayload.ts

@@ -0,0 +1,241 @@
+import {routes} from "@lodestar/api";
+import {ForkName} from "@lodestar/params";
+import {
+  BeaconStateView,
+  CachedBeaconStateGloas,
+  getExecutionPayloadEnvelopeSignatureSet,
+} from "@lodestar/state-transition";
+import {processExecutionPayloadEnvelope} from "@lodestar/state-transition/block";
+import {byteArrayEquals, fromHex, toRootHex} from "@lodestar/utils";
+import {ExecutionPayloadStatus} from "../../execution/index.js";
+import {isQueueErrorAborted} from "../../util/queue/index.js";
+import {BeaconChain} from "../chain.js";
+import {RegenCaller} from "../regen/interface.js";
+import {PayloadEnvelopeInput} from "../seenCache/seenPayloadEnvelopeInput.js";
+import {ImportPayloadOpts} from "./types.js";
+
+const EVENTSTREAM_EMIT_RECENT_EXECUTION_PAYLOAD_SLOTS = 64;
+
+export enum PayloadErrorCode {
+  EXECUTION_ENGINE_INVALID = "PAYLOAD_ERROR_EXECUTION_ENGINE_INVALID",
+  EXECUTION_ENGINE_ERROR = "PAYLOAD_ERROR_EXECUTION_ENGINE_ERROR",
+  BLOCK_NOT_IN_FORK_CHOICE = "PAYLOAD_ERROR_BLOCK_NOT_IN_FORK_CHOICE",
+  STATE_TRANSITION_ERROR = "PAYLOAD_ERROR_STATE_TRANSITION_ERROR",
+  INVALID_SIGNATURE = "PAYLOAD_ERROR_INVALID_SIGNATURE",
+}
+
+export type PayloadErrorType =
+  | {
+      code: PayloadErrorCode.EXECUTION_ENGINE_INVALID;
+      execStatus: ExecutionPayloadStatus;
+      errorMessage: string;
+    }
+  | {
+      code: PayloadErrorCode.EXECUTION_ENGINE_ERROR;
+      execStatus: ExecutionPayloadStatus;
+      errorMessage: string;
+    }
+  | {
+      code: PayloadErrorCode.BLOCK_NOT_IN_FORK_CHOICE;
+      blockRootHex: string;
+    }
+  | {
+      code: PayloadErrorCode.STATE_TRANSITION_ERROR;
+      message: string;
+    }
+  | {
+      code: PayloadErrorCode.INVALID_SIGNATURE;
+    };
+
+export class PayloadError extends Error {
+  type: PayloadErrorType;
+
+  constructor(type: PayloadErrorType, message?: string) {
+    super(message ?? type.code);
+    this.type = type;
+  }
+}
+
+/**
+ * Import an execution payload envelope after all data is available.
+ *
+ * This function:
+ * 1. Gets the ProtoBlock from fork choice
+ * 2. Applies write-queue backpressure (waitForSpace) early, before verification
+ * 3. Regenerates the block state
+ * 4. Runs EL verification (notifyNewPayload) in parallel with signature verification and processExecutionPayloadEnvelope
+ * 5. Persists verified payload envelope to hot DB
+ * 6. Updates fork choice
+ * 7. Caches the post-execution payload state
+ * 8. Records metrics for column sources
+ *
+ */
+export async function importExecutionPayload(
+  this: BeaconChain,
+  payloadInput: PayloadEnvelopeInput,
+  opts: ImportPayloadOpts = {}
+): Promise<void> {
+  const envelope = payloadInput.getPayloadEnvelope();
+  const blockRootHex = payloadInput.blockRootHex;
+
+  // 1. Get ProtoBlock for parent root lookup
+  const protoBlock = this.forkChoice.getBlockHexDefaultStatus(blockRootHex);
+  if (!protoBlock) {
+    throw new PayloadError({
+      code: PayloadErrorCode.BLOCK_NOT_IN_FORK_CHOICE,
+      blockRootHex,
+    });
+  }
+
+  // 2. Apply backpressure from the write queue early, before doing verification work.
+  // The actual DB write is deferred until after verification succeeds.
+  await this.unfinalizedPayloadEnvelopeWrites.waitForSpace();
+
+  // 3. Get pre-state for processExecutionPayloadEnvelope
+  // We need the block state (post-block, pre-payload) to process the envelope
+  const blockState = (await this.regen.getBlockSlotState(
+    protoBlock,
+    protoBlock.slot,
+    {dontTransferCache: true},
+    RegenCaller.processBlock
+  )) as CachedBeaconStateGloas;
+
+  // 4. Run verification steps in parallel
+  // Note: No data availability check needed here - importExecutionPayload is only
+  // called when payloadInput.isComplete() is true, so all data is already available.
+  const [execResult, signatureValid, postPayloadResult] = await Promise.all([
+    this.executionEngine.notifyNewPayload(
+      ForkName.gloas,
+      envelope.message.payload,
+      payloadInput.getVersionedHashes(),
+      fromHex(protoBlock.parentRoot),
+      envelope.message.executionRequests
+    ),
+
+    opts.validSignature === true
+      ? Promise.resolve(true)
+      : (async () => {
+          const signatureSet = getExecutionPayloadEnvelopeSignatureSet(
+            this.config,
+            blockState.epochCtx.pubkeyCache,
+            new BeaconStateView(blockState),
+            envelope,
+            payloadInput.proposerIndex
+          );
+          return this.bls.verifySignatureSets([signatureSet]);
+        })(),
+
+    // Signature verified separately above.
+    // State root check is done separately below with better error typing (matching block pipeline pattern).
+    (async () => {
+      try {
+        return {
+          postPayloadState: processExecutionPayloadEnvelope(blockState, envelope, {
+            verifySignature: false,
+            verifyStateRoot: false,
+          }),
+        };
+      } catch (e) {
+        throw new PayloadError(
+          {
+            code: PayloadErrorCode.STATE_TRANSITION_ERROR,
+            message: (e as Error).message,
+          },
+          `State transition error: ${(e as Error).message}`
+        );
+      }
+    })(),
+  ]);
+
+  // 4b. Check signature verification result
+  if (!signatureValid) {
+    throw new PayloadError({code: PayloadErrorCode.INVALID_SIGNATURE});
+  }
+
+  // 5. Handle EL response
+  switch (execResult.status) {
+    case ExecutionPayloadStatus.VALID:
+      break;
+
+    case ExecutionPayloadStatus.INVALID:
+      throw new PayloadError({
+        code: PayloadErrorCode.EXECUTION_ENGINE_INVALID,
+        execStatus: execResult.status,
+        errorMessage: execResult.validationError ?? "",
+      });
+
+    case ExecutionPayloadStatus.ACCEPTED:
+    case ExecutionPayloadStatus.SYNCING:
+      // TODO GLOAS: Handle optimistic import for payload - for now treat as error
+      throw new PayloadError({
+        code: PayloadErrorCode.EXECUTION_ENGINE_ERROR,
+        execStatus: execResult.status,
+        errorMessage: execResult.validationError ?? "EL syncing, payload not yet validated",
+      });
+
+    case ExecutionPayloadStatus.INVALID_BLOCK_HASH:
+    case ExecutionPayloadStatus.ELERROR:
+    case ExecutionPayloadStatus.UNAVAILABLE:
+      throw new PayloadError({
+        code: PayloadErrorCode.EXECUTION_ENGINE_ERROR,
+        execStatus: execResult.status,
+        errorMessage: execResult.validationError ?? "",
+      });
+  }
+
+  // 5b. Verify envelope state root matches post-state
+  const postPayloadState = postPayloadResult.postPayloadState;
+  const postPayloadStateRoot = postPayloadState.hashTreeRoot();
+  if (!byteArrayEquals(envelope.message.stateRoot, postPayloadStateRoot)) {
+    throw new PayloadError({
+      code: PayloadErrorCode.STATE_TRANSITION_ERROR,
+      message: `Envelope state root mismatch expected=${toRootHex(envelope.message.stateRoot)} actual=${toRootHex(postPayloadStateRoot)}`,
+    });
+  }
+
+  // 5c. Persist payload envelope to hot DB (performed asynchronously to avoid blocking)
+  this.unfinalizedPayloadEnvelopeWrites.push(payloadInput).catch((e) => {
+    if (!isQueueErrorAborted(e)) {
+      this.logger.error(
+        "Error pushing payload envelope to unfinalized write queue",
+        {slot: payloadInput.slot, root: blockRootHex},
+        e as Error
+      );
+    }
+  });
+
+  // 6. Update fork choice
+  this.forkChoice.onExecutionPayload(
+    blockRootHex,
+    payloadInput.getBlockHashHex(),
+    envelope.message.payload.blockNumber,
+    toRootHex(postPayloadStateRoot)
+  );
+
+  // 7. Cache payload state
+  // TODO GLOAS: Enable when PR #8868 merged (adds processPayloadState)
+  // this.regen.processPayloadState(postPayloadState);
+  // if epoch boundary also call
+  // this.regen.addCheckpointState(cp, checkpointState, true);
+
+  // 8. Record metrics for payload envelope and column sources
+  this.metrics?.importPayload.bySource.inc({source: payloadInput.getPayloadEnvelopeSource().source});
+  for (const {source} of payloadInput.getSampledColumnsWithSource()) {
+    this.metrics?.importPayload.columnsBySource.inc({source});
+  }
+
+  this.logger.verbose("Execution payload imported", {
+    slot: payloadInput.slot,
+    root: blockRootHex,
+    blockHash: payloadInput.getBlockHashHex(),
+  });
+
+  // 9. Emit event after payload is fully verified and imported to fork choice, only for recent enough payloads
+  const currentSlot = this.clock.currentSlot;
+  if (currentSlot - payloadInput.slot < EVENTSTREAM_EMIT_RECENT_EXECUTION_PAYLOAD_SLOTS) {
+    this.emitter.emit(routes.events.EventType.executionPayloadAvailable, {
+      slot: payloadInput.slot,
+      blockRoot: blockRootHex,
+    });
+  }
+}

package/src/chain/blocks/payloadEnvelopeInput/index.ts

@@ -0,0 +1,2 @@
+export * from "./payloadEnvelopeInput.js";
+export * from "./types.js";

package/src/chain/blocks/payloadEnvelopeInput/payloadEnvelopeInput.ts

@@ -0,0 +1,336 @@
+import {NUMBER_OF_COLUMNS} from "@lodestar/params";
+import {ColumnIndex, DataColumnSidecars, RootHex, Slot, ValidatorIndex, deneb, gloas} from "@lodestar/types";
+import {toRootHex, withTimeout} from "@lodestar/utils";
+import {VersionedHashes} from "../../../execution/index.js";
+import {kzgCommitmentToVersionedHash} from "../../../util/blobs.js";
+import {AddPayloadEnvelopeProps, ColumnWithSource, CreateFromBlockProps, SourceMeta} from "./types.js";
+
+export type PayloadEnvelopeInputState =
+  | {
+      hasPayload: false;
+      hasAllData: false;
+      hasComputedAllData: false;
+    }
+  | {
+      hasPayload: false;
+      hasAllData: true;
+      hasComputedAllData: boolean;
+    }
+  | {
+      hasPayload: true;
+      hasAllData: false;
+      hasComputedAllData: false;
+      payloadEnvelope: gloas.SignedExecutionPayloadEnvelope;
+      payloadEnvelopeSource: SourceMeta;
+    }
+  | {
+      hasPayload: true;
+      hasAllData: true;
+      hasComputedAllData: boolean;
+      payloadEnvelope: gloas.SignedExecutionPayloadEnvelope;
+      payloadEnvelopeSource: SourceMeta;
+      timeCompleteSec: number;
+    };
+
+type PromiseParts<T> = {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (e: Error) => void;
+};
+
+function createPromise<T>(): PromiseParts<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (e: Error) => void;
+  const promise = new Promise<T>((_resolve, _reject) => {
+    resolve = _resolve;
+    reject = _reject;
+  });
+  return {promise, resolve, reject};
+}
+
+/**
+ * Tracks bid + payload envelope + data columns for a Gloas block.
+ *
+ * Created during block import from signedExecutionPayloadBid in block body.
+ * Always has bid (required for creation).
+ *
+ * Completion requires: payload envelope + all sampled columns
+ */
+export class PayloadEnvelopeInput {
+  readonly blockRootHex: RootHex;
+  readonly slot: Slot;
+  readonly proposerIndex: ValidatorIndex;
+  readonly bid: gloas.ExecutionPayloadBid;
+  readonly versionedHashes: VersionedHashes;
+
+  private columnsCache = new Map<ColumnIndex, ColumnWithSource>();
+
+  private readonly sampledColumns: ColumnIndex[];
+  private readonly custodyColumns: ColumnIndex[];
+
+  private timeCreatedSec: number;
+
+  private readonly payloadEnvelopeDataPromise: PromiseParts<gloas.SignedExecutionPayloadEnvelope>;
+  private readonly columnsDataPromise: PromiseParts<DataColumnSidecars>;
+
+  state: PayloadEnvelopeInputState;
+
+  private constructor(props: {
+    blockRootHex: RootHex;
+    slot: Slot;
+    proposerIndex: ValidatorIndex;
+    bid: gloas.ExecutionPayloadBid;
+    sampledColumns: ColumnIndex[];
+    custodyColumns: ColumnIndex[];
+    timeCreatedSec: number;
+  }) {
+    this.blockRootHex = props.blockRootHex;
+    this.slot = props.slot;
+    this.proposerIndex = props.proposerIndex;
+    this.bid = props.bid;
+    this.versionedHashes = props.bid.blobKzgCommitments.map(kzgCommitmentToVersionedHash);
+    this.sampledColumns = props.sampledColumns;
+    this.custodyColumns = props.custodyColumns;
+    this.timeCreatedSec = props.timeCreatedSec;
+    this.payloadEnvelopeDataPromise = createPromise();
+    this.columnsDataPromise = createPromise();
+
+    const noBlobs = props.bid.blobKzgCommitments.length === 0;
+    const noSampledColumns = props.sampledColumns.length === 0;
+    const hasAllData = noBlobs || noSampledColumns;
+
+    if (hasAllData) {
+      this.state = {hasPayload: false, hasAllData: true, hasComputedAllData: true};
+      this.columnsDataPromise.resolve(this.getSampledColumns());
+    } else {
+      this.state = {hasPayload: false, hasAllData: false, hasComputedAllData: false};
+    }
+  }
+
+  static createFromBlock(props: CreateFromBlockProps): PayloadEnvelopeInput {
+    const bid = (props.block.message.body as gloas.BeaconBlockBody).signedExecutionPayloadBid.message;
+    return new PayloadEnvelopeInput({
+      blockRootHex: props.blockRootHex,
+      slot: props.block.message.slot,
+      proposerIndex: props.block.message.proposerIndex,
+      bid,
+      sampledColumns: props.sampledColumns,
+      custodyColumns: props.custodyColumns,
+      timeCreatedSec: props.timeCreatedSec,
+    });
+  }
+
+  getBid(): gloas.ExecutionPayloadBid {
+    return this.bid;
+  }
+
+  getBuilderIndex(): ValidatorIndex {
+    return this.bid.builderIndex;
+  }
+
+  getBlockHashHex(): RootHex {
+    return toRootHex(this.bid.blockHash);
+  }
+
+  getBlobKzgCommitments(): deneb.BlobKzgCommitments {
+    return this.bid.blobKzgCommitments;
+  }
+
+  addPayloadEnvelope(props: AddPayloadEnvelopeProps): void {
+    if (this.state.hasPayload) {
+      throw new Error(`Payload envelope already set for block ${this.blockRootHex}`);
+    }
+    if (toRootHex(props.envelope.message.beaconBlockRoot) !== this.blockRootHex) {
+      throw new Error("Payload envelope beacon_block_root mismatch");
+    }
+
+    const source: SourceMeta = {
+      source: props.source,
+      seenTimestampSec: props.seenTimestampSec,
+      peerIdStr: props.peerIdStr,
+    };
+
+    if (this.state.hasAllData) {
+      // Complete state
+      this.state = {
+        hasPayload: true,
+        hasAllData: true,
+        hasComputedAllData: this.state.hasComputedAllData,
+        payloadEnvelope: props.envelope,
+        payloadEnvelopeSource: source,
+        timeCompleteSec: props.seenTimestampSec,
+      };
+      this.payloadEnvelopeDataPromise.resolve(props.envelope);
+    } else {
+      // Has payload, waiting for columns
+      this.state = {
+        hasPayload: true,
+        hasAllData: false,
+        hasComputedAllData: false,
+        payloadEnvelope: props.envelope,
+        payloadEnvelopeSource: source,
+      };
+    }
+  }
+
+  addColumn(columnWithSource: ColumnWithSource): void {
+    const {columnSidecar, seenTimestampSec} = columnWithSource;
+    this.columnsCache.set(columnSidecar.index, columnWithSource);
+
+    const sampledColumns = this.getSampledColumns();
+    const hasAllData =
+      // already hasAllData
+      this.state.hasAllData ||
+      // has all sampled columns
+      sampledColumns.length === this.sampledColumns.length ||
+      // has enough columns to reconstruct the rest
+      this.columnsCache.size >= NUMBER_OF_COLUMNS / 2;
+
+    const hasComputedAllData =
+      // has all sampled columns
+      sampledColumns.length === this.sampledColumns.length;
+
+    if (!hasAllData) {
+      return;
+    }
+
+    if (hasComputedAllData) {
+      this.columnsDataPromise.resolve(sampledColumns);
+    }
+
+    if (this.state.hasPayload) {
+      // Complete state
+      this.state = {
+        hasPayload: true,
+        hasAllData: true,
+        hasComputedAllData: hasComputedAllData || this.state.hasComputedAllData,
+        payloadEnvelope: this.state.payloadEnvelope,
+        payloadEnvelopeSource: this.state.payloadEnvelopeSource,
+        timeCompleteSec: seenTimestampSec,
+      };
+      this.payloadEnvelopeDataPromise.resolve(this.state.payloadEnvelope);
+    } else {
+      // No payload yet, all data ready
+      this.state = {
+        hasPayload: false,
+        hasAllData: true,
+        hasComputedAllData: hasComputedAllData || this.state.hasComputedAllData,
+      };
+    }
+  }
+
+  getVersionedHashes(): VersionedHashes {
+    return this.versionedHashes;
+  }
+
+  hasPayloadEnvelope(): boolean {
+    return this.state.hasPayload;
+  }
+
+  getPayloadEnvelope(): gloas.SignedExecutionPayloadEnvelope {
+    if (!this.state.hasPayload) throw new Error("Payload envelope not set");
+    return this.state.payloadEnvelope;
+  }
+
+  getPayloadEnvelopeSource(): SourceMeta {
+    if (!this.state.hasPayload) throw new Error("Payload envelope source not set");
+    return this.state.payloadEnvelopeSource;
+  }
+
+  getSampledColumns(): gloas.DataColumnSidecars {
+    const columns: gloas.DataColumnSidecars = [];
+    for (const index of this.sampledColumns) {
+      const column = this.columnsCache.get(index);
+      if (column) {
+        columns.push(column.columnSidecar);
+      }
+    }
+    return columns;
+  }
+
+  getSampledColumnsWithSource(): ColumnWithSource[] {
+    const columns: ColumnWithSource[] = [];
+    for (const index of this.sampledColumns) {
+      const column = this.columnsCache.get(index);
+      if (column) {
+        columns.push(column);
+      }
+    }
+    return columns;
+  }
+
+  getCustodyColumns(): gloas.DataColumnSidecars {
+    const columns: gloas.DataColumnSidecars = [];
+    for (const index of this.custodyColumns) {
+      const column = this.columnsCache.get(index);
+      if (column) {
+        columns.push(column.columnSidecar);
+      }
+    }
+    return columns;
+  }
+
+  hasComputedAllData(): boolean {
+    return this.state.hasComputedAllData;
+  }
+
+  waitForComputedAllData(timeout: number, signal?: AbortSignal): Promise<DataColumnSidecars> {
+    if (this.state.hasComputedAllData) {
+      return Promise.resolve(this.getSampledColumns());
+    }
+    return withTimeout(() => this.columnsDataPromise.promise, timeout, signal);
+  }
+
+  getTimeCreated(): number {
+    return this.timeCreatedSec;
+  }
+
+  getTimeComplete(): number {
+    if (!this.state.hasPayload || !this.state.hasAllData) throw new Error("Not yet complete");
+    return this.state.timeCompleteSec;
+  }
+
+  isComplete(): boolean {
+    return this.state.hasPayload && this.state.hasAllData;
+  }
+
+  async waitForData(): Promise<gloas.SignedExecutionPayloadEnvelope> {
+    return this.payloadEnvelopeDataPromise.promise;
+  }
+
+  getSerializedCacheKeys(): object[] {
+    const objects: object[] = [];
+
+    if (this.state.hasPayload) {
+      objects.push(this.state.payloadEnvelope);
+    }
+
+    for (const {columnSidecar} of this.columnsCache.values()) {
+      objects.push(columnSidecar);
+    }
+
+    return objects;
+  }
+
+  getLogMeta(): {
+    slot: number;
+    blockRoot: string;
+    hasPayload: boolean;
+    hasAllData: boolean;
+    hasComputedAllData: boolean;
+    isComplete: boolean;
+    columnsCount: number;
+    sampledColumnsCount: number;
+  } {
+    return {
+      slot: this.slot,
+      blockRoot: this.blockRootHex,
+      hasPayload: this.state.hasPayload,
+      hasAllData: this.state.hasAllData,
+      hasComputedAllData: this.state.hasComputedAllData,
+      isComplete: this.isComplete(),
+      columnsCount: this.columnsCache.size,
+      sampledColumnsCount: this.sampledColumns.length,
+    };
+  }
+}

package/src/chain/blocks/payloadEnvelopeInput/types.ts

@@ -0,0 +1,33 @@
+import {ForkPostGloas} from "@lodestar/params";
+import {ColumnIndex, RootHex, SignedBeaconBlock, gloas} from "@lodestar/types";
+
+export enum PayloadEnvelopeInputSource {
+  gossip = "gossip",
+  api = "api",
+  engine = "engine",
+  byRange = "req_resp_by_range",
+  byRoot = "req_resp_by_root",
+  recovery = "recovery",
+}
+
+export type SourceMeta = {
+  source: PayloadEnvelopeInputSource;
+  seenTimestampSec: number;
+  peerIdStr?: string;
+};
+
+export type ColumnWithSource = SourceMeta & {
+  columnSidecar: gloas.DataColumnSidecar;
+};
+
+export type CreateFromBlockProps = {
+  blockRootHex: RootHex;
+  block: SignedBeaconBlock<ForkPostGloas>;
+  sampledColumns: ColumnIndex[];
+  custodyColumns: ColumnIndex[];
+  timeCreatedSec: number;
+};
+
+export type AddPayloadEnvelopeProps = SourceMeta & {
+  envelope: gloas.SignedExecutionPayloadEnvelope;
+};

package/src/chain/blocks/payloadEnvelopeProcessor.ts

@@ -0,0 +1,61 @@
+import {Metrics} from "../../metrics/metrics.js";
+import {JobItemQueue} from "../../util/queue/index.js";
+import type {BeaconChain} from "../chain.js";
+import {PayloadEnvelopeInput} from "../seenCache/seenPayloadEnvelopeInput.js";
+import {importExecutionPayload} from "./importExecutionPayload.js";
+import {ImportPayloadOpts} from "./types.js";
+
+// TODO GLOAS: Set to be equal to DEFAULT_MAX_PENDING_UNFINALIZED_PAYLOAD_ENVELOPE_WRITES for now
+const QUEUE_MAX_LENGTH = 16;
+
+enum PayloadEnvelopeImportStatus {
+  queued = "queued",
+  importing = "importing",
+  imported = "imported",
+}
+
+/**
+ * PayloadEnvelopeProcessor processes payload envelope jobs in a queued fashion, one after the other.
+ */
+export class PayloadEnvelopeProcessor {
+  readonly jobQueue: JobItemQueue<[PayloadEnvelopeInput, ImportPayloadOpts], void>;
+  private readonly importStatus = new WeakMap<PayloadEnvelopeInput, PayloadEnvelopeImportStatus>();
+
+  constructor(chain: BeaconChain, metrics: Metrics | null, signal: AbortSignal) {
+    this.jobQueue = new JobItemQueue<[PayloadEnvelopeInput, ImportPayloadOpts], void>(
+      (payloadInput, opts) => {
+        this.importStatus.set(payloadInput, PayloadEnvelopeImportStatus.importing);
+        return importExecutionPayload.call(chain, payloadInput, opts);
+      },
+      {maxLength: QUEUE_MAX_LENGTH, noYieldIfOneItem: true, signal},
+      metrics?.payloadEnvelopeProcessorQueue ?? undefined
+    );
+  }
+
+  async processPayloadEnvelopeJob(payloadInput: PayloadEnvelopeInput, opts: ImportPayloadOpts = {}): Promise<void> {
+    if (!payloadInput.isComplete()) {
+      return;
+    }
+
+    if (this.importStatus.get(payloadInput) !== undefined) {
+      return;
+    }
+
+    await this.jobQueue.waitForSpace();
+
+    // Re-check after await, as another call may have queued this payload.
+    if (this.importStatus.get(payloadInput) !== undefined) {
+      return;
+    }
+
+    this.importStatus.set(payloadInput, PayloadEnvelopeImportStatus.queued);
+
+    try {
+      await this.jobQueue.push(payloadInput, opts);
+      this.importStatus.set(payloadInput, PayloadEnvelopeImportStatus.imported);
+    } catch (e) {
+      this.importStatus.delete(payloadInput);
+      throw e;
+    }
+  }
+}

package/src/chain/blocks/types.ts

@@ -41,6 +41,14 @@ export enum BlobSidecarValidation {
   Full,
 }
 
+export type ImportPayloadOpts = {
+  /**
+   * Set to true if envelope signature was already verified (e.g., during gossip/API validation).
+   * When false/undefined, signature will be verified during import.
+   */
+  validSignature?: boolean;
+};
+
 export type ImportBlockOpts = {
   /**
    * TEMP: Review if this is safe, Lighthouse always imports attestations even in finalized sync.