@lodestar/state-transition 1.35.0-dev.8ea34e52ba → 1.35.0-dev.901d719660

package/src/util/epochShuffling.ts

@@ -0,0 +1,185 @@
+import {asyncUnshuffleList, unshuffleList} from "@chainsafe/swap-or-not-shuffle";
+import {BeaconConfig} from "@lodestar/config";
+import {
+  DOMAIN_BEACON_ATTESTER,
+  GENESIS_SLOT,
+  MAX_COMMITTEES_PER_SLOT,
+  SHUFFLE_ROUND_COUNT,
+  SLOTS_PER_EPOCH,
+  TARGET_COMMITTEE_SIZE,
+} from "@lodestar/params";
+import {Epoch, RootHex, ValidatorIndex, ssz} from "@lodestar/types";
+import {GaugeExtra, Logger, NoLabels, intDiv, toRootHex} from "@lodestar/utils";
+import {BeaconStateAllForks} from "../types.js";
+import {getBlockRootAtSlot} from "./blockRoot.js";
+import {computeAnchorCheckpoint} from "./computeAnchorCheckpoint.js";
+import {computeStartSlotAtEpoch} from "./epoch.js";
+import {getSeed} from "./seed.js";
+
+export interface ShufflingBuildProps {
+  state: BeaconStateAllForks;
+  activeIndices: Uint32Array;
+}
+
+export interface PublicShufflingCacheMetrics {
+  shufflingCache: {
+    nextShufflingNotOnEpochCache: GaugeExtra<NoLabels>;
+  };
+}
+export interface IShufflingCache {
+  metrics: PublicShufflingCacheMetrics | null;
+  logger: Logger | null;
+  /**
+   * Gets a cached shuffling via the epoch and decision root. If the state and
+   * activeIndices are passed and a shuffling is not available it will be built
+   * synchronously. If the state is not passed and the shuffling is not available
+   * nothing will be returned.
+   *
+   * NOTE: If a shuffling is already queued and not calculated it will build and resolve
+   * the promise but the already queued build will happen at some later time
+   */
+  getSync<T extends ShufflingBuildProps | undefined>(
+    epoch: Epoch,
+    decisionRoot: RootHex,
+    buildProps?: T
+  ): T extends ShufflingBuildProps ? EpochShuffling : EpochShuffling | null;
+
+  /**
+   * Gets a cached shuffling via the epoch and decision root.  Returns a promise
+   * for the shuffling if it hs not calculated yet.  Returns null if a build has
+   * not been queued nor a shuffling was calculated.
+   */
+  get(epoch: Epoch, decisionRoot: RootHex): Promise<EpochShuffling | null>;
+
+  /**
+   * Queue asynchronous build for an EpochShuffling
+   */
+  build(epoch: Epoch, decisionRoot: RootHex, state: BeaconStateAllForks, activeIndices: Uint32Array): void;
+}
+
+/**
+ * Readonly interface for EpochShuffling.
+ */
+export type ReadonlyEpochShuffling = {
+  readonly epoch: Epoch;
+  readonly committees: Readonly<ValidatorIndex[][][]>;
+};
+
+export type EpochShuffling = {
+  /**
+   * Epoch being shuffled
+   */
+  epoch: Epoch;
+
+  /**
+   * Non-shuffled active validator indices
+   */
+  activeIndices: Uint32Array;
+
+  /**
+   * The active validator indices, shuffled into their committee
+   */
+  shuffling: Uint32Array;
+
+  /**
+   * List of list of committees Committees
+   *
+   * Committees by index, by slot
+   *
+   * Note: With a high amount of shards, or low amount of validators,
+   * some shards may not have a committee this epoch
+   */
+  committees: Uint32Array[][];
+
+  /**
+   * Committees per slot, for fast attestation verification
+   */
+  committeesPerSlot: number;
+};
+
+export function computeCommitteeCount(activeValidatorCount: number): number {
+  const validatorsPerSlot = intDiv(activeValidatorCount, SLOTS_PER_EPOCH);
+  const committeesPerSlot = intDiv(validatorsPerSlot, TARGET_COMMITTEE_SIZE);
+  return Math.max(1, Math.min(MAX_COMMITTEES_PER_SLOT, committeesPerSlot));
+}
+
+function buildCommitteesFromShuffling(shuffling: Uint32Array): Uint32Array[][] {
+  const activeValidatorCount = shuffling.length;
+  const committeesPerSlot = computeCommitteeCount(activeValidatorCount);
+  const committeeCount = committeesPerSlot * SLOTS_PER_EPOCH;
+
+  const committees = new Array<Uint32Array[]>(SLOTS_PER_EPOCH);
+  for (let slot = 0; slot < SLOTS_PER_EPOCH; slot++) {
+    const slotCommittees = new Array<Uint32Array>(committeesPerSlot);
+
+    for (let committeeIndex = 0; committeeIndex < committeesPerSlot; committeeIndex++) {
+      const index = slot * committeesPerSlot + committeeIndex;
+      const startOffset = Math.floor((activeValidatorCount * index) / committeeCount);
+      const endOffset = Math.floor((activeValidatorCount * (index + 1)) / committeeCount);
+      if (!(startOffset <= endOffset)) {
+        throw new Error(`Invalid offsets: start ${startOffset} must be less than or equal end ${endOffset}`);
+      }
+      slotCommittees[committeeIndex] = shuffling.subarray(startOffset, endOffset);
+    }
+
+    committees[slot] = slotCommittees;
+  }
+
+  return committees;
+}
+
+export function computeEpochShuffling(
+  // TODO: (@matthewkeil) remove state/epoch and pass in seed to clean this up
+  state: BeaconStateAllForks,
+  activeIndices: Uint32Array,
+  epoch: Epoch
+): EpochShuffling {
+  const seed = getSeed(state, epoch, DOMAIN_BEACON_ATTESTER);
+  const shuffling = unshuffleList(activeIndices, seed, SHUFFLE_ROUND_COUNT);
+  const committees = buildCommitteesFromShuffling(shuffling);
+  return {
+    epoch,
+    activeIndices,
+    shuffling,
+    committees,
+    committeesPerSlot: committees[0].length,
+  };
+}
+
+export async function computeEpochShufflingAsync(
+  // TODO: (@matthewkeil) remove state/epoch and pass in seed to clean this up
+  state: BeaconStateAllForks,
+  activeIndices: Uint32Array,
+  epoch: Epoch
+): Promise<EpochShuffling> {
+  const seed = getSeed(state, epoch, DOMAIN_BEACON_ATTESTER);
+  const shuffling = await asyncUnshuffleList(activeIndices, seed, SHUFFLE_ROUND_COUNT);
+  const committees = buildCommitteesFromShuffling(shuffling);
+  return {
+    epoch,
+    activeIndices,
+    shuffling,
+    committees,
+    committeesPerSlot: committees[0].length,
+  };
+}
+
+function calculateDecisionRoot(state: BeaconStateAllForks, epoch: Epoch): RootHex {
+  const pivotSlot = computeStartSlotAtEpoch(epoch - 1) - 1;
+  return toRootHex(getBlockRootAtSlot(state, pivotSlot));
+}
+
+/**
+ * Get the shuffling decision block root for the given epoch of given state
+ *   - Special case close to genesis block, return the genesis block root
+ *   - This is similar to forkchoice.getDependentRoot() function, otherwise we cannot get cached shuffing in attestation verification when syncing from genesis.
+ */
+export function calculateShufflingDecisionRoot(
+  config: BeaconConfig,
+  state: BeaconStateAllForks,
+  epoch: Epoch
+): RootHex {
+  return state.slot > GENESIS_SLOT
+    ? calculateDecisionRoot(state, epoch)
+    : toRootHex(ssz.phase0.BeaconBlockHeader.hashTreeRoot(computeAnchorCheckpoint(config, state).blockHeader));
+}

package/src/util/execution.ts

@@ -0,0 +1,177 @@
+import {ForkName, ForkPostBellatrix, ForkSeq} from "@lodestar/params";
+import {
+  BeaconBlock,
+  BeaconBlockBody,
+  BlindedBeaconBlock,
+  BlindedBeaconBlockBody,
+  ExecutionPayload,
+  ExecutionPayloadHeader,
+  bellatrix,
+  capella,
+  deneb,
+  isBlindedBeaconBlockBody,
+  isExecutionPayload,
+  ssz,
+} from "@lodestar/types";
+import {
+  BeaconStateAllForks,
+  BeaconStateBellatrix,
+  BeaconStateCapella,
+  BeaconStateExecutions,
+  CachedBeaconStateAllForks,
+  CachedBeaconStateExecutions,
+} from "../types.js";
+
+/**
+ * Execution enabled = merge is done.
+ * When (A) state has execution data OR (B) block has execution data
+ */
+export function isExecutionEnabled(state: BeaconStateExecutions, block: BeaconBlock | BlindedBeaconBlock): boolean {
+  if (isMergeTransitionComplete(state)) {
+    return true;
+  }
+
+  // Throws if not post-bellatrix block. A fork-guard in isExecutionEnabled() prevents this from happening
+  const payload = getFullOrBlindedPayload(block);
+  // Note: spec says to check all payload is zero-ed. However a state-root cannot be zero for any non-empty payload
+  // TODO: Consider comparing with the payload root if this assumption is not correct.
+  // return !byteArrayEquals(payload.stateRoot, ZERO_HASH);
+
+  // UPDATE: stateRoot comparision should have been enough with zero hash, but spec tests were failing
+  // Revisit this later to fix specs and make this efficient
+  return isExecutionPayload(payload)
+    ? !ssz.bellatrix.ExecutionPayload.equals(payload, ssz.bellatrix.ExecutionPayload.defaultValue())
+    : !ssz.bellatrix.ExecutionPayloadHeader.equals(
+        state.latestExecutionPayloadHeader,
+        // TODO: Performance
+        ssz.bellatrix.ExecutionPayloadHeader.defaultValue()
+      );
+}
+
+/**
+ * Merge block is the SINGLE block that transitions from POW to POS.
+ * state has no execution data AND this block has execution data
+ */
+export function isMergeTransitionBlock(state: BeaconStateExecutions, body: bellatrix.BeaconBlockBody): boolean {
+  return (
+    !isMergeTransitionComplete(state) &&
+    !ssz.bellatrix.ExecutionPayload.equals(body.executionPayload, ssz.bellatrix.ExecutionPayload.defaultValue())
+  );
+}
+
+/**
+ * Merge is complete when the state includes execution layer data:
+ * state.latestExecutionPayloadHeader NOT EMPTY
+ */
+export function isMergeTransitionComplete(state: BeaconStateExecutions): boolean {
+  if (!isCapellaStateType(state)) {
+    return !ssz.bellatrix.ExecutionPayloadHeader.equals(
+      (state as BeaconStateBellatrix).latestExecutionPayloadHeader,
+      // TODO: Performance
+      ssz.bellatrix.ExecutionPayloadHeader.defaultValue()
+    );
+  }
+
+  return !ssz.capella.ExecutionPayloadHeader.equals(
+    state.latestExecutionPayloadHeader,
+    // TODO: Performance
+    ssz.capella.ExecutionPayloadHeader.defaultValue()
+  );
+}
+
+/** Type guard for bellatrix.BeaconState */
+export function isExecutionStateType(state: BeaconStateAllForks): state is BeaconStateExecutions {
+  return (state as BeaconStateExecutions).latestExecutionPayloadHeader !== undefined;
+}
+
+/** Type guard for capella.BeaconState */
+export function isCapellaStateType(state: BeaconStateAllForks): state is BeaconStateCapella {
+  return (
+    (state as BeaconStateCapella).latestExecutionPayloadHeader !== undefined &&
+    (state as BeaconStateCapella).latestExecutionPayloadHeader.withdrawalsRoot !== undefined
+  );
+}
+
+/** Type guard for bellatrix.CachedBeaconState */
+export function isExecutionCachedStateType(state: CachedBeaconStateAllForks): state is CachedBeaconStateExecutions {
+  return (state as CachedBeaconStateExecutions).latestExecutionPayloadHeader !== undefined;
+}
+
+/** Type guard for ExecutionBlockBody */
+export function isExecutionBlockBodyType(blockBody: BeaconBlockBody): blockBody is BeaconBlockBody<ForkPostBellatrix> {
+  return (blockBody as BeaconBlockBody<ForkPostBellatrix>).executionPayload !== undefined;
+}
+
+export function getFullOrBlindedPayload(block: BeaconBlock): ExecutionPayload | ExecutionPayloadHeader {
+  return getFullOrBlindedPayloadFromBody(block.body);
+}
+
+export function getFullOrBlindedPayloadFromBody(
+  body: BeaconBlockBody | BlindedBeaconBlockBody
+): ExecutionPayload | ExecutionPayloadHeader {
+  if (isBlindedBeaconBlockBody(body)) {
+    return body.executionPayloadHeader;
+  }
+
+  if ((body as bellatrix.BeaconBlockBody).executionPayload !== undefined) {
+    return (body as bellatrix.BeaconBlockBody).executionPayload;
+  }
+
+  throw Error("Not full or blinded beacon block");
+}
+
+export function isCapellaPayload(
+  payload: ExecutionPayload | ExecutionPayloadHeader
+): payload is ExecutionPayload<ForkName.capella> | ExecutionPayloadHeader<ForkName.capella> {
+  return (
+    (payload as ExecutionPayload<ForkName.capella>).withdrawals !== undefined ||
+    (payload as ExecutionPayloadHeader<ForkName.capella>).withdrawalsRoot !== undefined
+  );
+}
+
+export function isCapellaPayloadHeader(
+  payload: capella.FullOrBlindedExecutionPayload
+): payload is capella.ExecutionPayloadHeader {
+  return (payload as capella.ExecutionPayloadHeader).withdrawalsRoot !== undefined;
+}
+
+export function executionPayloadToPayloadHeader(fork: ForkSeq, payload: ExecutionPayload): ExecutionPayloadHeader {
+  const transactionsRoot = ssz.bellatrix.Transactions.hashTreeRoot(payload.transactions);
+
+  const bellatrixPayloadFields: ExecutionPayloadHeader = {
+    parentHash: payload.parentHash,
+    feeRecipient: payload.feeRecipient,
+    stateRoot: payload.stateRoot,
+    receiptsRoot: payload.receiptsRoot,
+    logsBloom: payload.logsBloom,
+    prevRandao: payload.prevRandao,
+    blockNumber: payload.blockNumber,
+    gasLimit: payload.gasLimit,
+    gasUsed: payload.gasUsed,
+    timestamp: payload.timestamp,
+    extraData: payload.extraData,
+    baseFeePerGas: payload.baseFeePerGas,
+    blockHash: payload.blockHash,
+    transactionsRoot,
+  };
+
+  if (fork >= ForkSeq.capella) {
+    (bellatrixPayloadFields as capella.ExecutionPayloadHeader).withdrawalsRoot = ssz.capella.Withdrawals.hashTreeRoot(
+      (payload as capella.ExecutionPayload).withdrawals
+    );
+  }
+
+  if (fork >= ForkSeq.deneb) {
+    // https://github.com/ethereum/consensus-specs/blob/dev/specs/eip4844/beacon-chain.md#process_execution_payload
+    (bellatrixPayloadFields as deneb.ExecutionPayloadHeader).blobGasUsed = (
+      payload as deneb.ExecutionPayloadHeader | deneb.ExecutionPayload
+    ).blobGasUsed;
+    (bellatrixPayloadFields as deneb.ExecutionPayloadHeader).excessBlobGas = (
+      payload as deneb.ExecutionPayloadHeader | deneb.ExecutionPayload
+    ).excessBlobGas;
+  }
+
+  // No change in Electra
+
+  return bellatrixPayloadFields;
+}

package/src/util/finality.ts

@@ -0,0 +1,17 @@
+import {MIN_EPOCHS_TO_INACTIVITY_PENALTY} from "@lodestar/params";
+import {CachedBeaconStateAllForks} from "../types.js";
+
+export function getFinalityDelay(state: CachedBeaconStateAllForks): number {
+  // previousEpoch = epoch - 1
+  return state.epochCtx.epoch - 1 - state.finalizedCheckpoint.epoch;
+}
+
+/**
+ * If the chain has not been finalized for >4 epochs, the chain enters an "inactivity leak" mode,
+ * where inactive validators get progressively penalized more and more, to reduce their influence
+ * until blocks get finalized again. See here (https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md#inactivity-quotient) for what the inactivity leak is, what it's for and how
+ * it works.
+ */
+export function isInInactivityLeak(state: CachedBeaconStateAllForks): boolean {
+  return getFinalityDelay(state) > MIN_EPOCHS_TO_INACTIVITY_PENALTY;
+}

package/src/util/fulu.ts

@@ -0,0 +1,43 @@
+import {ForkSeq, MIN_SEED_LOOKAHEAD} from "@lodestar/params";
+import {ValidatorIndex} from "@lodestar/types";
+import {CachedBeaconStateElectra} from "../types.js";
+import {computeEpochShuffling} from "./epochShuffling.js";
+import {computeProposerIndices} from "./seed.js";
+import {getActiveValidatorIndices} from "./validator.js";
+
+/**
+ * Return the proposer indices for the full available lookahead starting from current epoch.
+ * Used to initialize the `proposer_lookahead` field in the beacon state at genesis and after forks.
+ */
+export function initializeProposerLookahead(state: CachedBeaconStateElectra): ValidatorIndex[] {
+  const currentEpoch = state.epochCtx.epoch;
+
+  const lookahead: ValidatorIndex[] = [];
+
+  for (let i = 0; i <= MIN_SEED_LOOKAHEAD; i++) {
+    const epoch = currentEpoch + i;
+
+    // Try to pull cached shuffling first
+    let shuffling = state.epochCtx.getShufflingAtEpochOrNull(epoch);
+
+    if (!shuffling) {
+      // Only compute epoch shuffling if cache is not yet populated
+      let activeIndices: Uint32Array;
+      if (epoch === currentEpoch) {
+        // This should never happen as current shuffling will always be cached
+        activeIndices = state.epochCtx.currentShuffling.activeIndices;
+      } else if (epoch === currentEpoch + 1) {
+        activeIndices = state.epochCtx.nextActiveIndices;
+      } else {
+        // This will never be reached with current spec as `MIN_SEED_LOOKAHEAD == 1`
+        activeIndices = getActiveValidatorIndices(state, epoch);
+      }
+
+      shuffling = computeEpochShuffling(state, activeIndices, epoch);
+    }
+
+    lookahead.push(...computeProposerIndices(ForkSeq.fulu, state, shuffling, epoch));
+  }
+
+  return lookahead;
+}