@aztec/end-to-end 5.0.0-rc.2 → 5.0.1

package/src/fixtures/standard_contracts_genesis.ts

@@ -0,0 +1,28 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+import { getPublishableStandardContracts } from '@aztec/standard-contracts';
+import { siloNullifier } from '@aztec/stdlib/hash';
+
+/**
+ * Computes the genesis nullifiers that pre-publish the standard contracts (AuthRegistry, PublicChecks,
+ * HandshakeRegistry) in e2e environments, mirroring the nullifiers their on-chain publish txs would emit. Per contract:
+ * - `siloNullifier(ContractClassRegistry, classId)` — the class-registration nullifier that `ContractClassRegistry.publish` pushes.
+ * - `siloNullifier(ContractInstanceRegistry, instanceAddress)` — the instance-deployment nullifier that
+ *   `ContractInstanceRegistry.publish_for_public_execution` pushes, using the contract's real derived address (standard
+ *   contracts are deployed at artifact-derived addresses, not magic protocol addresses).
+ *
+ * Seed these into the genesis nullifier tree (as the 5th `getGenesisValues` arg) alongside the archiver's
+ * `testPreloadStandardContracts` preload: the store preload makes the `ensure*Published` guards short-circuit, and these
+ * nullifiers make the AVM's deployment-nullifier check pass when the contracts are called. Every e2e node genesis that
+ * feeds an L1 `genesisArchiveRoot` must seed the same set, or the world-state root diverges from the deployed rollup.
+ */
+export async function getStandardContractGenesisNullifiers(): Promise<Fr[]> {
+  const classRegistry = ProtocolContractAddress.ContractClassRegistry;
+  const instanceRegistry = ProtocolContractAddress.ContractInstanceRegistry;
+  const nullifiers: Fr[] = [];
+  for (const { contractClass, address } of await getPublishableStandardContracts()) {
+    nullifiers.push(await siloNullifier(classRegistry, contractClass.id));
+    nullifiers.push(await siloNullifier(instanceRegistry, address.toField()));
+  }
+  return nullifiers;
+}

package/src/fixtures/timing.ts

@@ -0,0 +1,97 @@
+/**
+ * E2e span instrumentation. Wrapping a shared test helper in {@link testSpan} / {@link testSpanSync}
+ * records how long it ran, attributed to the test (or suite) that was executing, so a full CI run can
+ * be aggregated into a ranked list of where the suite spends wall-clock (setup, protocol waits, client
+ * proving, warp scans, ...). See the A-1178 timing environment in `shared/timing_env.mjs`.
+ *
+ * Everything here is gated on the collector installed by that environment, which only exists when
+ * `TEST_TIMING_FILE` is set. When it is unset, {@link testSpan} calls `fn()` directly with no extra work
+ * and no clock reads — instrumentation is exactly zero-cost and cannot change a test's behavior or
+ * timing.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Async-context owner override. A span normally attributes itself to the running test
+ * (`collector.current`), but a background producer (e.g. the mempool feeder) runs interleaved with
+ * arbitrary tests, so its spans would smear across whichever test happened to be current when each
+ * round fired. Running such work inside {@link withTestSpanOwner} pins every span in that async call
+ * tree to a fixed owner instead — isolated by async context from concurrent test-body spans.
+ */
+const ownerOverride = new AsyncLocalStorage<string | null>();
+
+/**
+ * Runs `fn` with every {@link testSpan} inside its async call tree attributed to `owner` instead of the
+ * currently running test. Use a non-test sentinel owner (e.g. `other:mempool-feeder`) to keep a
+ * background producer's spans out of the per-test view.
+ */
+export function withTestSpanOwner<T>(owner: string, fn: () => Promise<T>): Promise<T> {
+  return ownerOverride.run(owner, fn);
+}
+
+/** One recorded span occurrence on the process-wide `performance.now()` clock. */
+export type TimingSpan = {
+  /** Full name of the test running when the span started, or `null` if inside a beforeAll/afterAll hook. */
+  owner: string | null;
+  /** Stable `category:label` tag, aggregated across occurrences (e.g. `wait:checkpoint`, `setup:node`). */
+  name: string;
+  /** `performance.now()` at span start. */
+  start: number;
+  /** `performance.now()` at span end. */
+  end: number;
+};
+
+/**
+ * The collector shared by the timing environment on `globalThis.__e2eTimings`. `current` is the full
+ * name of the test currently running (`null` during beforeAll/afterAll); the environment sets it. The
+ * `spans` array accumulates every recorded span until the environment folds it into the per-test /
+ * per-suite JSONL line at flush.
+ */
+export type SpanCollector = {
+  /** Full name of the running test, or `null` during a beforeAll/afterAll hook. */
+  current: string | null;
+  /** All recorded spans, drained by the timing environment at flush time. */
+  spans: TimingSpan[];
+};
+
+function getCollector(): SpanCollector | undefined {
+  return (globalThis as { __e2eTimings?: SpanCollector }).__e2eTimings;
+}
+
+/**
+ * Times `fn` and records a span tagged `name`, attributed to the test (or suite) running when it
+ * started. The span is recorded even when `fn` throws. Pure passthrough: when no collector is
+ * installed (i.e. `TEST_TIMING_FILE` is unset) this calls `fn()` directly with zero overhead.
+ *
+ * Use stable `category:label` tags and prefer wrapping at the leaf wait/setup/tx level — labels are
+ * forever aggregation keys, and leaf-level tagging keeps spans additive. See `SPEEDUP_FOLLOWUPS` and
+ * the A-1179 design doc for the tag taxonomy.
+ */
+export async function testSpan<T>(name: string, fn: () => Promise<T>): Promise<T> {
+  const collector = getCollector();
+  if (!collector) {
+    return fn();
+  }
+  const owner = ownerOverride.getStore() ?? collector.current;
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    collector.spans.push({ owner, name, start, end: performance.now() });
+  }
+}
+
+/** Synchronous variant of {@link testSpan} for non-async helpers. Same zero-cost guarantee when unset. */
+export function testSpanSync<T>(name: string, fn: () => T): T {
+  const collector = getCollector();
+  if (!collector) {
+    return fn();
+  }
+  const owner = ownerOverride.getStore() ?? collector.current;
+  const start = performance.now();
+  try {
+    return fn();
+  } finally {
+    collector.spans.push({ owner, name, start, end: performance.now() });
+  }
+}

package/src/fixtures/wait_helpers.ts

@@ -0,0 +1,333 @@
+import type { WaitOpts } from '@aztec/aztec.js/contracts';
+import type { Fr } from '@aztec/aztec.js/fields';
+import { waitForTx } from '@aztec/aztec.js/node';
+import { INITIAL_L2_BLOCK_NUM } from '@aztec/aztec.js/protocol';
+import type { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { promiseWithResolvers } from '@aztec/foundation/promise';
+import { retryUntil } from '@aztec/foundation/retry';
+import type { Sequencer, SequencerEvents, SequencerState } from '@aztec/sequencer-client';
+import type { L2BlockTag } from '@aztec/stdlib/block';
+import type { AztecNode, CheckpointTag } from '@aztec/stdlib/interfaces/client';
+import type { L2ToL1MembershipWitness } from '@aztec/stdlib/messaging';
+import type { TxHash, TxReceipt, TxStatus } from '@aztec/stdlib/tx';
+
+import { testSpan } from './timing.js';
+
+/** Options for the block-number polling helpers. */
+export type WaitForBlockOpts = {
+  /** Which chain tip to read; defaults to 'proposed'. */
+  tag?: L2BlockTag;
+  /** How the node's block number must relate to `target`; defaults to `(actual, target) => actual >= target`. */
+  compare?: (actual: number, target: number) => boolean;
+  /** Seconds before the poll rejects; defaults to 60. */
+  timeout?: number;
+  /** Seconds between polls; defaults to 0.25. */
+  interval?: number;
+};
+
+/**
+ * Polls `node.getBlockNumber(tag)` until `opts.compare(actual, target)` holds (default `>=`). Replaces
+ * the ad-hoc `retryUntil(() => node.getBlockNumber(tag) <op> target)` polls scattered across the suite,
+ * where the node may sync forward or prune backward — the caller passes the comparator for whichever it
+ * expects.
+ * @returns The block number once the comparison holds.
+ */
+export function waitForBlockNumber(node: AztecNode, target: number, opts: WaitForBlockOpts = {}): Promise<BlockNumber> {
+  const tag = opts.tag ?? 'proposed';
+  const compare = opts.compare ?? ((actual, target) => actual >= target);
+  return testSpan(`wait:${tag}`, () =>
+    // Wrap the matched value: retryUntil treats any falsy return as "keep polling", so a legitimate
+    // match of block 0 (e.g. a freshly-pruned tip) would otherwise loop until timeout.
+    retryUntil(
+      async () => {
+        const blockNumber = await node.getBlockNumber(tag);
+        return compare(blockNumber, target) ? { blockNumber } : undefined;
+      },
+      `block ${tag} ${compare} ${target}`,
+      opts.timeout ?? 60,
+      opts.interval ?? 0.25,
+    ).then(({ blockNumber }) => blockNumber),
+  );
+}
+
+/** Convenience for {@link waitForBlockNumber} on the proven tip. */
+export function waitForProvenBlock(
+  node: AztecNode,
+  target: number,
+  opts: Omit<WaitForBlockOpts, 'tag'> = {},
+): Promise<BlockNumber> {
+  return waitForBlockNumber(node, target, { ...opts, tag: 'proven' });
+}
+
+/** Compares the node's checkpoint number against the target; defaults to `>=`. */
+export type CheckpointComparator = (actual: number, target: number) => boolean;
+
+/** Options for {@link waitForNodeCheckpoint}. */
+export type WaitForCheckpointOpts = {
+  /** Which checkpoint tip to read; defaults to 'checkpointed'. */
+  tag?: CheckpointTag;
+  /** How the node's checkpoint number must relate to `target`; defaults to `(actual, target) => actual >= target`. */
+  compare?: CheckpointComparator;
+  /** Seconds before the poll rejects; defaults to 30. */
+  timeout?: number;
+  /** Seconds between polls; defaults to 0.5. */
+  interval?: number;
+};
+
+/**
+ * Polls a single node's checkpoint number until `opts.compare(actual, target)` holds. Replaces the
+ * `retryUntil(() => node.getChainTips().then(tips => tips.<tag>.checkpoint.number <op> target))` polls
+ * duplicated across the reorg/proving tests, where the node may sync forward, prune backward, or land
+ * exactly on a value — the caller passes the comparator lambda for whichever it expects.
+ * @returns The node's checkpoint number once the comparison holds.
+ */
+export function waitForNodeCheckpoint(
+  node: AztecNode,
+  target: number,
+  opts: WaitForCheckpointOpts = {},
+): Promise<CheckpointNumber> {
+  const tag = opts.tag ?? 'checkpointed';
+  const compare = opts.compare ?? ((actual, target) => actual >= target);
+  return testSpan(tag === 'proven' ? 'wait:proven-checkpoint' : 'wait:checkpoint', () =>
+    // Wrap the matched value: retryUntil treats any falsy return as "keep polling", so a legitimate
+    // match of checkpoint 0 (e.g. proven === 0 or checkpointed <= 1 after a prune) would otherwise
+    // loop until timeout instead of resolving.
+    retryUntil(
+      async () => {
+        const checkpointNumber = await node.getCheckpointNumber(tag);
+        return compare(checkpointNumber, target) ? { checkpointNumber } : undefined;
+      },
+      `node checkpoint ${tag} ${compare} ${target}`,
+      opts.timeout ?? 30,
+      opts.interval ?? 0.5,
+    ).then(({ checkpointNumber }) => checkpointNumber),
+  );
+}
+
+/** Convenience for {@link waitForNodeCheckpoint} on the proven tip. */
+export function waitForNodeProvenCheckpoint(
+  node: AztecNode,
+  target: number,
+  opts: Omit<WaitForCheckpointOpts, 'tag'> = {},
+): Promise<CheckpointNumber> {
+  return waitForNodeCheckpoint(node, target, { ...opts, tag: 'proven' });
+}
+
+/**
+ * Waits for all of `txHashes` to reach the desired status on `node`. The plural form of
+ * {@link waitForTx}; resolves with the receipts in input order.
+ */
+export function waitForTxs(node: AztecNode, txHashes: TxHash[], opts?: WaitOpts): Promise<TxReceipt[]> {
+  const optsWithInterval = { ...opts, interval: opts?.interval ?? 0.25 };
+  return testSpan('wait:tx-mined', () =>
+    Promise.all(txHashes.map(txHash => waitForTx(node, txHash, optsWithInterval))),
+  );
+}
+
+/** Options for {@link waitForBlocksAtSlots}. */
+export type WaitForBlocksAtSlotsOpts = {
+  /** Block number to start scanning from; defaults to the initial L2 block. */
+  from?: BlockNumber;
+  /** How many blocks to fetch per poll; defaults to 10. */
+  limit?: number;
+  /** Seconds before the poll rejects; defaults to 20. */
+  timeout?: number;
+  /** Seconds between polls; defaults to 0.25. */
+  interval?: number;
+};
+
+/**
+ * Polls `node.getBlocks` until every slot in `slots` is present among the fetched blocks' slot
+ * numbers. Replaces the hand-rolled `retryUntil` over `getBlocks(...).map(getSlot)` membership check.
+ */
+export async function waitForBlocksAtSlots(
+  node: AztecNode,
+  slots: SlotNumber[],
+  opts: WaitForBlocksAtSlotsOpts = {},
+): Promise<void> {
+  const from = opts.from ?? INITIAL_L2_BLOCK_NUM;
+  const limit = opts.limit ?? 10;
+  await testSpan('wait:block', () =>
+    retryUntil(
+      async () => {
+        const blocks = await node.getBlocks(from, limit);
+        const foundSlots = blocks.map(block => block.header.getSlot());
+        return slots.every(slot => foundSlots.includes(slot)) || undefined;
+      },
+      `blocks at slots ${slots.join(', ')}`,
+      opts.timeout ?? 20,
+      opts.interval ?? 0.25,
+    ),
+  );
+}
+
+/**
+ * Polls `node.getL2ToL1MembershipWitness(txHash, message)` until a witness is available, resolving
+ * with it. Wraps the `retryUntil` the cross-chain tests hand-roll while waiting for an L2-to-L1
+ * message's membership witness to become provable.
+ */
+export function waitForL2ToL1Witness(
+  node: AztecNode,
+  txHash: TxHash,
+  message: Fr,
+  opts: { timeout?: number; interval?: number } = {},
+): Promise<L2ToL1MembershipWitness> {
+  return testSpan('wait:l2-to-l1-witness', () =>
+    retryUntil(
+      () => node.getL2ToL1MembershipWitness(txHash, message),
+      `L2-to-L1 membership witness for ${txHash.toString()}`,
+      opts.timeout ?? 30,
+      opts.interval ?? 0.25,
+    ),
+  );
+}
+
+/** Options for the tx-receipt polling helpers. */
+export type WaitForTxReceiptOpts = {
+  /** Seconds before the poll rejects; defaults to 30. */
+  timeout?: number;
+  /** Seconds between polls; defaults to 0.25. */
+  interval?: number;
+};
+
+/**
+ * Polls `node.getTxReceipt(txHash)` until `predicate(receipt)` holds, resolving with the receipt.
+ * Wraps the `retryUntil` that the block-building reorg tests hand-roll while waiting for a tx to
+ * transition between statuses (pruned, re-included, ...).
+ * @returns The receipt once the predicate holds.
+ */
+export function waitForTxReceipt(
+  node: AztecNode,
+  txHash: TxHash,
+  predicate: (receipt: TxReceipt) => boolean,
+  opts: WaitForTxReceiptOpts = {},
+): Promise<TxReceipt> {
+  return testSpan('wait:tx-mined', () =>
+    retryUntil(
+      async () => {
+        const receipt = await node.getTxReceipt(txHash);
+        return predicate(receipt) ? { receipt } : undefined;
+      },
+      `tx receipt for ${txHash.toString()}`,
+      opts.timeout ?? 30,
+      opts.interval ?? 0.25,
+    ).then(({ receipt }) => receipt),
+  );
+}
+
+/** Polls until `node.getTxReceipt(txHash).status === status`. Thin wrapper over {@link waitForTxReceipt}. */
+export function waitForTxStatus(
+  node: AztecNode,
+  txHash: TxHash,
+  status: TxStatus,
+  opts: WaitForTxReceiptOpts = {},
+): Promise<TxReceipt> {
+  return waitForTxReceipt(node, txHash, receipt => receipt.status === status, opts);
+}
+
+/** Compares the node's pending-tx count against the target; defaults to `>=`. */
+export type PendingTxCountComparator = (actual: number, target: number) => boolean;
+
+/** Options for {@link waitForPendingTxCount}. */
+export type WaitForPendingTxCountOpts = {
+  /** How the node's pending-tx count must relate to `target`; defaults to `(actual, target) => actual >= target`. */
+  compare?: PendingTxCountComparator;
+  /** Seconds before the poll rejects; defaults to 30. */
+  timeout?: number;
+  /** Seconds between polls; defaults to 0.25. */
+  interval?: number;
+};
+
+/**
+ * Polls `node.getPendingTxCount()` until `opts.compare(actual, target)` holds (default `>=`).
+ * Replaces the hand-rolled mempool-size poll in the slashing tests.
+ * @returns The pending-tx count once the comparison holds.
+ */
+export function waitForPendingTxCount(
+  node: AztecNode,
+  target: number,
+  opts: WaitForPendingTxCountOpts = {},
+): Promise<number> {
+  const compare = opts.compare ?? ((actual, target) => actual >= target);
+  return testSpan('wait:pending-tx', () =>
+    // Wrap the matched value: retryUntil treats any falsy return as "keep polling", so a legitimate
+    // match of 0 pending txs would otherwise loop until timeout instead of resolving.
+    retryUntil(
+      async () => {
+        const count = await node.getPendingTxCount();
+        return compare(count, target) ? { count } : undefined;
+      },
+      `pending tx count ${compare} ${target}`,
+      opts.timeout ?? 30,
+      opts.interval ?? 0.25,
+    ).then(({ count }) => count),
+  );
+}
+
+/** Options for {@link waitForSequencerState}. */
+export type WaitForSequencerStateOpts = {
+  /** Milliseconds before the wait rejects; defaults to 30000. */
+  timeout?: number;
+  /**
+   * Action to run after subscribing to the sequencer but before awaiting the transition. Subscribing
+   * first guarantees the state change the action triggers is not missed between the action and the
+   * listener attaching.
+   */
+  after?: () => unknown;
+};
+
+/**
+ * Resolves once `sequencer` reaches `state`. Subscribes to the `state-changed` event first, then (if
+ * `opts.after` is given) runs the action, then resolves immediately if the sequencer is already at
+ * `state`, otherwise waits for the transition. The listener is cleaned up on both resolve and timeout.
+ * Replaces the hand-rolled `state-changed` on/off subscriptions duplicated across the fee, cross-chain,
+ * and keystore-reload tests.
+ */
+export function waitForSequencerState(
+  sequencer: Sequencer,
+  state: SequencerState,
+  opts: WaitForSequencerStateOpts = {},
+): Promise<void> {
+  return testSpan('wait:sequencer-state', () => waitForSequencerStateInner(sequencer, state, opts));
+}
+
+async function waitForSequencerStateInner(
+  sequencer: Sequencer,
+  state: SequencerState,
+  opts: WaitForSequencerStateOpts,
+): Promise<void> {
+  const timeout = opts.timeout ?? 30000;
+  const { promise, resolve, reject } = promiseWithResolvers<void>();
+
+  let settled = false;
+  const handler = (args: Parameters<SequencerEvents['state-changed']>[0]) => {
+    if (args.newState === state) {
+      finish(resolve);
+    }
+  };
+  const timer = setTimeout(
+    () => finish(() => reject(new Error(`Timeout waiting for sequencer ${state} state`))),
+    timeout,
+  );
+  function finish(complete: () => void) {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    clearTimeout(timer);
+    sequencer.off('state-changed', handler);
+    complete();
+  }
+
+  sequencer.on('state-changed', handler);
+  try {
+    await opts.after?.();
+    if (sequencer.status().state === state) {
+      finish(resolve);
+    }
+    await promise;
+  } catch (err) {
+    finish(() => {});
+    throw err;
+  }
+}

package/src/forward-compatibility/wallet_service.ts

@@ -33,9 +33,9 @@ async function main() {
   const extraAccountSalt = Fr.ZERO;
   const extraAccountSigningKey = GrumpkinScalar.random();
   const extraAccountAddress = await getSchnorrAccountContractAddress(
-    extraAccountSecret,
-    extraAccountSalt,
     extraAccountSigningKey,
+    extraAccountSalt,
+    extraAccountSecret,
   );
 
   logger.info('Starting wallet service...', { l1RpcUrls });

package/src/infra/README.md

@@ -0,0 +1,12 @@
+# `infra` e2e test category
+
+Infrastructure tests cover deployment, network targeting, and ops scenarios that are not about a
+single protocol behavior. A test belongs here when its primary concern is network targeting or
+operational smoke-testing rather than correctness of a specific consensus, block-building, or
+proving behavior.
+
+## Tests
+
+| File | Contents |
+|---|---|
+| `public_testnet_transfer.test.ts` | Deploy and transfer on a public L1 network (Sepolia) or local Anvil, parameterized by `L1_CHAIN_ID`. With no `L1_CHAIN_ID` set the test targets local Anvil and runs in CI; with Sepolia credentials (`SEQ_PUBLISHER_PRIVATE_KEY`, `ETHEREUM_HOSTS`, `L1_CHAIN_ID=11155111`) it runs against the live public testnet. |

package/src/multi-node/README.md

@@ -0,0 +1,96 @@
+# `multi-node` e2e test category
+
+Multi-node tests run N validator nodes sharing an in-memory `MockGossipSubNetwork` bus (no real
+libp2p). This is the category for any multi-node test whose subject — proposals, attestations,
+checkpointing, pruning/recovery, offense detection — is faithfully reproduced by the mock-gossip bus.
+Tests that need *real networking* (peer discovery / discv5, the req/resp protocol, gossip mesh
+formation, peer auth/scoring, transport behavior) belong in the `p2p` category instead.
+
+## Base class
+
+`MultiNodeTestContext` (`multi_node_test_context.ts`) extends `SingleNodeTestContext` (in
+`../single-node/`) with the N-validator topology:
+
+- `createValidatorNode` / `createValidatorNodeAt(index)` spawn nodes on the mock-gossip bus; passing
+  the same index to two calls (with different coinbases) models an equivocating proposer that shares
+  a key across two nodes. Validators with no spawned node stay registered-but-offline.
+- The per-validator registration accessors (`validatorAt` / `addressAt` / `privateKeyAt`) for the
+  validators registered at genesis via `initialValidators`.
+- `getSlashingContracts()` for the rollup / slasher / slashing-proposer L1 contracts.
+- The committee convergence helpers `waitForAllNodes*` and `findSlotsWithProposers`.
+
+The environment (in-process anvil + L1 deploy), the prover lifecycle, and the proving / reorg waiters
+all live on the parent and are inherited.
+
+## Shared presets and helpers
+
+These are exported from `multi_node_test_context.ts` and spread into a `setup(...)` call rather than
+copy-pasted:
+
+- `buildMockGossipValidators(n)` — the deterministic validator set (keys from
+  `getPrivateKeyFromIndex(i + 3)`), passed as `initialValidators`.
+- `MOCK_GOSSIP_MULTI_VALIDATOR_OPTS` — a tight committee on the mock bus with no prover
+  (`{ mockGossipSubNetwork, skipInitialSequencer, startProverNode: false, aztecProofSubmissionEpochs:
+  NO_REORG_SUBMISSION_EPOCHS, numberOfAccounts: 0 }`, the constant re-exported from `../single-node/setup.ts`).
+  Tests that want a prover leave `startProverNode` explicit.
+- `SLASHER_ENABLED_MULTI_VALIDATOR_OPTS` — the same committee with the slasher turned on, used by the
+  offense-detection tests.
+- `defaultSlashingPenalties(unit?)` / `withOnlyOffense(offense, unit?)` — build the per-offense
+  `slash*Penalty` knobs; `withOnlyOffense` zeroes all but the named offense to isolate one offense.
+- `setupHaPairs(test, validators, { baseOpts, coinbases })` — stands up two HA pairs (nodes 0/1 share
+  keys pk1+pk2, nodes 2/3 share pk3+pk4), each pair on a shared slashing-protection DB with distinct
+  per-node coinbases. Used by the `high-availability/` tests.
+
+## Organizing principle
+
+The top level groups tests by node topology and setup model; the second level names the primary
+behavior under test, not the shared setup or a flag. Multiple-blocks-per-slot and proposer pipelining
+are default traits of block production here, not separate categories. Each file has a single top-level
+`describe` named to match its path, and a co-located `setup.ts` holds shared setup. A `.parallel`
+suffix marks files with more than one top-level `it`; CI splits each `it` into its own job.
+
+## Subfolders
+
+| Folder | Base / preset | Contents |
+|---|---|---|
+| `block-production/` | `MultiNodeTestContext` + wide-slot / block-production timing (`setup.ts`) | Happy-path committee block production with multiple blocks per slot and pipelining as the default cadence: `simple`, `high_tps`, `first_slot` (blocks on the first two slots of an epoch), `deploy_and_call_ordering` (a contract deployed and called in separate blocks of one slot), `cross_chain_messages.parallel` (multi-block slots carrying L2→L1 and L1→L2 messages), `proposed_chain.parallel` (txs anchored to proposed blocks; non-validators re-execute and sync multi-block slots), `proof_boundary.parallel` (the proof-submission deadline vs. the pipelining boundary slot, across five proof-landing scenarios), `redistribution.parallel` (checkpoint budget redistributed so a late tx burst fits across the last blocks), `blob_promotion` (a promotion-disabled node fetches blobs while peers skip them, and a high-block-count checkpoint still proves), `multi_validator_node.parallel` (one physical node hosting 5 validator keys builds blocks and collects quorum attestations; after withdrawing 2 validators, signing is filtered to the active committee only). |
+| `recovery/` | `MultiNodeTestContext` + wide-slot / block-production timing | The chain detects a bad/withheld/conflicting proposal and recovers: `proposal_failure_recovery.parallel` (all nodes prune and recover when a proposer fails to publish to L1), `pipeline_prune` (an uncheckpointed-blocks prune under pipelined MBPS, then recovery to a multi-block checkpoint), `equivocation_recovery` (an L1-confirmed checkpoint overrides a gossip-only equivocating proposal, the chain heals, and observers record the offense). |
+| `invalid-attestations/` | `MultiNodeTestContext` (slasher on) | Invalid checkpoints are detected, invalidated on L1, and the chain progresses: `invalidate_block.parallel`, a six-validator suite injecting insufficient/fake/high-s/unrecoverable/shuffled attestations and withheld blobs. |
+| `high-availability/` | `MultiNodeTestContext` + `setupHaPairs` | HA-pair sync and handoff between nodes that share validator keys: `ha_sync` (a peer that did not build a block syncs to the proposed chain tip over P2P), `ha_checkpoint_handoff` (a peer records and takes over a pipelined checkpoint when its partner proposes the previous slot). |
+| `slashing/` | `MultiNodeTestContext` + `SLASHER_ENABLED_MULTI_VALIDATOR_OPTS` (`setup.ts`) | Offense detection and the sentinel that drives it. Equivocation — both duplicate-proposal and duplicate-attestation — (`equivocation_offenses`), broadcast of an invalid block or checkpoint proposal (`broadcasted_invalid_block_proposal_slash`, `broadcasted_invalid_checkpoint_proposal_slash.parallel`), attesting to an invalid checkpoint (`attested_invalid_proposal.parallel`), data withholding (`data_withholding_slash`), inactivity (`inactivity_slash`, `inactivity_slash_with_consecutive_epochs`, sharing the `InactivityTest` fixture in `inactivity_setup.ts`), the slasher veto path (`slash_veto_demo`), and sentinel observability (`validators_sentinel.parallel`, `multiple_validators_sentinel.parallel`, `sentinel_status_slash.parallel`). `setup.ts` holds the two timing profiles (`baseSlashingOpts`, `SENTINEL_TIMING`), the shared offense lookup (`findSlashOffense`), and the slashing waiters (`awaitCommitteeExists`, `awaitOffenseDetected`, `advanceToEpochBeforeProposer`, `findUpcomingProposerSlot`, `awaitCommitteeKicked`, `awaitProposalExecution`). |
+| `governance/` | `MultiNodeTestContext` + `MOCK_GOSSIP_MULTI_VALIDATOR_OPTS` + `GOVERNANCE_TIMING` (`setup.ts`) | A validator committee drives an L1 governance upgrade. `upgrade_governance_proposer` (the committee signals a new governance-proposer payload, reaches quorum, and the proposal executes) and `add_rollup` (a new rollup version is registered and the nodes migrate to it, exercising L1↔L2 bridging on both rollups). |
+
+## Helper surface
+
+Prefer these named waiters over hand-rolled `retryUntil` / raw `.on` / `sleep` polling in test bodies.
+
+On `SingleNodeTestContext` (inherited):
+
+- `waitUntilEpochStarts(epoch)` / `waitUntilNextEpochStarts()` — epoch-boundary waiters.
+- `waitUntilCheckpointNumber(n)` / `waitUntilProvenCheckpointNumber(n)` — checkpoint waiters.
+- `waitUntilLastSlotOfProofSubmissionWindow(epoch)` — proof-window timing.
+- `waitForNodeToSync(blockNumber, type)` — single-node sync wait.
+- `watchSequencerEvents(sequencers, …)` accumulates state-changes and fail-events across sequencers;
+  `assertNoFailuresFromSequencers(failEvents)` asserts none fired.
+- `waitForSequencerEvent(sequencer, event, match?, opts)` — one-shot wait for a matching event, with
+  timeout and listener cleanup.
+- `assertMultipleBlocksPerSlot(n)` — asserts some checkpoint has at least `n` blocks (MBPS).
+
+Added by `MultiNodeTestContext`:
+
+- `waitForAllNodes(predicate, opts)` and the conveniences
+  `waitForAllNodesToReachProvenCheckpoint(target, opts)` and
+  `waitForAllNodesToReachBlockAtSlot(slot, tag, match?, opts)` — multi-node convergence.
+- `findSlotsWithProposers(count, predicate, opts)` — finds N consecutive slots whose proposers
+  satisfy `predicate`, warping the L1 clock forward and retrying on `EpochNotStable`.
+
+On `ChainMonitor` (`@aztec/ethereum/test`):
+
+- `waitUntilCheckpoint(n)` / `waitUntilCheckpointProven(n)`, `waitUntilL2Slot(slot)`,
+  `waitUntilL1Block` / `waitUntilL1Timestamp`.
+
+Node-only / wallet-only waits (no context dependency) live in `../fixtures/wait_helpers.ts`:
+
+- `waitForBlockNumber(node, target, { tag })` / `waitForProvenBlock(node, target)`.
+- `waitForNodeCheckpoint(node, target, opts)` / `waitForNodeProvenCheckpoint(node, target)`.
+- `waitForTxs(node, txHashes, opts)` — the plural form of `waitForTx`.