@lodestar/state-transition 1.35.0-dev.e9dd48f165 → 1.35.0-dev.fcf8d024ea

package/src/util/blindedBlock.ts

@@ -0,0 +1,144 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {
+  ForkName,
+  ForkPostBellatrix,
+  ForkPostDeneb,
+  ForkSeq,
+  isForkPostBellatrix,
+  isForkPostDeneb,
+} from "@lodestar/params";
+import {
+  BeaconBlock,
+  BeaconBlockHeader,
+  BlindedBeaconBlock,
+  BlobsBundle,
+  ExecutionPayload,
+  ExecutionPayloadAndBlobsBundle,
+  ExecutionPayloadHeader,
+  Root,
+  SignedBeaconBlock,
+  SignedBlindedBeaconBlock,
+  SignedBlockContents,
+  isBlindedBeaconBlock,
+  isExecutionPayloadAndBlobsBundle,
+} from "@lodestar/types";
+import {executionPayloadToPayloadHeader} from "./execution.js";
+
+export function blindedOrFullBlockHashTreeRoot(
+  config: ChainForkConfig,
+  blindedOrFull: BeaconBlock | BlindedBeaconBlock
+): Root {
+  return isBlindedBeaconBlock(blindedOrFull)
+    ? // Blinded
+      config
+        .getPostBellatrixForkTypes(blindedOrFull.slot)
+        .BlindedBeaconBlock.hashTreeRoot(blindedOrFull)
+    : // Full
+      config
+        .getForkTypes(blindedOrFull.slot)
+        .BeaconBlock.hashTreeRoot(blindedOrFull);
+}
+
+export function blindedOrFullBlockToHeader(
+  config: ChainForkConfig,
+  blindedOrFull: BeaconBlock | BlindedBeaconBlock
+): BeaconBlockHeader {
+  const bodyRoot = isBlindedBeaconBlock(blindedOrFull)
+    ? // Blinded
+      config
+        .getPostBellatrixForkTypes(blindedOrFull.slot)
+        .BlindedBeaconBlockBody.hashTreeRoot(blindedOrFull.body)
+    : // Full
+      config
+        .getForkTypes(blindedOrFull.slot)
+        .BeaconBlockBody.hashTreeRoot(blindedOrFull.body);
+
+  return {
+    slot: blindedOrFull.slot,
+    proposerIndex: blindedOrFull.proposerIndex,
+    parentRoot: blindedOrFull.parentRoot,
+    stateRoot: blindedOrFull.stateRoot,
+    bodyRoot,
+  };
+}
+
+export function beaconBlockToBlinded(
+  config: ChainForkConfig,
+  block: BeaconBlock<ForkPostBellatrix>
+): BlindedBeaconBlock {
+  const fork = config.getForkName(block.slot);
+  const executionPayloadHeader = executionPayloadToPayloadHeader(ForkSeq[fork], block.body.executionPayload);
+  const blindedBlock: BlindedBeaconBlock = {...block, body: {...block.body, executionPayloadHeader}};
+  return blindedBlock;
+}
+
+export function signedBeaconBlockToBlinded(
+  config: ChainForkConfig,
+  signedBlock: SignedBeaconBlock<ForkPostBellatrix>
+): SignedBlindedBeaconBlock {
+  return {
+    message: beaconBlockToBlinded(config, signedBlock.message),
+    signature: signedBlock.signature,
+  };
+}
+
+export function signedBlindedBlockToFull(
+  fork: ForkName,
+  signedBlindedBlock: SignedBlindedBeaconBlock,
+  executionPayload: ExecutionPayload | null
+): SignedBeaconBlock {
+  if (isForkPostBellatrix(fork) && executionPayload === null) {
+    throw Error("Missing executionPayload to reconstruct post-bellatrix full block");
+  }
+
+  const signedBlock = {
+    ...signedBlindedBlock,
+    message: {
+      ...signedBlindedBlock.message,
+      body: {
+        ...signedBlindedBlock.message.body,
+        // state transition doesn't handle null value for executionPayload in pre-bellatrix blocks
+        executionPayload: executionPayload ?? undefined,
+      },
+    },
+  } as SignedBeaconBlock;
+
+  // state transition can't seem to handle executionPayloadHeader presense in merge block
+  // so just delete the extra field we don't require
+  delete (signedBlock.message.body as {executionPayloadHeader?: ExecutionPayloadHeader}).executionPayloadHeader;
+  return signedBlock;
+}
+
+export function parseExecutionPayloadAndBlobsBundle(data: ExecutionPayload | ExecutionPayloadAndBlobsBundle): {
+  executionPayload: ExecutionPayload;
+  blobsBundle: BlobsBundle | null;
+} {
+  if (isExecutionPayloadAndBlobsBundle(data)) {
+    return data;
+  }
+  return {
+    executionPayload: data,
+    blobsBundle: null,
+  };
+}
+
+export function reconstructSignedBlockContents(
+  fork: ForkName,
+  signedBlindedBlock: SignedBlindedBeaconBlock,
+  executionPayload: ExecutionPayload | null,
+  blobsBundle: BlobsBundle | null
+): SignedBlockContents {
+  const signedBlock = signedBlindedBlockToFull(fork, signedBlindedBlock, executionPayload);
+
+  if (isForkPostDeneb(fork)) {
+    if (blobsBundle === null) {
+      throw Error("Missing blobs bundle to reconstruct post-deneb block contents");
+    }
+    return {
+      signedBlock: signedBlock as SignedBeaconBlock<ForkPostDeneb>,
+      kzgProofs: blobsBundle.proofs,
+      blobs: blobsBundle.blobs,
+    };
+  }
+  return {signedBlock};
+}

package/src/util/blockRoot.ts

@@ -0,0 +1,72 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {SLOTS_PER_HISTORICAL_ROOT} from "@lodestar/params";
+import {
+  BeaconBlock,
+  BeaconBlockHeader,
+  Epoch,
+  Root,
+  SignedBeaconBlock,
+  SignedBeaconBlockHeader,
+  Slot,
+} from "@lodestar/types";
+import {ZERO_HASH} from "../constants/index.js";
+import {BeaconStateAllForks} from "../types.js";
+import {computeStartSlotAtEpoch} from "./epoch.js";
+
+/**
+ * Return the block root at a recent [[slot]].
+ */
+export function getBlockRootAtSlot(state: BeaconStateAllForks, slot: Slot): Root {
+  if (slot >= state.slot) {
+    throw Error(`Can only get block root in the past currentSlot=${state.slot} slot=${slot}`);
+  }
+  if (slot < state.slot - SLOTS_PER_HISTORICAL_ROOT) {
+    throw Error(`Cannot get block root more than ${SLOTS_PER_HISTORICAL_ROOT} in the past`);
+  }
+  return state.blockRoots.get(slot % SLOTS_PER_HISTORICAL_ROOT);
+}
+
+/**
+ * Return the block root at the start of a recent [[epoch]].
+ */
+export function getBlockRoot(state: BeaconStateAllForks, epoch: Epoch): Root {
+  return getBlockRootAtSlot(state, computeStartSlotAtEpoch(epoch));
+}
+/**
+ * Return the block header corresponding to a block with ``state_root`` set to ``ZERO_HASH``.
+ */
+export function getTemporaryBlockHeader(config: ChainForkConfig, block: BeaconBlock): BeaconBlockHeader {
+  return {
+    slot: block.slot,
+    proposerIndex: block.proposerIndex,
+    parentRoot: block.parentRoot,
+    // `state_root` is zeroed and overwritten in the next `process_slot` call
+    stateRoot: ZERO_HASH,
+    bodyRoot: config.getForkTypes(block.slot).BeaconBlockBody.hashTreeRoot(block.body),
+  };
+}
+
+/**
+ * Receives a BeaconBlock, and produces the corresponding BeaconBlockHeader.
+ */
+export function blockToHeader(config: ChainForkConfig, block: BeaconBlock): BeaconBlockHeader {
+  return {
+    stateRoot: block.stateRoot,
+    proposerIndex: block.proposerIndex,
+    slot: block.slot,
+    parentRoot: block.parentRoot,
+    bodyRoot: config.getForkTypes(block.slot).BeaconBlockBody.hashTreeRoot(block.body),
+  };
+}
+
+export function signedBlockToSignedHeader(
+  config: ChainForkConfig,
+  signedBlock: SignedBeaconBlock
+): SignedBeaconBlockHeader {
+  const message = blockToHeader(config, signedBlock.message);
+  const signature = signedBlock.signature;
+  return {
+    message,
+    signature,
+  };
+}

package/src/util/calculateCommitteeAssignments.ts

@@ -0,0 +1,43 @@
+import {SLOTS_PER_EPOCH} from "@lodestar/params";
+import {CommitteeIndex, Slot, ValidatorIndex} from "@lodestar/types";
+import {EpochShuffling} from "./epochShuffling.js";
+
+// Copied from lodestar-api package to avoid depending on the package
+export interface AttesterDuty {
+  validatorIndex: ValidatorIndex;
+  committeeIndex: CommitteeIndex;
+  committeeLength: number;
+  committeesAtSlot: number;
+  validatorCommitteeIndex: number;
+  slot: Slot;
+}
+
+export function calculateCommitteeAssignments(
+  epochShuffling: EpochShuffling,
+  requestedValidatorIndices: ValidatorIndex[]
+): Map<ValidatorIndex, AttesterDuty> {
+  const requestedValidatorIndicesSet = new Set(requestedValidatorIndices);
+  const duties = new Map<ValidatorIndex, AttesterDuty>();
+
+  const epochCommittees = epochShuffling.committees;
+  for (let epochSlot = 0; epochSlot < SLOTS_PER_EPOCH; epochSlot++) {
+    const slotCommittees = epochCommittees[epochSlot];
+    for (let i = 0, committeesAtSlot = slotCommittees.length; i < committeesAtSlot; i++) {
+      for (let j = 0, committeeLength = slotCommittees[i].length; j < committeeLength; j++) {
+        const validatorIndex = slotCommittees[i][j];
+        if (requestedValidatorIndicesSet.has(validatorIndex)) {
+          duties.set(validatorIndex, {
+            validatorIndex,
+            committeeLength,
+            committeesAtSlot,
+            validatorCommitteeIndex: j,
+            committeeIndex: i,
+            slot: epochShuffling.epoch * SLOTS_PER_EPOCH + epochSlot,
+          });
+        }
+      }
+    }
+  }
+
+  return duties;
+}

package/src/util/capella.ts

@@ -0,0 +1,8 @@
+import {ETH1_ADDRESS_WITHDRAWAL_PREFIX} from "@lodestar/params";
+
+/**
+ * https://github.com/ethereum/consensus-specs/blob/3d235740e5f1e641d3b160c8688f26e7dc5a1894/specs/capella/beacon-chain.md#has_eth1_withdrawal_credential
+ */
+export function hasEth1WithdrawalCredential(withdrawalCredentials: Uint8Array): boolean {
+  return withdrawalCredentials[0] === ETH1_ADDRESS_WITHDRAWAL_PREFIX;
+}

package/src/util/computeAnchorCheckpoint.ts

@@ -0,0 +1,38 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {GENESIS_SLOT, ZERO_HASH} from "@lodestar/params";
+import {phase0, ssz} from "@lodestar/types";
+import {BeaconStateAllForks} from "../types.js";
+import {blockToHeader} from "./blockRoot.js";
+import {computeCheckpointEpochAtStateSlot} from "./epoch.js";
+
+export function computeAnchorCheckpoint(
+  config: ChainForkConfig,
+  anchorState: BeaconStateAllForks
+): {checkpoint: phase0.Checkpoint; blockHeader: phase0.BeaconBlockHeader} {
+  let blockHeader: phase0.BeaconBlockHeader;
+  let root: Uint8Array;
+  const blockTypes = config.getForkTypes(anchorState.latestBlockHeader.slot);
+
+  if (anchorState.latestBlockHeader.slot === GENESIS_SLOT) {
+    const block = blockTypes.BeaconBlock.defaultValue();
+    block.stateRoot = anchorState.hashTreeRoot();
+    blockHeader = blockToHeader(config, block);
+    root = ssz.phase0.BeaconBlockHeader.hashTreeRoot(blockHeader);
+  } else {
+    blockHeader = ssz.phase0.BeaconBlockHeader.clone(anchorState.latestBlockHeader);
+    if (ssz.Root.equals(blockHeader.stateRoot, ZERO_HASH)) {
+      blockHeader.stateRoot = anchorState.hashTreeRoot();
+    }
+    root = ssz.phase0.BeaconBlockHeader.hashTreeRoot(blockHeader);
+  }
+
+  return {
+    checkpoint: {
+      root,
+      // the checkpoint epoch = computeEpochAtSlot(anchorState.slot) + 1 if slot is not at epoch boundary
+      // this is similar to a process_slots() call
+      epoch: computeCheckpointEpochAtStateSlot(anchorState.slot),
+    },
+    blockHeader,
+  };
+}

package/src/util/deposit.ts

@@ -0,0 +1,22 @@
+import {ForkSeq, MAX_DEPOSITS} from "@lodestar/params";
+import {UintNum64, phase0} from "@lodestar/types";
+import {CachedBeaconStateAllForks, CachedBeaconStateElectra} from "../types.js";
+
+export function getEth1DepositCount(state: CachedBeaconStateAllForks, eth1Data?: phase0.Eth1Data): UintNum64 {
+  const eth1DataToUse = eth1Data ?? state.eth1Data;
+  if (state.config.getForkSeq(state.slot) >= ForkSeq.electra) {
+    const electraState = state as CachedBeaconStateElectra;
+    // eth1DataIndexLimit = min(UintNum64, UintBn64) can be safely casted as UintNum64
+    // since the result lies within upper and lower bound of UintNum64
+    const eth1DataIndexLimit: UintNum64 =
+      eth1DataToUse.depositCount < electraState.depositRequestsStartIndex
+        ? eth1DataToUse.depositCount
+        : Number(electraState.depositRequestsStartIndex);
+
+    if (state.eth1DepositIndex < eth1DataIndexLimit) {
+      return Math.min(MAX_DEPOSITS, eth1DataIndexLimit - state.eth1DepositIndex);
+    }
+    return 0;
+  }
+  return Math.min(MAX_DEPOSITS, eth1DataToUse.depositCount - state.eth1DepositIndex);
+}

package/src/util/domain.ts

@@ -0,0 +1,31 @@
+import {DomainType, Epoch, Root, Version, phase0, ssz} from "@lodestar/types";
+
+// Only used by processDeposit +  lightclient
+/**
+ * Return the domain for the [[domainType]] and [[forkVersion]].
+ */
+export function computeDomain(domainType: DomainType, forkVersion: Version, genesisValidatorRoot: Root): Uint8Array {
+  const forkDataRoot = computeForkDataRoot(forkVersion, genesisValidatorRoot);
+  const domain = new Uint8Array(32);
+  domain.set(domainType, 0);
+  domain.set(forkDataRoot.slice(0, 28), 4);
+  return domain;
+}
+
+/**
+ * Return the ForkVersion at an epoch from a Fork type
+ */
+export function getForkVersion(fork: phase0.Fork, epoch: Epoch): Version {
+  return epoch < fork.epoch ? fork.previousVersion : fork.currentVersion;
+}
+
+/**
+ * Used primarily in signature domains to avoid collisions across forks/chains.
+ */
+export function computeForkDataRoot(currentVersion: Version, genesisValidatorsRoot: Root): Uint8Array {
+  const forkData: phase0.ForkData = {
+    currentVersion,
+    genesisValidatorsRoot,
+  };
+  return ssz.phase0.ForkData.hashTreeRoot(forkData);
+}

package/src/util/electra.ts

@@ -0,0 +1,68 @@
+import {COMPOUNDING_WITHDRAWAL_PREFIX, GENESIS_SLOT, MIN_ACTIVATION_BALANCE} from "@lodestar/params";
+import {ValidatorIndex, ssz} from "@lodestar/types";
+import {G2_POINT_AT_INFINITY} from "../constants/constants.js";
+import {CachedBeaconStateElectra} from "../types.js";
+import {hasEth1WithdrawalCredential} from "./capella.js";
+
+export function hasCompoundingWithdrawalCredential(withdrawalCredentials: Uint8Array): boolean {
+  return withdrawalCredentials[0] === COMPOUNDING_WITHDRAWAL_PREFIX;
+}
+
+export function hasExecutionWithdrawalCredential(withdrawalCredentials: Uint8Array): boolean {
+  return (
+    hasCompoundingWithdrawalCredential(withdrawalCredentials) || hasEth1WithdrawalCredential(withdrawalCredentials)
+  );
+}
+
+export function switchToCompoundingValidator(state: CachedBeaconStateElectra, index: ValidatorIndex): void {
+  const validator = state.validators.get(index);
+
+  // directly modifying the byte leads to ssz missing the modification resulting into
+  // wrong root compute, although slicing can be avoided but anyway this is not going
+  // to be a hot path so its better to clean slice and avoid side effects
+  const newWithdrawalCredentials = Uint8Array.prototype.slice.call(
+    validator.withdrawalCredentials,
+    0,
+    validator.withdrawalCredentials.length
+  );
+  newWithdrawalCredentials[0] = COMPOUNDING_WITHDRAWAL_PREFIX;
+  validator.withdrawalCredentials = newWithdrawalCredentials;
+  queueExcessActiveBalance(state, index);
+}
+
+export function queueExcessActiveBalance(state: CachedBeaconStateElectra, index: ValidatorIndex): void {
+  const balance = state.balances.get(index);
+  if (balance > MIN_ACTIVATION_BALANCE) {
+    const validator = state.validators.getReadonly(index);
+    const excessBalance = balance - MIN_ACTIVATION_BALANCE;
+    state.balances.set(index, MIN_ACTIVATION_BALANCE);
+
+    const pendingDeposit = ssz.electra.PendingDeposit.toViewDU({
+      pubkey: validator.pubkey,
+      withdrawalCredentials: validator.withdrawalCredentials,
+      amount: excessBalance,
+      // Use bls.G2_POINT_AT_INFINITY as a signature field placeholder
+      signature: G2_POINT_AT_INFINITY,
+      // Use GENESIS_SLOT to distinguish from a pending deposit request
+      slot: GENESIS_SLOT,
+    });
+    state.pendingDeposits.push(pendingDeposit);
+  }
+}
+
+/**
+ * Since we share pubkey2index, pubkey maybe added by other epoch transition but we don't have that validator in this state
+ */
+export function isPubkeyKnown(state: CachedBeaconStateElectra, pubkey: Uint8Array): boolean {
+  return isValidatorKnown(state, state.epochCtx.getValidatorIndex(pubkey));
+}
+
+/**
+ * Since we share pubkey2index, validatorIndex maybe not null but we don't have that validator in this state
+ */
+export function isValidatorKnown(
+  state: CachedBeaconStateElectra,
+  index: ValidatorIndex | null
+): index is ValidatorIndex {
+  return index !== null && index < state.validators.length;
+}

package/src/util/epoch.ts

@@ -0,0 +1,135 @@
+import {EPOCHS_PER_SYNC_COMMITTEE_PERIOD, GENESIS_EPOCH, MAX_SEED_LOOKAHEAD, SLOTS_PER_EPOCH} from "@lodestar/params";
+import {BeaconState, Epoch, Gwei, Slot, SyncPeriod} from "@lodestar/types";
+import {CachedBeaconStateElectra} from "../types.js";
+import {getActivationExitChurnLimit, getConsolidationChurnLimit} from "./validator.js";
+
+/**
+ * Return the epoch number at the given slot.
+ */
+export function computeEpochAtSlot(slot: Slot): Epoch {
+  return Math.floor(slot / SLOTS_PER_EPOCH);
+}
+
+/**
+ * Return the epoch at the state slot for purposes of checkpoint.
+ * Ideally this slot % SLOTS_PER_EPOCH === 0, but just to handle the improbable case of
+ * non boundary slot, using ceil so that the state's latestBlockHeader would always
+ * lie before this epooch
+ */
+export function computeCheckpointEpochAtStateSlot(slot: Slot): Epoch {
+  return Math.ceil(slot / SLOTS_PER_EPOCH);
+}
+
+/**
+ * Return the starting slot of the given epoch.
+ */
+export function computeStartSlotAtEpoch(epoch: Epoch): Slot {
+  return epoch * SLOTS_PER_EPOCH;
+}
+
+/**
+ * Return the end slot of the given epoch.
+ */
+export function computeEndSlotAtEpoch(epoch: Epoch): Slot {
+  return computeStartSlotAtEpoch(epoch + 1) - 1;
+}
+
+/**
+ * Return the epoch at which an activation or exit triggered in ``epoch`` takes effect.
+ */
+export function computeActivationExitEpoch(epoch: Epoch): Epoch {
+  return epoch + 1 + MAX_SEED_LOOKAHEAD;
+}
+
+export function computeExitEpochAndUpdateChurn(state: CachedBeaconStateElectra, exitBalance: Gwei): number {
+  let earliestExitEpoch = Math.max(state.earliestExitEpoch, computeActivationExitEpoch(state.epochCtx.epoch));
+  const perEpochChurn = getActivationExitChurnLimit(state.epochCtx);
+
+  // New epoch for exits.
+  let exitBalanceToConsume =
+    state.earliestExitEpoch < earliestExitEpoch ? perEpochChurn : Number(state.exitBalanceToConsume);
+
+  // Exit doesn't fit in the current earliest epoch.
+  if (exitBalance > exitBalanceToConsume) {
+    const balanceToProcess = Number(exitBalance) - exitBalanceToConsume;
+    const additionalEpochs = Math.floor((balanceToProcess - 1) / perEpochChurn) + 1;
+    earliestExitEpoch += additionalEpochs;
+    exitBalanceToConsume += additionalEpochs * perEpochChurn;
+  }
+
+  // Consume the balance and update state variables.
+  state.exitBalanceToConsume = BigInt(exitBalanceToConsume) - exitBalance;
+  state.earliestExitEpoch = earliestExitEpoch;
+
+  return state.earliestExitEpoch;
+}
+
+export function computeConsolidationEpochAndUpdateChurn(
+  state: CachedBeaconStateElectra,
+  consolidationBalance: Gwei
+): number {
+  let earliestConsolidationEpoch = Math.max(
+    state.earliestConsolidationEpoch,
+    computeActivationExitEpoch(state.epochCtx.epoch)
+  );
+  const perEpochConsolidationChurn = getConsolidationChurnLimit(state.epochCtx);
+
+  // New epoch for consolidations
+  let consolidationBalanceToConsume =
+    state.earliestConsolidationEpoch < earliestConsolidationEpoch
+      ? perEpochConsolidationChurn
+      : Number(state.consolidationBalanceToConsume);
+
+  // Consolidation doesn't fit in the current earliest epoch.
+  if (consolidationBalance > consolidationBalanceToConsume) {
+    const balanceToProcess = Number(consolidationBalance) - consolidationBalanceToConsume;
+    const additionalEpochs = Math.floor((balanceToProcess - 1) / perEpochConsolidationChurn) + 1;
+    earliestConsolidationEpoch += additionalEpochs;
+    consolidationBalanceToConsume += additionalEpochs * perEpochConsolidationChurn;
+  }
+
+  // Consume the balance and update state variables.
+  state.consolidationBalanceToConsume = BigInt(consolidationBalanceToConsume) - consolidationBalance;
+  state.earliestConsolidationEpoch = earliestConsolidationEpoch;
+
+  return state.earliestConsolidationEpoch;
+}
+
+/**
+ * Return the current epoch of the given state.
+ */
+export function getCurrentEpoch(state: Pick<BeaconState, "slot">): Epoch {
+  return computeEpochAtSlot(state.slot);
+}
+
+/**
+ * Return the previous epoch of the given state.
+ */
+export function getPreviousEpoch(state: Pick<BeaconState, "slot">): Epoch {
+  const currentEpoch = getCurrentEpoch(state);
+  if (currentEpoch === GENESIS_EPOCH) {
+    return GENESIS_EPOCH;
+  }
+  return currentEpoch - 1;
+}
+
+/**
+ * Return the sync committee period at slot
+ */
+export function computeSyncPeriodAtSlot(slot: Slot): SyncPeriod {
+  return computeSyncPeriodAtEpoch(computeEpochAtSlot(slot));
+}
+
+/**
+ * Return the sync committee period at epoch
+ */
+export function computeSyncPeriodAtEpoch(epoch: Epoch): SyncPeriod {
+  return Math.floor(epoch / EPOCHS_PER_SYNC_COMMITTEE_PERIOD);
+}
+
+/**
+ * Determine if the given slot is start slot of an epoch
+ */
+export function isStartSlotOfEpoch(slot: Slot): boolean {
+  return slot % SLOTS_PER_EPOCH === 0;
+}