@aztec-labs/ethereum 6.0.0-nightly.20260829

package/src/queries.ts

@@ -0,0 +1,189 @@
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { BaseError, type Block } from 'viem';
+
+import { DefaultL1ContractsConfig, type L1ContractsConfig } from './config.js';
+import { ReadOnlyGovernanceContract } from './contracts/governance.js';
+import { GovernanceProposerContract } from './contracts/governance_proposer.js';
+import { RollupContract } from './contracts/rollup.js';
+import type { ViemClient, ViemPublicClient } from './types.js';
+
+/**
+ * Returns the L1 finalized block, or `undefined` if the chain does not yet have one
+ * (common on freshly started devnets). Rethrows any other RPC error.
+ */
+export async function getFinalizedL1Block(client: ViemClient): Promise<Block<bigint, false, 'finalized'> | undefined> {
+  try {
+    return await client.getBlock({ blockTag: 'finalized', includeTransactions: false });
+  } catch (err) {
+    if (isFinalizedBlockTagNotFoundError(err)) {
+      return undefined;
+    }
+    throw err;
+  }
+}
+
+// Error messages returned by popular Ethereum execution clients when
+// eth_getBlockByNumber / eth_call is called with blockTag "finalized" or
+// "safe" and no such block has been produced yet:
+//
+//   geth       "finalized block not found"
+//              "safe block not found"
+//   reth       "block not found: finalized"
+//              "block not found: safe"
+//   nethermind "Unknown block error"           (same for both tags)
+//   besu       "Unknown block"
+//   erigon     'block "finalized" not available (head block: N)'
+//              'block "safe" not available (head block: N)'
+//
+// A combined regex covers all five:
+const FINALIZED_BLOCK_TAG_NOT_FOUND_MESSAGE_RE =
+  /(finalized|safe) block not found|block not found: (finalized|safe)|unknown block|block "(finalized|safe)" not available/i;
+
+/**
+ * Returns true if the error originates from an RPC call that failed because
+ * the "finalized" (or "safe") block tag is not yet available on the chain.
+ */
+export function isFinalizedBlockTagNotFoundError(err: unknown): boolean {
+  if (!err) {
+    return false;
+  }
+
+  if (err instanceof BaseError) {
+    const hit = err.walk((e: any) => matchesFinalizedBlockTagNotFound(e));
+    if (hit) {
+      return true;
+    }
+  }
+
+  for (let cur: any = err, i = 0; cur && i < 10; cur = cur.cause, i++) {
+    if (matchesFinalizedBlockTagNotFound(cur)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function matchesFinalizedBlockTagNotFound(e: any): boolean {
+  if (!e) {
+    return false;
+  }
+  const text = `${e.details ?? ''} ${e.message ?? ''} ${e.shortMessage ?? ''}`;
+  return FINALIZED_BLOCK_TAG_NOT_FOUND_MESSAGE_RE.test(text);
+}
+
+/** Reads the L1ContractsConfig from L1 contracts. */
+export async function getL1ContractsConfig(
+  publicClient: ViemPublicClient,
+  addresses: { governanceAddress: EthAddress; rollupAddress?: EthAddress },
+): Promise<
+  Omit<L1ContractsConfig, 'ethereumSlotDuration'> & {
+    l1StartBlock: bigint;
+    l1GenesisTime: bigint;
+    rollupVersion: number;
+    genesisArchiveTreeRoot: `0x${string}`;
+  }
+> {
+  const governance = new ReadOnlyGovernanceContract(addresses.governanceAddress.toString(), publicClient);
+  const governanceProposerAddress = await governance.getGovernanceProposerAddress();
+  const governanceProposer = new GovernanceProposerContract(publicClient, governanceProposerAddress.toString());
+  const rollupAddress = addresses.rollupAddress ?? (await governanceProposer.getRollupAddress());
+  const rollup = new RollupContract(publicClient, rollupAddress.toString());
+  const slasherProposer = await rollup.getSlashingProposer();
+  const slasher = await rollup.getSlasherContract();
+
+  const [
+    l1StartBlock,
+    l1GenesisTime,
+    aztecEpochDuration,
+    aztecSlotDuration,
+    aztecProofSubmissionEpochs,
+    aztecTargetCommitteeSize,
+    lagInEpochsForValidatorSet,
+    lagInEpochsForRandao,
+    activationThreshold,
+    ejectionThreshold,
+    localEjectionThreshold,
+    governanceProposerQuorum,
+    governanceProposerRoundSize,
+    slashingQuorum,
+    slashingRoundSize,
+    slashingLifetimeInRounds,
+    slashingExecutionDelayInRounds,
+    slashingOffsetInRounds,
+    slashingAmounts,
+    slashingVetoer,
+    slashingDisableDuration,
+    manaTarget,
+    provingCostPerMana,
+    rollupVersion,
+    genesisArchiveTreeRoot,
+    exitDelay,
+  ] = await Promise.all([
+    rollup.getL1StartBlock(),
+    rollup.getL1GenesisTime(),
+    rollup.getEpochDuration(),
+    rollup.getSlotDuration(),
+    rollup.getProofSubmissionEpochs(),
+    rollup.getTargetCommitteeSize(),
+    rollup.getLagInEpochsForValidatorSet(),
+    rollup.getLagInEpochsForRandao(),
+    rollup.getActivationThreshold(),
+    rollup.getEjectionThreshold(),
+    rollup.getLocalEjectionThreshold(),
+    governanceProposer.getQuorumSize(),
+    governanceProposer.getRoundSize(),
+    slasherProposer?.getQuorumSize() ?? 0n,
+    slasherProposer?.getRoundSize() ?? 0n,
+    slasherProposer?.getLifetimeInRounds() ?? 0n,
+    slasherProposer?.getExecutionDelayInRounds() ?? 0n,
+    slasherProposer?.getSlashOffsetInRounds() ?? 0n,
+    slasherProposer?.getSlashingAmounts() ?? [0n, 0n, 0n],
+    slasher?.getVetoer() ?? EthAddress.ZERO,
+    slasher?.getSlashingDisableDuration() ?? 0,
+    rollup.getManaTarget(),
+    rollup.getProvingCostPerMana(),
+    rollup.getVersion(),
+    rollup.getGenesisArchiveTreeRoot(),
+    rollup.getExitDelay(),
+  ] as const);
+
+  return {
+    l1StartBlock,
+    l1GenesisTime,
+    aztecEpochDuration: Number(aztecEpochDuration),
+    aztecSlotDuration: Number(aztecSlotDuration),
+    aztecProofSubmissionEpochs: Number(aztecProofSubmissionEpochs),
+    aztecTargetCommitteeSize: Number(aztecTargetCommitteeSize),
+    lagInEpochsForValidatorSet: Number(lagInEpochsForValidatorSet),
+    lagInEpochsForRandao: Number(lagInEpochsForRandao),
+    governanceProposerQuorum: Number(governanceProposerQuorum),
+    governanceProposerRoundSize: Number(governanceProposerRoundSize),
+    governanceVotingDuration: DefaultL1ContractsConfig.governanceVotingDuration,
+    activationThreshold,
+    ejectionThreshold,
+    localEjectionThreshold,
+    slashingQuorum: Number(slashingQuorum),
+    slashingRoundSizeInEpochs: Number(Number(slashingRoundSize) / aztecEpochDuration),
+    slashingLifetimeInRounds: Number(slashingLifetimeInRounds),
+    slashingExecutionDelayInRounds: Number(slashingExecutionDelayInRounds),
+    slashingVetoer,
+    slashingDisableDuration,
+    manaTarget,
+    provingCostPerMana: provingCostPerMana,
+    rollupVersion: Number(rollupVersion),
+    genesisArchiveTreeRoot: genesisArchiveTreeRoot.toString(),
+    exitDelaySeconds: Number(exitDelay),
+    slasherEnabled: !!slasherProposer,
+    slashingOffsetInRounds: Number(slashingOffsetInRounds),
+    slashAmountSmall: slashingAmounts[0],
+    slashAmountMedium: slashingAmounts[1],
+    slashAmountLarge: slashingAmounts[2],
+    initialEthPerFeeAsset: DefaultL1ContractsConfig.initialEthPerFeeAsset,
+    // Not exposed by the rollup contract; fall back to defaults like the other non-on-chain fields above.
+    entryQueueBootstrapValidatorSetSize: DefaultL1ContractsConfig.entryQueueBootstrapValidatorSetSize,
+    entryQueueBootstrapFlushSize: DefaultL1ContractsConfig.entryQueueBootstrapFlushSize,
+    entryQueueFlushSizeMin: DefaultL1ContractsConfig.entryQueueFlushSizeMin,
+    entryQueueFlushSizeQuotient: DefaultL1ContractsConfig.entryQueueFlushSizeQuotient,
+    entryQueueMaxFlushSize: DefaultL1ContractsConfig.entryQueueMaxFlushSize,
+  };
+}

package/src/test/blob_kzg_warmup.ts

@@ -0,0 +1,65 @@
+import { getBytesPerBlob, getBytesPerCommitment, getKzg } from '@aztec-labs/blob-lib';
+import type { Logger } from '@aztec-labs/foundation/log';
+
+import type { ExtendedViemWalletClient } from '../types.js';
+
+/**
+ * Warms both KZG trusted setups in parallel for tests against a local anvil:
+ *   - anvil's own setup, loaded lazily when it first validates a blob sidecar in `eth_sendRawTransaction`
+ *   - our `@crate-crypto/node-eth-kzg` singleton (`getKzg()`, a ~2.2s synchronous precomp build)
+ *
+ * Without this, the first checkpoint publish pays both serially (~4.4s). The recipe does all RPC round
+ * trips up front, fires a single bare raw send carrying a fake (garbage) blob sidecar that anvil rejects
+ * after loading its trusted setup, yields once to flush the socket write, then synchronously builds our
+ * own precomp tables while anvil warms in parallel. The fake tx is rejected at admission, so it never
+ * enters the pool, mines no block, and burns no nonce — sending it from the passed client is harmless.
+ *
+ * Best-effort: any failure is debug-logged and swallowed, leaving lazy init as the fallback. Never throws.
+ *
+ * @param l1Client - The L1 client whose account sends the (rejected) warm-up blob tx.
+ */
+export async function warmBlobKzg(l1Client: ExtendedViemWalletClient, logger?: Logger): Promise<void> {
+  try {
+    // A pure-JS fake kzg: returns deterministic garbage of the correct lengths (commitment and proof are
+    // both 48 bytes). It makes viem build a syntactically valid sidecar without initializing any native
+    // module, so anvil loads its trusted setup to validate the (invalid) proof and then rejects the tx.
+    const fakeKzg = {
+      blobToKzgCommitment: () => {
+        const commitment = new Uint8Array(getBytesPerCommitment());
+        commitment.fill(0xab);
+        commitment[0] = 0xc0;
+        return commitment;
+      },
+      computeBlobKzgProof: () => {
+        const proof = new Uint8Array(getBytesPerCommitment());
+        proof.fill(0xcd);
+        proof[0] = 0xc0;
+        return proof;
+      },
+    };
+
+    // All RPC round trips (nonce, fees, gas) happen here, so only a single socket write remains to flush.
+    const prepared = await l1Client.prepareTransactionRequest({
+      blobs: [new Uint8Array(getBytesPerBlob())],
+      kzg: fakeKzg,
+      to: '0x0000000000000000000000000000000000000000',
+      value: 0n,
+      maxFeePerBlobGas: 1_000_000_000_000n,
+    });
+    const serialized = await l1Client.signTransaction(prepared);
+
+    // Fire the raw send without awaiting and swallow the expected rejection.
+    const sent = l1Client.request({ method: 'eth_sendRawTransaction', params: [serialized] }).catch(() => {});
+
+    // Flush the single socket write so anvil receives the tx and starts loading its trusted setup in its
+    // own process before we block the event loop below.
+    await new Promise(resolve => setImmediate(resolve));
+
+    // Synchronously build our precomp tables (~2.2s, event-loop-blocking); anvil warms in parallel.
+    getKzg();
+
+    await sent;
+  } catch (err) {
+    logger?.debug('Failed to warm blob KZG; falling back to lazy init', { err });
+  }
+}

package/src/test/chain_monitor.ts

@@ -0,0 +1,389 @@
+import type { ManaMinFeeComponents, RollupContract } from '@aztec-labs/ethereum/contracts';
+import { InboxContract } from '@aztec-labs/ethereum/contracts';
+import { CheckpointNumber, EpochNumber, SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { promiseWithResolvers } from '@aztec-labs/foundation/promise';
+import { DateProvider } from '@aztec-labs/foundation/timer';
+import { EventEmitter } from 'events';
+
+import type { ViemClient } from '../types.js';
+
+/** L2 fee data reported by the chain monitor. */
+export type L2FeeData = ManaMinFeeComponents & {
+  /** Total minimum fee per mana in Fee Juice (sum of sequencerCost + proverCost + congestionCost). */
+  minFeePerMana: bigint;
+  /** L1 base fee observed by the oracle. */
+  l1BaseFee: bigint;
+  /** L1 blob fee observed by the oracle. */
+  l1BlobFee: bigint;
+  /** ETH per fee asset exchange rate (1e12 precision). */
+  ethPerFeeAsset: bigint;
+  /** Mana target per checkpoint. */
+  manaTarget: bigint;
+};
+
+export type ChainMonitorEventMap = {
+  'l1-block': [{ l1BlockNumber: number; timestamp: bigint }];
+  checkpoint: [
+    { checkpointNumber: CheckpointNumber; l1BlockNumber: number; l2SlotNumber: SlotNumber; timestamp: bigint },
+  ];
+  'checkpoint-proven': [{ provenCheckpointNumber: CheckpointNumber; l1BlockNumber: number; timestamp: bigint }];
+  'l2-messages': [{ totalL2Messages: number; l1BlockNumber: number }];
+  'l2-epoch': [{ l2EpochNumber: EpochNumber; timestamp: bigint; committee: EthAddress[] | undefined }];
+  'l2-slot': [{ l2SlotNumber: SlotNumber; timestamp: bigint }];
+  '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
+  private running: Set<Promise<void>> = new Set();
+
+  /** Current L1 block number */
+  public l1BlockNumber!: number;
+  /** Current checkpoint number */
+  public checkpointNumber!: CheckpointNumber;
+  /** Current proven checkpoint number */
+  public provenCheckpointNumber!: CheckpointNumber;
+  /** L1 timestamp for the current checkpoint */
+  public checkpointTimestamp!: bigint;
+  /** L1 timestamp for the proven checkpoint */
+  public provenCheckpointTimestamp!: bigint;
+  /** Total number of L2 messages pushed into the Inbox */
+  public totalL2Messages: number = 0;
+  /** Current L2 epoch number */
+  public l2EpochNumber!: EpochNumber;
+  /** Current L2 slot number */
+  public l2SlotNumber!: SlotNumber;
+  /** Current L2 fee data (components of the minimum fee per mana). */
+  public l2FeeData!: L2FeeData;
+
+  constructor(
+    private readonly rollup: RollupContract,
+    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() {
+    if (this.handle) {
+      throw new Error('Chain monitor already started');
+    }
+    this.handle = setInterval(this.safeRun.bind(this), this.intervalMs);
+    return this;
+  }
+
+  async stop() {
+    try {
+      this.removeAllListeners();
+      if (this.handle) {
+        clearInterval(this.handle!);
+        this.handle = undefined;
+      }
+      await Promise.allSettled([...this.running]);
+    } catch (err) {
+      this.logger.error('Error stopping chain monitor', err);
+    }
+  }
+
+  protected async getInbox() {
+    if (!this.inbox) {
+      const { inboxAddress } = await this.rollup.getRollupAddresses();
+      this.inbox = new InboxContract(this.l1Client, inboxAddress);
+    }
+    return this.inbox;
+  }
+
+  protected safeRun() {
+    const running = promiseWithResolvers<void>();
+    this.running.add(running.promise);
+
+    void this.run()
+      .catch(error => {
+        this.logger.error('Error in chain monitor loop', error);
+      })
+      .finally(() => {
+        running.resolve();
+        this.running.delete(running.promise);
+      });
+  }
+
+  async run(force = false) {
+    const newL1BlockNumber = Number(await this.l1Client.getBlockNumber({ cacheTime: 0 }));
+    if (!force && this.l1BlockNumber === newL1BlockNumber) {
+      return this;
+    }
+    this.l1BlockNumber = newL1BlockNumber;
+
+    const [l2SlotNumber, l2Epoch, l1block] = await Promise.all([
+      this.rollup.getSlotNumber(),
+      this.rollup.getCurrentEpoch(),
+      this.l1Client.getBlock({ blockNumber: BigInt(newL1BlockNumber), includeTransactions: false }),
+    ]);
+
+    const timestamp = l1block.timestamp;
+    const timestampString = new Date(Number(timestamp) * 1000).toTimeString().split(' ')[0];
+
+    this.emit('l1-block', { l1BlockNumber: newL1BlockNumber, timestamp });
+    let msg = `L1 block ${newL1BlockNumber} mined at ${timestampString}`;
+
+    const newCheckpointNumber = await this.rollup.getCheckpointNumber();
+    if (this.checkpointNumber !== newCheckpointNumber) {
+      const epochNumber = await this.rollup.getEpochNumberForCheckpoint(newCheckpointNumber);
+      msg += ` with new checkpoint ${newCheckpointNumber} for epoch ${epochNumber}`;
+      this.checkpointNumber = newCheckpointNumber;
+      this.checkpointTimestamp = timestamp;
+      this.emit('checkpoint', {
+        checkpointNumber: newCheckpointNumber,
+        l1BlockNumber: newL1BlockNumber,
+        l2SlotNumber,
+        timestamp,
+      });
+    }
+
+    const newProvenCheckpointNumber = await this.rollup.getProvenCheckpointNumber();
+    if (this.provenCheckpointNumber !== newProvenCheckpointNumber) {
+      const epochNumber = await this.rollup.getEpochNumberForCheckpoint(newProvenCheckpointNumber);
+      msg += ` with proof up to checkpoint ${newProvenCheckpointNumber} for epoch ${epochNumber}`;
+      this.provenCheckpointNumber = newProvenCheckpointNumber;
+      this.provenCheckpointTimestamp = timestamp;
+      this.emit('checkpoint-proven', {
+        provenCheckpointNumber: newProvenCheckpointNumber,
+        l1BlockNumber: newL1BlockNumber,
+        timestamp,
+      });
+    }
+
+    const inbox = await this.getInbox();
+    const newTotalL2Messages = await inbox.getState().then(s => Number(s.totalMessagesInserted));
+    if (this.totalL2Messages !== newTotalL2Messages) {
+      msg += ` with ${newTotalL2Messages - this.totalL2Messages} new L2 messages (total ${newTotalL2Messages})`;
+      this.totalL2Messages = newTotalL2Messages;
+      this.emit('l2-messages', { totalL2Messages: newTotalL2Messages, l1BlockNumber: newL1BlockNumber });
+    }
+
+    let committee: EthAddress[] | undefined;
+    if (l2Epoch !== this.l2EpochNumber) {
+      this.l2EpochNumber = l2Epoch;
+      committee = await this.rollup.getCurrentEpochCommittee();
+      this.emit('l2-epoch', { l2EpochNumber: l2Epoch, timestamp, committee });
+      msg += ` starting new epoch ${this.l2EpochNumber}`;
+    }
+
+    if (l2SlotNumber !== this.l2SlotNumber) {
+      this.l2SlotNumber = l2SlotNumber;
+      this.emit('l2-slot', { l2SlotNumber, timestamp });
+    }
+
+    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, {
+      currentTimestamp: this.dateProvider.nowInSeconds(),
+      l1Timestamp: timestamp,
+      l1BlockNumber: this.l1BlockNumber,
+      l2SlotNumber,
+      l2Epoch,
+      checkpointNumber: this.checkpointNumber,
+      provenCheckpointNumber: this.provenCheckpointNumber,
+      totalL2Messages: this.totalL2Messages,
+      committee,
+      ...this.l2FeeData,
+    });
+
+    return this;
+  }
+
+  public waitUntilL2Slot(slot: SlotNumber): Promise<void> {
+    if (this.l2SlotNumber >= slot) {
+      return Promise.resolve();
+    }
+    return new Promise(resolve => {
+      const listener = (data: { l2SlotNumber: SlotNumber; timestamp: bigint }) => {
+        if (data.l2SlotNumber >= slot) {
+          this.off('l2-slot', listener);
+          resolve();
+        }
+      };
+      this.on('l2-slot', listener);
+    });
+  }
+
+  public async waitUntilNextL2Slot(): Promise<void> {
+    const targetSlot = SlotNumber.add((await this.run()).l2SlotNumber, 1);
+    return this.waitUntilL2Slot(targetSlot);
+  }
+
+  public waitUntilL1Block(block: number | bigint): Promise<void> {
+    const targetBlock = typeof block === 'bigint' ? block.valueOf() : block;
+    if (this.l1BlockNumber >= targetBlock) {
+      return Promise.resolve();
+    }
+    return new Promise(resolve => {
+      const listener = (data: { l1BlockNumber: number; timestamp: bigint }) => {
+        if (data.l1BlockNumber >= targetBlock) {
+          this.off('l1-block', listener);
+          resolve();
+        }
+      };
+      this.on('l1-block', listener);
+    });
+  }
+
+  public waitUntilL1Timestamp(timestamp: number | bigint): Promise<void> {
+    const targetTimestamp = typeof timestamp === 'bigint' ? timestamp.valueOf() : timestamp;
+    if (this.l1BlockNumber >= targetTimestamp) {
+      return Promise.resolve();
+    }
+    return new Promise(resolve => {
+      const listener = (data: { l1BlockNumber: number; timestamp: bigint }) => {
+        if (data.timestamp >= targetTimestamp) {
+          this.off('l1-block', listener);
+          resolve();
+        }
+      };
+      this.on('l1-block', listener);
+    });
+  }
+
+  public waitUntilCheckpoint(checkpointNumber: CheckpointNumber): Promise<void> {
+    if (this.checkpointNumber >= checkpointNumber) {
+      return Promise.resolve();
+    }
+    return new Promise(resolve => {
+      const listener = (data: { checkpointNumber: CheckpointNumber; timestamp: bigint }) => {
+        if (data.checkpointNumber >= checkpointNumber) {
+          this.off('checkpoint', listener);
+          resolve();
+        }
+      };
+      this.on('checkpoint', listener);
+    });
+  }
+
+  /**
+   * 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),
+      this.rollup.getManaMinFeeAt(timestamp, true),
+      this.rollup.getL1FeesAt(timestamp),
+      this.rollup.getEthPerFeeAsset(),
+      this.rollup.getManaTarget(),
+    ]);
+    return {
+      ...components,
+      minFeePerMana,
+      l1BaseFee: l1Fees.baseFee,
+      l1BlobFee: l1Fees.blobFee,
+      ethPerFeeAsset,
+      manaTarget,
+    };
+  }
+
+  private hasFeeDataChanged(newData: L2FeeData): boolean {
+    if (!this.l2FeeData) {
+      return true;
+    }
+    return (
+      this.l2FeeData.sequencerCost !== newData.sequencerCost ||
+      this.l2FeeData.proverCost !== newData.proverCost ||
+      this.l2FeeData.congestionCost !== newData.congestionCost ||
+      this.l2FeeData.l1BaseFee !== newData.l1BaseFee ||
+      this.l2FeeData.l1BlobFee !== newData.l1BlobFee ||
+      this.l2FeeData.ethPerFeeAsset !== newData.ethPerFeeAsset
+    );
+  }
+}