@lodestar/state-transition 1.46.0-dev.281a8ee194 → 1.46.0-dev.3e8651f2dc

package/src/slot/upgradeStateToGloas.ts

@@ -172,8 +172,8 @@ function onboardBuildersFromPendingDeposits(state: CachedBeaconStateGloas): void
   const pendingDeposits = ssz.gloas.PendingDeposits.defaultViewDU();
   const pendingDepositsLookup = PendingDepositsLookup.buildEmpty();
 
-  for (let i = 0; i < state.pendingDeposits.length; i++) {
-    const deposit = state.pendingDeposits.getReadonly(i);
+  for (const deposit of state.pendingDeposits.getAllReadonly()) {
+    const depositValue = deposit.toValue();
 
     const validatorIndex = state.epochCtx.getValidatorIndex(deposit.pubkey);
     const pubkeyHex = toPubkeyHex(deposit.pubkey);
@@ -181,7 +181,7 @@ function onboardBuildersFromPendingDeposits(state: CachedBeaconStateGloas): void
     // Deposits for existing validators stay in the pending queue
     if (isValidatorKnown(state, validatorIndex)) {
       pendingDeposits.push(deposit);
-      pendingDepositsLookup.add(deposit, pubkeyHex);
+      pendingDepositsLookup.add(depositValue, pubkeyHex);
       continue;
     }
 
@@ -202,26 +202,33 @@ function onboardBuildersFromPendingDeposits(state: CachedBeaconStateGloas): void
     // can pick it up later.
     if (!isBuilderWithdrawalCredential(deposit.withdrawalCredentials)) {
       pendingDeposits.push(deposit);
-      pendingDepositsLookup.add(deposit, pubkeyHex);
+      pendingDepositsLookup.add(depositValue, pubkeyHex);
       continue;
     }
-    if (pendingDepositsLookup.hasPendingValidator(state.config, pubkeyHex)) {
+    if (
+      pendingDepositsLookup.hasPendingValidator(state.config, pubkeyHex, state.epochCtx.builderDepositSignatureCache)
+    ) {
       pendingDeposits.push(deposit);
-      pendingDepositsLookup.add(deposit, pubkeyHex);
+      pendingDepositsLookup.add(depositValue, pubkeyHex);
       continue;
     }
 
     // Verify the deposit signature (proof of possession). If invalid the deposit is silently
     // dropped — stake is forfeited, matching the validator deposit contract behavior.
-    if (
-      !isValidDepositSignature(
+    //
+    // The prepareNextSlot scheduler pre-verifies these signatures in the epochs before the fork
+    // A cache miss falls back to verifying this one deposit — no worse than pre-cache.
+    const cached = state.epochCtx.builderDepositSignatureCache.getSignatureValidity(depositValue);
+    const isValid =
+      cached ??
+      isValidDepositSignature(
         state.config,
         deposit.pubkey,
         deposit.withdrawalCredentials,
         deposit.amount,
         deposit.signature
-      )
-    ) {
+      );
+    if (!isValid) {
       continue;
     }
 

package/src/stateView/beaconStateView.ts

@@ -67,6 +67,7 @@ import {
 } from "../util/execution.js";
 import {canBuilderCoverBid} from "../util/gloas.js";
 import {loadState} from "../util/loadState/loadState.js";
+import {PreVerifyBuilderDepositsResult, preVerifyBuilderDepositsPreGloas} from "../util/preVerifyBuilderDeposits.js";
 import {getRandaoMix} from "../util/seed.js";
 import {getLatestWeakSubjectivityCheckpointEpoch} from "../util/weakSubjectivity.js";
 import {IBeaconStateView, IBeaconStateViewGloas, IBeaconStateViewLatestFork, isStatePostGloas} from "./interface.js";
@@ -341,6 +342,18 @@ export class BeaconStateView implements IBeaconStateViewLatestFork {
     return this._proposerLookahead;
   }
 
+  preVerifyBuilderDepositsPreGloas(maxBuilderDeposits: number, maxDurationMs: number): PreVerifyBuilderDepositsResult {
+    return preVerifyBuilderDepositsPreGloas(
+      this.cachedState as CachedBeaconStateFulu,
+      maxBuilderDeposits,
+      maxDurationMs
+    );
+  }
+
+  clearPreGloasBuilderDepositCache(): void {
+    this.cachedState.epochCtx.builderDepositSignatureCache.clear();
+  }
+
   // gloas
 
   get latestBlockHash(): Bytes32 {

package/src/stateView/interface.ts

@@ -52,6 +52,7 @@ import {SyncCommitteeCache} from "../cache/syncCommitteeCache.js";
 import {SyncCommitteeWitness} from "../lightClient/types.js";
 import {StateTransitionModules, StateTransitionOpts} from "../stateTransition.js";
 import {EpochShuffling} from "../util/epochShuffling.js";
+import {PreVerifyBuilderDepositsResult} from "../util/preVerifyBuilderDeposits.js";
 
 /**
  * A read-only view of the BeaconState.
@@ -242,6 +243,13 @@ export interface IBeaconStateViewElectra extends IBeaconStateViewDeneb {
 export interface IBeaconStateViewFulu extends IBeaconStateViewElectra {
   forkName: ForkPostFulu;
   proposerLookahead: fulu.ProposerLookahead;
+  /**
+   * Pre-verify a slice of builder-prefix pending deposits and cache the results on the underlying
+   * `BuilderDepositSignatureCache` (Fulu is the fork immediately before Gloas).
+   */
+  preVerifyBuilderDepositsPreGloas(maxBuilderDeposits: number, maxDurationMs: number): PreVerifyBuilderDepositsResult;
+  /** Drop the pre-Gloas builder-deposit signature cache (called once the Gloas fork is finalized). */
+  clearPreGloasBuilderDepositCache(): void;
 }
 
 /** Gloas+ state fields — use isStatePostGloas() guard */

package/src/stateView/nativeBeaconStateView.ts

@@ -35,6 +35,7 @@ import {SyncCommitteeCache} from "../cache/syncCommitteeCache.js";
 import {SyncCommitteeWitness} from "../lightClient/types.js";
 import {StateTransitionModules, StateTransitionOpts} from "../stateTransition.js";
 import {EpochShuffling} from "../util/epochShuffling.js";
+import {PreVerifyBuilderDepositsResult} from "../util/preVerifyBuilderDeposits.js";
 import {
   IBeaconStateView,
   IBeaconStateViewGloas,
@@ -845,6 +846,14 @@ export class NativeBeaconStateView implements IBeaconStateViewLatestFork {
     return this._proposerLookahead;
   }
 
+  preVerifyBuilderDepositsPreGloas(maxBuilderDeposits: number, maxDurationMs: number): PreVerifyBuilderDepositsResult {
+    return this.binding.preVerifyBuilderDepositsPreGloas(maxBuilderDeposits, maxDurationMs);
+  }
+
+  clearPreGloasBuilderDepositCache(): void {
+    this.binding.clearPreGloasBuilderDepositCache();
+  }
+
   // ─── gloas ───────────────────────────────────────────────────────────────
 
   get latestBlockHash(): Bytes32 {

package/src/testUtils/util.ts

@@ -1,25 +1,28 @@
 import {PublicKey, SecretKey} from "@chainsafe/blst";
 import {BitArray, fromHexString} from "@chainsafe/ssz";
-import {createBeaconConfig, createChainForkConfig} from "@lodestar/config";
+import {BeaconConfig, createBeaconConfig, createChainForkConfig} from "@lodestar/config";
 import {config} from "@lodestar/config/default";
 import {
+  BUILDER_WITHDRAWAL_PREFIX,
+  DOMAIN_DEPOSIT,
   EPOCHS_PER_ETH1_VOTING_PERIOD,
   EPOCHS_PER_HISTORICAL_VECTOR,
   ForkName,
   ForkSeq,
+  GENESIS_SLOT,
   MAX_ATTESTATIONS,
   MAX_EFFECTIVE_BALANCE,
   SLOTS_PER_EPOCH,
   SLOTS_PER_HISTORICAL_ROOT,
 } from "@lodestar/params";
-import {BeaconState, Slot, phase0, ssz} from "@lodestar/types";
+import {BeaconState, Slot, electra, phase0, ssz} from "@lodestar/types";
 import {getEffectiveBalanceIncrements} from "../cache/effectiveBalanceIncrements.js";
+import {ZERO_HASH} from "../constants/index.js";
 import {
   computeCommitteeCount,
   computeEpochAtSlot,
   createCachedBeaconState,
   createPubkeyCache,
-  interopSecretKey,
   newFilledArray,
   processSlots,
 } from "../index.js";
@@ -32,6 +35,9 @@ import {
   CachedBeaconStateElectra,
   CachedBeaconStatePhase0,
 } from "../types.js";
+import {computeDomain} from "../util/domain.js";
+import {interopSecretKey} from "../util/interop.js";
+import {computeSigningRoot} from "../util/signingRoot.js";
 import {getNextSyncCommittee} from "../util/syncCommittee.js";
 import {getActiveValidatorIndices} from "../util/validator.js";
 import {interopPubkeysCached} from "./interop.js";
@@ -541,3 +547,67 @@ export function generateTestCachedBeaconStateOnlyValidators({
     {skipSyncPubkeys: true}
   );
 }
+
+/**
+ * Generate `count` validly-signed builder pending deposits with distinct interop pubkeys
+ * [startIndex, startIndex + count). Withdrawal credentials carry the BUILDER_WITHDRAWAL_PREFIX so
+ * `isBuilderWithdrawalCredential` recognizes them. Used to exercise the pre-Gloas builder-deposit
+ * pre-verify scanner and the fork-transition onboarding path.
+ */
+export function generateBuilderPendingDeposits(
+  config: BeaconConfig,
+  count: number,
+  startIndex: number
+): electra.PendingDeposit[] {
+  // Deposits use a fork-agnostic domain, see `isValidDepositSignature`
+  const domain = computeDomain(DOMAIN_DEPOSIT, config.GENESIS_FORK_VERSION, ZERO_HASH);
+  const amount = 1_000_000_000; // 1 ETH in Gwei
+  const deposits: electra.PendingDeposit[] = [];
+
+  for (let i = 0; i < count; i++) {
+    const sk = interopSecretKey(startIndex + i);
+    const pubkey = sk.toPublicKey().toBytes();
+
+    const withdrawalCredentials = Buffer.alloc(32, 0);
+    withdrawalCredentials[0] = BUILDER_WITHDRAWAL_PREFIX;
+    // bytes [12, 32) hold the 20-byte builder execution address
+    withdrawalCredentials.fill((startIndex + i) & 0xff, 12, 32);
+
+    const signingRoot = computeSigningRoot(ssz.phase0.DepositMessage, {pubkey, withdrawalCredentials, amount}, domain);
+
+    deposits.push({
+      pubkey,
+      withdrawalCredentials,
+      amount,
+      signature: sk.sign(signingRoot).toBytes(),
+      slot: GENESIS_SLOT,
+    });
+  }
+
+  return deposits;
+}
+
+/**
+ * Generate a validly-signed *validator* (0x00-prefix) pending deposit for interop key `keyIndex`.
+ * Shares its pubkey with `generateBuilderPendingDeposits(config, 1, keyIndex)`, so it stands in for a
+ * validator deposit competing with a builder deposit for the same pubkey (the `hasPendingValidator`
+ * path). `amount` lets callers build otherwise-identical-but-distinct deposit value objects.
+ */
+export function generateValidatorPendingDeposit(
+  config: BeaconConfig,
+  keyIndex: number,
+  amount = 32_000_000_000
+): electra.PendingDeposit {
+  const domain = computeDomain(DOMAIN_DEPOSIT, config.GENESIS_FORK_VERSION, ZERO_HASH);
+  const sk = interopSecretKey(keyIndex);
+  const pubkey = sk.toPublicKey().toBytes();
+  const withdrawalCredentials = Buffer.alloc(32, 0); // 0x00 prefix → validator, not a builder
+  const signingRoot = computeSigningRoot(ssz.phase0.DepositMessage, {pubkey, withdrawalCredentials, amount}, domain);
+  return {
+    pubkey,
+    withdrawalCredentials,
+    amount,
+    signature: sk.sign(signingRoot).toBytes(),
+    slot: GENESIS_SLOT,
+  };
+}

package/src/util/index.ts

@@ -20,6 +20,7 @@ export * from "./gloas.js";
 export * from "./interop.js";
 export * from "./loadState/index.js";
 export * from "./pendingDepositsLookup.js";
+export * from "./preVerifyBuilderDeposits.js";
 export * from "./rootCache.js";
 export * from "./seed.js";
 export * from "./shuffling.js";

package/src/util/pendingDepositsLookup.ts

@@ -1,8 +1,7 @@
 import {BeaconConfig} from "@lodestar/config";
 import {PubkeyHex, electra} from "@lodestar/types";
-import {toPubkeyHex} from "@lodestar/utils";
 import {isValidDepositSignature} from "../block/processDeposit.js";
-import {CachedBeaconStateGloas} from "../types.js";
+import {BuilderDepositSignatureCache} from "../cache/builderDepositSignatureCache.js";
 
 type PendingDepositsValidation = {
   hasValidSignature: boolean;
@@ -34,28 +33,14 @@ export class PendingDepositsLookup {
   }
 
   /**
-   * Build a pubkey -> pending-deposits lookup from `state.pendingDeposits`.
-   * No BLS work is done here; signature verification happens lazily in `hasPendingValidator`.
+   * Append a pending deposit to the represented sequence, keyed by its (precomputed) `pubkeyHex`.
    */
-  static build(state: CachedBeaconStateGloas): PendingDepositsLookup {
-    const lookup = PendingDepositsLookup.buildEmpty();
-    for (const pendingDeposit of state.pendingDeposits.getAllReadonly()) {
-      lookup.add(pendingDeposit);
-    }
-    return lookup;
-  }
-
-  /**
-   * Append a pending deposit to the represented sequence.
-   * Pass `pubkeyHex` if the caller has already computed it.
-   */
-  add(pendingDeposit: electra.PendingDeposit, pubkeyHex?: PubkeyHex): void {
-    const key = pubkeyHex ?? toPubkeyHex(pendingDeposit.pubkey);
-    const existing = this.depositsByPubkey.get(key);
+  add(pendingDeposit: electra.PendingDeposit, pubkeyHex: PubkeyHex): void {
+    const existing = this.depositsByPubkey.get(pubkeyHex);
     if (existing) {
       existing.push(pendingDeposit);
     } else {
-      this.depositsByPubkey.set(key, [pendingDeposit]);
+      this.depositsByPubkey.set(pubkeyHex, [pendingDeposit]);
     }
   }
 
@@ -63,8 +48,11 @@ export class PendingDepositsLookup {
    * Returns true if any pending deposit for `pubkeyHex` has a valid BLS deposit signature.
    * Memoizes the result in `validationCache` so repeated checks for the same pubkey
    * within a block only verify deposits that have not already been checked.
+   *
+   * Most of the time it should hit the BuilderDepositSignatureCache so we don't have to validate
+   * signatures here.
    */
-  hasPendingValidator(config: BeaconConfig, pubkeyHex: PubkeyHex): boolean {
+  hasPendingValidator(config: BeaconConfig, pubkeyHex: PubkeyHex, cache: BuilderDepositSignatureCache): boolean {
     const validation = this.validationCache.get(pubkeyHex);
     if (validation?.hasValidSignature === true) {
       return true;
@@ -85,15 +73,16 @@ export class PendingDepositsLookup {
 
     for (let i = startIndex; i < deposits.length; i++) {
       const deposit = deposits[i];
-      if (
+      const isValid =
+        cache.getSignatureValidity(deposit) ??
         isValidDepositSignature(
           config,
           deposit.pubkey,
           deposit.withdrawalCredentials,
           deposit.amount,
           deposit.signature
-        )
-      ) {
+        );
+      if (isValid) {
         this.validationCache.set(pubkeyHex, {hasValidSignature: true, validatedCount: i + 1});
         return true;
       }

package/src/util/preVerifyBuilderDeposits.ts

@@ -0,0 +1,153 @@
+import {electra} from "@lodestar/types";
+import {toPubkeyHex} from "@lodestar/utils";
+import {verifyDepositSignatures} from "../block/processDeposit.js";
+import {CachedBeaconStateFulu} from "../types.js";
+import {isBuilderWithdrawalCredential} from "./gloas.js";
+
+/** Verify queued deposit signatures in batches of this size. Also the time-box granularity: the
+ *  deadline is checked once per batch, so overrun is bounded to a single batch. Exported for tests. */
+export const BUILDER_DEPOSIT_BATCH_SIZE = 32;
+
+/**
+ * Per-tick cap on builder deposits the prepareForNextSlot scanner will verify.
+ * ~2.7s for 10_000 BLS verifications on a typical server — fits within the slot budget while the
+ * pre-window (see GLOAS_PREVERIFY_WINDOW_EPOCHS) covers up to ~620k deposits over its duration.
+ */
+export const MAX_BUILDER_DEPOSITS_PER_SLOT = 10_000;
+
+/**
+ * Number of epochs before GLOAS_FORK_EPOCH during which the prepareForNextSlot scanner pre-verifies
+ * builder-deposit signatures. Two: deposits arriving this late cannot collude with validator
+ * deposits — validator-vs-builder routing is decided at the fork boundary from what is already in
+ * pendingDeposits, so anything submitted inside this window is unambiguous.
+ */
+export const GLOAS_PREVERIFY_WINDOW_EPOCHS = 2;
+
+/**
+ * Summary of a single `preVerifyBuilderDepositsPreGloas` call.
+ */
+export type PreVerifyBuilderDepositsResult = {
+  /** Builder-prefix deposit signatures verified valid in this call (cached true). */
+  validBuilderSignaturesCount: number;
+  /** Builder-prefix deposit signatures verified invalid in this call (cached false, dropped at fork). */
+  invalidBuilderSignaturesCount: number;
+  /** Validator (builder-pubkey) deposit signatures verified valid in this call. */
+  validValidatorSignaturesCount: number;
+  /** Validator (builder-pubkey) deposit signatures verified invalid in this call (abuse signal). */
+  invalidValidatorSignaturesCount: number;
+  /** Pending deposits examined this call (all creds; < pendingDepositsCount ⇒ per-tick cap hit). */
+  scannedPendingDeposits: number;
+  /** Cumulative deposits verified & cached so far this window (cache size, pass + fail). */
+  totalCachedDeposits: number;
+  /** Distinct builder pubkeys tracked so far this window. */
+  totalBuilderPubkeys: number;
+  /** Current `state.pendingDeposits.length` — the full backlog. */
+  pendingDepositsCount: number;
+};
+
+/**
+ * Scanner driven by `prepareForNextSlot` over the `GLOAS_PREVERIFY_WINDOW_EPOCHS` epochs before
+ * GLOAS_FORK_EPOCH. Walks `state.pendingDeposits` (as struct values via getAllReadonlyValues) and
+ * queues, for signature verification, the deposits the fork transition will check on its hot path:
+ *   - builder-prefix deposits (for onboarding); records each builder pubkey on the cache, and
+ *   - validator deposits sharing a builder pubkey (the set `hasPendingValidator` walks at the fork),
+ *     but only until one is found valid — `hasPendingValidator` stops at the first valid signature, so
+ *     the cache marks the pubkey and the scanner skips that pubkey's remaining validator deposits.
+ *
+ * Bounded by two knobs: at most `maxBuilderDeposits` new deposits are queued per call, and the chunk
+ * verification is **time-boxed** to `maxDurationMs`.
+ */
+export function preVerifyBuilderDepositsPreGloas(
+  state: CachedBeaconStateFulu,
+  maxBuilderDeposits: number,
+  maxDurationMs: number
+): PreVerifyBuilderDepositsResult {
+  const cache = state.epochCtx.builderDepositSignatureCache;
+
+  // Collect uncached deposits to verify as struct values. Full rescan each tick: iteration is
+  // O(pendingDeposits) but runs in prepareNextSlot spare time, and isVerified() is an O(1) skip for
+  // already-cached deposits. For a ContainerNodeStructType, getAllReadonlyValues() returns each
+  // node.value by reference — the stable cache key.
+  const queue: electra.PendingDeposit[] = [];
+  let scannedPendingDeposits = 0;
+  for (const deposit of state.pendingDeposits.getAllReadonlyValues()) {
+    if (queue.length >= maxBuilderDeposits) break; // per-tick cap; next tick resumes via isVerified()
+    scannedPendingDeposits++;
+    if (cache.isVerified(deposit)) continue; // already verified in an earlier tick
+
+    if (isBuilderWithdrawalCredential(deposit.withdrawalCredentials)) {
+      // Record the builder pubkey so validator deposits sharing it get pre-verified — this or a
+      // later tick, since those validator deposits precede the builder deposit in the queue. A cached
+      // builder deposit already added its pubkey, so it's safe to skip via the `continue` above.
+      cache.addBuilderPubkey(toPubkeyHex(deposit.pubkey));
+      queue.push(deposit);
+    } else {
+      // Validator deposit — pre-verify only if it shares a builder pubkey (the set hasPendingValidator
+      // walks at the fork) AND we haven't already cached a valid validator deposit for that pubkey.
+      // this is the same logic to hasPendingValidator.
+      const pubkeyHex = toPubkeyHex(deposit.pubkey);
+      if (cache.isBuilderPubkey(pubkeyHex) && !cache.hasValidValidatorDeposit(pubkeyHex)) {
+        queue.push(deposit);
+      }
+    }
+  }
+
+  const pendingDepositsCount = state.pendingDeposits.length;
+  if (queue.length === 0) {
+    return {
+      validBuilderSignaturesCount: 0,
+      invalidBuilderSignaturesCount: 0,
+      validValidatorSignaturesCount: 0,
+      invalidValidatorSignaturesCount: 0,
+      scannedPendingDeposits,
+      totalCachedDeposits: cache.cachedDepositCount,
+      totalBuilderPubkeys: cache.builderPubkeyCount,
+      pendingDepositsCount,
+    };
+  }
+
+  // Verify in chunks; chunking caps the fallback blast radius so one bad signature only forces 32
+  // individual re-verifications. Key each result by the deposit value object. Counts are tracked
+  // incrementally (not queue.length - verified) so they stay correct when we time-box out early.
+  const deadline = Date.now() + maxDurationMs;
+  let validBuilderSignaturesCount = 0;
+  let invalidBuilderSignaturesCount = 0;
+  let validValidatorSignaturesCount = 0;
+  let invalidValidatorSignaturesCount = 0;
+  for (let chunkStart = 0; chunkStart < queue.length; chunkStart += BUILDER_DEPOSIT_BATCH_SIZE) {
+    const end = Math.min(chunkStart + BUILDER_DEPOSIT_BATCH_SIZE, queue.length);
+    const chunk = queue.slice(chunkStart, end);
+    const chunkResults = verifyDepositSignatures(state.epochCtx.config, chunk);
+    for (let j = 0; j < chunk.length; j++) {
+      cache.setSignatureValidity(chunk[j], chunkResults[j]);
+      const isBuilder = isBuilderWithdrawalCredential(chunk[j].withdrawalCredentials);
+      if (chunkResults[j]) {
+        if (isBuilder) {
+          validBuilderSignaturesCount++;
+        } else {
+          validValidatorSignaturesCount++;
+          // A valid validator deposit satisfies hasPendingValidator() for this pubkey; stop
+          // pre-verifying its remaining validator deposits on later ticks.
+          cache.setValidValidatorDeposit(toPubkeyHex(chunk[j].pubkey));
+        }
+      } else if (isBuilder) {
+        invalidBuilderSignaturesCount++;
+      } else {
+        invalidValidatorSignaturesCount++;
+      }
+    }
+    // Time-box: keep everything verified so far (already cached) and stop
+    if (Date.now() >= deadline) break;
+  }
+
+  return {
+    validBuilderSignaturesCount,
+    invalidBuilderSignaturesCount,
+    validValidatorSignaturesCount,
+    invalidValidatorSignaturesCount,
+    scannedPendingDeposits,
+    totalCachedDeposits: cache.cachedDepositCount,
+    totalBuilderPubkeys: cache.builderPubkeyCount,
+    pendingDepositsCount,
+  };
+}