@aztec/end-to-end 0.0.1-commit.d3ec352c → 0.0.1-commit.d58ff9d0

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/fixtures/web3signer.ts

@@ -1,4 +1,4 @@
-import { randomBytes } from '@aztec/foundation/crypto';
+import { randomBytes } from '@aztec/foundation/crypto/random';
 import { retryUntil } from '@aztec/foundation/retry';
 import { sleep } from '@aztec/foundation/sleep';
 import { RemoteSigner } from '@aztec/node-keystore';

package/src/fixtures/with_telemetry_utils.ts

@@ -7,12 +7,12 @@ import {
 } from '@aztec/telemetry-client';
 import { OTelPinoStream } from '@aztec/telemetry-client/otel-pino-stream';
 
-export function getEndToEndTestTelemetryClient(metricsPort?: number): TelemetryClient {
+export async function getEndToEndTestTelemetryClient(metricsPort?: number): Promise<TelemetryClient> {
   if (metricsPort) {
     const otelStream = new OTelPinoStream({ levels });
     registerLoggingStream(otelStream);
   }
-  return initTelemetryClient(getEndToEndTestTelemetryConfig(metricsPort));
+  return await initTelemetryClient(getEndToEndTestTelemetryConfig(metricsPort));
 }
 
 /**

package/src/forward-compatibility/wallet_rpc_client.ts

@@ -0,0 +1,14 @@
+import type { Wallet } from '@aztec/aztec.js/wallet';
+import { WalletSchema } from '@aztec/aztec.js/wallet';
+import { createSafeJsonRpcClient, makeFetch } from '@aztec/foundation/json-rpc/client';
+
+/**
+ * Creates a JSON-RPC client that connects to a remote wallet service.
+ * The returned object implements the {@link Wallet} interface, proxying all calls over HTTP to the specified URL.
+ */
+export function createWalletClient(url: string): Wallet {
+  return createSafeJsonRpcClient<Wallet>(url, WalletSchema, {
+    namespaceMethods: 'wallet',
+    fetch: makeFetch([1, 2, 3], false),
+  });
+}

package/src/forward-compatibility/wallet_service.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env -S node --no-warnings
+/**
+ * Standalone entrypoint that spins up a local Aztec network (L1 + node) and exposes a {@link NodeEmbeddedWallet} over
+ * JSON-RPC.
+ *
+ * Intended for forward-compatibility testing: an **old** release image runs this script so that **new** tests can send
+ * new artifacts to old runtime code (loadContractArtifact, ACIR simulator, class-ID computation, entrypoint encoding,
+ * etc.).
+ */
+import { getSchnorrAccountContractAddress } from '@aztec/accounts/schnorr';
+import { getInitialTestAccountsData } from '@aztec/accounts/testing';
+import { createLocalNetwork } from '@aztec/aztec';
+import { Fr } from '@aztec/aztec.js/fields';
+import { WalletSchema } from '@aztec/aztec.js/wallet';
+import { GrumpkinScalar } from '@aztec/foundation/curves/grumpkin';
+import { createNamespacedSafeJsonRpcServer, startHttpRpcServer } from '@aztec/foundation/json-rpc/server';
+import { createLogger } from '@aztec/foundation/log';
+import { AztecNodeApiSchema } from '@aztec/stdlib/interfaces/client';
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
+
+const logger = createLogger('wallet-service');
+
+const { ETHEREUM_HOSTS = 'http://localhost:8545', NODE_PORT = '8080', WALLET_PORT = '8081' } = process.env;
+
+async function main() {
+  const l1RpcUrls = ETHEREUM_HOSTS.split(',').map(url => url.trim());
+
+  // Some tests (e.g. AMM) need 4 accounts but only 3 are funded via genesis. Generate deterministic keys for a 4th
+  // account so we can compute its address before network startup and include it in genesis funding. We cannot do this
+  // in the test because Wallet interface does not expose account creation functionality (only TestWallet exposes that
+  // but that's not used in forward compatibility testing).
+  const extraAccountSecret = Fr.fromHexString('0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef');
+  const extraAccountSalt = Fr.ZERO;
+  const extraAccountSigningKey = GrumpkinScalar.random();
+  const extraAccountAddress = await getSchnorrAccountContractAddress(
+    extraAccountSigningKey,
+    extraAccountSalt,
+    extraAccountSecret,
+  );
+
+  logger.info('Starting wallet service...', { l1RpcUrls });
+
+  // createLocalNetwork deploys L1 contracts, starts the node, and optionally deploys funded test accounts (when
+  // TEST_ACCOUNTS=true via env). We are not proving anything just like is done when local network is started by
+  // the `aztecStart` function. The extra account address is passed via prefundAddresses so it gets fee juice at genesis.
+  const { node, stop: stopNetwork } = await createLocalNetwork(
+    { l1RpcUrls, realProofs: false, prefundAddresses: [extraAccountAddress.toString()] },
+    logger.info,
+  );
+
+  // Create an ephemeral embedded wallet backed by the local node.
+  const wallet = await EmbeddedWallet.create(node, { ephemeral: true });
+
+  // Re-register the initial test accounts so they are available via wallet.getAccounts(). createLocalNetwork deploys
+  // them onchain but uses a temporary wallet that is then stopped.
+  //
+  // We use the non-lazy import path (@aztec/accounts/testing, not /lazy) to avoid the dynamic JSON import that is
+  // incompatible with Node.js import attribute enforcement.
+  const testAccountsData = await getInitialTestAccountsData();
+  const accounts = await Promise.all(
+    testAccountsData.map(({ secret, salt, signingKey }) =>
+      wallet.createSchnorrInitializerlessAccount(secret, salt, signingKey),
+    ),
+  );
+
+  // Register and deploy the 4th account.
+  const extraAccount = await wallet.createSchnorrAccount(extraAccountSecret, extraAccountSalt, extraAccountSigningKey);
+  const deployMethod = await extraAccount.getDeployMethod();
+  await deployMethod.send({ from: accounts[0].address });
+
+  logger.info('Embedded wallet created', {
+    accounts: [...accounts, extraAccount].map(a => a.address.toString()),
+  });
+
+  // Contract artifacts are large, so allow generous body sizes for RPC requests.
+  const rpcOptions = { maxBodySizeBytes: '50mb' };
+
+  // Serve node RPC
+  const nodeRpcServer = createNamespacedSafeJsonRpcServer({ aztec: [node, AztecNodeApiSchema] }, rpcOptions);
+  const nodeHttpServer = await startHttpRpcServer(nodeRpcServer, { port: NODE_PORT });
+  logger.info(`Node JSON-RPC server listening on port ${nodeHttpServer.port}`);
+
+  // Serve wallet RPC
+  const walletRpcServer = createNamespacedSafeJsonRpcServer({ wallet: [wallet, WalletSchema] }, rpcOptions);
+  const walletHttpServer = await startHttpRpcServer(walletRpcServer, { port: WALLET_PORT });
+  logger.info(`Wallet JSON-RPC server listening on port ${walletHttpServer.port}`);
+
+  const shutdown = async () => {
+    logger.info('Shutting down...');
+    nodeHttpServer.close();
+    walletHttpServer.close();
+    await wallet.stop();
+    await stopNetwork();
+    process.exit(0);
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-misused-promises
+  process.once('SIGINT', shutdown);
+  // eslint-disable-next-line @typescript-eslint/no-misused-promises
+  process.once('SIGTERM', shutdown);
+}
+
+main().catch(err => {
+  logger.error('Wallet service failed to start', err);
+  process.exit(1);
+});

package/src/guides/up_quick_start.sh

@@ -18,10 +18,10 @@ aztec-wallet() {
 
 aztec-wallet import-test-accounts
 
-# docs:start:declare-accounts
 aztec-wallet create-account -a alice -f test0
 aztec-wallet create-account -a bob -f test0
-# docs:end:declare-accounts
+
+aztec-wallet bridge-fee-juice 1000000000000000000000 accounts:alice --mint --no-wait
 
 DEPLOY_OUTPUT=$(aztec-wallet deploy ../noir-contracts.js/artifacts/token_contract-Token.json --args accounts:test0 Test TST 18 -f test0)
 TOKEN_ADDRESS=$(echo "$DEPLOY_OUTPUT" | grep -oE 'Contract deployed at 0x[0-9a-fA-F]+' | cut -d ' ' -f4)
@@ -38,9 +38,12 @@ fi
 
 TRANSFER_AMOUNT=42
 
-aztec-wallet create-authwit transfer_in_private accounts:test0 -ca last --args accounts:alice accounts:bob $TRANSFER_AMOUNT 1 -f alice
+# Alice's bridged fee-juice claim is only consumable inboxLag (2) checkpoints after the L1->L2 message
+# is inserted. The token deploy and mint above produced two blocks; force one more here (a public mint
+# from test0, which leaves the alice/bob private balances untouched) so the claim is available below.
+aztec-wallet send mint_to_public -ca last --args accounts:test0 1 -f test0
 
-aztec-wallet send transfer_in_private -ca last --args accounts:alice accounts:bob $TRANSFER_AMOUNT 1 -aw authwits:last -f test0
+aztec-wallet send transfer_in_private -ca last --args accounts:alice accounts:bob $TRANSFER_AMOUNT 0 -f alice --payment method=fee_juice,claim
 
 # Test end result
 ALICE_BALANCE=$(aztec-wallet simulate balance_of_private -ca last --args accounts:alice -f alice)

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/install_legacy_contracts.cjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Installs pinned legacy @aztec/* contract-artifact packages into .legacy-contracts/<version>/.
+//
+// Called from two places:
+//   - bootstrap.sh ci-compat-e2e: pre-populates the cache on the host before hermetic test
+//     containers launch. The containers run with --net=none (see ci3/docker_isolate), so on-demand
+//     installs from inside them fail with EAI_AGAIN.
+//   - legacy-jest-resolver.cjs: on-demand install for local dev, where jest runs with network.
+//
+// Idempotent: no-op when all packages are already present.
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const path = require('path');
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+const REDIRECTED = ['@aztec/noir-contracts.js', '@aztec/noir-test-contracts.js', '@aztec/accounts'];
+
+const e2eRoot = path.resolve(__dirname, '..');
+
+function cacheRoot(version) {
+  return path.join(e2eRoot, '.legacy-contracts', version);
+}
+
+function pkgJsonPath(version, pkg) {
+  return path.join(cacheRoot(version), 'node_modules', pkg, 'package.json');
+}
+
+function installLegacyContracts(version) {
+  if (!version) {
+    throw new Error('installLegacyContracts: version is required');
+  }
+  if (REDIRECTED.every(pkg => fs.existsSync(pkgJsonPath(version, pkg)))) {
+    return;
+  }
+
+  const cacheDir = cacheRoot(version);
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  // Seed a standalone package.json so `npm install --prefix` treats cacheRoot as its own project. Without this, npm
+  // walks up and finds the yarn-project workspace root, which breaks on `workspace:` protocol deps and risks
+  // clobbering the monorepo's node_modules.
+  const seed = path.join(cacheDir, 'package.json');
+  if (!fs.existsSync(seed)) {
+    fs.writeFileSync(seed, JSON.stringify({ name: 'legacy-contracts-cache', private: true }));
+  }
+
+  const specs = REDIRECTED.map(pkg => `${pkg}@${version}`);
+  process.stderr.write(`[legacy-contracts] installing ${specs.join(' ')} into ${cacheDir}\n`);
+  // --prefix: install into cacheRoot instead of cwd, so the cache is isolated from the monorepo.
+  // --no-save: don't write the installed packages back to the seeded package.json.
+  // --ignore-scripts: skip lifecycle scripts (preinstall/postinstall) of the legacy packages and their transitive
+  //   deps; we only want the files on disk, not to run any build steps.
+  // --legacy-peer-deps: tolerate peer-dependency mismatches between the pinned legacy @aztec/* graph and whatever
+  //   current versions npm would otherwise try to reconcile.
+  execFileSync(
+    'npm',
+    ['install', '--prefix', cacheDir, '--no-save', '--ignore-scripts', '--legacy-peer-deps', ...specs],
+    { stdio: 'inherit' },
+  );
+
+  // Verify versions on disk match the requested version.
+  for (const pkg of REDIRECTED) {
+    const onDisk = JSON.parse(fs.readFileSync(pkgJsonPath(version, pkg), 'utf8')).version;
+    if (onDisk !== version) {
+      throw new Error(`[legacy-contracts] ${pkg} on disk is ${onDisk}, expected ${version}`);
+    }
+  }
+}
+
+module.exports = { installLegacyContracts, REDIRECTED, cacheRoot };
+
+if (require.main === module) {
+  installLegacyContracts(process.argv[2]);
+}