@lodestar/beacon-node 1.35.0-dev.f80d2d52da → 1.35.0-dev.fd1dac853d

package/src/chain/rewards/attestationsRewards.ts

@@ -0,0 +1,196 @@
+import {routes} from "@lodestar/api";
+import {BeaconConfig} from "@lodestar/config";
+import {
+  EFFECTIVE_BALANCE_INCREMENT,
+  ForkName,
+  INACTIVITY_PENALTY_QUOTIENT_ALTAIR,
+  MAX_EFFECTIVE_BALANCE,
+  MAX_EFFECTIVE_BALANCE_ELECTRA,
+  PARTICIPATION_FLAG_WEIGHTS,
+  TIMELY_HEAD_FLAG_INDEX,
+  TIMELY_SOURCE_FLAG_INDEX,
+  TIMELY_TARGET_FLAG_INDEX,
+  WEIGHT_DENOMINATOR,
+  isForkPostElectra,
+} from "@lodestar/params";
+import {
+  CachedBeaconStateAllForks,
+  CachedBeaconStateAltair,
+  EpochTransitionCache,
+  FLAG_ELIGIBLE_ATTESTER,
+  FLAG_PREV_HEAD_ATTESTER_UNSLASHED,
+  FLAG_PREV_SOURCE_ATTESTER_UNSLASHED,
+  FLAG_PREV_TARGET_ATTESTER_UNSLASHED,
+  beforeProcessEpoch,
+  hasMarkers,
+  isInInactivityLeak,
+} from "@lodestar/state-transition";
+import {Epoch, ValidatorIndex} from "@lodestar/types";
+import {fromHex} from "@lodestar/utils";
+
+export type AttestationsRewards = routes.beacon.AttestationsRewards;
+type IdealAttestationsReward = routes.beacon.IdealAttestationsReward;
+type TotalAttestationsReward = routes.beacon.TotalAttestationsReward;
+/** Attestations penalty with respect to effective balance in Gwei */
+type AttestationsPenalty = {target: number; source: number; effectiveBalance: number};
+
+const defaultAttestationsReward = {head: 0, target: 0, source: 0, inclusionDelay: 0, inactivity: 0};
+const defaultAttestationsPenalty = {target: 0, source: 0};
+
+export async function computeAttestationsRewards(
+  _epoch: Epoch,
+  state: CachedBeaconStateAllForks,
+  _config: BeaconConfig,
+  validatorIds?: (ValidatorIndex | string)[]
+): Promise<AttestationsRewards> {
+  const fork = state.config.getForkName(state.slot);
+  if (fork === ForkName.phase0) {
+    throw Error("Unsupported fork. Attestations rewards calculation is not available in phase0");
+  }
+
+  const stateAltair = state as CachedBeaconStateAltair;
+  const transitionCache = beforeProcessEpoch(stateAltair);
+
+  const [idealRewards, penalties] = computeIdealAttestationsRewardsAndPenaltiesAltair(stateAltair, transitionCache);
+  const totalRewards = computeTotalAttestationsRewardsAltair(
+    stateAltair,
+    transitionCache,
+    idealRewards,
+    penalties,
+    validatorIds
+  );
+
+  return {idealRewards, totalRewards};
+}
+
+function computeIdealAttestationsRewardsAndPenaltiesAltair(
+  state: CachedBeaconStateAllForks,
+  transitionCache: EpochTransitionCache
+): [IdealAttestationsReward[], AttestationsPenalty[]] {
+  const baseRewardPerIncrement = transitionCache.baseRewardPerIncrement;
+  const activeBalanceByIncrement = transitionCache.totalActiveStakeByIncrement;
+  const fork = state.config.getForkName(state.slot);
+  const maxEffectiveBalance = isForkPostElectra(fork) ? MAX_EFFECTIVE_BALANCE_ELECTRA : MAX_EFFECTIVE_BALANCE;
+  const maxEffectiveBalanceByIncrement = Math.floor(maxEffectiveBalance / EFFECTIVE_BALANCE_INCREMENT);
+
+  const idealRewards = Array.from({length: maxEffectiveBalanceByIncrement + 1}, (_, effectiveBalanceByIncrement) => ({
+    ...defaultAttestationsReward,
+    effectiveBalance: effectiveBalanceByIncrement * EFFECTIVE_BALANCE_INCREMENT,
+  }));
+
+  const attestationsPenalties: AttestationsPenalty[] = Array.from(
+    {length: maxEffectiveBalanceByIncrement + 1},
+    (_, effectiveBalanceByIncrement) => ({
+      ...defaultAttestationsPenalty,
+      effectiveBalance: effectiveBalanceByIncrement * EFFECTIVE_BALANCE_INCREMENT,
+    })
+  );
+
+  for (let i = 0; i < PARTICIPATION_FLAG_WEIGHTS.length; i++) {
+    const weight = PARTICIPATION_FLAG_WEIGHTS[i];
+
+    let unslashedStakeByIncrement: number;
+    let flagName: keyof IdealAttestationsReward;
+
+    switch (i) {
+      case TIMELY_SOURCE_FLAG_INDEX: {
+        unslashedStakeByIncrement = transitionCache.prevEpochUnslashedStake.sourceStakeByIncrement;
+        flagName = "source";
+        break;
+      }
+      case TIMELY_TARGET_FLAG_INDEX: {
+        unslashedStakeByIncrement = transitionCache.prevEpochUnslashedStake.targetStakeByIncrement;
+        flagName = "target";
+        break;
+      }
+      case TIMELY_HEAD_FLAG_INDEX: {
+        unslashedStakeByIncrement = transitionCache.prevEpochUnslashedStake.headStakeByIncrement;
+        flagName = "head";
+        break;
+      }
+      default: {
+        throw Error(`Unable to retrieve unslashed stake. Unknown participation flag index: ${i}`);
+      }
+    }
+
+    for (
+      let effectiveBalanceByIncrement = 0;
+      effectiveBalanceByIncrement <= maxEffectiveBalanceByIncrement;
+      effectiveBalanceByIncrement++
+    ) {
+      const baseReward = effectiveBalanceByIncrement * baseRewardPerIncrement;
+      const rewardNumerator = baseReward * weight * unslashedStakeByIncrement;
+      // Both idealReward and penalty are rounded to nearest integer. Loss of precision is minimal as unit is gwei
+      const idealReward = Math.round(rewardNumerator / activeBalanceByIncrement / WEIGHT_DENOMINATOR);
+      const penalty = Math.round((baseReward * weight) / WEIGHT_DENOMINATOR); // Positive number indicates penalty
+
+      const idealAttestationsReward = idealRewards[effectiveBalanceByIncrement];
+      idealAttestationsReward[flagName] = isInInactivityLeak(state) ? 0 : idealReward; // No attestations rewards during inactivity leak
+
+      if (flagName !== "head") {
+        const attestationPenalty = attestationsPenalties[effectiveBalanceByIncrement];
+        attestationPenalty[flagName] = penalty;
+      }
+    }
+  }
+
+  return [idealRewards, attestationsPenalties];
+}
+
+// Same calculation as `getRewardsAndPenaltiesAltair` but returns the breakdown of rewards instead of aggregated
+function computeTotalAttestationsRewardsAltair(
+  state: CachedBeaconStateAltair,
+  transitionCache: EpochTransitionCache,
+  idealRewards: IdealAttestationsReward[],
+  penalties: AttestationsPenalty[],
+  validatorIds: (ValidatorIndex | string)[] = []
+): TotalAttestationsReward[] {
+  const rewards = [];
+  const {flags} = transitionCache;
+  const {epochCtx, config} = state;
+  const validatorIndices = validatorIds
+    .map((id) => (typeof id === "number" ? id : epochCtx.pubkey2index.get(fromHex(id))))
+    .filter((index) => index !== undefined); // Validator indices to include in the result
+
+  const inactivityPenaltyDenominator = config.INACTIVITY_SCORE_BIAS * INACTIVITY_PENALTY_QUOTIENT_ALTAIR;
+
+  for (let i = 0; i < flags.length; i++) {
+    if (validatorIndices.length && !validatorIndices.includes(i)) {
+      continue;
+    }
+
+    const flag = flags[i];
+    if (!hasMarkers(flag, FLAG_ELIGIBLE_ATTESTER)) {
+      continue;
+    }
+
+    const effectiveBalanceIncrement = epochCtx.effectiveBalanceIncrements[i];
+
+    const currentRewards = {...defaultAttestationsReward, validatorIndex: i};
+
+    if (hasMarkers(flag, FLAG_PREV_SOURCE_ATTESTER_UNSLASHED)) {
+      currentRewards.source = idealRewards[effectiveBalanceIncrement].source;
+    } else {
+      currentRewards.source = penalties[effectiveBalanceIncrement].source * -1; // Negative reward to indicate penalty
+    }
+
+    if (hasMarkers(flag, FLAG_PREV_TARGET_ATTESTER_UNSLASHED)) {
+      currentRewards.target = idealRewards[effectiveBalanceIncrement].target;
+    } else {
+      currentRewards.target = penalties[effectiveBalanceIncrement].target * -1;
+
+      // Also incur inactivity penalty if not voting target correctly
+      const inactivityPenaltyNumerator =
+        effectiveBalanceIncrement * EFFECTIVE_BALANCE_INCREMENT * state.inactivityScores.get(i);
+      currentRewards.inactivity = Math.floor(inactivityPenaltyNumerator / inactivityPenaltyDenominator) * -1;
+    }
+
+    if (hasMarkers(flag, FLAG_PREV_HEAD_ATTESTER_UNSLASHED)) {
+      currentRewards.head = idealRewards[effectiveBalanceIncrement].head;
+    }
+
+    rewards.push(currentRewards);
+  }
+
+  return rewards;
+}

package/src/chain/rewards/blockRewards.ts

@@ -0,0 +1,150 @@
+import {routes} from "@lodestar/api";
+import {
+  ForkName,
+  WHISTLEBLOWER_REWARD_QUOTIENT,
+  WHISTLEBLOWER_REWARD_QUOTIENT_ELECTRA,
+  isForkPostElectra,
+} from "@lodestar/params";
+import {
+  CachedBeaconStateAllForks,
+  CachedBeaconStateAltair,
+  CachedBeaconStatePhase0,
+  getAttesterSlashableIndices,
+  processAttestationsAltair,
+} from "@lodestar/state-transition";
+import {BeaconBlock, altair, phase0} from "@lodestar/types";
+
+export type BlockRewards = routes.beacon.BlockRewards;
+type SubRewardValue = number; // All reward values should be integer
+
+/**
+ * Calculate total proposer block rewards given block and the beacon state of the same slot before the block is applied (preState)
+ * postState can be passed in to read reward cache if available
+ * Standard (Non MEV) rewards for proposing a block consists of:
+ *  1) Including attestations from (beacon) committee
+ *  2) Including attestations from sync committee
+ *  3) Reporting slashable behaviours from proposer and attester
+ */
+export async function computeBlockRewards(
+  block: BeaconBlock,
+  preState: CachedBeaconStateAllForks,
+  postState?: CachedBeaconStateAllForks
+): Promise<BlockRewards> {
+  const fork = preState.config.getForkName(block.slot);
+  const {attestations: cachedAttestationsReward = 0, syncAggregate: cachedSyncAggregateReward = 0} =
+    postState?.proposerRewards ?? {};
+  let blockAttestationReward = cachedAttestationsReward;
+  let syncAggregateReward = cachedSyncAggregateReward;
+
+  if (blockAttestationReward === 0) {
+    blockAttestationReward =
+      fork === ForkName.phase0
+        ? computeBlockAttestationRewardPhase0(block as phase0.BeaconBlock, preState as CachedBeaconStatePhase0)
+        : computeBlockAttestationRewardAltair(block as altair.BeaconBlock, preState as CachedBeaconStateAltair);
+  }
+
+  if (syncAggregateReward === 0) {
+    syncAggregateReward = computeSyncAggregateReward(block as altair.BeaconBlock, preState as CachedBeaconStateAltair);
+  }
+
+  const blockProposerSlashingReward = computeBlockProposerSlashingReward(fork, block, preState);
+  const blockAttesterSlashingReward = computeBlockAttesterSlashingReward(fork, block, preState);
+
+  const total =
+    blockAttestationReward + syncAggregateReward + blockProposerSlashingReward + blockAttesterSlashingReward;
+
+  return {
+    proposerIndex: block.proposerIndex,
+    total,
+    attestations: blockAttestationReward,
+    syncAggregate: syncAggregateReward,
+    proposerSlashings: blockProposerSlashingReward,
+    attesterSlashings: blockAttesterSlashingReward,
+  };
+}
+
+/**
+ * TODO: Calculate rewards received by block proposer for including attestations.
+ */
+function computeBlockAttestationRewardPhase0(
+  _block: phase0.BeaconBlock,
+  _preState: CachedBeaconStatePhase0
+): SubRewardValue {
+  throw new Error("Unsupported fork! Block attestation reward calculation is not available in phase0");
+}
+
+/**
+ * Calculate rewards received by block proposer for including attestations since Altair.
+ * Reuses `processAttestationsAltair()`. Has dependency on RewardCache
+ */
+function computeBlockAttestationRewardAltair(
+  block: altair.BeaconBlock,
+  preState: CachedBeaconStateAltair
+): SubRewardValue {
+  const fork = preState.config.getForkSeq(block.slot);
+  const {attestations} = block.body;
+
+  processAttestationsAltair(fork, preState, attestations, false);
+
+  return preState.proposerRewards.attestations;
+}
+
+function computeSyncAggregateReward(block: altair.BeaconBlock, preState: CachedBeaconStateAltair): SubRewardValue {
+  if (block.body.syncAggregate !== undefined) {
+    const {syncCommitteeBits} = block.body.syncAggregate;
+    const {syncProposerReward} = preState.epochCtx;
+
+    return syncCommitteeBits.getTrueBitIndexes().length * Math.floor(syncProposerReward); // syncProposerReward should already be integer
+  }
+
+  return 0; // phase0 block does not have syncAggregate
+}
+
+/**
+ * Calculate rewards received by block proposer for including proposer slashings.
+ * All proposer slashing rewards go to block proposer and none to whistleblower as of Deneb
+ */
+function computeBlockProposerSlashingReward(
+  fork: ForkName,
+  block: BeaconBlock,
+  state: CachedBeaconStateAllForks
+): SubRewardValue {
+  let proposerSlashingReward = 0;
+
+  for (const proposerSlashing of block.body.proposerSlashings) {
+    const offendingProposerIndex = proposerSlashing.signedHeader1.message.proposerIndex;
+    const offendingProposerBalance = state.validators.getReadonly(offendingProposerIndex).effectiveBalance;
+    const whistleblowerRewardQuotient = isForkPostElectra(fork)
+      ? WHISTLEBLOWER_REWARD_QUOTIENT_ELECTRA
+      : WHISTLEBLOWER_REWARD_QUOTIENT;
+
+    proposerSlashingReward += Math.floor(offendingProposerBalance / whistleblowerRewardQuotient);
+  }
+
+  return proposerSlashingReward;
+}
+
+/**
+ * Calculate rewards received by block proposer for including attester slashings.
+ * All attester slashing rewards go to block proposer and none to whistleblower as of Deneb
+ */
+function computeBlockAttesterSlashingReward(
+  fork: ForkName,
+  block: BeaconBlock,
+  preState: CachedBeaconStateAllForks
+): SubRewardValue {
+  let attesterSlashingReward = 0;
+
+  for (const attesterSlashing of block.body.attesterSlashings) {
+    for (const offendingAttesterIndex of getAttesterSlashableIndices(attesterSlashing)) {
+      const offendingAttesterBalance = preState.validators.getReadonly(offendingAttesterIndex).effectiveBalance;
+      const whistleblowerRewardQuotient = isForkPostElectra(fork)
+        ? WHISTLEBLOWER_REWARD_QUOTIENT_ELECTRA
+        : WHISTLEBLOWER_REWARD_QUOTIENT;
+
+      attesterSlashingReward += Math.floor(offendingAttesterBalance / whistleblowerRewardQuotient);
+    }
+  }
+
+  return attesterSlashingReward;
+}

package/src/chain/rewards/syncCommitteeRewards.ts

@@ -0,0 +1,58 @@
+import {routes} from "@lodestar/api";
+import {ForkName, SYNC_COMMITTEE_SIZE} from "@lodestar/params";
+import {CachedBeaconStateAllForks, CachedBeaconStateAltair} from "@lodestar/state-transition";
+import {BeaconBlock, ValidatorIndex, altair} from "@lodestar/types";
+
+export type SyncCommitteeRewards = routes.beacon.SyncCommitteeRewards;
+type BalanceRecord = {val: number}; // Use val for convenient way to increment/decrement balance
+
+export async function computeSyncCommitteeRewards(
+  block: BeaconBlock,
+  preState: CachedBeaconStateAllForks,
+  validatorIds: (ValidatorIndex | string)[] = []
+): Promise<SyncCommitteeRewards> {
+  const fork = preState.config.getForkName(block.slot);
+  if (fork === ForkName.phase0) {
+    throw Error("Cannot get sync rewards as phase0 block does not have sync committee");
+  }
+
+  const altairBlock = block as altair.BeaconBlock;
+  const preStateAltair = preState as CachedBeaconStateAltair;
+  const {index2pubkey} = preStateAltair.epochCtx;
+
+  // Bound syncCommitteeValidatorIndices in case it goes beyond SYNC_COMMITTEE_SIZE just to be safe
+  const syncCommitteeValidatorIndices = preStateAltair.epochCtx.currentSyncCommitteeIndexed.validatorIndices.slice(
+    0,
+    SYNC_COMMITTEE_SIZE
+  );
+  const {syncParticipantReward} = preStateAltair.epochCtx;
+  const {syncCommitteeBits} = altairBlock.body.syncAggregate;
+
+  // Use balance of each committee as starting point such that we cap the penalty to avoid balance dropping below 0
+  const balances: Map<ValidatorIndex, BalanceRecord> = new Map();
+  for (const i of syncCommitteeValidatorIndices) {
+    balances.set(i, {val: preStateAltair.balances.get(i)});
+  }
+
+  for (const i of syncCommitteeValidatorIndices) {
+    const balanceRecord = balances.get(i) as BalanceRecord;
+    if (syncCommitteeBits.get(i)) {
+      // Positive rewards for participants
+      balanceRecord.val += syncParticipantReward;
+    } else {
+      // Negative rewards for non participants
+      balanceRecord.val = Math.max(0, balanceRecord.val - syncParticipantReward);
+    }
+  }
+
+  const rewards = Array.from(balances, ([validatorIndex, v]) => ({validatorIndex, reward: v.val}));
+
+  if (validatorIds.length) {
+    const filtersSet = new Set(validatorIds);
+    return rewards.filter(
+      (reward) => filtersSet.has(reward.validatorIndex) || filtersSet.has(index2pubkey[reward.validatorIndex].toHex())
+    );
+  }
+
+  return rewards;
+}

package/src/chain/seenCache/index.ts

@@ -0,0 +1,5 @@
+export {SeenAggregators, SeenAttesters} from "./seenAttesters.js";
+export {SeenBlockProposers} from "./seenBlockProposers.js";
+export {SeenSyncCommitteeMessages} from "./seenCommittee.js";
+export {SeenContributionAndProof} from "./seenCommitteeContribution.js";
+export {SeenBlockInput} from "./seenGossipBlockInput.js";

package/src/chain/seenCache/seenAggregateAndProof.ts

@@ -0,0 +1,120 @@
+import {BitArray} from "@chainsafe/ssz";
+import {CommitteeIndex, Epoch, RootHex} from "@lodestar/types";
+import {MapDef} from "@lodestar/utils";
+import {Metrics} from "../../metrics/index.js";
+import {isSuperSetOrEqual} from "../../util/bitArray.js";
+
+/**
+ * With this gossip validation condition:
+ * pre-deneb:
+ * - [IGNORE] aggregate.data.slot is within the last ATTESTATION_PROPAGATION_SLOT_RANGE slots (with a MAXIMUM_GOSSIP_CLOCK_DISPARITY allowance)
+ * post-deneb:
+ * - [IGNORE] the epoch of `aggregate.data.slot` is either the current or previous epoch
+ * - [IGNORE] `aggregate.data.slot` is equal to or earlier than the `current_slot` (with a `MAXIMUM_GOSSIP_CLOCK_DISPARITY` allowance)
+ *
+ * We keep seen AggregateAndProof in the last 2 epochs pre and post deneb.
+ */
+const EPOCH_LOOKBACK_LIMIT = 2;
+
+export type AggregationInfo = {
+  aggregationBits: BitArray;
+  trueBitCount: number;
+};
+
+/**
+ * Although there are up to TARGET_AGGREGATORS_PER_COMMITTEE (16 for mainnet) AggregateAndProof messages per slot,
+ * they tend to have the same aggregate attestation, or one attestation is non-strict superset of another,
+ * the gossipsub messages-ids are different because they are really different SignedAggregateAndProof object.
+ * This is used to address the following spec in p2p-interface gossipsub:
+ * _[IGNORE]_ A valid aggregate attestation defined by `hash_tree_root(aggregate.data)` whose `aggregation_bits` is a
+ * non-strict superset has _not_ already been seen.
+ *
+ * We have AggregatedAttestationPool op pool, however aggregated attestations are not added to that place while this does.
+ */
+export class SeenAggregatedAttestations {
+  /**
+   * Array of AttestingIndices by same attestation data root by epoch.
+   * Note that there are at most TARGET_AGGREGATORS_PER_COMMITTEE (16) per attestation data.
+   * */
+  private readonly aggregateRootsByEpoch = new MapDef<
+    Epoch,
+    MapDef<CommitteeIndex, MapDef<RootHex, AggregationInfo[]>>
+  >(
+    () =>
+      new MapDef<CommitteeIndex, MapDef<RootHex, AggregationInfo[]>>(
+        () => new MapDef<RootHex, AggregationInfo[]>(() => [])
+      )
+  );
+  private lowestPermissibleEpoch: Epoch = 0;
+
+  constructor(private readonly metrics: Metrics | null) {}
+
+  isKnown(
+    targetEpoch: Epoch,
+    committeeIndex: CommitteeIndex,
+    attDataRoot: RootHex,
+    aggregationBits: BitArray
+  ): boolean {
+    const seenAggregationInfoArr = this.aggregateRootsByEpoch
+      .getOrDefault(targetEpoch)
+      .getOrDefault(committeeIndex)
+      .getOrDefault(attDataRoot);
+    this.metrics?.seenCache.aggregatedAttestations.isKnownCalls.inc();
+
+    for (let i = 0; i < seenAggregationInfoArr.length; i++) {
+      if (isSuperSetOrEqual(seenAggregationInfoArr[i].aggregationBits, aggregationBits)) {
+        this.metrics?.seenCache.aggregatedAttestations.superSetCheckTotal.observe(i + 1);
+        this.metrics?.seenCache.aggregatedAttestations.isKnownHits.inc();
+        return true;
+      }
+    }
+
+    this.metrics?.seenCache.aggregatedAttestations.superSetCheckTotal.observe(seenAggregationInfoArr.length);
+    return false;
+  }
+
+  add(
+    targetEpoch: Epoch,
+    committeeIndex: CommitteeIndex,
+    attDataRoot: RootHex,
+    newItem: AggregationInfo,
+    checkIsKnown: boolean
+  ): void {
+    const {aggregationBits} = newItem;
+    if (checkIsKnown && this.isKnown(targetEpoch, committeeIndex, attDataRoot, aggregationBits)) {
+      return;
+    }
+
+    const seenAggregationInfoArr = this.aggregateRootsByEpoch
+      .getOrDefault(targetEpoch)
+      .getOrDefault(committeeIndex)
+      .getOrDefault(attDataRoot);
+    insertDesc(seenAggregationInfoArr, newItem);
+  }
+
+  prune(currentEpoch: Epoch): void {
+    this.lowestPermissibleEpoch = Math.max(currentEpoch - EPOCH_LOOKBACK_LIMIT, 0);
+    for (const epoch of this.aggregateRootsByEpoch.keys()) {
+      if (epoch < this.lowestPermissibleEpoch) {
+        this.aggregateRootsByEpoch.delete(epoch);
+      }
+    }
+  }
+}
+
+/**
+ * Make sure seenAggregationInfoArr is always in desc order based on trueBitCount so that isKnown can be faster
+ */
+export function insertDesc(seenAggregationInfoArr: AggregationInfo[], newItem: AggregationInfo): void {
+  const {trueBitCount} = newItem;
+  let found = false;
+  for (let i = 0; i < seenAggregationInfoArr.length; i++) {
+    if (trueBitCount >= seenAggregationInfoArr[i].trueBitCount) {
+      seenAggregationInfoArr.splice(i, 0, newItem);
+      found = true;
+      break;
+    }
+  }
+
+  if (!found) seenAggregationInfoArr.push(newItem);
+}

package/src/chain/seenCache/seenAttestationData.ts

@@ -0,0 +1,145 @@
+import {CommitteeIndex, RootHex, Slot, SubnetID, phase0} from "@lodestar/types";
+import {MapDef} from "@lodestar/utils";
+import {Metrics} from "../../metrics/metrics.js";
+import {InsertOutcome} from "../opPools/types.js";
+
+export type SeenAttDataKey = AttDataBase64;
+// AttestationData is used to cache attestations
+type AttDataBase64 = string;
+
+export type AttestationDataCacheEntry = {
+  // part of shuffling data, so this does not take memory
+  committeeValidatorIndices: Uint32Array;
+  committeeIndex: CommitteeIndex;
+  // IndexedAttestationData signing root, 32 bytes
+  signingRoot: Uint8Array;
+  // to be consumed by forkchoice and oppool
+  attDataRootHex: RootHex;
+  // caching this for 3 slots take 600 instances max, this is nothing compared to attestations processed per slot
+  // for example in a mainnet node subscribing to all subnets, attestations are processed up to 20k per slot
+  attestationData: phase0.AttestationData;
+  subnet: SubnetID;
+};
+
+export enum RejectReason {
+  // attestation data reaches MAX_CACHE_SIZE_PER_SLOT
+  reached_limit = "reached_limit",
+  // attestation data is too old
+  too_old = "too_old",
+  // attestation data is already known
+  already_known = "already_known",
+}
+
+// For pre-electra, there is no committeeIndex in SingleAttestation, so we hard code it to 0
+// AttDataBase64 has committeeIndex instead
+export const PRE_ELECTRA_SINGLE_ATTESTATION_COMMITTEE_INDEX = 0;
+
+/**
+ * There are maximum 64 committees per slot, assuming 1 committee may have up to 3 different data due to some nodes
+ * are not up to date, we can have up to 192 different attestation data per slot.
+ */
+const DEFAULT_MAX_CACHE_SIZE_PER_SLOT = 200;
+
+/**
+ * It takes less than 300kb to cache 200 attestation data per slot, so we can cache 3 slots worth of attestation data.
+ */
+const DEFAULT_CACHE_SLOT_DISTANCE = 2;
+
+/**
+ * Cached seen AttestationData to improve gossip validation. For Electra, this still take into account attestationIndex
+ * even through it is moved outside of AttestationData.
+ * As of April 2023, validating gossip attestation takes ~12% of cpu time for a node subscribing to all subnets on mainnet.
+ * Having this cache help saves a lot of cpu time since most of the gossip attestations are on the same slot.
+ */
+export class SeenAttestationDatas {
+  private cacheEntryByAttDataByIndexBySlot = new MapDef<
+    Slot,
+    MapDef<CommitteeIndex, Map<AttDataBase64, AttestationDataCacheEntry>>
+  >(
+    () =>
+      new MapDef<CommitteeIndex, Map<AttDataBase64, AttestationDataCacheEntry>>(
+        () => new Map<AttDataBase64, AttestationDataCacheEntry>()
+      )
+  );
+  private lowestPermissibleSlot = 0;
+
+  constructor(
+    private readonly metrics: Metrics | null,
+    private readonly cacheSlotDistance = DEFAULT_CACHE_SLOT_DISTANCE,
+    // mainly for unit test
+    private readonly maxCacheSizePerSlot = DEFAULT_MAX_CACHE_SIZE_PER_SLOT
+  ) {
+    metrics?.seenCache.attestationData.totalSlot.addCollect(() => this.onScrapeLodestarMetrics(metrics));
+  }
+
+  /**
+   * Add an AttestationDataCacheEntry to the cache.
+   * - preElectra: add(slot, PRE_ELECTRA_SINGLE_ATTESTATION_COMMITTEE_INDEX, attDataBase64, cacheEntry)
+   * - electra: add(slot, committeeIndex, attDataBase64, cacheEntry)
+   */
+  add(
+    slot: Slot,
+    committeeIndex: CommitteeIndex,
+    attDataBase64: AttDataBase64,
+    cacheEntry: AttestationDataCacheEntry
+  ): InsertOutcome {
+    if (slot < this.lowestPermissibleSlot) {
+      this.metrics?.seenCache.attestationData.reject.inc({reason: RejectReason.too_old});
+      return InsertOutcome.Old;
+    }
+
+    const cacheEntryByAttDataByIndex = this.cacheEntryByAttDataByIndexBySlot.getOrDefault(slot);
+    const cacheEntryByAttData = cacheEntryByAttDataByIndex.getOrDefault(committeeIndex);
+    if (cacheEntryByAttData.has(attDataBase64)) {
+      this.metrics?.seenCache.attestationData.reject.inc({reason: RejectReason.already_known});
+      return InsertOutcome.AlreadyKnown;
+    }
+
+    if (cacheEntryByAttData.size >= this.maxCacheSizePerSlot) {
+      this.metrics?.seenCache.attestationData.reject.inc({reason: RejectReason.reached_limit});
+      return InsertOutcome.ReachLimit;
+    }
+
+    cacheEntryByAttData.set(attDataBase64, cacheEntry);
+    return InsertOutcome.NewData;
+  }
+
+  /**
+   * Get an AttestationDataCacheEntry from the cache.
+   * - preElectra: get(slot, PRE_ELECTRA_SINGLE_ATTESTATION_COMMITTEE_INDEX, attDataBase64)
+   * - electra: get(slot, committeeIndex, attDataBase64)
+   */
+  get(slot: Slot, committeeIndex: CommitteeIndex, attDataBase64: SeenAttDataKey): AttestationDataCacheEntry | null {
+    const cacheEntryByAttDataByIndex = this.cacheEntryByAttDataByIndexBySlot.get(slot);
+    const cacheEntryByAttData = cacheEntryByAttDataByIndex?.get(committeeIndex);
+    const cacheEntry = cacheEntryByAttData?.get(attDataBase64);
+    if (cacheEntry) {
+      this.metrics?.seenCache.attestationData.hit.inc();
+    } else {
+      this.metrics?.seenCache.attestationData.miss.inc();
+    }
+    return cacheEntry ?? null;
+  }
+
+  onSlot(clockSlot: Slot): void {
+    this.lowestPermissibleSlot = Math.max(clockSlot - this.cacheSlotDistance, 0);
+    for (const slot of this.cacheEntryByAttDataByIndexBySlot.keys()) {
+      if (slot < this.lowestPermissibleSlot) {
+        this.cacheEntryByAttDataByIndexBySlot.delete(slot);
+      }
+    }
+  }
+
+  private onScrapeLodestarMetrics(metrics: Metrics): void {
+    metrics?.seenCache.attestationData.totalSlot.set(this.cacheEntryByAttDataByIndexBySlot.size);
+    // tracking number of attestation data at current slot may not be correct if scrape time is not at the end of slot
+    // so we track it at the previous slot
+    const previousSlot = this.lowestPermissibleSlot + this.cacheSlotDistance - 1;
+    const cacheEntryByAttDataByIndex = this.cacheEntryByAttDataByIndexBySlot.get(previousSlot);
+    let count = 0;
+    for (const cacheEntryByAttDataBase64 of cacheEntryByAttDataByIndex?.values() ?? []) {
+      count += cacheEntryByAttDataBase64.size;
+    }
+    metrics?.seenCache.attestationData.countPerSlot.set(count);
+  }
+}