@lodestar/state-transition 1.35.0-dev.47c570ab76 → 1.35.0-dev.549f58dd39

package/src/stateTransition.ts

@@ -0,0 +1,305 @@
+import {SLOTS_PER_EPOCH} from "@lodestar/params";
+import {Epoch, SignedBeaconBlock, SignedBlindedBeaconBlock, Slot, ssz} from "@lodestar/types";
+import {toRootHex} from "@lodestar/utils";
+import {BlockExternalData, DataAvailabilityStatus, ExecutionPayloadStatus} from "./block/externalData.js";
+import {processBlock} from "./block/index.js";
+import {ProcessBlockOpts} from "./block/types.js";
+import {EpochTransitionCache, EpochTransitionCacheOpts, beforeProcessEpoch} from "./cache/epochTransitionCache.js";
+import {EpochTransitionStep, processEpoch} from "./epoch/index.js";
+import {BeaconStateTransitionMetrics, onPostStateMetrics, onStateCloneMetrics} from "./metrics.js";
+import {verifyProposerSignature} from "./signatureSets/index.js";
+import {
+  processSlot,
+  upgradeStateToAltair,
+  upgradeStateToBellatrix,
+  upgradeStateToCapella,
+  upgradeStateToDeneb,
+  upgradeStateToElectra,
+  upgradeStateToGloas,
+} from "./slot/index.js";
+import {upgradeStateToFulu} from "./slot/upgradeStateToFulu.js";
+import {
+  CachedBeaconStateAllForks,
+  CachedBeaconStateAltair,
+  CachedBeaconStateBellatrix,
+  CachedBeaconStateCapella,
+  CachedBeaconStateDeneb,
+  CachedBeaconStateElectra,
+  CachedBeaconStateFulu,
+  CachedBeaconStatePhase0,
+} from "./types.js";
+import {computeEpochAtSlot} from "./util/index.js";
+
+// Multifork capable state transition
+
+// NOTE DENEB: Mandatory BlockExternalData to decide if block is available or not
+export type StateTransitionOpts = BlockExternalData &
+  EpochTransitionCacheOpts &
+  ProcessBlockOpts & {
+    verifyStateRoot?: boolean;
+    verifyProposer?: boolean;
+    verifySignatures?: boolean;
+    dontTransferCache?: boolean;
+  };
+
+export type StateTransitionModules = {
+  metrics?: BeaconStateTransitionMetrics | null;
+  validatorMonitor?: ValidatorMonitor | null;
+};
+
+interface ValidatorMonitor {
+  registerValidatorStatuses(
+    currentEpoch: Epoch,
+    inclusionDelays: number[],
+    flags: number[],
+    isActiveCurrEpoch: boolean[],
+    isActivePrevEpoch: boolean[],
+    balances?: number[]
+  ): void;
+}
+
+/**
+ * `state.clone()` invocation source tracked in metrics
+ */
+export enum StateCloneSource {
+  stateTransition = "stateTransition",
+  processSlots = "processSlots",
+}
+
+/**
+ * `state.hashTreeRoot()` invocation source tracked in metrics
+ */
+export enum StateHashTreeRootSource {
+  stateTransition = "state_transition",
+  blockTransition = "block_transition",
+  prepareNextSlot = "prepare_next_slot",
+  prepareNextEpoch = "prepare_next_epoch",
+  regenState = "regen_state",
+  computeNewStateRoot = "compute_new_state_root",
+}
+
+/**
+ * Implementation Note: follows the optimizations in protolambda's eth2fastspec (https://github.com/protolambda/eth2fastspec)
+ */
+export function stateTransition(
+  state: CachedBeaconStateAllForks,
+  signedBlock: SignedBeaconBlock | SignedBlindedBeaconBlock,
+  options: StateTransitionOpts = {
+    // Assume default to be valid and available
+    executionPayloadStatus: ExecutionPayloadStatus.valid,
+    dataAvailabilityStatus: DataAvailabilityStatus.Available,
+  },
+  {metrics, validatorMonitor}: StateTransitionModules = {}
+): CachedBeaconStateAllForks {
+  const {verifyStateRoot = true, verifyProposer = true} = options;
+
+  const block = signedBlock.message;
+  const blockSlot = block.slot;
+
+  // .clone() before mutating state in state transition
+  let postState = state.clone(options.dontTransferCache);
+
+  if (metrics) {
+    onStateCloneMetrics(postState, metrics, StateCloneSource.stateTransition);
+  }
+
+  // State is already a ViewDU, which won't commit changes. Equivalent to .setStateCachesAsTransient()
+  // postState.setStateCachesAsTransient();
+
+  // Process slots (including those with no blocks) since block.
+  // Includes state upgrades
+  postState = processSlotsWithTransientCache(postState, blockSlot, options, {metrics, validatorMonitor});
+
+  // Verify proposer signature only
+  if (verifyProposer && !verifyProposerSignature(postState, signedBlock)) {
+    throw new Error("Invalid block signature");
+  }
+
+  // Process block
+  const fork = state.config.getForkSeq(block.slot);
+
+  // Note: time only on success
+  const processBlockTimer = metrics?.processBlockTime.startTimer();
+
+  processBlock(fork, postState, block, options, options, metrics);
+
+  const processBlockCommitTimer = metrics?.processBlockCommitTime.startTimer();
+  postState.commit();
+  processBlockCommitTimer?.();
+
+  // Note: time only on success. Include processBlock and commit
+  processBlockTimer?.();
+
+  if (metrics) {
+    onPostStateMetrics(postState, metrics);
+  }
+
+  // Verify state root
+  if (verifyStateRoot) {
+    const hashTreeRootTimer = metrics?.stateHashTreeRootTime.startTimer({
+      source: StateHashTreeRootSource.stateTransition,
+    });
+    const stateRoot = postState.hashTreeRoot();
+    hashTreeRootTimer?.();
+
+    if (!ssz.Root.equals(block.stateRoot, stateRoot)) {
+      throw new Error(
+        `Invalid state root at slot ${block.slot}, expected=${toRootHex(block.stateRoot)}, actual=${toRootHex(
+          stateRoot
+        )}`
+      );
+    }
+  }
+
+  return postState;
+}
+
+/**
+ * Like `processSlots` from the spec but additionally handles fork upgrades
+ *
+ * Implementation Note: follows the optimizations in protolambda's eth2fastspec (https://github.com/protolambda/eth2fastspec)
+ */
+export function processSlots(
+  state: CachedBeaconStateAllForks,
+  slot: Slot,
+  epochTransitionCacheOpts?: EpochTransitionCacheOpts & {dontTransferCache?: boolean},
+  {metrics, validatorMonitor}: StateTransitionModules = {}
+): CachedBeaconStateAllForks {
+  // .clone() before mutating state in state transition
+  let postState = state.clone(epochTransitionCacheOpts?.dontTransferCache);
+
+  if (metrics) {
+    onStateCloneMetrics(postState, metrics, StateCloneSource.processSlots);
+  }
+
+  // State is already a ViewDU, which won't commit changes. Equivalent to .setStateCachesAsTransient()
+  // postState.setStateCachesAsTransient();
+
+  postState = processSlotsWithTransientCache(postState, slot, epochTransitionCacheOpts, {metrics, validatorMonitor});
+
+  // Apply changes to state, must do before hashing
+  postState.commit();
+
+  return postState;
+}
+
+/**
+ * All processSlot() logic but separate so stateTransition() can recycle the caches
+ *
+ * Epoch transition will be processed at the last slot of an epoch. Note that compute_shuffling() is going
+ * to be executed in parallel (either by napi-rs or worker thread) with processEpoch() like below:
+ *
+ *   state-transition
+ *   ╔══════════════════════════════════════════════════════════════════════════════════╗
+ *   ║   beforeProcessEpoch          processEpoch                 afterPRocessEpoch     ║
+ *   ║  |-------------------------|--------------------|-------------------------------|║
+ *   ║                       |                         |     |                          ║
+ *   ╚═══════════════════════|═══════════════════════════════|══════════════════════════╝
+ *                           |                               |
+ *                         build()                          get()
+ *                           |                               |
+ *   ╔═══════════════════════V═══════════════════════════════V═══════════════════════════╗
+ *   ║                       |                               |                           ║
+ *   ║                       |-------------------------------|                           ║
+ *   ║                          compute_shuffling()                                      ║
+ *   ╚═══════════════════════════════════════════════════════════════════════════════════╝
+ *   beacon-node ShufflingCache
+ */
+function processSlotsWithTransientCache(
+  postState: CachedBeaconStateAllForks,
+  slot: Slot,
+  epochTransitionCacheOpts?: EpochTransitionCacheOpts,
+  {metrics, validatorMonitor}: StateTransitionModules = {}
+): CachedBeaconStateAllForks {
+  const {config} = postState;
+  if (postState.slot > slot) {
+    throw Error(`Too old slot ${slot}, current=${postState.slot}`);
+  }
+
+  while (postState.slot < slot) {
+    processSlot(postState);
+
+    // Process epoch on the first slot of the next epoch
+    if ((postState.slot + 1) % SLOTS_PER_EPOCH === 0) {
+      // At fork boundary we don't want to process "next fork" epoch before upgrading state
+      const fork = postState.config.getForkSeq(postState.slot);
+
+      const epochTransitionTimer = metrics?.epochTransitionTime.startTimer();
+
+      let epochTransitionCache: EpochTransitionCache;
+      {
+        const timer = metrics?.epochTransitionStepTime.startTimer({step: EpochTransitionStep.beforeProcessEpoch});
+        epochTransitionCache = beforeProcessEpoch(postState, epochTransitionCacheOpts);
+        timer?.();
+      }
+
+      processEpoch(fork, postState, epochTransitionCache, metrics);
+
+      const {currentEpoch, inclusionDelays, flags, isActiveCurrEpoch, isActivePrevEpoch, balances} =
+        epochTransitionCache;
+      validatorMonitor?.registerValidatorStatuses(
+        currentEpoch,
+        inclusionDelays,
+        flags,
+        isActiveCurrEpoch,
+        isActivePrevEpoch,
+        balances
+      );
+
+      postState.slot++;
+
+      {
+        const timer = metrics?.epochTransitionStepTime.startTimer({step: EpochTransitionStep.afterProcessEpoch});
+        // this should be called before `upgradeState*()` below to prepare data for it
+        postState.epochCtx.afterProcessEpoch(postState, epochTransitionCache);
+        timer?.();
+      }
+
+      // Upgrade state if exactly at epoch boundary
+      const stateEpoch = computeEpochAtSlot(postState.slot);
+      if (stateEpoch === config.ALTAIR_FORK_EPOCH) {
+        postState = upgradeStateToAltair(postState as CachedBeaconStatePhase0) as CachedBeaconStateAllForks;
+      }
+      if (stateEpoch === config.BELLATRIX_FORK_EPOCH) {
+        postState = upgradeStateToBellatrix(postState as CachedBeaconStateAltair) as CachedBeaconStateAllForks;
+      }
+      if (stateEpoch === config.CAPELLA_FORK_EPOCH) {
+        postState = upgradeStateToCapella(postState as CachedBeaconStateBellatrix) as CachedBeaconStateAllForks;
+      }
+      if (stateEpoch === config.DENEB_FORK_EPOCH) {
+        postState = upgradeStateToDeneb(postState as CachedBeaconStateCapella) as CachedBeaconStateAllForks;
+      }
+      if (stateEpoch === config.ELECTRA_FORK_EPOCH) {
+        postState = upgradeStateToElectra(postState as CachedBeaconStateDeneb) as CachedBeaconStateAllForks;
+      }
+      if (stateEpoch === config.FULU_FORK_EPOCH) {
+        postState = upgradeStateToFulu(postState as CachedBeaconStateElectra) as CachedBeaconStateAllForks;
+      }
+      if (stateEpoch === config.GLOAS_FORK_EPOCH) {
+        postState = upgradeStateToGloas(postState as CachedBeaconStateFulu) as CachedBeaconStateAllForks;
+      }
+
+      {
+        const timer = metrics?.epochTransitionStepTime.startTimer({step: EpochTransitionStep.finalProcessEpoch});
+        // last step to prepare epoch data that depends on the upgraded state, for example proposerLookahead of BeaconStateFulu
+        postState.epochCtx.finalProcessEpoch(postState);
+        timer?.();
+      }
+
+      // Running commit here is not strictly necessary. The cost of running commit twice (here + after process block)
+      // Should be negligible but gives better metrics to differentiate the cost of it for block and epoch proc.
+      {
+        const timer = metrics?.epochTransitionCommitTime.startTimer();
+        postState.commit();
+        timer?.();
+      }
+
+      // Note: time only on success. Include beforeProcessEpoch, processEpoch, afterProcessEpoch, upgradeState*, finalProcessEpoch, commit
+      epochTransitionTimer?.();
+    } else {
+      postState.slot++;
+    }
+  }
+
+  return postState;
+}

package/src/types.ts

@@ -0,0 +1,26 @@
+export {EpochCache} from "./cache/epochCache.js";
+export type {EpochTransitionCache} from "./cache/epochTransitionCache.js";
+export type {
+  CachedBeaconStateAllForks,
+  CachedBeaconStateAltair,
+  CachedBeaconStateBellatrix,
+  CachedBeaconStateCapella,
+  CachedBeaconStateDeneb,
+  CachedBeaconStateElectra,
+  CachedBeaconStateExecutions,
+  CachedBeaconStateFulu,
+  CachedBeaconStateGloas,
+  CachedBeaconStatePhase0,
+} from "./cache/stateCache.js";
+export type {
+  BeaconStateAllForks,
+  BeaconStateAltair,
+  BeaconStateBellatrix,
+  BeaconStateCapella,
+  BeaconStateDeneb,
+  BeaconStateElectra,
+  BeaconStateExecutions,
+  BeaconStateFulu,
+  BeaconStateGloas,
+  BeaconStatePhase0,
+} from "./cache/types.js";

package/src/util/aggregator.ts

@@ -0,0 +1,33 @@
+import {digest} from "@chainsafe/as-sha256";
+import {
+  SYNC_COMMITTEE_SIZE,
+  SYNC_COMMITTEE_SUBNET_COUNT,
+  TARGET_AGGREGATORS_PER_COMMITTEE,
+  TARGET_AGGREGATORS_PER_SYNC_SUBCOMMITTEE,
+} from "@lodestar/params";
+import {BLSSignature} from "@lodestar/types";
+import {bytesToBigInt, intDiv} from "@lodestar/utils";
+
+const ZERO_BIGINT = BigInt(0);
+
+export function isSyncCommitteeAggregator(selectionProof: BLSSignature): boolean {
+  const modulo = Math.max(
+    1,
+    intDiv(intDiv(SYNC_COMMITTEE_SIZE, SYNC_COMMITTEE_SUBNET_COUNT), TARGET_AGGREGATORS_PER_SYNC_SUBCOMMITTEE)
+  );
+  return isSelectionProofValid(selectionProof, modulo);
+}
+
+export function isAggregatorFromCommitteeLength(committeeLength: number, slotSignature: BLSSignature): boolean {
+  const modulo = Math.max(1, intDiv(committeeLength, TARGET_AGGREGATORS_PER_COMMITTEE));
+  return isSelectionProofValid(slotSignature, modulo);
+}
+
+/**
+ * Note: **must** use bytesToBigInt() otherwise a JS number is not able to represent the latest digits of
+ * the remainder, resulting in `14333559117764833000` for example, where the last three digits are always zero.
+ * Using bytesToInt() may cause isSelectionProofValid() to always return false.
+ */
+export function isSelectionProofValid(sig: BLSSignature, modulo: number): boolean {
+  return bytesToBigInt(digest(sig).slice(0, 8)) % BigInt(modulo) === ZERO_BIGINT;
+}

package/src/util/altair.ts

@@ -0,0 +1,13 @@
+import {BASE_REWARD_FACTOR, EFFECTIVE_BALANCE_INCREMENT} from "@lodestar/params";
+import {bigIntSqrt, bnToNum} from "@lodestar/utils";
+
+/**
+ * Before we manage bigIntSqrt(totalActiveStake) as BigInt and return BigInt.
+ * bigIntSqrt(totalActiveStake) should fit a number (2 ** 53 -1 max)
+ **/
+export function computeBaseRewardPerIncrement(totalActiveStakeByIncrement: number): number {
+  return Math.floor(
+    (EFFECTIVE_BALANCE_INCREMENT * BASE_REWARD_FACTOR) /
+      bnToNum(bigIntSqrt(BigInt(totalActiveStakeByIncrement) * BigInt(EFFECTIVE_BALANCE_INCREMENT)))
+  );
+}

package/src/util/array.ts

@@ -0,0 +1,53 @@
+/**
+ * Returns an array of size `n` filled with 0
+ * 20 times faster than
+ * ```
+ * Array.from({length: n}, () => 0)
+ * ```
+ * - Array.from: 40ms / 200_000 elements
+ * - This fn: 2.2ms / 200_000 elements
+ */
+export function newZeroedArray(n: number): number[] {
+  const arr = new Array<number>(n);
+  for (let i = 0; i < n; ++i) {
+    arr[i] = 0;
+  }
+  return arr;
+}
+
+export function newZeroedBigIntArray(n: number): bigint[] {
+  const arr = new Array<bigint>(n);
+  for (let i = 0; i < n; ++i) {
+    arr[i] = BigInt(0);
+  }
+  return arr;
+}
+
+export function newFilledArray<T>(n: number, val: T): T[] {
+  const arr = new Array<T>(n);
+  for (let i = 0; i < n; ++i) {
+    arr[i] = val;
+  }
+  return arr;
+}
+
+/**
+ * Returns an array with all values not in the participants array.
+ * - All elements in values must be unique
+ * - Does NOT require sorting
+ */
+export function getUnparticipantValues<T>(participants: T[], values: T[]): T[] {
+  const unparticipants: T[] = [];
+
+  let j = 0;
+  for (let i = 0; i < values.length; i++) {
+    if (values[i] === participants[j]) {
+      // Included
+      j++;
+    } else {
+      unparticipants.push(values[i]);
+    }
+  }
+
+  return unparticipants;
+}

package/src/util/attestation.ts

@@ -0,0 +1,36 @@
+import {MIN_ATTESTATION_INCLUSION_DELAY, SLOTS_PER_EPOCH} from "@lodestar/params";
+import {AttesterSlashing, Slot, ValidatorIndex, phase0, ssz} from "@lodestar/types";
+
+/**
+ * Check if [[data1]] and [[data2]] are slashable according to Casper FFG rules.
+ */
+export function isSlashableAttestationData(
+  data1: phase0.AttestationDataBigint,
+  data2: phase0.AttestationDataBigint
+): boolean {
+  return (
+    // Double vote
+    (!ssz.phase0.AttestationDataBigint.equals(data1, data2) && data1.target.epoch === data2.target.epoch) ||
+    // Surround vote
+    (data1.source.epoch < data2.source.epoch && data2.target.epoch < data1.target.epoch)
+  );
+}
+
+export function isValidAttestationSlot(attestationSlot: Slot, currentSlot: Slot): boolean {
+  return (
+    attestationSlot + MIN_ATTESTATION_INCLUSION_DELAY <= currentSlot && currentSlot <= attestationSlot + SLOTS_PER_EPOCH
+  );
+}
+
+export function getAttesterSlashableIndices(attesterSlashing: AttesterSlashing): ValidatorIndex[] {
+  const indices: ValidatorIndex[] = [];
+  const attSet1 = new Set(attesterSlashing.attestation1.attestingIndices);
+  const attArr2 = attesterSlashing.attestation2.attestingIndices;
+  for (let i = 0, len = attArr2.length; i < len; i++) {
+    const index = attArr2[i];
+    if (attSet1.has(index)) {
+      indices.push(index);
+    }
+  }
+  return indices;
+}

package/src/util/attesterStatus.ts

@@ -0,0 +1,83 @@
+import {TIMELY_HEAD_FLAG_INDEX, TIMELY_SOURCE_FLAG_INDEX, TIMELY_TARGET_FLAG_INDEX} from "@lodestar/params";
+
+// We pack both previous and current epoch attester flags
+// as well as slashed and eligibility flags into a single number
+// to save space in our epoch transition cache.
+// Note: the order of the flags is important for efficiently translating
+// from the BeaconState flags to our flags.
+// [prevSource, prevTarget, prevHead, currSource, currTarget, currHead, unslashed, eligible]
+export const FLAG_PREV_SOURCE_ATTESTER = 1 << TIMELY_SOURCE_FLAG_INDEX;
+export const FLAG_PREV_TARGET_ATTESTER = 1 << TIMELY_TARGET_FLAG_INDEX;
+export const FLAG_PREV_HEAD_ATTESTER = 1 << TIMELY_HEAD_FLAG_INDEX;
+
+export const FLAG_CURR_SOURCE_ATTESTER = 1 << (3 + TIMELY_SOURCE_FLAG_INDEX);
+export const FLAG_CURR_TARGET_ATTESTER = 1 << (3 + TIMELY_TARGET_FLAG_INDEX);
+export const FLAG_CURR_HEAD_ATTESTER = 1 << (3 + TIMELY_HEAD_FLAG_INDEX);
+
+export const FLAG_UNSLASHED = 1 << 6;
+export const FLAG_ELIGIBLE_ATTESTER = 1 << 7;
+
+// Precompute OR flags used in epoch processing
+export const FLAG_PREV_SOURCE_ATTESTER_UNSLASHED = FLAG_PREV_SOURCE_ATTESTER | FLAG_UNSLASHED;
+export const FLAG_PREV_TARGET_ATTESTER_UNSLASHED = FLAG_PREV_TARGET_ATTESTER | FLAG_UNSLASHED;
+export const FLAG_PREV_HEAD_ATTESTER_UNSLASHED = FLAG_PREV_HEAD_ATTESTER | FLAG_UNSLASHED;
+
+export function hasMarkers(flags: number, markers: number): boolean {
+  return (flags & markers) === markers;
+}
+
+export type AttesterFlags = {
+  prevSourceAttester: boolean;
+  prevTargetAttester: boolean;
+  prevHeadAttester: boolean;
+  currSourceAttester: boolean;
+  currTargetAttester: boolean;
+  currHeadAttester: boolean;
+  unslashed: boolean;
+  eligibleAttester: boolean;
+};
+
+export function parseAttesterFlags(flags: number): AttesterFlags {
+  return {
+    prevSourceAttester: hasMarkers(flags, FLAG_PREV_SOURCE_ATTESTER),
+    prevTargetAttester: hasMarkers(flags, FLAG_PREV_TARGET_ATTESTER),
+    prevHeadAttester: hasMarkers(flags, FLAG_PREV_HEAD_ATTESTER),
+    currSourceAttester: hasMarkers(flags, FLAG_CURR_SOURCE_ATTESTER),
+    currTargetAttester: hasMarkers(flags, FLAG_CURR_TARGET_ATTESTER),
+    currHeadAttester: hasMarkers(flags, FLAG_CURR_HEAD_ATTESTER),
+    unslashed: hasMarkers(flags, FLAG_UNSLASHED),
+    eligibleAttester: hasMarkers(flags, FLAG_ELIGIBLE_ATTESTER),
+  };
+}
+
+export function toAttesterFlags(flagsObj: AttesterFlags): number {
+  let flag = 0;
+  if (flagsObj.prevSourceAttester) flag |= FLAG_PREV_SOURCE_ATTESTER;
+  if (flagsObj.prevTargetAttester) flag |= FLAG_PREV_TARGET_ATTESTER;
+  if (flagsObj.prevHeadAttester) flag |= FLAG_PREV_HEAD_ATTESTER;
+  if (flagsObj.currSourceAttester) flag |= FLAG_CURR_SOURCE_ATTESTER;
+  if (flagsObj.currTargetAttester) flag |= FLAG_CURR_TARGET_ATTESTER;
+  if (flagsObj.currHeadAttester) flag |= FLAG_CURR_HEAD_ATTESTER;
+  if (flagsObj.unslashed) flag |= FLAG_UNSLASHED;
+  if (flagsObj.eligibleAttester) flag |= FLAG_ELIGIBLE_ATTESTER;
+  return flag;
+}
+
+/** Same to https://github.com/ethereum/eth2.0-specs/blob/v1.1.0-alpha.5/specs/altair/beacon-chain.md#has_flag */
+const TIMELY_SOURCE = 1 << TIMELY_SOURCE_FLAG_INDEX;
+const TIMELY_TARGET = 1 << TIMELY_TARGET_FLAG_INDEX;
+const TIMELY_HEAD = 1 << TIMELY_HEAD_FLAG_INDEX;
+
+export type ParticipationFlags = {
+  timelySource: boolean;
+  timelyTarget: boolean;
+  timelyHead: boolean;
+};
+
+export function parseParticipationFlags(flags: number): ParticipationFlags {
+  return {
+    timelySource: hasMarkers(flags, TIMELY_SOURCE),
+    timelyTarget: hasMarkers(flags, TIMELY_TARGET),
+    timelyHead: hasMarkers(flags, TIMELY_HEAD),
+  };
+}

package/src/util/balance.ts

@@ -0,0 +1,83 @@
+import {EFFECTIVE_BALANCE_INCREMENT} from "@lodestar/params";
+import {Gwei, ValidatorIndex} from "@lodestar/types";
+import {bigIntMax} from "@lodestar/utils";
+import {EffectiveBalanceIncrements} from "../cache/effectiveBalanceIncrements.js";
+import {BeaconStateAllForks} from "../index.js";
+import {CachedBeaconStateAllForks} from "../types.js";
+
+/**
+ * Return the combined effective balance of the [[indices]].
+ * `EFFECTIVE_BALANCE_INCREMENT` Gwei minimum to avoid divisions by zero.
+ *
+ * SLOW CODE - 🐢
+ */
+export function getTotalBalance(state: BeaconStateAllForks, indices: ValidatorIndex[]): Gwei {
+  let total = BigInt(0);
+
+  // TODO: Use a fast cache to get the effective balance 🐢
+  const validatorsArr = state.validators.getAllReadonlyValues();
+  for (let i = 0; i < indices.length; i++) {
+    total += BigInt(validatorsArr[indices[i]].effectiveBalance);
+  }
+
+  return bigIntMax(BigInt(EFFECTIVE_BALANCE_INCREMENT), total);
+}
+
+/**
+ * Increase the balance for a validator with the given ``index`` by ``delta``.
+ */
+export function increaseBalance(state: BeaconStateAllForks, index: ValidatorIndex, delta: number): void {
+  // TODO: Inline this
+  state.balances.set(index, state.balances.get(index) + delta);
+}
+
+/**
+ * Decrease the balance for a validator with the given ``index`` by ``delta``.
+ *
+ * Set to ``0`` when underflow.
+ */
+export function decreaseBalance(state: BeaconStateAllForks, index: ValidatorIndex, delta: number): void {
+  const currentBalance = state.balances.get(index);
+  const newBalance = currentBalance > delta ? state.balances.get(index) - delta : 0;
+  // TODO: Is it necessary to protect against underflow here? Add unit test
+  state.balances.set(index, Math.max(0, newBalance));
+}
+
+/**
+ * This method is used to get justified balances from a justified state.
+ * This is consumed by forkchoice which based on delta so we return "by increment" (in ether) value,
+ * ie [30, 31, 32] instead of [30e9, 31e9, 32e9]
+ */
+export function getEffectiveBalanceIncrementsZeroInactive(
+  justifiedState: CachedBeaconStateAllForks
+): EffectiveBalanceIncrements {
+  const {activeIndices} = justifiedState.epochCtx.currentShuffling;
+  // 5x faster than reading from state.validators, with validator Nodes as values
+  const validatorCount = justifiedState.validators.length;
+  const {effectiveBalanceIncrements} = justifiedState.epochCtx;
+  // Slice up to `validatorCount` since it won't be mutated, nor accessed beyond `validatorCount`
+  // NOTE: Force to use Uint16Array.slice (copy) instead of Buffer.call (not copy)
+  const effectiveBalanceIncrementsZeroInactive = Uint16Array.prototype.slice.call(
+    effectiveBalanceIncrements,
+    0,
+    validatorCount
+  );
+
+  let j = 0;
+  justifiedState.validators.forEachValue((validator, i) => {
+    const {slashed} = validator;
+    if (i === activeIndices[j]) {
+      // active validator
+      j++;
+      if (slashed) {
+        // slashed validator
+        effectiveBalanceIncrementsZeroInactive[i] = 0;
+      }
+    } else {
+      // inactive validator
+      effectiveBalanceIncrementsZeroInactive[i] = 0;
+    }
+  });
+
+  return effectiveBalanceIncrementsZeroInactive;
+}