feat: align BeaconStateView to IBeaconStateView

Author: spiral-ladder

bindings/napi/BeaconStateView.zig

@@ -56,9 +56,9 @@ pub const Validator = js.Object(struct {
 });
 
 pub const ProposerRewards = js.Object(struct {
-    attestations: js.BigInt,
-    syncAggregate: js.BigInt,
-    slashing: js.BigInt,
+    attestations: js.Number,
+    syncAggregate: js.Number,
+    slashing: js.Number,
 });
 
 pub const MultiProof = js.Object(struct {

bindings/napi/js_types.zig

@@ -52,5 +52,6 @@ fn register(env: napi.Env, exports: napi.Value) !void {
 }
 
 comptime {
+    @setEvalBranchQuota(1_000_000);
     js.exportModule(@This(), .{ .init = init, .cleanup = cleanup, .register = register });
 }

bindings/napi/root.zig

@@ -22,10 +22,10 @@ else
 /// - dontTransferCache: bool (negated to set transfer_cache)
 ///
 /// This is the double negative version to conform with production lodestar.
-/// TODO(bing): Eventually rename this to `transferCache` to avoid double negation because its confusing naming.
-/// TODO(bing): Other fields (executionPayloadStatus, ..).
-fn parseOptions(options: ?js.Value) !st.TransitionOpt {
-    var transition_opts: st.TransitionOpt = .{};
+/// TODO(bing): Eventually rename `dontTransferCache` to `transferCache` to avoid double negation because its confusing naming.
+fn parseOptions(options: ?js.Value) !st.TransitionOpts {
+    var transition_opts: st.TransitionOpts = .{};
+
     if (options) |value| {
         const raw = value.toValue();
         if (try raw.typeof() == .object) {

bindings/napi/stateTransition.zig

@@ -43,6 +43,17 @@ interface Fork {
   epoch: number;
 }
 
+enum ForkName {
+  phase0 = "phase0",
+  altair = "altair",
+  bellatrix = "bellatrix",
+  capella = "capella",
+  deneb = "deneb",
+  electra = "electra",
+  fulu = "fulu",
+  gloas = "gloas",
+}
+
 interface SyncCommittee {
   pubkeys: Uint8Array;
   aggregatePubkey: Uint8Array;
@@ -54,7 +65,8 @@ interface ProcessSlotsOpts {
 }
 
 interface CompactMultiProof {
-  type: "compactMulti";
+  // biome-ignore lint/suspicious/noExplicitAny: native returns string literal "compactMulti", IBeaconStateView uses @chainsafe/persistent-merkle-tree's ProofType enum nominally
+  type: any;
   leaves: Uint8Array[];
   descriptor: Uint8Array;
 }
@@ -74,20 +86,27 @@ interface TransitionOpts {
   verifySignatures?: boolean;
   /** Default: false (cache is transferred). Set to true to opt out of cache transfer. */
   dontTransferCache?: boolean;
-  /** Other fields (executionPayloadStatus, dataAvailabilityStatus, metrics, validatorMonitor, …) */
-  [extra: string]: unknown;
 }
 
 interface ProposerRewards {
-  attestations: bigint;
-  syncAggregate: bigint;
-  slashing: bigint;
+  attestations: number;
+  syncAggregate: number;
+  slashing: number;
 }
 
 interface SyncCommitteeCache {
   validatorIndices: number[];
 }
 
+interface EpochShuffling {
+  epoch: number;
+  activeIndices: Uint32Array;
+  shuffling: Uint32Array;
+  /** committees[slotInEpoch][committeeIndex] -> validator indices */
+  committees: Uint32Array[][];
+  committeesPerSlot: number;
+}
+
 interface HistoricalSummary {
   blockSummaryRoot: Uint8Array;
   stateSummaryRoot: Uint8Array;
@@ -134,6 +153,7 @@ declare class BeaconStateView {
 
   slot: number;
   fork: Fork;
+  forkName: ForkName;
   epoch: number;
   genesisTime: number;
   genesisValidatorsRoot: Uint8Array;
@@ -142,11 +162,17 @@ declare class BeaconStateView {
   previousJustifiedCheckpoint: Checkpoint;
   currentJustifiedCheckpoint: Checkpoint;
   finalizedCheckpoint: Checkpoint;
-  getBlockRoot(slot: number): Uint8Array;
+  getBlockRoot(epoch: number): Uint8Array;
+  getBlockRootAtSlot(slot: number): Uint8Array;
+  getBlockRootAtEpoch(epoch: number): Uint8Array;
+  getStateRootAtSlot(slot: number): Uint8Array;
   getRandaoMix(epoch: number): Uint8Array;
-  previousEpochParticipation: number[];
-  currentEpochParticipation: number[];
+  previousEpochParticipation: Uint8Array;
+  currentEpochParticipation: Uint8Array;
+  getPreviousEpochParticipation(index: number): number;
+  getCurrentEpochParticipation(index: number): number;
   latestExecutionPayloadHeader: ExecutionPayloadHeader;
+  payloadBlockNumber: number;
   historicalSummaries: HistoricalSummary[];
   pendingDeposits: Uint8Array;
   pendingDepositsCount: number;
@@ -157,12 +183,35 @@ declare class BeaconStateView {
   proposerLookahead: Uint32Array;
   // executionPayloadAvailability: boolean[];
 
-  // getShufflingAtEpoch(epoch: number): EpochShuffling;
-  previousDecisionRoot: Uint8Array;
-  currentDecisionRoot: Uint8Array;
-  nextDecisionRoot: Uint8Array;
-  // TODO wrong return type
-  getShufflingDecisionRoot(epoch: number): Uint8Array;
+  // Gloas-only — throw "not available before Gloas" when called pre-Gloas.
+  latestBlockHash: Uint8Array;
+  // TODO(bing): type this once we support gloas
+  // biome-ignore lint/suspicious/noExplicitAny: gloas stub
+  executionPayloadAvailability: any;
+  // TODO(bing): type this once we support gloas
+  // biome-ignore lint/suspicious/noExplicitAny: gloas stub
+  latestExecutionPayloadBid: any;
+  // TODO(bing): type this once we support gloas
+  // biome-ignore lint/suspicious/noExplicitAny: gloas stub
+  payloadExpectedWithdrawals: any[];
+  // TODO(bing): type this once we support gloas
+  // biome-ignore lint/suspicious/noExplicitAny: gloas stub
+  getBuilder(index: number): any;
+  canBuilderCoverBid(builderIndex: number, bidAmount: number): boolean;
+  getEpochPTCs(epoch: number): Uint32Array[];
+  getIndexInPayloadTimelinessCommittee(validatorIndex: number, slot: number): number;
+  // TODO(bing): type this once we support gloas
+  // biome-ignore lint/suspicious/noExplicitAny: gloas stub
+  getExpectedWithdrawalsForFullParent(executionRequests: any): any[];
+
+  getShufflingAtEpoch(epoch: number): EpochShuffling;
+  getPreviousShuffling(): EpochShuffling;
+  getCurrentShuffling(): EpochShuffling;
+  getNextShuffling(): EpochShuffling;
+  previousDecisionRoot: string;
+  currentDecisionRoot: string;
+  nextDecisionRoot: string;
+  getShufflingDecisionRoot(epoch: number): string;
   previousProposers: number[] | null;
   currentProposers: number[];
   nextProposers: number[];
@@ -172,58 +221,103 @@ declare class BeaconStateView {
   currentSyncCommitteeIndexed: SyncCommitteeCache;
   syncProposerReward: number;
   getIndexedSyncCommitteeAtEpoch(epoch: number): SyncCommitteeCache;
+  getIndexedSyncCommittee(slot: number): SyncCommitteeCache;
 
   effectiveBalanceIncrements: Uint16Array;
   getEffectiveBalanceIncrementsZeroInactive(): Uint16Array;
-  getBalance(index: number): bigint;
+  getBalance(index: number): number;
   getValidator(index: number): Validator;
+  getAllValidators(): Validator[];
+  getAllBalances(): number[];
+  getValidatorsByStatus(statuses: Set<string>, currentEpoch: number): Validator[];
   // TODO wrong function
   getValidatorStatus(index: number): ValidatorStatus;
   validatorCount: number;
   activeValidatorCount: number;
 
   isExecutionStateType: boolean;
   isMergeTransitionComplete: boolean;
-  // TODO remove
-  isExecutionEnabled(fork: string, signedBlockBytes: Uint8Array): boolean;
+  /** True iff state is pre-merge AND the given block carries a non-default execution payload. Bellatrix-only. */
+  isMergeTransitionBlock(signedBlockBytes: Uint8Array): boolean;
+  /**
+   * Spec: `is_execution_enabled(state, body) = is_merge_transition_complete(state) or is_merge_transition_block(state, body)`.
+   * Fast path for post-merge states (no SSZ work); deserializes only on the rare pre-merge bellatrix path.
+   */
+  isExecutionEnabled(signedBlockBytes: Uint8Array): boolean;
 
   // getExpectedWithdrawals(): ExpectedWithdrawals;
 
   proposerRewards: ProposerRewards;
-  // computeBlockRewards(block: BeaconBlock, proposerRewards: RewardsCache): BlockRewards;
-  // computeAttestationRewards(validatorIds?: (number | string)[]): AttestationRewards;
-  // computeSyncCommitteeRewards(block: BeaconBlock, validatorIds?: (number | string)[]): SyncCommitteeRewards;
-  // getLatestWeakSubjectivityCheckpointEpoch(): number;
+  // biome-ignore lint/suspicious/noExplicitAny: stub
+  // TODO(bing): This is stubbed and untyped until we implement the beacon node rewards endpoints
+  computeBlockRewards(block: any, proposerRewards?: any): Promise<any>;
+  // biome-ignore lint/suspicious/noExplicitAny: stub
+  // TODO(bing): This is stubbed and untyped until we implement the beacon node rewards endpoints
+  computeAttestationsRewards(validatorIds?: (number | string)[]): Promise<any>;
+  // TODO(bing): This is stubbed and untyped until we implement the beacon node rewards endpoints
+  // biome-ignore lint/suspicious/noExplicitAny: stub
+  computeSyncCommitteeRewards(block: any, validatorIds: (number | string)[]): Promise<any>;
+  getLatestWeakSubjectivityCheckpointEpoch(): number;
 
-  getVoluntaryExitValidity(signedVoluntaryExitBytes: Uint8Array, verifySignature: boolean): VoluntaryExitValidity;
-  isValidVoluntaryExit(signedVoluntaryExitBytes: Uint8Array, verifySignature: boolean): boolean;
+  /**
+   * Native walks the JS `phase0.SignedVoluntaryExit` shape directly.
+   * Return is the string union `VoluntaryExitValidity` at runtime, but lodestar's
+   * matching TS enum is nominally typed — `any` to satisfy structural conformance.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: TS-nominal-enum mismatch (runtime values match exactly)
+  getVoluntaryExitValidity(
+    signedVoluntaryExit: {message: {epoch: number; validatorIndex: number}; signature: Uint8Array},
+    verifySignature: boolean
+  ): any;
+  isValidVoluntaryExit(
+    signedVoluntaryExit: {message: {epoch: number; validatorIndex: number}; signature: Uint8Array},
+    verifySignature: boolean
+  ): boolean;
 
   getFinalizedRootProof(): Uint8Array[];
-  // getSyncCommitteesWitness(): SyncCommitteeWitness;
-  getSingleProof(gindex: number): Uint8Array[];
+  // biome-ignore lint/suspicious/noExplicitAny: stub
+  getSyncCommitteesWitness(): any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub
+  getExpectedWithdrawals(): any;
+  // biome-ignore lint/suspicious/noExplicitAny: native takes number, IBeaconStateView declares bigint
+  getSingleProof(gindex: any): Uint8Array[];
   // createMultiProof(descriptor: Uint8Array): CompactMultiProof;
 
   computeUnrealizedCheckpoints(): {
     justifiedCheckpoint: Checkpoint;
     finalizedCheckpoint: Checkpoint;
   };
+  computeAnchorCheckpoint(): {
+    checkpoint: Checkpoint;
+    blockHeader: BeaconBlockHeader;
+  };
 
   clonedCount: number;
   clonedCountWithTransferCache: number;
   createdWithTransferCache: boolean;
-  // isStateValidatorsNodesPopulated(): boolean;
+  isStateValidatorsNodesPopulated(): boolean;
 
-  // loadOtherState(stateBytes: Uint8Array, seedValidatorsBytes?: Uint8Array): void;
+  // biome-ignore lint/suspicious/noExplicitAny: stub
+  loadOtherState(
+    stateBytes: Uint8Array,
+    seedValidatorsBytes?: Uint8Array,
+    opts?: {preloadValidatorsAndBalances?: boolean}
+  ): any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub
+  toValue(): any;
   serialize(): Uint8Array;
   serializedSize(): number;
-  serializeToBytes(output: Uint8Array, offset: number): number;
+  /** Takes a `@chainsafe/ssz` ByteViews `{uint8Array, dataView}`; native uses `uint8Array` only. */
+  serializeToBytes(output: {uint8Array: Uint8Array; dataView: DataView}, offset: number): number;
   serializeValidators(): Uint8Array;
   serializedValidatorsSize(): number;
-  serializeValidatorsToBytes(output: Uint8Array, offset: number): number;
+  /** Same shape as `serializeToBytes`. */
+  serializeValidatorsToBytes(output: {uint8Array: Uint8Array; dataView: DataView}, offset: number): number;
   hashTreeRoot(): Uint8Array;
   createMultiProof(descriptor: Uint8Array): CompactMultiProof;
 
-  // stateTransition(signedBlockBytes: Uint8Array): BeaconStateView;
+  // biome-ignore lint/suspicious/noExplicitAny: signed block bytes are passed as Uint8Array at runtime; signature is loosened so it satisfies `IBeaconStateView.stateTransition(block, opts, modules)` structurally.
+  stateTransition(signedBlock: any, options?: any, modules?: any): BeaconStateView;
   processSlots(slot: number, options?: ProcessSlotsOpts): BeaconStateView;
 }
 

bindings/src/index.d.ts

@@ -307,6 +307,7 @@
                     .config,
                     .fork_types,
                     .state_transition,
+                    .hex,
                     "zapi:zapi",
                 },
             },

build.zig.zon

@@ -87,6 +87,7 @@ pub const AnchorCheckpoint = @import("./AnchorCheckpoint.zig");
 pub const deinitStateTransition = @import("./state_transition.zig").deinitStateTransition;
 pub const isExecutionEnabled = @import("./utils/execution.zig").isExecutionEnabled;
 pub const isMergeTransitionComplete = @import("./utils/execution.zig").isMergeTransitionComplete;
+pub const isMergeTransitionBlock = @import("./utils/execution.zig").isMergeTransitionBlock;
 pub const getRandaoMix = @import("./utils/seed.zig").getRandaoMix;
 pub const getEffectiveBalanceIncrementsZeroInactive = @import("./utils/balance.zig").getEffectiveBalanceIncrementsZeroInactive;
 

src/state_transition/root.zig

@@ -26,7 +26,7 @@ pub fn isMergeTransitionBlock(
     comptime fork: ForkSeq,
     state: *BeaconState(fork),
     comptime block_type: BlockType,
-    body: *const BeaconBlockBody(fork, block_type),
+    body: *const BeaconBlockBody(block_type, fork),
 ) bool {
     if (comptime fork != .bellatrix) {
         return false;