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

package/src/fixtures/setup_p2p_test.ts

@@ -1,13 +1,13 @@
 /**
  * Test fixtures and utilities to set up and run a test using multiple validators
  */
-import { type AztecNodeConfig, AztecNodeService } from '@aztec/aztec-node';
+import { type AztecNodeConfig, AztecNodeService, createAztecNodeService } from '@aztec/aztec-node';
 import { range } from '@aztec/foundation/array';
 import { SecretValue } from '@aztec/foundation/config';
 import { withLoggerBindings } from '@aztec/foundation/log/server';
 import { bufferToHex } from '@aztec/foundation/string';
 import type { DateProvider } from '@aztec/foundation/timer';
-import type { PublicDataTreeLeaf } from '@aztec/stdlib/trees';
+import type { GenesisData } from '@aztec/stdlib/world-state';
 
 import getPort from 'get-port';
 
@@ -40,7 +40,7 @@ export async function createNodes(
   bootstrapNodeEnr: string,
   numNodes: number,
   bootNodePort: number,
-  prefilledPublicData?: PublicDataTreeLeaf[],
+  genesis?: GenesisData,
   dataDirectory?: string,
   metricsPort?: number,
   indexOffset = 0,
@@ -65,7 +65,7 @@ export async function createNodes(
       port,
       bootstrapNodeEnr,
       validatorIndices,
-      prefilledPublicData,
+      genesis,
       dataDir,
       metricsPort,
     );
@@ -88,6 +88,10 @@ export type CreateNodeConfig = AztecNodeConfig & {
   dontStartSequencer?: boolean;
   /** Override the private key (instead of deriving from addressIndex). */
   validatorPrivateKey?: `0x${string}`;
+  /** Corrupt only the block proposal at this indexWithinCheckpoint (testing only). */
+  invalidBlockProposalIndexWithinCheckpoint?: number;
+  /** Accept proposal gossip regardless of slot timing (testing only). */
+  skipProposalSlotValidation?: boolean;
 };
 
 /** Creates a P2P enabled instance of Aztec Node Service with a validator. */
@@ -97,7 +101,7 @@ export async function createNode(
   tcpPort: number,
   bootstrapNode: string | undefined,
   addressIndex: number | number[],
-  prefilledPublicData?: PublicDataTreeLeaf[],
+  genesis?: GenesisData,
   dataDirectory?: string,
   metricsPort?: number,
 ) {
@@ -105,10 +109,10 @@ export async function createNode(
   return await withLoggerBindings({ actor: `validator-${actorIndex}` }, async () => {
     const validatorConfig = await createValidatorConfig(config, bootstrapNode, tcpPort, addressIndex, dataDirectory);
     const telemetry = await getEndToEndTestTelemetryClient(metricsPort);
-    return await AztecNodeService.createAndSync(
+    return await createAztecNodeService(
       validatorConfig,
       { telemetry, dateProvider },
-      { prefilledPublicData, dontStartSequencer: config.dontStartSequencer },
+      { genesis, dontStartSequencer: config.dontStartSequencer },
     );
   });
 }
@@ -119,7 +123,7 @@ export async function createNonValidatorNode(
   dateProvider: DateProvider,
   tcpPort: number,
   bootstrapNode: string | undefined,
-  prefilledPublicData?: PublicDataTreeLeaf[],
+  genesis?: GenesisData,
   dataDirectory?: string,
   metricsPort?: number,
 ) {
@@ -133,7 +137,7 @@ export async function createNonValidatorNode(
       sequencerPublisherPrivateKeys: [],
     };
     const telemetry = await getEndToEndTestTelemetryClient(metricsPort);
-    return await AztecNodeService.createAndSync(config, { telemetry, dateProvider }, { prefilledPublicData });
+    return await createAztecNodeService(config, { telemetry, dateProvider }, { genesis });
   });
 }
 
@@ -143,7 +147,7 @@ export async function createProverNode(
   bootstrapNode: string | undefined,
   addressIndex: number,
   deps: { dateProvider: DateProvider },
-  prefilledPublicData?: PublicDataTreeLeaf[],
+  genesis?: GenesisData,
   dataDirectory?: string,
   metricsPort?: number,
 ): Promise<{ proverNode: AztecNodeService }> {
@@ -159,7 +163,7 @@ export async function createProverNode(
       { ...config, ...p2pConfig },
       { dataDirectory },
       { ...deps, telemetry },
-      { prefilledPublicData: prefilledPublicData ?? [] },
+      { genesis },
     );
   });
 }

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/token_utils.ts

@@ -3,14 +3,46 @@ import { BatchCall } from '@aztec/aztec.js/contracts';
 import type { Logger } from '@aztec/aztec.js/log';
 import type { Wallet } from '@aztec/aztec.js/wallet';
 import { TokenContract } from '@aztec/noir-contracts.js/Token';
+import { TestTokenContract } from '@aztec/noir-test-contracts.js/TestToken';
+
+/**
+ * Either token flavour. Canonical `TokenContract` uses constrained message delivery (production / docs
+ * source of truth); `TestTokenContract` is its codegen'd unconstrained-delivery sibling, used by tests
+ * where a token is just a unit-of-account vehicle. The two share an identical ABI, so helpers that only
+ * read balances or mint accept either.
+ */
+export type AnyTokenContract = TokenContract | TestTokenContract;
 
 export async function deployToken(wallet: Wallet, admin: AztecAddress, initialAdminBalance: bigint, logger: Logger) {
   logger.info(`Deploying Token contract...`);
-  const {
-    receipt: { contract, instance },
-  } = await TokenContract.deploy(wallet, admin, 'TokenName', 'TokenSymbol', 18).send({
+  const { contract, instance } = await TokenContract.deploy(wallet, admin, 'TokenName', 'TokenSymbol', 18).send({
+    from: admin,
+  });
+
+  if (initialAdminBalance > 0n) {
+    await mintTokensToPrivate(contract, admin, admin, initialAdminBalance);
+  }
+
+  logger.info('L2 contract deployed');
+
+  return { contract, instance };
+}
+
+/**
+ * Deploys the unconstrained-delivery `TestTokenContract`. Use this in tests where the token is a
+ * unit-of-account vehicle rather than the subject, so they don't pay constrained delivery's first-send
+ * handshake cost (which distorts step/log counts that benches assert on). Use {@link deployToken} when a
+ * test exercises canonical Token semantics or note discovery.
+ */
+export async function deployTestToken(
+  wallet: Wallet,
+  admin: AztecAddress,
+  initialAdminBalance: bigint,
+  logger: Logger,
+) {
+  logger.info(`Deploying TestToken contract...`);
+  const { contract, instance } = await TestTokenContract.deploy(wallet, admin, 'TokenName', 'TokenSymbol', 18).send({
     from: admin,
-    wait: { returnReceipt: true },
   });
 
   if (initialAdminBalance > 0n) {
@@ -23,7 +55,7 @@ export async function deployToken(wallet: Wallet, admin: AztecAddress, initialAd
 }
 
 export async function mintTokensToPrivate(
-  token: TokenContract,
+  token: AnyTokenContract,
   minter: AztecAddress,
   recipient: AztecAddress,
   amount: bigint,
@@ -34,13 +66,13 @@ export async function mintTokensToPrivate(
 
 export async function expectTokenBalance(
   wallet: Wallet,
-  token: TokenContract,
+  token: AnyTokenContract,
   owner: AztecAddress,
   expectedBalance: bigint,
   logger: Logger,
 ) {
   // Then check the balance
-  const contractWithWallet = TokenContract.at(token.address, wallet);
+  const contractWithWallet = token.withWallet(wallet);
   const { result: balance } = await contractWithWallet.methods.balance_of_private(owner).simulate({ from: owner });
   logger.info(`Account ${owner} balance: ${balance}`);
   expect(balance).toBe(expectedBalance);
@@ -50,7 +82,7 @@ export async function mintNotes(
   wallet: Wallet,
   minter: AztecAddress,
   recipient: AztecAddress,
-  asset: TokenContract,
+  asset: AnyTokenContract,
   noteAmounts: bigint[],
 ): Promise<bigint> {
   // We can only mint 5 notes at a time, since that's the maximum number of calls our entrypoints allow

package/src/fixtures/utils.ts

@@ -7,8 +7,8 @@ export {
   type EndToEndContext,
   type SetupOptions,
   createAndSyncProverNode,
-  deployAccounts,
-  ensureAccountContractsPublished,
+  ensureAuthRegistryPublished,
+  ensurePublicChecksPublished,
   expectMapping,
   expectMappingDelta,
   getBalancesFn,
@@ -16,7 +16,6 @@ export {
   getPrivateKeyFromIndex,
   getSponsoredFPCAddress,
   getSponsoredFPCInstance,
-  publicDeployAccounts,
   registerSponsoredFPC,
   setup,
   setupPXEAndGetWallet,

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;
+  }
+}