@lodestar/state-transition 1.46.0-dev.2063820a22 → 1.46.0-dev.20c6ad786e

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)) {

package/src/util/weakSubjectivity.ts

@@ -1,10 +1,12 @@
 import {BeaconConfig, ChainForkConfig} from "@lodestar/config";
 import {
   EFFECTIVE_BALANCE_INCREMENT,
+  ForkSeq,
   MAX_DEPOSITS,
   MAX_EFFECTIVE_BALANCE,
   SLOTS_PER_EPOCH,
   isForkPostElectra,
+  isForkPostGloas,
 } from "@lodestar/params";
 import {Epoch, Root, ssz} from "@lodestar/types";
 import {Checkpoint} from "@lodestar/types/phase0";
@@ -14,10 +16,14 @@ import {BeaconStateAllForks, CachedBeaconStateAllForks} from "../types.js";
 import {computeCheckpointEpochAtStateSlot, computeEpochAtSlot, getCurrentEpoch} from "./epoch.js";
 import {getCurrentSlot} from "./slot.js";
 import {
+  getActivationChurnLimit,
   getActiveValidatorIndices,
   getBalanceChurnLimit,
   getBalanceChurnLimitFromCache,
   getChurnLimit,
+  getConsolidationChurnLimit,
+  getExitChurnLimit,
+  getGloasChurnLimits,
 } from "./validator.js";
 
 export const ETH_TO_GWEI = 10 ** 9;
@@ -49,18 +55,26 @@ export function computeWeakSubjectivityPeriodCachedState(
   const activeValidatorCount = state.epochCtx.currentShuffling.activeIndices.length;
   const fork = config.getForkName(state.slot);
 
-  return isForkPostElectra(fork)
-    ? computeWeakSubjectivityPeriodFromConstituentsElectra(
+  return isForkPostGloas(fork)
+    ? computeWeakSubjectivityPeriodFromConstituentsGloas(
         state.epochCtx.totalActiveBalanceIncrements,
-        getBalanceChurnLimitFromCache(state.epochCtx),
+        getExitChurnLimit(state.epochCtx),
+        getActivationChurnLimit(state.epochCtx),
+        getConsolidationChurnLimit(ForkSeq.gloas, state.epochCtx),
         config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
       )
-    : computeWeakSubjectivityPeriodFromConstituentsPhase0(
-        activeValidatorCount,
-        state.epochCtx.totalActiveBalanceIncrements,
-        getChurnLimit(config, activeValidatorCount),
-        config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
-      );
+    : isForkPostElectra(fork)
+      ? computeWeakSubjectivityPeriodFromConstituentsElectra(
+          state.epochCtx.totalActiveBalanceIncrements,
+          getBalanceChurnLimitFromCache(state.epochCtx),
+          config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
+        )
+      : computeWeakSubjectivityPeriodFromConstituentsPhase0(
+          activeValidatorCount,
+          state.epochCtx.totalActiveBalanceIncrements,
+          getChurnLimit(config, activeValidatorCount),
+          config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
+        );
 }
 
 /**
@@ -80,22 +94,32 @@ export function computeWeakSubjectivityPeriod(config: ChainForkConfig, state: Be
     totalActiveBalanceIncrements = 1;
   }
 
-  return isForkPostElectra(fork)
-    ? computeWeakSubjectivityPeriodFromConstituentsElectra(
+  const churnLimitsGloas = getGloasChurnLimits(config, totalActiveBalanceIncrements);
+
+  return isForkPostGloas(fork)
+    ? computeWeakSubjectivityPeriodFromConstituentsGloas(
         totalActiveBalanceIncrements,
-        getBalanceChurnLimit(
-          totalActiveBalanceIncrements,
-          config.CHURN_LIMIT_QUOTIENT,
-          config.MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA
-        ),
+        churnLimitsGloas.exit,
+        churnLimitsGloas.activation,
+        churnLimitsGloas.consolidation,
         config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
       )
-    : computeWeakSubjectivityPeriodFromConstituentsPhase0(
-        activeIndices.length,
-        totalActiveBalanceIncrements,
-        getChurnLimit(config, activeIndices.length),
-        config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
-      );
+    : isForkPostElectra(fork)
+      ? computeWeakSubjectivityPeriodFromConstituentsElectra(
+          totalActiveBalanceIncrements,
+          getBalanceChurnLimit(
+            totalActiveBalanceIncrements,
+            config.CHURN_LIMIT_QUOTIENT,
+            config.MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA
+          ),
+          config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
+        )
+      : computeWeakSubjectivityPeriodFromConstituentsPhase0(
+          activeIndices.length,
+          totalActiveBalanceIncrements,
+          getChurnLimit(config, activeIndices.length),
+          config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
+        );
 }
 
 export function computeWeakSubjectivityPeriodFromConstituentsPhase0(
@@ -142,6 +166,21 @@ export function computeWeakSubjectivityPeriodFromConstituentsElectra(
   return minWithdrawabilityDelay + epochsForValidatorSetChurn;
 }
 
+export function computeWeakSubjectivityPeriodFromConstituentsGloas(
+  totalBalanceByIncrement: number,
+  exitChurnLimit: number,
+  activationChurnLimit: number,
+  consolidationChurnLimit: number,
+  minWithdrawabilityDelay: number
+): number {
+  // Keep t as increment for now. Multiply final result by EFFECTIVE_BALANCE_INCREMENT
+  const t = totalBalanceByIncrement;
+  const delta = Math.floor((2 * exitChurnLimit) / 3) + Math.floor(activationChurnLimit / 3) + consolidationChurnLimit;
+  const epochsForValidatorSetChurn = Math.floor(((SAFETY_DECAY * t) / (2 * delta * 100)) * EFFECTIVE_BALANCE_INCREMENT);
+
+  return minWithdrawabilityDelay + epochsForValidatorSetChurn;
+}
+
 export function getLatestBlockRoot(state: BeaconStateAllForks): Root {
   const header = ssz.phase0.BeaconBlockHeader.clone(state.latestBlockHeader);
   if (ssz.Root.equals(header.stateRoot, ZERO_HASH)) {