@aztec/end-to-end 0.0.1-commit.a89ec08 → 0.0.1-commit.aa0c64f

package/src/multi-node/governance/setup.ts

@@ -0,0 +1,172 @@
+import { RollupContract } from '@aztec/ethereum/contracts';
+import type { L1TxUtils } from '@aztec/ethereum/l1-tx-utils';
+import type { ExtendedViemWalletClient } from '@aztec/ethereum/types';
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import { retryUntil } from '@aztec/foundation/retry';
+import { GovernanceAbi, GovernanceProposerAbi } from '@aztec/l1-artifacts';
+
+import { jest } from '@jest/globals';
+import { type GetContractReturnType, encodeFunctionData, getAddress, getContract } from 'viem';
+
+import type { MultiNodeTestContext } from '../multi_node_test_context.js';
+
+jest.setTimeout(1000 * 60 * 10);
+
+/**
+ * The shortened block-time timing the governance tests run on: a 12s L2 slot, 4s L1 slot, and a long
+ * proof-submission window so unproven blocks are never pruned (the committee runs no prover). Spread into
+ * a {@link MultiNodeTestContext.setup} call alongside {@link MOCK_GOSSIP_MULTI_VALIDATOR_OPTS} and
+ * `initialValidators`.
+ */
+export const GOVERNANCE_TIMING = {
+  aztecSlotDuration: 12,
+  ethereumSlotDuration: 4,
+  aztecProofSubmissionEpochs: 640,
+} as const;
+
+/** The current round leader's payload and its signal count, as observed by {@link GovernanceTestDriver.govInfo}. */
+type GovRoundState = { round: bigint; leaderVotes: bigint };
+
+/**
+ * Wraps the L1 governance-proposer / governance / rollup contracts and the round-driving mechanics shared by
+ * the governance suites (`add_rollup`, `upgrade_governance_proposer`): warping to round boundaries, polling
+ * round state, waiting for signal quorum, submitting the round winner, and voting a proposal through to
+ * executable. Scenario-specific payload construction, node signaling, and post-execution assertions stay in
+ * each test.
+ */
+export interface GovernanceTestDriver {
+  governanceProposer: GetContractReturnType<typeof GovernanceProposerAbi, ExtendedViemWalletClient>;
+  governance: GetContractReturnType<typeof GovernanceAbi, ExtendedViemWalletClient>;
+  rollup: RollupContract;
+  roundSize: bigint;
+  emperor: ExtendedViemWalletClient['account'];
+  /** Sends a 1-wei self-transfer to mine a fresh L1 block, so warped time takes effect. */
+  waitL1Block: () => Promise<void>;
+  /** Reads the current round's leading payload and its signal count. */
+  govInfo: () => Promise<GovRoundState>;
+  /** Warps L1 to the start of the next governance-proposer round. */
+  warpToNextRound: () => Promise<void>;
+  /** Polls once per L2 slot until the round leader reaches quorum, returning the round state at that point. */
+  waitForQuorum: (quorumSize: bigint, timeoutSeconds: number) => Promise<GovRoundState>;
+  /** Submits the winning payload of `round` to the governance proposer, creating the on-chain proposal. */
+  submitRoundWinner: (round: bigint) => Promise<void>;
+  /**
+   * Warps past the proposal's voting delay, casts a yes vote (asserting it lands), then warps past the
+   * voting duration and execution delay so the proposal becomes executable.
+   */
+  voteToExecutable: () => Promise<void>;
+}
+
+/** Builds a {@link GovernanceTestDriver} over the context's L1 governance contracts. */
+export async function createGovernanceTestDriver(
+  test: MultiNodeTestContext,
+  l1TxUtils: L1TxUtils,
+): Promise<GovernanceTestDriver> {
+  const { l1Client, l1ContractAddresses } = test.context.deployL1ContractsValues;
+  const rollupAddress = l1ContractAddresses.rollupAddress.toString();
+
+  const governanceProposer = getContract({
+    address: getAddress(l1ContractAddresses.governanceProposerAddress.toString()),
+    abi: GovernanceProposerAbi,
+    client: l1Client,
+  });
+  const governance = getContract({
+    address: getAddress(l1ContractAddresses.governanceAddress.toString()),
+    abi: GovernanceAbi,
+    client: l1Client,
+  });
+  const rollup = new RollupContract(l1Client, l1ContractAddresses.rollupAddress);
+  const roundSize = await governanceProposer.read.ROUND_SIZE();
+  const emperor = l1Client.account;
+
+  const waitL1Block = async () => {
+    await l1TxUtils.sendAndMonitorTransaction({ to: emperor.address, value: 1n });
+  };
+
+  const govInfo = async (): Promise<GovRoundState> => {
+    const bn = await test.context.cheatCodes.eth.blockNumber();
+    const slot = await rollup.getSlotNumber();
+    const round = await governanceProposer.read.computeRound([BigInt(slot)]);
+    const info = await governanceProposer.read.getRoundData([rollupAddress, round]);
+    const leaderVotes = await governanceProposer.read.signalCount([rollupAddress, round, info.payloadWithMostSignals]);
+    test.logger.info(
+      `Governance stats for round ${round} (Slot: ${slot}, BN: ${bn}). Leader: ${info.payloadWithMostSignals} have ${leaderVotes} signals`,
+    );
+    return { round, leaderVotes };
+  };
+
+  const warpToNextRound = async () => {
+    const currentSlot = await rollup.getSlotNumber();
+    const nextRoundSlot = SlotNumber.fromBigInt((BigInt(currentSlot) / roundSize) * roundSize + roundSize);
+    const nextRoundTimestamp = await rollup.getTimestampForSlot(nextRoundSlot);
+    await test.context.cheatCodes.eth.warp(Number(nextRoundTimestamp));
+  };
+
+  const waitForQuorum = (quorumSize: bigint, timeoutSeconds: number) =>
+    retryUntil(
+      async () => {
+        const data = await govInfo();
+        return data.leaderVotes >= quorumSize ? data : undefined;
+      },
+      'governance leader reaches quorum',
+      timeoutSeconds,
+      GOVERNANCE_TIMING.aztecSlotDuration,
+    );
+
+  const submitRoundWinner = async (round: bigint) => {
+    await l1TxUtils.sendAndMonitorTransaction({
+      to: governanceProposer.address,
+      data: encodeFunctionData({ abi: GovernanceProposerAbi, functionName: 'submitRoundWinner', args: [round] }),
+    });
+  };
+
+  const voteToExecutable = async () => {
+    const proposal = await governance.read.getProposal([0n]);
+
+    const timeToActive = proposal.creation + proposal.config.votingDelay;
+    await test.context.cheatCodes.eth.warp(Number(timeToActive + 1n));
+    await waitL1Block();
+
+    const voteTx = await rollup.vote(l1TxUtils, 0n);
+    expect(voteTx.receipt?.status).toBe('success');
+
+    const timeToExecutable = timeToActive + proposal.config.votingDuration + proposal.config.executionDelay + 1n;
+    await test.context.cheatCodes.eth.warp(Number(timeToExecutable));
+    await waitL1Block();
+  };
+
+  return {
+    governanceProposer,
+    governance,
+    rollup,
+    roundSize,
+    emperor,
+    waitL1Block,
+    govInfo,
+    warpToNextRound,
+    waitForQuorum,
+    submitRoundWinner,
+    voteToExecutable,
+  };
+}
+
+/**
+ * Drives one governance round to an executable proposal: waits for the signaled payload to reach quorum,
+ * warps to the next round, submits the round winner, then votes the resulting proposal through its voting
+ * and execution delays. Returns the round state observed at quorum; the caller performs the scenario-specific
+ * execution and assertions.
+ */
+export async function driveGovernanceRound(
+  driver: GovernanceTestDriver,
+  opts: { quorumTimeoutSeconds: number },
+): Promise<{ govData: GovRoundState }> {
+  const quorumSize = await driver.governanceProposer.read.QUORUM_SIZE();
+  const govData = await driver.waitForQuorum(quorumSize, opts.quorumTimeoutSeconds);
+  await driver.warpToNextRound();
+  await driver.waitL1Block();
+  await driver.submitRoundWinner(govData.round);
+  await driver.voteToExecutable();
+  return { govData };
+}
+
+export { jest };

package/src/multi-node/multi_node_test_context.ts

@@ -0,0 +1,447 @@
+import type { AztecNodeConfig, AztecNodeService } from '@aztec/aztec-node';
+import { EthAddress } from '@aztec/aztec.js/addresses';
+import { Fr } from '@aztec/aztec.js/fields';
+import { RollupContract, type SlashingProposerContract } from '@aztec/ethereum/contracts';
+import type { Operator } from '@aztec/ethereum/deploy-aztec-l1-contracts';
+import type { ViemClient } from '@aztec/ethereum/types';
+import { CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { times } from '@aztec/foundation/collection';
+import { SecretValue } from '@aztec/foundation/config';
+import { retryUntil } from '@aztec/foundation/retry';
+import { bufferToHex } from '@aztec/foundation/string';
+import { SlasherAbi } from '@aztec/l1-artifacts';
+import type { L2Tips } from '@aztec/stdlib/block';
+import type { AztecNode, BlockResponse } from '@aztec/stdlib/interfaces/client';
+import type { Offense } from '@aztec/stdlib/slashing';
+import { createSharedSlashingProtectionDb } from '@aztec/validator-ha-signer/factory';
+import type { SlashingProtectionDatabase } from '@aztec/validator-ha-signer/types';
+
+import { type GetContractReturnType, getAddress, getContract } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+
+import { testSpan } from '../fixtures/timing.js';
+import { getPrivateKeyFromIndex } from '../fixtures/utils.js';
+import { NO_REORG_SUBMISSION_EPOCHS } from '../single-node/setup.js';
+import {
+  SingleNodeTestContext,
+  type SingleNodeTestOpts,
+  type TrackedSequencerEvent,
+} from '../single-node/single_node_test_context.js';
+
+export { NO_REORG_SUBMISSION_EPOCHS, PROVING_SLOT_TIMING } from '../single-node/setup.js';
+export {
+  WORLD_STATE_CHECKPOINT_HISTORY,
+  WORLD_STATE_BLOCK_CHECK_INTERVAL,
+  ARCHIVER_POLL_INTERVAL,
+  DEFAULT_L1_BLOCK_TIME,
+  REORG_TIMING_BASE,
+  FAST_REORG_TIMING,
+  MULTI_VALIDATOR_REORG_TIMING,
+  MULTI_VALIDATOR_BLOCK_PRODUCTION_TIMING,
+  WIDE_SLOT_TIMING,
+  type BlockProposedEvent,
+  type TrackedSequencerEvent,
+  type SingleNodeTestOpts,
+} from '../single-node/single_node_test_context.js';
+
+/** Options for {@link MultiNodeTestContext.setup} — superset of {@link SingleNodeTestOpts}. */
+export type MultiNodeTestOpts = SingleNodeTestOpts;
+
+/** A registered validator with its on-chain operator data and the L1 private key its node signs with. */
+export type RegisteredValidator = Operator & { privateKey: `0x${string}` };
+
+/**
+ * Builds the deterministic validator set used across the multi-validator tests: `count` validators
+ * keyed from `getPrivateKeyFromIndex(i + 3)` (indices 0..2 are reserved for the setup account,
+ * bootstrap node, and prover node, matching the `P2PNetworkTest` convention). This replaces the
+ * `times(N, i => ({ attester, withdrawer, privateKey, bn254SecretKey }))` block copy-pasted in every
+ * direct multi-validator test.
+ */
+export function buildMockGossipValidators(count: number): RegisteredValidator[] {
+  return times(count, i => {
+    const privateKey = bufferToHex(getPrivateKeyFromIndex(i + 3)!);
+    const attester = EthAddress.fromString(privateKeyToAccount(privateKey).address);
+    return { attester, withdrawer: attester, privateKey, bn254SecretKey: new SecretValue(Fr.random().toBigInt()) };
+  });
+}
+
+/**
+ * The shared `setup` cluster for the multi-validator tests that run a tight committee on the
+ * in-memory mock-gossip bus without a prover (block-production / recovery tests). Spread into the `setup`
+ * call alongside `initialValidators` (from {@link buildMockGossipValidators}). Tests that want a
+ * prover (MBPS / HA-sync) leave `startProverNode` explicit rather than adopting this preset's `false`.
+ */
+export const MOCK_GOSSIP_MULTI_VALIDATOR_OPTS = {
+  mockGossipSubNetwork: true,
+  skipInitialSequencer: true,
+  startProverNode: false,
+  aztecProofSubmissionEpochs: NO_REORG_SUBMISSION_EPOCHS,
+  numberOfAccounts: 0,
+} as const;
+
+/**
+ * The `setup` preset for a slasher-enabled committee on the in-memory mock-gossip bus, used by the
+ * offense-detection tests (`slashing/`). Mirrors {@link MOCK_GOSSIP_MULTI_VALIDATOR_OPTS} but turns
+ * the slasher on; spread alongside `initialValidators` (from {@link buildMockGossipValidators}) and
+ * the per-test slashing-round/penalty config.
+ */
+export const SLASHER_ENABLED_MULTI_VALIDATOR_OPTS = {
+  mockGossipSubNetwork: true,
+  skipInitialSequencer: true,
+  slasherEnabled: true,
+} as const;
+
+/** The slasher and slashing-proposer L1 contracts a slashing test interacts with. */
+export type SlashingContracts = {
+  rollup: RollupContract;
+  slasherContract: GetContractReturnType<typeof SlasherAbi, ViemClient>;
+  slashingProposer: SlashingProposerContract | undefined;
+};
+
+/** The per-offense penalty knobs a slashing test tunes; all default to a single `unit`. */
+export type SlashingPenalties = {
+  slashInactivityPenalty: bigint;
+  slashDataWithholdingPenalty: bigint;
+  slashBroadcastedInvalidBlockPenalty: bigint;
+  slashBroadcastedInvalidCheckpointProposalPenalty: bigint;
+  slashDuplicateProposalPenalty: bigint;
+  slashDuplicateAttestationPenalty: bigint;
+  slashProposeInvalidAttestationsPenalty: bigint;
+  slashProposeDescendantOfCheckpointWithInvalidAttestationsPenalty: bigint;
+  slashAttestInvalidCheckpointProposalPenalty: bigint;
+  slashUnknownPenalty: bigint;
+};
+
+/** The names of every per-offense penalty knob, in declaration order. */
+const SLASHING_PENALTY_KEYS: (keyof SlashingPenalties)[] = [
+  'slashInactivityPenalty',
+  'slashDataWithholdingPenalty',
+  'slashBroadcastedInvalidBlockPenalty',
+  'slashBroadcastedInvalidCheckpointProposalPenalty',
+  'slashDuplicateProposalPenalty',
+  'slashDuplicateAttestationPenalty',
+  'slashProposeInvalidAttestationsPenalty',
+  'slashProposeDescendantOfCheckpointWithInvalidAttestationsPenalty',
+  'slashAttestInvalidCheckpointProposalPenalty',
+  'slashUnknownPenalty',
+];
+
+/**
+ * Returns every per-offense slashing penalty set to `unit` (default `1e14` — small enough not to
+ * kick a validator out). Spread alongside the slashing-round/quorum config in a slashing test's
+ * `setup`.
+ */
+export function defaultSlashingPenalties(unit: bigint = BigInt(1e14)): SlashingPenalties {
+  return Object.fromEntries(SLASHING_PENALTY_KEYS.map(key => [key, unit])) as SlashingPenalties;
+}
+
+/**
+ * Returns the penalties with only `offense` set to `unit` and every other offense zeroed out, so a
+ * test isolates a single slashing offense. Names the test's intent (which offense is under test) and
+ * replaces the ~9-line manual zero-out block.
+ */
+export function withOnlyOffense(offense: keyof SlashingPenalties, unit: bigint = BigInt(1e14)): SlashingPenalties {
+  return Object.fromEntries(SLASHING_PENALTY_KEYS.map(key => [key, key === offense ? unit : 0n])) as SlashingPenalties;
+}
+
+/** One HA pair: its two member nodes, the two shared validator keys, and the per-node coinbases. */
+export type HaPairNodes = {
+  nodes: [AztecNodeService, AztecNodeService];
+  privateKeys: [`0x${string}`, `0x${string}`];
+  coinbases: [EthAddress, EthAddress];
+};
+
+/**
+ * Stands up two HA pairs from the first four registered validators: nodes[0]/nodes[1] share keys
+ * pk1+pk2, nodes[2]/nodes[3] share pk3+pk4. Each pair shares an in-memory slashing-protection DB (so
+ * only one peer signs per duty) and each node gets a distinct coinbase. Encapsulates the ~40-line
+ * pair-wiring duplicated by both HA tests; the per-test divergence (publishing disabled vs. enabled,
+ * empty-checkpoint building) is passed through `baseOpts`.
+ * @returns The four nodes flat, plus the two `HaPairNodes` descriptors.
+ */
+export async function setupHaPairs(
+  test: MultiNodeTestContext,
+  validators: RegisteredValidator[],
+  opts: { baseOpts?: Partial<AztecNodeConfig> & { dontStartSequencer?: boolean }; coinbases?: EthAddress[] } = {},
+): Promise<{ nodes: AztecNodeService[]; pairs: [HaPairNodes, HaPairNodes] }> {
+  const baseOpts = opts.baseOpts ?? {};
+  const coinbases = opts.coinbases ?? [1, 2, 3, 4].map(n => EthAddress.fromNumber(n));
+  const [pk1, pk2, pk3, pk4] = validators.map(v => v.privateKey);
+  const sharedDb1 = await createSharedSlashingProtectionDb(test.context.dateProvider);
+  const sharedDb2 = await createSharedSlashingProtectionDb(test.context.dateProvider);
+
+  const nodes = [
+    await test.createValidatorNode([pk1, pk2], {
+      ...baseOpts,
+      coinbase: coinbases[0],
+      slashingProtectionDb: sharedDb1,
+    }),
+    await test.createValidatorNode([pk1, pk2], {
+      ...baseOpts,
+      coinbase: coinbases[1],
+      slashingProtectionDb: sharedDb1,
+    }),
+    await test.createValidatorNode([pk3, pk4], {
+      ...baseOpts,
+      coinbase: coinbases[2],
+      slashingProtectionDb: sharedDb2,
+    }),
+    await test.createValidatorNode([pk3, pk4], {
+      ...baseOpts,
+      coinbase: coinbases[3],
+      slashingProtectionDb: sharedDb2,
+    }),
+  ];
+
+  const pairs: [HaPairNodes, HaPairNodes] = [
+    { nodes: [nodes[0], nodes[1]], privateKeys: [pk1, pk2], coinbases: [coinbases[0], coinbases[1]] },
+    { nodes: [nodes[2], nodes[3]], privateKeys: [pk3, pk4], coinbases: [coinbases[2], coinbases[3]] },
+  ];
+
+  return { nodes, pairs };
+}
+
+/**
+ * Multi-validator test base: N validator nodes sharing the in-memory `MockGossipSubNetwork` bus, with
+ * fast block times and short epochs. Extends {@link SingleNodeTestContext} with validator-node
+ * spawning and the convergence helpers (`waitForAllNodes*`, `findSlotsWithProposers`) that only make
+ * sense across a committee. The environment, prover lifecycle, and reorg/proving waiters live on the
+ * parent so the single-node-topology tests share them.
+ */
+export class MultiNodeTestContext extends SingleNodeTestContext {
+  /**
+   * The validators registered on-chain at genesis (from `opts.initialValidators`). Tests spawn nodes
+   * for whichever validators they want online via {@link createValidatorNodeAt}; the rest stay
+   * registered-but-offline. Empty for single-validator-less topologies.
+   */
+  public validators: RegisteredValidator[] = [];
+
+  public override async setup(opts: MultiNodeTestOpts = {}) {
+    this.validators = (opts.initialValidators as RegisteredValidator[] | undefined) ?? [];
+    await super.setup(opts);
+  }
+
+  public createValidatorNode(
+    privateKeys: `0x${string}`[],
+    opts: Partial<AztecNodeConfig> & {
+      dontStartSequencer?: boolean;
+      slashingProtectionDb?: SlashingProtectionDatabase;
+    } = {},
+  ) {
+    this.logger.warn('Creating and syncing a validator node...');
+    return this.createNode({ ...opts, disableValidator: false, validatorPrivateKeys: new SecretValue(privateKeys) });
+  }
+
+  /** Returns the validator registered at on-chain index `index` (0-based into {@link validators}). */
+  public validatorAt(index: number): RegisteredValidator {
+    return this.validators[index];
+  }
+
+  /** The L1 attester address of the validator registered at `index`. */
+  public addressAt(index: number): EthAddress {
+    return this.validators[index].attester;
+  }
+
+  /** The L1 signing key of the validator registered at `index`. */
+  public privateKeyAt(index: number): `0x${string}` {
+    return this.validators[index].privateKey;
+  }
+
+  /**
+   * Spawns a validator node on the mock-gossip bus signing with the validator registered at `index`.
+   * Pass the same `index` to two calls (with different `coinbase`) to model an equivocating proposer
+   * that shares a key across two nodes.
+   */
+  public createValidatorNodeAt(
+    index: number,
+    opts: Partial<AztecNodeConfig> & { dontStartSequencer?: boolean } = {},
+  ): Promise<AztecNodeService> {
+    return this.createValidatorNode([this.privateKeyAt(index)], opts);
+  }
+
+  /** Resolves the rollup, slasher, and slashing-proposer L1 contracts a slashing test interacts with. */
+  public async getSlashingContracts(): Promise<SlashingContracts> {
+    const rollup = this.rollup;
+    const slasherContract = getContract({
+      address: getAddress((await rollup.getSlasherAddress()).toString()),
+      abi: SlasherAbi,
+      client: this.l1Client,
+    });
+    const slashingProposer = await rollup.getSlashingProposer();
+    return { rollup, slasherContract, slashingProposer };
+  }
+
+  /**
+   * Polls every node until `predicate(tips, node)` holds for all of them. The multi-node
+   * generalization of {@link SingleNodeTestContext.waitForNodeToSync} — replaces hand-rolled
+   * `Promise.all(this.nodes.map(node => retryUntil(...)))` fan-out blocks.
+   * @param nodes - Nodes to poll; defaults to all validator nodes (`this.nodes`).
+   */
+  public async waitForAllNodes(
+    predicate: (tips: L2Tips, node: AztecNode) => boolean | Promise<boolean>,
+    opts: { nodes?: AztecNode[]; timeout?: number; interval?: number; description?: string } = {},
+  ): Promise<void> {
+    const nodes = opts.nodes ?? this.nodes;
+    const timeout = opts.timeout ?? this.L2_SLOT_DURATION_IN_S * 4;
+    const interval = opts.interval ?? 0.5;
+    const description = opts.description ?? 'all nodes to reach target';
+    await Promise.all(
+      nodes.map((node, idx) =>
+        retryUntil(
+          async () => {
+            const tips = await node.getChainTips();
+            return (await predicate(tips, node)) || undefined;
+          },
+          `node ${idx} ${description}`,
+          timeout,
+          interval,
+        ),
+      ),
+    );
+  }
+
+  /** Waits until every node's proven checkpoint tip reaches `target`. */
+  public waitForAllNodesToReachProvenCheckpoint(
+    target: CheckpointNumber,
+    opts: { nodes?: AztecNode[]; timeout?: number; interval?: number } = {},
+  ): Promise<void> {
+    return testSpan('wait:proven-checkpoint', () =>
+      this.waitForAllNodes(tips => tips.proven.checkpoint.number >= target, {
+        ...opts,
+        description: `proven checkpoint >= ${target}`,
+      }),
+    );
+  }
+
+  /** Waits until every node's checkpointed checkpoint tip reaches `target`. */
+  public waitForAllNodesToReachCheckpoint(
+    target: CheckpointNumber,
+    opts: { nodes?: AztecNode[]; timeout?: number; interval?: number } = {},
+  ): Promise<void> {
+    return testSpan('wait:checkpoint', () =>
+      this.waitForAllNodes(tips => tips.checkpointed.checkpoint.number >= target, {
+        ...opts,
+        description: `checkpointed checkpoint >= ${target}`,
+      }),
+    );
+  }
+
+  /**
+   * Waits until every node's `proposed` or `checkpointed` tip points at a block whose slot
+   * satisfies `match` (defaults to "slot equals `slot`"). Polls the block referenced by the tip.
+   */
+  public waitForAllNodesToReachBlockAtSlot(
+    slot: SlotNumber,
+    tag: 'proposed' | 'checkpointed',
+    match: (block: BlockResponse) => boolean = block => block.header.globalVariables.slotNumber === slot,
+    opts: { nodes?: AztecNode[]; timeout?: number; interval?: number } = {},
+  ): Promise<void> {
+    return testSpan('wait:block', () =>
+      this.waitForAllNodes(
+        async (tips, node) => {
+          const blockNumber = tag === 'proposed' ? tips.proposed.number : tips.checkpointed.block.number;
+          if (blockNumber === 0) {
+            return false;
+          }
+          const block = await node.getBlock(blockNumber);
+          return !!block && match(block);
+        },
+        { ...opts, description: `${tag} block at slot ${slot}` },
+      ),
+    );
+  }
+
+  /**
+   * Finds `count` consecutive slots (starting from `opts.fromSlot` or the current slot plus a
+   * margin) whose proposers satisfy `predicate`, warping the L1 clock forward one epoch and
+   * retrying when the rollup reports `ValidatorSelection__EpochNotStable` for a future epoch.
+   * Returns the matched slots and their proposer addresses. Encapsulates the slot-search loop
+   * duplicated across the multi-validator tests.
+   */
+  public findSlotsWithProposers(
+    count: number,
+    predicate: (proposers: EthAddress[]) => boolean,
+    opts: { fromSlot?: SlotNumber; margin?: number; maxAttempts?: number } = {},
+  ): Promise<{ slots: SlotNumber[]; proposers: EthAddress[] }> {
+    return testSpan('warp:find-proposer', async () => {
+      const margin = opts.margin ?? 4;
+      const maxAttempts = opts.maxAttempts ?? 200;
+      let candidate = opts.fromSlot ?? SlotNumber(Number(this.epochCache.getEpochAndSlotNow().slot) + margin);
+
+      for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+          const slots = Array.from({ length: count }, (_, i) => SlotNumber(candidate + i));
+          const maybeProposers = await Promise.all(
+            slots.map(slot => this.epochCache.getProposerAttesterAddressInSlot(slot)),
+          );
+          if (maybeProposers.every((p): p is EthAddress => p !== undefined) && predicate(maybeProposers)) {
+            return { slots, proposers: maybeProposers };
+          }
+          candidate = SlotNumber(candidate + 1);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          if (!msg.includes('EpochNotStable')) {
+            throw err;
+          }
+          const block = await this.l1Client.getBlock({ includeTransactions: false });
+          const warpBy = this.epochDuration * this.L2_SLOT_DURATION_IN_S;
+          const newTs = Number(block.timestamp) + warpBy;
+          this.logger.warn(
+            `Hit EpochNotStable at candidate ${candidate}, warping L1 forward by ${warpBy}s to ${newTs}`,
+          );
+          await this.context.cheatCodes.eth.warp(newTs, { resetBlockInterval: true });
+          const newCurrentSlot = Number(this.epochCache.getEpochAndSlotNow().slot);
+          if (candidate < newCurrentSlot + margin) {
+            candidate = SlotNumber(newCurrentSlot + margin);
+          }
+        }
+      }
+      throw new Error(
+        `Could not find ${count} consecutive slots matching the proposer predicate after ${maxAttempts} attempts`,
+      );
+    });
+  }
+
+  /**
+   * Watches the sequencers of `nodes` via {@link SingleNodeTestContext.watchSequencerEvents}, pulling
+   * the {@link SequencerClient} off each node first. `getMetadata` tags each captured event; it
+   * defaults to `{ validator: this.validators[i].attester }`. Pass an override for tests that label
+   * their nodes differently (e.g. `['A','B','C'][i]`).
+   */
+  public watchNodeSequencerEvents(
+    nodes: AztecNodeService[],
+    getMetadata: (i: number) => Record<string, any> = i => ({ validator: this.validators[i].attester }),
+  ): { failEvents: TrackedSequencerEvent[]; stateChanges: TrackedSequencerEvent[] } {
+    return this.watchSequencerEvents(this.getSequencers(nodes), getMetadata);
+  }
+
+  /**
+   * Waits until matching slash offenses have converged across `nodes`, polling `getSlashOffenses`.
+   * With `opts.mode === 'all'` (the default) every node must record a matching offense; with `'any'`
+   * a single node suffices. Resolves with all matching offenses collected across the polled nodes.
+   */
+  public waitForOffenseOnNodes(
+    nodes: AztecNodeService[],
+    match: (offense: Offense) => boolean,
+    opts: { mode?: 'all' | 'any'; timeout?: number; interval?: number } = {},
+  ): Promise<Offense[]> {
+    const mode = opts.mode ?? 'all';
+    const timeout = opts.timeout ?? this.L2_SLOT_DURATION_IN_S * 4;
+    const interval = opts.interval ?? 0.5;
+    return testSpan('wait:offense', () =>
+      retryUntil(
+        async () => {
+          const perNode = await Promise.all(
+            nodes.map(node => node.getSlashOffenses('all').then(os => os.filter(match))),
+          );
+          const converged =
+            mode === 'all' ? perNode.every(matches => matches.length > 0) : perNode.some(m => m.length > 0);
+          return converged ? perNode.flat() : undefined;
+        },
+        `offense on ${mode} node(s)`,
+        timeout,
+        interval,
+      ),
+    );
+  }
+}