@aztec/ethereum 0.0.1-commit.a072138 → 0.0.1-commit.a5db02d

package/src/test/eth_cheat_codes.ts

@@ -85,14 +85,26 @@ export class EthCheatCodes {
   }
 
   /**
-   * Get the current timestamp
-   * @returns The current timestamp
+   * Get the timestamp of the latest mined L1 block.
+   * Note: this is NOT the current time — it's the discrete timestamp of the last block.
+   * Between blocks, the actual chain time advances but no new block reflects it.
+   * @returns The latest block timestamp in seconds
    */
-  public async timestamp(): Promise<number> {
+  public async lastBlockTimestamp(): Promise<number> {
     const res = await this.doRpcCall('eth_getBlockByNumber', ['latest', true]);
     return parseInt(res.timestamp, 16);
   }
 
+  /**
+   * Get the timestamp of the pending L1 block — the block that anvil will mine next.
+   * Reflects any prior `setNextBlockTimestamp` call or the configured block interval.
+   * @returns The pending block timestamp in seconds.
+   */
+  public async nextBlockTimestamp(): Promise<number> {
+    const res = await this.doRpcCall('eth_getBlockByNumber', ['pending', false]);
+    return parseInt(res.timestamp, 16);
+  }
+
   /**
    * Advance the chain by a number of blocks
    * @param numberOfBlocks - The number of blocks to mine
@@ -194,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
@@ -466,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 {
@@ -552,7 +568,7 @@ export class EthCheatCodes {
   }
 
   public async syncDateProvider() {
-    const timestamp = await this.timestamp();
+    const timestamp = await this.lastBlockTimestamp();
     if ('setTime' in this.dateProvider) {
       this.dateProvider.setTime(timestamp * 1000);
     }

package/src/test/index.ts

@@ -1,8 +1,7 @@
-export * from './delayed_tx_utils.js';
+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';
-export * from './tx_delayer.js';
 export * from './upgrade_utils.js';
 export * from './chain_monitor.js';
 export * from './rollup_cheat_codes.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';
 
@@ -15,6 +16,7 @@ import {
   getContract,
   hexToBigInt,
   http,
+  keccak256,
 } from 'viem';
 
 import { EthCheatCodes } from './eth_cheat_codes.js';
@@ -53,7 +55,17 @@ export class RollupCheatCodes {
   /** Returns the current slot */
   public async getSlot(): Promise<SlotNumber> {
     const ts = BigInt((await this.client.getBlock()).timestamp);
-    return SlotNumber.fromBigInt(await this.rollup.read.getSlotAt([ts]));
+    return this.getSlotAt(ts);
+  }
+
+  /** Returns the slot number at a given timestamp. */
+  public async getSlotAt(timestamp: bigint): Promise<SlotNumber> {
+    return SlotNumber.fromBigInt(await this.rollup.read.getSlotAt([timestamp]));
+  }
+
+  /** Returns the timestamp for the start of a given slot. */
+  public async getTimestampForSlot(slot: SlotNumber): Promise<bigint> {
+    return await this.rollup.read.getTimestampForSlot([BigInt(slot)]);
   }
 
   /** Returns the number of seconds until the start of the given slot based on L1 block timestamp. */
@@ -168,6 +180,21 @@ export class RollupCheatCodes {
     return [timestamp, nextSlot];
   }
 
+  /**
+   * Warps L1 time to the start of an explicit absolute slot. Unlike `advanceSlots(N)` which is
+   * relative to the current L1 timestamp at call time and therefore races with real-time
+   * progression between query and warp, this lands at the slot regardless of latency.
+   *
+   * Throws if the requested slot is in the past relative to current L1 time (anvil cannot
+   * rewind).
+   */
+  public async advanceToSlot(slot: SlotNumber) {
+    const timestamp = await this.rollup.read.getTimestampForSlot([BigInt(slot)]);
+    await this.ethCheatCodes.warp(Number(timestamp), { silent: true, resetBlockInterval: true });
+    this.logger.warn(`Advanced to slot ${slot}`, { timestamp });
+    return timestamp;
+  }
+
   /**
    * Warps time in L1 equivalent to however many slots.
    * @param howMany - The number of slots to advance.
@@ -218,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
@@ -259,12 +336,14 @@ export class RollupCheatCodes {
     });
   }
 
-  public insertOutbox(epoch: EpochNumber, outHash: bigint) {
+  public insertOutbox(epoch: EpochNumber, numCheckpointsInEpoch: number, outHash: bigint) {
     return this.ethCheatCodes.execWithPausedAnvil(async () => {
       const outboxAddress = await this.rollup.read.getOutbox();
-      const epochRootSlot = OutboxContract.getEpochRootStorageSlot(epoch);
+      const epochRootSlot = OutboxContract.getEpochRootStorageSlot(epoch, numCheckpointsInEpoch);
       await this.ethCheatCodes.store(EthAddress.fromString(outboxAddress), epochRootSlot, outHash);
-      this.logger.warn(`Advanced outbox to epoch ${epoch} with out hash ${outHash}`);
+      this.logger.warn(
+        `Advanced outbox to epoch ${epoch} numCheckpointsInEpoch ${numCheckpointsInEpoch} with out hash ${outHash}`,
+      );
     });
   }
 
@@ -313,7 +392,8 @@ export class RollupCheatCodes {
   }
 
   /**
-   * Directly updates proving cost per mana.
+   * Directly updates proving cost per mana. Throws if the on-chain tx reverts
+   * (e.g. rate-limit cooldown, step cap, or floor) instead of silently succeeding.
    * @param ethValue - The new proving cost per mana in ETH
    */
   public async setProvingCostPerMana(ethValue: bigint) {
@@ -323,8 +403,37 @@ export class RollupCheatCodes {
         chain: this.client.chain,
         gasLimit: 1000000n,
       });
-      await this.client.waitForTransactionReceipt({ hash });
+      const receipt = await this.client.waitForTransactionReceipt({ hash });
+      if (receipt.status !== 'success') {
+        throw new Error(
+          `setProvingCostPerMana(${ethValue}) reverted on L1 (tx ${hash}). ` +
+            `Likely FeeLib rate-limit (30-day cooldown or 1.5x step cap); ` +
+            `use clearProvingCostCooldown() between successive updates.`,
+        );
+      }
       this.logger.warn(`Updated proving cost per mana to ${ethValue}`);
     });
   }
+
+  /**
+   * Resets the 30-day proving-cost update cooldown enforced by FeeLib.updateProvingCostPerMana
+   * by zeroing `FeeStore.provingCostLastUpdate` directly in contract storage. Use between
+   * successive setProvingCostPerMana / bumpProvingCostPerMana calls so the later update can
+   * land instead of reverting. Does not touch L1 time, so PXE/tx-expiration state stays intact.
+   *
+   * @note This is tightly coupled to the `FeeStore` layout in
+   * l1-contracts/src/core/libraries/rollup/FeeLib.sol:
+   *   slot + 0: CompressedFeeConfig config          (uint256)
+   *   slot + 1: L1GasOracleValues l1GasOracleValues (14+14+4 bytes, packed)
+   *   slot + 2: uint64 provingCostLastUpdate        (only member — zeroing the slot is safe)
+   * If the struct layout changes, update the offset below.
+   */
+  public async clearProvingCostCooldown() {
+    const feeStoreBaseSlot = hexToBigInt(keccak256(Buffer.from('aztec.fee.storage', 'utf-8')));
+    const provingCostLastUpdateSlot = feeStoreBaseSlot + 2n;
+    await this.ethCheatCodes.store(EthAddress.fromString(this.rollup.address), provingCostLastUpdateSlot, 0n, {
+      silent: true,
+    });
+    this.logger.warn(`Cleared proving-cost update cooldown`);
+  }
 }

package/src/test/start_anvil.ts

@@ -1,9 +1,42 @@
 import { createLogger } from '@aztec/foundation/log';
 import { makeBackoff, retry } from '@aztec/foundation/retry';
-import { fileURLToPath } from '@aztec/foundation/url';
+import type { TestDateProvider } from '@aztec/foundation/timer';
 
-import { type Anvil, createAnvil } from '@viem/anvil';
-import { dirname, resolve } from 'path';
+import { type ChildProcess, spawn } from 'child_process';
+
+import { resolveFoundryBinary } from '../foundry_binary.js';
+
+/** Minimal interface matching the @viem/anvil Anvil shape used by callers. */
+export interface Anvil {
+  readonly port: number;
+  readonly host: string;
+  readonly status: 'listening' | 'idle';
+  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.
@@ -16,56 +49,203 @@ export async function startAnvil(
     captureMethodCalls?: boolean;
     accounts?: number;
     chainId?: number;
-    /** The hardfork to use - note: @viem/anvil types are out of date but 'cancun' and 'latest' work */
+    /** The hardfork to use (e.g. 'cancun', 'latest'). */
     hardfork?: string;
+    /**
+     * Number of slots per epoch used by anvil to compute the 'finalized' and 'safe' block tags.
+     * Anvil reports `finalized = latest - slotsInAnEpoch * 2`.
+     * Defaults to 1 so the finalized block advances immediately, making tests that check
+     * L1-finality-based logic work without needing hundreds of mined blocks.
+     */
+    slotsInAnEpoch?: number;
+    /**
+     * If provided, the date provider will be synced to anvil's block time on every mined block.
+     * This keeps the dateProvider in lockstep with anvil's chain time, avoiding drift between
+     * the wall clock and the L1 chain when computing L1 slot timestamps.
+     */
+    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;
 
-  let port: number | undefined;
+  let detectedPort: number | undefined;
 
-  // Start anvil.
-  // We go via a wrapper script to ensure if the parent dies, anvil dies.
   const anvil = await retry(
     async () => {
-      const anvil = createAnvil({
-        anvilBinary,
-        host: '127.0.0.1',
-        port: opts.port ?? (process.env.ANVIL_PORT ? parseInt(process.env.ANVIL_PORT) : 8545),
-        blockTime: opts.l1BlockTime,
-        stopTimeout: 1000,
-        accounts: opts.accounts ?? 20,
-        gasLimit: 45_000_000n,
-        chainId: opts.chainId ?? 31337,
+      // `--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',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        '--accounts',
+        String(opts.accounts ?? 20),
+        '--gas-limit',
+        String(45_000_000),
+        '--chain-id',
+        String(opts.chainId ?? 31337),
+      ];
+      if (opts.l1BlockTime !== undefined) {
+        args.push('--block-time', String(opts.l1BlockTime));
+      }
+      if (opts.hardfork !== undefined) {
+        args.push('--hardfork', opts.hardfork);
+      }
+      args.push('--slots-in-an-epoch', String(opts.slotsInAnEpoch ?? 1));
+
+      // 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, ANVIL_BIN: anvilBinary, RAYON_NUM_THREADS: '1' },
       });
 
-      // Listen to the anvil output to get the port.
-      const removeHandler = anvil.on('message', (message: string) => {
-        logger?.debug(message.trim());
+      // Wait for "Listening on" or an early exit.
+      await new Promise<void>((resolve, reject) => {
+        let stderr = '';
+
+        const onStdout = (data: Buffer) => {
+          const text = data.toString();
+          logger?.debug(text.trim());
+          methodCalls?.push(...(text.match(/eth_[^\s]+/g) || []));
 
-        methodCalls?.push(...(message.match(/eth_[^\s]+/g) || []));
-        if (port === undefined && message.includes('Listening on')) {
-          port = parseInt(message.match(/Listening on ([^:]+):(\d+)/)![2]);
-        }
+          if (detectedPort === undefined && text.includes('Listening on')) {
+            const match = text.match(/Listening on ([^:]+):(\d+)/);
+            if (match) {
+              detectedPort = parseInt(match[2]);
+            }
+          }
+          if (detectedPort !== undefined) {
+            child.stdout?.removeListener('data', onStdout);
+            child.stderr?.removeListener('data', onStderr);
+            child.removeListener('close', onClose);
+            resolve();
+          }
+        };
+
+        const onStderr = (data: Buffer) => {
+          stderr += data.toString();
+          logger?.debug(data.toString().trim());
+        };
+
+        const onClose = (code: number | null) => {
+          child.stdout?.removeListener('data', onStdout);
+          child.stderr?.removeListener('data', onStderr);
+          reject(new Error(`Anvil exited with code ${code} before listening. stderr: ${stderr}`));
+        };
+
+        child.stdout?.on('data', onStdout);
+        child.stderr?.on('data', onStderr);
+        child.once('close', onClose);
       });
-      await anvil.start();
-      if (!logger && !opts.captureMethodCalls) {
-        removeHandler();
+
+      // Continue piping for logging, method-call capture, and/or dateProvider sync after startup.
+      if (logger || opts.captureMethodCalls || opts.dateProvider) {
+        child.stdout?.on('data', (data: Buffer) => {
+          const text = data.toString();
+          logger?.debug(text.trim());
+          methodCalls?.push(...(text.match(/eth_[^\s]+/g) || []));
+          if (opts.dateProvider) {
+            syncDateProviderFromAnvilOutput(text, opts.dateProvider);
+          }
+        });
+        child.stderr?.on('data', (data: Buffer) => {
+          logger?.debug(data.toString().trim());
+        });
+      } else {
+        // Consume streams so the child process doesn't block on full pipe buffers.
+        child.stdout?.resume();
+        child.stderr?.resume();
       }
 
-      return anvil;
+      return child;
     },
     'Start anvil',
     makeBackoff([5, 5, 5]),
   );
 
-  if (!port) {
+  if (!detectedPort) {
     throw new Error('Failed to start anvil');
   }
 
-  // Monkeypatch the anvil instance to include the actually assigned port
-  // Object.defineProperty(anvil, 'port', { value: port, writable: false });
-  return { anvil, methodCalls, stop: () => anvil.stop(), rpcUrl: `http://127.0.0.1:${port}` };
+  const port = detectedPort;
+  let status: 'listening' | 'idle' = 'listening';
+
+  anvil.once('close', () => {
+    status = 'idle';
+  });
+
+  const stop = async () => {
+    if (status === 'idle') {
+      return;
+    }
+    await killChild(anvil);
+  };
+
+  const anvilObj: Anvil = {
+    port,
+    host: '127.0.0.1',
+    get status() {
+      return status;
+    },
+    stop,
+  };
+
+  return { anvil: anvilObj, methodCalls, stop, rpcUrl: `http://127.0.0.1:${port}` };
+}
+
+/** Extracts block time from anvil stdout and syncs the dateProvider. */
+function syncDateProviderFromAnvilOutput(text: string, dateProvider: TestDateProvider): void {
+  // Anvil logs mined blocks as:
+  //   Block Time: "Fri, 20 Mar 2026 02:10:46 +0000"
+  const match = text.match(/Block Time:\s*"([^"]+)"/);
+  if (match) {
+    const blockTimeMs = new Date(match[1]).getTime();
+    if (!isNaN(blockTimeMs)) {
+      dateProvider.setTime(blockTimeMs);
+    }
+  }
+}
+
+/**
+ * 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) {
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      resolve();
+      return;
+    }
+
+    let killTimer: NodeJS.Timeout | undefined;
+
+    const onClose = () => {
+      if (killTimer !== undefined) {
+        clearTimeout(killTimer);
+      }
+      // Destroy stdio streams so their PipeWrap handles don't keep the event loop alive.
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      resolve();
+    };
+
+    child.once('close', onClose);
+    child.kill('SIGTERM');
+
+    killTimer = setTimeout(() => {
+      killTimer = undefined;
+      child.kill('SIGKILL');
+    }, 5000);
+
+    // Ensure the timer does not prevent Node from exiting.
+    killTimer.unref();
+  });
 }

package/src/test/upgrade_utils.ts

@@ -7,7 +7,7 @@ import { type GetContractReturnType, type PrivateKeyAccount, getContract } from
 
 import { extractProposalIdFromLogs } from '../contracts/governance.js';
 import type { L1ContractAddresses } from '../l1_contract_addresses.js';
-import { createL1TxUtilsFromViemWallet } from '../l1_tx_utils/index.js';
+import { createL1TxUtils } from '../l1_tx_utils/index.js';
 import type { ExtendedViemWalletClient, ViemPublicClient } from '../types.js';
 import { EthCheatCodes } from './eth_cheat_codes.js';
 
@@ -22,7 +22,7 @@ export async function executeGovernanceProposal(
 ) {
   const proposal = await governance.read.getProposal([proposalId]);
 
-  const l1TxUtils = createL1TxUtilsFromViemWallet(l1Client);
+  const l1TxUtils = createL1TxUtils(l1Client);
 
   const waitL1Block = async () => {
     await l1TxUtils.sendAndMonitorTransaction({