@lodestar/state-transition 1.35.0-dev.83de5b8dea → 1.35.0-dev.8689cc3545

package/src/epoch/getRewardsAndPenalties.ts

@@ -0,0 +1,137 @@
+import {
+  EFFECTIVE_BALANCE_INCREMENT,
+  ForkSeq,
+  INACTIVITY_PENALTY_QUOTIENT_ALTAIR,
+  INACTIVITY_PENALTY_QUOTIENT_BELLATRIX,
+  PARTICIPATION_FLAG_WEIGHTS,
+  TIMELY_HEAD_FLAG_INDEX,
+  TIMELY_SOURCE_FLAG_INDEX,
+  TIMELY_TARGET_FLAG_INDEX,
+  WEIGHT_DENOMINATOR,
+} from "@lodestar/params";
+import {CachedBeaconStateAltair, EpochTransitionCache} from "../types.js";
+import {
+  FLAG_ELIGIBLE_ATTESTER,
+  FLAG_PREV_HEAD_ATTESTER_UNSLASHED,
+  FLAG_PREV_SOURCE_ATTESTER_UNSLASHED,
+  FLAG_PREV_TARGET_ATTESTER_UNSLASHED,
+  hasMarkers,
+} from "../util/attesterStatus.js";
+import {isInInactivityLeak} from "../util/index.js";
+
+type RewardPenaltyItem = {
+  baseReward: number;
+  timelySourceReward: number;
+  timelySourcePenalty: number;
+  timelyTargetReward: number;
+  timelyTargetPenalty: number;
+  timelyHeadReward: number;
+};
+
+/**
+ * This data is reused and never gc.
+ */
+const rewards = new Array<number>();
+const penalties = new Array<number>();
+/**
+ * An aggregate of getFlagIndexDeltas and getInactivityPenaltyDeltas that loop through process.flags 1 time instead of 4.
+ *
+ * - On normal mainnet conditions
+ *   - prevSourceAttester: 98%
+ *   - prevTargetAttester: 96%
+ *   - prevHeadAttester:   93%
+ *   - currSourceAttester: 95%
+ *   - currTargetAttester: 93%
+ *   - currHeadAttester:   91%
+ *   - unslashed:          100%
+ *   - eligibleAttester:   98%
+ */
+export function getRewardsAndPenaltiesAltair(
+  state: CachedBeaconStateAltair,
+  cache: EpochTransitionCache
+): [number[], number[]] {
+  // TODO: Is there a cheaper way to measure length that going to `state.validators`?
+  const validatorCount = state.validators.length;
+  const activeIncrements = cache.totalActiveStakeByIncrement;
+  rewards.length = validatorCount;
+  rewards.fill(0);
+  penalties.length = validatorCount;
+  penalties.fill(0);
+
+  const isInInactivityLeakBn = isInInactivityLeak(state);
+  // effectiveBalance is multiple of EFFECTIVE_BALANCE_INCREMENT and less than MAX_EFFECTIVE_BALANCE
+  // so there are limited values of them like 32, 31, 30
+  const rewardPenaltyItemCache = new Map<number, RewardPenaltyItem>();
+  const {config, epochCtx} = state;
+  const fork = config.getForkSeq(state.slot);
+
+  const inactivityPenalityMultiplier =
+    fork === ForkSeq.altair ? INACTIVITY_PENALTY_QUOTIENT_ALTAIR : INACTIVITY_PENALTY_QUOTIENT_BELLATRIX;
+  const penaltyDenominator = config.INACTIVITY_SCORE_BIAS * inactivityPenalityMultiplier;
+
+  const {flags} = cache;
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    if (!hasMarkers(flag, FLAG_ELIGIBLE_ATTESTER)) {
+      continue;
+    }
+
+    const effectiveBalanceIncrement = epochCtx.effectiveBalanceIncrements[i];
+
+    let rewardPenaltyItem = rewardPenaltyItemCache.get(effectiveBalanceIncrement);
+    if (!rewardPenaltyItem) {
+      const baseReward = effectiveBalanceIncrement * cache.baseRewardPerIncrement;
+      const tsWeigh = PARTICIPATION_FLAG_WEIGHTS[TIMELY_SOURCE_FLAG_INDEX];
+      const ttWeigh = PARTICIPATION_FLAG_WEIGHTS[TIMELY_TARGET_FLAG_INDEX];
+      const thWeigh = PARTICIPATION_FLAG_WEIGHTS[TIMELY_HEAD_FLAG_INDEX];
+      const tsUnslashedParticipatingIncrements = cache.prevEpochUnslashedStake.sourceStakeByIncrement;
+      const ttUnslashedParticipatingIncrements = cache.prevEpochUnslashedStake.targetStakeByIncrement;
+      const thUnslashedParticipatingIncrements = cache.prevEpochUnslashedStake.headStakeByIncrement;
+      const tsRewardNumerator = baseReward * tsWeigh * tsUnslashedParticipatingIncrements;
+      const ttRewardNumerator = baseReward * ttWeigh * ttUnslashedParticipatingIncrements;
+      const thRewardNumerator = baseReward * thWeigh * thUnslashedParticipatingIncrements;
+      rewardPenaltyItem = {
+        baseReward: baseReward,
+        timelySourceReward: Math.floor(tsRewardNumerator / (activeIncrements * WEIGHT_DENOMINATOR)),
+        timelyTargetReward: Math.floor(ttRewardNumerator / (activeIncrements * WEIGHT_DENOMINATOR)),
+        timelyHeadReward: Math.floor(thRewardNumerator / (activeIncrements * WEIGHT_DENOMINATOR)),
+        timelySourcePenalty: Math.floor((baseReward * tsWeigh) / WEIGHT_DENOMINATOR),
+        timelyTargetPenalty: Math.floor((baseReward * ttWeigh) / WEIGHT_DENOMINATOR),
+      };
+      rewardPenaltyItemCache.set(effectiveBalanceIncrement, rewardPenaltyItem);
+    }
+
+    const {timelySourceReward, timelySourcePenalty, timelyTargetReward, timelyTargetPenalty, timelyHeadReward} =
+      rewardPenaltyItem;
+
+    // same logic to getFlagIndexDeltas
+    if (hasMarkers(flag, FLAG_PREV_SOURCE_ATTESTER_UNSLASHED)) {
+      if (!isInInactivityLeakBn) {
+        rewards[i] += timelySourceReward;
+      }
+    } else {
+      penalties[i] += timelySourcePenalty;
+    }
+
+    if (hasMarkers(flag, FLAG_PREV_TARGET_ATTESTER_UNSLASHED)) {
+      if (!isInInactivityLeakBn) {
+        rewards[i] += timelyTargetReward;
+      }
+    } else {
+      penalties[i] += timelyTargetPenalty;
+    }
+
+    if (hasMarkers(flag, FLAG_PREV_HEAD_ATTESTER_UNSLASHED) && !isInInactivityLeakBn) {
+      rewards[i] += timelyHeadReward;
+    }
+
+    // Same logic to getInactivityPenaltyDeltas
+    // TODO: if we have limited value in inactivityScores we can provide a cache too
+    if (!hasMarkers(flag, FLAG_PREV_TARGET_ATTESTER_UNSLASHED)) {
+      const penaltyNumerator = effectiveBalanceIncrement * EFFECTIVE_BALANCE_INCREMENT * state.inactivityScores.get(i);
+      penalties[i] += Math.floor(penaltyNumerator / penaltyDenominator);
+    }
+  }
+
+  return [rewards, penalties];
+}

package/src/epoch/index.ts

@@ -0,0 +1,202 @@
+import {
+  ForkSeq,
+  MAX_ATTESTER_SLASHINGS,
+  MAX_EFFECTIVE_BALANCE,
+  MAX_VALIDATORS_PER_COMMITTEE,
+  SLOTS_PER_EPOCH,
+} from "@lodestar/params";
+import {BeaconStateTransitionMetrics} from "../metrics.js";
+import {
+  CachedBeaconStateAllForks,
+  CachedBeaconStateAltair,
+  CachedBeaconStateCapella,
+  CachedBeaconStateElectra,
+  CachedBeaconStateFulu,
+  CachedBeaconStatePhase0,
+  EpochTransitionCache,
+} from "../types.js";
+import {processEffectiveBalanceUpdates} from "./processEffectiveBalanceUpdates.js";
+import {processEth1DataReset} from "./processEth1DataReset.js";
+import {processHistoricalRootsUpdate} from "./processHistoricalRootsUpdate.js";
+import {processHistoricalSummariesUpdate} from "./processHistoricalSummariesUpdate.js";
+import {processInactivityUpdates} from "./processInactivityUpdates.js";
+import {processJustificationAndFinalization} from "./processJustificationAndFinalization.js";
+import {processParticipationFlagUpdates} from "./processParticipationFlagUpdates.js";
+import {processParticipationRecordUpdates} from "./processParticipationRecordUpdates.js";
+import {processPendingConsolidations} from "./processPendingConsolidations.js";
+import {processPendingDeposits} from "./processPendingDeposits.js";
+import {processProposerLookahead} from "./processProposerLookahead.js";
+import {processRandaoMixesReset} from "./processRandaoMixesReset.js";
+import {processRegistryUpdates} from "./processRegistryUpdates.js";
+import {processRewardsAndPenalties} from "./processRewardsAndPenalties.js";
+import {processSlashings} from "./processSlashings.js";
+import {processSlashingsReset} from "./processSlashingsReset.js";
+import {processSyncCommitteeUpdates} from "./processSyncCommitteeUpdates.js";
+
+// For spec tests
+export {getRewardsAndPenalties} from "./processRewardsAndPenalties.js";
+export {
+  processJustificationAndFinalization,
+  processInactivityUpdates,
+  processRewardsAndPenalties,
+  processRegistryUpdates,
+  processSlashings,
+  processEth1DataReset,
+  processEffectiveBalanceUpdates,
+  processSlashingsReset,
+  processRandaoMixesReset,
+  processHistoricalRootsUpdate,
+  processParticipationRecordUpdates,
+  processParticipationFlagUpdates,
+  processSyncCommitteeUpdates,
+  processHistoricalSummariesUpdate,
+  processPendingDeposits,
+  processPendingConsolidations,
+  processProposerLookahead,
+};
+
+export {computeUnrealizedCheckpoints} from "./computeUnrealizedCheckpoints.js";
+
+const maxValidatorsPerStateSlashing = SLOTS_PER_EPOCH * MAX_ATTESTER_SLASHINGS * MAX_VALIDATORS_PER_COMMITTEE;
+const maxSafeValidators = Math.floor(Number.MAX_SAFE_INTEGER / MAX_EFFECTIVE_BALANCE);
+
+/**
+ * Epoch transition steps tracked in metrics
+ */
+export enum EpochTransitionStep {
+  beforeProcessEpoch = "beforeProcessEpoch",
+  afterProcessEpoch = "afterProcessEpoch",
+  finalProcessEpoch = "finalProcessEpoch",
+  processJustificationAndFinalization = "processJustificationAndFinalization",
+  processInactivityUpdates = "processInactivityUpdates",
+  processRegistryUpdates = "processRegistryUpdates",
+  processSlashings = "processSlashings",
+  processRewardsAndPenalties = "processRewardsAndPenalties",
+  processEffectiveBalanceUpdates = "processEffectiveBalanceUpdates",
+  processParticipationFlagUpdates = "processParticipationFlagUpdates",
+  processSyncCommitteeUpdates = "processSyncCommitteeUpdates",
+  processPendingDeposits = "processPendingDeposits",
+  processPendingConsolidations = "processPendingConsolidations",
+  processProposerLookahead = "processProposerLookahead",
+}
+
+export function processEpoch(
+  fork: ForkSeq,
+  state: CachedBeaconStateAllForks,
+  cache: EpochTransitionCache,
+  metrics?: BeaconStateTransitionMetrics | null
+): void {
+  // state.slashings is initially a Gwei (BigInt) vector, however since Nov 2023 it's converted to UintNum64 (number) vector in the state transition because:
+  //  - state.slashings[nextEpoch % EPOCHS_PER_SLASHINGS_VECTOR] is reset per epoch in processSlashingsReset()
+  //  - max slashed validators per epoch is SLOTS_PER_EPOCH * MAX_ATTESTER_SLASHINGS * MAX_VALIDATORS_PER_COMMITTEE which is 32 * 2 * 2048 = 131072 on mainnet
+  //  - with that and 32_000_000_000 MAX_EFFECTIVE_BALANCE or 2048_000_000_000 MAX_EFFECTIVE_BALANCE_ELECTRA, it still fits in a number given that Math.floor(Number.MAX_SAFE_INTEGER / 32_000_000_000) = 281474
+  if (maxValidatorsPerStateSlashing > maxSafeValidators) {
+    throw new Error("Lodestar does not support this network, parameters don't fit number value inside state.slashings");
+  }
+
+  {
+    const timer = metrics?.epochTransitionStepTime.startTimer({
+      step: EpochTransitionStep.processJustificationAndFinalization,
+    });
+    processJustificationAndFinalization(state, cache);
+    timer?.();
+  }
+
+  if (fork >= ForkSeq.altair) {
+    const timer = metrics?.epochTransitionStepTime.startTimer({step: EpochTransitionStep.processInactivityUpdates});
+    processInactivityUpdates(state as CachedBeaconStateAltair, cache);
+    timer?.();
+  }
+
+  // processRewardsAndPenalties() is 2nd step in the specs, we optimize to do it
+  // after processSlashings() to update balances only once
+  // processRewardsAndPenalties(state, cache);
+  {
+    metrics?.validatorsInActivationQueue.set(cache.indicesEligibleForActivationQueue.length);
+    metrics?.validatorsInExitQueue.set(cache.indicesToEject.length);
+    const timer = metrics?.epochTransitionStepTime.startTimer({step: EpochTransitionStep.processRegistryUpdates});
+    processRegistryUpdates(fork, state, cache);
+    timer?.();
+  }
+
+  // accumulate slashing penalties and only update balances once in processRewardsAndPenalties()
+  let slashingPenalties: number[];
+  {
+    const timer = metrics?.epochTransitionStepTime.startTimer({step: EpochTransitionStep.processSlashings});
+    slashingPenalties = processSlashings(state, cache, false);
+    timer?.();
+  }
+
+  {
+    const timer = metrics?.epochTransitionStepTime.startTimer({step: EpochTransitionStep.processRewardsAndPenalties});
+    processRewardsAndPenalties(state, cache, slashingPenalties);
+    timer?.();
+  }
+
+  processEth1DataReset(state, cache);
+
+  if (fork >= ForkSeq.electra) {
+    const stateElectra = state as CachedBeaconStateElectra;
+    {
+      const timer = metrics?.epochTransitionStepTime.startTimer({
+        step: EpochTransitionStep.processPendingDeposits,
+      });
+      processPendingDeposits(stateElectra, cache);
+      timer?.();
+    }
+
+    {
+      const timer = metrics?.epochTransitionStepTime.startTimer({
+        step: EpochTransitionStep.processPendingConsolidations,
+      });
+      processPendingConsolidations(stateElectra, cache);
+      timer?.();
+    }
+  }
+
+  {
+    const timer = metrics?.epochTransitionStepTime.startTimer({
+      step: EpochTransitionStep.processEffectiveBalanceUpdates,
+    });
+    const numUpdate = processEffectiveBalanceUpdates(fork, state, cache);
+    timer?.();
+    metrics?.numEffectiveBalanceUpdates.set(numUpdate);
+  }
+
+  processSlashingsReset(state, cache);
+  processRandaoMixesReset(state, cache);
+
+  if (fork >= ForkSeq.capella) {
+    processHistoricalSummariesUpdate(state as CachedBeaconStateCapella, cache);
+  } else {
+    processHistoricalRootsUpdate(state, cache);
+  }
+
+  if (fork === ForkSeq.phase0) {
+    processParticipationRecordUpdates(state as CachedBeaconStatePhase0);
+  } else {
+    {
+      const timer = metrics?.epochTransitionStepTime.startTimer({
+        step: EpochTransitionStep.processParticipationFlagUpdates,
+      });
+      processParticipationFlagUpdates(state as CachedBeaconStateAltair);
+      timer?.();
+    }
+
+    {
+      const timer = metrics?.epochTransitionStepTime.startTimer({
+        step: EpochTransitionStep.processSyncCommitteeUpdates,
+      });
+      processSyncCommitteeUpdates(fork, state as CachedBeaconStateAltair);
+      timer?.();
+    }
+  }
+
+  if (fork >= ForkSeq.fulu) {
+    const timer = metrics?.epochTransitionStepTime.startTimer({
+      step: EpochTransitionStep.processProposerLookahead,
+    });
+    processProposerLookahead(fork, state as CachedBeaconStateFulu, cache);
+    timer?.();
+  }
+}

package/src/epoch/processEffectiveBalanceUpdates.ts

@@ -0,0 +1,111 @@
+import {
+  EFFECTIVE_BALANCE_INCREMENT,
+  ForkSeq,
+  HYSTERESIS_DOWNWARD_MULTIPLIER,
+  HYSTERESIS_QUOTIENT,
+  HYSTERESIS_UPWARD_MULTIPLIER,
+  MAX_EFFECTIVE_BALANCE,
+  MAX_EFFECTIVE_BALANCE_ELECTRA,
+  MIN_ACTIVATION_BALANCE,
+  TIMELY_TARGET_FLAG_INDEX,
+} from "@lodestar/params";
+import {BeaconStateAltair, CachedBeaconStateAllForks, EpochTransitionCache} from "../types.js";
+
+/** Same to https://github.com/ethereum/eth2.0-specs/blob/v1.1.0-alpha.5/specs/altair/beacon-chain.md#has_flag */
+const TIMELY_TARGET = 1 << TIMELY_TARGET_FLAG_INDEX;
+/**
+ * Update effective balances if validator.balance has changed enough
+ *
+ * PERF: Cost 'proportional' to $VALIDATOR_COUNT, to iterate over all balances. Then cost is proportional to the amount
+ * of validators whose effectiveBalance changed. Worst case is a massive network leak or a big slashing event which
+ * causes a large amount of the network to decrease their balance simultaneously.
+ *
+ * - On normal mainnet conditions 0 validators change their effective balance
+ * - In case of big innactivity event a medium portion of validators may have their effectiveBalance updated
+ *
+ * Return number of validators updated
+ */
+export function processEffectiveBalanceUpdates(
+  fork: ForkSeq,
+  state: CachedBeaconStateAllForks,
+  cache: EpochTransitionCache
+): number {
+  const HYSTERESIS_INCREMENT = EFFECTIVE_BALANCE_INCREMENT / HYSTERESIS_QUOTIENT;
+  const DOWNWARD_THRESHOLD = HYSTERESIS_INCREMENT * HYSTERESIS_DOWNWARD_MULTIPLIER;
+  const UPWARD_THRESHOLD = HYSTERESIS_INCREMENT * HYSTERESIS_UPWARD_MULTIPLIER;
+  const {validators, epochCtx} = state;
+  const {effectiveBalanceIncrements} = epochCtx;
+  const forkSeq = epochCtx.config.getForkSeq(state.slot);
+  let nextEpochTotalActiveBalanceByIncrement = 0;
+
+  // update effective balances with hysteresis
+
+  // epochTransitionCache.balances is initialized in processRewardsAndPenalties()
+  // and updated in processPendingDeposits() and processPendingConsolidations()
+  // so it's recycled here for performance.
+  const balances = cache.balances ?? state.balances.getAll();
+  const isCompoundingValidatorArr = cache.isCompoundingValidatorArr;
+
+  let numUpdate = 0;
+  for (let i = 0, len = balances.length; i < len; i++) {
+    const balance = balances[i];
+
+    // PERF: It's faster to access to get() every single element (4ms) than to convert to regular array then loop (9ms)
+    let effectiveBalanceIncrement = effectiveBalanceIncrements[i];
+    let effectiveBalance = effectiveBalanceIncrement * EFFECTIVE_BALANCE_INCREMENT;
+
+    let effectiveBalanceLimit: number;
+    if (fork < ForkSeq.electra) {
+      effectiveBalanceLimit = MAX_EFFECTIVE_BALANCE;
+    } else {
+      // from electra, effectiveBalanceLimit is per validator
+      effectiveBalanceLimit = isCompoundingValidatorArr[i] ? MAX_EFFECTIVE_BALANCE_ELECTRA : MIN_ACTIVATION_BALANCE;
+    }
+
+    if (
+      // Too big
+      effectiveBalance > balance + DOWNWARD_THRESHOLD ||
+      // Too small. Check effectiveBalance < MAX_EFFECTIVE_BALANCE to prevent unnecessary updates
+      (effectiveBalance < effectiveBalanceLimit && effectiveBalance + UPWARD_THRESHOLD < balance)
+    ) {
+      // Update the state tree
+      // Should happen rarely, so it's fine to update the tree
+      const validator = validators.get(i);
+
+      effectiveBalance = Math.min(balance - (balance % EFFECTIVE_BALANCE_INCREMENT), effectiveBalanceLimit);
+      validator.effectiveBalance = effectiveBalance;
+      // Also update the fast cached version
+      const newEffectiveBalanceIncrement = Math.floor(effectiveBalance / EFFECTIVE_BALANCE_INCREMENT);
+
+      // TODO: describe issue. Compute progressive target balances
+      // Must update target balances for consistency, see comments below
+      if (forkSeq >= ForkSeq.altair) {
+        const deltaEffectiveBalanceIncrement = newEffectiveBalanceIncrement - effectiveBalanceIncrement;
+        const {previousEpochParticipation, currentEpochParticipation} = state as BeaconStateAltair;
+
+        if (!validator.slashed && (previousEpochParticipation.get(i) & TIMELY_TARGET) === TIMELY_TARGET) {
+          epochCtx.previousTargetUnslashedBalanceIncrements += deltaEffectiveBalanceIncrement;
+        }
+
+        // currentTargetUnslashedBalanceIncrements is transfered to previousTargetUnslashedBalanceIncrements in afterEpochTransitionCache
+        // at epoch transition of next epoch (in EpochTransitionCache), prevTargetUnslStake is calculated based on newEffectiveBalanceIncrement
+        if (!validator.slashed && (currentEpochParticipation.get(i) & TIMELY_TARGET) === TIMELY_TARGET) {
+          epochCtx.currentTargetUnslashedBalanceIncrements += deltaEffectiveBalanceIncrement;
+        }
+      }
+
+      effectiveBalanceIncrement = newEffectiveBalanceIncrement;
+      effectiveBalanceIncrements[i] = effectiveBalanceIncrement;
+      numUpdate++;
+    }
+
+    // TODO: Do this in afterEpochTransitionCache, looping a Uint8Array should be very cheap
+    if (cache.isActiveNextEpoch[i]) {
+      // We track nextEpochTotalActiveBalanceByIncrement as ETH to fit total network balance in a JS number (53 bits)
+      nextEpochTotalActiveBalanceByIncrement += effectiveBalanceIncrement;
+    }
+  }
+
+  cache.nextEpochTotalActiveBalanceByIncrement = nextEpochTotalActiveBalanceByIncrement;
+  return numUpdate;
+}

package/src/epoch/processEth1DataReset.ts

@@ -0,0 +1,17 @@
+import {EPOCHS_PER_ETH1_VOTING_PERIOD} from "@lodestar/params";
+import {ssz} from "@lodestar/types";
+import {CachedBeaconStateAllForks, EpochTransitionCache} from "../types.js";
+
+/**
+ * Reset eth1DataVotes tree every `EPOCHS_PER_ETH1_VOTING_PERIOD`.
+ *
+ * PERF: Almost no (constant) cost
+ */
+export function processEth1DataReset(state: CachedBeaconStateAllForks, cache: EpochTransitionCache): void {
+  const nextEpoch = cache.currentEpoch + 1;
+
+  // reset eth1 data votes
+  if (nextEpoch % EPOCHS_PER_ETH1_VOTING_PERIOD === 0) {
+    state.eth1DataVotes = ssz.phase0.Eth1DataVotes.defaultViewDU();
+  }
+}

package/src/epoch/processHistoricalRootsUpdate.ts

@@ -0,0 +1,25 @@
+import {SLOTS_PER_EPOCH, SLOTS_PER_HISTORICAL_ROOT} from "@lodestar/params";
+import {ssz} from "@lodestar/types";
+import {intDiv} from "@lodestar/utils";
+import {CachedBeaconStateAllForks, EpochTransitionCache} from "../types.js";
+
+/**
+ * Persist blockRoots and stateRoots to historicalRoots.
+ *
+ * PERF: Very low (constant) cost. Most of the HistoricalBatch should already be hashed.
+ */
+export function processHistoricalRootsUpdate(state: CachedBeaconStateAllForks, cache: EpochTransitionCache): void {
+  const nextEpoch = cache.currentEpoch + 1;
+
+  // set historical root accumulator
+  if (nextEpoch % intDiv(SLOTS_PER_HISTORICAL_ROOT, SLOTS_PER_EPOCH) === 0) {
+    state.historicalRoots.push(
+      // HistoricalBatchRoots = Non-spec'ed helper type to allow efficient hashing in epoch transition.
+      // This type is like a 'Header' of HistoricalBatch where its fields are hashed.
+      ssz.phase0.HistoricalBatchRoots.hashTreeRoot({
+        blockRoots: state.blockRoots.hashTreeRoot(),
+        stateRoots: state.stateRoots.hashTreeRoot(),
+      })
+    );
+  }
+}

package/src/epoch/processHistoricalSummariesUpdate.ts

@@ -0,0 +1,23 @@
+import {SLOTS_PER_EPOCH, SLOTS_PER_HISTORICAL_ROOT} from "@lodestar/params";
+import {ssz} from "@lodestar/types";
+import {intDiv} from "@lodestar/utils";
+import {CachedBeaconStateCapella, EpochTransitionCache} from "../types.js";
+
+/**
+ * Persist blockRoots and stateRoots to historicalSummaries.
+ *
+ * PERF: Very low (constant) cost. Most of the HistoricalSummaries should already be hashed.
+ */
+export function processHistoricalSummariesUpdate(state: CachedBeaconStateCapella, cache: EpochTransitionCache): void {
+  const nextEpoch = cache.currentEpoch + 1;
+
+  // set historical root accumulator
+  if (nextEpoch % intDiv(SLOTS_PER_HISTORICAL_ROOT, SLOTS_PER_EPOCH) === 0) {
+    state.historicalSummaries.push(
+      ssz.capella.HistoricalSummary.toViewDU({
+        blockSummaryRoot: state.blockRoots.hashTreeRoot(),
+        stateSummaryRoot: state.stateRoots.hashTreeRoot(),
+      })
+    );
+  }
+}

package/src/epoch/processInactivityUpdates.ts

@@ -0,0 +1,60 @@
+import {GENESIS_EPOCH} from "@lodestar/params";
+import {CachedBeaconStateAltair, EpochTransitionCache} from "../types.js";
+import * as attesterStatusUtil from "../util/attesterStatus.js";
+import {isInInactivityLeak} from "../util/index.js";
+
+/**
+ * This data is reused and never gc.
+ */
+const inactivityScoresArr = new Array<number>();
+
+/**
+ * Mutates `inactivityScores` from pre-calculated validator flags.
+ *
+ * PERF: Cost = iterate over an array of size $VALIDATOR_COUNT + 'proportional' to how many validtors are inactive or
+ * have been inactive in the past, i.e. that require an update to their inactivityScore. Worst case = all validators
+ * need to update their non-zero `inactivityScore`.
+ *
+ * - On normal mainnet conditions
+ *   - prevTargetAttester: 96%
+ *   - unslashed:          100%
+ *   - eligibleAttester:   98%
+ *
+ * TODO: Compute from altair testnet inactivityScores updates on average
+ */
+export function processInactivityUpdates(state: CachedBeaconStateAltair, cache: EpochTransitionCache): void {
+  if (state.epochCtx.epoch === GENESIS_EPOCH) {
+    return;
+  }
+
+  const {config, inactivityScores} = state;
+  const {INACTIVITY_SCORE_BIAS, INACTIVITY_SCORE_RECOVERY_RATE} = config;
+  const {flags} = cache;
+  const inActivityLeak = isInInactivityLeak(state);
+
+  // this avoids importing FLAG_ELIGIBLE_ATTESTER inside the for loop, check the compiled code
+  const {FLAG_PREV_TARGET_ATTESTER_UNSLASHED, FLAG_ELIGIBLE_ATTESTER, hasMarkers} = attesterStatusUtil;
+
+  inactivityScoresArr.length = state.validators.length;
+  inactivityScores.getAll(inactivityScoresArr);
+
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i];
+    if (hasMarkers(flag, FLAG_ELIGIBLE_ATTESTER)) {
+      let inactivityScore = inactivityScoresArr[i];
+
+      const prevInactivityScore = inactivityScore;
+      if (hasMarkers(flag, FLAG_PREV_TARGET_ATTESTER_UNSLASHED)) {
+        inactivityScore -= Math.min(1, inactivityScore);
+      } else {
+        inactivityScore += INACTIVITY_SCORE_BIAS;
+      }
+      if (!inActivityLeak) {
+        inactivityScore -= Math.min(INACTIVITY_SCORE_RECOVERY_RATE, inactivityScore);
+      }
+      if (inactivityScore !== prevInactivityScore) {
+        inactivityScores.set(i, inactivityScore);
+      }
+    }
+  }
+}

package/src/epoch/processJustificationAndFinalization.ts

@@ -0,0 +1,90 @@
+import {BitArray} from "@chainsafe/ssz";
+import {GENESIS_EPOCH} from "@lodestar/params";
+import {ssz} from "@lodestar/types";
+import {CachedBeaconStateAllForks, EpochTransitionCache} from "../types.js";
+import {computeEpochAtSlot, getBlockRoot} from "../util/index.js";
+
+/**
+ * Update justified and finalized checkpoints depending on network participation.
+ *
+ * PERF: Very low (constant) cost. Persist small objects to the tree.
+ */
+export function processJustificationAndFinalization(
+  state: CachedBeaconStateAllForks,
+  cache: EpochTransitionCache
+): void {
+  // Initial FFG checkpoint values have a `0x00` stub for `root`.
+  // Skip FFG updates in the first two epochs to avoid corner cases that might result in modifying this stub.
+  if (cache.currentEpoch <= GENESIS_EPOCH + 1) {
+    return;
+  }
+  weighJustificationAndFinalization(
+    state,
+    cache.totalActiveStakeByIncrement,
+    cache.prevEpochUnslashedStake.targetStakeByIncrement,
+    cache.currEpochUnslashedTargetStakeByIncrement
+  );
+}
+
+/**
+ * Updates `state` checkpoints based on previous and current target balance
+ */
+export function weighJustificationAndFinalization(
+  state: CachedBeaconStateAllForks,
+  totalActiveBalance: number,
+  previousEpochTargetBalance: number,
+  currentEpochTargetBalance: number
+): void {
+  const currentEpoch = computeEpochAtSlot(state.slot);
+  const previousEpoch = currentEpoch - 1;
+
+  const oldPreviousJustifiedCheckpoint = state.previousJustifiedCheckpoint;
+  const oldCurrentJustifiedCheckpoint = state.currentJustifiedCheckpoint;
+
+  // Process justifications
+  state.previousJustifiedCheckpoint = state.currentJustifiedCheckpoint;
+  const bits = state.justificationBits.toBoolArray();
+
+  // Rotate bits
+  for (let i = bits.length - 1; i >= 1; i--) {
+    bits[i] = bits[i - 1];
+  }
+  bits[0] = false;
+
+  if (previousEpochTargetBalance * 3 >= totalActiveBalance * 2) {
+    state.currentJustifiedCheckpoint = ssz.phase0.Checkpoint.toViewDU({
+      epoch: previousEpoch,
+      root: getBlockRoot(state, previousEpoch),
+    });
+    bits[1] = true;
+  }
+  if (currentEpochTargetBalance * 3 >= totalActiveBalance * 2) {
+    state.currentJustifiedCheckpoint = ssz.phase0.Checkpoint.toViewDU({
+      epoch: currentEpoch,
+      root: getBlockRoot(state, currentEpoch),
+    });
+    bits[0] = true;
+  }
+
+  state.justificationBits = ssz.phase0.JustificationBits.toViewDU(BitArray.fromBoolArray(bits));
+
+  // TODO: Consider rendering bits as array of boolean for faster repeated access here
+
+  // Process finalizations
+  // The 2nd/3rd/4th most recent epochs are all justified, the 2nd using the 4th as source
+  if (bits[1] && bits[2] && bits[3] && oldPreviousJustifiedCheckpoint.epoch + 3 === currentEpoch) {
+    state.finalizedCheckpoint = oldPreviousJustifiedCheckpoint;
+  }
+  // The 2nd/3rd most recent epochs are both justified, the 2nd using the 3rd as source
+  if (bits[1] && bits[2] && oldPreviousJustifiedCheckpoint.epoch + 2 === currentEpoch) {
+    state.finalizedCheckpoint = oldPreviousJustifiedCheckpoint;
+  }
+  // The 1st/2nd/3rd most recent epochs are all justified, the 1st using the 3rd as source
+  if (bits[0] && bits[1] && bits[2] && oldCurrentJustifiedCheckpoint.epoch + 2 === currentEpoch) {
+    state.finalizedCheckpoint = oldCurrentJustifiedCheckpoint;
+  }
+  // The 1st/2nd most recent epochs are both justified, the 1st using the 2nd as source
+  if (bits[0] && bits[1] && oldCurrentJustifiedCheckpoint.epoch + 1 === currentEpoch) {
+    state.finalizedCheckpoint = oldCurrentJustifiedCheckpoint;
+  }
+}