@aztec/epoch-cache 5.0.0-private.20260319 → 5.0.0-rc.1

package/src/epoch_cache.ts

@@ -1,6 +1,7 @@
 import { createEthereumChain } from '@aztec/ethereum/chain';
 import { makeL1HttpTransport } from '@aztec/ethereum/client';
 import { NoCommitteeError, RollupContract } from '@aztec/ethereum/contracts';
+import { getFinalizedL1Block } from '@aztec/ethereum/queries';
 import { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { type Logger, createLogger } from '@aztec/foundation/log';
@@ -9,8 +10,11 @@ import {
   type L1RollupConstants,
   getEpochAtSlot,
   getEpochNumberAtTimestamp,
+  getNextL1SlotTimestamp,
+  getSlotAtNextL1Block,
   getSlotAtTimestamp,
   getSlotRangeForEpoch,
+  getStartTimestampForEpoch,
   getTimestampForSlot,
 } from '@aztec/stdlib/epoch-helpers';
 
@@ -18,7 +22,7 @@ import { createPublicClient, encodeAbiParameters, keccak256 } from 'viem';
 
 import { type EpochCacheConfig, getEpochCacheConfigEnvVars } from './config.js';
 
-/** When proposer pipelining is enabled, the proposer builds one slot ahead. */
+/** The proposer pipelines by building one slot ahead. */
 export const PROPOSER_PIPELINING_SLOT_OFFSET = 1;
 
 /** Flat return type for compound epoch/slot getters. */
@@ -38,6 +42,22 @@ export type EpochCommitteeInfo = {
 
 export type SlotTag = 'now' | 'next' | SlotNumber;
 
+/** Minimal L1 block info used for cache provenance. */
+type L1BlockInfo = { number: bigint; hash: `0x${string}`; timestamp: bigint };
+
+/** Resolved cache entry with L1 provenance metadata. */
+type CachedEpochEntry = {
+  data: EpochCommitteeInfo;
+  /** L1 block number at which the committee data was originally queried. */
+  lastQueryL1BlockNumber: bigint;
+  /** L1 block hash at which the committee data was originally queried. Used to detect reorgs. */
+  lastQueryL1BlockHash: `0x${string}`;
+  /** Latest L1 block timestamp at the time of the most recent refresh (full fetch or lightweight check). */
+  lastRefreshL1Timestamp: bigint;
+  /** Whether the epoch's sampling data falls within finalized L1 history. */
+  finalized: boolean;
+};
+
 export interface EpochCacheInterface {
   getCommittee(slot: SlotTag | undefined): Promise<EpochCommitteeInfo>;
   getSlotNow(): SlotNumber;
@@ -48,7 +68,6 @@ export interface EpochCacheInterface {
   getEpochAndSlotInNextL1Slot(): EpochAndSlot & { nowSeconds: bigint };
   /** Returns epoch/slot info for the next L1 slot with pipeline offset applied. */
   getTargetEpochAndSlotInNextL1Slot(): EpochAndSlot & { nowSeconds: bigint };
-  isProposerPipeliningEnabled(): boolean;
   isEscapeHatchOpen(epoch: EpochNumber): Promise<boolean>;
   isEscapeHatchOpenAtSlot(slot: SlotTag): Promise<boolean>;
   getProposerIndexEncoding(epoch: EpochNumber, slot: SlotNumber, seed: bigint): `0x${string}`;
@@ -72,14 +91,15 @@ export interface EpochCacheInterface {
  * Note: This class is very dependent on the system clock being in sync.
  */
 export class EpochCache implements EpochCacheInterface {
-  // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
-  protected cache: Map<EpochNumber, EpochCommitteeInfo> = new Map();
+  /**
+   * Single map holding both resolved entries and in-flight promises.
+   * A `Promise` value means a fetch is in progress; concurrent callers await it.
+   */
+  protected cache: Map<EpochNumber, CachedEpochEntry | Promise<CachedEpochEntry>> = new Map();
   private allValidators: Set<string> = new Set();
   private lastValidatorRefresh = 0;
   private readonly log: Logger = createLogger('epoch-cache');
 
-  protected enableProposerPipelining: boolean;
-
   constructor(
     private rollup: RollupContract,
     private readonly l1constants: L1RollupConstants & {
@@ -87,12 +107,10 @@ export class EpochCache implements EpochCacheInterface {
       lagInEpochsForRandao: number;
     },
     private readonly dateProvider: DateProvider = new DateProvider(),
-    protected readonly config = { cacheSize: 12, validatorRefreshIntervalSeconds: 60, enableProposerPipelining: false },
+    protected readonly config = { cacheSize: 12, validatorRefreshIntervalSeconds: 60 },
   ) {
-    this.enableProposerPipelining = this.config.enableProposerPipelining;
     this.log.debug(`Initialized EpochCache`, {
       l1constants,
-      enableProposerPipelining: this.enableProposerPipelining,
     });
   }
 
@@ -155,7 +173,6 @@ export class EpochCache implements EpochCacheInterface {
     return new EpochCache(rollup, l1RollupConstants, deps.dateProvider, {
       cacheSize: 12,
       validatorRefreshIntervalSeconds: 60,
-      enableProposerPipelining: config.enableProposerPipelining,
     });
   }
 
@@ -163,17 +180,13 @@ export class EpochCache implements EpochCacheInterface {
     return this.l1constants;
   }
 
-  public isProposerPipeliningEnabled(): boolean {
-    return this.enableProposerPipelining;
-  }
-
   public getSlotNow(): SlotNumber {
     return this.getEpochAndSlotNow().slot;
   }
 
   public getTargetSlot(): SlotNumber {
     const slotNow = this.getSlotNow();
-    const offset = this.isProposerPipeliningEnabled() ? PROPOSER_PIPELINING_SLOT_OFFSET : 0;
+    const offset = PROPOSER_PIPELINING_SLOT_OFFSET;
     return SlotNumber(slotNow + offset);
   }
 
@@ -191,25 +204,17 @@ export class EpochCache implements EpochCacheInterface {
     return { ...this.getEpochAndSlotAtTimestamp(nowSeconds), nowMs };
   }
 
-  public nowInSeconds(): bigint {
-    return BigInt(Math.floor(this.dateProvider.now() / 1000));
-  }
-
   private getEpochAndSlotAtSlot(slot: SlotNumber): EpochAndSlot {
     return this.getEpochAndSlotAtTimestamp(getTimestampForSlot(slot, this.l1constants));
   }
 
   public getEpochAndSlotInNextL1Slot(): EpochAndSlot & { nowSeconds: bigint } {
-    const nowSeconds = this.nowInSeconds();
-    const nextSlotTs = nowSeconds + BigInt(this.l1constants.ethereumSlotDuration);
-    return { ...this.getEpochAndSlotAtTimestamp(nextSlotTs), nowSeconds };
+    const nowSeconds = this.dateProvider.nowInSeconds();
+    const nextSlotTs = getNextL1SlotTimestamp(nowSeconds, this.l1constants);
+    return { ...this.getEpochAndSlotAtTimestamp(nextSlotTs), nowSeconds: BigInt(nowSeconds) };
   }
 
   public getTargetEpochAndSlotInNextL1Slot(): EpochAndSlot & { nowSeconds: bigint } {
-    if (!this.isProposerPipeliningEnabled()) {
-      return this.getEpochAndSlotInNextL1Slot();
-    }
-
     const result = this.getEpochAndSlotInNextL1Slot();
     const offset = PROPOSER_PIPELINING_SLOT_OFFSET;
     const targetSlot = SlotNumber(result.slot + offset);
@@ -231,17 +236,8 @@ export class EpochCache implements EpochCacheInterface {
     return this.getCommittee(startSlot);
   }
 
-  /**
-   * Returns whether the escape hatch is open for the given epoch.
-   *
-   * Uses the already-cached EpochCommitteeInfo when available. If not cached, it will fetch
-   * the epoch committee info (which includes the escape hatch flag) and return it.
-   */
+  /** Returns whether the escape hatch is open for the given epoch. */
   public async isEscapeHatchOpen(epoch: EpochNumber): Promise<boolean> {
-    const cached = this.cache.get(epoch);
-    if (cached) {
-      return cached.isEscapeHatchOpen;
-    }
     const info = await this.getCommitteeForEpoch(epoch);
     return info.isEscapeHatchOpen;
   }
@@ -264,30 +260,49 @@ export class EpochCache implements EpochCacheInterface {
   }
 
   /**
-   * Get the current validator set
-   * @param nextSlot - If true, get the validator set for the next slot.
-   * @returns The current validator set.
+   * Get the current validator set.
+   *
+   * Returns cached data if the entry is finalized or still fresh (queried less than one
+   * Ethereum slot ago). Stale non-finalized entries are re-queried, and concurrent callers
+   * coalesce on the same in-flight promise so the L1 query happens only once.
    */
   public async getCommittee(slot: SlotTag = 'now'): Promise<EpochCommitteeInfo> {
     const { epoch, ts } = this.getEpochAndTimestamp(slot);
 
-    if (this.cache.has(epoch)) {
-      return this.cache.get(epoch)!;
+    const cached = this.cache.get(epoch);
+
+    // In-flight promise: another caller is already fetching this epoch — just await it.
+    if (cached instanceof Promise) {
+      return (await cached).data;
     }
 
-    const epochData = await this.computeCommittee({ epoch, ts });
-    // If the committee size is 0 or undefined, then do not cache
-    if (!epochData.committee || epochData.committee.length === 0) {
-      return epochData;
+    // Resolved entry: return it if finalized or still fresh.
+    if (cached && (cached.finalized || !this.isStale(cached))) {
+      return cached.data;
     }
-    this.cache.set(epoch, epochData);
 
-    const toPurge = Array.from(this.cache.keys())
-      .sort((a, b) => Number(b - a))
-      .slice(this.config.cacheSize);
-    toPurge.forEach(key => this.cache.delete(key));
+    // Stale non-finalized entry: do a lightweight refresh first (check block hash + finalized ts).
+    // Only fall back to a full re-fetch if the L1 block was reorged.
+    if (cached) {
+      const promise = this.refreshStaleEntry(cached, epoch, ts);
+      this.cache.set(epoch, promise);
+      try {
+        return (await promise).data;
+      } catch (err) {
+        this.cache.set(epoch, cached);
+        throw err;
+      }
+    }
 
-    return epochData;
+    // No entry at all: full fetch.
+    const promise = this.fetchAndCache(epoch, ts);
+    this.cache.set(epoch, promise);
+    try {
+      return (await promise).data;
+    } catch (err) {
+      this.cache.delete(epoch);
+      throw err;
+    }
   }
 
   private getEpochAndTimestamp(slot: SlotTag = 'now'): { epoch: EpochNumber; ts: bigint } {
@@ -300,22 +315,140 @@ export class EpochCache implements EpochCacheInterface {
     }
   }
 
-  private async computeCommittee(when: { epoch: EpochNumber; ts: bigint }): Promise<EpochCommitteeInfo> {
-    const { ts, epoch } = when;
-    const [committee, seedBuffer, l1Timestamp, isEscapeHatchOpen] = await Promise.all([
+  /** Evicts oldest cache entries (resolved or in-flight) beyond cacheSize. */
+  private purgeCache(): void {
+    if (this.cache.size <= this.config.cacheSize) {
+      return;
+    }
+    const toPurge = Array.from(this.cache.keys())
+      .sort((a, b) => Number(b - a))
+      .slice(this.config.cacheSize);
+    toPurge.forEach(key => this.cache.delete(key));
+  }
+
+  /** Returns true if a non-finalized cache entry is older than one Ethereum slot. */
+  private isStale(entry: CachedEpochEntry): boolean {
+    const nowSeconds = BigInt(this.dateProvider.nowInSeconds());
+    return nowSeconds - entry.lastRefreshL1Timestamp >= BigInt(this.l1constants.ethereumSlotDuration);
+  }
+
+  /** Whether a cached epoch entry has been marked as finalized. Returns undefined if not cached or still in-flight. */
+  public isFinalized(epoch: EpochNumber): boolean | undefined {
+    const entry = this.cache.get(epoch);
+    if (!entry || entry instanceof Promise) {
+      return undefined;
+    }
+    return entry.finalized;
+  }
+
+  /** Returns the latest L1 timestamp stored in the cached entry. Undefined if not cached or in-flight. */
+  public getCachedLastRefreshL1Timestamp(epoch: EpochNumber): bigint | undefined {
+    const entry = this.cache.get(epoch);
+    if (!entry || entry instanceof Promise) {
+      return undefined;
+    }
+    return entry.lastRefreshL1Timestamp;
+  }
+
+  /** Computes the sampling timestamp for an epoch's committee data. */
+  private getSamplingTimestamp(epoch: EpochNumber): bigint {
+    const { lagInEpochsForRandao, epochDuration, slotDuration } = this.l1constants;
+    const epochStartTs = getStartTimestampForEpoch(epoch, this.l1constants);
+    return epochStartTs - BigInt(lagInEpochsForRandao) * BigInt(epochDuration) * BigInt(slotDuration);
+  }
+
+  /**
+   * Lightweight refresh for a stale non-finalized entry. Queries only the block hash at
+   * the original block number and the finalized block timestamp — avoids the expensive
+   * getCommitteeAt and getSampleSeedAt calls on the rollup contract.
+   *
+   * If the block hash still matches (no L1 reorg), we keep the existing data and just
+   * update the provenance timestamp. If the finalized block has caught up, we promote the
+   * entry to finalized. If there was a reorg (hash mismatch), we fall back to a full fetch.
+   */
+  private async refreshStaleEntry(stale: CachedEpochEntry, epoch: EpochNumber, ts: bigint): Promise<CachedEpochEntry> {
+    const [blockAtOriginal, l1FinalizedBlock, latestBlock] = await Promise.all([
+      this.rollup.client.getBlock({ blockNumber: stale.lastQueryL1BlockNumber, includeTransactions: false }),
+      getFinalizedL1Block(this.rollup.client),
+      this.rollup.client.getBlock({ includeTransactions: false }),
+    ]);
+
+    if (blockAtOriginal.hash === stale.lastQueryL1BlockHash) {
+      // No reorg: the data is still valid. Check if we can now mark it as finalized.
+      const samplingTs = this.getSamplingTimestamp(epoch);
+      const finalized =
+        !!(stale.data.committee && stale.data.committee.length > 0) &&
+        l1FinalizedBlock !== undefined &&
+        samplingTs <= l1FinalizedBlock.timestamp;
+
+      const refreshed: CachedEpochEntry = {
+        ...stale,
+        lastRefreshL1Timestamp: latestBlock.timestamp,
+        finalized,
+      };
+      this.cache.set(epoch, refreshed);
+      return refreshed;
+    }
+
+    // Reorg detected: block hash mismatch. Do a full re-fetch.
+    // Pass the already-fetched block timestamps to avoid redundant queries.
+    this.log.warn(`L1 reorg detected for epoch ${epoch}: block ${stale.lastQueryL1BlockNumber} hash changed`, {
+      epoch,
+      expectedHash: stale.lastQueryL1BlockHash,
+      actualHash: blockAtOriginal.hash,
+    });
+    return this.fetchAndCache(epoch, ts, { latestBlock, finalizedBlock: l1FinalizedBlock });
+  }
+
+  /**
+   * Fetches committee data from L1, determines finalization status, and stores in the cache.
+   *
+   * Uses `lagInEpochsForRandao` (the binding constraint, always <= lagInEpochsForValidatorSet)
+   * and computes the sampling timestamp from the epoch start to match the L1 contract's logic.
+   *
+   * When called from refreshStaleEntry after a reorg, the latest and finalized blocks are
+   * passed in to avoid redundant L1 queries.
+   */
+  private async fetchAndCache(
+    epoch: EpochNumber,
+    ts: bigint,
+    prefetched?: { latestBlock: L1BlockInfo; finalizedBlock: { timestamp: bigint } | undefined },
+  ): Promise<CachedEpochEntry> {
+    const [committee, seedBuffer, latestBlock, finalizedBlock, isEscapeHatchOpen] = await Promise.all([
       this.rollup.getCommitteeAt(ts),
       this.rollup.getSampleSeedAt(ts),
-      this.rollup.client.getBlock({ includeTransactions: false }).then(b => b.timestamp),
+      prefetched?.latestBlock ?? this.rollup.client.getBlock({ includeTransactions: false }),
+      prefetched !== undefined ? prefetched.finalizedBlock : getFinalizedL1Block(this.rollup.client),
       this.rollup.isEscapeHatchOpen(epoch),
     ]);
-    const { lagInEpochsForValidatorSet, epochDuration, slotDuration } = this.l1constants;
-    const sub = BigInt(lagInEpochsForValidatorSet) * BigInt(epochDuration) * BigInt(slotDuration);
-    if (ts - sub > l1Timestamp) {
+
+    const samplingTs = this.getSamplingTimestamp(epoch);
+
+    if (samplingTs > latestBlock.timestamp) {
       throw new Error(
-        `Cannot query committee for future epoch ${epoch} with timestamp ${ts} (current L1 time is ${l1Timestamp}). Check your Ethereum node is synced.`,
+        `Cannot query committee for future epoch ${epoch}: ` +
+          `sampling timestamp ${samplingTs} is beyond latest L1 block at ${latestBlock.timestamp}. ` +
+          `Check your Ethereum node is synced.`,
       );
     }
-    return { committee, seed: seedBuffer.toBigInt(), epoch, isEscapeHatchOpen };
+
+    // Empty committees are never marked finalized so they always get re-queried after TTL.
+    // If L1 has no finalized block yet (devnet startup), entries stay unfinalized.
+    const hasCommittee = !!(committee && committee.length > 0);
+    const finalized = hasCommittee && finalizedBlock !== undefined && samplingTs <= finalizedBlock.timestamp;
+    const data: EpochCommitteeInfo = { committee, seed: seedBuffer.toBigInt(), epoch, isEscapeHatchOpen };
+    const entry: CachedEpochEntry = {
+      data,
+      lastQueryL1BlockNumber: latestBlock.number!,
+      lastQueryL1BlockHash: latestBlock.hash!,
+      lastRefreshL1Timestamp: latestBlock.timestamp,
+      finalized,
+    };
+
+    this.cache.set(epoch, entry);
+    this.purgeCache();
+
+    return entry;
   }
 
   /**
@@ -351,15 +484,18 @@ export class EpochCache implements EpochCacheInterface {
     };
   }
 
-  /** Returns the taget and next L2 slot in the next L1 slot */
+  /** Returns the target and next L2 slot in the next L1 slot. */
   public getTargetAndNextSlot(): { targetSlot: SlotNumber; nextSlot: SlotNumber } {
-    const targetSlot = this.getTargetSlot();
-    const next = this.getTargetEpochAndSlotInNextL1Slot();
+    const nowSeconds = BigInt(this.dateProvider.nowInSeconds());
+    const offset = PROPOSER_PIPELINING_SLOT_OFFSET;
 
-    return {
-      targetSlot,
-      nextSlot: next.slot,
-    };
+    const currentSlot = getSlotAtTimestamp(nowSeconds, this.l1constants);
+    const targetSlot = SlotNumber(currentSlot + offset);
+
+    const nextL2SlotOnL1 = getSlotAtNextL1Block(nowSeconds, this.l1constants);
+    const nextSlot = SlotNumber(nextL2SlotOnL1 + offset);
+
+    return { targetSlot, nextSlot };
   }
 
   /**
@@ -440,10 +576,11 @@ export class EpochCache implements EpochCacheInterface {
   async getRegisteredValidators(): Promise<EthAddress[]> {
     const validatorRefreshIntervalMs = this.config.validatorRefreshIntervalSeconds * 1000;
     const validatorRefreshTime = this.lastValidatorRefresh + validatorRefreshIntervalMs;
-    if (validatorRefreshTime < this.dateProvider.now()) {
-      const currentSet = await this.rollup.getAttesters();
+    const now = this.dateProvider.now();
+    if (validatorRefreshTime < now) {
+      const currentSet = await this.rollup.getAttesters(BigInt(Math.floor(now / 1000)));
       this.allValidators = new Set(currentSet.map(v => v.toString()));
-      this.lastValidatorRefresh = this.dateProvider.now();
+      this.lastValidatorRefresh = now;
     }
     return Array.from(this.allValidators.keys()).map(v => EthAddress.fromString(v));
   }

package/src/test/test_epoch_cache.ts

@@ -1,7 +1,12 @@
 import { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
-import { getEpochAtSlot, getSlotAtTimestamp, getTimestampRangeForEpoch } from '@aztec/stdlib/epoch-helpers';
+import {
+  getEpochAtSlot,
+  getSlotAtTimestamp,
+  getTimestampForSlot,
+  getTimestampRangeForEpoch,
+} from '@aztec/stdlib/epoch-helpers';
 
 import {
   type EpochAndSlot,
@@ -38,7 +43,6 @@ export class TestEpochCache implements EpochCacheInterface {
   private seed: bigint = 0n;
   private registeredValidators: EthAddress[] = [];
   private l1Constants: L1RollupConstants;
-  private proposerPipeliningEnabled = false;
 
   constructor(l1Constants: Partial<L1RollupConstants> = {}) {
     this.l1Constants = { ...DEFAULT_L1_CONSTANTS, ...l1Constants };
@@ -111,10 +115,6 @@ export class TestEpochCache implements EpochCacheInterface {
     return this.l1Constants;
   }
 
-  setProposerPipeliningEnabled(enabled: boolean): void {
-    this.proposerPipeliningEnabled = enabled;
-  }
-
   getCommittee(_slot?: SlotTag): Promise<EpochCommitteeInfo> {
     const epoch = getEpochAtSlot(this.currentSlot, this.l1Constants);
     return Promise.resolve({
@@ -130,9 +130,7 @@ export class TestEpochCache implements EpochCacheInterface {
   }
 
   getTargetSlot(): SlotNumber {
-    return this.proposerPipeliningEnabled
-      ? SlotNumber(this.currentSlot + PROPOSER_PIPELINING_SLOT_OFFSET)
-      : this.currentSlot;
+    return SlotNumber(this.currentSlot + PROPOSER_PIPELINING_SLOT_OFFSET);
   }
 
   getEpochNow(): EpochNumber {
@@ -143,13 +141,12 @@ export class TestEpochCache implements EpochCacheInterface {
     return getEpochAtSlot(this.getTargetSlot(), this.l1Constants);
   }
 
-  isProposerPipeliningEnabled(): boolean {
-    return this.proposerPipeliningEnabled;
-  }
-
   getEpochAndSlotNow(): EpochAndSlot & { nowMs: bigint } {
+    // Model "now" as the start of the current slot (mirroring the real EpochCache, which derives nowMs
+    // from the wall clock). Using the slot start rather than the epoch start keeps nowMs consistent with
+    // currentSlot, which the pipelining receive-window check (clock_tolerance) relies on.
     const epochNow = getEpochAtSlot(this.currentSlot, this.l1Constants);
-    const ts = getTimestampRangeForEpoch(epochNow, this.l1Constants)[0];
+    const ts = getTimestampForSlot(this.currentSlot, this.l1Constants);
     return {
       epoch: epochNow,
       slot: this.currentSlot,
@@ -174,7 +171,7 @@ export class TestEpochCache implements EpochCacheInterface {
 
   getTargetEpochAndSlotInNextL1Slot(): EpochAndSlot & { nowSeconds: bigint } {
     const result = this.getEpochAndSlotInNextL1Slot();
-    const offset = this.isProposerPipeliningEnabled() ? PROPOSER_PIPELINING_SLOT_OFFSET : 0;
+    const offset = PROPOSER_PIPELINING_SLOT_OFFSET;
     const targetSlot = SlotNumber(result.slot + offset);
     return { ...result, slot: targetSlot, epoch: getEpochAtSlot(targetSlot, this.l1Constants) };
   }