@aztec/epoch-cache 0.0.0-test.1 → 0.0.1-commit.017a351

package/dest/epoch_cache.js

@@ -1,105 +1,331 @@
-import { RollupContract, createEthereumChain } from '@aztec/ethereum';
+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 { SlotNumber } from '@aztec/foundation/branded-types';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { createLogger } from '@aztec/foundation/log';
 import { DateProvider } from '@aztec/foundation/timer';
-import { EmptyL1RollupConstants, getEpochNumberAtTimestamp, getSlotAtTimestamp } from '@aztec/stdlib/epoch-helpers';
-import { EventEmitter } from 'node:events';
-import { createPublicClient, encodeAbiParameters, fallback, http, keccak256 } from 'viem';
+import { getEpochAtSlot, getEpochNumberAtTimestamp, getNextL1SlotTimestamp, getSlotAtNextL1Block, getSlotAtTimestamp, getSlotRangeForEpoch, getStartTimestampForEpoch, getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
+import { createPublicClient, encodeAbiParameters, keccak256 } from 'viem';
 import { getEpochCacheConfigEnvVars } from './config.js';
+/** The proposer pipelines by building one slot ahead. */ export const PROPOSER_PIPELINING_SLOT_OFFSET = 1;
 /**
  * Epoch cache
  *
  * This class is responsible for managing traffic to the l1 node, by caching the validator set.
+ * Keeps the last N epochs in cache.
  * It also provides a method to get the current or next proposer, and to check who is in the current slot.
  *
- * If the epoch changes, then we update the stored validator set.
- *
  * Note: This class is very dependent on the system clock being in sync.
- */ export class EpochCache extends EventEmitter {
+ */ export class EpochCache {
     rollup;
     l1constants;
     dateProvider;
-    committee;
-    cachedEpoch;
-    cachedSampleSeed;
+    config;
+    /**
+   * Single map holding both resolved entries and in-flight promises.
+   * A `Promise` value means a fetch is in progress; concurrent callers await it.
+   */ cache;
+    allValidators;
+    lastValidatorRefresh;
     log;
-    constructor(rollup, initialValidators = [], initialSampleSeed = 0n, l1constants = EmptyL1RollupConstants, dateProvider = new DateProvider()){
-        super(), this.rollup = rollup, this.l1constants = l1constants, this.dateProvider = dateProvider, this.log = createLogger('epoch-cache');
-        this.committee = initialValidators;
-        this.cachedSampleSeed = initialSampleSeed;
-        this.log.debug(`Initialized EpochCache with constants and validators`, {
-            l1constants,
-            initialValidators
+    constructor(rollup, l1constants, dateProvider = new DateProvider(), config = {
+        cacheSize: 12,
+        validatorRefreshIntervalSeconds: 60
+    }){
+        this.rollup = rollup;
+        this.l1constants = l1constants;
+        this.dateProvider = dateProvider;
+        this.config = config;
+        this.cache = new Map();
+        this.allValidators = new Set();
+        this.lastValidatorRefresh = 0;
+        this.log = createLogger('epoch-cache');
+        this.log.debug(`Initialized EpochCache`, {
+            l1constants
         });
-        this.cachedEpoch = getEpochNumberAtTimestamp(this.nowInSeconds(), this.l1constants);
     }
-    static async create(rollupAddress, config, deps = {}) {
+    static async create(rollupOrAddress, config, deps = {}) {
         config = config ?? getEpochCacheConfigEnvVars();
-        const chain = createEthereumChain(config.l1RpcUrls, config.l1ChainId);
-        const publicClient = createPublicClient({
-            chain: chain.chainInfo,
-            transport: fallback(config.l1RpcUrls.map((url)=>http(url))),
-            pollingInterval: config.viemPollingIntervalMS
-        });
-        const rollup = new RollupContract(publicClient, rollupAddress.toString());
-        const [l1StartBlock, l1GenesisTime, initialValidators, sampleSeed] = await Promise.all([
+        // Load the rollup contract if we were given an address
+        let rollup;
+        if ('address' in rollupOrAddress) {
+            rollup = rollupOrAddress;
+        } else {
+            const chain = createEthereumChain(config.l1RpcUrls, config.l1ChainId);
+            const publicClient = createPublicClient({
+                chain: chain.chainInfo,
+                transport: makeL1HttpTransport(config.l1RpcUrls, {
+                    timeout: config.l1HttpTimeoutMS
+                }),
+                pollingInterval: config.viemPollingIntervalMS
+            });
+            rollup = new RollupContract(publicClient, rollupOrAddress.toString());
+        }
+        const [l1StartBlock, l1GenesisTime, proofSubmissionEpochs, slotDuration, epochDuration, lagInEpochsForValidatorSet, lagInEpochsForRandao, targetCommitteeSize, rollupManaLimit] = await Promise.all([
             rollup.getL1StartBlock(),
             rollup.getL1GenesisTime(),
-            rollup.getCurrentEpochCommittee(),
-            rollup.getCurrentSampleSeed()
+            rollup.getProofSubmissionEpochs(),
+            rollup.getSlotDuration(),
+            rollup.getEpochDuration(),
+            rollup.getLagInEpochsForValidatorSet(),
+            rollup.getLagInEpochsForRandao(),
+            rollup.getTargetCommitteeSize(),
+            rollup.getManaLimit()
         ]);
         const l1RollupConstants = {
             l1StartBlock,
             l1GenesisTime,
-            slotDuration: config.aztecSlotDuration,
-            epochDuration: config.aztecEpochDuration,
-            ethereumSlotDuration: config.ethereumSlotDuration
+            proofSubmissionEpochs: Number(proofSubmissionEpochs),
+            slotDuration: Number(slotDuration),
+            epochDuration: Number(epochDuration),
+            ethereumSlotDuration: config.ethereumSlotDuration,
+            lagInEpochsForValidatorSet: Number(lagInEpochsForValidatorSet),
+            lagInEpochsForRandao: Number(lagInEpochsForRandao),
+            targetCommitteeSize: Number(targetCommitteeSize),
+            rollupManaLimit: Number(rollupManaLimit)
         };
-        return new EpochCache(rollup, initialValidators.map((v)=>EthAddress.fromString(v)), sampleSeed, l1RollupConstants, deps.dateProvider);
+        return new EpochCache(rollup, l1RollupConstants, deps.dateProvider, {
+            cacheSize: 12,
+            validatorRefreshIntervalSeconds: 60
+        });
+    }
+    getL1Constants() {
+        return this.l1constants;
+    }
+    getSlotNow() {
+        return this.getEpochAndSlotNow().slot;
+    }
+    getTargetSlot() {
+        const slotNow = this.getSlotNow();
+        const offset = PROPOSER_PIPELINING_SLOT_OFFSET;
+        return SlotNumber(slotNow + offset);
+    }
+    getEpochNow() {
+        return this.getEpochAndSlotNow().epoch;
     }
-    nowInSeconds() {
-        return BigInt(Math.floor(this.dateProvider.now() / 1000));
+    getTargetEpoch() {
+        return getEpochAtSlot(this.getTargetSlot(), this.l1constants);
     }
     getEpochAndSlotNow() {
-        return this.getEpochAndSlotAtTimestamp(this.nowInSeconds());
+        const nowMs = BigInt(this.dateProvider.now());
+        const nowSeconds = nowMs / 1000n;
+        return {
+            ...this.getEpochAndSlotAtTimestamp(nowSeconds),
+            nowMs
+        };
+    }
+    getEpochAndSlotAtSlot(slot) {
+        return this.getEpochAndSlotAtTimestamp(getTimestampForSlot(slot, this.l1constants));
+    }
+    getEpochAndSlotInNextL1Slot() {
+        const nowSeconds = this.dateProvider.nowInSeconds();
+        const nextSlotTs = getNextL1SlotTimestamp(nowSeconds, this.l1constants);
+        return {
+            ...this.getEpochAndSlotAtTimestamp(nextSlotTs),
+            nowSeconds: BigInt(nowSeconds)
+        };
     }
-    getEpochAndSlotInNextSlot() {
-        const nextSlotTs = this.nowInSeconds() + BigInt(this.l1constants.slotDuration);
-        return this.getEpochAndSlotAtTimestamp(nextSlotTs);
+    getTargetEpochAndSlotInNextL1Slot() {
+        const result = this.getEpochAndSlotInNextL1Slot();
+        const offset = PROPOSER_PIPELINING_SLOT_OFFSET;
+        const targetSlot = SlotNumber(result.slot + offset);
+        return {
+            ...result,
+            slot: targetSlot,
+            epoch: getEpochAtSlot(targetSlot, this.l1constants)
+        };
     }
     getEpochAndSlotAtTimestamp(ts) {
+        const slot = getSlotAtTimestamp(ts, this.l1constants);
+        const epoch = getEpochNumberAtTimestamp(ts, this.l1constants);
         return {
-            epoch: getEpochNumberAtTimestamp(ts, this.l1constants),
-            slot: getSlotAtTimestamp(ts, this.l1constants),
-            ts
+            slot,
+            epoch,
+            ts: getTimestampForSlot(slot, this.l1constants)
         };
     }
+    getCommitteeForEpoch(epoch) {
+        const [startSlot] = getSlotRangeForEpoch(epoch, this.l1constants);
+        return this.getCommittee(startSlot);
+    }
+    /** Returns whether the escape hatch is open for the given epoch. */ async isEscapeHatchOpen(epoch) {
+        const info = await this.getCommitteeForEpoch(epoch);
+        return info.isEscapeHatchOpen;
+    }
     /**
-   * Get the current validator set
+   * Returns whether the escape hatch is open for the epoch containing the given slot.
    *
-   * @param nextSlot - If true, get the validator set for the next slot.
-   * @returns The current validator set.
-   */ async getCommittee(nextSlot = false) {
-        // If the current epoch has changed, then we need to make a request to update the validator set
-        const { epoch: calculatedEpoch, ts } = nextSlot ? this.getEpochAndSlotInNextSlot() : this.getEpochAndSlotNow();
-        if (calculatedEpoch !== this.cachedEpoch) {
-            this.log.debug(`Updating validator set for new epoch ${calculatedEpoch}`, {
-                epoch: calculatedEpoch,
-                previousEpoch: this.cachedEpoch
-            });
-            const [committeeAtTs, sampleSeedAtTs] = await Promise.all([
-                this.rollup.getCommitteeAt(ts),
-                this.rollup.getSampleSeedAt(ts)
-            ]);
-            this.committee = committeeAtTs.map((v)=>EthAddress.fromString(v));
-            this.cachedEpoch = calculatedEpoch;
-            this.cachedSampleSeed = sampleSeedAtTs;
-            this.log.debug(`Updated validator set for epoch ${calculatedEpoch}`, {
-                commitee: this.committee
-            });
-            this.emit('committeeChanged', this.committee, calculatedEpoch);
+   * This is a lightweight helper intended for callers that already have a slot number and only
+   * need the escape hatch flag (without pulling full committee info).
+   */ async isEscapeHatchOpenAtSlot(slot = 'now') {
+        const epoch = slot === 'now' ? this.getEpochNow() : slot === 'next' ? this.getEpochAndSlotInNextL1Slot().epoch : getEpochAtSlot(slot, this.l1constants);
+        return await this.isEscapeHatchOpen(epoch);
+    }
+    /**
+   * 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.
+   */ async getCommittee(slot = 'now') {
+        const { epoch, ts } = this.getEpochAndTimestamp(slot);
+        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;
+        }
+        // Resolved entry: return it if finalized or still fresh.
+        if (cached && (cached.finalized || !this.isStale(cached))) {
+            return cached.data;
+        }
+        // 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;
+            }
+        }
+        // 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;
+        }
+    }
+    getEpochAndTimestamp(slot = 'now') {
+        if (slot === 'now') {
+            return this.getEpochAndSlotNow();
+        } else if (slot === 'next') {
+            return this.getEpochAndSlotInNextL1Slot();
+        } else {
+            return this.getEpochAndSlotAtSlot(slot);
+        }
+    }
+    /** Evicts oldest cache entries (resolved or in-flight) beyond cacheSize. */ purgeCache() {
+        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. */ isStale(entry) {
+        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. */ isFinalized(epoch) {
+        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. */ getCachedLastRefreshL1Timestamp(epoch) {
+        const entry = this.cache.get(epoch);
+        if (!entry || entry instanceof Promise) {
+            return undefined;
         }
-        return this.committee;
+        return entry.lastRefreshL1Timestamp;
+    }
+    /** Computes the sampling timestamp for an epoch's committee data. */ getSamplingTimestamp(epoch) {
+        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.
+   */ async refreshStaleEntry(stale, epoch, ts) {
+        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 = {
+                ...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.
+   */ async fetchAndCache(epoch, ts, prefetched) {
+        const [committee, seedBuffer, latestBlock, finalizedBlock, isEscapeHatchOpen] = await Promise.all([
+            this.rollup.getCommitteeAt(ts),
+            this.rollup.getSampleSeedAt(ts),
+            prefetched?.latestBlock ?? this.rollup.client.getBlock({
+                includeTransactions: false
+            }),
+            prefetched !== undefined ? prefetched.finalizedBlock : getFinalizedL1Block(this.rollup.client),
+            this.rollup.isEscapeHatchOpen(epoch)
+        ]);
+        const samplingTs = this.getSamplingTimestamp(epoch);
+        if (samplingTs > latestBlock.timestamp) {
+            throw new Error(`Cannot query committee for future epoch ${epoch}: ` + `sampling timestamp ${samplingTs} is beyond latest L1 block at ${latestBlock.timestamp}. ` + `Check your Ethereum node is synced.`);
+        }
+        // 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 = {
+            committee,
+            seed: seedBuffer.toBigInt(),
+            epoch,
+            isEscapeHatchOpen
+        };
+        const entry = {
+            data,
+            lastQueryL1BlockNumber: latestBlock.number,
+            lastQueryL1BlockHash: latestBlock.hash,
+            lastRefreshL1Timestamp: latestBlock.timestamp,
+            finalized
+        };
+        this.cache.set(epoch, entry);
+        this.purgeCache();
+        return entry;
     }
     /**
    * Get the ABI encoding of the proposer index - see ValidatorSelectionLib.sol computeProposerIndex
@@ -118,47 +344,101 @@ import { getEpochCacheConfigEnvVars } from './config.js';
                 name: 'seed'
             }
         ], [
-            epoch,
-            slot,
+            BigInt(epoch),
+            BigInt(slot),
             seed
         ]);
     }
     computeProposerIndex(slot, epoch, seed, size) {
+        // if committe size is 0, then mod 1 is 0
+        if (size === 0n) {
+            return 0n;
+        }
         return BigInt(keccak256(this.getProposerIndexEncoding(epoch, slot, seed))) % size;
     }
-    /**
-   * Returns the current and next proposer
-   *
-   * We return the next proposer as the node will check if it is the proposer at the next ethereum block, which
-   * can be the next slot. If this is the case, then it will send proposals early.
-   *
-   * If we are at an epoch boundary, then we can update the cache for the next epoch, this is the last check
-   * we do in the validator client, so we can update the cache here.
-   */ async getProposerInCurrentOrNextSlot() {
-        // Validators are sorted by their index in the committee, and getValidatorSet will cache
-        const committee = await this.getCommittee();
-        const { slot: currentSlot, epoch: currentEpoch } = this.getEpochAndSlotNow();
-        const { slot: nextSlot, epoch: nextEpoch } = this.getEpochAndSlotInNextSlot();
-        // Compute the proposer in this and the next slot
-        const proposerIndex = this.computeProposerIndex(currentSlot, this.cachedEpoch, this.cachedSampleSeed, BigInt(committee.length));
-        // Check if the next proposer is in the next epoch
-        if (nextEpoch !== currentEpoch) {
-            await this.getCommittee(/*next slot*/ true);
-        }
-        const nextProposerIndex = this.computeProposerIndex(nextSlot, this.cachedEpoch, this.cachedSampleSeed, BigInt(committee.length));
-        const currentProposer = committee[Number(proposerIndex)];
-        const nextProposer = committee[Number(nextProposerIndex)];
+    /** Returns the current and next L2 slot in next eth L1 Slot. */ getCurrentAndNextSlot() {
+        const currentSlot = this.getSlotNow();
+        const next = this.getEpochAndSlotInNextL1Slot();
         return {
-            currentProposer,
-            nextProposer,
             currentSlot,
+            nextSlot: next.slot
+        };
+    }
+    /** Returns the target and next L2 slot in the next L1 slot. */ getTargetAndNextSlot() {
+        const nowSeconds = BigInt(this.dateProvider.nowInSeconds());
+        const offset = PROPOSER_PIPELINING_SLOT_OFFSET;
+        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
         };
     }
     /**
-   * Check if a validator is in the current epoch's committee
-   */ async isInCommittee(validator) {
-        const committee = await this.getCommittee();
+   * Get the proposer attester address in the given L2 slot
+   * @returns The proposer attester address. If the committee does not exist, we throw a NoCommitteeError.
+   * If the committee is empty (i.e. target committee size is 0, and anyone can propose), we return undefined.
+   */ getProposerAttesterAddressInSlot(slot) {
+        const epochAndSlot = this.getEpochAndSlotAtSlot(slot);
+        return this.getProposerAttesterAddressAt(epochAndSlot);
+    }
+    /**
+   * Get the proposer attester address in the next slot
+   * @returns The proposer attester address. If the committee does not exist, we throw a NoCommitteeError.
+   * If the committee is empty (i.e. target committee size is 0, and anyone can propose), we return undefined.
+   */ getProposerAttesterAddressInNextSlot() {
+        const epochAndSlot = this.getEpochAndSlotInNextL1Slot();
+        return this.getProposerAttesterAddressAt(epochAndSlot);
+    }
+    /**
+   * Get the proposer attester address at a given epoch and slot
+   * @param when - The epoch and slot to get the proposer attester address at
+   * @returns The proposer attester address. If the committee does not exist, we throw a NoCommitteeError.
+   * If the committee is empty (i.e. target committee size is 0, and anyone can propose), we return undefined.
+   */ async getProposerAttesterAddressAt(when) {
+        const { epoch, slot } = when;
+        const { committee, seed } = await this.getCommittee(slot);
+        if (!committee) {
+            throw new NoCommitteeError();
+        } else if (committee.length === 0) {
+            return undefined;
+        }
+        const proposerIndex = this.computeProposerIndex(slot, epoch, seed, BigInt(committee.length));
+        return committee[Number(proposerIndex)];
+    }
+    getProposerFromEpochCommittee(epochCommitteeInfo, slot) {
+        if (!epochCommitteeInfo.committee || epochCommitteeInfo.committee.length === 0) {
+            return undefined;
+        }
+        const proposerIndex = this.computeProposerIndex(slot, epochCommitteeInfo.epoch, epochCommitteeInfo.seed, BigInt(epochCommitteeInfo.committee.length));
+        return epochCommitteeInfo.committee[Number(proposerIndex)];
+    }
+    /** Check if a validator is in the given slot's committee */ async isInCommittee(slot, validator) {
+        const { committee } = await this.getCommittee(slot);
+        if (!committee) {
+            return false;
+        }
         return committee.some((v)=>v.equals(validator));
     }
+    /** From the set of given addresses, return all that are on the committee for the given slot */ async filterInCommittee(slot, validators) {
+        const { committee } = await this.getCommittee(slot);
+        if (!committee) {
+            return [];
+        }
+        const committeeSet = new Set(committee.map((v)=>v.toString()));
+        return validators.filter((v)=>committeeSet.has(v.toString()));
+    }
+    async getRegisteredValidators() {
+        const validatorRefreshIntervalMs = this.config.validatorRefreshIntervalSeconds * 1000;
+        const validatorRefreshTime = this.lastValidatorRefresh + validatorRefreshIntervalMs;
+        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 = now;
+        }
+        return Array.from(this.allValidators.keys()).map((v)=>EthAddress.fromString(v));
+    }
 }

package/dest/index.d.ts

@@ -1,3 +1,3 @@
 export * from './epoch_cache.js';
 export * from './config.js';
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsYUFBYSxDQUFDIn0=

package/dest/test/index.d.ts

@@ -0,0 +1,2 @@
+export * from './test_epoch_cache.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy90ZXN0L2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsdUJBQXVCLENBQUMifQ==

package/dest/test/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dest/test/index.js

@@ -0,0 +1 @@
+export * from './test_epoch_cache.js';

package/dest/test/test_epoch_cache.d.ts

@@ -0,0 +1,88 @@
+import { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { L1RollupConstants } from '@aztec/stdlib/epoch-helpers';
+import { type EpochAndSlot, type EpochCacheInterface, type EpochCommitteeInfo, type SlotTag } from '../epoch_cache.js';
+/**
+ * A test implementation of EpochCacheInterface that allows manual configuration
+ * of committee, proposer, slot, and escape hatch state for use in tests.
+ *
+ * Unlike the real EpochCache, this class doesn't require any RPC connections
+ * or mock setup. Simply use the setter methods to configure the test state.
+ */
+export declare class TestEpochCache implements EpochCacheInterface {
+    private committee;
+    private proposerAddress;
+    private currentSlot;
+    private escapeHatchOpen;
+    private seed;
+    private registeredValidators;
+    private l1Constants;
+    constructor(l1Constants?: Partial<L1RollupConstants>);
+    /**
+     * Sets the committee members. Used in validation and attestation flows.
+     * @param committee - Array of committee member addresses.
+     */
+    setCommittee(committee: EthAddress[]): this;
+    /**
+     * Sets the proposer address returned by getProposerAttesterAddressInSlot.
+     * @param proposer - The address of the current proposer.
+     */
+    setProposer(proposer: EthAddress | undefined): this;
+    /**
+     * Sets the current slot number.
+     * @param slot - The slot number to set.
+     */
+    setCurrentSlot(slot: SlotNumber): this;
+    /**
+     * Sets whether the escape hatch is open.
+     * @param open - True if escape hatch should be open.
+     */
+    setEscapeHatchOpen(open: boolean): this;
+    /**
+     * Sets the randomness seed used for proposer selection.
+     * @param seed - The seed value.
+     */
+    setSeed(seed: bigint): this;
+    /**
+     * Sets the list of registered validators (all validators, not just committee).
+     * @param validators - Array of validator addresses.
+     */
+    setRegisteredValidators(validators: EthAddress[]): this;
+    /**
+     * Sets the L1 constants used for epoch/slot calculations.
+     * @param constants - Partial constants to override defaults.
+     */
+    setL1Constants(constants: Partial<L1RollupConstants>): this;
+    getL1Constants(): L1RollupConstants;
+    getCommittee(_slot?: SlotTag): Promise<EpochCommitteeInfo>;
+    getSlotNow(): SlotNumber;
+    getTargetSlot(): SlotNumber;
+    getEpochNow(): EpochNumber;
+    getTargetEpoch(): EpochNumber;
+    getEpochAndSlotNow(): EpochAndSlot & {
+        nowMs: bigint;
+    };
+    getEpochAndSlotInNextL1Slot(): EpochAndSlot & {
+        nowSeconds: bigint;
+    };
+    getTargetEpochAndSlotInNextL1Slot(): EpochAndSlot & {
+        nowSeconds: bigint;
+    };
+    getProposerIndexEncoding(epoch: EpochNumber, slot: SlotNumber, seed: bigint): `0x${string}`;
+    computeProposerIndex(slot: SlotNumber, _epoch: EpochNumber, _seed: bigint, size: bigint): bigint;
+    getCurrentAndNextSlot(): {
+        currentSlot: SlotNumber;
+        nextSlot: SlotNumber;
+    };
+    getTargetAndNextSlot(): {
+        targetSlot: SlotNumber;
+        nextSlot: SlotNumber;
+    };
+    getProposerAttesterAddressInSlot(_slot: SlotNumber): Promise<EthAddress | undefined>;
+    getRegisteredValidators(): Promise<EthAddress[]>;
+    isInCommittee(_slot: SlotTag, validator: EthAddress): Promise<boolean>;
+    filterInCommittee(_slot: SlotTag, validators: EthAddress[]): Promise<EthAddress[]>;
+    isEscapeHatchOpen(_epoch: EpochNumber): Promise<boolean>;
+    isEscapeHatchOpenAtSlot(_slot?: SlotTag): Promise<boolean>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGVzdF9lcG9jaF9jYWNoZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3Rlc3QvdGVzdF9lcG9jaF9jYWNoZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsV0FBVyxFQUFFLFVBQVUsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBQzFFLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSwrQkFBK0IsQ0FBQztBQUMzRCxPQUFPLEtBQUssRUFBRSxpQkFBaUIsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBR3JFLE9BQU8sRUFDTCxLQUFLLFlBQVksRUFDakIsS0FBSyxtQkFBbUIsRUFDeEIsS0FBSyxrQkFBa0IsRUFFdkIsS0FBSyxPQUFPLEVBQ2IsTUFBTSxtQkFBbUIsQ0FBQztBQWMzQjs7Ozs7O0dBTUc7QUFDSCxxQkFBYSxjQUFlLFlBQVcsbUJBQW1CO0lBQ3hELE9BQU8sQ0FBQyxTQUFTLENBQW9CO0lBQ3JDLE9BQU8sQ0FBQyxlQUFlLENBQXlCO0lBQ2hELE9BQU8sQ0FBQyxXQUFXLENBQTZCO0lBQ2hELE9BQU8sQ0FBQyxlQUFlLENBQWtCO0lBQ3pDLE9BQU8sQ0FBQyxJQUFJLENBQWM7SUFDMUIsT0FBTyxDQUFDLG9CQUFvQixDQUFvQjtJQUNoRCxPQUFPLENBQUMsV0FBVyxDQUFvQjtJQUV2QyxZQUFZLFdBQVcsR0FBRSxPQUFPLENBQUMsaUJBQWlCLENBQU0sRUFFdkQ7SUFFRDs7O09BR0c7SUFDSCxZQUFZLENBQUMsU0FBUyxFQUFFLFVBQVUsRUFBRSxHQUFHLElBQUksQ0FHMUM7SUFFRDs7O09BR0c7SUFDSCxXQUFXLENBQUMsUUFBUSxFQUFFLFVBQVUsR0FBRyxTQUFTLEdBQUcsSUFBSSxDQUdsRDtJQUVEOzs7T0FHRztJQUNILGNBQWMsQ0FBQyxJQUFJLEVBQUUsVUFBVSxHQUFHLElBQUksQ0FHckM7SUFFRDs7O09BR0c7SUFDSCxrQkFBa0IsQ0FBQyxJQUFJLEVBQUUsT0FBTyxHQUFHLElBQUksQ0FHdEM7SUFFRDs7O09BR0c7SUFDSCxPQUFPLENBQUMsSUFBSSxFQUFFLE1BQU0sR0FBRyxJQUFJLENBRzFCO0lBRUQ7OztPQUdHO0lBQ0gsdUJBQXVCLENBQUMsVUFBVSxFQUFFLFVBQVUsRUFBRSxHQUFHLElBQUksQ0FHdEQ7SUFFRDs7O09BR0c7SUFDSCxjQUFjLENBQUMsU0FBUyxFQUFFLE9BQU8sQ0FBQyxpQkFBaUIsQ0FBQyxHQUFHLElBQUksQ0FHMUQ7SUFFRCxjQUFjLElBQUksaUJBQWlCLENBRWxDO0lBRUQsWUFBWSxDQUFDLEtBQUssQ0FBQyxFQUFFLE9BQU8sR0FBRyxPQUFPLENBQUMsa0JBQWtCLENBQUMsQ0FRekQ7SUFFRCxVQUFVLElBQUksVUFBVSxDQUV2QjtJQUVELGFBQWEsSUFBSSxVQUFVLENBRTFCO0lBRUQsV0FBVyxJQUFJLFdBQVcsQ0FFekI7SUFFRCxjQUFjLElBQUksV0FBVyxDQUU1QjtJQUVELGtCQUFrQixJQUFJLFlBQVksR0FBRztRQUFFLEtBQUssRUFBRSxNQUFNLENBQUE7S0FBRSxDQVNyRDtJQUVELDJCQUEyQixJQUFJLFlBQVksR0FBRztRQUFFLFVBQVUsRUFBRSxNQUFNLENBQUE7S0FBRSxDQVluRTtJQUVELGlDQUFpQyxJQUFJLFlBQVksR0FBRztRQUFFLFVBQVUsRUFBRSxNQUFNLENBQUE7S0FBRSxDQUt6RTtJQUVELHdCQUF3QixDQUFDLEtBQUssRUFBRSxXQUFXLEVBQUUsSUFBSSxFQUFFLFVBQVUsRUFBRSxJQUFJLEVBQUUsTUFBTSxHQUFHLEtBQUssTUFBTSxFQUFFLENBRzFGO0lBRUQsb0JBQW9CLENBQUMsSUFBSSxFQUFFLFVBQVUsRUFBRSxNQUFNLEVBQUUsV0FBVyxFQUFFLEtBQUssRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFLE1BQU0sR0FBRyxNQUFNLENBSy9GO0lBRUQscUJBQXFCLElBQUk7UUFBRSxXQUFXLEVBQUUsVUFBVSxDQUFDO1FBQUMsUUFBUSxFQUFFLFVBQVUsQ0FBQTtLQUFFLENBUXpFO0lBRUQsb0JBQW9CLElBQUk7UUFBRSxVQUFVLEVBQUUsVUFBVSxDQUFDO1FBQUMsUUFBUSxFQUFFLFVBQVUsQ0FBQTtLQUFFLENBUXZFO0lBRUQsZ0NBQWdDLENBQUMsS0FBSyxFQUFFLFVBQVUsR0FBRyxPQUFPLENBQUMsVUFBVSxHQUFHLFNBQVMsQ0FBQyxDQUVuRjtJQUVELHVCQUF1QixJQUFJLE9BQU8sQ0FBQyxVQUFVLEVBQUUsQ0FBQyxDQUUvQztJQUVELGFBQWEsQ0FBQyxLQUFLLEVBQUUsT0FBTyxFQUFFLFNBQVMsRUFBRSxVQUFVLEdBQUcsT0FBTyxDQUFDLE9BQU8sQ0FBQyxDQUVyRTtJQUVELGlCQUFpQixDQUFDLEtBQUssRUFBRSxPQUFPLEVBQUUsVUFBVSxFQUFFLFVBQVUsRUFBRSxHQUFHLE9BQU8sQ0FBQyxVQUFVLEVBQUUsQ0FBQyxDQUdqRjtJQUVELGlCQUFpQixDQUFDLE1BQU0sRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLE9BQU8sQ0FBQyxDQUV2RDtJQUVELHVCQUF1QixDQUFDLEtBQUssQ0FBQyxFQUFFLE9BQU8sR0FBRyxPQUFPLENBQUMsT0FBTyxDQUFDLENBRXpEO0NBQ0YifQ==

package/dest/test/test_epoch_cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test_epoch_cache.d.ts","sourceRoot":"","sources":["../../src/test/test_epoch_cache.ts"],"names":[],"mappings":"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"}