feat: cache builder deposit signatures for gloas fork transition

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

@@ -10,12 +10,15 @@ import {
   isForkPostGloas,
 } from "@lodestar/params";
 import {
+  GLOAS_PREVERIFY_WINDOW_EPOCHS,
   IBeaconStateView,
   IBeaconStateViewBellatrix,
+  MAX_BUILDER_DEPOSITS_PER_SLOT,
   StateHashTreeRootSource,
   computeEpochAtSlot,
   computeTimeAtSlot,
   isStatePostBellatrix,
+  isStatePostFulu,
   isStatePostGloas,
 } from "@lodestar/state-transition";
 import {Bytes32, Slot, ValidatorIndex} from "@lodestar/types";
@@ -37,6 +40,11 @@ export const PREPARE_NEXT_SLOT_BPS = 6667;
 /* We don't want to do more epoch transition than this */
 const PREPARE_EPOCH_LIMIT = 1;
 
+/* Fraction of a slot (out of 10_000) the pre-Gloas builder-deposit pre-verify may spend per tick.
+ * 2000 = 20% of slot (2.4s on mainnet), within the spare window left after PREPARE_NEXT_SLOT_BPS.
+ * Expressed in bps so it scales with slot duration (mainnet vs minimal/devnet). */
+const BUILDER_PREVERIFY_LIMIT_BPS = 2000;
+
 /**
  * At Bellatrix, if we are responsible for proposing in next slot, we want to prepare payload
  * 4s before the start of next slot at PREPARE_NEXT_SLOT_BPS of the current slot.
@@ -117,6 +125,7 @@ export class PrepareNextSlotScheduler {
         ? this.metrics?.precomputeNextEpochTransition.duration.startTimer()
         : null;
       const start = Date.now();
+      let feeRecipient: string | undefined;
       // No need to wait for this or the clock drift
       if (isForkPostBellatrix(fork)) {
         let preparedState: IBeaconStateView | undefined;
@@ -140,7 +149,7 @@ export class PrepareNextSlotScheduler {
         };
 
         const proposerIndex = await getProposerIndex();
-        const feeRecipient = this.chain.beaconProposerCache.get(proposerIndex);
+        feeRecipient = this.chain.beaconProposerCache.get(proposerIndex);
 
         if (feeRecipient) {
           // If we are proposing next slot, we need to predict if we can proposer-boost-reorg or not
@@ -287,6 +296,74 @@ export class PrepareNextSlotScheduler {
         });
 
         precomputeEpochTransitionTimer?.();
+
+        // Nothing more to do on an epoch-transition slot: that precompute already ran a full (>1s)
+        // epoch transition, so we don't pile the builder-deposit pre-verify (below) on top of it.
+        return;
+      }
+
+      // Pre-verify builder-deposit signatures in the GLOAS_PREVERIFY_WINDOW_EPOCHS epochs leading
+      // up to the Gloas fork, off the block-import hot path, so onboardBuildersFromPendingDeposits
+      // at the transition is mostly cache hits. Reached only on non-epoch-transition slots (the
+      // epoch-transition branch returned above). Runs on the head state — its pendingDeposits are
+      // what the fork transition derives from, and its epochCtx holds the shared, app-wide
+      // builderDepositSignatureCache.
+      const headState = this.chain.getHeadState();
+      if (isStatePostFulu(headState)) {
+        const gloasEpoch = this.config.GLOAS_FORK_EPOCH;
+        const finalizedEpoch = this.chain.forkChoice.getFinalizedCheckpoint().epoch;
+        if (finalizedEpoch >= gloasEpoch) {
+          // Gloas is finalized — the pre-verify cache has served its purpose; release its memory.
+          headState.clearPreGloasBuilderDepositCache();
+        } else {
+          const clockEpoch = computeEpochAtSlot(clockSlot);
+          if (
+            ForkSeq[fork] < ForkSeq.gloas && // only before the fork
+            clockEpoch >= gloasEpoch - GLOAS_PREVERIFY_WINDOW_EPOCHS && // Infinity when Gloas unscheduled → skip
+            clockEpoch < gloasEpoch &&
+            // skip when we're the next-slot proposer — don't compete with block-production prep.
+            feeRecipient === undefined
+          ) {
+            const maxDurationMs = this.config.getSlotComponentDurationMs(BUILDER_PREVERIFY_LIMIT_BPS);
+            const preVerifyTimer = this.metrics?.builderDepositPreVerify.duration.startTimer();
+            const result = headState.preVerifyBuilderDepositsPreGloas(MAX_BUILDER_DEPOSITS_PER_SLOT, maxDurationMs);
+            preVerifyTimer?.();
+
+            const preVerifyMetrics = this.metrics?.builderDepositPreVerify;
+            if (preVerifyMetrics) {
+              preVerifyMetrics.pendingDeposits.set(result.pendingDepositsCount);
+              preVerifyMetrics.cachedDeposits.set(result.totalCachedDeposits);
+              preVerifyMetrics.scannedDeposits.set(result.scannedPendingDeposits);
+              preVerifyMetrics.builderPubkeys.set(result.totalBuilderPubkeys);
+              if (result.validBuilderSignaturesCount > 0) {
+                preVerifyMetrics.validSignatures.inc({type: "builder"}, result.validBuilderSignaturesCount);
+              }
+              if (result.validValidatorSignaturesCount > 0) {
+                preVerifyMetrics.validSignatures.inc({type: "validator"}, result.validValidatorSignaturesCount);
+              }
+              if (result.invalidBuilderSignaturesCount > 0) {
+                preVerifyMetrics.invalidSignatures.inc({type: "builder"}, result.invalidBuilderSignaturesCount);
+              }
+              if (result.invalidValidatorSignaturesCount > 0) {
+                preVerifyMetrics.invalidSignatures.inc({type: "validator"}, result.invalidValidatorSignaturesCount);
+              }
+            }
+
+            // Always log (once per slot, only within the pre-fork window) so devnets show the
+            // pre-verify draining even on all-cache-hit ticks.
+            this.logger.verbose("PrepareNextSlotScheduler pre-verified deposit signatures", {
+              clockSlot,
+              validBuilderSignaturesCount: result.validBuilderSignaturesCount,
+              invalidBuilderSignaturesCount: result.invalidBuilderSignaturesCount,
+              validValidatorSignaturesCount: result.validValidatorSignaturesCount,
+              invalidValidatorSignaturesCount: result.invalidValidatorSignaturesCount,
+              scannedPendingDeposits: result.scannedPendingDeposits,
+              totalCachedDeposits: result.totalCachedDeposits,
+              totalBuilderPubkeys: result.totalBuilderPubkeys,
+              pendingDepositsCount: result.pendingDepositsCount,
+            });
+          }
+        }
       }
     } catch (e) {
       if (!isErrorAborted(e) && !isQueueErrorAborted(e)) {

packages/beacon-node/src/metrics/metrics/lodestar.ts

@@ -1708,6 +1708,41 @@ export function createLodestarMetrics(
       }),
     },
 
+    // Pre-verify builder-deposit signatures in the epochs before the Gloas fork (prepareNextSlot).
+    builderDepositPreVerify: {
+      duration: register.histogram({
+        name: "lodestar_builder_deposit_preverify_duration_seconds",
+        help: "Duration of one preVerifyBuilderDepositsPreGloas call (BLS batch verify + scan)",
+        buckets: [1, 2, 3, 4],
+      }),
+      pendingDeposits: register.gauge({
+        name: "lodestar_builder_deposit_preverify_pending_deposits",
+        help: "Current state.pendingDeposits length (backlog to drain before the fork)",
+      }),
+      cachedDeposits: register.gauge({
+        name: "lodestar_builder_deposit_preverify_cached_deposits",
+        help: "Deposit signatures verified & cached so far this pre-fork window (valid + invalid)",
+      }),
+      scannedDeposits: register.gauge({
+        name: "lodestar_builder_deposit_preverify_scanned_deposits",
+        help: "Pending deposits examined by the last pre-verify call (< pending_deposits ⇒ cap hit)",
+      }),
+      builderPubkeys: register.gauge({
+        name: "lodestar_builder_deposit_preverify_builder_pubkeys",
+        help: "Distinct builder pubkeys tracked this window (validator deposits for these are pre-verified)",
+      }),
+      validSignatures: register.counter<{type: "builder" | "validator"}>({
+        name: "lodestar_builder_deposit_preverify_valid_signatures_total",
+        help: "Cumulative deposit signatures whose BLS verification passed (VALID), by credential type",
+        labelNames: ["type"],
+      }),
+      invalidSignatures: register.counter<{type: "builder" | "validator"}>({
+        name: "lodestar_builder_deposit_preverify_invalid_signatures_total",
+        help: "Cumulative deposit signatures whose BLS verification failed (INVALID), by credential type",
+        labelNames: ["type"],
+      }),
+    },
+
     // reprocess attestations
     reprocessApiAttestations: {
       total: register.gauge({

packages/state-transition/src/block/processDeposit.ts

@@ -1,4 +1,4 @@
-import {PublicKey, Signature, verify} from "@chainsafe/blst";
+import {PublicKey, Signature, verify, verifyMultipleAggregateSignatures} from "@chainsafe/blst";
 import {BeaconConfig} from "@lodestar/config";
 import {
   DEPOSIT_CONTRACT_TREE_DEPTH,
@@ -138,6 +138,10 @@ export function addValidatorToRegistry(
   state.balances.push(amount);
 }
 
+/**
+ * Verify a single deposit signature (proof of possession). See {@link verifyDepositSignatures} for
+ * the batch equivalent — the two MUST stay consistent (same domain, signing root, and checks).
+ */
 export function isValidDepositSignature(
   config: BeaconConfig,
   pubkey: Uint8Array,
@@ -164,3 +168,73 @@ export function isValidDepositSignature(
     return false; // Catch all BLS errors: failed key validation, failed signature validation, invalid signature
   }
 }
+
+/**
+ * Batch equivalent of {@link isValidDepositSignature} — verify many deposit signatures at once.
+ * MUST stay consistent with `isValidDepositSignature`: same fork-agnostic deposit domain, same
+ * `DepositMessage` signing root, same group + infinity checks. Tries a single aggregate verify and,
+ * on failure, falls back to verifying each deposit individually so the valid deposits in a batch
+ * containing an invalid one are still identified. Returns a boolean per input deposit; `slot` is not
+ * part of the signature check.
+ *
+ * Used by the pre-Gloas builder-deposit pre-verify scanner (see `preVerifyBuilderDeposits.ts`).
+ */
+export function verifyDepositSignatures(config: BeaconConfig, deposits: electra.PendingDeposit[]): boolean[] {
+  const results = new Array<boolean>(deposits.length).fill(false);
+  // fork-agnostic domain since deposits are valid across forks, matching isValidDepositSignature
+  const domain = computeDomain(DOMAIN_DEPOSIT, config.GENESIS_FORK_VERSION, ZERO_HASH);
+
+  const signatureSets: {pk: PublicKey; msg: Uint8Array; sig: Signature}[] = [];
+  const signatureSetDepositIndices: number[] = [];
+  for (let i = 0; i < deposits.length; i++) {
+    const {pubkey, withdrawalCredentials, amount, signature} = deposits[i];
+    let pk: PublicKey;
+    let sig: Signature;
+    try {
+      // Parse without group/infinity checks; deferred to the verify call below so it can be
+      // batched across all sets.
+      pk = PublicKey.fromBytes(pubkey);
+      sig = Signature.fromBytes(signature);
+    } catch (_) {
+      // Malformed pubkey or signature bytes - invalid deposit, results[i] stays false
+      continue;
+    }
+    const msg = computeSigningRoot(ssz.phase0.DepositMessage, {pubkey, withdrawalCredentials, amount}, domain);
+    signatureSets.push({pk, msg, sig});
+    signatureSetDepositIndices.push(i);
+  }
+
+  if (signatureSets.length === 0) {
+    return results;
+  }
+
+  // Deposit pubkeys and signatures are untrusted, so group + infinity checks are required.
+  // The trailing (true, true) args delegate those checks to blst, amortized across the batch.
+  let batchValid: boolean;
+  try {
+    batchValid =
+      signatureSets.length >= 2
+        ? verifyMultipleAggregateSignatures(signatureSets, true, true)
+        : verify(signatureSets[0].msg, signatureSets[0].pk, signatureSets[0].sig, true, true);
+  } catch (_) {
+    batchValid = false;
+  }
+
+  if (batchValid) {
+    for (const depositIndex of signatureSetDepositIndices) {
+      results[depositIndex] = true;
+    }
+  } else {
+    for (let s = 0; s < signatureSets.length; s++) {
+      try {
+        if (verify(signatureSets[s].msg, signatureSets[s].pk, signatureSets[s].sig, true, true)) {
+          results[signatureSetDepositIndices[s]] = true;
+        }
+      } catch (_) {
+        // invalid point / malformed → invalid signature, results[i] stays false
+      }
+    }
+  }
+
+  return results;
+}

packages/state-transition/src/cache/builderDepositSignatureCache.ts

@@ -0,0 +1,81 @@
+import {PubkeyHex, electra} from "@lodestar/types";
+
+/**
+ * Caches deposit signature-verification results — passes (`true`) and failures (`false`) — so the
+ * Fulu → Gloas fork transition can skip the bulk verification cost AND skip re-verifying deposits
+ * already proven invalid. Covers both builder-prefix deposits (onboarding) and validator deposits
+ * that share a pubkey with a builder deposit (the ones `hasPendingValidator` checks at the fork).
+ *
+ * Keyed by the deposit's struct **value object** — `electra.PendingDeposit` is a
+ * `ContainerNodeStructType`, so its `node.value` is a stable object reused across
+ * prepareNextSlot-derived states and carried by reference through the gloas pendingDeposits
+ * migration. No merkle-root computation, no slot bucketing.
+ *
+ * Also tracks builder pubkeys seen so the scanner knows which validator deposits to pre-verify (only
+ * those sharing a pubkey with a builder deposit ever reach `hasPendingValidator`). The mapped boolean
+ * records whether a *valid* validator deposit for that pubkey has been found: once true, the scanner
+ * stops pre-verifying further validator deposits for it — `hasPendingValidator` short-circuits on the
+ * first valid signature at the fork, so the rest would never be read.
+ *
+ * Lifecycle owned by `prepareNextSlot`: filled during the pre-fork window, then `clear()`ed once the
+ * Gloas fork is finalized. `onboardBuildersFromPendingDeposits()` only reads it. A plain `Map` (not a
+ * `WeakMap`) is used so the drop is deterministic and the contents are inspectable for logging.
+ *
+ * Single instance across the application (created in `EpochCache.createFromState`, shared
+ * by-reference through `clone()`).
+ */
+export class BuilderDepositSignatureCache {
+  private validityByDeposit = new Map<electra.PendingDeposit, boolean>();
+  /** builder pubkey → whether a valid validator deposit sharing it has already been pre-verified. */
+  private builderPubkeys = new Map<PubkeyHex, boolean>();
+
+  setSignatureValidity(deposit: electra.PendingDeposit, isValid: boolean): void {
+    this.validityByDeposit.set(deposit, isValid);
+  }
+
+  getSignatureValidity(deposit: electra.PendingDeposit): boolean | null {
+    return this.validityByDeposit.get(deposit) ?? null;
+  }
+
+  isVerified(deposit: electra.PendingDeposit): boolean {
+    return this.validityByDeposit.has(deposit);
+  }
+
+  /** Record a builder deposit's pubkey so the scanner pre-verifies validator deposits for it.
+   *  Idempotent; never downgrades a pubkey already marked as having a valid validator deposit. */
+  addBuilderPubkey(pubkeyHex: PubkeyHex): void {
+    if (!this.builderPubkeys.has(pubkeyHex)) {
+      this.builderPubkeys.set(pubkeyHex, false);
+    }
+  }
+
+  isBuilderPubkey(pubkeyHex: PubkeyHex): boolean {
+    return this.builderPubkeys.has(pubkeyHex);
+  }
+
+  /** True once a valid validator deposit sharing this builder pubkey has been pre-verified — the
+   *  scanner then skips this pubkey's remaining validator deposits (as `hasPendingValidator` would). */
+  hasValidValidatorDeposit(pubkeyHex: PubkeyHex): boolean {
+    return this.builderPubkeys.get(pubkeyHex) === true;
+  }
+
+  /** Mark that a valid validator deposit sharing this builder pubkey was found. */
+  setValidValidatorDeposit(pubkeyHex: PubkeyHex): void {
+    this.builderPubkeys.set(pubkeyHex, true);
+  }
+
+  /** Cumulative deposits verified & cached this window (pass + fail). */
+  get cachedDepositCount(): number {
+    return this.validityByDeposit.size;
+  }
+
+  /** Distinct builder pubkeys tracked this window. */
+  get builderPubkeyCount(): number {
+    return this.builderPubkeys.size;
+  }
+
+  clear(): void {
+    this.validityByDeposit.clear();
+    this.builderPubkeys.clear();
+  }
+}

packages/state-transition/src/cache/epochCache.ts

@@ -53,6 +53,7 @@ import {
 } from "../util/shuffling.js";
 import {computeBaseRewardPerIncrement, computeSyncParticipantReward} from "../util/syncCommittee.js";
 import {sumTargetUnslashedBalanceIncrements} from "../util/targetUnslashedBalance.js";
+import {BuilderDepositSignatureCache} from "./builderDepositSignatureCache.js";
 import {EffectiveBalanceIncrements, getEffectiveBalanceIncrementsWithLen} from "./effectiveBalanceIncrements.js";
 import {EpochTransitionCache} from "./epochTransitionCache.js";
 import {PubkeyCache, createPubkeyCache, syncPubkeys} from "./pubkeyCache.js";
@@ -112,6 +113,13 @@ export class EpochCache {
    * Couples both index→pubkey and pubkey→index lookups, keeping them in sync atomically.
    */
   pubkeyCache: PubkeyCache;
+  /**
+   * Shared across all clones of the same chain head. Holds builder deposit signature validity
+   * pre-verified by the prepareForNextSlot scheduler in the `GLOAS_PREVERIFY_WINDOW_EPOCHS` epochs
+   * leading up to GLOAS_FORK_EPOCH, so `onboardBuildersFromPendingDeposits()` at the fork transition
+   * can skip the bulk verification cost. There should only exist one for the entire application.
+   */
+  builderDepositSignatureCache: BuilderDepositSignatureCache;
   /**
    * Indexes of the block proposers for the current epoch.
    * For pre-fulu, this is computed and cached from the current shuffling.
@@ -245,6 +253,7 @@ export class EpochCache {
   constructor(data: {
     config: BeaconConfig;
     pubkeyCache: PubkeyCache;
+    builderDepositSignatureCache: BuilderDepositSignatureCache;
     proposers: number[];
     proposersPrevEpoch: number[] | null;
     proposersNextEpoch: ProposersDeferred;
@@ -277,6 +286,7 @@ export class EpochCache {
   }) {
     this.config = data.config;
     this.pubkeyCache = data.pubkeyCache;
+    this.builderDepositSignatureCache = data.builderDepositSignatureCache;
     this.proposers = data.proposers;
     this.proposersPrevEpoch = data.proposersPrevEpoch;
     this.proposersNextEpoch = data.proposersNextEpoch;
@@ -514,6 +524,8 @@ export class EpochCache {
     return new EpochCache({
       config,
       pubkeyCache,
+      // Created once per application (shared by-reference through clone()).
+      builderDepositSignatureCache: new BuilderDepositSignatureCache(),
       proposers,
       // On first epoch, set to null to prevent unnecessary work since this is only used for metrics
       proposersPrevEpoch: null,
@@ -558,6 +570,8 @@ export class EpochCache {
       config: this.config,
       // Common append-only structures shared with all states, no need to clone
       pubkeyCache: this.pubkeyCache,
+      // Singleton per application, shared by-reference across clones
+      builderDepositSignatureCache: this.builderDepositSignatureCache,
       // Immutable data
       proposers: this.proposers,
       proposersPrevEpoch: this.proposersPrevEpoch,