@lodestar/state-transition 1.46.0-dev.1cd9a671ea → 1.46.0-dev.1dde9abaa6

package/src/util/clock.ts

@@ -0,0 +1,183 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {GENESIS_SLOT, SLOTS_PER_EPOCH} from "@lodestar/params";
+import {Epoch, Slot, TimeSeconds} from "@lodestar/types";
+import {ErrorAborted, Logger, isErrorAborted, sleep} from "@lodestar/utils";
+import {computeEpochAtSlot} from "./epoch.js";
+import {computeTimeAtSlot, getCurrentSlot} from "./slot.js";
+
+type RunEveryFn = (slot: Slot, signal: AbortSignal) => Promise<void>;
+
+export type ClockOptions = {
+  skipSlots?: boolean;
+};
+
+export interface IClock {
+  readonly genesisTime: number;
+  readonly secondsPerSlot: number;
+
+  readonly currentEpoch: number;
+
+  start(signal: AbortSignal): void;
+  runEverySlot(fn: (slot: Slot, signal: AbortSignal) => Promise<void>): void;
+  runEveryEpoch(fn: (epoch: Epoch, signal: AbortSignal) => Promise<void>): void;
+  msToSlot(slot: Slot): number;
+  msFromSlot(slot: Slot): number;
+  secFromSlot(slot: Slot): number;
+  getCurrentSlot(): Slot;
+  getCurrentEpoch(): Epoch;
+}
+
+export enum TimeItem {
+  Slot,
+  Epoch,
+}
+
+export class Clock implements IClock {
+  readonly genesisTime: number;
+  readonly secondsPerSlot: number;
+  private readonly config: ChainForkConfig;
+  private readonly logger: Logger;
+  private readonly fns: {timeItem: TimeItem; fn: RunEveryFn}[] = [];
+
+  constructor(
+    config: ChainForkConfig,
+    logger: Logger,
+    private readonly opts: {genesisTime: number} & ClockOptions
+  ) {
+    this.genesisTime = opts.genesisTime;
+    this.secondsPerSlot = config.SLOT_DURATION_MS / 1000;
+    this.config = config;
+    this.logger = logger;
+  }
+
+  get currentEpoch(): Epoch {
+    return computeEpochAtSlot(getCurrentSlot(this.config, this.genesisTime));
+  }
+
+  start(signal: AbortSignal): void {
+    for (const {timeItem, fn} of this.fns) {
+      this.runAtMostEvery(timeItem, signal, fn).catch((e: Error) => {
+        if (!isErrorAborted(e)) {
+          this.logger.error("runAtMostEvery", {}, e);
+        }
+      });
+    }
+  }
+
+  getCurrentSlot(): Slot {
+    return getCurrentSlot(this.config, this.genesisTime);
+  }
+
+  getCurrentEpoch(): Epoch {
+    return computeEpochAtSlot(getCurrentSlot(this.config, this.genesisTime));
+  }
+
+  runEverySlot(fn: RunEveryFn): void {
+    this.fns.push({timeItem: TimeItem.Slot, fn});
+  }
+
+  runEveryEpoch(fn: RunEveryFn): void {
+    this.fns.push({timeItem: TimeItem.Epoch, fn});
+  }
+
+  /** Milliseconds from now to a specific slot */
+  msToSlot(slot: Slot): number {
+    return computeTimeAtSlot(this.config, slot, this.genesisTime) * 1000 - Date.now();
+  }
+
+  /** Milliseconds elapsed from a specific slot to now */
+  msFromSlot(slot: Slot): number {
+    return Date.now() - computeTimeAtSlot(this.config, slot, this.genesisTime) * 1000;
+  }
+
+  /** Seconds elapsed from a specific slot to now */
+  secFromSlot(slot: Slot): number {
+    return Date.now() / 1000 - computeTimeAtSlot(this.config, slot, this.genesisTime);
+  }
+
+  /**
+   * If a task happens to take more than one slot to run, we might skip a slot. This is unfortunate,
+   * however the alternative is to *always* process every slot, which has the chance of creating a
+   * theoretically unlimited backlog of tasks. It was a conscious decision to choose to drop tasks
+   * on an overloaded/latent system rather than overload it even more.
+   */
+  private async runAtMostEvery(timeItem: TimeItem, signal: AbortSignal, fn: RunEveryFn): Promise<void> {
+    // Run immediately first
+    let slot = getCurrentSlot(this.config, this.genesisTime);
+    let slotOrEpoch = timeItem === TimeItem.Slot ? slot : computeEpochAtSlot(slot);
+    while (!signal.aborted) {
+      // Must catch fn() to ensure `sleep()` is awaited both for resolve and reject
+      const task = fn(slotOrEpoch, signal).catch((e: Error) => {
+        if (!isErrorAborted(e)) this.logger.error("Error on runEvery fn", {}, e);
+      });
+
+      if (timeItem !== TimeItem.Slot || this.opts.skipSlots !== false) {
+        // await response to only continue with next task if current task finished within slot
+        await task;
+      }
+
+      try {
+        await sleep(this.timeUntilNext(timeItem), signal);
+        // calling getCurrentSlot here may not be correct when we're close to the next slot
+        // it's safe to call getCurrentSlotAround after we sleep
+        const nextSlot = getCurrentSlotAround(this.config, this.genesisTime);
+
+        if (timeItem === TimeItem.Slot) {
+          if (nextSlot > slot + 1) {
+            // It's not very likely that we skip more than one slot as HTTP timeout is set
+            // to SLOT_DURATION_MS so we will fail task before skipping another slot.
+            this.logger.warn("Skipped slot due to task taking more than one slot to run", {
+              skippedSlot: slot + 1,
+            });
+          }
+          slotOrEpoch = nextSlot;
+        } else {
+          slotOrEpoch = computeEpochAtSlot(nextSlot);
+        }
+        slot = nextSlot;
+      } catch (e) {
+        if (e instanceof ErrorAborted) {
+          return;
+        }
+        throw e;
+      }
+    }
+  }
+
+  private timeUntilNext(timeItem: TimeItem): number {
+    const milliSecondsPerSlot = this.config.SLOT_DURATION_MS;
+    const msFromGenesis = Date.now() - this.genesisTime * 1000;
+
+    if (timeItem === TimeItem.Slot) {
+      if (msFromGenesis >= 0) {
+        return milliSecondsPerSlot - (msFromGenesis % milliSecondsPerSlot);
+      }
+      return Math.abs(msFromGenesis) % milliSecondsPerSlot;
+    }
+    const milliSecondsPerEpoch = SLOTS_PER_EPOCH * milliSecondsPerSlot;
+    if (msFromGenesis >= 0) {
+      return milliSecondsPerEpoch - (msFromGenesis % milliSecondsPerEpoch);
+    }
+    return Math.abs(msFromGenesis) % milliSecondsPerEpoch;
+  }
+}
+
+/**
+ * Same to the spec but we use Math.round instead of Math.floor.
+ */
+export function getCurrentSlotAround(config: ChainForkConfig, genesisTime: TimeSeconds): Slot {
+  const diffInSeconds = Date.now() / 1000 - genesisTime;
+  const slotsSinceGenesis = Math.round((diffInSeconds * 1000) / config.SLOT_DURATION_MS);
+  return GENESIS_SLOT + slotsSinceGenesis;
+}
+
+// function useEventStream() {
+//   this.stream = this.events.getEventStream([BeaconEventType.BLOCK, BeaconEventType.HEAD, BeaconEventType.CHAIN_REORG]);
+//   pipeToEmitter(this.stream, this).catch((e: Error) => {
+//     this.logger.error("Error on stream pipe", {}, e);
+//   });
+
+//   // On stop
+//   this.stream.stop();
+//   this.stream = null;
+// }

package/src/util/deposit.ts

@@ -4,19 +4,21 @@ import {CachedBeaconStateAllForks, CachedBeaconStateElectra} from "../types.js";
 
 export function getEth1DepositCount(state: CachedBeaconStateAllForks, eth1Data?: phase0.Eth1Data): UintNum64 {
   const eth1DataToUse = eth1Data ?? state.eth1Data;
+  // Proposer can set any value, use in bigint until the result is bounded by MAX_DEPOSITS
+  const depositCount = eth1DataToUse.depositCount;
+  const eth1DepositIndex = BigInt(state.eth1DepositIndex);
+  const maxDeposits = BigInt(MAX_DEPOSITS);
   if (state.config.getForkSeq(state.slot) >= ForkSeq.electra) {
     const electraState = state as CachedBeaconStateElectra;
-    // eth1DataIndexLimit = min(UintNum64, UintBn64) can be safely casted as UintNum64
-    // since the result lies within upper and lower bound of UintNum64
-    const eth1DataIndexLimit: UintNum64 =
-      eth1DataToUse.depositCount < electraState.depositRequestsStartIndex
-        ? eth1DataToUse.depositCount
-        : Number(electraState.depositRequestsStartIndex);
+    const eth1DataIndexLimit =
+      depositCount < electraState.depositRequestsStartIndex ? depositCount : electraState.depositRequestsStartIndex;
 
-    if (state.eth1DepositIndex < eth1DataIndexLimit) {
-      return Math.min(MAX_DEPOSITS, eth1DataIndexLimit - state.eth1DepositIndex);
+    if (eth1DepositIndex < eth1DataIndexLimit) {
+      const available = eth1DataIndexLimit - eth1DepositIndex;
+      return Number(available < maxDeposits ? available : maxDeposits);
     }
     return 0;
   }
-  return Math.min(MAX_DEPOSITS, eth1DataToUse.depositCount - state.eth1DepositIndex);
+  const available = depositCount - eth1DepositIndex;
+  return Number(available < maxDeposits ? available : maxDeposits);
 }

package/src/util/genesis.ts

@@ -139,7 +139,7 @@ export function applyDeposits(
   const fullDepositDataRootArr = fullDepositDataRootList ? fullDepositDataRootList.getAllReadonlyValues() : null;
 
   if (fullDepositDataRootArr) {
-    const depositCount = state.eth1Data.depositCount;
+    const depositCount = Number(state.eth1Data.depositCount);
     for (let index = 0; index < depositCount; index++) {
       depositDataRootList.push(fullDepositDataRootArr[index]);
     }
@@ -160,7 +160,7 @@ export function applyDeposits(
       );
     }
 
-    state.eth1Data.depositCount += 1;
+    state.eth1Data.depositCount += 1n;
 
     const fork = config.getForkSeq(GENESIS_SLOT);
     processDeposit(fork, state, deposit);
@@ -334,6 +334,12 @@ export function initializeBeaconStateFromEth1(
     stateGloas.fork.currentVersion = config.GLOAS_FORK_VERSION;
   }
 
+  if (fork >= ForkSeq.heze) {
+    const stateHeze = state as CompositeViewDU<typeof ssz.heze.BeaconState>;
+    stateHeze.fork.previousVersion = config.HEZE_FORK_VERSION;
+    stateHeze.fork.currentVersion = config.HEZE_FORK_VERSION;
+  }
+
   state.commit();
 
   return state;

package/src/util/gloas.ts

@@ -87,15 +87,19 @@ export function isActiveBuilder(builder: gloas.Builder, finalizedEpoch: Epoch):
  * From https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md
  */
 export function getExpectedGasLimit(parentGasLimit: number, targetGasLimit: number): number {
-  const maxGasLimitDifference = Math.max(Math.floor(parentGasLimit / 1024), 1) - 1;
+  return Number(getExpectedGasLimitBigint(BigInt(parentGasLimit), BigInt(targetGasLimit)));
+}
+
+export function getExpectedGasLimitBigint(parentGasLimit: bigint, targetGasLimit: bigint): bigint {
+  const maxGasLimitDifference = (parentGasLimit / 1024n > 1n ? parentGasLimit / 1024n : 1n) - 1n;
 
   if (targetGasLimit > parentGasLimit) {
     const gasDiff = targetGasLimit - parentGasLimit;
-    return parentGasLimit + Math.min(gasDiff, maxGasLimitDifference);
+    return parentGasLimit + (gasDiff < maxGasLimitDifference ? gasDiff : maxGasLimitDifference);
   }
 
   const gasDiff = parentGasLimit - targetGasLimit;
-  return parentGasLimit - Math.min(gasDiff, maxGasLimitDifference);
+  return parentGasLimit - (gasDiff < maxGasLimitDifference ? gasDiff : maxGasLimitDifference);
 }
 
 /**
@@ -104,8 +108,8 @@ export function getExpectedGasLimit(parentGasLimit: number, targetGasLimit: numb
  * adjustment step of the parent, otherwise it must hit the clamped boundary.
  * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.8/specs/gloas/builder.md#new-is_gas_limit_target_compatible
  */
-export function isGasLimitTargetCompatible(parentGasLimit: number, gasLimit: number, targetGasLimit: number): boolean {
-  return gasLimit === getExpectedGasLimit(parentGasLimit, targetGasLimit);
+export function isGasLimitTargetCompatible(parentGasLimit: bigint, gasLimit: bigint, targetGasLimit: bigint): boolean {
+  return gasLimit === getExpectedGasLimitBigint(parentGasLimit, targetGasLimit);
 }
 
 /**

package/src/util/index.ts

@@ -6,6 +6,7 @@ export * from "./balance.js";
 export * from "./blindedBlock.js";
 export * from "./blockRoot.js";
 export * from "./capella.js";
+export * from "./clock.js";
 export * from "./computeAnchorCheckpoint.js";
 export * from "./deposit.js";
 export * from "./domain.js";
@@ -19,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/loadState/loadState.ts

@@ -25,10 +25,29 @@ export function loadState(
 ): MigrateStateOutput {
   // casting only to make typescript happy
   const stateType = getStateTypeFromBytes(config, stateBytes) as typeof ssz.capella.BeaconState;
+  const fork = getForkFromStateBytes(config, stateBytes);
+  const seedFork = config.getForkSeq(seedState.slot);
+
   const dataView = new DataView(stateBytes.buffer, stateBytes.byteOffset, stateBytes.byteLength);
   const fieldRanges = stateType.getFieldRanges(dataView, 0, stateBytes.length);
   const allFields = Object.keys(stateType.fields);
   const validatorsFieldIndex = allFields.indexOf("validators");
+  const validatorsRange = fieldRanges[validatorsFieldIndex];
+  const newValidatorsBytes = stateBytes.subarray(validatorsRange.start, validatorsRange.end);
+
+  // EIP-7688 replaces List with ProgressiveList for validators and inactivityScores at gloas,
+  // changing the merkle tree shape. Seed nodes cannot be reused when one state is pre-gloas
+  // and the other post-gloas.
+  const crossesGloasFork =
+    (fork >= ForkSeq.gloas && seedFork < ForkSeq.gloas) || (fork < ForkSeq.gloas && seedFork >= ForkSeq.gloas);
+  if (crossesGloasFork) {
+    const migratedState = stateType.deserializeToViewDU(stateBytes) as BeaconStateAllForks;
+    // modified validators must still be reported so that the pubkey cache is refreshed for
+    // any index that differs from the seed state, which may not be an ancestor of this state
+    const modifiedValidators = findModifiedAndAppendedValidators(seedState, newValidatorsBytes, seedValidatorsBytes);
+    return {state: migratedState, modifiedValidators};
+  }
+
   // start with default view has the same performance to start with seed state
   // and it is not fork dependent
   const migratedState = deserializeContainerIgnoreFields(
@@ -39,19 +58,10 @@ export function loadState(
   ) as BeaconStateAllForks;
 
   // validators are rarely changed
-  const validatorsRange = fieldRanges[validatorsFieldIndex];
-  const modifiedValidators = loadValidators(
-    migratedState,
-    seedState,
-    stateBytes.subarray(validatorsRange.start, validatorsRange.end),
-    seedValidatorsBytes
-  );
+  const modifiedValidators = loadValidators(migratedState, seedState, newValidatorsBytes, seedValidatorsBytes);
 
   // inactivityScores are rarely changed
   // this saves ~500ms of hashTreeRoot() time of state
-  const fork = getForkFromStateBytes(config, stateBytes);
-  const seedFork = config.getForkSeq(seedState.slot);
-
   if (fork >= ForkSeq.altair && seedFork >= ForkSeq.altair) {
     const inactivityScoresIndex = allFields.indexOf("inactivityScores");
     const inactivityScoresRange = fieldRanges[inactivityScoresIndex];
@@ -141,7 +151,9 @@ function loadInactivityScores(
     }
   } else {
     if (newValidator - 1 < 0) {
-      migratedState.inactivityScores = ssz.altair.InactivityScores.defaultViewDU();
+      // use the state's own field type, the list shape differs between altair (List) and gloas (ProgressiveList)
+      const inactivityScoresType = (migratedState.type as typeof ssz.altair.BeaconState).fields.inactivityScores;
+      migratedState.inactivityScores = inactivityScoresType.defaultViewDU();
     } else {
       migratedState.inactivityScores = migratedState.inactivityScores.sliceTo(newValidator - 1);
     }
@@ -177,6 +189,33 @@ function loadInactivityScores(
  * @param migratedState state to be migrated, the validators are loaded to this state
  * @returns modified validator indices
  */
+/**
+ * Find indices of validators whose serialized bytes differ from the seed state, plus indices
+ * appended past the seed state's validator count. Unlike loadValidators() this only diffs
+ * bytes and does not share the seed state's tree.
+ */
+function findModifiedAndAppendedValidators(
+  seedState: BeaconStateAllForks,
+  newValidatorsBytes: Uint8Array,
+  seedStateValidatorsBytes?: Uint8Array
+): number[] {
+  const seedValidatorCount = seedState.validators.length;
+  const newValidatorCount = Math.floor(newValidatorsBytes.length / VALIDATOR_BYTES_SIZE);
+  const minValidatorCount = Math.min(seedValidatorCount, newValidatorCount);
+  const seedValidatorsBytes = seedStateValidatorsBytes ?? seedState.validators.serialize();
+  const modifiedValidators: number[] = [];
+  findModifiedValidators(
+    seedValidatorsBytes.subarray(0, minValidatorCount * VALIDATOR_BYTES_SIZE),
+    newValidatorsBytes.subarray(0, minValidatorCount * VALIDATOR_BYTES_SIZE),
+    modifiedValidators
+  );
+
+  for (let validatorIndex = seedValidatorCount; validatorIndex < newValidatorCount; validatorIndex++) {
+    modifiedValidators.push(validatorIndex);
+  }
+  return modifiedValidators;
+}
+
 function loadValidators(
   migratedState: BeaconStateAllForks,
   seedState: BeaconStateAllForks,

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,
+  };
+}

package/src/util/ssz.ts

@@ -1,7 +1,7 @@
 import {BranchNode, LeafNode, Node, zeroNode} from "@chainsafe/persistent-merkle-tree";
 import {progressiveSubtreeFillToContents} from "@chainsafe/ssz";
 
-// TODO: move these utils to @chainsafe/ssz (progressive.ts, next to progressiveSubtreeFillToContents)
+// TODO: move these utils to @chainsafe/ssz, see https://github.com/ChainSafe/ssz/issues/542
 
 /** Root node (chunks + length mix-in) of a zero-filled ProgressiveListBasicType of `length` items */
 export function zeroProgressiveListBasicRootNode(itemsPerChunk: number, length: number): Node {
@@ -15,6 +15,14 @@ export function zeroProgressiveListBasicRootNode(itemsPerChunk: number, length:
   return new BranchNode(zeroProgressiveNode(numSubtrees), LeafNode.fromUint32(length));
 }
 
+/**
+ * Check if an array-type ViewDU (ListBasic, ListComposite or their progressive equivalents) has its
+ * internal nodes cache populated. The flag is a private attribute maintained by all of these classes.
+ */
+export function isViewDUNodesPopulated(view: unknown): boolean {
+  return (view as {nodesPopulated?: boolean}).nodesPopulated === true;
+}
+
 /**
  * Root node of a progressive list from its chunk/element nodes + length mix-in.
  * `nodes` are packed 32-byte chunk leaves for basic lists, or element root nodes for composite lists.

package/src/util/validator.ts

@@ -128,6 +128,23 @@ export function getConsolidationChurnLimit(fork: ForkSeq, epochCtx: EpochCache):
   return getBalanceChurnLimitFromCache(epochCtx) - getActivationExitChurnLimit(epochCtx);
 }
 
+// NOTE: duplicates the quotient/min choices in get{Exit,Activation,Consolidation}ChurnLimit.
+export function getGloasChurnLimits(
+  config: ChainForkConfig,
+  totalActiveBalanceIncrements: number
+): {exit: number; activation: number; consolidation: number} {
+  const exit = getBalanceChurnLimit(
+    totalActiveBalanceIncrements,
+    config.CHURN_LIMIT_QUOTIENT_GLOAS,
+    config.MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA
+  );
+  return {
+    exit,
+    activation: Math.min(config.MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT_GLOAS, exit),
+    consolidation: getBalanceChurnLimit(totalActiveBalanceIncrements, config.CONSOLIDATION_CHURN_LIMIT_QUOTIENT, 0),
+  };
+}
+
 export function getMaxEffectiveBalance(withdrawalCredentials: Uint8Array): number {
   // Compounding withdrawal credential only available since Electra
   if (hasCompoundingWithdrawalCredential(withdrawalCredentials)) {