@lodestar/state-transition 1.49.0 → 1.50.0-dev.023ad6c012

package/src/stateView/interface.ts

@@ -277,6 +277,8 @@ export interface IBeaconStateViewGloas extends IBeaconStateViewFulu {
   executionPayloadAvailability: BitArray;
   latestExecutionPayloadBid: ExecutionPayloadBid;
   payloadExpectedWithdrawals: capella.Withdrawal[];
+  builderPendingPayments: gloas.BuilderPendingPayments;
+  builderPendingWithdrawals: gloas.BuilderPendingWithdrawals;
   getBuilder(index: BuilderIndex): gloas.Builder;
   getBuildersLength(): number;
   canBuilderCoverBid(builderIndex: BuilderIndex, bidAmount: number): boolean;

package/src/stateView/nativeBeaconStateView.ts

@@ -118,6 +118,8 @@ export class NativeBeaconStateView implements IBeaconStateViewLatestFork {
   private _latestBlockHash: Bytes32 | null = null;
   private _latestExecutionPayloadBid: ExecutionPayloadBid | null = null;
   private _payloadExpectedWithdrawals: capella.Withdrawal[] | null = null;
+  private _builderPendingPayments: gloas.BuilderPendingPayments | null = null;
+  private _builderPendingWithdrawals: gloas.BuilderPendingWithdrawals | null = null;
 
   // Per-argument caches for argument-taking methods. The binding is treated as
   // immutable for the view's lifetime, so a given argument always yields the
@@ -892,6 +894,20 @@ export class NativeBeaconStateView implements IBeaconStateViewLatestFork {
     return this._payloadExpectedWithdrawals;
   }
 
+  get builderPendingPayments(): gloas.BuilderPendingPayments {
+    if (this._builderPendingPayments === null) {
+      this._builderPendingPayments = this.binding.builderPendingPayments;
+    }
+    return this._builderPendingPayments;
+  }
+
+  get builderPendingWithdrawals(): gloas.BuilderPendingWithdrawals {
+    if (this._builderPendingWithdrawals === null) {
+      this._builderPendingWithdrawals = this.binding.builderPendingWithdrawals;
+    }
+    return this._builderPendingWithdrawals;
+  }
+
   getBuilder(index: BuilderIndex): gloas.Builder {
     let cached = this._getBuilder.get(index);
     if (cached === undefined) {

package/src/stateView/stateViewFactory.ts

@@ -1,40 +1,33 @@
-import {type PubkeyCache, pubkeyCache} from "@chainsafe/lodestar-z/pubkeys";
+import {pubkeyCache} from "@chainsafe/lodestar-z/pubkeys";
 import {BeaconConfig} from "@lodestar/config";
 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;
+type CreateBeaconStateViewOpts = {
+  useNative: boolean;
   config: BeaconConfig;
-  pubkeyCache: PubkeyCache;
-};
-
-type NativeOpts = {
-  useNative: true;
   stateBytes: Uint8Array;
 };
 
 /**
- * Create a BeaconStateView from a pre-deserialized state. Used at node startup.
+ * Create a BeaconStateView from raw SSZ bytes. 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).
+ * Caller must reserve pubkey capacity before calling this function.
  *
  * Set `useNative: true` to use the native (Zig) implementation once available.
  */
-export function createBeaconStateView(opts: NodeJSOpts | NativeOpts): IBeaconStateView {
+export function createBeaconStateView(opts: CreateBeaconStateViewOpts): IBeaconStateView {
   if (opts.useNative) {
     throw new Error("Native (Zig) BeaconStateView not yet implemented");
     // TODO: return a new instance of NativeBeaconStateView
   }
-  const {anchorState, config, pubkeyCache} = opts;
-  const cachedState = createCachedBeaconState(anchorState, {config, pubkeyCache}, {skipSyncPubkeys: true});
+  const {config, stateBytes} = opts;
+  const state = getStateTypeFromBytes(config, stateBytes).deserializeToViewDU(stateBytes);
+  const cachedState = createCachedBeaconState(state, {config, pubkeyCache}, {skipSyncPubkeys: false});
   return new BeaconStateView(cachedState);
 }
 

package/src/util/gloas.ts

@@ -178,21 +178,6 @@ export function initiateBuilderExit(state: CachedBeaconStateGloas, builderIndex:
   builder.withdrawableEpoch = currentEpoch + state.config.MIN_BUILDER_WITHDRAWABILITY_DELAY;
 }
 
-/**
- * Find the index of a builder by their public key.
- * Returns null if not found.
- *
- * May consider builder pubkey cache if performance becomes an issue.
- */
-export function findBuilderIndexByPubkey(state: CachedBeaconStateGloas, pubkey: Uint8Array): BuilderIndex | null {
-  for (let i = 0; i < state.builders.length; i++) {
-    if (byteArrayEquals(state.builders.getReadonly(i).pubkey, pubkey)) {
-      return i;
-    }
-  }
-  return null;
-}
-
 /**
  * Use cached block roots to avoid repeated state root lookups while matching the spec's is_attestation_same_slot behavior.
  */
@@ -248,41 +233,6 @@ export function getPtcWindowEpochCacheData(state: CachedBeaconStateGloas): {
   };
 }
 
-/**
- * Add a new builder to the builders registry. Reuses slots from exited and fully withdrawn
- * builders when available, otherwise appends.
- *
- * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/gloas/beacon-chain.md#new-add_builder_to_registry
- */
-export function addBuilderToRegistry(
-  state: CachedBeaconStateGloas,
-  pubkey: Uint8Array,
-  version: number,
-  executionAddress: Uint8Array,
-  amount: number,
-  slot: number
-): void {
-  const currentEpoch = computeEpochAtSlot(state.slot);
-  const depositEpoch = computeEpochAtSlot(slot);
-
-  let builderIndex = state.builders.length;
-  for (let i = 0; i < state.builders.length; i++) {
-    const builder = state.builders.getReadonly(i);
-    if (builder.withdrawableEpoch <= currentEpoch && builder.balance === 0) {
-      builderIndex = i;
-      break;
-    }
-  }
-
-  const newBuilder = createBuilderView(pubkey, version, executionAddress, amount, depositEpoch);
-
-  if (builderIndex < state.builders.length) {
-    state.builders.set(builderIndex, newBuilder);
-  } else {
-    state.builders.push(newBuilder);
-  }
-}
-
 /**
  * Append a new builder to the registry without scanning for a reusable slot.
  *
@@ -301,10 +251,9 @@ export function appendBuilderToRegistry(
 }
 
 /**
- * Build a Builder view for registry insertion. Shared by the scan-based {@link addBuilderToRegistry}
- * and the append-only {@link appendBuilderToRegistry} so both paths produce an identical view.
+ * Build a Builder view from builder fields.
  */
-function createBuilderView(
+export function createBuilderView(
   pubkey: Uint8Array,
   version: number,
   executionAddress: Uint8Array,

package/src/util/index.ts

@@ -28,6 +28,12 @@ export * from "./signatureSets.js";
 export * from "./signingRoot.js";
 export * from "./slot.js";
 export * from "./ssz.js";
+export {
+  type StateBytesMetadata,
+  getValidatorCountFromStateBytes,
+  getValidatorPubkeyFromStateBytes,
+  readBeaconStateBytesMetadata,
+} from "./sszBytes.js";
 export * from "./syncCommittee.js";
 export * from "./validator.js";
 export * from "./weakSubjectivity.js";

package/src/util/sszBytes.ts

@@ -1,32 +1,31 @@
 import {ChainForkConfig} from "@lodestar/config";
-import {ForkAll, ForkSeq} from "@lodestar/params";
-import {SSZTypesFor, Slot} from "@lodestar/types";
+import {EFFECTIVE_BALANCE_INCREMENT, ForkAll, ForkSeq} from "@lodestar/params";
+import {Epoch, SSZTypesFor, Slot, ssz} from "@lodestar/types";
 import {bytesToInt} from "@lodestar/utils";
 
-/**
- * Slot	uint64
- */
-const SLOT_BYTE_COUNT = 8;
+const UINT64_SIZE = 8;
+const ROOT_SIZE = 32;
 
 /**
- * 48 + 32 + 8 + 1 + 8 + 8 + 8 + 8 = 121
  * ```
  * class Validator(Container):
-    pubkey: BLSPubkey [fixed - 48 bytes]
-    withdrawal_credentials: Bytes32 [fixed - 32 bytes]
-    effective_balance: Gwei [fixed - 8 bytes]
-    slashed: boolean [fixed - 1 byte]
-    # Status epochs
-    activation_eligibility_epoch: Epoch [fixed - 8 bytes]
-    activation_epoch: Epoch [fixed - 8 bytes]
-    exit_epoch: Epoch [fixed - 8 bytes]
-    withdrawable_epoch: Epoch [fixed - 8 bytes]
-  ```
+ *   pubkey: BLSPubkey [fixed - 48 bytes]
+ *   withdrawal_credentials: Bytes32 [fixed - 32 bytes]
+ *   effective_balance: Gwei [fixed - 8 bytes]
+ *   slashed: boolean [fixed - 1 byte]
+ *   activation_eligibility_epoch: Epoch [fixed - 8 bytes]
+ *   activation_epoch: Epoch [fixed - 8 bytes]
+ *   exit_epoch: Epoch [fixed - 8 bytes]
+ *   withdrawable_epoch: Epoch [fixed - 8 bytes]
+ * ```
  */
-export const VALIDATOR_BYTES_SIZE = 121;
+const PUBKEY_SIZE = 48;
+const VALIDATOR_EFFECTIVE_BALANCE_OFFSET = PUBKEY_SIZE + ROOT_SIZE;
+const VALIDATOR_ACTIVATION_EPOCH_OFFSET = VALIDATOR_EFFECTIVE_BALANCE_OFFSET + UINT64_SIZE + 1 + UINT64_SIZE;
+const VALIDATOR_EXIT_EPOCH_OFFSET = VALIDATOR_ACTIVATION_EPOCH_OFFSET + UINT64_SIZE;
+export const VALIDATOR_BYTES_SIZE = VALIDATOR_EXIT_EPOCH_OFFSET + UINT64_SIZE + UINT64_SIZE;
 
 /**
- * 8 + 32 = 40
  * ```
  * class BeaconState(Container):
  *   genesis_time: uint64 [fixed - 8 bytes]
@@ -35,10 +34,12 @@ export const VALIDATOR_BYTES_SIZE = 121;
  *   ...
  * ```
  */
-const SLOT_BYTES_POSITION_IN_STATE = 40;
+const STATE_GENESIS_TIME_OFFSET = 0;
+const STATE_GENESIS_VALIDATORS_ROOT_OFFSET = STATE_GENESIS_TIME_OFFSET + UINT64_SIZE;
+const STATE_SLOT_OFFSET = STATE_GENESIS_VALIDATORS_ROOT_OFFSET + ROOT_SIZE;
 
 export function getForkFromStateBytes(config: ChainForkConfig, bytes: Uint8Array): ForkSeq {
-  const slot = bytesToInt(bytes.subarray(SLOT_BYTES_POSITION_IN_STATE, SLOT_BYTES_POSITION_IN_STATE + SLOT_BYTE_COUNT));
+  const slot = bytesToInt(bytes.subarray(STATE_SLOT_OFFSET, STATE_SLOT_OFFSET + UINT64_SIZE));
   return config.getForkSeq(slot);
 }
 
@@ -48,5 +49,111 @@ export function getStateTypeFromBytes(config: ChainForkConfig, bytes: Uint8Array
 }
 
 export function getStateSlotFromBytes(bytes: Uint8Array): Slot {
-  return bytesToInt(bytes.subarray(SLOT_BYTES_POSITION_IN_STATE, SLOT_BYTES_POSITION_IN_STATE + SLOT_BYTE_COUNT));
+  return bytesToInt(bytes.subarray(STATE_SLOT_OFFSET, STATE_SLOT_OFFSET + UINT64_SIZE));
+}
+
+export type StateBytesMetadata = {slot: Slot; genesisTime: number; genesisValidatorsRoot: Uint8Array};
+
+export function readBeaconStateBytesMetadata(bytes: Uint8Array): StateBytesMetadata | null {
+  if (bytes.length < STATE_SLOT_OFFSET + UINT64_SIZE) {
+    return null;
+  }
+  const data = {uint8Array: bytes, dataView: new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)};
+  return {
+    genesisTime: ssz.UintNum64.value_deserializeFromBytes(
+      data,
+      STATE_GENESIS_TIME_OFFSET,
+      STATE_GENESIS_TIME_OFFSET + UINT64_SIZE
+    ),
+    genesisValidatorsRoot: Uint8Array.from(
+      bytes.subarray(STATE_GENESIS_VALIDATORS_ROOT_OFFSET, STATE_GENESIS_VALIDATORS_ROOT_OFFSET + ROOT_SIZE)
+    ),
+    slot: ssz.Slot.value_deserializeFromBytes(data, STATE_SLOT_OFFSET, STATE_SLOT_OFFSET + UINT64_SIZE),
+  };
+}
+
+/** Read only the validator fields needed for weak subjectivity, without allocating validator objects. */
+export function scanActiveValidatorsFromStateBytes(
+  stateBytes: Uint8Array,
+  stateType: SSZTypesFor<ForkAll, "BeaconState">,
+  epoch: Epoch
+): {activeValidatorCount: number; totalActiveBalanceIncrements: number} | null {
+  const range = getValidatorsRangeFromStateBytes(stateBytes, stateType);
+  if (range === null) {
+    return null;
+  }
+
+  const data = {
+    uint8Array: stateBytes,
+    dataView: new DataView(stateBytes.buffer, stateBytes.byteOffset, stateBytes.byteLength),
+  };
+  let activeValidatorCount = 0;
+  let totalActiveBalanceIncrements = 0;
+  for (let offset = range.start; offset < range.end; offset += VALIDATOR_BYTES_SIZE) {
+    const activationEpoch = ssz.EpochInf.value_deserializeFromBytes(
+      data,
+      offset + VALIDATOR_ACTIVATION_EPOCH_OFFSET,
+      offset + VALIDATOR_ACTIVATION_EPOCH_OFFSET + UINT64_SIZE
+    );
+    const exitEpoch = ssz.EpochInf.value_deserializeFromBytes(
+      data,
+      offset + VALIDATOR_EXIT_EPOCH_OFFSET,
+      offset + VALIDATOR_EXIT_EPOCH_OFFSET + UINT64_SIZE
+    );
+    if (activationEpoch <= epoch && epoch < exitEpoch) {
+      activeValidatorCount++;
+      const effectiveBalance = ssz.UintNum64.value_deserializeFromBytes(
+        data,
+        offset + VALIDATOR_EFFECTIVE_BALANCE_OFFSET,
+        offset + VALIDATOR_EFFECTIVE_BALANCE_OFFSET + UINT64_SIZE
+      );
+      totalActiveBalanceIncrements += Math.floor(effectiveBalance / EFFECTIVE_BALANCE_INCREMENT);
+    }
+  }
+  return {activeValidatorCount, totalActiveBalanceIncrements: Math.max(1, totalActiveBalanceIncrements)};
+}
+
+export function getValidatorCountFromStateBytes(config: ChainForkConfig, stateBytes: Uint8Array): number | null {
+  const range = getValidatorsRangeFromStateBytes(stateBytes, getStateTypeFromBytes(config, stateBytes));
+  // A non-null range always holds a whole number of validator records, so the division is exact
+  return range === null ? null : (range.end - range.start) / VALIDATOR_BYTES_SIZE;
+}
+
+/** Returns a view into `stateBytes`, or null if the index is not in the registry. */
+export function getValidatorPubkeyFromStateBytes(
+  config: ChainForkConfig,
+  stateBytes: Uint8Array,
+  index: number
+): Uint8Array | null {
+  const range = getValidatorsRangeFromStateBytes(stateBytes, getStateTypeFromBytes(config, stateBytes));
+  if (range === null) {
+    return null;
+  }
+  const start = range.start + index * VALIDATOR_BYTES_SIZE;
+  if (index < 0 || start >= range.end) {
+    return null;
+  }
+  return stateBytes.subarray(start, start + PUBKEY_SIZE);
+}
+
+function getValidatorsRangeFromStateBytes(
+  stateBytes: Uint8Array,
+  stateType: SSZTypesFor<ForkAll, "BeaconState">
+): {start: number; end: number} | null {
+  let range: {start: number; end: number};
+  try {
+    const containerType = stateType as (typeof ssz)[ForkAll]["BeaconState"];
+    const dataView = new DataView(stateBytes.buffer, stateBytes.byteOffset, stateBytes.byteLength);
+    const ranges = containerType.getFieldRanges(dataView, 0, stateBytes.length);
+    range = ranges[Object.keys(containerType.fields).indexOf("validators")];
+  } catch {
+    return null;
+  }
+  if (!range || range.start < 0 || range.end > stateBytes.length || range.end < range.start) {
+    return null;
+  }
+  if ((range.end - range.start) % VALIDATOR_BYTES_SIZE !== 0) {
+    return null;
+  }
+  return range;
 }

package/src/util/weakSubjectivity.ts

@@ -1,20 +1,19 @@
-import {BeaconConfig, ChainForkConfig} from "@lodestar/config";
+import {ChainForkConfig} from "@lodestar/config";
 import {
   EFFECTIVE_BALANCE_INCREMENT,
   ForkSeq,
+  GENESIS_SLOT,
   MAX_DEPOSITS,
   MAX_EFFECTIVE_BALANCE,
   SLOTS_PER_EPOCH,
   isForkPostElectra,
   isForkPostGloas,
 } from "@lodestar/params";
-import {Epoch, Root, ssz} from "@lodestar/types";
-import {Checkpoint} from "@lodestar/types/phase0";
-import {toRootHex} from "@lodestar/utils";
+import {Epoch, Root, Slot, TimeSeconds, ssz} from "@lodestar/types";
 import {ZERO_HASH} from "../constants/constants.js";
 import {BeaconStateAllForks, CachedBeaconStateAllForks} from "../types.js";
 import {computeCheckpointEpochAtStateSlot, computeEpochAtSlot, getCurrentEpoch} from "./epoch.js";
-import {getCurrentSlot} from "./slot.js";
+import {StateBytesMetadata, getStateTypeFromBytes, scanActiveValidatorsFromStateBytes} from "./sszBytes.js";
 import {
   getActivationChurnLimit,
   getActiveValidatorIndices,
@@ -79,12 +78,10 @@ export function computeWeakSubjectivityPeriodCachedState(
 
 /**
  * Same to computeWeakSubjectivityPeriodCachedState but for normal state
- * This is called only 1 time at app startup so it's ok to calculate totalActiveBalanceIncrements manually
  */
 export function computeWeakSubjectivityPeriod(config: ChainForkConfig, state: BeaconStateAllForks): number {
   const activeIndices = getActiveValidatorIndices(state, getCurrentEpoch(state));
   const validators = state.validators.getAllReadonlyValues();
-  const fork = config.getForkName(state.slot);
 
   let totalActiveBalanceIncrements = 0;
   for (const index of activeIndices) {
@@ -94,6 +91,22 @@ export function computeWeakSubjectivityPeriod(config: ChainForkConfig, state: Be
     totalActiveBalanceIncrements = 1;
   }
 
+  return computeWeakSubjectivityPeriodFromActiveValidators(config, state.slot, {
+    activeValidatorCount: activeIndices.length,
+    totalActiveBalanceIncrements,
+  });
+}
+
+function computeWeakSubjectivityPeriodFromActiveValidators(
+  config: ChainForkConfig,
+  slot: Slot,
+  {
+    activeValidatorCount,
+    totalActiveBalanceIncrements,
+  }: {activeValidatorCount: number; totalActiveBalanceIncrements: number}
+): number {
+  const fork = config.getForkName(slot);
+
   const churnLimitsGloas = getGloasChurnLimits(config, totalActiveBalanceIncrements);
 
   return isForkPostGloas(fork)
@@ -115,9 +128,9 @@ export function computeWeakSubjectivityPeriod(config: ChainForkConfig, state: Be
           config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
         )
       : computeWeakSubjectivityPeriodFromConstituentsPhase0(
-          activeIndices.length,
+          activeValidatorCount,
           totalActiveBalanceIncrements,
-          getChurnLimit(config, activeIndices.length),
+          getChurnLimit(config, activeValidatorCount),
           config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
         );
 }
@@ -189,37 +202,27 @@ export function getLatestBlockRoot(state: BeaconStateAllForks): Root {
   return ssz.phase0.BeaconBlockHeader.hashTreeRoot(header);
 }
 
-export function isWithinWeakSubjectivityPeriod(
-  config: BeaconConfig,
-  wsState: BeaconStateAllForks,
-  wsCheckpoint: Checkpoint
-): boolean {
-  try {
-    ensureWithinWeakSubjectivityPeriod(config, wsState, wsCheckpoint);
-    return true;
-  } catch (_) {
-    return false;
-  }
+export type WeakSubjectivitySummary = {checkpointEpoch: Epoch; genesisTime: number; period: number};
+
+/** The metadata must describe the supplied state bytes. */
+export function computeWeakSubjectivitySummaryFromStateBytes(
+  config: ChainForkConfig,
+  bytes: Uint8Array,
+  metadata: StateBytesMetadata
+): WeakSubjectivitySummary | null {
+  const {slot, genesisTime} = metadata;
+  const stateType = getStateTypeFromBytes(config, bytes);
+  const activeValidators = scanActiveValidatorsFromStateBytes(bytes, stateType, computeEpochAtSlot(slot));
+  if (activeValidators === null) return null;
+  const period = computeWeakSubjectivityPeriodFromActiveValidators(config, slot, activeValidators);
+  return {checkpointEpoch: computeCheckpointEpochAtStateSlot(slot), genesisTime, period};
 }
 
-export function ensureWithinWeakSubjectivityPeriod(
-  config: BeaconConfig,
-  wsState: BeaconStateAllForks,
-  wsCheckpoint: Checkpoint
-): void {
-  const wsStateEpoch = computeCheckpointEpochAtStateSlot(wsState.slot);
-  const blockRoot = getLatestBlockRoot(wsState);
-  if (!ssz.Root.equals(blockRoot, wsCheckpoint.root)) {
-    throw new Error(`Roots do not match.  expected=${toRootHex(wsCheckpoint.root)}, actual=${toRootHex(blockRoot)}`);
-  }
-  if (!ssz.Epoch.equals(wsStateEpoch, wsCheckpoint.epoch)) {
-    throw new Error(`Epochs do not match.  expected=${wsCheckpoint.epoch}, actual=${wsStateEpoch}`);
-  }
-  const wsPeriod = computeWeakSubjectivityPeriod(config, wsState);
-  const clockEpoch = computeEpochAtSlot(getCurrentSlot(config, wsState.genesisTime));
-  if (clockEpoch > wsStateEpoch + wsPeriod) {
-    throw new Error(
-      `The downloaded state with epoch ${wsStateEpoch} is not within weak subjectivity period of ${wsPeriod} from the current epoch ${clockEpoch}. Please verify your checkpoint source`
-    );
-  }
+export function isWithinWeakSubjectivityPeriodFromSummary(
+  config: ChainForkConfig,
+  summary: WeakSubjectivitySummary,
+  now: TimeSeconds = Date.now() / 1000
+): boolean {
+  const clockSlot = GENESIS_SLOT + Math.floor((now - summary.genesisTime) / (config.SLOT_DURATION_MS / 1000));
+  return computeEpochAtSlot(clockSlot) <= summary.checkpointEpoch + summary.period;
 }