@lodestar/state-transition 1.43.0-dev.4fb05c546d → 1.43.0-dev.4fe6b362c9

package/src/block/index.ts

@@ -14,8 +14,8 @@ import {processBlockHeader} from "./processBlockHeader.js";
 import {processEth1Data} from "./processEth1Data.js";
 import {processExecutionPayload} from "./processExecutionPayload.js";
 import {processExecutionPayloadBid} from "./processExecutionPayloadBid.js";
-import {processExecutionPayloadEnvelope} from "./processExecutionPayloadEnvelope.js";
 import {processOperations} from "./processOperations.js";
+import {processParentExecutionPayload} from "./processParentExecutionPayload.js";
 import {processPayloadAttestation} from "./processPayloadAttestation.js";
 import {processRandao} from "./processRandao.js";
 import {processSyncAggregate} from "./processSyncCommittee.js";
@@ -32,7 +32,7 @@ export {
   processWithdrawals,
   processExecutionPayloadBid,
   processPayloadAttestation,
-  processExecutionPayloadEnvelope,
+  processParentExecutionPayload,
 };
 
 export * from "./externalData.js";
@@ -51,10 +51,16 @@ export function processBlock(
 ): void {
   const {verifySignatures = true} = opts ?? {};
 
+  // Apply the parent's deferred payload effects before everything else. Must run before
+  // processBlockHeader and processExecutionPayloadBid so subsequent steps see the updated state.
+  if (fork >= ForkSeq.gloas) {
+    processParentExecutionPayload(state as CachedBeaconStateGloas, block as BeaconBlock<ForkPostGloas>);
+  }
+
   processBlockHeader(state, block);
 
   if (fork >= ForkSeq.gloas) {
-    // After gloas, processWithdrawals does not take a payload parameter
+    // Parent payload's execution requests were already applied by processParentExecutionPayload above
     processWithdrawals(fork, state as CachedBeaconStateGloas);
   } else if (fork >= ForkSeq.capella) {
     const fullOrBlindedPayload = getFullOrBlindedPayload(block);
@@ -67,7 +73,9 @@ export function processBlock(
 
   // The call to the process_execution_payload must happen before the call to the process_randao as the former depends
   // on the randao_mix computed with the reveal of the previous block.
-  // TODO GLOAS: We call processExecutionPayload somewhere else post-gloas
+  // Post-gloas: process_execution_payload is not part of block processing. The parent's payload
+  // effects are applied earlier via processParentExecutionPayload, and each execution payload is
+  // verified out-of-band via verifyExecutionPayloadEnvelope when it arrives.
   if (
     fork < ForkSeq.gloas &&
     fork >= ForkSeq.bellatrix &&

package/src/block/processConsolidationRequest.ts

@@ -46,7 +46,8 @@ export function processConsolidationRequest(
   }
 
   // If there is too little available consolidation churn limit, consolidation requests are ignored
-  if (getConsolidationChurnLimit(state.epochCtx) <= MIN_ACTIVATION_BALANCE) {
+  const fork = state.config.getForkSeq(state.slot);
+  if (getConsolidationChurnLimit(fork, state.epochCtx) <= MIN_ACTIVATION_BALANCE) {
     return;
   }
 

package/src/block/processDepositRequest.ts

@@ -1,10 +1,10 @@
-import {BeaconConfig} from "@lodestar/config";
 import {FAR_FUTURE_EPOCH, ForkSeq, UNSET_DEPOSIT_REQUESTS_START_INDEX} from "@lodestar/params";
-import {BLSPubkey, Bytes32, PubkeyHex, UintNum64, electra, ssz} from "@lodestar/types";
+import {BLSPubkey, Bytes32, UintNum64, electra, ssz} from "@lodestar/types";
 import {toPubkeyHex} from "@lodestar/utils";
 import {CachedBeaconStateElectra, CachedBeaconStateGloas} from "../types.js";
 import {findBuilderIndexByPubkey, isBuilderWithdrawalCredential} from "../util/gloas.js";
 import {computeEpochAtSlot, isValidatorKnown} from "../util/index.js";
+import {PendingDepositsLookup} from "../util/pendingDepositsLookup.js";
 import {isValidDepositSignature} from "./processDeposit.js";
 
 /**
@@ -76,53 +76,60 @@ function addBuilderToRegistry(
   }
 }
 
-// TODO GLOAS: pendingValidatorPubkeys cache is currently naive and has room for improvement.
-// Currently the cache lives in process_block, but we should put it in epochCache or elsewhere that has longer
-// lifetime to avoid duplicated deposit signature computation
+// TODO GLOAS: the PendingDepositsLookup is currently scoped to a single envelope of
+// deposit-requests. We can track it as ephemeral within EpochCache and transfer to the next block
+// transition to reuse cached signature verifications.
 // See https://github.com/ChainSafe/lodestar/issues/9181
 export function processDepositRequest(
   fork: ForkSeq,
   state: CachedBeaconStateElectra | CachedBeaconStateGloas,
   depositRequest: electra.DepositRequest,
-  pendingValidatorPubkeysCache?: Set<PubkeyHex>
+  pendingDepositsLookup?: PendingDepositsLookup
 ): void {
   const {pubkey, withdrawalCredentials, amount, signature} = depositRequest;
 
-  // Check if this is a builder or validator deposit
   if (fork >= ForkSeq.gloas) {
     const stateGloas = state as CachedBeaconStateGloas;
-    const pendingValidatorPubkeys =
-      pendingValidatorPubkeysCache ?? getPendingValidatorPubkeys(state.config, stateGloas);
+    const lookup = pendingDepositsLookup ?? PendingDepositsLookup.build(stateGloas);
     const pubkeyHex = toPubkeyHex(pubkey);
     const builderIndex = findBuilderIndexByPubkey(stateGloas, pubkey);
     const validatorIndex = state.epochCtx.getValidatorIndex(pubkey);
 
-    // Regardless of the withdrawal credentials prefix, if a builder/validator
-    // already exists with this pubkey, apply the deposit to their balance
     const isBuilder = builderIndex !== null;
     const isValidator = isValidatorKnown(state, validatorIndex);
-    const isPendingValidator = pendingValidatorPubkeys.has(pubkeyHex);
 
-    if (isBuilder || (isBuilderWithdrawalCredential(withdrawalCredentials) && !isValidator && !isPendingValidator)) {
-      // Apply builder deposits immediately
+    if (isBuilder) {
+      // Top up an existing builder regardless of withdrawal credential prefix
       applyDepositForBuilder(stateGloas, pubkey, withdrawalCredentials, amount, signature, state.slot);
       return;
     }
 
-    // Keep the shared cache in sync: if this deposit has a valid signature, subsequent
-    // deposit requests for the same pubkey in this envelope must see it as a pending validator
+    // Only check the (expensive) "pending validator" condition when needed
     if (
-      pendingValidatorPubkeysCache &&
+      isBuilderWithdrawalCredential(withdrawalCredentials) &&
       !isValidator &&
-      !isPendingValidator &&
-      isValidDepositSignature(state.config, pubkey, withdrawalCredentials, amount, signature)
+      !lookup.hasPendingValidator(state.config, pubkeyHex)
     ) {
-      pendingValidatorPubkeys.add(pubkeyHex);
+      applyDepositForBuilder(stateGloas, pubkey, withdrawalCredentials, amount, signature, state.slot);
+      return;
     }
+
+    const pendingDeposit = ssz.electra.PendingDeposit.toViewDU({
+      pubkey,
+      withdrawalCredentials,
+      amount,
+      signature,
+      slot: state.slot,
+    });
+    // Keep the lookup in sync with state.pendingDeposits so later deposit-requests
+    // in the same envelope see this deposit
+    lookup.add(pendingDeposit, pubkeyHex);
+    state.pendingDeposits.push(pendingDeposit);
+    return;
   }
 
-  // Only set deposit_requests_start_index in Electra fork, not Gloas
-  if (fork < ForkSeq.gloas && state.depositRequestsStartIndex === UNSET_DEPOSIT_REQUESTS_START_INDEX) {
+  // Pre-Gloas (Electra) path
+  if (state.depositRequestsStartIndex === UNSET_DEPOSIT_REQUESTS_START_INDEX) {
     state.depositRequestsStartIndex = depositRequest.index;
   }
 
@@ -136,28 +143,3 @@ export function processDepositRequest(
   });
   state.pendingDeposits.push(pendingDeposit);
 }
-
-/**
- * Build a set of pubkeys (hex-encoded) from pending deposits that have valid signatures.
- * This is computed once and passed to each processDepositRequest call to avoid
- * repeatedly iterating state.pendingDeposits.
- *
- * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.3/specs/gloas/beacon-chain.md#new-is_pending_validator
- */
-export function getPendingValidatorPubkeys(config: BeaconConfig, state: CachedBeaconStateGloas): Set<PubkeyHex> {
-  const result = new Set<PubkeyHex>();
-  for (const pendingDeposit of state.pendingDeposits.getAllReadonly()) {
-    if (
-      isValidDepositSignature(
-        config,
-        pendingDeposit.pubkey,
-        pendingDeposit.withdrawalCredentials,
-        pendingDeposit.amount,
-        pendingDeposit.signature
-      )
-    ) {
-      result.add(toPubkeyHex(pendingDeposit.pubkey));
-    }
-  }
-  return result;
-}

package/src/block/processParentExecutionPayload.ts

@@ -0,0 +1,117 @@
+import {ForkPostGloas, SLOTS_PER_EPOCH, SLOTS_PER_HISTORICAL_ROOT} from "@lodestar/params";
+import {BeaconBlock, electra, ssz} from "@lodestar/types";
+import {byteArrayEquals, toRootHex} from "@lodestar/utils";
+import {CachedBeaconStateGloas} from "../types.js";
+import {computeEpochAtSlot} from "../util/epoch.js";
+import {PendingDepositsLookup} from "../util/pendingDepositsLookup.js";
+import {processConsolidationRequest} from "./processConsolidationRequest.js";
+import {processDepositRequest} from "./processDepositRequest.js";
+import {processWithdrawalRequest} from "./processWithdrawalRequest.js";
+
+/**
+ * Process parent execution payload effects as the first step of processBlock.
+ *
+ * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.6/specs/gloas/beacon-chain.md#new-process_parent_execution_payload
+ */
+export function processParentExecutionPayload(state: CachedBeaconStateGloas, block: BeaconBlock<ForkPostGloas>): void {
+  const bid = block.body.signedExecutionPayloadBid.message;
+  const parentBid = state.latestExecutionPayloadBid;
+  const requests = block.body.parentExecutionRequests;
+
+  const isParentBlockFull = byteArrayEquals(bid.parentBlockHash, parentBid.blockHash);
+  if (!isParentBlockFull) {
+    // Parent was EMPTY -- no execution requests expected
+    assertEmptyExecutionRequests(requests);
+    return;
+  }
+
+  // Parent was FULL -- verify the bid commitment and apply the payload
+  const requestsRoot = ssz.electra.ExecutionRequests.hashTreeRoot(requests);
+  if (!byteArrayEquals(requestsRoot, parentBid.executionRequestsRoot)) {
+    throw new Error(
+      `Parent execution requests root mismatch actual=${toRootHex(requestsRoot)} expected=${toRootHex(parentBid.executionRequestsRoot)}`
+    );
+  }
+
+  applyParentExecutionPayload(state, requests);
+}
+
+/**
+ * Process the parent's execution requests, queue the builder payment, update payload availability,
+ * and update the latest block hash.
+ *
+ * Called from processParentExecutionPayload during block processing, and from the validator during
+ * block production before computing withdrawals.
+ *
+ * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.6/specs/gloas/beacon-chain.md#new-apply_parent_execution_payload
+ */
+export function applyParentExecutionPayload(state: CachedBeaconStateGloas, requests: electra.ExecutionRequests): void {
+  const fork = state.config.getForkSeq(state.slot);
+  const parentBid = state.latestExecutionPayloadBid;
+  const parentSlot = parentBid.slot;
+  const parentEpoch = computeEpochAtSlot(parentSlot);
+  const currentEpoch = computeEpochAtSlot(state.slot);
+
+  // Process execution requests from parent's payload. The execution
+  // requests are processed at state.slot (child's slot), not the parent's slot.
+  if (requests.deposits.length > 0) {
+    const pendingDepositsLookup = PendingDepositsLookup.build(state);
+    for (const deposit of requests.deposits) {
+      processDepositRequest(fork, state, deposit, pendingDepositsLookup);
+    }
+  }
+
+  for (const withdrawal of requests.withdrawals) {
+    processWithdrawalRequest(fork, state, withdrawal);
+  }
+
+  for (const consolidation of requests.consolidations) {
+    processConsolidationRequest(state, consolidation);
+  }
+
+  // Settle the builder payment
+  if (parentEpoch === currentEpoch) {
+    settleBuilderPayment(state, SLOTS_PER_EPOCH + (parentSlot % SLOTS_PER_EPOCH));
+  } else if (parentEpoch === currentEpoch - 1) {
+    settleBuilderPayment(state, parentSlot % SLOTS_PER_EPOCH);
+  } else if (parentBid.value > 0) {
+    // Parent is older than the previous epoch, its payment entry has been evicted from
+    // builder_pending_payments. Append the withdrawal directly.
+    state.builderPendingWithdrawals.push(
+      ssz.gloas.BuilderPendingWithdrawal.toViewDU({
+        feeRecipient: parentBid.feeRecipient,
+        amount: parentBid.value,
+        builderIndex: parentBid.builderIndex,
+      })
+    );
+  }
+
+  // Update parent payload availability and latest block hash
+  state.executionPayloadAvailability.set(parentSlot % SLOTS_PER_HISTORICAL_ROOT, true);
+  state.latestBlockHash = parentBid.blockHash;
+}
+
+/**
+ * Settle a builder payment at the given index: move its withdrawal (if any) to the
+ * pending withdrawals list and clear the payment slot.
+ *
+ * Spec: https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.6/specs/gloas/beacon-chain.md#new-settle_builder_payment
+ */
+function settleBuilderPayment(state: CachedBeaconStateGloas, paymentIndex: number): void {
+  if (paymentIndex >= state.builderPendingPayments.length) {
+    throw new Error(
+      `Invalid builder payment index paymentIndex=${paymentIndex} limit=${state.builderPendingPayments.length}`
+    );
+  }
+  const payment = state.builderPendingPayments.get(paymentIndex).clone();
+  if (payment.withdrawal.amount > 0) {
+    state.builderPendingWithdrawals.push(payment.withdrawal);
+  }
+  state.builderPendingPayments.set(paymentIndex, ssz.gloas.BuilderPendingPayment.defaultViewDU());
+}
+
+function assertEmptyExecutionRequests(requests: electra.ExecutionRequests): void {
+  if (requests.deposits.length !== 0 || requests.withdrawals.length !== 0 || requests.consolidations.length !== 0) {
+    throw new Error("Parent execution requests must be empty when parent block is EMPTY");
+  }
+}

package/src/block/processWithdrawals.ts

@@ -15,7 +15,6 @@ import {
   convertBuilderIndexToValidatorIndex,
   convertValidatorIndexToBuilderIndex,
   isBuilderIndex,
-  isParentBlockFull,
 } from "../util/gloas.js";
 import {
   decreaseBalance,
@@ -32,8 +31,15 @@ export function processWithdrawals(
   payload?: capella.FullOrBlindedExecutionPayload
 ): void {
   // Return early if the parent block is empty
-  if (fork >= ForkSeq.gloas && !isParentBlockFull(state as CachedBeaconStateGloas)) {
-    return;
+  if (fork >= ForkSeq.gloas) {
+    const stateGloas = state as CachedBeaconStateGloas;
+    const isParentBlockEmpty = !byteArrayEquals(
+      stateGloas.latestBlockHash,
+      stateGloas.latestExecutionPayloadBid.blockHash
+    );
+    if (isParentBlockEmpty) {
+      return;
+    }
   }
 
   // processedBuilderWithdrawalsCount is withdrawals coming from builder payment since gloas (EIP-7732)
@@ -48,7 +54,9 @@ export function processWithdrawals(
   } = getExpectedWithdrawals(fork, state);
   const numWithdrawals = expectedWithdrawals.length;
 
-  // After gloas, withdrawals are verified later in processExecutionPayloadEnvelope
+  // Pre-gloas verifies the payload's withdrawals against expectedWithdrawals here.
+  // Post-gloas, the payload arrives later as an envelope and that consistency check
+  // happens in verifyExecutionPayloadEnvelope against state.payloadExpectedWithdrawals.
   if (fork < ForkSeq.gloas) {
     if (payload === undefined) {
       throw Error("payload is required for pre-gloas processWithdrawals");

package/src/cache/epochCache.ts

@@ -38,9 +38,9 @@ import {
   computeEpochAtSlot,
   computeProposers,
   computeSyncPeriodAtEpoch,
-  getActivationChurnLimit,
   getChurnLimit,
   getSeed,
+  getValidatorActivationChurnLimit,
   isActiveValidator,
   isAggregatorFromCommitteeLength,
 } from "../util/index.js";
@@ -478,7 +478,7 @@ export class EpochCache {
     // the first block of the epoch process_block() call. So churnLimit must be computed at the end of the before epoch
     // transition and the result is valid until the end of the next epoch transition
     const churnLimit = getChurnLimit(config, currentShuffling.activeIndices.length);
-    const activationChurnLimit = getActivationChurnLimit(
+    const activationChurnLimit = getValidatorActivationChurnLimit(
       config,
       config.getForkSeq(state.slot),
       currentShuffling.activeIndices.length
@@ -652,7 +652,7 @@ export class EpochCache {
     // the first block of the epoch process_block() call. So churnLimit must be computed at the end of the before epoch
     // transition and the result is valid until the end of the next epoch transition
     this.churnLimit = getChurnLimit(this.config, this.currentShuffling.activeIndices.length);
-    this.activationChurnLimit = getActivationChurnLimit(
+    this.activationChurnLimit = getValidatorActivationChurnLimit(
       this.config,
       this.config.getForkSeq(state.slot),
       this.currentShuffling.activeIndices.length

package/src/epoch/processPendingDeposits.ts

@@ -5,7 +5,7 @@ import {CachedBeaconStateElectra, EpochTransitionCache} from "../types.js";
 import {increaseBalance} from "../util/balance.js";
 import {hasCompoundingWithdrawalCredential, isValidatorKnown} from "../util/electra.js";
 import {computeStartSlotAtEpoch} from "../util/epoch.js";
-import {getActivationExitChurnLimit} from "../util/validator.js";
+import {getActivationChurnLimit, getActivationExitChurnLimit} from "../util/validator.js";
 
 /**
  * Starting from Electra:
@@ -17,8 +17,11 @@ import {getActivationExitChurnLimit} from "../util/validator.js";
  * TODO Electra: Update ssz library to support batch push to `pendingDeposits`
  */
 export function processPendingDeposits(state: CachedBeaconStateElectra, cache: EpochTransitionCache): void {
+  const fork = state.config.getForkSeq(state.slot);
   const nextEpoch = state.epochCtx.epoch + 1;
-  const availableForProcessing = state.depositBalanceToConsume + BigInt(getActivationExitChurnLimit(state.epochCtx));
+  const churnLimit =
+    fork >= ForkSeq.gloas ? getActivationChurnLimit(state.epochCtx) : getActivationExitChurnLimit(state.epochCtx);
+  const availableForProcessing = state.depositBalanceToConsume + BigInt(churnLimit);
   let processedAmount = 0;
   let nextDepositIndex = 0;
   const depositsToPostpone = [];

package/src/lightClient/spec/index.ts

@@ -0,0 +1,101 @@
+import {BeaconConfig} from "@lodestar/config";
+import {UPDATE_TIMEOUT} from "@lodestar/params";
+import {
+  LightClientBootstrap,
+  LightClientFinalityUpdate,
+  LightClientOptimisticUpdate,
+  LightClientUpdate,
+  Slot,
+} from "@lodestar/types";
+import {computeSyncPeriodAtSlot} from "../../util/epoch.js";
+import {
+  type ProcessUpdateOpts,
+  getSyncCommitteeAtPeriod,
+  processLightClientUpdate,
+} from "./processLightClientUpdate.js";
+import {type ILightClientStore, LightClientStore, type LightClientStoreEvents} from "./store.js";
+import {ZERO_HEADER, ZERO_SYNC_COMMITTEE, getZeroFinalityBranch, getZeroSyncCommitteeBranch} from "./utils.js";
+
+export type {LightClientUpdateSummary} from "./isBetterUpdate.js";
+export {isBetterUpdate, toLightClientUpdateSummary} from "./isBetterUpdate.js";
+export {
+  type ProcessUpdateOpts,
+  getSyncCommitteeAtPeriod,
+  isSafeLightClientUpdate,
+  processLightClientUpdate,
+} from "./processLightClientUpdate.js";
+export {
+  type ILightClientStore,
+  LightClientStore,
+  type LightClientStoreEvents,
+  type LightClientUpdateWithSummary,
+  type SyncCommitteeFast,
+} from "./store.js";
+export {
+  getSafetyThreshold,
+  isFinalityUpdate,
+  isSyncCommitteeUpdate,
+  isValidLightClientHeader,
+  normalizeMerkleBranch,
+  upgradeLightClientFinalityUpdate,
+  upgradeLightClientHeader,
+  upgradeLightClientOptimisticUpdate,
+  upgradeLightClientStore,
+  upgradeLightClientUpdate,
+} from "./utils.js";
+export {validateLightClientBootstrap} from "./validateLightClientBootstrap.js";
+export {validateLightClientUpdate} from "./validateLightClientUpdate.js";
+
+export class LightclientSpec {
+  readonly store: ILightClientStore;
+  readonly config: BeaconConfig;
+
+  constructor(
+    config: BeaconConfig,
+    private readonly opts: ProcessUpdateOpts & LightClientStoreEvents,
+    bootstrap: LightClientBootstrap
+  ) {
+    this.store = new LightClientStore(config, bootstrap, opts);
+    this.config = config;
+  }
+
+  onUpdate(currentSlot: Slot, update: LightClientUpdate): void {
+    processLightClientUpdate(this.config, this.store, currentSlot, this.opts, update);
+  }
+
+  onFinalityUpdate(currentSlot: Slot, finalityUpdate: LightClientFinalityUpdate): void {
+    this.onUpdate(currentSlot, {
+      attestedHeader: finalityUpdate.attestedHeader,
+      nextSyncCommittee: ZERO_SYNC_COMMITTEE,
+      nextSyncCommitteeBranch: getZeroSyncCommitteeBranch(this.config.getForkName(finalityUpdate.signatureSlot)),
+      finalizedHeader: finalityUpdate.finalizedHeader,
+      finalityBranch: finalityUpdate.finalityBranch,
+      syncAggregate: finalityUpdate.syncAggregate,
+      signatureSlot: finalityUpdate.signatureSlot,
+    });
+  }
+
+  onOptimisticUpdate(currentSlot: Slot, optimisticUpdate: LightClientOptimisticUpdate): void {
+    this.onUpdate(currentSlot, {
+      attestedHeader: optimisticUpdate.attestedHeader,
+      nextSyncCommittee: ZERO_SYNC_COMMITTEE,
+      nextSyncCommitteeBranch: getZeroSyncCommitteeBranch(this.config.getForkName(optimisticUpdate.signatureSlot)),
+      finalizedHeader: {beacon: ZERO_HEADER},
+      finalityBranch: getZeroFinalityBranch(this.config.getForkName(optimisticUpdate.signatureSlot)),
+      syncAggregate: optimisticUpdate.syncAggregate,
+      signatureSlot: optimisticUpdate.signatureSlot,
+    });
+  }
+
+  forceUpdate(currentSlot: Slot): void {
+    for (const bestValidUpdate of this.store.bestValidUpdates.values()) {
+      if (currentSlot > bestValidUpdate.update.finalizedHeader.beacon.slot + UPDATE_TIMEOUT) {
+        const updatePeriod = computeSyncPeriodAtSlot(bestValidUpdate.update.signatureSlot);
+        // Simulate process_light_client_store_force_update() by forcing to apply a bestValidUpdate
+        // https://github.com/ethereum/consensus-specs/blob/a57e15636013eeba3610ff3ade41781dba1bb0cd/specs/altair/light-client/sync-protocol.md?plain=1#L394
+        // Call for `updatePeriod + 1` to force the update at `update.signatureSlot` to be applied
+        getSyncCommitteeAtPeriod(this.store, updatePeriod + 1, this.opts);
+      }
+    }
+  }
+}

package/src/lightClient/spec/isBetterUpdate.ts

@@ -0,0 +1,94 @@
+import {SYNC_COMMITTEE_SIZE} from "@lodestar/params";
+import {LightClientUpdate, Slot} from "@lodestar/types";
+import {computeSyncPeriodAtSlot} from "../../util/epoch.js";
+import {isFinalityUpdate, isSyncCommitteeUpdate, sumBits} from "./utils.js";
+
+/**
+ * Wrapper type for `isBetterUpdate()` so we can apply its logic without requiring the full LightClientUpdate type.
+ */
+export type LightClientUpdateSummary = {
+  activeParticipants: number;
+  attestedHeaderSlot: Slot;
+  signatureSlot: Slot;
+  finalizedHeaderSlot: Slot;
+  /** `if update.next_sync_committee_branch != [Bytes32() for _ in range(floorlog2(NEXT_SYNC_COMMITTEE_INDEX))]` */
+  isSyncCommitteeUpdate: boolean;
+  /** `if update.finality_branch != [Bytes32() for _ in range(floorlog2(FINALIZED_ROOT_INDEX))]` */
+  isFinalityUpdate: boolean;
+};
+
+/**
+ * Returns the update with more bits. On ties, prevUpdate is the better
+ *
+ * https://github.com/ethereum/consensus-specs/blob/be3c774069e16e89145660be511c1b183056017e/specs/altair/light-client/sync-protocol.md#is_better_update
+ */
+export function isBetterUpdate(newUpdate: LightClientUpdateSummary, oldUpdate: LightClientUpdateSummary): boolean {
+  // Compare supermajority (> 2/3) sync committee participation
+  const newNumActiveParticipants = newUpdate.activeParticipants;
+  const oldNumActiveParticipants = oldUpdate.activeParticipants;
+  const newHasSupermajority = newNumActiveParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2;
+  const oldHasSupermajority = oldNumActiveParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2;
+  if (newHasSupermajority !== oldHasSupermajority) {
+    return newHasSupermajority;
+  }
+  if (!newHasSupermajority && newNumActiveParticipants !== oldNumActiveParticipants) {
+    return newNumActiveParticipants > oldNumActiveParticipants;
+  }
+
+  // Compare presence of relevant sync committee
+  const newHasRelevantSyncCommittee =
+    newUpdate.isSyncCommitteeUpdate &&
+    computeSyncPeriodAtSlot(newUpdate.attestedHeaderSlot) === computeSyncPeriodAtSlot(newUpdate.signatureSlot);
+  const oldHasRelevantSyncCommittee =
+    oldUpdate.isSyncCommitteeUpdate &&
+    computeSyncPeriodAtSlot(oldUpdate.attestedHeaderSlot) === computeSyncPeriodAtSlot(oldUpdate.signatureSlot);
+  if (newHasRelevantSyncCommittee !== oldHasRelevantSyncCommittee) {
+    return newHasRelevantSyncCommittee;
+  }
+
+  // Compare indication of any finality
+  const newHasFinality = newUpdate.isFinalityUpdate;
+  const oldHasFinality = oldUpdate.isFinalityUpdate;
+  if (newHasFinality !== oldHasFinality) {
+    return newHasFinality;
+  }
+
+  // Compare sync committee finality
+  if (newHasFinality) {
+    const newHasSyncCommitteeFinality =
+      computeSyncPeriodAtSlot(newUpdate.finalizedHeaderSlot) === computeSyncPeriodAtSlot(newUpdate.attestedHeaderSlot);
+    const oldHasSyncCommitteeFinality =
+      computeSyncPeriodAtSlot(oldUpdate.finalizedHeaderSlot) === computeSyncPeriodAtSlot(oldUpdate.attestedHeaderSlot);
+    if (newHasSyncCommitteeFinality !== oldHasSyncCommitteeFinality) {
+      return newHasSyncCommitteeFinality;
+    }
+  }
+
+  // Tiebreaker 1: Sync committee participation beyond supermajority
+  if (newNumActiveParticipants !== oldNumActiveParticipants) {
+    return newNumActiveParticipants > oldNumActiveParticipants;
+  }
+
+  // Tiebreaker 2: Prefer older data (fewer changes to best)
+  if (newUpdate.attestedHeaderSlot !== oldUpdate.attestedHeaderSlot) {
+    return newUpdate.attestedHeaderSlot < oldUpdate.attestedHeaderSlot;
+  }
+  return newUpdate.signatureSlot < oldUpdate.signatureSlot;
+}
+
+export function isSafeLightClientUpdate(update: LightClientUpdateSummary): boolean {
+  return (
+    update.activeParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2 && update.isFinalityUpdate && update.isSyncCommitteeUpdate
+  );
+}
+
+export function toLightClientUpdateSummary(update: LightClientUpdate): LightClientUpdateSummary {
+  return {
+    activeParticipants: sumBits(update.syncAggregate.syncCommitteeBits),
+    attestedHeaderSlot: update.attestedHeader.beacon.slot,
+    signatureSlot: update.signatureSlot,
+    finalizedHeaderSlot: update.finalizedHeader.beacon.slot,
+    isSyncCommitteeUpdate: isSyncCommitteeUpdate(update),
+    isFinalityUpdate: isFinalityUpdate(update),
+  };
+}