@aztec/ethereum 5.0.0-rc.2 → 5.0.1

package/src/test/chain_monitor.ts

@@ -36,9 +36,20 @@ export type ChainMonitorEventMap = {
   'l2-fees': [L2FeeData];
 };
 
+/** Options for tuning what the {@link ChainMonitor} polls on each new L1 block. */
+export type ChainMonitorOptions = {
+  /**
+   * Whether to fetch L2 fee/oracle data (5 extra rollup reads per new L1 block) and emit `l2-fees`.
+   * Defaults to `true`. Set to `false` for tests that only care about slot/checkpoint/proven state to
+   * avoid the extra round-trips.
+   */
+  includeFeeData?: boolean;
+};
+
 /** Utility class that polls the chain on quick intervals and logs new L1 blocks, L2 blocks, and L2 proofs. */
 export class ChainMonitor extends EventEmitter<ChainMonitorEventMap> {
   private readonly l1Client: ViemClient;
+  private readonly includeFeeData: boolean;
   private inbox: InboxContract | undefined;
   private handle: NodeJS.Timeout | undefined;
   // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
@@ -68,9 +79,11 @@ export class ChainMonitor extends EventEmitter<ChainMonitorEventMap> {
     private readonly dateProvider: DateProvider = new DateProvider(),
     private readonly logger = createLogger('aztecjs:utils:chain_monitor'),
     private readonly intervalMs = 200,
+    options: ChainMonitorOptions = {},
   ) {
     super();
     this.l1Client = rollup.client;
+    this.includeFeeData = options.includeFeeData ?? true;
   }
 
   start() {
@@ -183,11 +196,13 @@ export class ChainMonitor extends EventEmitter<ChainMonitorEventMap> {
       this.emit('l2-slot', { l2SlotNumber, timestamp });
     }
 
-    const feeData = await this.fetchFeeData(timestamp);
-    if (this.hasFeeDataChanged(feeData)) {
-      msg += ` with L2 min fee ${feeData.minFeePerMana}`;
-      this.l2FeeData = feeData;
-      this.emit('l2-fees', feeData);
+    if (this.includeFeeData) {
+      const feeData = await this.fetchFeeData(timestamp);
+      if (this.hasFeeDataChanged(feeData)) {
+        msg += ` with L2 min fee ${feeData.minFeePerMana}`;
+        this.l2FeeData = feeData;
+        this.emit('l2-fees', feeData);
+      }
     }
 
     this.logger.info(msg, {
@@ -273,6 +288,74 @@ export class ChainMonitor extends EventEmitter<ChainMonitorEventMap> {
     });
   }
 
+  /**
+   * Resolves with the first `checkpoint` event whose payload satisfies `match`. Unlike
+   * {@link waitUntilCheckpoint} (which waits for a target number), this lets callers wait for an
+   * arbitrary checkpoint property (e.g. one published in the first half of its slot). Rejects after
+   * `opts.timeout` ms if provided; otherwise waits indefinitely.
+   *
+   * By default this is purely event-driven and only resolves on the *next* matching checkpoint that
+   * arrives after the call. Set `checkCurrentCheckpoint` to also test the current checkpoint first (via
+   * a fresh {@link run} snapshot) and short-circuit if it already satisfies `match`. Use it only for
+   * latching state predicates (e.g. "checkpoint number has passed N"), where an already-satisfied
+   * result is valid and you want to avoid missing an advance that landed before the listener attached.
+   * Do NOT set it when the predicate depends on observing the checkpoint live (e.g. one published
+   * mid-slot that the caller then times against wall-clock), since it may return a checkpoint whose
+   * slot has already elapsed.
+   */
+  public async waitForCheckpoint(
+    match: (event: ChainMonitorEventMap['checkpoint'][0]) => boolean,
+    opts: { timeout?: number; checkCurrentCheckpoint?: boolean } = {},
+  ): Promise<ChainMonitorEventMap['checkpoint'][0]> {
+    if (opts.checkCurrentCheckpoint) {
+      await this.run();
+      const current: ChainMonitorEventMap['checkpoint'][0] = {
+        checkpointNumber: this.checkpointNumber,
+        l1BlockNumber: this.l1BlockNumber,
+        l2SlotNumber: this.l2SlotNumber,
+        timestamp: this.checkpointTimestamp,
+      };
+      if (match(current)) {
+        return current;
+      }
+    }
+    return new Promise((resolve, reject) => {
+      let timer: NodeJS.Timeout | undefined;
+      const listener = (event: ChainMonitorEventMap['checkpoint'][0]) => {
+        if (match(event)) {
+          if (timer) {
+            clearTimeout(timer);
+          }
+          this.off('checkpoint', listener);
+          resolve(event);
+        }
+      };
+      if (opts.timeout !== undefined) {
+        timer = setTimeout(() => {
+          this.off('checkpoint', listener);
+          reject(new Error(`Timed out after ${opts.timeout}ms waiting for a matching checkpoint`));
+        }, opts.timeout);
+      }
+      this.on('checkpoint', listener);
+    });
+  }
+
+  /** Resolves once the proven checkpoint number reaches `checkpointNumber`. */
+  public waitUntilCheckpointProven(checkpointNumber: CheckpointNumber): Promise<void> {
+    if (this.provenCheckpointNumber >= checkpointNumber) {
+      return Promise.resolve();
+    }
+    return new Promise(resolve => {
+      const listener = (data: { provenCheckpointNumber: CheckpointNumber; timestamp: bigint }) => {
+        if (data.provenCheckpointNumber >= checkpointNumber) {
+          this.off('checkpoint-proven', listener);
+          resolve();
+        }
+      };
+      this.on('checkpoint-proven', listener);
+    });
+  }
+
   private async fetchFeeData(timestamp: bigint): Promise<L2FeeData> {
     const [components, minFeePerMana, l1Fees, ethPerFeeAsset, manaTarget] = await Promise.all([
       this.rollup.getManaMinFeeComponentsAt(timestamp, true),

package/src/test/eth_cheat_codes.ts

@@ -206,6 +206,22 @@ export class EthCheatCodes {
     }
   }
 
+  /**
+   * Starts interval mining from a freshly mined block and syncs the date provider to the block timestamp.
+   */
+  public async startIntervalMiningWithFreshBlock(seconds: number): Promise<void> {
+    if (seconds <= 0) {
+      throw new Error(`Interval mining requires a positive interval, got ${seconds}`);
+    }
+
+    await this.setAutomine(false);
+    await this.setIntervalMining(0, { silent: true });
+    await this.evmMine();
+    await this.syncDateProvider();
+    await this.setIntervalMining(seconds);
+    this.logger.warn(`Started L1 interval mining at ${seconds} seconds from a fresh block`);
+  }
+
   /**
    * Set the automine status of the underlying anvil chain
    * @param automine - The automine status to set
@@ -478,58 +494,46 @@ export class EthCheatCodes {
   }
 
   /**
-   * Mines an empty block by temporarily removing all pending transactions from the mempool,
-   * mining a block, and then re-adding the transactions back to the pool.
+   * Mines empty blocks while leaving any pending transactions untouched in the mempool.
+   *
+   * Never manipulates the mempool, so it is immune to the race that dropping and re-adding txs has against a
+   * concurrent publisher that is monitoring and re-broadcasting the same in-flight tx (with that approach the
+   * in-flight tx could reappear in the pool and be swept into the "empty" block, mining a proposal the caller
+   * expected to stay pending). Works in two steps: first the block gas limit is temporarily lowered below the
+   * intrinsic cost of any transaction (21000 gas) and the blocks are mined, so no pending tx is includable;
+   * then those blocks are reorged out and replaced with empty blocks mined at the restored gas limit. The
+   * reorg is needed because anvil applies a new gas limit only to future blocks: without it the just-mined
+   * blocks would keep the tiny gas limit, and an `eth_call` against `latest` (whose gas is capped by the
+   * block gas limit) would revert with "intrinsic gas too high".
    */
   public async mineEmptyBlock(blockCount: number = 1): Promise<void> {
     await this.execWithPausedAnvil(async () => {
-      // Get all pending and queued transactions from the pool
-      const txs = await this.getTxPoolContents();
-
-      this.logger.debug(`Found ${txs.length} transactions in pool`);
-
-      // Get raw transactions before dropping them
-      const rawTxs: Hex[] = [];
-      for (const tx of txs) {
-        try {
-          const rawTx = await this.doRpcCall('debug_getRawTransaction', [tx.hash]);
-          if (rawTx) {
-            rawTxs.push(rawTx);
-            this.logger.debug(`Got raw tx for ${tx.hash}`);
-          } else {
-            this.logger.warn(`No raw tx found for ${tx.hash}`);
-          }
-        } catch {
-          this.logger.warn(`Failed to get raw transaction for ${tx.hash}`);
-        }
-      }
-
-      this.logger.debug(`Retrieved ${rawTxs.length} raw transactions`);
-
-      // Drop all transactions from the mempool
-      await this.doRpcCall('anvil_dropAllTransactions', []);
-
-      // Mine an empty block
-      await this.doMine(blockCount);
-
-      // Re-add the transactions to the pool
-      for (const rawTx of rawTxs) {
-        try {
-          const txHash = await this.doRpcCall('eth_sendRawTransaction', [rawTx]);
-          this.logger.debug(`Re-added transaction ${txHash}`);
-        } catch (err) {
-          this.logger.warn(`Failed to re-add transaction: ${err}`);
-        }
-      }
-
-      if (rawTxs.length !== txs.length) {
-        this.logger.warn(`Failed to add all txs back: had ${txs.length} but re-added ${rawTxs.length}`);
+      const originalGasLimit = await this.getBlockGasLimit();
+      try {
+        await this.setBlockGasLimit(1n);
+        await this.doMine(blockCount);
+      } finally {
+        await this.setBlockGasLimit(originalGasLimit);
       }
+      // Replace the tiny-gas-limit blocks with empty blocks at the restored gas limit, keeping the same
+      // height and timestamps. The reorged-out blocks held no transactions, so nothing returns to the pool.
+      await this.doRpcCall('anvil_reorg', [blockCount, []]);
     });
 
     this.logger.warn(`Mined ${blockCount} empty L1 ${pluralize('block', blockCount)}`);
   }
 
+  /** Returns the gas limit of the latest mined L1 block. */
+  public async getBlockGasLimit(): Promise<bigint> {
+    const block = await this.doRpcCall('eth_getBlockByNumber', ['latest', false]);
+    return BigInt(block.gasLimit);
+  }
+
+  /** Sets the block gas limit applied to subsequently mined L1 blocks. */
+  public async setBlockGasLimit(gasLimit: bigint): Promise<void> {
+    await this.doRpcCall('anvil_setBlockGasLimit', [toHex(gasLimit)]);
+  }
+
   public async execWithPausedAnvil<T>(fn: () => Promise<T>): Promise<T> {
     const [blockInterval, wasAutoMining] = await Promise.all([this.getIntervalMining(), this.isAutoMining()]);
     try {

package/src/test/index.ts

@@ -1,3 +1,4 @@
+export * from './blob_kzg_warmup.js';
 export * from './eth_cheat_codes.js';
 export * from './eth_cheat_codes_with_state.js';
 export * from './start_anvil.js';

package/src/test/rollup_cheat_codes.ts

@@ -4,6 +4,7 @@ import type { ViemPublicClient } from '@aztec/ethereum/types';
 import { CheckpointNumber, EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { createLogger } from '@aztec/foundation/log';
+import { retryUntil } from '@aztec/foundation/retry';
 import type { DateProvider } from '@aztec/foundation/timer';
 import { RollupAbi } from '@aztec/l1-artifacts/RollupAbi';
 
@@ -244,6 +245,56 @@ export class RollupCheatCodes {
     });
   }
 
+  /**
+   * Polls the rollup until its current epoch reaches `epoch`. Unlike {@link advanceToEpoch} this does
+   * not warp the L1 clock; it only waits for the chain to reach `epoch` through external activity.
+   */
+  public async waitForEpoch(epoch: EpochNumber, opts: { timeout?: number; interval?: number } = {}): Promise<void> {
+    await retryUntil(
+      async () => (await this.getEpoch()) >= epoch || undefined,
+      `rollup epoch >= ${epoch}`,
+      opts.timeout ?? 60,
+      opts.interval ?? 1,
+    );
+  }
+
+  /**
+   * Polls the rollup until its current slot reaches `slot`. Unlike {@link advanceToSlot} this does not
+   * warp the L1 clock; it only waits for the chain to reach `slot` through external activity.
+   */
+  public async waitForSlot(slot: SlotNumber, opts: { timeout?: number; interval?: number } = {}): Promise<void> {
+    await retryUntil(
+      async () => (await this.getSlot()) >= slot || undefined,
+      `rollup slot >= ${slot}`,
+      opts.timeout ?? 60,
+      opts.interval ?? 1,
+    );
+  }
+
+  /**
+   * Polls the rollup until its pending checkpoint settles below `checkpoint` on a freshly mined, non-zero
+   * checkpoint, and returns that new pending checkpoint number. Reads the L1 rollup contract directly
+   * rather than a node, since a rollback lands on L1 first.
+   *
+   * A prune can momentarily drop the pending checkpoint to 0 before the post-deadline propose mines its
+   * replacement, so a caller detecting a rollback wants the new lower checkpoint, not that transient
+   * empty state — hence the non-zero guard.
+   */
+  public async waitForCheckpointBelow(
+    checkpoint: CheckpointNumber,
+    opts: { timeout?: number; interval?: number } = {},
+  ): Promise<CheckpointNumber> {
+    return await retryUntil(
+      async () => {
+        const { pending } = await this.getTips();
+        return pending > 0 && pending < checkpoint ? pending : undefined;
+      },
+      `rollup checkpoint in (0, ${checkpoint})`,
+      opts.timeout ?? 60,
+      opts.interval ?? 1,
+    );
+  }
+
   /**
    * Overrides the inProgress field of the Inbox contract state
    * @param howMuch - How many checkpoints to move it forward

package/src/test/start_anvil.ts

@@ -1,10 +1,10 @@
 import { createLogger } from '@aztec/foundation/log';
 import { makeBackoff, retry } from '@aztec/foundation/retry';
 import type { TestDateProvider } from '@aztec/foundation/timer';
-import { fileURLToPath } from '@aztec/foundation/url';
 
 import { type ChildProcess, spawn } from 'child_process';
-import { dirname, resolve } from 'path';
+
+import { resolveFoundryBinary } from '../foundry_binary.js';
 
 /** Minimal interface matching the @viem/anvil Anvil shape used by callers. */
 export interface Anvil {
@@ -14,6 +14,30 @@ export interface Anvil {
   stop(): Promise<void>;
 }
 
+// Watchdog wrapper: instead of spawning anvil directly, we spawn a small bash supervisor that runs
+// anvil as a background child and polls its own parent (this node process). If the parent dies for
+// ANY reason — including SIGKILL / crash / OOM, where node's own exit handlers never run — the poll
+// loop ends and the EXIT trap reaps anvil. The script is inlined (rather than shipped as a `.sh`) so
+// it works from the published npm tarball too, and the resolved anvil binary is passed via
+// `$ANVIL_BIN` so it works without `anvil` on PATH.
+//
+// `$@` is the anvil argv; `bash -c <script> bash <...args>` puts the args in `$@` and `$0` = 'bash'.
+//
+// The EXIT trap reaps anvil; INT/TERM just `exit` (which fires the EXIT trap) so a signal terminates
+// the supervisor promptly instead of being swallowed — a trapped TERM does NOT terminate the shell,
+// so trapping the kill directly on TERM would leave the poll loop running and the caller's teardown
+// hanging until its SIGKILL escalation. `sleep & wait` makes the poll interruptible, so INT/TERM are
+// handled immediately rather than after the current `sleep` returns.
+const ANVIL_WATCHDOG = `
+set -u
+parent=$PPID
+"$ANVIL_BIN" "$@" &
+anvil_pid=$!
+trap 'kill "$anvil_pid" 2>/dev/null' EXIT
+trap 'exit 0' INT TERM
+while kill -0 "$parent" 2>/dev/null; do sleep 1 & wait $!; done
+`;
+
 /**
  * Ensures there's a running Anvil instance and returns the RPC URL.
  */
@@ -42,7 +66,7 @@ export async function startAnvil(
     dateProvider?: TestDateProvider;
   } = {},
 ): Promise<{ anvil: Anvil; methodCalls?: string[]; rpcUrl: string; stop: () => Promise<void> }> {
-  const anvilBinary = resolve(dirname(fileURLToPath(import.meta.url)), '../../', 'scripts/anvil_kill_wrapper.sh');
+  const anvilBinary = resolveFoundryBinary('anvil');
   const logger = opts.log ? createLogger('ethereum:anvil') : undefined;
   const methodCalls = opts.captureMethodCalls ? ([] as string[]) : undefined;
 
@@ -50,6 +74,9 @@ export async function startAnvil(
 
   const anvil = await retry(
     async () => {
+      // `--port 0` lets anvil bind an OS-assigned ephemeral port; the actual port is read back from
+      // its "Listening on host:port" stdout below, so independent suites can spawn their own anvil
+      // in parallel without fighting over a fixed port.
       const port = opts.port ?? (process.env.ANVIL_PORT ? parseInt(process.env.ANVIL_PORT) : 8545);
       const args: string[] = [
         '--host',
@@ -71,9 +98,11 @@ export async function startAnvil(
       }
       args.push('--slots-in-an-epoch', String(opts.slotsInAnEpoch ?? 1));
 
-      const child = spawn(anvilBinary, args, {
+      // Spawn the watchdog (see ANVIL_WATCHDOG). It launches anvil with these args and reaps it if we
+      // die; `$0` is 'bash' and `$@` is the anvil argv.
+      const child = spawn('bash', ['-c', ANVIL_WATCHDOG, 'bash', ...args], {
         stdio: ['ignore', 'pipe', 'pipe'],
-        env: { ...process.env, RAYON_NUM_THREADS: '1' },
+        env: { ...process.env, ANVIL_BIN: anvilBinary, RAYON_NUM_THREADS: '1' },
       });
 
       // Wait for "Listening on" or an early exit.
@@ -183,7 +212,10 @@ function syncDateProviderFromAnvilOutput(text: string, dateProvider: TestDatePro
   }
 }
 
-/** Send SIGTERM, wait up to 5 s, then SIGKILL. All timers are always cleared. */
+/**
+ * Send SIGTERM to the watchdog, wait up to 5 s, then SIGKILL. The watchdog's trap forwards the
+ * signal to anvil, so terminating it tears down anvil too. All timers are always cleared.
+ */
 function killChild(child: ChildProcess): Promise<void> {
   return new Promise<void>(resolve => {
     if (child.exitCode !== null || child.killed) {