@lodestar/state-transition 1.35.0-dev.a70bac5bd3 → 1.35.0-dev.ba92bd8a88

package/src/util/targetUnslashedBalance.ts

@@ -0,0 +1,30 @@
+import {EFFECTIVE_BALANCE_INCREMENT, TIMELY_TARGET_FLAG_INDEX} from "@lodestar/params";
+import {Epoch, phase0} from "@lodestar/types";
+import {isActiveValidator} from "./validator.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;
+
+/**
+ * TODO: describe issue. Compute progressive target balances
+ * Compute balances from zero, note this state could be mid-epoch so target balances != 0
+ * @param participation from `state.previousEpochParticipation.getAll()`
+ * @param epoch either currentEpoch or previousEpoch
+ * @param validators from `state.validators.getAllReadonlyValues()`
+ */
+export function sumTargetUnslashedBalanceIncrements(
+  participation: number[],
+  epoch: Epoch,
+  validators: phase0.Validator[]
+): number {
+  let total = 0;
+  for (let i = 0; i < participation.length; i++) {
+    if ((participation[i] & TIMELY_TARGET) === TIMELY_TARGET) {
+      const validator = validators[i];
+      if (isActiveValidator(validator, epoch) && !validator.slashed) {
+        total += Math.floor(validator.effectiveBalance / EFFECTIVE_BALANCE_INCREMENT);
+      }
+    }
+  }
+  return total;
+}

package/src/util/validator.ts

@@ -0,0 +1,105 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {
+  EFFECTIVE_BALANCE_INCREMENT,
+  ForkSeq,
+  MAX_EFFECTIVE_BALANCE_ELECTRA,
+  MIN_ACTIVATION_BALANCE,
+} from "@lodestar/params";
+import {Epoch, ValidatorIndex, phase0} from "@lodestar/types";
+import {intDiv} from "@lodestar/utils";
+import {BeaconStateAllForks, CachedBeaconStateElectra, EpochCache} from "../types.js";
+import {hasCompoundingWithdrawalCredential} from "./electra.js";
+
+/**
+ * Check if [[validator]] is active
+ */
+export function isActiveValidator(validator: phase0.Validator, epoch: Epoch): boolean {
+  return validator.activationEpoch <= epoch && epoch < validator.exitEpoch;
+}
+
+/**
+ * Check if [[validator]] is slashable
+ */
+export function isSlashableValidator(validator: phase0.Validator, epoch: Epoch): boolean {
+  return !validator.slashed && validator.activationEpoch <= epoch && epoch < validator.withdrawableEpoch;
+}
+
+/**
+ * Return the sequence of active validator indices at [[epoch]].
+ *
+ * NAIVE - SLOW CODE 🐢
+ */
+export function getActiveValidatorIndices(state: BeaconStateAllForks, epoch: Epoch): Uint32Array {
+  const indices: ValidatorIndex[] = [];
+
+  const validatorsArr = state.validators.getAllReadonlyValues();
+  for (let i = 0; i < validatorsArr.length; i++) {
+    if (isActiveValidator(validatorsArr[i], epoch)) {
+      indices.push(i);
+    }
+  }
+
+  return new Uint32Array(indices);
+}
+
+export function getActivationChurnLimit(config: ChainForkConfig, fork: ForkSeq, activeValidatorCount: number): number {
+  if (fork >= ForkSeq.deneb) {
+    return Math.min(config.MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT, getChurnLimit(config, activeValidatorCount));
+  }
+  return getChurnLimit(config, activeValidatorCount);
+}
+
+export function getChurnLimit(config: ChainForkConfig, activeValidatorCount: number): number {
+  return Math.max(config.MIN_PER_EPOCH_CHURN_LIMIT, intDiv(activeValidatorCount, config.CHURN_LIMIT_QUOTIENT));
+}
+
+/**
+ * Get combined churn limit of activation-exit and consolidation
+ */
+export function getBalanceChurnLimit(
+  totalActiveBalanceIncrements: number,
+  churnLimitQuotient: number,
+  minPerEpochChurnLimit: number
+): number {
+  const churnLimitByTotalActiveBalance = Math.floor(
+    (totalActiveBalanceIncrements / churnLimitQuotient) * EFFECTIVE_BALANCE_INCREMENT
+  );
+
+  const churn = Math.max(churnLimitByTotalActiveBalance, minPerEpochChurnLimit);
+
+  return churn - (churn % EFFECTIVE_BALANCE_INCREMENT);
+}
+
+export function getBalanceChurnLimitFromCache(epochCtx: EpochCache): number {
+  return getBalanceChurnLimit(
+    epochCtx.totalActiveBalanceIncrements,
+    epochCtx.config.CHURN_LIMIT_QUOTIENT,
+    epochCtx.config.MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA
+  );
+}
+
+export function getActivationExitChurnLimit(epochCtx: EpochCache): number {
+  return Math.min(epochCtx.config.MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT, getBalanceChurnLimitFromCache(epochCtx));
+}
+
+export function getConsolidationChurnLimit(epochCtx: EpochCache): number {
+  return getBalanceChurnLimitFromCache(epochCtx) - getActivationExitChurnLimit(epochCtx);
+}
+
+export function getMaxEffectiveBalance(withdrawalCredentials: Uint8Array): number {
+  // Compounding withdrawal credential only available since Electra
+  if (hasCompoundingWithdrawalCredential(withdrawalCredentials)) {
+    return MAX_EFFECTIVE_BALANCE_ELECTRA;
+  }
+  return MIN_ACTIVATION_BALANCE;
+}
+
+export function getPendingBalanceToWithdraw(state: CachedBeaconStateElectra, validatorIndex: ValidatorIndex): number {
+  let total = 0;
+  for (const item of state.pendingPartialWithdrawals.getAllReadonly()) {
+    if (item.validatorIndex === validatorIndex) {
+      total += Number(item.amount);
+    }
+  }
+  return total;
+}

package/src/util/weakSubjectivity.ts

@@ -0,0 +1,186 @@
+import {BeaconConfig, ChainForkConfig} from "@lodestar/config";
+import {
+  EFFECTIVE_BALANCE_INCREMENT,
+  MAX_DEPOSITS,
+  MAX_EFFECTIVE_BALANCE,
+  SLOTS_PER_EPOCH,
+  isForkPostElectra,
+} from "@lodestar/params";
+import {Epoch, Root, ssz} from "@lodestar/types";
+import {Checkpoint} from "@lodestar/types/phase0";
+import {toRootHex} from "@lodestar/utils";
+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 {
+  getActiveValidatorIndices,
+  getBalanceChurnLimit,
+  getBalanceChurnLimitFromCache,
+  getChurnLimit,
+} from "./validator.js";
+
+export const ETH_TO_GWEI = 10 ** 9;
+const SAFETY_DECAY = 10;
+
+/**
+ * Returns the epoch of the latest weak subjectivity checkpoint for the given
+  `state` and `safetyDecay`. The default `safetyDecay` used should be 10% (= 0.1)
+ */
+export function getLatestWeakSubjectivityCheckpointEpoch(
+  config: ChainForkConfig,
+  state: CachedBeaconStateAllForks
+): Epoch {
+  return state.epochCtx.epoch - computeWeakSubjectivityPeriodCachedState(config, state);
+}
+
+/**
+  Returns the weak subjectivity period for the current `state`.
+    This computation takes into account the effect of:
+      - validator set churn (bounded by `get_validator_churn_limit()` per epoch), and
+      - validator balance top-ups (bounded by `MAX_DEPOSITS * SLOTS_PER_EPOCH` per epoch).
+    A detailed calculation can be found at:
+    https://github.com/runtimeverification/beacon-chain-verification/blob/master/weak-subjectivity/weak-subjectivity-analysis.pdf
+ */
+export function computeWeakSubjectivityPeriodCachedState(
+  config: ChainForkConfig,
+  state: CachedBeaconStateAllForks
+): number {
+  const activeValidatorCount = state.epochCtx.currentShuffling.activeIndices.length;
+  const fork = state.config.getForkName(state.slot);
+
+  return isForkPostElectra(fork)
+    ? computeWeakSubjectivityPeriodFromConstituentsElectra(
+        state.epochCtx.totalActiveBalanceIncrements,
+        getBalanceChurnLimitFromCache(state.epochCtx),
+        config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
+      )
+    : computeWeakSubjectivityPeriodFromConstituentsPhase0(
+        activeValidatorCount,
+        state.epochCtx.totalActiveBalanceIncrements,
+        getChurnLimit(config, activeValidatorCount),
+        config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
+      );
+}
+
+/**
+ * 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) {
+    totalActiveBalanceIncrements += Math.floor(validators[index].effectiveBalance / EFFECTIVE_BALANCE_INCREMENT);
+  }
+  if (totalActiveBalanceIncrements <= 1) {
+    totalActiveBalanceIncrements = 1;
+  }
+
+  return isForkPostElectra(fork)
+    ? computeWeakSubjectivityPeriodFromConstituentsElectra(
+        totalActiveBalanceIncrements,
+        getBalanceChurnLimit(
+          totalActiveBalanceIncrements,
+          config.CHURN_LIMIT_QUOTIENT,
+          config.MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA
+        ),
+        config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
+      )
+    : computeWeakSubjectivityPeriodFromConstituentsPhase0(
+        activeIndices.length,
+        totalActiveBalanceIncrements,
+        getChurnLimit(config, activeIndices.length),
+        config.MIN_VALIDATOR_WITHDRAWABILITY_DELAY
+      );
+}
+
+export function computeWeakSubjectivityPeriodFromConstituentsPhase0(
+  activeValidatorCount: number,
+  totalBalanceByIncrement: number,
+  churnLimit: number,
+  minWithdrawabilityDelay: number
+): number {
+  const N = activeValidatorCount;
+  // originally const t = Number(totalBalance / BigInt(N) / BigInt(ETH_TO_GWEI));
+  // totalBalanceByIncrement = totalBalance / MAX_EFFECTIVE_BALANCE and MAX_EFFECTIVE_BALANCE = ETH_TO_GWEI atm
+  // we need to change this calculation just in case MAX_EFFECTIVE_BALANCE != ETH_TO_GWEI
+  const t = Math.floor(totalBalanceByIncrement / N);
+  const T = MAX_EFFECTIVE_BALANCE / ETH_TO_GWEI;
+  const delta = churnLimit;
+  const Delta = MAX_DEPOSITS * SLOTS_PER_EPOCH;
+  const D = SAFETY_DECAY;
+
+  let wsPeriod = minWithdrawabilityDelay;
+  if (T * (200 + 3 * D) < t * (200 + 12 * D)) {
+    const epochsForValidatorSetChurn = Math.floor(
+      (N * (t * (200 + 12 * D) - T * (200 + 3 * D))) / (600 * delta * (2 * t + T))
+    );
+    const epochsForBalanceTopUps = Math.floor((N * (200 + 3 * D)) / (600 * Delta));
+    wsPeriod +=
+      epochsForValidatorSetChurn > epochsForBalanceTopUps ? epochsForValidatorSetChurn : epochsForBalanceTopUps;
+  } else {
+    wsPeriod += Math.floor((3 * N * D * t) / (200 * Delta * (T - t)));
+  }
+  return wsPeriod;
+}
+
+export function computeWeakSubjectivityPeriodFromConstituentsElectra(
+  totalBalanceByIncrement: number,
+  // Note this is not the same as churnLimit in `computeWeakSubjectivityPeriodFromConstituentsPhase0`
+  balanceChurnLimit: number,
+  minWithdrawabilityDelay: number
+): number {
+  // Keep t as increment for now. Multiply final result by EFFECTIVE_BALANCE_INCREMENT
+  const t = totalBalanceByIncrement;
+  const delta = balanceChurnLimit;
+  const epochsForValidatorSetChurn = Math.floor(((SAFETY_DECAY * t) / (2 * delta * 100)) * EFFECTIVE_BALANCE_INCREMENT);
+
+  return minWithdrawabilityDelay + epochsForValidatorSetChurn;
+}
+
+export function getLatestBlockRoot(state: BeaconStateAllForks): Root {
+  const header = ssz.phase0.BeaconBlockHeader.clone(state.latestBlockHeader);
+  if (ssz.Root.equals(header.stateRoot, ZERO_HASH)) {
+    header.stateRoot = state.hashTreeRoot();
+  }
+  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 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`
+    );
+  }
+}