feat: exported in-process testing network (#24629)

Upstreaming the utilities build for `aztec-kit` so external projects can
benefit from our e2e scaffolding. Essentially the same thing we already
use, but pure ts rather than the unpublishable .sh script. Verified with
`ci-full-no-test-cache`

(cherry picked from commit 7e09008)

Author: Thunkar

l1-contracts/scripts/forge_broadcast.js

@@ -59,11 +59,11 @@ const timeoutMs =
   (isAnvil ? 120_000 : 1_200_000);
 
 const proc = spawn(
-  "forge",
+  process.env.FORGE_BIN || "forge",
   ["script", ...args, "--broadcast", "--batch-size", batchSize],
   {
     stdio: ["ignore", "pipe", "inherit"],
-  },
+  }
 );
 
 const stdout = [];
@@ -85,14 +85,14 @@ const exitCode = await new Promise((resolve) => {
   });
   proc.on("close", (code) => {
     clearTimeout(timeout);
-    resolve(timedOut ? 1 : (code ?? 1));
+    resolve(timedOut ? 1 : code ?? 1);
   });
 });
 
 log(
   exitCode === 0
     ? "Broadcast succeeded."
-    : `Broadcast failed (exit ${exitCode}).`,
+    : `Broadcast failed (exit ${exitCode}).`
 );
 const data = Buffer.concat(stdout);
 if (data.length > 0) writeSync(1, data);

yarn-project/aztec/bootstrap.sh

@@ -12,6 +12,8 @@ function test_cmds {
   # All CLI tests share test/mixed-workspace/target so they must run sequentially
   # in a single jest invocation (--runInBand is set by run_test.sh).
   echo "$hash:ISOLATE=1:NAME=aztec/cli NARGO=$NARGO BB=$BB PROFILER_PATH=$PROFILER_PATH yarn-project/scripts/run_test.sh aztec/src/cli"
+  # setupLocalNetwork smoke test: spins up anvil + an in-process node (network usage ⇒ ISOLATE).
+  echo "$hash:ISOLATE=1:NAME=aztec/testing yarn-project/scripts/run_test.sh aztec/src/testing/local-network.test.ts"
 }
 
 case "$cmd" in

yarn-project/aztec/src/local-network/local-network.ts

@@ -88,6 +88,8 @@ export type LocalNetworkConfig = AztecNodeConfig & {
   l1Mnemonic: string;
   /** Whether to deploy test accounts on local network start.*/
   testAccounts: boolean;
+  /** Override the default per-address fee juice granted at genesis to funded addresses. */
+  initialAccountFeeJuice?: Fr;
 };
 
 /**
@@ -176,7 +178,10 @@ export async function createLocalNetwork(config: Partial<LocalNetworkConfig> = {
     ...(initialAccounts.length ? [bananaFPC, sponsoredFPC] : []),
     ...prefundAddresses,
   ];
-  const { genesisArchiveRoot, genesis, fundingNeeded } = await getGenesisValues(fundedAddresses);
+  const { genesisArchiveRoot, genesis, fundingNeeded } = await getGenesisValues(
+    fundedAddresses,
+    config.initialAccountFeeJuice,
+  );
 
   const dateProvider = new TestDateProvider();
 

yarn-project/aztec/src/testing/index.ts

@@ -1,4 +1,5 @@
 export { EthCheatCodes, RollupCheatCodes } from '@aztec/ethereum/test';
 export { CheatCodes } from './cheat_codes.js';
 export { EpochTestSettler } from './epoch_test_settler.js';
+export { setupLocalNetwork, TEST_FEE_PADDING, type LocalNetwork, type LocalNetworkOptions } from './local-network.js';
 export { getTokenAllowedSetupFunctions } from './token_allowed_setup.js';

yarn-project/aztec/src/testing/local-network.test.ts

@@ -0,0 +1,52 @@
+import { getInitialTestAccountsData } from '@aztec/accounts/testing';
+import { TokenContract } from '@aztec/noir-contracts.js/Token';
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
+
+import { TEST_FEE_PADDING, setupLocalNetwork } from './local-network.js';
+
+describe('setupLocalNetwork', () => {
+  it('serves a live node on a random L1 port and tears down cleanly', async () => {
+    await using net = await setupLocalNetwork();
+    const info = await net.node.getNodeInfo();
+    expect(info.l1ContractAddresses.rollupAddress).toBeDefined();
+    expect(await net.node.getBlockNumber()).toBeGreaterThanOrEqual(0);
+    expect(net.l1ChainId).toBe(31337);
+    // OS-assigned ephemeral port, never the fixed default 8545.
+    expect(net.l1RpcUrl).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+    expect(net.l1RpcUrl).not.toContain(':8545');
+  }, 300_000);
+
+  it('runs two networks in parallel on distinct ports', async () => {
+    const [a, b] = await Promise.all([setupLocalNetwork(), setupLocalNetwork()]);
+    try {
+      expect(a.l1RpcUrl).not.toEqual(b.l1RpcUrl);
+      expect(await a.node.getBlockNumber()).toBeGreaterThanOrEqual(0);
+      expect(await b.node.getBlockNumber()).toBeGreaterThanOrEqual(0);
+    } finally {
+      await Promise.all([a.stop(), b.stop()]);
+    }
+  }, 300_000);
+
+  it('pre-funds addresses at genesis so they can pay for their own txs', async () => {
+    const [alice] = await getInitialTestAccountsData();
+    const net = await setupLocalNetwork({ fundedAddresses: [alice.address] });
+    try {
+      const wallet = await EmbeddedWallet.create(net.node, {
+        ephemeral: true,
+        pxeConfig: { proverEnabled: false },
+      });
+      await wallet.createSchnorrInitializerlessAccount(alice.secret, alice.salt, alice.signingKey);
+      wallet.setMinFeePadding(TEST_FEE_PADDING);
+
+      const { contract } = await TokenContract.deploy(wallet, alice.address, 'TokenName', 'TKN', 18).send({
+        from: alice.address,
+      });
+      expect(contract.address).toBeDefined();
+      expect(await net.node.getBlockNumber()).toBeGreaterThan(0);
+
+      await wallet.stop();
+    } finally {
+      await net.stop();
+    }
+  }, 300_000);
+});

yarn-project/aztec/src/testing/local-network.ts

@@ -0,0 +1,97 @@
+import type { AztecNodeService } from '@aztec/aztec-node';
+import type { AztecNodeConfig } from '@aztec/aztec-node/config';
+import type { Fr } from '@aztec/aztec.js/fields';
+import { startAnvil } from '@aztec/ethereum/test';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+import { foundry } from 'viem/chains';
+
+import { createLocalNetwork } from '../local-network/local-network.js';
+
+/** A running in-process local network: an inline Aztec node backed by its own anvil L1. */
+export interface LocalNetwork extends AsyncDisposable {
+  /** Fully-synced Aztec node, ready to serve client requests. */
+  node: AztecNodeService;
+  /** RPC URL of the spawned anvil instance. */
+  l1RpcUrl: string;
+  /** Chain id used on L1 (foundry's default 31337). */
+  l1ChainId: number;
+  /** Stops every process started by the fixture: node and anvil. Also invoked by `await using`. */
+  stop: () => Promise<void>;
+}
+
+/** Options for {@link setupLocalNetwork}. */
+export interface LocalNetworkOptions {
+  /**
+   * Addresses that should hold fee juice at genesis. Saves each of these the round-trip of bridging
+   * + claiming fee juice before they can pay for gas.
+   */
+  fundedAddresses?: AztecAddress[];
+  /** Override the default per-address genesis fee juice granted to {@link fundedAddresses}. */
+  initialAccountFeeJuice?: Fr;
+  /** Node config overrides, e.g. `realProofs`, `aztecEpochDuration`, `p2pEnabled`. */
+  config?: Partial<AztecNodeConfig>;
+}
+
+/**
+ * Spin up an in-process local network with the given addresses pre-funded.
+ *
+ * Each call spawns its own anvil on an OS-assigned random port and runs the Aztec node inline via
+ * the same {@link createLocalNetwork} codepath that backs `aztec start --local-network` (with the
+ * sandbox account/FPC/token setup skipped). Distinct ports let independent suites run in parallel.
+ * The caller must `await result.stop()` in its teardown (or hold the result with `await using`).
+ *
+ * Requires a Foundry toolchain (`anvil`/`forge`), installed via `aztec-up` or `foundryup`. Binaries
+ * are located in the standard install directories or on `PATH`; set `$ANVIL_BIN` / `$FORGE_BIN` to
+ * pin specific ones.
+ */
+export async function setupLocalNetwork(opts: LocalNetworkOptions = {}): Promise<LocalNetwork> {
+  // `--port 0` → anvil binds an ephemeral port that `startAnvil` reads back, so parallel suites
+  // never collide on a fixed port.
+  const { rpcUrl, stop: stopAnvil } = await startAnvil({ port: 0 });
+
+  try {
+    const { node, stop: stopNode } = await createLocalNetwork(
+      {
+        ...opts.config,
+        l1RpcUrls: [rpcUrl],
+        testAccounts: false,
+        prefundAddresses: (opts.fundedAddresses ?? []).map(a => a.toString()),
+        initialAccountFeeJuice: opts.initialAccountFeeJuice,
+      },
+      () => {},
+    );
+
+    // Stop the node before anvil (its teardown still talks to L1); the finally guarantees anvil is
+    // reaped even if node shutdown throws.
+    const stop = async () => {
+      try {
+        await stopNode();
+      } finally {
+        await stopAnvil();
+      }
+    };
+
+    return {
+      node,
+      l1RpcUrl: rpcUrl,
+      l1ChainId: foundry.id,
+      stop,
+      [Symbol.asyncDispose]: stop,
+    };
+  } catch (err) {
+    await stopAnvil();
+    throw err;
+  }
+}
+
+/**
+ * Min-fee padding multiplier for test wallets whose txs may mine well after their fee estimate.
+ * The automine sequencer builds one block per tx and advances L1 time in big jumps, and proposer
+ * pipelining evolves the fee-asset price across the build/publish gap (~20x observed in CI), so the
+ * network's congestion base fee can swing sharply between the wallet's fee estimate and the block
+ * the tx actually lands in. The default wallet padding isn't enough and trips
+ * `maxFeesPerGas.feePerL2Gas must be >= gasFees.feePerL2Gas`. Apply via
+ * `wallet.setMinFeePadding(TEST_FEE_PADDING)` on every test wallet that sends txs.
+ */
+export const TEST_FEE_PADDING = 30;

yarn-project/end-to-end/src/fixtures/fixtures.ts

@@ -1,4 +1,5 @@
 import type { AztecNode } from '@aztec/aztec.js/node';
+import { TEST_FEE_PADDING } from '@aztec/aztec/testing';
 import type { GasFees } from '@aztec/stdlib/gas';
 
 export const METRICS_PORT = 4318;
@@ -17,9 +18,10 @@ export const LARGE_MIN_FEE_PADDING = 15;
  * price modifier evolves faster across the build/publish gap, so client-set maxFeesPerGas (sized
  * for the default 5x padding) was getting bumped past by the time the tx mined a few slots later.
  * Observed worst case in CI: fee evolved ~20x between PXE snapshot and inclusion, exceeding even
- * LARGE_MIN_FEE_PADDING (15x).
+ * LARGE_MIN_FEE_PADDING (15x). Same multiplier and same class of problem as the published
+ * {@link TEST_FEE_PADDING}, re-exported under a name that captures the pipelining rationale.
  */
-export const PIPELINED_FEE_PADDING = 30;
+export const PIPELINED_FEE_PADDING = TEST_FEE_PADDING;
 
 /**
  * Setup option preset that opts a test into proposer pipelining. Use with `setup()`:
@@ -77,7 +79,7 @@ export const AUTOMINE_E2E_OPTS = {
   minTxsPerBlock: 0,
   aztecSlotDuration: 12,
   ethereumSlotDuration: 4,
-  walletMinFeePadding: PIPELINED_FEE_PADDING,
+  walletMinFeePadding: TEST_FEE_PADDING,
 } as const;
 
 /** Returns worst-case predicted min fees with padding applied, mirroring the BaseWallet pattern. */

yarn-project/ethereum/scripts/anvil_kill_wrapper.sh

@@ -22,6 +22,7 @@ import { createExtendedL1Client } from './client.js';
 import { type L1ContractsConfig, assertValidSlotDurations } from './config.js';
 import { deployMulticall3 } from './contracts/multicall.js';
 import { RollupContract } from './contracts/rollup.js';
+import { resolveFoundryBinary } from './foundry_binary.js';
 import type { L1ContractAddresses } from './l1_contract_addresses.js';
 import type { ExtendedViemWalletClient } from './types.js';
 
@@ -95,11 +96,16 @@ function runProcess<T>(
 
 // Covers an edge where where we may have a cached BlobLib that is not meant for production.
 // Despite the profile apparently sometimes cached code remains (so says Lasse after his ignition-monorepo arc).
-async function maybeForgeForceProductionBuild(l1ContractsPath: string, script: string, chainId: number) {
+async function maybeForgeForceProductionBuild(
+  forgeBin: string,
+  l1ContractsPath: string,
+  script: string,
+  chainId: number,
+) {
   if (chainId === mainnet.id) {
     logger.info(`Recompiling ${script} with production profile for mainnet deployment`);
     logger.info('This may take a minute but ensures production BlobLib is used.');
-    await runProcess('forge', ['build', script, '--force'], { FOUNDRY_PROFILE: 'production' }, l1ContractsPath);
+    await runProcess(forgeBin, ['build', script, '--force'], { FOUNDRY_PROFILE: 'production' }, l1ContractsPath);
   }
 }
 
@@ -320,8 +326,9 @@ export async function deployAztecL1Contracts(
   // Use foundry-artifacts from l1-artifacts package
   const l1ContractsPath = prepareL1ContractsForDeployment();
 
+  const forgeBin = resolveFoundryBinary('forge');
   const FORGE_SCRIPT = 'script/deploy/DeployAztecL1Contracts.s.sol';
-  await maybeForgeForceProductionBuild(l1ContractsPath, FORGE_SCRIPT, chainId);
+  await maybeForgeForceProductionBuild(forgeBin, l1ContractsPath, FORGE_SCRIPT, chainId);
 
   // Verify contracts on Etherscan when on mainnet/sepolia and ETHERSCAN_API_KEY is available.
   const isVerifiableChain = chainId === mainnet.id || chainId === sepolia.id;
@@ -346,6 +353,8 @@ export async function deployAztecL1Contracts(
     ...(shouldVerify ? ['--verify'] : []),
   ];
   const forgeEnv = {
+    // Resolved forge binary picked up by forge_broadcast.js, so it works without forge on PATH.
+    FORGE_BIN: forgeBin,
     // Env vars required by l1-contracts/script/deploy/DeploymentConfiguration.sol.
     NETWORK: getActiveNetworkName(),
     FOUNDRY_PROFILE: chainId === mainnet.id ? 'production' : undefined,
@@ -618,12 +627,15 @@ export const deployRollupForUpgrade = async (
   // Use foundry-artifacts from l1-artifacts package
   const l1ContractsPath = prepareL1ContractsForDeployment();
 
+  const forgeBin = resolveFoundryBinary('forge');
   const FORGE_SCRIPT = 'script/deploy/DeployRollupForUpgrade.s.sol';
-  await maybeForgeForceProductionBuild(l1ContractsPath, FORGE_SCRIPT, chainId);
+  await maybeForgeForceProductionBuild(forgeBin, l1ContractsPath, FORGE_SCRIPT, chainId);
 
   const scriptPath = join(getL1ContractsPath(), 'scripts', 'forge_broadcast.js');
   const forgeArgs = [FORGE_SCRIPT, '--sig', 'run()', '--private-key', privateKey, '--rpc-url', rpcUrl];
   const forgeEnv = {
+    // Resolved forge binary picked up by forge_broadcast.js, so it works without forge on PATH.
+    FORGE_BIN: forgeBin,
     FOUNDRY_PROFILE: chainId === mainnet.id ? 'production' : undefined,
     // Env vars required by l1-contracts/script/deploy/RollupConfiguration.sol.
     REGISTRY_ADDRESS: registryAddress.toString(),