@lodestar/state-transition 1.46.0-dev.e00bf67333 → 1.46.0-dev.eabf12abae

package/src/rewards/blockRewards.ts

@@ -4,11 +4,17 @@ import {
   WHISTLEBLOWER_REWARD_QUOTIENT,
   WHISTLEBLOWER_REWARD_QUOTIENT_ELECTRA,
   isForkPostElectra,
+  isForkPostGloas,
 } from "@lodestar/params";
-import {BeaconBlock, altair, phase0, rewards} from "@lodestar/types";
+import {BeaconBlock, Slot, altair, phase0, rewards} from "@lodestar/types";
 import {processAttestationsAltair} from "../block/processAttestationsAltair.js";
 import {RewardCache} from "../cache/rewardCache.js";
-import {CachedBeaconStateAllForks, CachedBeaconStateAltair, CachedBeaconStatePhase0} from "../cache/stateCache.js";
+import {
+  CachedBeaconStateAllForks,
+  CachedBeaconStateAltair,
+  CachedBeaconStateGloas,
+  CachedBeaconStatePhase0,
+} from "../cache/stateCache.js";
 import {getAttesterSlashableIndices} from "../util/attestation.js";
 
 type SubRewardValue = number; // All reward values should be integer
@@ -36,10 +42,18 @@ export async function computeBlockRewards(
   let syncAggregateReward = cachedSyncAggregateReward;
 
   if (blockAttestationReward === 0) {
+    const parentSlot = isForkPostGloas(fork)
+      ? (preState as CachedBeaconStateGloas).latestExecutionPayloadBid.slot
+      : null;
     blockAttestationReward =
       fork === ForkName.phase0
         ? computeBlockAttestationRewardPhase0(block as phase0.BeaconBlock, preState as CachedBeaconStatePhase0)
-        : computeBlockAttestationRewardAltair(config, block as altair.BeaconBlock, preState as CachedBeaconStateAltair);
+        : computeBlockAttestationRewardAltair(
+            config,
+            block as altair.BeaconBlock,
+            preState as CachedBeaconStateAltair,
+            parentSlot
+          );
   }
 
   if (syncAggregateReward === 0) {
@@ -79,12 +93,13 @@ function computeBlockAttestationRewardPhase0(
 function computeBlockAttestationRewardAltair(
   config: BeaconConfig,
   block: altair.BeaconBlock,
-  preState: CachedBeaconStateAltair
+  preState: CachedBeaconStateAltair,
+  parentSlot: Slot | null
 ): SubRewardValue {
   const fork = config.getForkSeq(block.slot);
   const {attestations} = block.body;
 
-  processAttestationsAltair(fork, preState, attestations, false);
+  processAttestationsAltair(fork, preState, attestations, parentSlot, false);
 
   return preState.proposerRewards.attestations;
 }

package/src/signatureSets/executionPayloadBid.ts

@@ -1,14 +1,12 @@
 import {BeaconConfig} from "@lodestar/config";
-import {DOMAIN_BEACON_BUILDER} from "@lodestar/params";
-import {Slot, gloas, ssz} from "@lodestar/types";
+import {DOMAIN_BEACON_BUILDER, isForkPostGloas} from "@lodestar/params";
+import {ExecutionPayloadBid, ssz, sszTypesFor} from "@lodestar/types";
 import {computeSigningRoot} from "../util/index.js";
 
-export function getExecutionPayloadBidSigningRoot(
-  config: BeaconConfig,
-  stateSlot: Slot,
-  bid: gloas.ExecutionPayloadBid
-): Uint8Array {
-  const domain = config.getDomain(stateSlot, DOMAIN_BEACON_BUILDER);
+export function getExecutionPayloadBidSigningRoot(config: BeaconConfig, bid: ExecutionPayloadBid): Uint8Array {
+  const fork = config.getForkName(bid.slot);
+  const domain = config.getDomain(bid.slot, DOMAIN_BEACON_BUILDER);
+  const sszType = isForkPostGloas(fork) ? sszTypesFor(fork).ExecutionPayloadBid : ssz.gloas.ExecutionPayloadBid;
 
-  return computeSigningRoot(ssz.gloas.ExecutionPayloadBid, bid, domain);
+  return computeSigningRoot(sszType, bid, domain);
 }

package/src/slot/index.ts

@@ -10,6 +10,7 @@ export {upgradeStateToDeneb} from "./upgradeStateToDeneb.js";
 export {upgradeStateToElectra} from "./upgradeStateToElectra.js";
 export {upgradeStateToFulu} from "./upgradeStateToFulu.js";
 export {upgradeStateToGloas} from "./upgradeStateToGloas.js";
+export {upgradeStateToHeze} from "./upgradeStateToHeze.js";
 
 /**
  * Dial state to next slot. Common for all forks

package/src/slot/upgradeStateToAltair.ts

@@ -137,6 +137,7 @@ function translateParticipation(
       attestation.inclusionDelay,
       epochCtx.epoch,
       rootCache,
+      null,
       null
     );
 

package/src/slot/upgradeStateToGloas.ts

@@ -70,7 +70,7 @@ export function upgradeStateToGloas(stateFulu: CachedBeaconStateFulu): CachedBea
   stateGloasView.currentSyncCommittee = stateGloasCloned.currentSyncCommittee;
   stateGloasView.nextSyncCommittee = stateGloasCloned.nextSyncCommittee;
   stateGloasView.latestExecutionPayloadBid.blockHash = stateFulu.latestExecutionPayloadHeader.blockHash;
-  stateGloasView.latestExecutionPayloadBid.gasLimit = stateFulu.latestExecutionPayloadHeader.gasLimit;
+  stateGloasView.latestExecutionPayloadBid.gasLimit = BigInt(stateFulu.latestExecutionPayloadHeader.gasLimit);
   stateGloasView.latestExecutionPayloadBid.executionRequestsRoot = ssz.gloas.ExecutionRequests.hashTreeRoot(
     ssz.gloas.ExecutionRequests.defaultValue()
   );
@@ -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/slot/upgradeStateToHeze.ts

@@ -0,0 +1,91 @@
+import {ssz} from "@lodestar/types";
+import {getCachedBeaconState} from "../cache/stateCache.js";
+import {CachedBeaconStateGloas, CachedBeaconStateHeze} from "../types.js";
+
+/**
+ * Upgrade a state from Gloas to Heze.
+ * Spec: heze/fork.md `upgrade_to_heze`.
+ */
+export function upgradeStateToHeze(stateGloas: CachedBeaconStateGloas): CachedBeaconStateHeze {
+  const {config} = stateGloas;
+
+  ssz.gloas.BeaconState.commitViewDU(stateGloas);
+  const stateHezeCloned = stateGloas;
+
+  const stateHezeView = ssz.heze.BeaconState.defaultViewDU();
+
+  stateHezeView.genesisTime = stateHezeCloned.genesisTime;
+  stateHezeView.genesisValidatorsRoot = stateHezeCloned.genesisValidatorsRoot;
+  stateHezeView.slot = stateHezeCloned.slot;
+  stateHezeView.fork = ssz.phase0.Fork.toViewDU({
+    previousVersion: stateGloas.fork.currentVersion,
+    currentVersion: config.HEZE_FORK_VERSION,
+    epoch: stateGloas.epochCtx.epoch,
+  });
+  stateHezeView.latestBlockHeader = stateHezeCloned.latestBlockHeader;
+  stateHezeView.blockRoots = stateHezeCloned.blockRoots;
+  stateHezeView.stateRoots = stateHezeCloned.stateRoots;
+  stateHezeView.historicalRoots = stateHezeCloned.historicalRoots;
+  stateHezeView.eth1Data = stateHezeCloned.eth1Data;
+  stateHezeView.eth1DataVotes = stateHezeCloned.eth1DataVotes;
+  stateHezeView.eth1DepositIndex = stateHezeCloned.eth1DepositIndex;
+  stateHezeView.validators = stateHezeCloned.validators;
+  stateHezeView.balances = stateHezeCloned.balances;
+  stateHezeView.randaoMixes = stateHezeCloned.randaoMixes;
+  stateHezeView.slashings = stateHezeCloned.slashings;
+  stateHezeView.previousEpochParticipation = stateHezeCloned.previousEpochParticipation;
+  stateHezeView.currentEpochParticipation = stateHezeCloned.currentEpochParticipation;
+  stateHezeView.justificationBits = stateHezeCloned.justificationBits;
+  stateHezeView.previousJustifiedCheckpoint = stateHezeCloned.previousJustifiedCheckpoint;
+  stateHezeView.currentJustifiedCheckpoint = stateHezeCloned.currentJustifiedCheckpoint;
+  stateHezeView.finalizedCheckpoint = stateHezeCloned.finalizedCheckpoint;
+  stateHezeView.inactivityScores = stateHezeCloned.inactivityScores;
+  stateHezeView.currentSyncCommittee = stateHezeCloned.currentSyncCommittee;
+  stateHezeView.nextSyncCommittee = stateHezeCloned.nextSyncCommittee;
+  stateHezeView.latestBlockHash = stateHezeCloned.latestBlockHash;
+  stateHezeView.nextWithdrawalIndex = stateHezeCloned.nextWithdrawalIndex;
+  stateHezeView.nextWithdrawalValidatorIndex = stateHezeCloned.nextWithdrawalValidatorIndex;
+  stateHezeView.historicalSummaries = stateHezeCloned.historicalSummaries;
+  stateHezeView.depositRequestsStartIndex = stateHezeCloned.depositRequestsStartIndex;
+  stateHezeView.depositBalanceToConsume = stateHezeCloned.depositBalanceToConsume;
+  stateHezeView.exitBalanceToConsume = stateHezeCloned.exitBalanceToConsume;
+  stateHezeView.earliestExitEpoch = stateHezeCloned.earliestExitEpoch;
+  stateHezeView.consolidationBalanceToConsume = stateHezeCloned.consolidationBalanceToConsume;
+  stateHezeView.earliestConsolidationEpoch = stateHezeCloned.earliestConsolidationEpoch;
+  stateHezeView.pendingDeposits = stateHezeCloned.pendingDeposits;
+  stateHezeView.pendingPartialWithdrawals = stateHezeCloned.pendingPartialWithdrawals;
+  stateHezeView.pendingConsolidations = stateHezeCloned.pendingConsolidations;
+  stateHezeView.proposerLookahead = stateHezeCloned.proposerLookahead;
+  stateHezeView.builders = stateHezeCloned.builders;
+  stateHezeView.nextWithdrawalBuilderIndex = stateHezeCloned.nextWithdrawalBuilderIndex;
+  stateHezeView.executionPayloadAvailability = stateHezeCloned.executionPayloadAvailability;
+  stateHezeView.builderPendingPayments = stateHezeCloned.builderPendingPayments;
+  stateHezeView.builderPendingWithdrawals = stateHezeCloned.builderPendingWithdrawals;
+
+  // [Modified in Heze:EIP7805] inclusion_list_bits = Bitvector[INCLUSION_LIST_COMMITTEE_SIZE]() (default zero)
+  const oldBid = stateHezeCloned.latestExecutionPayloadBid;
+  const newBid = ssz.heze.ExecutionPayloadBid.defaultViewDU();
+  newBid.parentBlockHash = oldBid.parentBlockHash;
+  newBid.parentBlockRoot = oldBid.parentBlockRoot;
+  newBid.blockHash = oldBid.blockHash;
+  newBid.prevRandao = oldBid.prevRandao;
+  newBid.feeRecipient = oldBid.feeRecipient;
+  newBid.gasLimit = oldBid.gasLimit;
+  newBid.builderIndex = oldBid.builderIndex;
+  newBid.slot = oldBid.slot;
+  newBid.value = oldBid.value;
+  newBid.executionPayment = oldBid.executionPayment;
+  newBid.blobKzgCommitments = oldBid.blobKzgCommitments;
+  newBid.executionRequestsRoot = oldBid.executionRequestsRoot;
+  stateHezeView.latestExecutionPayloadBid = newBid;
+
+  stateHezeView.payloadExpectedWithdrawals = stateHezeCloned.payloadExpectedWithdrawals;
+  stateHezeView.ptcWindow = stateHezeCloned.ptcWindow;
+
+  const stateHeze = getCachedBeaconState(stateHezeView, stateGloas);
+  stateHeze.commit();
+  // biome-ignore lint/complexity/useLiteralKeys: It is a protected attribute
+  stateHeze["clearCache"]();
+
+  return stateHeze;
+}

package/src/stateTransition.ts

@@ -16,6 +16,7 @@ import {
   upgradeStateToDeneb,
   upgradeStateToElectra,
   upgradeStateToGloas,
+  upgradeStateToHeze,
 } from "./slot/index.js";
 import {upgradeStateToFulu} from "./slot/upgradeStateToFulu.js";
 import {
@@ -26,6 +27,7 @@ import {
   CachedBeaconStateDeneb,
   CachedBeaconStateElectra,
   CachedBeaconStateFulu,
+  CachedBeaconStateGloas,
   CachedBeaconStatePhase0,
 } from "./types.js";
 import {computeEpochAtSlot} from "./util/index.js";
@@ -278,6 +280,9 @@ function processSlotsWithTransientCache(
       if (stateEpoch === config.GLOAS_FORK_EPOCH) {
         postState = upgradeStateToGloas(postState as CachedBeaconStateFulu) as CachedBeaconStateAllForks;
       }
+      if (stateEpoch === config.HEZE_FORK_EPOCH) {
+        postState = upgradeStateToHeze(postState as CachedBeaconStateGloas) as CachedBeaconStateAllForks;
+      }
 
       {
         const timer = metrics?.epochTransitionStepTime.startTimer({step: EpochTransitionStep.finalProcessEpoch});

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

@@ -9,6 +9,7 @@ import {
   ForkPostElectra,
   ForkPostFulu,
   ForkPostGloas,
+  ForkPostHeze,
   isForkPostAltair,
   isForkPostBellatrix,
   isForkPostCapella,
@@ -16,6 +17,7 @@ import {
   isForkPostElectra,
   isForkPostFulu,
   isForkPostGloas,
+  isForkPostHeze,
 } from "@lodestar/params";
 import {
   BeaconBlock,
@@ -50,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.
@@ -240,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 */
@@ -267,14 +277,19 @@ export interface IBeaconStateViewGloas extends IBeaconStateViewFulu {
   withParentPayloadApplied(executionRequests: gloas.ExecutionRequests): IBeaconStateViewGloas;
 }
 
+/** Heze+ state fields — use isStatePostHeze() guard */
+export interface IBeaconStateViewHeze extends IBeaconStateViewGloas {
+  forkName: ForkPostHeze;
+}
+
 /**
  * Type constraint for the concrete BeaconStateView class.
- * Requires all fields from the latest fork interface (IBeaconStateViewGloas) but keeps
+ * Requires all fields from the latest fork interface (IBeaconStateViewHeze) but keeps
  * forkName as ForkName since the class wraps any fork's state.
  * Sub-interfaces retain their narrowed forkName discriminants for caller-side type guards.
  */
 export type IBeaconStateViewLatestFork = Omit<
-  IBeaconStateViewGloas,
+  IBeaconStateViewHeze,
   "forkName" | "latestExecutionPayloadHeader" | "payloadBlockNumber"
 > & {
   forkName: ForkName;
@@ -337,3 +352,7 @@ export function isStatePostFulu(state: IBeaconStateView): state is IBeaconStateV
 export function isStatePostGloas(state: IBeaconStateView): state is IBeaconStateViewGloas {
   return isForkPostGloas(state.forkName);
 }
+
+export function isStatePostHeze(state: IBeaconStateView): state is IBeaconStateViewHeze {
+  return isForkPostHeze(state.forkName);
+}

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/state.ts

@@ -54,7 +54,7 @@ export function generateState(opts?: TestBeaconState): BeaconStatePhase0 {
     eth1Data: {
       depositRoot: Buffer.alloc(32),
       blockHash: Buffer.alloc(32),
-      depositCount: 0,
+      depositCount: 0n,
     },
     eth1DataVotes: [],
     eth1DepositIndex: 0,

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";
@@ -437,13 +443,13 @@ function buildPerformanceStatePhase0(pubkeysArg?: Uint8Array[]): phase0.BeaconSt
     historicalRoots: [],
     // Eth1
     eth1Data: {
-      depositCount: pubkeys.length,
+      depositCount: BigInt(pubkeys.length),
       depositRoot: fromHexString("0xcb1f89a924cfd31224823db5a41b1643f10faa7aedf231f1e28887f6ee98c047"),
       blockHash: fromHexString("0x701fb2869ce16d0f1d14f6705725adb0dec6799da29006dfc6fff83960298f21"),
     },
     // minus one so that inserting 1 from block works
     eth1DataVotes: newFilledArray(EPOCHS_PER_ETH1_VOTING_PERIOD * SLOTS_PER_EPOCH - 1, {
-      depositCount: 1,
+      depositCount: 1n,
       depositRoot: Buffer.alloc(32, 1),
       blockHash: Buffer.alloc(32, 1),
     }),
@@ -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/types.ts

@@ -10,6 +10,7 @@ export type {
   CachedBeaconStateExecutions,
   CachedBeaconStateFulu,
   CachedBeaconStateGloas,
+  CachedBeaconStateHeze,
   CachedBeaconStatePhase0,
 } from "./cache/stateCache.js";
 export type {
@@ -22,6 +23,7 @@ export type {
   BeaconStateExecutions,
   BeaconStateFulu,
   BeaconStateGloas,
+  BeaconStateHeze,
   BeaconStatePhase0,
   ShufflingGetter,
 } from "./cache/types.js";