feat(ethereum): add mineUntilTimestamp to EthCheatCodes and use in rollup cheat codes

Adds mineUntilTimestamp which mines real L1 blocks (via hardhat_mine with
a timestamp interval) so finalized block timestamps advance alongside latest.
This prevents epoch-cache's finalized guard from rejecting committees after
time advances in tests.

The method derives the block interval from the last two block timestamps
(to handle anvil_setBlockTimestampInterval overrides), stops interval mining
before the burst, and leaves it stopped so the caller controls when to resume.

Updates rollup cheat codes (advanceToEpoch, advanceToNextEpoch, advanceToNextSlot,
advanceSlots) to use mineUntilTimestamp with automatic interval restore.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: spalladino

yarn-project/epoch-cache/src/epoch_cache.integration.test.ts

@@ -64,8 +64,13 @@ describe('EpochCache Integration', () => {
       bn254SecretKey: new SecretValue(Fr.random().toBigInt()),
     }));
 
+    // Use short L2 epochs (6 slots * 24s = 144s) so mineUntilTimestamp doesn't
+    // need to mine thousands of blocks. With ethereumSlotDuration=12 and
+    // aztecSlotDuration=24, advancing one L2 epoch needs ceil(144/12) = 12 L1 blocks.
     const deployed = await deployAztecL1Contracts(rpcUrl, deployerPrivateKey, foundry.id, {
       ...DefaultL1ContractsConfig,
+      aztecSlotDuration: 24,
+      aztecEpochDuration: 6,
       vkTreeRoot: Fr.random(),
       protocolContractsHash: Fr.random(),
       genesisArchiveRoot: Fr.random(),
@@ -74,7 +79,11 @@ describe('EpochCache Integration', () => {
       initialValidators,
     });
 
-    rollupCheatCodes = new RollupCheatCodes(cheatCodes, deployed.l1ContractAddresses);
+    rollupCheatCodes = new RollupCheatCodes(
+      cheatCodes,
+      deployed.l1ContractAddresses,
+      DefaultL1ContractsConfig.ethereumSlotDuration,
+    );
 
     const publicClient = getPublicClient({ l1RpcUrls: [rpcUrl], l1ChainId: foundry.id });
     rollup = new RollupContract(publicClient, deployed.l1ContractAddresses.rollupAddress.toString());
@@ -95,14 +104,17 @@ describe('EpochCache Integration', () => {
       // Advance past the validator set lag so the epoch's data is finalized.
       const lagEpochs = Math.max(constants.lagInEpochsForValidatorSet, constants.lagInEpochsForRandao);
       const targetEpoch = EpochNumber(lagEpochs + 2);
+      // mineUntilTimestamp mines real blocks so finalized advances with them.
+      // It stops interval mining, so we must restore it before setupEpoch (which
+      // submits a transaction that needs to be mined).
       await rollupCheatCodes.advanceToEpoch(targetEpoch);
 
-      // Mine enough blocks so the finalized tag catches up (finalized = latest - 16 with slotsInAnEpoch=8).
-      await cheatCodes.mine(20);
-
       // Setup epoch so the committee commitment is stored on-chain.
       await rollupCheatCodes.setupEpoch();
 
+      // Stop interval mining to freeze the dateProvider while we run assertions.
+      await cheatCodes.setIntervalMining(0);
+
       const { committee, seed, epoch } = await epochCache.getCommittee('now');
 
       expect(committee).toBeDefined();

yarn-project/ethereum/src/test/eth_cheat_codes.test.ts

@@ -212,6 +212,46 @@ describe('EthCheatCodes', () => {
     });
   });
 
+  describe('mineUntilTimestamp', () => {
+    it('mines blocks until the target timestamp is reached and restores interval mining', async () => {
+      const blockInterval = 2;
+      await cheatCodes.setIntervalMining(blockInterval);
+
+      const currentTs = await cheatCodes.lastBlockTimestamp();
+      const targetTs = currentTs + 20;
+
+      await cheatCodes.mineUntilTimestamp(targetTs, { blockTimestampInterval: blockInterval });
+
+      const latestTs = await cheatCodes.lastBlockTimestamp();
+      expect(latestTs).toBeGreaterThanOrEqual(targetTs);
+
+      // The key difference from warp: finalized block timestamp also advances.
+      const finalizedBlock = await cheatCodes.publicClient.getBlock({ blockTag: 'finalized' });
+      expect(Number(finalizedBlock.timestamp)).toBeGreaterThan(currentTs);
+
+      // Interval mining should be restored.
+      const intervalAfter = await cheatCodes.getIntervalMining();
+      expect(intervalAfter).toBe(blockInterval);
+    });
+
+    it('throws when blockTimestampInterval is not positive', async () => {
+      const currentTs = await cheatCodes.lastBlockTimestamp();
+      await expect(cheatCodes.mineUntilTimestamp(currentTs + 10, { blockTimestampInterval: 0 })).rejects.toThrow(
+        'blockTimestampInterval must be a positive number',
+      );
+    });
+
+    it('does nothing if already past the target timestamp', async () => {
+      const currentTs = await cheatCodes.lastBlockTimestamp();
+      const blockNumberBefore = await cheatCodes.blockNumber();
+
+      await cheatCodes.mineUntilTimestamp(currentTs - 5, { blockTimestampInterval: 1 });
+
+      const blockNumberAfter = await cheatCodes.blockNumber();
+      expect(blockNumberAfter).toBe(blockNumberBefore);
+    });
+  });
+
   describe('mineEmptyBlock', () => {
     it('mines an empty block while preserving pending transactions', async () => {
       // Deploy a token first (with automine enabled)

yarn-project/ethereum/src/test/eth_cheat_codes.ts

@@ -279,6 +279,58 @@ export class EthCheatCodes {
     }
   }
 
+  /**
+   * Advances L1 time to the target timestamp by mining blocks at the given interval.
+   * Unlike `warp`, this mines real blocks so finalized block timestamps also advance.
+   *
+   * Stops interval mining for the burst, then restores it if it was previously enabled.
+   *
+   * @param timestamp - The target timestamp to advance to
+   * @param opts - Must include `blockTimestampInterval` (seconds between block timestamps).
+   */
+  public async mineUntilTimestamp(
+    timestamp: number | bigint,
+    opts: { blockTimestampInterval: number; silent?: boolean },
+  ): Promise<void> {
+    const targetTimestamp = Number(timestamp);
+    const blockInterval = opts.blockTimestampInterval;
+    if (blockInterval <= 0) {
+      throw new Error('blockTimestampInterval must be a positive number');
+    }
+
+    const currentTimestamp = await this.lastBlockTimestamp();
+    const blocksNeeded = Math.ceil((targetTimestamp - currentTimestamp) / blockInterval);
+    if (blocksNeeded <= 0) {
+      return;
+    }
+
+    // Save and stop interval mining so Anvil doesn't auto-mine during the burst.
+    const previousInterval = await this.getIntervalMining();
+    if (previousInterval !== null && previousInterval > 0) {
+      await this.setIntervalMining(0, { silent: true });
+    }
+
+    try {
+      // Mine all blocks at once with the correct interval between them.
+      // hardhat_mine accepts (count, interval) where interval is seconds between blocks.
+      await this.doRpcCall('hardhat_mine', [`0x${blocksNeeded.toString(16)}`, `0x${blockInterval.toString(16)}`]);
+    } finally {
+      // Restore interval mining if it was previously enabled.
+      if (previousInterval !== null && previousInterval > 0) {
+        await this.setIntervalMining(previousInterval, { silent: true });
+      }
+    }
+
+    // Query the actual last block timestamp (may overshoot the target due to rounding).
+    const actualTimestamp = await this.lastBlockTimestamp();
+    if ('setTime' in this.dateProvider) {
+      this.dateProvider.setTime(actualTimestamp * 1000);
+    }
+    if (!opts.silent) {
+      this.logger.warn(`Mined ${blocksNeeded} L1 blocks until timestamp ${actualTimestamp}`);
+    }
+  }
+
   /**
    * Load the value at a storage slot of a contract address on eth
    * @param contract - The contract address

yarn-project/ethereum/src/test/rollup_cheat_codes.ts

@@ -29,6 +29,7 @@ export class RollupCheatCodes {
   constructor(
     private ethCheatCodes: EthCheatCodes,
     addresses: Pick<L1ContractAddresses, 'rollupAddress'>,
+    private readonly ethereumSlotDuration: number = 12,
   ) {
     this.client = createPublicClient({
       chain: ethCheatCodes.chain,
@@ -45,9 +46,10 @@ export class RollupCheatCodes {
     rpcUrls: string[],
     addresses: Pick<L1ContractAddresses, 'rollupAddress'>,
     dateProvider: DateProvider,
+    ethereumSlotDuration: number = 12,
   ): RollupCheatCodes {
     const ethCheatCodes = new EthCheatCodes(rpcUrls, dateProvider);
-    return new RollupCheatCodes(ethCheatCodes, addresses);
+    return new RollupCheatCodes(ethCheatCodes, addresses, ethereumSlotDuration);
   }
 
   /** Returns the current slot */
@@ -136,47 +138,56 @@ export class RollupCheatCodes {
     const slotNumber = SlotNumber(Number(epoch) * Number(slotsInEpoch));
     const timestamp = (await this.rollup.read.getTimestampForSlot([BigInt(slotNumber)])) + BigInt(opts.offset ?? 0);
     try {
-      await this.ethCheatCodes.warp(Number(timestamp), { ...opts, silent: true, resetBlockInterval: true });
-      this.logger.warn(`Warped to epoch ${epoch}`, { offset: opts.offset, timestamp });
+      await this.ethCheatCodes.mineUntilTimestamp(Number(timestamp), {
+        blockTimestampInterval: this.ethereumSlotDuration,
+        silent: true,
+      });
+      this.logger.warn(`Advanced to epoch ${epoch}`, { offset: opts.offset, timestamp });
     } catch (err) {
-      this.logger.warn(`Warp to epoch ${epoch} failed: ${err}`);
+      this.logger.warn(`Advance to epoch ${epoch} failed: ${err}`);
     }
     return timestamp;
   }
 
-  /** Warps time in L1 until the next epoch */
+  /** Advances L1 time until the next epoch */
   public async advanceToNextEpoch() {
     const slot = await this.getSlot();
     const { epochDuration, slotDuration } = await this.getConfig();
     const slotsUntilNextEpoch = epochDuration - (BigInt(slot) % epochDuration) + 1n;
     const timeToNextEpoch = slotsUntilNextEpoch * BigInt(slotDuration);
     const l1Timestamp = BigInt((await this.client.getBlock()).timestamp);
-    await this.ethCheatCodes.warp(Number(l1Timestamp + timeToNextEpoch), {
+    await this.ethCheatCodes.mineUntilTimestamp(Number(l1Timestamp + timeToNextEpoch), {
+      blockTimestampInterval: this.ethereumSlotDuration,
       silent: true,
-      resetBlockInterval: true,
     });
     this.logger.warn(`Advanced to next epoch`);
   }
 
-  /** Warps time in L1 until the beginning of the next slot. */
+  /** Advances L1 time until the beginning of the next slot. */
   public async advanceToNextSlot() {
     const currentSlot = await this.getSlot();
     const nextSlot = SlotNumber(currentSlot + 1);
     const timestamp = await this.rollup.read.getTimestampForSlot([BigInt(nextSlot)]);
-    await this.ethCheatCodes.warp(Number(timestamp), { silent: true, resetBlockInterval: true });
+    await this.ethCheatCodes.mineUntilTimestamp(Number(timestamp), {
+      blockTimestampInterval: this.ethereumSlotDuration,
+      silent: true,
+    });
     this.logger.warn(`Advanced to slot ${nextSlot}`);
     return [timestamp, nextSlot];
   }
 
   /**
-   * Warps time in L1 equivalent to however many slots.
+   * Advances L1 time by the given number of slots.
    * @param howMany - The number of slots to advance.
    */
   public async advanceSlots(howMany: number) {
     const l1Timestamp = (await this.client.getBlock()).timestamp;
     const slotDuration = Number(await this.rollup.read.getSlotDuration());
     const timeToWarp = BigInt(howMany) * BigInt(slotDuration);
-    await this.ethCheatCodes.warp(l1Timestamp + timeToWarp, { silent: true, resetBlockInterval: true });
+    await this.ethCheatCodes.mineUntilTimestamp(Number(l1Timestamp + timeToWarp), {
+      blockTimestampInterval: this.ethereumSlotDuration,
+      silent: true,
+    });
     const [slot, epoch] = await Promise.all([this.getSlot(), this.getEpoch()]);
     this.logger.warn(`Advanced ${howMany} slots up to slot ${slot} in epoch ${epoch}`);
   }