@lodestar/state-transition 1.50.0-dev.11028e782c → 1.50.0-dev.15ca1827f4

package/src/stateView/interface.ts

@@ -55,10 +55,13 @@ import {StateTransitionModules, StateTransitionOpts} from "../stateTransition.js
 import {EpochShuffling} from "../util/epochShuffling.js";
 import {PreVerifyBuilderDepositsResult} from "../util/preVerifyBuilderDeposits.js";
 
-/** Inputs for computing the state root of a locally produced block. */
-export type ComputeNewStateRootInput = {
+/** Signed block to apply in a state transition. */
+export type BlockSTFInput = {
   block: SignedBeaconBlock | SignedBlindedBeaconBlock;
-  /** Pre-serialized block bytes for native implementations. */
+  /**
+   * Fork-specific SSZ serialization of `block`, using the matching full or blinded block type. Native
+   * implementations serialize `block` when omitted.
+   */
   ssz?: Uint8Array;
 };
 
@@ -159,6 +162,13 @@ export interface IBeaconStateView {
   // TODO is there a better name that is less implementation specific but still conveys the meaning?
   isStateValidatorsNodesPopulated(): boolean;
 
+  // Lifecycle
+  /**
+   * Release resources owned by this view.
+   * Do not use the view after calling this method.
+   */
+  release(): void;
+
   // Serialization
   /** Set `preloadValidatorsAndBalances` only when the whole state will be consumed
    *  immediately (e.g. CP reload before block replay). */
@@ -178,9 +188,9 @@ export interface IBeaconStateView {
   hashTreeRoot(): Uint8Array;
 
   // State transition
-  computeNewStateRoot(input: ComputeNewStateRootInput, modules: StateTransitionModules): ComputeNewStateRootResult;
+  computeNewStateRoot(input: BlockSTFInput, modules: StateTransitionModules): ComputeNewStateRootResult;
   stateTransition(
-    signedBlock: SignedBeaconBlock | SignedBlindedBeaconBlock,
+    input: BlockSTFInput,
     options: StateTransitionOpts,
     modules: StateTransitionModules
   ): IBeaconStateView;
@@ -317,33 +327,63 @@ export type IBeaconStateViewLatestFork = Omit<
 /**
  * Contract a BeaconStateView backing implementation must satisfy.
  *
- * Differs from `IBeaconStateViewLatestFork` in two ways:
- * - `executionPayloadAvailability` is a raw `{uint8Array, bitLen}` POJO — a
- *   native (`.node`) binding cannot construct a `BitArray` across FFI.
- *   `NativeBeaconStateView` lifts it back to `BitArray` for beacon-node.
- * - Methods that produce another view (`stateTransition`, `processSlots`,
- *   `loadOtherState`, `withParentPayloadApplied`) return `IBeaconStateViewNative`
- *   so callers can re-wrap without an `as unknown` cast. Param lists are reused
- *   via `Parameters<...>` to avoid duplicating signatures.
- * - `computeNewStateRoot` is implemented by the wrapper because its inputs differ
- *   between the TypeScript and Zig implementations.
- *
- * The TS-side `BeaconStateView` also structurally satisfies this contract since
- * `BitArray` exposes `uint8Array` and `bitLen`.
+ * Differs from `IBeaconStateViewLatestFork` in these ways:
+ * - SSZ-backed lists use serialized bytes or native typed arrays at the FFI boundary.
+ * - Methods that produce another view return `IBeaconStateViewNative` so callers can re-wrap them.
+ * - `stateTransition` accepts the native block inputs and omits JS-only modules.
+ * - `computeNewStateRoot` is implemented by the wrapper because its inputs differ between implementations.
  */
 export type IBeaconStateViewNative = Omit<
   IBeaconStateViewLatestFork,
+  | "builderPendingPayments"
+  | "builderPendingWithdrawals"
+  | "computeAttestationsRewards"
+  | "computeBlockRewards"
   | "computeNewStateRoot"
+  | "computeSyncCommitteeRewards"
+  | "eth1Data"
   | "executionPayloadAvailability"
+  | "getBeaconCommittee"
+  | "getIndicesInPayloadTimelinessCommittee"
+  | "getPayloadTimelinessCommittee"
   | "loadOtherState"
-  | "stateTransition"
+  | "pendingConsolidations"
+  | "pendingDeposits"
+  | "pendingPartialWithdrawals"
+  | "preVerifyBuilderDepositsPreGloas"
+  | "clearPreGloasBuilderDepositCache"
   | "processSlots"
+  | "proposerLookahead"
+  | "stateTransition"
   | "withParentPayloadApplied"
 > & {
+  pendingDeposits: Uint8Array;
+  pendingPartialWithdrawals: Uint8Array;
+  pendingConsolidations: Uint8Array;
+  proposerLookahead: Uint32Array;
+  // UintBn64 lowers to number across the FFI boundary; the wrapper lifts it back to bigint
+  eth1Data: phase0.Eth1Data;
   executionPayloadAvailability: {uint8Array: Uint8Array; bitLen: number};
+  computeBlockRewards(
+    signedBlockBytes: Uint8Array,
+    isBlinded: boolean,
+    proposerRewards?: RewardCache
+  ): rewards.BlockRewards;
+  computeAttestationsRewards(validatorIds?: (ValidatorIndex | string)[]): rewards.AttestationsRewards;
+  computeSyncCommitteeRewards(
+    block: BeaconBlock,
+    validatorIds: (ValidatorIndex | string)[]
+  ): rewards.SyncCommitteeRewards;
+  getBeaconCommittee(slot: Slot, index: CommitteeIndex): Uint32Array;
+  getIndexInPayloadTimelinessCommittee?(validatorIndex: ValidatorIndex, slot: Slot): number;
+  getIndicesInPayloadTimelinessCommittee?(validatorIndex: ValidatorIndex, slot: Slot): number[];
   loadOtherState(...args: Parameters<IBeaconStateViewLatestFork["loadOtherState"]>): IBeaconStateViewNative;
-  stateTransition(...args: Parameters<IBeaconStateViewLatestFork["stateTransition"]>): IBeaconStateViewNative;
-  processSlots(...args: Parameters<IBeaconStateViewLatestFork["processSlots"]>): IBeaconStateViewNative;
+  stateTransition(
+    signedBlockBytes: Uint8Array,
+    isBlinded: boolean,
+    options?: StateTransitionOpts
+  ): IBeaconStateViewNative;
+  processSlots(slot: Slot, opts?: {dontTransferCache?: boolean}): IBeaconStateViewNative;
   withParentPayloadApplied(
     ...args: Parameters<IBeaconStateViewLatestFork["withParentPayloadApplied"]>
   ): IBeaconStateViewNative;