@lodestar/beacon-node 1.46.0 → 1.47.0-dev.02d2dbea03

package/src/chain/stateCache/persistentCheckpointsCache.ts

@@ -14,7 +14,11 @@ import {BlockStateCache, CacheItemType, CheckpointHex, CheckpointStateCache} fro
 export type PersistentCheckpointStateCacheOpts = {
   /** Keep max n state epochs in memory, persist the rest to disk */
   maxCPStateEpochsInMemory?: number;
-  /** Keep max n state epochs on disk */
+  /**
+   * On-disk retention of persisted checkpoint states. Selects one of two modes:
+   * - `Infinity` (default) -> tiered retention mode
+   * - any finite `n` (>= 0) -> legacy flat retention (keep the last n dense epochs)
+   */
   maxCPStateEpochsOnDisk?: number;
 };
 
@@ -64,6 +68,18 @@ export const DEFAULT_MAX_CP_STATE_EPOCHS_IN_MEMORY = 3;
  */
 export const DEFAULT_MAX_CP_STATE_ON_DISK = Infinity;
 
+// CP_STATE_TIER_BASE = spacing multiplier per tier AND per-tier capacity. Deciding capacity == base
+// so that a full tier[n] always holds exactly ONE epoch aligned to tier[n+1]
+// given tier[n] has span = 16 ^ n and tier[n+1] has span = 16 ^ (n+1)
+// why 16?
+//   - tier 0 is the dense hot-regen window; it must exceed regen's MAX_EPOCH_TO_PROCESS (=5).
+//   - with a full 4 tiers = 64 epochs, we can cover ~ a year of continuous non-finality, and it'll grow very slowly after that
+//     - tier0 spans 16 epochs ≈ 1.7h, this is more than enough to handle reorg
+//     - tier1 spans 256 epochs ≈ 1.1d, ie we store 16 epochs of the previous day
+//     - tier2 spans 4096 epochs ≈ 18d, ie we store 16 epochs of the last ~2.5 weeks
+//     - tier3 spans 65536ep ≈ 291d, ie we store 16 epochs of the last 0.8 year
+export const CP_STATE_TIER_BASE = 16;
+
 // TODO GLOAS: re-evaluate this timing
 const PROCESS_CHECKPOINT_STATES_BPS = 6667;
 
@@ -112,6 +128,19 @@ export class PersistentCheckpointStateCache implements CheckpointStateCache {
   private preComputedCheckpointHits: number | null = null;
   private readonly maxEpochsInMemory: number;
   private readonly maxEpochsOnDisk: number;
+  /**
+   * Persist checkpoint states (epoch + root) by tiers
+   *
+   *                   ╔═════════ tier 2 ══════════╦═══════ tier 1 ═══════╦═══ tier 0 (dense) ══╗
+   * finalizedEpoch -> ║  keep 1 epoch per 256     ║  keep 1 epoch per 16 ║  keep every epoch   ║ -> head
+   *                   ║  x·······x·······x······  ║  x···x···x···x···    ║  xxxxxxxxxxxxxxxxx  ║
+   *                   ╚═══════════════════════════╩══════════════════════╩═════════════════════╝
+   *
+   * starting from tier 1, all epochs must be aligned to the finalized epoch
+   */
+  private persistentTiers: Map<Epoch, Set<RootHex>>[] = [new Map()];
+  private finalizedEpoch: Epoch = 0;
+  private justifiedEpoch: Epoch = 0;
   private readonly datastore: CPStateDatastore;
   private readonly blockStateCache: BlockStateCache;
   private readonly bufferPool?: BufferPool;
@@ -152,6 +181,13 @@ export class PersistentCheckpointStateCache implements CheckpointStateCache {
         metrics.cpStateCache.size.set({type: CacheItemType.inMemory}, inMemoryCount);
         metrics.cpStateCache.epochSize.set({type: CacheItemType.persisted}, persistentEpochs.size);
         metrics.cpStateCache.epochSize.set({type: CacheItemType.inMemory}, memoryEpochs.size);
+
+        for (let tier = 0; tier < this.persistentTiers.length; tier++) {
+          let states = 0;
+          for (const roots of this.persistentTiers[tier].values()) states += roots.size;
+          metrics.cpStateCache.persistentTierEpochs.set({tier}, this.persistentTiers[tier].size);
+          metrics.cpStateCache.persistentTierStates.set({tier}, states);
+        }
       });
     }
     this.logger = logger;
@@ -407,10 +443,77 @@ export class PersistentCheckpointStateCache implements CheckpointStateCache {
   }
 
   /**
-   * This is just to conform to the old implementation
+   * This is called on every checkpoint event to refresh the pinned finalized/justified epochs.
    */
-  prune(): void {
-    // do nothing
+  onCheckpoint(finalizedEpoch: Epoch, justifiedEpoch: Epoch): void {
+    this.finalizedEpoch = finalizedEpoch;
+    this.justifiedEpoch = justifiedEpoch;
+  }
+
+  /**
+   * This is called right after we persist a checkpoint state.
+   */
+  private async onPersist(epoch: Epoch, rootHex: RootHex): Promise<void> {
+    let roots = this.persistentTiers[0].get(epoch);
+    if (roots === undefined) {
+      roots = new Set<RootHex>();
+      this.persistentTiers[0].set(epoch, roots);
+    }
+    roots.add(rootHex);
+    await this.prunePersistentTier(0);
+  }
+
+  /**
+   * When tier `n` overflows (> CP_STATE_TIER_BASE epochs), evict its oldest epoch and either promote it to tier `n + 1` (if aligned there) or delete it.
+   *
+   *   before:  persistentTiers[n]   = { ..., e_old }
+   *            persistentTiers[n+1] = { ... }
+   *
+   *   after, if e_old aligns to n+1:           |  after, if e_old does NOT align to n+1:
+   *     persistentTiers[n]   = { ... }         |    persistentTiers[n]   = { ... }
+   *     persistentTiers[n+1] = { ..., e_old }  |    e_old and all its roots deleted from disk
+   *
+   * Since pruning a tier[n] may push an item at tier[n+1], we must call the function recursively.
+   */
+  private async prunePersistentTier(tier: number): Promise<void> {
+    const tierMap = this.persistentTiers[tier];
+    while (tierMap.size > CP_STATE_TIER_BASE) {
+      // Evict the oldest epoch, but never the pinned justified epoch
+      const oldestEpoch = Math.min(...Array.from(tierMap.keys()).filter((epoch) => epoch !== this.justifiedEpoch));
+      const roots = tierMap.get(oldestEpoch) as Set<RootHex>;
+      tierMap.delete(oldestEpoch);
+
+      const rootHexes = Array.from(roots).join(",");
+      // `>= finalizedEpoch` guards the transient window where an epoch below the (fork-choice)
+      // finalized epoch has not yet been removed by pruneFinalized: its offset would be negative
+      // and JS `%` could spuriously report it as aligned. Such epochs are stale -> delete.
+      if (oldestEpoch >= this.finalizedEpoch && this.alignedForTier(oldestEpoch, tier + 1)) {
+        if (this.persistentTiers[tier + 1] === undefined) {
+          this.persistentTiers[tier + 1] = new Map<Epoch, Set<RootHex>>();
+        }
+        this.persistentTiers[tier + 1].set(oldestEpoch, roots);
+        this.logger.verbose("Migrated persistent checkpoint states to lower tier", {
+          epoch: oldestEpoch,
+          fromTier: tier,
+          toTier: tier + 1,
+          rootHexes,
+        });
+        await this.prunePersistentTier(tier + 1);
+      } else {
+        // the oldest epoch is not aligned to the next tier
+        await this.deleteAllEpochItems(oldestEpoch)
+          .then(() => this.logger.verbose("Pruned checkpoint states from disk", {epoch: oldestEpoch, tier, rootHexes}))
+          .catch((e) => this.logger.debug("Error delete all epoch items", {epoch: oldestEpoch, tier}, e as Error));
+      }
+    }
+  }
+
+  /**
+   * Starting from tier[1], it must be aligned to the finalized epoch
+   * ie given finalized epoch F, tier[n] only epochs of F + n*16, n = 1,2,3...
+   */
+  private alignedForTier(epoch: Epoch, tier: number): boolean {
+    return (epoch - this.finalizedEpoch) % CP_STATE_TIER_BASE ** tier === 0;
   }
 
   /**
@@ -598,9 +701,16 @@ export class PersistentCheckpointStateCache implements CheckpointStateCache {
     return seedBlockState;
   }
 
-  clear(): void {
-    this.cache.clear();
-    this.epochIndex.clear();
+  async clear(): Promise<void> {
+    // deleteAllEpochItems removes every root of an epoch from disk and clears the cache
+    await Promise.all(
+      Array.from(this.epochIndex.keys()).map((epoch) =>
+        this.deleteAllEpochItems(epoch).catch((e) =>
+          this.logger.debug("Error delete all epoch items on clear", {epoch}, e as Error)
+        )
+      )
+    );
+    this.persistentTiers = [new Map()];
   }
 
   /** ONLY FOR DEBUGGING PURPOSES. For lodestar debug API */
@@ -743,12 +853,18 @@ export class PersistentCheckpointStateCache implements CheckpointStateCache {
           }
           // overwrite cpKey, this means the state is deleted from memory
           this.cache.set(cpKey, {type: CacheItemType.persisted, value: persistedKey});
+          if (this.isTieredMode) {
+            await this.onPersist(epoch, rootHex);
+          }
         } else {
           if (persistedKey) {
             // persisted file will be eventually deleted by the archive task
             // this also means the state is deleted from memory
             this.cache.set(cpKey, {type: CacheItemType.persisted, value: persistedKey});
             // do not update epochIndex
+            if (this.isTieredMode) {
+              await this.onPersist(epoch, rootHex);
+            }
           } else {
             // delete the state from memory
             this.cache.delete(cpKey);
@@ -790,6 +906,10 @@ export class PersistentCheckpointStateCache implements CheckpointStateCache {
       this.cache.delete(key);
     }
     this.epochIndex.delete(epoch);
+    // keep the on-disk retention tiers in sync so they never drift from epochIndex
+    for (const tierMap of this.persistentTiers) {
+      tierMap.delete(epoch);
+    }
     this.logger.verbose("Pruned checkpoint states for epoch", {
       epoch,
       persistCount,
@@ -798,7 +918,7 @@ export class PersistentCheckpointStateCache implements CheckpointStateCache {
   }
 
   /**
-   * Prune persisted checkpoint states from disk.
+   * Legacy flat-window on-disk pruning, used only when a `maxEpochsOnDisk` is configured.
    * Note that this should handle all possible errors and not throw.
    */
   private prunePersistedStates(): void {
@@ -842,6 +962,11 @@ export class PersistentCheckpointStateCache implements CheckpointStateCache {
 
     return null;
   }
+
+  /** Tiered pruning is active with the default `Infinity` on-disk cap; a finite cap uses the flat path */
+  private get isTieredMode(): boolean {
+    return this.maxEpochsOnDisk === Infinity;
+  }
 }
 
 export function toCheckpointHex(checkpoint: phase0.Checkpoint): CheckpointHex {

package/src/chain/stateCache/types.ts

@@ -29,7 +29,7 @@ export interface BlockStateCache {
   getSeedState(): IBeaconStateView;
   clear(): void;
   size: number;
-  prune(headStateRootHex: RootHex): void;
+  onCheckpoint(headStateRootHex: RootHex): void;
   dumpSummary(): routes.lodestar.StateCacheItem[];
   /** Expose beacon states stored in cache. Use with caution */
   getStates(): IterableIterator<IBeaconStateView>;
@@ -65,9 +65,9 @@ export interface CheckpointStateCache {
   getLatest(rootHex: RootHex, maxEpoch: Epoch): IBeaconStateView | null;
   getOrReloadLatest(rootHex: RootHex, maxEpoch: Epoch): Promise<IBeaconStateView | null>;
   updatePreComputedCheckpoint(rootHex: RootHex, epoch: Epoch): number | null;
-  prune(finalizedEpoch: Epoch, justifiedEpoch: Epoch): void;
+  onCheckpoint(finalizedEpoch: Epoch, justifiedEpoch: Epoch): void;
   processState(blockRootHex: RootHex, state: IBeaconStateView): Promise<number>;
-  clear(): void;
+  clear(): Promise<void>;
   dumpSummary(): routes.lodestar.StateCacheItem[];
   /** Expose beacon states stored in cache. Use with caution */
   getStates(): IterableIterator<IBeaconStateView>;

package/src/chain/validation/attestation.ts

@@ -142,13 +142,7 @@ export async function validateGossipAttestationsSameAttData(
   const batchableBls = signatureSets.length >= chain.opts.minSameMessageSignatureSetsToBatch;
   if (batchableBls) {
     // all signature sets should have same signing root since we filtered in network processor
-    signatureValids = await chain.bls.verifySignatureSetsSameMessage(
-      signatureSets.map((set) => {
-        const publicKey = chain.pubkeyCache.getOrThrow(set.index);
-        return {publicKey, signature: set.signature};
-      }),
-      signatureSets[0].signingRoot
-    );
+    signatureValids = await chain.bls.verifySignatureSetsSameMessage(signatureSets, signatureSets[0].signingRoot);
   } else {
     // don't want to block the main thread if there are too few signatures
     signatureValids = await Promise.all(

package/src/chain/validation/attesterSlashing.ts

@@ -44,14 +44,7 @@ export async function validateAttesterSlashing(
   // [REJECT] All of the conditions within process_attester_slashing pass validation.
   try {
     // verifySignature = false, verified in batch below
-    assertValidAttesterSlashing(
-      chain.config,
-      chain.pubkeyCache,
-      state.slot,
-      state.validatorCount,
-      attesterSlashing,
-      false
-    );
+    assertValidAttesterSlashing(chain.config, state.slot, state.validatorCount, attesterSlashing, false);
   } catch (e) {
     throw new AttesterSlashingError(GossipAction.REJECT, {
       code: AttesterSlashingErrorCode.INVALID,

package/src/chain/validation/block.ts

@@ -89,13 +89,20 @@ export async function validateGossipBlock(
 
   // [IGNORE] The block is the first block with valid signature received for the proposer for the slot, signed_beacon_block.message.slot.
   const proposerIndex = block.proposerIndex;
-  const hasBlockRoot = chain.seenBlockProposers.hasBlockRoot(blockSlot, proposerIndex, blockRoot);
   if (chain.seenBlockProposers.isKnown(blockSlot, proposerIndex)) {
-    if (!hasBlockRoot && !chain.seenBlockProposers.isEquivocating(blockSlot, proposerIndex)) {
-      await verifyBlockProposerSignature(chain, signedBlock, blockRoot, {verifyOnMainThread: false});
-      chain.seenBlockProposers.observeBlockRoot(blockSlot, proposerIndex, blockRoot, signedBlockHeader);
+    if (chain.seenBlockProposers.isRepeatProposal(blockSlot, proposerIndex, blockRoot)) {
+      const hasBlockRoot = chain.seenBlockProposers.hasBlockRoot(blockSlot, proposerIndex, blockRoot);
+      if (!hasBlockRoot && !chain.seenBlockProposers.isEquivocating(blockSlot, proposerIndex)) {
+        await verifyBlockProposerSignature(chain, signedBlock, blockRoot, {verifyOnMainThread: false});
+        chain.seenBlockProposers.observeBlockRoot(blockSlot, proposerIndex, blockRoot, signedBlockHeader);
+      }
+      throw new BlockGossipError(GossipAction.IGNORE, {
+        code: BlockErrorCode.REPEAT_PROPOSAL,
+        proposerIndex,
+        root: blockRoot,
+      });
     }
-    throw new BlockGossipError(GossipAction.IGNORE, {code: BlockErrorCode.REPEAT_PROPOSAL, proposerIndex});
+    throw new BlockGossipError(GossipAction.IGNORE, {code: BlockErrorCode.ALREADY_KNOWN, root: blockRoot});
   }
 
   // [REJECT] The current finalized_checkpoint is an ancestor of block -- i.e.
@@ -301,10 +308,17 @@ export async function validateGossipBlock(
 
   // Check again after all async validation and the early-block delay so concurrent proposals cannot both pass
   if (chain.seenBlockProposers.isKnown(blockSlot, proposerIndex)) {
-    throw new BlockGossipError(GossipAction.IGNORE, {code: BlockErrorCode.REPEAT_PROPOSAL, proposerIndex});
+    if (chain.seenBlockProposers.isRepeatProposal(blockSlot, proposerIndex, blockRoot)) {
+      throw new BlockGossipError(GossipAction.IGNORE, {
+        code: BlockErrorCode.REPEAT_PROPOSAL,
+        proposerIndex,
+        root: blockRoot,
+      });
+    }
+    throw new BlockGossipError(GossipAction.IGNORE, {code: BlockErrorCode.ALREADY_KNOWN, root: blockRoot});
   }
 
-  chain.seenBlockProposers.add(blockSlot, proposerIndex);
+  chain.seenBlockProposers.add(blockSlot, proposerIndex, blockRoot);
 
   return {skippedSlots};
 }

package/src/chain/validation/executionPayloadBid.ts

@@ -1,4 +1,3 @@
-import {PublicKey} from "@chainsafe/blst";
 import {IForkChoice, ProtoBlock} from "@lodestar/fork-choice";
 import {PAYLOAD_BUILDER_VERSION} from "@lodestar/params";
 import {
@@ -345,7 +344,7 @@ async function validateExecutionPayloadBid(
 
   // [REJECT] `signed_execution_payload_bid.signature` is valid with respect to the `bid.builder_index`.
   const signatureSet = createSingleSignatureSetFromComponents(
-    PublicKey.fromBytes(builder.pubkey),
+    builder.pubkey,
     getExecutionPayloadBidSigningRoot(chain.config, bid),
     signedExecutionPayloadBid.signature
   );

package/src/chain/validation/executionPayloadEnvelope.ts

@@ -170,7 +170,6 @@ async function validateExecutionPayloadEnvelope(
   // by `verify_execution_payload_envelope_signature`.
   const signatureSet = getExecutionPayloadEnvelopeSignatureSet(
     chain.config,
-    chain.pubkeyCache,
     blockState,
     executionPayloadEnvelope,
     payloadInput.proposerIndex

package/src/chain/validation/payloadAttestationMessage.ts

@@ -1,6 +1,5 @@
 import {
-  computeEpochAtSlot,
-  createSingleSignatureSetFromComponents,
+  createIndexedSignatureSetFromComponents,
   getPayloadAttestationDataSigningRoot,
   isStatePostGloas,
 } from "@lodestar/state-transition";
@@ -36,7 +35,6 @@ async function validatePayloadAttestationMessage(
   prioritizeBls = false
 ): Promise<PayloadAttestationValidationResult> {
   const {data, validatorIndex} = payloadAttestationMessage;
-  const epoch = computeEpochAtSlot(data.slot);
 
   // [IGNORE] The message's slot is for the current slot (with a `MAXIMUM_GOSSIP_CLOCK_DISPARITY` allowance), i.e. `data.slot == current_slot`.
   if (!chain.clock.isCurrentSlotGivenGossipDisparity(data.slot)) {
@@ -48,9 +46,8 @@ async function validatePayloadAttestationMessage(
   }
 
   // [IGNORE] The `payload_attestation_message` is the first valid message received
-  // from the validator with index `payload_attestation_message.validator_index`.
-  // A single validator can participate PTC at most once per epoch
-  if (chain.seenPayloadAttesters.isKnown(epoch, validatorIndex)) {
+  // for the slot from the validator with index `payload_attestation_message.validator_index`.
+  if (chain.seenPayloadAttesters.isKnown(data.slot, validatorIndex)) {
     throw new PayloadAttestationError(GossipAction.IGNORE, {
       code: PayloadAttestationErrorCode.PAYLOAD_ATTESTATION_ALREADY_KNOWN,
       validatorIndex,
@@ -114,16 +111,8 @@ async function validatePayloadAttestationMessage(
   }
 
   // [REJECT] `payload_attestation_message.signature` is valid with respect to the validator's public key.
-  const validatorPubkey = chain.pubkeyCache.get(validatorIndex);
-  if (!validatorPubkey) {
-    throw new PayloadAttestationError(GossipAction.REJECT, {
-      code: PayloadAttestationErrorCode.INVALID_ATTESTER,
-      attesterIndex: validatorIndex,
-    });
-  }
-
-  const signatureSet = createSingleSignatureSetFromComponents(
-    validatorPubkey,
+  const signatureSet = createIndexedSignatureSetFromComponents(
+    validatorIndex,
     getPayloadAttestationDataSigningRoot(chain.config, data),
     payloadAttestationMessage.signature
   );
@@ -135,7 +124,7 @@ async function validatePayloadAttestationMessage(
   }
 
   // Valid
-  chain.seenPayloadAttesters.add(epoch, validatorIndex);
+  chain.seenPayloadAttesters.add(data.slot, validatorIndex);
 
   return {
     attDataRootHex: toRootHex(ssz.gloas.PayloadAttestationData.hashTreeRoot(data)),

package/src/chain/validation/proposerPreferences.ts

@@ -1,9 +1,9 @@
 import {IForkChoice, ProtoBlock} from "@lodestar/fork-choice";
-import {GENESIS_EPOCH, GENESIS_SLOT, MIN_SEED_LOOKAHEAD, SLOTS_PER_EPOCH} from "@lodestar/params";
+import {GENESIS_EPOCH, GENESIS_SLOT, MIN_SEED_LOOKAHEAD, SLOTS_PER_EPOCH, isForkPostGloas} from "@lodestar/params";
 import {
   computeEpochAtSlot,
   computeStartSlotAtEpoch,
-  createSingleSignatureSetFromComponents,
+  createIndexedSignatureSetFromComponents,
   getProposerPreferencesSigningRoot,
 } from "@lodestar/state-transition";
 import {Epoch, Slot, ValidatorIndex, gloas} from "@lodestar/types";
@@ -13,7 +13,7 @@ import {IBeaconChain} from "../index.js";
 
 /**
  * Validates a gossiped `SignedProposerPreferences` per
- * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.13/specs/gloas/p2p-interface.md#new-proposer_preferences
+ * https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.14/specs/gloas/p2p-interface.md#new-proposer_preferences
  */
 export async function validateGossipProposerPreferences(
   chain: IBeaconChain,
@@ -24,6 +24,16 @@ export async function validateGossipProposerPreferences(
   const dependentRootHex = toRootHex(dependentRoot);
   const proposalEpoch = computeEpochAtSlot(proposalSlot);
 
+  // [IGNORE] The proposal epoch is after the Gloas upgrade
+  const proposalFork = chain.config.getForkName(proposalSlot);
+  if (!isForkPostGloas(proposalFork)) {
+    throw new ProposerPreferencesError(GossipAction.IGNORE, {
+      code: ProposerPreferencesErrorCode.PRE_GLOAS_PROPOSAL_SLOT,
+      proposalSlot,
+      proposalFork,
+    });
+  }
+
   // [IGNORE] `preferences.proposal_slot` is within the proposer lookahead,
   // allowing for `MAXIMUM_GOSSIP_CLOCK_DISPARITY`.
   const currentEpoch = computeEpochAtSlot(chain.clock.currentSlotWithGossipDisparity);
@@ -129,8 +139,8 @@ export async function validateGossipProposerPreferences(
   }
 
   // [REJECT] `signed_proposer_preferences.signature` is valid with respect to the validator's public key.
-  const signatureSet = createSingleSignatureSetFromComponents(
-    chain.pubkeyCache.getOrThrow(validatorIndex),
+  const signatureSet = createIndexedSignatureSetFromComponents(
+    validatorIndex,
     getProposerPreferencesSigningRoot(chain.config, preferences),
     signedProposerPreferences.signature
   );

package/src/chain/validation/proposerSlashing.ts

@@ -37,7 +37,7 @@ async function validateProposerSlashing(
   try {
     const proposer = state.getValidator(proposerSlashing.signedHeader1.message.proposerIndex);
     // verifySignature = false, verified in batch below
-    assertValidProposerSlashing(chain.config, chain.pubkeyCache, state.slot, proposerSlashing, proposer, false);
+    assertValidProposerSlashing(chain.config, state.slot, proposerSlashing, proposer, false);
   } catch (e) {
     throw new ProposerSlashingError(GossipAction.REJECT, {
       code: ProposerSlashingErrorCode.INVALID,

package/src/chain/validation/voluntaryExit.ts

@@ -9,12 +9,69 @@ import {
 import {IBeaconChain} from "../index.js";
 import {RegenCaller} from "../regen/index.js";
 
+export type ApiVoluntaryExitResult = {status: "published"} | {status: "deferred"; validity: VoluntaryExitValidity};
+
+// Variants that can become valid in a future epoch without user action.
+// - earlyEpoch: exit.message.epoch is in the future; valid once current epoch catches up
+// - shortTimeActive: validator active < SHARD_COMMITTEE_PERIOD; valid once enough time passes
+// - pendingWithdrawals: Electra; valid once pending partial withdrawals drain
+// Note: VoluntaryExitValidity.inactive is intentionally excluded. It conflates
+// "validator does not exist" (permanent) with "validator not yet activated"
+// (transient), and cleanly classifying it requires splitting the enum variant
+// upstream. Left for a future follow-up.
+
+export function isTransientExitValidity(v: VoluntaryExitValidity): boolean {
+  switch (v) {
+    case VoluntaryExitValidity.earlyEpoch:
+    case VoluntaryExitValidity.shortTimeActive:
+    case VoluntaryExitValidity.pendingWithdrawals:
+      return true;
+    case VoluntaryExitValidity.valid:
+    case VoluntaryExitValidity.inactive:
+    case VoluntaryExitValidity.alreadyExited:
+    case VoluntaryExitValidity.invalidSignature:
+      return false;
+  }
+}
+
+// Comments for each call are present inside `validateVoluntaryExit`.
 export async function validateApiVoluntaryExit(
   chain: IBeaconChain,
   voluntaryExit: phase0.SignedVoluntaryExit
-): Promise<void> {
+): Promise<ApiVoluntaryExitResult> {
   const prioritizeBls = true;
-  return validateVoluntaryExit(chain, voluntaryExit, prioritizeBls);
+
+  if (
+    chain.opPool.hasSeenVoluntaryExit(voluntaryExit.message.validatorIndex) ||
+    chain.deferredVoluntaryExitPool.has(voluntaryExit.message.validatorIndex)
+  ) {
+    throw new VoluntaryExitError(GossipAction.IGNORE, {
+      code: VoluntaryExitErrorCode.ALREADY_EXISTS,
+    });
+  }
+
+  const state = await chain.getHeadStateAtCurrentEpoch(RegenCaller.validateApiVoluntaryExit);
+  const validity = state.getVoluntaryExitValidity(voluntaryExit, false);
+
+  if (validity !== VoluntaryExitValidity.valid && !isTransientExitValidity(validity)) {
+    throw new VoluntaryExitError(GossipAction.REJECT, {
+      code: voluntaryExitValidityToErrorCode(validity),
+    });
+  }
+
+  const signatureSet = getVoluntaryExitSignatureSet(chain.config, state, voluntaryExit);
+  if (!(await chain.bls.verifySignatureSets([signatureSet], {batchable: true, priority: prioritizeBls}))) {
+    throw new VoluntaryExitError(GossipAction.REJECT, {
+      code: VoluntaryExitErrorCode.INVALID_SIGNATURE,
+    });
+  }
+
+  if (validity !== VoluntaryExitValidity.valid) {
+    // Transient failure — signature is good, defer
+    return {status: "deferred", validity};
+  }
+
+  return {status: "published"};
 }
 
 export async function validateGossipVoluntaryExit(

package/src/execution/builder/http.ts

@@ -71,15 +71,18 @@ export class NoBidReceived extends Error {
 }
 
 /**
- * Beacon clients select randomized values from the following ranges when initializing
- * the circuit breaker (so at boot time and once for each unique boot).
+ * Default circuit breaker parameters:
  *
- * ALLOWED_FAULTS: between 1 and SLOTS_PER_EPOCH // 4
- * FAULT_INSPECTION_WINDOW: between SLOTS_PER_EPOCH and 2 * SLOTS_PER_EPOCH
+ * SLOTS_PER_EPOCH <= FAULT_INSPECTION_WINDOW < 2 * SLOTS_PER_EPOCH (randomized at initialization)
+ * ALLOWED_FAULTS: FAULT_INSPECTION_WINDOW // 4
  *
- * The values are randomized per node so builders cannot predict when a given proposer will
- * fall back to local blocks. With fixed thresholds a builder could withhold payloads right up
- * to the limit without ever tripping the breaker.
+ * e.g. on mainnet SLOTS_PER_EPOCH is 32, so FAULT_INSPECTION_WINDOW is between 32 and 63,
+ * and a window of 40 results in ALLOWED_FAULTS = 10.
+ *
+ * The randomized default window keeps the exact slots under inspection unpredictable per node,
+ * so a builder cannot tell when past faults age out of a given proposer's window and time
+ * withholding around trip or recovery points. Explicitly configured windows are clamped to at
+ * least SLOTS_PER_EPOCH, and configured allowedFaults is capped at the default ~25% budget.
  */
 export function getFaultInspectionParams(opts: {faultInspectionWindow?: number; allowedFaults?: number}): {
   faultInspectionWindow: number;
@@ -90,10 +93,7 @@ export function getFaultInspectionParams(opts: {faultInspectionWindow?: number;
     SLOTS_PER_EPOCH
   );
   // allowedFaults should be < faultInspectionWindow, limiting them to faultInspectionWindow/4
-  const allowedFaults = Math.min(
-    opts.allowedFaults ?? Math.floor(faultInspectionWindow / 4),
-    Math.floor(faultInspectionWindow / 4)
-  );
+  const allowedFaults = Math.min(opts.allowedFaults ?? Infinity, Math.floor(faultInspectionWindow / 4));
   return {faultInspectionWindow, allowedFaults};
 }
 

package/src/metrics/metrics/beacon.ts

@@ -143,17 +143,17 @@ export function createBeaconMetrics(register: RegistryMetricCreator) {
         name: "beacon_builder_circuit_breaker_active",
         help: "Whether the builder circuit breaker is active (1) causing builder bids to be ignored",
       }),
-      faults: register.gauge({
-        name: "beacon_builder_circuit_breaker_faults",
-        help: "Count of blocks with unrevealed payloads in the fault inspection window",
+      canonicalBlocks: register.gauge({
+        name: "beacon_builder_circuit_breaker_canonical_blocks",
+        help: "Count of canonical FULL and EMPTY blocks in the fault inspection window",
       }),
-      blocksPresent: register.gauge({
-        name: "beacon_builder_circuit_breaker_blocks_present",
-        help: "Count of blocks present in the fault inspection window",
+      fullBlocks: register.gauge({
+        name: "beacon_builder_circuit_breaker_full_blocks",
+        help: "Count of canonical FULL blocks in the fault inspection window",
       }),
-      payloadsRevealed: register.gauge({
-        name: "beacon_builder_circuit_breaker_payloads_revealed",
-        help: "Count of blocks with revealed payloads in the fault inspection window",
+      emptyBlocks: register.gauge({
+        name: "beacon_builder_circuit_breaker_empty_blocks",
+        help: "Count of canonical EMPTY blocks in the fault inspection window",
       }),
     },