@lodestar/state-transition 1.42.0-dev.f6213da56d → 1.42.0-dev.fb8f8a700e

package/src/stateView/beaconStateView.ts

@@ -1,9 +1,10 @@
 import {CompactMultiProof, ProofType, Tree, createProof} from "@chainsafe/persistent-merkle-tree";
-import {ByteViews} from "@chainsafe/ssz";
+import {BitArray, ByteViews} from "@chainsafe/ssz";
 import {BeaconConfig} from "@lodestar/config";
-import {ForkSeq, SLOTS_PER_HISTORICAL_ROOT, isForkPostGloas} from "@lodestar/params";
+import {ForkName, ForkSeq, SLOTS_PER_HISTORICAL_ROOT, isForkPostGloas} from "@lodestar/params";
 import {
   BeaconBlock,
+  BeaconState,
   BlindedBeaconBlock,
   BuilderIndex,
   Bytes32,
@@ -33,7 +34,6 @@ import {VoluntaryExitValidity, getVoluntaryExitValidity} from "../block/processV
 import {getExpectedWithdrawals} from "../block/processWithdrawals.js";
 import {EffectiveBalanceIncrements} from "../cache/effectiveBalanceIncrements.js";
 import {EpochTransitionCacheOpts} from "../cache/epochTransitionCache.js";
-import {PubkeyCache, createPubkeyCache} from "../cache/pubkeyCache.js";
 import {RewardCache} from "../cache/rewardCache.js";
 import {
   CachedBeaconStateAllForks,
@@ -47,7 +47,6 @@ import {
   isStateValidatorsNodesPopulated,
 } from "../cache/stateCache.js";
 import {SyncCommitteeCache} from "../cache/syncCommitteeCache.js";
-import {BeaconStateAllForks} from "../cache/types.js";
 import {computeUnrealizedCheckpoints} from "../epoch/computeUnrealizedCheckpoints.js";
 import {getFinalizedRootProof, getSyncCommitteesWitness} from "../lightClient/proofs.js";
 import {SyncCommitteeWitness} from "../lightClient/types.js";
@@ -64,11 +63,10 @@ import {isExecutionEnabled, isExecutionStateType, isMergeTransitionComplete} fro
 import {canBuilderCoverBid} from "../util/gloas.js";
 import {loadState} from "../util/loadState/loadState.js";
 import {getRandaoMix} from "../util/seed.js";
-import {getStateTypeFromBytes} from "../util/sszBytes.js";
 import {getLatestWeakSubjectivityCheckpointEpoch} from "../util/weakSubjectivity.js";
-import {IBeaconStateView} from "./interface.js";
+import {IBeaconStateView, IBeaconStateViewLatestFork} from "./interface.js";
 
-export class BeaconStateView implements IBeaconStateView {
+export class BeaconStateView implements IBeaconStateViewLatestFork {
   private readonly config: BeaconConfig;
   // Cached values extracted from the tree
   // phase0
@@ -92,7 +90,7 @@ export class BeaconStateView implements IBeaconStateView {
   // fulu
   private _proposerLookahead: fulu.ProposerLookahead | null = null;
   // gloas
-  private _executionPayloadAvailability: boolean[] | null = null;
+  private _executionPayloadAvailability: BitArray | null = null;
   private _latestExecutionPayloadBid: ExecutionPayloadBid | null = null;
 
   constructor(readonly cachedState: CachedBeaconStateAllForks) {
@@ -101,6 +99,10 @@ export class BeaconStateView implements IBeaconStateView {
 
   // phase0
 
+  get forkName(): ForkName {
+    return this.config.getForkName(this.cachedState.slot);
+  }
+
   get slot(): number {
     return this.cachedState.slot;
   }
@@ -357,15 +359,15 @@ export class BeaconStateView implements IBeaconStateView {
 
   // gloas
 
-  get executionPayloadAvailability(): boolean[] {
+  get executionPayloadAvailability(): BitArray {
     if (this.config.getForkSeq(this.cachedState.slot) < ForkSeq.gloas) {
       throw new Error("executionPayloadAvailability is not available before GLOAS");
     }
 
     if (this._executionPayloadAvailability === null) {
-      this._executionPayloadAvailability = (this.cachedState as CachedBeaconStateGloas).executionPayloadAvailability
-        .toValue()
-        .toBoolArray();
+      this._executionPayloadAvailability = (
+        this.cachedState as CachedBeaconStateGloas
+      ).executionPayloadAvailability.toValue();
     }
 
     return this._executionPayloadAvailability;
@@ -404,7 +406,7 @@ export class BeaconStateView implements IBeaconStateView {
    * Return the index of the validator in the PTC committee for the given slot.
    * return -1 if validator is not in the PTC committee for the given slot.
    */
-  validatorPTCCommitteeIndex(validatorIndex: ValidatorIndex, slot: Slot): number {
+  getIndexInPayloadTimelinessCommittee(validatorIndex: ValidatorIndex, slot: Slot): number {
     if (this.config.getForkSeq(this.cachedState.slot) < ForkSeq.gloas) {
       throw new Error("PTC committees are not supported before GLOAS");
     }
@@ -503,6 +505,10 @@ export class BeaconStateView implements IBeaconStateView {
     return this.cachedState.epochCtx.syncProposerReward;
   }
 
+  getIndexedSyncCommittee(slot: Slot): SyncCommitteeCache {
+    return this.cachedState.epochCtx.getIndexedSyncCommittee(slot);
+  }
+
   getIndexedSyncCommitteeAtEpoch(epoch: Epoch): SyncCommitteeCache {
     return this.cachedState.epochCtx.getIndexedSyncCommitteeAtEpoch(epoch);
   }
@@ -713,6 +719,10 @@ export class BeaconStateView implements IBeaconStateView {
     return new BeaconStateView(cachedState);
   }
 
+  toValue(): BeaconState {
+    return this.cachedState.toValue();
+  }
+
   serialize(): Uint8Array {
     return this.cachedState.serialize();
   }
@@ -778,41 +788,3 @@ export class BeaconStateView implements IBeaconStateView {
     return new BeaconStateView(postPayloadState);
   }
 }
-
-/**
- * Create BeaconStateView for historical state regen, no need to sync pubkey cache there.
- */
-export function createBeaconStateViewForHistoricalRegen(
-  config: BeaconConfig,
-  stateBytes: Uint8Array
-): IBeaconStateView {
-  const state = getStateTypeFromBytes(config, stateBytes).deserializeToViewDU(stateBytes);
-
-  const pubkeyCache = createPubkeyCache();
-  syncPubkeyCache(state, pubkeyCache);
-  const cachedState = createCachedBeaconState(
-    state,
-    {
-      config,
-      pubkeyCache,
-    },
-    {
-      skipSyncPubkeys: true,
-    }
-  );
-
-  return new BeaconStateView(cachedState);
-}
-
-/**
- * Populate a PubkeyIndexMap with any new entries based on a BeaconState
- */
-function syncPubkeyCache(state: BeaconStateAllForks, pubkeyCache: PubkeyCache): void {
-  // Get the validators sub tree once for all the loop
-
-  const newCount = state.validators.length;
-  for (let i = pubkeyCache.size; i < newCount; i++) {
-    const pubkey = state.validators.getReadonly(i).pubkey;
-    pubkeyCache.set(i, pubkey);
-  }
-}

package/src/stateView/index.ts

@@ -1,2 +1,3 @@
 export * from "./beaconStateView.js";
 export * from "./interface.js";
+export * from "./stateViewFactory.js";

package/src/stateView/interface.ts

@@ -1,7 +1,25 @@
 import {CompactMultiProof} from "@chainsafe/persistent-merkle-tree";
-import {ByteViews} from "@chainsafe/ssz";
+import {BitArray, ByteViews} from "@chainsafe/ssz";
+import {
+  ForkName,
+  ForkPostAltair,
+  ForkPostBellatrix,
+  ForkPostCapella,
+  ForkPostDeneb,
+  ForkPostElectra,
+  ForkPostFulu,
+  ForkPostGloas,
+  isForkPostAltair,
+  isForkPostBellatrix,
+  isForkPostCapella,
+  isForkPostDeneb,
+  isForkPostElectra,
+  isForkPostFulu,
+  isForkPostGloas,
+} from "@lodestar/params";
 import {
   BeaconBlock,
+  BeaconState,
   BlindedBeaconBlock,
   BuilderIndex,
   Bytes32,
@@ -40,6 +58,7 @@ export interface IBeaconStateView {
   // State access
 
   // phase0
+  forkName: ForkName;
   slot: Slot;
   fork: Fork;
   epoch: Epoch;
@@ -55,50 +74,6 @@ export interface IBeaconStateView {
   getStateRootAtSlot(slot: Slot): Root;
   getRandaoMix(epoch: Epoch): Bytes32;
 
-  // altair
-  previousEpochParticipation: Uint8Array;
-  currentEpochParticipation: Uint8Array;
-  getPreviousEpochParticipation(validatorIndex: ValidatorIndex): number;
-  getCurrentEpochParticipation(validatorIndex: ValidatorIndex): number;
-
-  // bellatrix
-  latestExecutionPayloadHeader: ExecutionPayloadHeader;
-  /**
-   * Cross-fork accessor for the execution block hash of the most recently included payload.
-   * Pre-gloas: returns latestExecutionPayloadHeader.blockHash (bellatrix–fulu).
-   * Gloas+: returns the dedicated latestBlockHash state field (EIP-7732).
-   * Throws before bellatrix.
-   */
-  latestBlockHash: Bytes32;
-  /**
-   * The execution block number of the most recently included payload.
-   * Named payloadBlockNumber (not latestBlockNumber) to mirror ExecutionPayloadHeader.blockNumber pre-gloas.
-   * Only available from bellatrix through fulu — not tracked on BeaconState in gloas+ (EIP-7732).
-   * Throws before bellatrix and from gloas onwards.
-   */
-  payloadBlockNumber: number;
-
-  // capella
-  historicalSummaries: capella.HistoricalSummaries;
-
-  // electra
-  pendingDeposits: electra.PendingDeposits;
-  pendingDepositsCount: number;
-  pendingPartialWithdrawals: electra.PendingPartialWithdrawals;
-  pendingPartialWithdrawalsCount: number;
-  pendingConsolidations: electra.PendingConsolidations;
-  pendingConsolidationsCount: number;
-
-  // fulu
-  proposerLookahead: fulu.ProposerLookahead;
-
-  // gloas
-  executionPayloadAvailability: boolean[];
-  latestExecutionPayloadBid: ExecutionPayloadBid;
-  getBuilder(index: BuilderIndex): gloas.Builder;
-  canBuilderCoverBid(builderIndex: BuilderIndex, bidAmount: number): boolean;
-  validatorPTCCommitteeIndex(validatorIndex: ValidatorIndex, slot: Slot): number;
-
   // Shuffling and committees
   getShufflingAtEpoch(epoch: Epoch): EpochShuffling;
   // Decision roots
@@ -110,19 +85,11 @@ export interface IBeaconStateView {
   getCurrentShuffling(): EpochShuffling;
   getNextShuffling(): EpochShuffling;
 
-  // utils: proposers, anchor checkpoint
+  // Proposer shuffling
   previousProposers: ValidatorIndex[] | null;
   currentProposers: ValidatorIndex[];
   nextProposers: ValidatorIndex[];
   getBeaconProposer(slot: Slot): ValidatorIndex;
-  computeAnchorCheckpoint(): {checkpoint: phase0.Checkpoint; blockHeader: phase0.BeaconBlockHeader};
-
-  // Sync committees
-  currentSyncCommittee: altair.SyncCommittee;
-  nextSyncCommittee: altair.SyncCommittee;
-  currentSyncCommitteeIndexed: SyncCommitteeCache;
-  syncProposerReward: number;
-  getIndexedSyncCommitteeAtEpoch(epoch: Epoch): SyncCommitteeCache;
 
   // Validators and balances
   effectiveBalanceIncrements: EffectiveBalanceIncrements;
@@ -138,28 +105,10 @@ export interface IBeaconStateView {
   getAllValidators(): phase0.Validator[];
   getAllBalances(): number[];
 
-  // Merge
-  isExecutionStateType: boolean;
-  isMergeTransitionComplete: boolean;
-  // TODO this should go away (or rather only need block)
-  isExecutionEnabled(block: BeaconBlock | BlindedBeaconBlock): boolean;
-
-  // Block production
-  getExpectedWithdrawals(): {
-    expectedWithdrawals: capella.Withdrawal[];
-    processedBuilderWithdrawalsCount: number;
-    processedPartialWithdrawalsCount: number;
-    processedValidatorSweepCount: number;
-  };
-
   // API
   proposerRewards: RewardCache;
   computeBlockRewards(block: BeaconBlock, proposerRewards?: RewardCache): Promise<rewards.BlockRewards>;
   computeAttestationsRewards(validatorIds?: (ValidatorIndex | string)[]): Promise<rewards.AttestationsRewards>;
-  computeSyncCommitteeRewards(
-    block: BeaconBlock,
-    validatorIds: (ValidatorIndex | string)[]
-  ): Promise<rewards.SyncCommitteeRewards>;
   getLatestWeakSubjectivityCheckpointEpoch(): Epoch;
 
   // Validation
@@ -171,7 +120,6 @@ export interface IBeaconStateView {
 
   // Proofs
   getFinalizedRootProof(): Uint8Array[];
-  getSyncCommitteesWitness(): SyncCommitteeWitness;
   getSingleProof(gindex: bigint): Uint8Array[];
   createMultiProof(descriptor: Uint8Array): CompactMultiProof;
 
@@ -180,6 +128,7 @@ export interface IBeaconStateView {
     justifiedCheckpoint: phase0.Checkpoint;
     finalizedCheckpoint: phase0.Checkpoint;
   };
+  computeAnchorCheckpoint(): {checkpoint: phase0.Checkpoint; blockHeader: phase0.BeaconBlockHeader};
 
   // this is for backward compatible
   clonedCount: number;
@@ -190,6 +139,7 @@ export interface IBeaconStateView {
 
   // Serialization
   loadOtherState(stateBytes: Uint8Array, seedValidatorsBytes?: Uint8Array): IBeaconStateView;
+  toValue(): BeaconState;
   serialize(): Uint8Array;
   serializedSize(): number;
   serializeToBytes(output: ByteViews, offset: number): number;
@@ -210,8 +160,132 @@ export interface IBeaconStateView {
     epochTransitionCacheOpts?: EpochTransitionCacheOpts & {dontTransferCache?: boolean},
     modules?: StateTransitionModules
   ): IBeaconStateView;
+}
+
+/** Altair+ state fields — use isStatePostAltair() guard */
+export interface IBeaconStateViewAltair extends IBeaconStateView {
+  forkName: ForkPostAltair;
+  previousEpochParticipation: Uint8Array;
+  currentEpochParticipation: Uint8Array;
+  getPreviousEpochParticipation(validatorIndex: ValidatorIndex): number;
+  getCurrentEpochParticipation(validatorIndex: ValidatorIndex): number;
+  currentSyncCommittee: altair.SyncCommittee;
+  nextSyncCommittee: altair.SyncCommittee;
+  currentSyncCommitteeIndexed: SyncCommitteeCache;
+  syncProposerReward: number;
+  getIndexedSyncCommitteeAtEpoch(epoch: Epoch): SyncCommitteeCache;
+  /** Get indexed sync committee with slot+1 offset for duty lookups */
+  getIndexedSyncCommittee(slot: Slot): SyncCommitteeCache;
+  computeSyncCommitteeRewards(
+    block: BeaconBlock,
+    validatorIds: (ValidatorIndex | string)[]
+  ): Promise<rewards.SyncCommitteeRewards>;
+  getSyncCommitteesWitness(): SyncCommitteeWitness;
+}
+
+/** Bellatrix+ state fields — use isStatePostBellatrix() guard */
+export interface IBeaconStateViewBellatrix extends IBeaconStateViewAltair {
+  forkName: ForkPostBellatrix;
+  latestExecutionPayloadHeader: ExecutionPayloadHeader;
+  /**
+   * Cross-fork accessor for the execution block hash of the most recently included payload.
+   * Pre-gloas: returns latestExecutionPayloadHeader.blockHash (bellatrix–fulu).
+   * Gloas+: returns the dedicated latestBlockHash state field (EIP-7732).
+   * Throws before bellatrix.
+   */
+  latestBlockHash: Bytes32;
+  /**
+   * The execution block number of the most recently included payload.
+   * Named payloadBlockNumber (not latestBlockNumber) to mirror ExecutionPayloadHeader.blockNumber pre-gloas.
+   * Only available from bellatrix through fulu — not tracked on BeaconState in gloas+ (EIP-7732).
+   * Throws before bellatrix and from gloas onwards.
+   */
+  payloadBlockNumber: number;
+  isExecutionStateType: boolean;
+  isMergeTransitionComplete: boolean;
+  isExecutionEnabled(block: BeaconBlock | BlindedBeaconBlock): boolean;
+}
+
+/** Capella+ state fields — use isStatePostCapella() guard */
+export interface IBeaconStateViewCapella extends IBeaconStateViewBellatrix {
+  forkName: ForkPostCapella;
+  historicalSummaries: capella.HistoricalSummaries;
+  getExpectedWithdrawals(): {
+    expectedWithdrawals: capella.Withdrawal[];
+    processedBuilderWithdrawalsCount: number;
+    processedPartialWithdrawalsCount: number;
+    processedBuildersSweepCount: number;
+    processedValidatorSweepCount: number;
+  };
+}
+
+/** Deneb+ state — no new state-view fields; placeholder for fork completeness and isStatePostDeneb() narrowing */
+export interface IBeaconStateViewDeneb extends IBeaconStateViewCapella {
+  forkName: ForkPostDeneb;
+}
+
+/** Electra+ state fields — use isStatePostElectra() guard */
+export interface IBeaconStateViewElectra extends IBeaconStateViewDeneb {
+  forkName: ForkPostElectra;
+  pendingDeposits: electra.PendingDeposits;
+  pendingDepositsCount: number;
+  pendingPartialWithdrawals: electra.PendingPartialWithdrawals;
+  pendingPartialWithdrawalsCount: number;
+  pendingConsolidations: electra.PendingConsolidations;
+  pendingConsolidationsCount: number;
+}
+
+/** Fulu+ state fields — use isStatePostFulu() guard */
+export interface IBeaconStateViewFulu extends IBeaconStateViewElectra {
+  forkName: ForkPostFulu;
+  proposerLookahead: fulu.ProposerLookahead;
+}
+
+/** Gloas+ state fields — use isStatePostGloas() guard */
+export interface IBeaconStateViewGloas extends IBeaconStateViewFulu {
+  forkName: ForkPostGloas;
+  executionPayloadAvailability: BitArray;
+  latestExecutionPayloadBid: ExecutionPayloadBid;
+  getBuilder(index: BuilderIndex): gloas.Builder;
+  canBuilderCoverBid(builderIndex: BuilderIndex, bidAmount: number): boolean;
+  getIndexInPayloadTimelinessCommittee(validatorIndex: ValidatorIndex, slot: Slot): number;
   processExecutionPayloadEnvelope(
     signedEnvelope: gloas.SignedExecutionPayloadEnvelope,
     opts?: ProcessExecutionPayloadEnvelopeOpts
   ): IBeaconStateView;
 }
+
+/**
+ * Type constraint for the concrete BeaconStateView class.
+ * Requires all fields from the latest fork interface (IBeaconStateViewGloas) 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, "forkName"> & {forkName: ForkName};
+export function isStatePostAltair(state: IBeaconStateView): state is IBeaconStateViewAltair {
+  return isForkPostAltair(state.forkName);
+}
+
+export function isStatePostBellatrix(state: IBeaconStateView): state is IBeaconStateViewBellatrix {
+  return isForkPostBellatrix(state.forkName);
+}
+
+export function isStatePostCapella(state: IBeaconStateView): state is IBeaconStateViewCapella {
+  return isForkPostCapella(state.forkName);
+}
+
+export function isStatePostDeneb(state: IBeaconStateView): state is IBeaconStateViewDeneb {
+  return isForkPostDeneb(state.forkName);
+}
+
+export function isStatePostElectra(state: IBeaconStateView): state is IBeaconStateViewElectra {
+  return isForkPostElectra(state.forkName);
+}
+
+export function isStatePostFulu(state: IBeaconStateView): state is IBeaconStateViewFulu {
+  return isForkPostFulu(state.forkName);
+}
+
+export function isStatePostGloas(state: IBeaconStateView): state is IBeaconStateViewGloas {
+  return isForkPostGloas(state.forkName);
+}

package/src/stateView/stateViewFactory.ts

@@ -0,0 +1,78 @@
+import {BeaconConfig} from "@lodestar/config";
+import {PubkeyCache, createPubkeyCache} from "../cache/pubkeyCache.js";
+import {createCachedBeaconState} from "../cache/stateCache.js";
+import {BeaconStateAllForks} from "../cache/types.js";
+import {getStateTypeFromBytes} from "../util/sszBytes.js";
+import {BeaconStateView} from "./beaconStateView.js";
+import {IBeaconStateView} from "./interface.js";
+
+// ---- createBeaconStateView (startup path) ----
+
+type NodeJSOpts = {
+  useNative: false;
+  anchorState: BeaconStateAllForks;
+  config: BeaconConfig;
+  pubkeyCache: PubkeyCache;
+};
+
+type NativeOpts = {
+  useNative: true;
+  stateBytes: Uint8Array;
+};
+
+/**
+ * Create a BeaconStateView from a pre-deserialized state. Used at node startup.
+ *
+ * The caller is responsible for creating and populating `pubkeyCache` (it is also
+ * passed separately to BeaconNode.init, so it must live outside this factory).
+ *
+ * Set `useNative: true` to use the native (Zig) implementation once available.
+ */
+export function createBeaconStateView(opts: NodeJSOpts | NativeOpts): IBeaconStateView {
+  if (opts.useNative) {
+    throw new Error("Native (Zig) BeaconStateView not yet implemented");
+  }
+  const {anchorState, config, pubkeyCache} = opts;
+  const cachedState = createCachedBeaconState(anchorState, {config, pubkeyCache}, {skipSyncPubkeys: true});
+  return new BeaconStateView(cachedState);
+}
+
+// ---- createBeaconStateViewForHistoricalRegen (regen path) ----
+
+// Reused across all historical state regen calls in the worker thread
+const pubkeyCacheRegen = createPubkeyCache();
+
+function syncPubkeyCache(state: BeaconStateAllForks, pubkeyCache: PubkeyCache): void {
+  const newCount = state.validators.length;
+  for (let i = pubkeyCache.size; i < newCount; i++) {
+    const pubkey = state.validators.getReadonly(i).pubkey;
+    pubkeyCache.set(i, pubkey);
+  }
+}
+
+type RegenNodeJSOpts = {
+  useNative: false;
+  config: BeaconConfig;
+  stateBytes: Uint8Array;
+};
+
+type RegenNativeOpts = {
+  useNative: true;
+  stateBytes: Uint8Array;
+};
+
+/**
+ * Create a BeaconStateView from raw SSZ bytes. Used in the historical state regen worker thread.
+ *
+ * Set `useNative: true` to use the native (Zig) implementation once available.
+ */
+export function createBeaconStateViewForHistoricalRegen(opts: RegenNodeJSOpts | RegenNativeOpts): IBeaconStateView {
+  if (opts.useNative) {
+    throw new Error("Native (Zig) BeaconStateView not yet implemented");
+  }
+  const {config, stateBytes} = opts;
+  const state = getStateTypeFromBytes(config, stateBytes).deserializeToViewDU(stateBytes);
+  syncPubkeyCache(state, pubkeyCacheRegen);
+  const cachedState = createCachedBeaconState(state, {config, pubkeyCache: pubkeyCacheRegen}, {skipSyncPubkeys: true});
+  return new BeaconStateView(cachedState);
+}

package/src/testUtils/cache.ts

@@ -5,4 +5,4 @@ import {fileURLToPath} from "node:url";
 // Solutions: https://stackoverflow.com/questions/46745014/alternative-for-dirname-in-node-js-when-using-es6-modules
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-export const testCachePath = path.join(__dirname, "../../test/test-cache");
+export const testCachePath = path.join(__dirname, "../../test-cache");