@aztec/end-to-end 0.0.1-commit.96dac018d → 0.0.1-commit.9badcec54

package/src/fixtures/setup.ts

@@ -1,11 +1,14 @@
 import { SchnorrAccountContractArtifact } from '@aztec/accounts/schnorr';
 import { type InitialAccountData, generateSchnorrAccounts } from '@aztec/accounts/testing';
 import { type AztecNodeConfig, AztecNodeService, getConfigEnvVars } from '@aztec/aztec-node';
+import { NO_FROM } from '@aztec/aztec.js/account';
 import { AztecAddress, EthAddress } from '@aztec/aztec.js/addresses';
 import {
   BatchCall,
   type ContractFunctionInteraction,
   type ContractMethod,
+  type DeployInteractionWaitOptions,
+  type DeployOptions,
   getContractClassFromArtifact,
   waitForProven,
 } from '@aztec/aztec.js/contracts';
@@ -30,6 +33,7 @@ import {
 } from '@aztec/ethereum/deploy-aztec-l1-contracts';
 import type { Delayer } from '@aztec/ethereum/l1-tx-utils';
 import { EthCheatCodes, EthCheatCodesWithState, startAnvil } from '@aztec/ethereum/test';
+import type { Anvil } from '@aztec/ethereum/test';
 import { BlockNumber, EpochNumber } from '@aztec/foundation/branded-types';
 import { SecretValue } from '@aztec/foundation/config';
 import { randomBytes } from '@aztec/foundation/crypto/random';
@@ -47,10 +51,10 @@ import type { ProverNodeConfig } from '@aztec/prover-node';
 import { type PXEConfig, getPXEConfig } from '@aztec/pxe/server';
 import type { SequencerClient } from '@aztec/sequencer-client';
 import { type ContractInstanceWithAddress, getContractInstanceFromInstantiationParams } from '@aztec/stdlib/contract';
-import type { AztecNodeAdmin } from '@aztec/stdlib/interfaces/client';
+import type { AztecNodeAdmin, AztecNodeDebug } from '@aztec/stdlib/interfaces/client';
 import { tryStop } from '@aztec/stdlib/interfaces/server';
-import type { P2PClientType } from '@aztec/stdlib/p2p';
 import type { PublicDataTreeLeaf } from '@aztec/stdlib/trees';
+import type { GenesisData } from '@aztec/stdlib/world-state';
 import {
   type TelemetryClient,
   type TelemetryClientConfig,
@@ -61,7 +65,6 @@ import { BenchmarkTelemetryClient } from '@aztec/telemetry-client/bench';
 import { deployFundedSchnorrAccounts } from '@aztec/wallets/testing';
 import { getGenesisValues } from '@aztec/world-state/testing';
 
-import type { Anvil } from '@viem/anvil';
 import fs from 'fs/promises';
 import { tmpdir } from 'os';
 import path from 'path';
@@ -178,6 +181,8 @@ export type SetupOptions = {
   proverNodeConfig?: Partial<ProverNodeConfig>;
   /** Whether to use a mock gossip sub network for p2p clients. */
   mockGossipSubNetwork?: boolean;
+  /** Whether to add simulated latency to the mock gossipsub network (in ms) */
+  mockGossipSubNetworkLatency?: number;
   /** Whether to disable the anvil test watcher (can still be manually started) */
   disableAnvilTestWatcher?: boolean;
   /** Whether to enable anvil automine during deployment of L1 contracts (consider defaulting this to true). */
@@ -186,6 +191,11 @@ export type SetupOptions = {
   anvilAccounts?: number;
   /** Port to start anvil (defaults to 8545) */
   anvilPort?: number;
+  /**
+   * Number of slots per epoch for Anvil's finality simulation.
+   * Anvil reports `finalized = latest - slotsInAnEpoch * 2`.
+   */
+  anvilSlotsInAnEpoch?: number;
   /** Key to use for publishing L1 contracts */
   l1PublisherKey?: SecretValue<`0x${string}`>;
   /** ZkPassport configuration (domain, scope, mock verifier) */
@@ -205,7 +215,7 @@ export type EndToEndContext = {
   /** The Anvil instance (only set if anvil was started locally). */
   anvil: Anvil | undefined;
   /** The Aztec Node service or client a connected to it. */
-  aztecNode: AztecNode;
+  aztecNode: AztecNode & AztecNodeDebug;
   /** The Aztec Node as a service. */
   aztecNodeService: AztecNodeService;
   /** Client to the Aztec Node admin interface. */
@@ -244,8 +254,8 @@ export type EndToEndContext = {
   sequencerDelayer: Delayer | undefined;
   /** Delayer for prover node L1 txs (only when enableDelayer and startProverNode are true). */
   proverDelayer: Delayer | undefined;
-  /** Prefilled public data used for setting up nodes. */
-  prefilledPublicData: PublicDataTreeLeaf[] | undefined;
+  /** Genesis data used for setting up nodes. */
+  genesis: GenesisData | undefined;
   /** ACVM config (only set if running locally). */
   acvmConfig: Awaited<ReturnType<typeof getACVMConfig>>;
   /** BB config (only set if running locally). */
@@ -271,7 +281,7 @@ export async function setup(
   let anvil: Anvil | undefined;
   try {
     opts.aztecTargetCommitteeSize ??= 0;
-    opts.slasherFlavor ??= 'none';
+    opts.slasherEnabled ??= false;
 
     const config: AztecNodeConfig & SetupOptions = { ...getConfigEnvVars(), ...opts };
     // use initialValidators for the node config
@@ -298,6 +308,8 @@ export async function setup(
       config.dataDirectory = directoryToCleanup;
     }
 
+    const dateProvider = new TestDateProvider();
+
     if (!config.l1RpcUrls?.length) {
       if (!isAnvilTestChain(chain.id)) {
         throw new Error(`No ETHEREUM_HOSTS set but non anvil chain requested`);
@@ -306,6 +318,8 @@ export async function setup(
         l1BlockTime: opts.ethereumSlotDuration,
         accounts: opts.anvilAccounts,
         port: opts.anvilPort ?? (process.env.ANVIL_PORT ? parseInt(process.env.ANVIL_PORT) : undefined),
+        slotsInAnEpoch: opts.anvilSlotsInAnEpoch,
+        dateProvider,
       });
       anvil = res.anvil;
       config.l1RpcUrls = [res.rpcUrl];
@@ -317,8 +331,6 @@ export async function setup(
       logger.info(`Logging metrics to ${filename}`);
       setupMetricsLogger(filename);
     }
-
-    const dateProvider = new TestDateProvider();
     const ethCheatCodes = new EthCheatCodesWithState(config.l1RpcUrls, dateProvider);
 
     if (opts.stateLoad) {
@@ -368,10 +380,12 @@ export async function setup(
       addressesToFund.push(sponsoredFPCAddress);
     }
 
-    const { genesisArchiveRoot, prefilledPublicData, fundingNeeded } = await getGenesisValues(
+    const genesisTimestamp = BigInt(Math.floor(Date.now() / 1000));
+    const { genesisArchiveRoot, genesis, fundingNeeded } = await getGenesisValues(
       addressesToFund,
       opts.initialAccountFeeJuice,
       opts.genesisPublicData,
+      genesisTimestamp,
     );
 
     const wasAutomining = await ethCheatCodes.isAutoMining();
@@ -414,11 +428,12 @@ export async function setup(
       await ethCheatCodes.setIntervalMining(config.ethereumSlotDuration);
     }
 
-    // Always sync dateProvider to L1 time after deploying L1 contracts, regardless of mining mode.
-    // In compose mode, L1 time may have drifted ahead of system time due to the local-network watcher
-    // warping time forward on each filled slot. Without this sync, the sequencer computes the wrong
-    // slot from its dateProvider and cannot propose blocks.
-    dateProvider.setTime((await ethCheatCodes.timestamp()) * 1000);
+    // In compose mode (no local anvil), sync dateProvider to L1 time since it may have drifted
+    // ahead of system time due to the local-network watcher warping time forward on each filled slot.
+    // When running with a local anvil, the dateProvider is kept in sync via the stdout listener.
+    if (!anvil) {
+      dateProvider.setTime((await ethCheatCodes.lastBlockTimestamp()) * 1000);
+    }
 
     if (opts.l2StartTime) {
       await ethCheatCodes.warp(opts.l2StartTime, { resetBlockInterval: true });
@@ -456,10 +471,10 @@ export async function setup(
     }
 
     let mockGossipSubNetwork: MockGossipSubNetwork | undefined;
-    let p2pClientDeps: P2PClientDeps<P2PClientType.Full> | undefined = undefined;
+    let p2pClientDeps: P2PClientDeps | undefined = undefined;
 
     if (opts.mockGossipSubNetwork) {
-      mockGossipSubNetwork = new MockGossipSubNetwork();
+      mockGossipSubNetwork = new MockGossipSubNetwork(opts.mockGossipSubNetworkLatency);
       p2pClientDeps = { p2pServiceFactory: getMockPubSubP2PServiceFactory(mockGossipSubNetwork) };
     }
 
@@ -488,11 +503,7 @@ export async function setup(
     }
 
     const aztecNodeService = await withLoggerBindings({ actor: 'node-0' }, () =>
-      AztecNodeService.createAndSync(
-        config,
-        { dateProvider, telemetry: telemetryClient, p2pClientDeps },
-        { prefilledPublicData },
-      ),
+      AztecNodeService.createAndSync(config, { dateProvider, telemetry: telemetryClient, p2pClientDeps }, { genesis }),
     );
     const sequencerClient = aztecNodeService.getSequencer();
 
@@ -503,7 +514,7 @@ export async function setup(
       const proverNodePrivateKeyHex: Hex = `0x${proverNodePrivateKey!.toString('hex')}`;
       const proverNodeDataDirectory = path.join(directoryToCleanup, randomBytes(8).toString('hex'));
 
-      const p2pClientDeps: Partial<P2PClientDeps<P2PClientType.Full>> = {
+      const p2pClientDeps: Partial<P2PClientDeps> = {
         p2pServiceFactory: mockGossipSubNetwork && getMockPubSubP2PServiceFactory(mockGossipSubNetwork!),
         rpcTxProviders: [aztecNodeService],
       };
@@ -516,7 +527,7 @@ export async function setup(
           dataDirectory: proverNodeDataDirectory,
         },
         { dateProvider, p2pClientDeps, telemetry: telemetryClient },
-        { prefilledPublicData },
+        { genesis },
       ));
     }
 
@@ -621,7 +632,7 @@ export async function setup(
       initialFundedAccounts,
       logger,
       mockGossipSubNetwork,
-      prefilledPublicData,
+      genesis,
       proverNode,
       sequencerDelayer,
       proverDelayer,
@@ -719,9 +730,9 @@ export function createAndSyncProverNode(
   deps: {
     telemetry?: TelemetryClient;
     dateProvider: DateProvider;
-    p2pClientDeps?: P2PClientDeps<P2PClientType.Full>;
+    p2pClientDeps?: P2PClientDeps;
   },
-  options: { prefilledPublicData: PublicDataTreeLeaf[]; dontStart?: boolean },
+  options: { genesis?: GenesisData; dontStart?: boolean },
 ): Promise<{ proverNode: AztecNodeService }> {
   return withLoggerBindings({ actor: 'prover-0' }, async () => {
     const proverNode = await AztecNodeService.createAndSync(
@@ -734,7 +745,7 @@ export function createAndSyncProverNode(
         proverPublisherPrivateKeys: [new SecretValue(proverNodePrivateKey)],
       },
       deps,
-      { ...options, dontStartProverNode: options.dontStart },
+      { genesis: options.genesis, dontStartProverNode: options.dontStart },
     );
 
     if (!proverNode.getProverNode()) {
@@ -754,7 +765,9 @@ export function getBalancesFn(
 ): (...addresses: (AztecAddress | { address: AztecAddress })[]) => Promise<bigint[]> {
   const balances = async (...addressLikes: (AztecAddress | { address: AztecAddress })[]) => {
     const addresses = addressLikes.map(addressLike => ('address' in addressLike ? addressLike.address : addressLike));
-    const b = await Promise.all(addresses.map(address => method(address).simulate({ from: address })));
+    const b = await Promise.all(
+      addresses.map(async address => (await method(address).simulate({ from: address })).result),
+    );
     const debugString = `${symbol} balances: ${addresses.map((address, i) => `${address}: ${b[i]}`).join(', ')}`;
     logger.verbose(debugString);
     return b;
@@ -823,7 +836,7 @@ export async function ensureAccountContractsPublished(wallet: Wallet, accountsTo
  * Returns deployed account data that can be used by tests.
  */
 export const deployAccounts =
-  (numberOfAccounts: number, logger: Logger) =>
+  (numberOfAccounts: number, logger: Logger, deployOptions?: Partial<DeployOptions<DeployInteractionWaitOptions>>) =>
   async ({ wallet, initialFundedAccounts }: { wallet: TestWallet; initialFundedAccounts: InitialAccountData[] }) => {
     if (initialFundedAccounts.length < numberOfAccounts) {
       throw new Error(`Cannot deploy more than ${initialFundedAccounts.length} initial accounts.`);
@@ -840,8 +853,9 @@ export const deployAccounts =
       );
       const deployMethod = await accountManager.getDeployMethod();
       await deployMethod.send({
-        from: AztecAddress.ZERO,
+        from: NO_FROM,
         skipClassPublication: i !== 0, // Publish the contract class at most once.
+        ...deployOptions,
       });
     }
 
@@ -872,7 +886,7 @@ export async function publicDeployAccounts(
 
   const batch = new BatchCall(wallet, calls);
 
-  const txReceipt = await batch.send({ from: accountsToDeploy[0] });
+  const { receipt: txReceipt } = await batch.send({ from: accountsToDeploy[0] });
   if (waitUntilProven) {
     if (!node) {
       throw new Error('Need to provide an AztecNode to wait for proven.');

package/src/fixtures/setup_p2p_test.ts

@@ -7,7 +7,7 @@ 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,
     );
@@ -97,7 +97,7 @@ export async function createNode(
   tcpPort: number,
   bootstrapNode: string | undefined,
   addressIndex: number | number[],
-  prefilledPublicData?: PublicDataTreeLeaf[],
+  genesis?: GenesisData,
   dataDirectory?: string,
   metricsPort?: number,
 ) {
@@ -108,7 +108,7 @@ export async function createNode(
     return await AztecNodeService.createAndSync(
       validatorConfig,
       { telemetry, dateProvider },
-      { prefilledPublicData, dontStartSequencer: config.dontStartSequencer },
+      { genesis, dontStartSequencer: config.dontStartSequencer },
     );
   });
 }
@@ -119,7 +119,7 @@ export async function createNonValidatorNode(
   dateProvider: DateProvider,
   tcpPort: number,
   bootstrapNode: string | undefined,
-  prefilledPublicData?: PublicDataTreeLeaf[],
+  genesis?: GenesisData,
   dataDirectory?: string,
   metricsPort?: number,
 ) {
@@ -133,7 +133,7 @@ export async function createNonValidatorNode(
       sequencerPublisherPrivateKeys: [],
     };
     const telemetry = await getEndToEndTestTelemetryClient(metricsPort);
-    return await AztecNodeService.createAndSync(config, { telemetry, dateProvider }, { prefilledPublicData });
+    return await AztecNodeService.createAndSync(config, { telemetry, dateProvider }, { genesis });
   });
 }
 
@@ -143,7 +143,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 +159,7 @@ export async function createProverNode(
       { ...config, ...p2pConfig },
       { dataDirectory },
       { ...deps, telemetry },
-      { prefilledPublicData: prefilledPublicData ?? [] },
+      { genesis },
     );
   });
 }

package/src/fixtures/token_utils.ts

@@ -8,7 +8,6 @@ export async function deployToken(wallet: Wallet, admin: AztecAddress, initialAd
   logger.info(`Deploying Token contract...`);
   const { contract, instance } = await TokenContract.deploy(wallet, admin, 'TokenName', 'TokenSymbol', 18).send({
     from: admin,
-    wait: { returnReceipt: true },
   });
 
   if (initialAdminBalance > 0n) {
@@ -39,7 +38,7 @@ export async function expectTokenBalance(
 ) {
   // Then check the balance
   const contractWithWallet = TokenContract.at(token.address, wallet);
-  const balance = await contractWithWallet.methods.balance_of_private(owner).simulate({ from: owner });
+  const { result: balance } = await contractWithWallet.methods.balance_of_private(owner).simulate({ from: owner });
   logger.info(`Account ${owner} balance: ${balance}`);
   expect(balance).toBe(expectedBalance);
 }

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,104 @@
+#!/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(
+    extraAccountSecret,
+    extraAccountSalt,
+    extraAccountSigningKey,
+  );
+
+  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.createSchnorrAccount(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({ node: [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,8 @@ 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
 

package/src/legacy-jest-resolver.cjs

@@ -0,0 +1,135 @@
+// Custom Jest resolver. When CONTRACT_ARTIFACTS_VERSION is set, redirects *only* JSON artifact files under
+// @aztec/noir-contracts.js/artifacts/, @aztec/noir-test-contracts.js/artifacts/, and @aztec/accounts/artifacts/ to a local cache of the pinned
+// legacy versions. TypeScript wrapper classes (e.g. Token.ts) continue to load from the current workspace and use the
+// current @aztec/aztec.js — only the artifact JSON (the deployed-contract ABI / bytecode / notes surface) is swapped.
+//
+// Why JSON-only: the JSON artifact is the actual interchange surface a "deployed contract" exposes. The TS wrapper is
+// generated client-side ergonomics that's tightly coupled to the current @aztec/aztec.js API. Redirecting the wrapper
+// would couple this test to a moving aztec.js surface and break at import time on unrelated breaking changes; we want
+// to fail only on actual artifact-compat regressions.
+//
+// The cache is populated on demand by running `npm install` into .legacy-contracts/<version>/.
+//
+// Activated by env var; passthrough otherwise.
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+const version = process.env.CONTRACT_ARTIFACTS_VERSION;
+const REDIRECTED = ['@aztec/noir-contracts.js', '@aztec/noir-test-contracts.js', '@aztec/accounts'];
+
+// Jest sets rootDir to <e2e>/src; this file lives there too.
+const e2eRoot = path.resolve(__dirname, '..');
+const cacheRoot = version ? path.join(e2eRoot, '.legacy-contracts', version) : null;
+
+function pkgJsonPath(name) {
+  return path.join(cacheRoot, 'node_modules', name, 'package.json');
+}
+
+function ensureCache() {
+  const missing = REDIRECTED.some(p => !fs.existsSync(pkgJsonPath(p)));
+  if (!missing) {
+    return;
+  }
+  fs.mkdirSync(cacheRoot, { 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(cacheRoot, 'package.json');
+  if (!fs.existsSync(seed)) {
+    fs.writeFileSync(seed, JSON.stringify({ name: 'legacy-contracts-cache', private: true }));
+  }
+
+  const specs = REDIRECTED.map(p => `${p}@${version}`).join(' ');
+  process.stderr.write(`[legacy-contracts] installing ${specs} into ${cacheRoot}\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.
+  execSync(`npm install --prefix "${cacheRoot}" --no-save --ignore-scripts --legacy-peer-deps ${specs}`, {
+    stdio: 'inherit',
+  });
+
+  // Verify versions on disk match the requested version.
+  for (const p of REDIRECTED) {
+    const onDisk = JSON.parse(fs.readFileSync(pkgJsonPath(p), 'utf8')).version;
+    if (onDisk !== version) {
+      throw new Error(`[legacy-contracts] ${p} on disk is ${onDisk}, expected ${version}`);
+    }
+  }
+}
+
+if (version) {
+  ensureCache();
+}
+
+let bannerPrinted = false;
+const seen = new Set();
+
+function printBannerOnce() {
+  if (bannerPrinted || !version) {
+    return;
+  }
+  bannerPrinted = true;
+  const lines = ['='.repeat(60), `[legacy-contracts][jest] CONTRACT_ARTIFACTS_VERSION=${version}`];
+  for (const p of REDIRECTED) {
+    const v = JSON.parse(fs.readFileSync(pkgJsonPath(p), 'utf8')).version;
+    if (v !== version) {
+      throw new Error(`[legacy-contracts] ${p} on disk is ${v}, expected ${version}`);
+    }
+    lines.push(`[legacy-contracts][jest] redirecting ${p}/artifacts/*.json -> .legacy-contracts/${version}/...`);
+  }
+  lines.push('='.repeat(60));
+  process.stderr.write(lines.join('\n') + '\n');
+}
+
+// Match a resolved absolute path against the workspace artifacts dirs and return the legacy cache equivalent, or null
+// if it's not an artifact path we should redirect.
+function legacyArtifactPath(resolved) {
+  if (!resolved.endsWith('.json')) {
+    return null;
+  }
+  for (const pkg of REDIRECTED) {
+    // pkg = '@aztec/noir-contracts.js' -> match '/noir-contracts.js/artifacts/'
+    const dirName = pkg.split('/')[1];
+    const marker = `/${dirName}/artifacts/`;
+    const idx = resolved.indexOf(marker);
+    if (idx === -1) {
+      continue;
+    }
+    const basename = resolved.slice(idx + marker.length);
+    return path.join(cacheRoot, 'node_modules', pkg, 'artifacts', basename);
+  }
+  return null;
+}
+
+module.exports = function legacyResolver(request, options) {
+  // Always run the default resolver first. We only inspect (and possibly rewrite) the *result*; this catches both
+  // bare-specifier imports of `@aztec/noir-contracts.js/artifacts/foo.json` and the relative `../artifacts/foo.json`
+  // imports inside the workspace TS wrapper classes — both resolve to the same workspace artifact path that we then
+  // redirect.
+  const resolved = options.defaultResolver(request, options);
+  if (!version) {
+    return resolved;
+  }
+  printBannerOnce();
+  const legacy = legacyArtifactPath(resolved);
+  if (!legacy) {
+    return resolved;
+  }
+  if (!fs.existsSync(legacy)) {
+    throw new Error(
+      `[legacy-contracts] artifact ${path.basename(legacy)} not present in legacy cache @${version}; ` +
+        `the contract may have been added after that release. Pin a newer CONTRACT_ARTIFACTS_VERSION or skip this test.`,
+    );
+  }
+  if (!seen.has(resolved)) {
+    seen.add(resolved);
+    process.stderr.write(`[legacy-contracts][jest] redirected ${path.basename(legacy)} -> ${legacy}\n`);
+  }
+  return legacy;
+};