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

package/src/fixtures/setup.ts

@@ -0,0 +1,987 @@
+import { type InitialAccountData, generateSchnorrAccounts } from '@aztec/accounts/testing';
+import { type AztecNodeConfig, AztecNodeService, createAztecNodeService, getConfigEnvVars } from '@aztec/aztec-node';
+import { AztecAddress, EthAddress } from '@aztec/aztec.js/addresses';
+import type { ContractMethod } from '@aztec/aztec.js/contracts';
+import { publishContractClass, publishInstance } from '@aztec/aztec.js/deployment';
+import { Fr } from '@aztec/aztec.js/fields';
+import { type Logger, createLogger } from '@aztec/aztec.js/log';
+import type { AztecNode } from '@aztec/aztec.js/node';
+import type { Wallet } from '@aztec/aztec.js/wallet';
+import { CheatCodes } from '@aztec/aztec/testing';
+import { SPONSORED_FPC_SALT } from '@aztec/constants';
+import { isAnvilTestChain } from '@aztec/ethereum/chain';
+import { createExtendedL1Client } from '@aztec/ethereum/client';
+import { getL1ContractsConfigEnvVars } from '@aztec/ethereum/config';
+import { NULL_KEY } from '@aztec/ethereum/constants';
+import { deployMulticall3 } from '@aztec/ethereum/contracts';
+import {
+  type DeployAztecL1ContractsArgs,
+  type DeployAztecL1ContractsReturnType,
+  type Operator,
+  type ZKPassportArgs,
+  deployAztecL1Contracts,
+} from '@aztec/ethereum/deploy-aztec-l1-contracts';
+import type { Delayer } from '@aztec/ethereum/l1-tx-utils';
+import { EthCheatCodes, EthCheatCodesWithState, startAnvil, warmBlobKzg } from '@aztec/ethereum/test';
+import type { Anvil } from '@aztec/ethereum/test';
+import type { ExtendedViemWalletClient } from '@aztec/ethereum/types';
+import { BlockNumber, EpochNumber } from '@aztec/foundation/branded-types';
+import { SecretValue } from '@aztec/foundation/config';
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import { tryRmDir } from '@aztec/foundation/fs';
+import { withLoggerBindings } from '@aztec/foundation/log/server';
+import { retryUntil } from '@aztec/foundation/retry';
+import { DateProvider, TestDateProvider } from '@aztec/foundation/timer';
+import { SponsoredFPCContract } from '@aztec/noir-contracts.js/SponsoredFPC';
+import { getVKTreeRoot } from '@aztec/noir-protocol-circuits-types/vk-tree';
+import type { P2PClientDeps } from '@aztec/p2p';
+import { MockGossipSubNetwork, getMockPubSubP2PServiceFactory } from '@aztec/p2p/test-helpers';
+import { protocolContractsHash } from '@aztec/protocol-contracts';
+import type { ProverNodeConfig } from '@aztec/prover-node';
+import { type PXEConfig, type PXECreationOptions, getPXEConfig } from '@aztec/pxe/server';
+import type { SequencerClient } from '@aztec/sequencer-client';
+import { AuthRegistryArtifact, getStandardAuthRegistry } from '@aztec/standard-contracts/auth-registry';
+import { HandshakeRegistryArtifact, getStandardHandshakeRegistry } from '@aztec/standard-contracts/handshake-registry';
+import { PublicChecksArtifact, getStandardPublicChecks } from '@aztec/standard-contracts/public-checks';
+import { ARTIFACT_VERSION_BEFORE_INJECTION } from '@aztec/stdlib/abi';
+import { type ContractInstanceWithAddress, getContractInstanceFromInstantiationParams } from '@aztec/stdlib/contract';
+import type { AztecNodeAdmin, AztecNodeDebug } from '@aztec/stdlib/interfaces/client';
+import { tryStop } from '@aztec/stdlib/interfaces/server';
+import type { PublicDataTreeLeaf } from '@aztec/stdlib/trees';
+import type { GenesisData } from '@aztec/stdlib/world-state';
+import {
+  type TelemetryClient,
+  type TelemetryClientConfig,
+  getConfigEnvVars as getTelemetryConfig,
+  initTelemetryClient,
+} from '@aztec/telemetry-client';
+import { BenchmarkTelemetryClient } from '@aztec/telemetry-client/bench';
+import { createFundedInitializerlessAccounts } from '@aztec/wallets/testing';
+import { getGenesisValues } from '@aztec/world-state/testing';
+
+import fs from 'fs/promises';
+import { tmpdir } from 'os';
+import path from 'path';
+import type { Hex } from 'viem';
+import {
+  type HDAccount,
+  type PrivateKeyAccount,
+  generatePrivateKey,
+  mnemonicToAccount,
+  privateKeyToAccount,
+} from 'viem/accounts';
+import { type Chain, foundry } from 'viem/chains';
+
+import { TestWallet } from '../test-wallet/test_wallet.js';
+import { MNEMONIC, TEST_MAX_PENDING_TX_POOL_COUNT, TEST_PEER_CHECK_INTERVAL_MS } from './fixtures.js';
+import { getACVMConfig } from './get_acvm_config.js';
+import { getBBConfig } from './get_bb_config.js';
+import { isMetricsLoggingRequested, setupMetricsLogger } from './logging.js';
+import { testSpan } from './timing.js';
+import { getEndToEndTestTelemetryClient } from './with_telemetry_utils.js';
+
+export { startAnvil };
+
+let telemetry: TelemetryClient | undefined = undefined;
+async function getTelemetryClient(partialConfig: Partial<TelemetryClientConfig> & { benchmark?: boolean } = {}) {
+  if (!telemetry) {
+    const config = { ...getTelemetryConfig(), ...partialConfig };
+    telemetry = config.benchmark ? new BenchmarkTelemetryClient() : await initTelemetryClient(config);
+  }
+  return telemetry;
+}
+
+export const getPrivateKeyFromIndex = (index: number): Buffer | null => {
+  const hdAccount = mnemonicToAccount(MNEMONIC, { addressIndex: index });
+  const privKeyRaw = hdAccount.getHdKey().privateKey;
+  return privKeyRaw === null ? null : Buffer.from(privKeyRaw);
+};
+
+/**
+ * Sets up shared blob storage using FileStore in the data directory.
+ */
+export async function setupSharedBlobStorage(config: { dataDirectory?: string } & Record<string, any>): Promise<void> {
+  const sharedBlobPath = path.join(config.dataDirectory!, 'shared-blobs');
+  await fs.mkdir(sharedBlobPath, { recursive: true });
+  config.blobFileStoreUrls = [`file://${sharedBlobPath}`];
+  config.blobFileStoreUploadUrl = `file://${sharedBlobPath}`;
+}
+
+/**
+ * Sets up Private eXecution Environment (PXE) and returns the corresponding test wallet.
+ * @param aztecNode - An instance of Aztec Node.
+ * @param nodeDebug - The node's debug API, used to register public function signatures for named traces; pass
+ *   `undefined` when the node does not expose it.
+ * @param opts - Partial configuration for the PXE.
+ * @param logger - The logger to be used.
+ * @param actor - Actor label to include in log output (e.g., 'pxe-test').
+ * @returns A test wallet, logger and teardown function.
+ */
+export async function setupPXEAndGetWallet(
+  aztecNode: AztecNode,
+  nodeDebug: AztecNodeDebug | undefined,
+  opts: Partial<PXEConfig> = {},
+  logger = getLogger(),
+  actor?: string,
+): Promise<{
+  wallet: TestWallet;
+  logger: Logger;
+  teardown: () => Promise<void>;
+}> {
+  const PXEConfig = { ...getPXEConfig(), ...opts };
+  // For tests we only want proving enabled if specifically requested
+  PXEConfig.proverEnabled = !!opts.proverEnabled;
+
+  // If no data directory provided, create a temp directory and clean up afterwards
+  const configuredDataDirectory = PXEConfig.dataDirectory;
+  if (!configuredDataDirectory) {
+    PXEConfig.dataDirectory = path.join(tmpdir(), randomBytes(8).toString('hex'));
+  }
+
+  const teardown = configuredDataDirectory ? () => Promise.resolve() : () => tryRmDir(PXEConfig.dataDirectory!);
+
+  const wallet = await TestWallet.create(aztecNode, PXEConfig, {
+    loggerActorLabel: actor,
+    nodeDebug,
+  });
+
+  return {
+    wallet,
+    logger,
+    teardown,
+  };
+}
+
+/** Options for the e2e tests setup */
+export type SetupOptions<TDeployExtraL1ContractsReturnType = unknown> = {
+  /** State load */
+  stateLoad?: string;
+  /** Whether to enable metrics collection, if undefined, metrics collection is disabled */
+  metricsPort?: number | undefined;
+  /** Previously deployed contracts on L1 */
+  deployL1ContractsValues?: DeployAztecL1ContractsReturnType;
+  /** Initial fee juice for default accounts */
+  initialAccountFeeJuice?: Fr;
+  /**
+   * Extra accounts to fund at genesis beyond the `numberOfAccounts` initializerless accounts that setup
+   * creates. Setup funds these but does NOT create or deploy them — the test creates/deploys them itself
+   */
+  additionallyFundedAccounts?: InitialAccountData[];
+  /** An initial set of validators */
+  initialValidators?: (Operator & { privateKey: `0x${string}` })[];
+  /** Anvil Start time */
+  l1StartTime?: number;
+  /** The anvil time where we should at the earliest be seeing L2 blocks */
+  l2StartTime?: number;
+  /** Whether to start a prover node */
+  startProverNode?: boolean;
+  /** Manual config for the telemetry client */
+  telemetryConfig?: Partial<TelemetryClientConfig> & { benchmark?: boolean };
+  /** Public data that will be inserted in the tree in genesis */
+  genesisPublicData?: PublicDataTreeLeaf[];
+  /** Specific config for the prover node, if set. */
+  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 mine the L1 setup txs (Multicall3 + rollup contract deployment) under anvil automine
+   * instead of waiting on the block interval. Defaults to `true` (set in `setupInner`); only suites
+   * that assert on genesis-relative L1 timing need to opt out with `false`.
+   */
+  automineL1Setup?: boolean;
+  /**
+   * Hook invoked after the Aztec L1 rollup contracts are deployed but BEFORE the node/sequencer
+   * start, while anvil automine is still enabled (when `automineL1Setup` is true, the default).
+   * Deploy extra L1 contracts a test needs here (e.g. a cross-chain token portal + ERC20) so they
+   * mine instantly under automine instead of paying the L1 block interval once the node is running
+   * (and racing the live sequencer/archiver). The resolved value is exposed on the returned context
+   * as `extraL1DeployResult`. The hook receives setup's L1 deployer client (the same one used to
+   * deploy Multicall3).
+   */
+  deployExtraL1Contracts?: (deps: {
+    l1Client: ExtendedViemWalletClient;
+    deployL1ContractsValues: DeployAztecL1ContractsReturnType;
+    logger: Logger;
+  }) => Promise<TDeployExtraL1ContractsReturnType>;
+  /** How many accounts to seed and unlock in anvil. */
+  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) */
+  zkPassportArgs?: ZKPassportArgs;
+  /** Whether to fund the sponsored FPC in genesis (defaults to false). */
+  fundSponsoredFPC?: boolean;
+  /** L1 contracts deployment arguments. */
+  l1ContractsArgs?: Partial<DeployAztecL1ContractsArgs>;
+  /** Wallet minimum fee padding multiplier */
+  walletMinFeePadding?: number;
+  /** Whether the initial node should be a lightweight RPC-only node (no sequencer, no validator).
+   *  Use for tests that create their own validator nodes and don't need the initial sequencer. */
+  skipInitialSequencer?: boolean;
+  /** Whether to swap the production Sequencer for the minimal AutomineSequencer.
+   * Use only for single-sequencer non-block-building tests. See AUTOMINE_E2E_OPTS in `fixtures.ts`. */
+  useAutomineSequencer?: boolean;
+  /** Options forwarded to PXE creation (e.g. execution hooks). */
+  pxeCreationOptions?: PXECreationOptions;
+} & Partial<AztecNodeConfig>;
+
+/** Context for an end-to-end test as returned by the `setup` function */
+export type EndToEndContext<TDeployExtraL1ContractsReturnType = unknown> = {
+  /** 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 & AztecNodeDebug;
+  /** The Aztec Node as a service. */
+  aztecNodeService: AztecNodeService;
+  /** Client to the Aztec Node admin interface. */
+  aztecNodeAdmin: AztecNodeAdmin;
+  /** The aztec node running the prover node subsystem (only set if startProverNode is true). */
+  proverNode: AztecNodeService | undefined;
+  /** A client to the sequencer service. */
+  sequencer: SequencerClient | undefined;
+  /** Return values from deployAztecL1Contracts function. */
+  deployL1ContractsValues: DeployAztecL1ContractsReturnType;
+  /** The Aztec Node configuration. */
+  config: AztecNodeConfig;
+  /** The Aztec Node configuration (alias for config for backward compatibility). */
+  aztecNodeConfig: AztecNodeConfig;
+  /** Data for the extra accounts funded at genesis but not created by setup (the test creates/deploys them). */
+  additionallyFundedAccounts: InitialAccountData[];
+  /** The wallet to be used. */
+  wallet: TestWallet;
+  /** The wallets to be used. */
+  accounts: AztecAddress[];
+  /** Logger instance named as the current test. */
+  logger: Logger;
+  /** The cheat codes. */
+  cheatCodes: CheatCodes;
+  /** The cheat codes for L1 */
+  ethCheatCodes: EthCheatCodes;
+  /** Allows tweaking current system time, used by the epoch cache only. */
+  dateProvider: TestDateProvider;
+  /** Telemetry client */
+  telemetryClient: TelemetryClient;
+  /** Mock gossip sub network used for gossipping messages (only if mockGossipSubNetwork was set to true in opts) */
+  mockGossipSubNetwork: MockGossipSubNetwork | undefined;
+  /** Delayer for sequencer L1 txs (only when enableDelayer is true). */
+  sequencerDelayer: Delayer | undefined;
+  /** Delayer for prover node L1 txs (only when enableDelayer and startProverNode are true). */
+  proverDelayer: Delayer | undefined;
+  /** Genesis data used for setting up nodes. */
+  genesis: GenesisData | undefined;
+  /** Resolved value of the `deployExtraL1Contracts` setup hook, if one was provided. */
+  extraL1DeployResult: TDeployExtraL1ContractsReturnType;
+  /** ACVM config (only set if running locally). */
+  acvmConfig: Awaited<ReturnType<typeof getACVMConfig>>;
+  /** BB config (only set if running locally). */
+  bbConfig: Awaited<ReturnType<typeof getBBConfig>>;
+  /** Directory to cleanup on teardown. */
+  directoryToCleanup: string;
+  /** Function to stop the started services. */
+  teardown: () => Promise<void>;
+};
+
+/**
+ * When CONTRACT_ARTIFACTS_VERSION is set (backwards compatibility testing), asserts that the loaded artifact's
+ * aztecVersion matches the expected version. This is a sanity check verifying that the legacy artifact resolver
+ * actually swapped in the correct version.
+ */
+function assertContractArtifactsVersion() {
+  const expected = process.env.CONTRACT_ARTIFACTS_VERSION;
+  if (!expected) {
+    return;
+  }
+  const { aztecVersion } = SponsoredFPCContract.artifact;
+  // TODO(F-557): Remove this bypass once pre-version artifacts are no longer tested.
+  if (aztecVersion === ARTIFACT_VERSION_BEFORE_INJECTION) {
+    createLogger('e2e:setup').info(
+      `Skipping artifact version check: artifact predates version injection (CONTRACT_ARTIFACTS_VERSION=${expected})`,
+    );
+    return;
+  }
+  if (aztecVersion !== expected) {
+    throw new Error(
+      `Artifact version mismatch: expected ${expected} but got ${aztecVersion}. ` +
+        `The legacy artifact resolver may not have swapped in the correct version.`,
+    );
+  }
+}
+
+/**
+ * Sets up the environment for the end-to-end tests.
+ * @param numberOfAccounts - The number of new accounts to be created once the PXE is initiated.
+ * @param opts - Options to pass to the node initialization and to the setup script.
+ * @param pxeOpts - Options to pass to the PXE initialization.
+ */
+export function setup<TDeployExtraL1ContractsReturnType = unknown>(
+  numberOfAccounts = 1,
+  opts: SetupOptions<TDeployExtraL1ContractsReturnType> = {},
+  pxeOpts: Partial<PXEConfig> = {},
+  chain: Chain = foundry,
+): Promise<EndToEndContext<TDeployExtraL1ContractsReturnType>> {
+  // Tag the top-level env spin-up with the prover mode (none → fake → real), the largest config-driven
+  // swing in setup cost, so the three factories are comparable on the span leaderboard. The internals
+  // (anvil / l1-deploy / sequencer-start / pxe / wallet:create) decompose this further.
+  const proverMode = opts.realProofs ? 'real' : opts.startProverNode ? 'fake' : 'none';
+  return testSpan(`setup:env:${proverMode}`, async () => {
+    const ctx = await setupInner(numberOfAccounts, opts, pxeOpts, chain);
+    if (process.env.EXIT_E2E_AFTER_SETUP) {
+      ctx.logger.info('EXIT_E2E_AFTER_SETUP is set; aborting before the test body runs');
+      throw new Error('EXIT_E2E_AFTER_SETUP');
+    }
+    return ctx;
+  });
+}
+
+async function setupInner<TDeployExtraL1ContractsReturnType = unknown>(
+  numberOfAccounts: number,
+  opts: SetupOptions<TDeployExtraL1ContractsReturnType>,
+  pxeOpts: Partial<PXEConfig>,
+  chain: Chain,
+): Promise<EndToEndContext<TDeployExtraL1ContractsReturnType>> {
+  assertContractArtifactsVersion();
+  const logger = getLogger();
+  let anvil: Anvil | undefined;
+  try {
+    opts.aztecTargetCommitteeSize ??= 0;
+    opts.slasherEnabled ??= false;
+    // Mine the L1 setup txs (Multicall3 + rollup contract deployment) immediately instead of
+    // waiting on anvil's block interval — this is the dominant cost of e2e setup. Suites that
+    // assert on genesis-relative L1 timing can opt out by passing `automineL1Setup: false`.
+    opts.automineL1Setup ??= true;
+    logger.trace('Starting e2e test setup');
+
+    const config: AztecNodeConfig & SetupOptions = { ...getConfigEnvVars(), ...opts };
+    // use initialValidators for the node config
+    config.validatorPrivateKeys = new SecretValue(opts.initialValidators?.map(v => v.privateKey) ?? []);
+
+    config.peerCheckIntervalMS = TEST_PEER_CHECK_INTERVAL_MS;
+    config.maxPendingTxCount = opts.maxPendingTxCount ?? TEST_MAX_PENDING_TX_POOL_COUNT;
+    // For tests we only want proving enabled if specifically requested
+    config.realProofs = !!opts.realProofs;
+    // Enable the tx delayer for tests (default config has it disabled, so we force-enable it here)
+    config.enableDelayer = true;
+    config.listenAddress = '127.0.0.1';
+
+    config.minTxPoolAgeMs = opts.minTxPoolAgeMs ?? 0;
+
+    // Create a temp directory for any services that need it and cleanup later
+    const directoryToCleanup = path.join(tmpdir(), randomBytes(8).toString('hex'));
+    await fs.mkdir(directoryToCleanup, { recursive: true });
+    if (!config.dataDirectory) {
+      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`);
+      }
+      const res = await testSpan('setup:env:anvil', () =>
+        startAnvil({
+          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];
+    }
+    logger.trace('Started anvil and L1 RPC client');
+
+    // Enable logging metrics to a local file named after the test suite
+    if (isMetricsLoggingRequested()) {
+      const filename = path.join('log', getJobName() + '.jsonl');
+      logger.info(`Logging metrics to ${filename}`);
+      setupMetricsLogger(filename);
+    }
+    const ethCheatCodes = new EthCheatCodesWithState(config.l1RpcUrls, dateProvider);
+
+    if (opts.stateLoad) {
+      await ethCheatCodes.loadChainState(opts.stateLoad);
+    }
+
+    if (opts.l1StartTime) {
+      await ethCheatCodes.warp(opts.l1StartTime, { resetBlockInterval: true });
+    }
+    logger.trace('Initialized L1 cheat codes and applied state/time overrides');
+
+    let publisherPrivKeyHex: `0x${string}` | undefined = undefined;
+    let publisherHdAccount: HDAccount | PrivateKeyAccount | undefined = undefined;
+
+    if (opts.l1PublisherKey && opts.l1PublisherKey.getValue() && opts.l1PublisherKey.getValue() != NULL_KEY) {
+      publisherPrivKeyHex = opts.l1PublisherKey.getValue();
+      publisherHdAccount = privateKeyToAccount(publisherPrivKeyHex);
+    } else if (
+      config.sequencerPublisherPrivateKeys &&
+      config.sequencerPublisherPrivateKeys.length > 0 &&
+      config.sequencerPublisherPrivateKeys[0].getValue() != NULL_KEY
+    ) {
+      publisherPrivKeyHex = config.sequencerPublisherPrivateKeys[0].getValue();
+      publisherHdAccount = privateKeyToAccount(publisherPrivKeyHex);
+    } else if (!MNEMONIC) {
+      throw new Error(`Mnemonic not provided and no publisher private key`);
+    } else {
+      publisherHdAccount = mnemonicToAccount(MNEMONIC, { addressIndex: 0 });
+      const publisherPrivKeyRaw = publisherHdAccount.getHdKey().privateKey;
+      const publisherPrivKey = publisherPrivKeyRaw === null ? null : Buffer.from(publisherPrivKeyRaw);
+      publisherPrivKeyHex = `0x${publisherPrivKey!.toString('hex')}` as const;
+      config.sequencerPublisherPrivateKeys = [new SecretValue(publisherPrivKeyHex)];
+    }
+
+    if (config.coinbase === undefined) {
+      config.coinbase = EthAddress.fromString(publisherHdAccount.address);
+    }
+    logger.trace('Resolved L1 publisher account');
+
+    // The accounts setup creates itself: `numberOfAccounts` initializerless accounts, generated here and
+    // funded at genesis so they are immediately usable.
+    const defaultAccounts = await generateSchnorrAccounts(numberOfAccounts);
+    // Extra accounts the test wants funded at genesis but will create/deploy itself.
+    const additionallyFundedAccounts = opts.additionallyFundedAccounts ?? [];
+    const addressesToFund = [...defaultAccounts, ...additionallyFundedAccounts].map(a => a.address);
+
+    // Optionally fund the sponsored FPC
+    if (opts.fundSponsoredFPC) {
+      const sponsoredFPCAddress = await getSponsoredFPCAddress();
+      addressesToFund.push(sponsoredFPCAddress);
+    }
+    logger.trace('Generated test accounts to fund at genesis');
+
+    const genesisTimestamp = BigInt(Math.floor(Date.now() / 1000));
+    const { genesisArchiveRoot, genesis, fundingNeeded } = await getGenesisValues(
+      addressesToFund,
+      opts.initialAccountFeeJuice,
+      opts.genesisPublicData,
+      genesisTimestamp,
+    );
+    logger.trace('Computed genesis values');
+
+    const wasAutomining = await ethCheatCodes.isAutoMining();
+    const enableAutomine = opts.automineL1Setup && !wasAutomining && isAnvilTestChain(chain.id);
+    if (enableAutomine) {
+      await ethCheatCodes.setAutomine(true);
+    }
+
+    const l1Client = createExtendedL1Client(config.l1RpcUrls, publisherHdAccount!, chain);
+
+    // Warm both KZG trusted setups (ours + anvil's) in parallel
+    if (anvil && isAnvilTestChain(chain.id)) {
+      await warmBlobKzg(l1Client, logger);
+    }
+
+    // Deploy Multicall3 if running locally
+    await deployMulticall3(l1Client, logger);
+
+    // Force viem to refresh its nonce cache to avoid "nonce too low" errors in subsequent transactions
+    // This is necessary because deployMulticall3 sends multiple transactions and viem may cache a stale nonce
+    await l1Client.getTransactionCount({ address: l1Client.account.address });
+    logger.trace('Deployed Multicall3');
+
+    const deployL1ContractsValues: DeployAztecL1ContractsReturnType = await testSpan('setup:env:l1-deploy', () =>
+      deployAztecL1Contracts(config.l1RpcUrls[0], publisherPrivKeyHex!, chain.id, {
+        ...getL1ContractsConfigEnvVars(),
+        ...opts,
+        ...opts.l1ContractsArgs,
+        vkTreeRoot: getVKTreeRoot(),
+        protocolContractsHash,
+        genesisArchiveRoot,
+        initialValidators: opts.initialValidators,
+        feeJuicePortalInitialBalance: fundingNeeded,
+        realVerifier: false,
+      }),
+    );
+
+    Object.assign(config, deployL1ContractsValues.l1ContractAddresses);
+    config.rollupVersion = deployL1ContractsValues.rollupVersion;
+
+    // Propagate L1-contracts-config overrides back to the node config so the archiver's
+    // `l1Constants` (and any other node-side consumer) agrees with what was actually deployed.
+    // Without this, a per-test override like `aztecEpochDuration: 4` lands on the rollup contract
+    // but the node config keeps the default (32), so `archiver.isEpochComplete(0)` computes
+    // `endSlot=31` and `EpochTestSettler`/`EpochMonitor` never fires — letting the
+    // `aztecProofSubmissionEpochs` window expire mid-test and prune the pending chain.
+    // Skip undefined values: callers (e.g. `P2PNetworkTest`) sometimes build `l1ContractsArgs`
+    // by spreading a partial `AztecNodeConfig`, which leaves unset fields (notably `dataDirectory`)
+    // as `undefined`. A blind Object.assign would then clobber the temp `dataDirectory` set earlier
+    // in this function and crash `setupSharedBlobStorage`.
+    if (opts.l1ContractsArgs) {
+      for (const [key, value] of Object.entries(opts.l1ContractsArgs)) {
+        if (value !== undefined) {
+          (config as unknown as Record<string, unknown>)[key] = value;
+        }
+      }
+    }
+
+    // Deploy any test-specific L1 contracts while automine is still on and before the node starts,
+    // so they mine instantly rather than paying the L1 block interval once the sequencer is live.
+    let extraL1DeployResult: TDeployExtraL1ContractsReturnType = undefined as TDeployExtraL1ContractsReturnType;
+    if (opts.deployExtraL1Contracts) {
+      logger.trace('Running deployExtraL1Contracts hook');
+      extraL1DeployResult = await opts.deployExtraL1Contracts({
+        l1Client,
+        deployL1ContractsValues,
+        logger,
+      });
+      // The hook reused `l1Client` to send deploy txs, so refresh viem's nonce cache to avoid a
+      // stale cached nonce for later transactions on the publisher account.
+      await l1Client.getTransactionCount({ address: l1Client.account.address });
+    }
+
+    if (enableAutomine) {
+      await ethCheatCodes.startIntervalMiningWithFreshBlock(config.ethereumSlotDuration);
+    }
+
+    // In compose mode (no local anvil), sync dateProvider to L1 time since it may have drifted
+    // ahead of system time. 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 });
+    }
+    logger.trace('Deployed L1 rollup contracts');
+
+    // These boot steps are independent and write disjoint config keys, so run them concurrently:
+    // telemetry returns a client (no config write), shared blob storage writes blobFileStore* keys,
+    // and the ACVM/BB config resolvers write their own acvm*/bb* keys.
+    const [telemetryClient, , acvmConfig, bbConfig] = await Promise.all([
+      // Use metricsPort-based telemetry if provided, otherwise use the regular telemetry client
+      opts.metricsPort ? getEndToEndTestTelemetryClient(opts.metricsPort) : getTelemetryClient(opts.telemetryConfig),
+      setupSharedBlobStorage(config),
+      getACVMConfig(logger),
+      getBBConfig(logger),
+    ]);
+    logger.trace('Created telemetry client');
+    logger.trace('Set up shared blob storage');
+
+    if (acvmConfig) {
+      config.acvmWorkingDirectory = acvmConfig.acvmWorkingDirectory;
+      config.acvmBinaryPath = acvmConfig.acvmBinaryPath;
+    }
+    logger.trace('Resolved ACVM config');
+
+    if (bbConfig) {
+      config.bbBinaryPath = bbConfig.bbBinaryPath;
+      config.bbWorkingDirectory = bbConfig.bbWorkingDirectory;
+    }
+    logger.trace('Resolved Barretenberg config');
+
+    logger.verbose('Creating and synching an aztec node', config);
+
+    let mockGossipSubNetwork: MockGossipSubNetwork | undefined;
+    let p2pClientDeps: P2PClientDeps | undefined = undefined;
+
+    if (opts.mockGossipSubNetwork) {
+      mockGossipSubNetwork = new MockGossipSubNetwork(opts.mockGossipSubNetworkLatency);
+      p2pClientDeps = { p2pServiceFactory: getMockPubSubP2PServiceFactory(mockGossipSubNetwork) };
+    }
+
+    config.p2pEnabled = opts.mockGossipSubNetwork || config.p2pEnabled;
+    config.p2pIp = opts.p2pIp ?? config.p2pIp ?? '127.0.0.1';
+
+    if (!config.disableValidator) {
+      if ((config.validatorPrivateKeys?.getValue().length ?? 0) === 0) {
+        config.validatorPrivateKeys = new SecretValue([generatePrivateKey()]);
+      }
+    }
+
+    // When skipInitialSequencer is set, the initial node is a lightweight RPC-only node.
+    // We apply these overrides to a copy so they don't leak into the returned config.
+    // Keep P2P enabled if mockGossipSubNetwork is used (needed for tx propagation to validators).
+    const initialNodeConfig = opts.skipInitialSequencer
+      ? {
+          ...config,
+          disableValidator: true,
+          ...(opts.mockGossipSubNetwork ? {} : { p2pEnabled: false, bootstrapNodes: [] as string[] }),
+        }
+      : config;
+    logger.trace('Prepared aztec node config');
+
+    const aztecNodeService = await testSpan('setup:env:sequencer-start', () =>
+      withLoggerBindings({ actor: 'node-0' }, () =>
+        createAztecNodeService(
+          initialNodeConfig,
+          { dateProvider, telemetry: telemetryClient, p2pClientDeps },
+          { genesis, dontStartSequencer: opts.skipInitialSequencer },
+        ),
+      ),
+    );
+    const sequencerClient = aztecNodeService.getSequencer();
+    logger.trace('Created and synced aztec node');
+
+    let proverNode: AztecNodeService | undefined = undefined;
+    if (opts.startProverNode) {
+      logger.verbose('Creating and syncing a simulated prover node...');
+      const proverNodePrivateKey = getPrivateKeyFromIndex(2);
+      const proverNodePrivateKeyHex: Hex = `0x${proverNodePrivateKey!.toString('hex')}`;
+      const proverNodeDataDirectory = path.join(directoryToCleanup, randomBytes(8).toString('hex'));
+
+      const p2pClientDeps: Partial<P2PClientDeps> = {
+        p2pServiceFactory: mockGossipSubNetwork && getMockPubSubP2PServiceFactory(mockGossipSubNetwork!),
+        rpcTxProviders: [aztecNodeService],
+      };
+
+      ({ proverNode } = await testSpan('setup:env:prover-node', () =>
+        createAndSyncProverNode(
+          proverNodePrivateKeyHex,
+          config,
+          {
+            ...config.proverNodeConfig,
+            dataDirectory: proverNodeDataDirectory,
+          },
+          { dateProvider, p2pClientDeps, telemetry: telemetryClient },
+          { genesis },
+        ),
+      ));
+      logger.trace('Created prover node');
+    }
+
+    const sequencerDelayer = sequencerClient?.getDelayer();
+    const proverDelayer = proverNode?.getProverNode()?.getDelayer();
+
+    logger.verbose('Creating a pxe...');
+    const pxeConfig = { ...getPXEConfig(), ...pxeOpts };
+    pxeConfig.dataDirectory = path.join(directoryToCleanup, randomBytes(8).toString('hex'));
+    // For tests we only want proving enabled if specifically requested
+    pxeConfig.proverEnabled = !!pxeOpts.proverEnabled;
+    const wallet = await testSpan('setup:env:pxe', () =>
+      TestWallet.create(aztecNodeService, pxeConfig, {
+        loggerActorLabel: 'pxe-0',
+        // In-process node implements the debug API, so register public function signatures for named traces.
+        nodeDebug: aztecNodeService,
+        ...opts.pxeCreationOptions,
+      }),
+    );
+
+    if (opts.walletMinFeePadding !== undefined) {
+      wallet.setMinFeePadding(opts.walletMinFeePadding);
+    }
+    logger.trace('Created PXE and test wallet');
+
+    const cheatCodes = await CheatCodes.create(config.l1RpcUrls, aztecNodeService, dateProvider);
+    logger.trace('Created cheat codes');
+
+    if (
+      (opts.aztecTargetCommitteeSize && opts.aztecTargetCommitteeSize > 0) ||
+      (opts.initialValidators && opts.initialValidators.length > 0)
+    ) {
+      // We need to advance such that the committee is set up.
+      await cheatCodes.rollup.advanceToEpoch(
+        EpochNumber.fromBigInt(
+          BigInt(await cheatCodes.rollup.getEpoch()) + BigInt(config.lagInEpochsForValidatorSet + 1),
+        ),
+      );
+      await cheatCodes.rollup.setupEpoch();
+      await cheatCodes.rollup.debugRollup();
+      logger.trace('Advanced chain to set up validator committee');
+    }
+
+    let accounts: AztecAddress[] = [];
+
+    // Create the default accounts. They are initializerless, so this is a PXE-side operation (registration
+    // + a simulated store call) with no on-chain tx, independent of the sequencer.
+    if (numberOfAccounts > 0) {
+      logger.info(`Creating ${numberOfAccounts} initializerless test accounts`);
+      await testSpan('wallet:create', () => createFundedInitializerlessAccounts(wallet, defaultAccounts));
+      accounts = defaultAccounts.map(a => a.address);
+    }
+    logger.trace('Created funded test accounts');
+
+    const teardown = () =>
+      testSpan('teardown:env', async () => {
+        try {
+          await tryStop(wallet, logger);
+          await tryStop(aztecNodeService, logger);
+          await tryStop(proverNode, logger);
+
+          if (acvmConfig?.cleanup) {
+            await acvmConfig.cleanup();
+          }
+
+          if (bbConfig?.cleanup) {
+            await bbConfig.cleanup();
+          }
+
+          await tryStop(anvil, logger);
+
+          await tryRmDir(directoryToCleanup, logger);
+        } catch (err) {
+          logger.error(`Error during e2e test teardown`, err);
+        } finally {
+          try {
+            await telemetryClient.stop();
+          } catch (err) {
+            logger.error(`Error during telemetry client stop`, err);
+          }
+        }
+      });
+
+    return {
+      anvil,
+      aztecNode: aztecNodeService,
+      aztecNodeService,
+      aztecNodeAdmin: aztecNodeService,
+      cheatCodes,
+      ethCheatCodes,
+      config,
+      aztecNodeConfig: config,
+      dateProvider,
+      deployL1ContractsValues,
+      additionallyFundedAccounts,
+      logger,
+      mockGossipSubNetwork,
+      genesis,
+      extraL1DeployResult,
+      proverNode,
+      sequencerDelayer,
+      proverDelayer,
+      sequencer: sequencerClient,
+      teardown,
+      telemetryClient,
+      wallet,
+      accounts,
+      acvmConfig,
+      bbConfig,
+      directoryToCleanup,
+    };
+  } catch (err) {
+    await anvil?.stop();
+    throw err;
+  }
+}
+
+/** Returns the job name for the current test. */
+function getJobName() {
+  return process.env.JOB_NAME ?? expect.getState().currentTestName?.split(' ')[0].replaceAll('/', '_') ?? 'unknown';
+}
+
+/**
+ * Returns a logger instance for the current test.
+ */
+export function getLogger() {
+  const describeBlockName = expect.getState().currentTestName?.split(' ')[0].replaceAll('/', ':');
+  if (!describeBlockName) {
+    const name = expect.getState().testPath?.split('/').pop()?.split('.')[0] ?? 'unknown';
+    return createLogger('e2e:' + name);
+  }
+  return createLogger('e2e:' + describeBlockName);
+}
+
+/**
+ * Computes the address of the "canonical" SponsoredFPCContract.
+ */
+export function getSponsoredFPCInstance(): Promise<ContractInstanceWithAddress> {
+  return Promise.resolve(
+    getContractInstanceFromInstantiationParams(SponsoredFPCContract.artifact, {
+      salt: new Fr(SPONSORED_FPC_SALT),
+    }),
+  );
+}
+
+/**
+ * Computes the address of the "canonical" SponsoredFPCContract.
+ */
+export async function getSponsoredFPCAddress() {
+  const sponsoredFPCInstance = await getSponsoredFPCInstance();
+  return sponsoredFPCInstance.address;
+}
+
+/**
+ * Deploy a sponsored FPC contract to a running instance.
+ */
+export async function setupSponsoredFPC(wallet: Wallet) {
+  const instance = await getContractInstanceFromInstantiationParams(SponsoredFPCContract.artifact, {
+    salt: new Fr(SPONSORED_FPC_SALT),
+  });
+
+  await wallet.registerContract(instance, SponsoredFPCContract.artifact);
+  getLogger().info(`SponsoredFPC: ${instance.address}`);
+  return instance;
+}
+
+/**
+ * Registers the SponsoredFPC in this PXE instance.
+ */
+export async function registerSponsoredFPC(wallet: Wallet): Promise<void> {
+  await wallet.registerContract(await getSponsoredFPCInstance(), SponsoredFPCContract.artifact);
+}
+
+export async function waitForProvenChain(
+  node: AztecNode,
+  targetBlock?: BlockNumber,
+  timeoutSec = 60,
+  intervalSec = 0.25,
+) {
+  targetBlock ??= await node.getBlockNumber();
+
+  await retryUntil(
+    async () => (await node.getBlockNumber('proven')) >= targetBlock,
+    'proven chain status',
+    timeoutSec,
+    intervalSec,
+  );
+}
+
+/**
+ * Creates an AztecNodeService with the prover node enabled as a subsystem.
+ * Returns both the aztec node service (for lifecycle management) and the prover node (for test internals access).
+ */
+export function createAndSyncProverNode(
+  proverNodePrivateKey: `0x${string}`,
+  baseConfig: AztecNodeConfig,
+  configOverrides: Pick<AztecNodeConfig, 'dataDirectory'>,
+  deps: {
+    telemetry?: TelemetryClient;
+    dateProvider: DateProvider;
+    p2pClientDeps?: P2PClientDeps;
+  },
+  options: { genesis?: GenesisData; dontStart?: boolean },
+): Promise<{ proverNode: AztecNodeService }> {
+  return withLoggerBindings({ actor: 'prover-0' }, async () => {
+    const proverNode = await createAztecNodeService(
+      {
+        ...baseConfig,
+        ...configOverrides,
+        p2pPort: 0,
+        enableProverNode: true,
+        disableValidator: true,
+        proverPublisherPrivateKeys: [new SecretValue(proverNodePrivateKey)],
+      },
+      deps,
+      { genesis: options.genesis, dontStartProverNode: options.dontStart },
+    );
+
+    if (!proverNode.getProverNode()) {
+      throw new Error('Prover node subsystem was not created despite enableProverNode being set');
+    }
+
+    getLogger().info(`Created and synced prover node`);
+    return { proverNode };
+  });
+}
+
+export type BalancesFn = ReturnType<typeof getBalancesFn>;
+export function getBalancesFn(
+  symbol: string,
+  method: ContractMethod,
+  logger: any,
+): (...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(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;
+  };
+
+  return balances;
+}
+
+export async function expectMapping<K, V>(
+  fn: (...k: K[]) => Promise<V[]>,
+  inputs: K[],
+  expectedOutputs: V[],
+): Promise<void> {
+  expect(inputs.length).toBe(expectedOutputs.length);
+
+  const outputs = await fn(...inputs);
+
+  expect(outputs).toEqual(expectedOutputs);
+}
+
+export async function expectMappingDelta<K, V extends number | bigint>(
+  initialValues: V[],
+  fn: (...k: K[]) => Promise<V[]>,
+  inputs: K[],
+  expectedDiffs: V[],
+): Promise<void> {
+  expect(inputs.length).toBe(expectedDiffs.length);
+
+  const outputs = await fn(...inputs);
+  const diffs = outputs.map((output, i) => output - initialValues[i]);
+
+  expect(diffs).toEqual(expectedDiffs);
+}
+
+/**
+ * Registers the auth_registry contract class and publishes its standard instance if not already
+ * present, and registers the artifact with PXE. Publishing is required before exercising the public
+ * authwit path (which relies on the AVM's deployment-nullifier check); the PXE-side registration is
+ * required so revert messages from AuthRegistry calls can be enriched (otherwise assertion strings
+ * surface as generic "Assertion failed:" and tests that match on the real message fail).
+ */
+export async function ensureAuthRegistryPublished(wallet: Wallet, from: AztecAddress) {
+  await testSpan('setup:auth-registry', async () => {
+    const { instance, contractClass } = await getStandardAuthRegistry();
+    if (!(await wallet.getContractClassMetadata(contractClass.id)).isContractClassPubliclyRegistered) {
+      await (await publishContractClass(wallet, AuthRegistryArtifact)).send({ from });
+    }
+    if (!(await wallet.getContractMetadata(instance.address)).isContractPublished) {
+      await publishInstance(wallet, instance).send({ from });
+    }
+    await wallet.registerContract(instance, AuthRegistryArtifact);
+  });
+}
+
+/**
+ * Registers the public_checks contract class and publishes its standard instance if not already
+ * present, and registers the artifact with PXE. Required for any contract that calls
+ * `privately_check_timestamp` / `privately_check_block_number` (which dispatch into the
+ * deployed PublicChecks contract via an enqueued public call).
+ */
+export async function ensurePublicChecksPublished(wallet: Wallet, from: AztecAddress) {
+  const { instance, contractClass } = await getStandardPublicChecks();
+  if (!(await wallet.getContractClassMetadata(contractClass.id)).isContractClassPubliclyRegistered) {
+    await (await publishContractClass(wallet, PublicChecksArtifact)).send({ from });
+  }
+  if (!(await wallet.getContractMetadata(instance.address)).isContractPublished) {
+    await publishInstance(wallet, instance).send({ from });
+  }
+  await wallet.registerContract(instance, PublicChecksArtifact);
+}
+
+/**
+ * Registers the handshake_registry contract class and publishes its standard instance if not
+ * already present, and registers the artifact with PXE. Required for constrained-delivery flows
+ * that call into the HandshakeRegistry at its well-known address.
+ */
+export async function ensureHandshakeRegistryPublished(wallet: Wallet, from: AztecAddress) {
+  const { instance, contractClass } = await getStandardHandshakeRegistry();
+  if (!(await wallet.getContractClassMetadata(contractClass.id)).isContractClassPubliclyRegistered) {
+    await (await publishContractClass(wallet, HandshakeRegistryArtifact)).send({ from });
+  }
+  if (!(await wallet.getContractMetadata(instance.address)).isContractPublished) {
+    await publishInstance(wallet, instance).send({ from });
+  }
+  await wallet.registerContract(instance, HandshakeRegistryArtifact);
+}
+
+/**
+ * Destroys the current context.
+ */
+export async function teardown(context: EndToEndContext | undefined) {
+  if (!context) {
+    return;
+  }
+  await context.teardown();
+}
+
+// Re-export for backward compatibility
+export { deployAndInitializeTokenAndBridgeContracts } from '../shared/cross_chain_test_harness.js';