@aztec/end-to-end 0.0.1-commit.c2595eba → 0.0.1-commit.c2eed6949

package/src/spartan/setup_test_wallets.ts

@@ -1,4 +1,5 @@
 import { generateSchnorrAccounts } from '@aztec/accounts/testing';
+import { NO_FROM } from '@aztec/aztec.js/account';
 import { AztecAddress } from '@aztec/aztec.js/addresses';
 import { NO_WAIT } from '@aztec/aztec.js/contracts';
 import { L1FeeJuicePortalManager } from '@aztec/aztec.js/ethereum';
@@ -13,11 +14,14 @@ import type { Logger } from '@aztec/foundation/log';
 import { retryUntil } from '@aztec/foundation/retry';
 import { TokenContract } from '@aztec/noir-contracts.js/Token';
 import type { AztecNodeAdmin } from '@aztec/stdlib/interfaces/client';
-import { TestWallet, proveInteraction, registerInitialLocalNetworkAccountsInWallet } from '@aztec/test-wallet/server';
+import { registerInitialLocalNetworkAccountsInWallet } from '@aztec/wallets/testing';
 
 import { getACVMConfig } from '../fixtures/get_acvm_config.js';
 import { getBBConfig } from '../fixtures/get_bb_config.js';
 import { getSponsoredFPCAddress, registerSponsoredFPC } from '../fixtures/utils.js';
+import { TestWallet } from '../test-wallet/test_wallet.js';
+import { proveInteraction } from '../test-wallet/utils.js';
+import { WorkerWallet } from '../test-wallet/worker_wallet.js';
 
 export interface TestAccounts {
   aztecNode: AztecNode;
@@ -85,11 +89,19 @@ export async function deploySponsoredTestAccountsWithTokens(
 
   const paymentMethod = new SponsoredFeePaymentMethod(await getSponsoredFPCAddress());
   const recipientDeployMethod = await recipientAccount.getDeployMethod();
-  await recipientDeployMethod.send({ from: AztecAddress.ZERO, fee: { paymentMethod }, wait: { timeout: 2400 } });
+  await recipientDeployMethod.send({
+    from: NO_FROM,
+    fee: { paymentMethod },
+    wait: { timeout: 2400 },
+  });
   await Promise.all(
     fundedAccounts.map(async a => {
       const deployMethod = await a.getDeployMethod();
-      await deployMethod.send({ from: AztecAddress.ZERO, fee: { paymentMethod }, wait: { timeout: 2400 } }); // increase timeout on purpose in order to account for two empty epochs
+      await deployMethod.send({
+        from: NO_FROM,
+        fee: { paymentMethod },
+        wait: { timeout: 2400 },
+      }); // increase timeout on purpose in order to account for two empty epochs
       logger.info(`Account deployed at ${a.address}`);
     }),
   );
@@ -118,16 +130,28 @@ export async function deploySponsoredTestAccountsWithTokens(
 }
 
 async function deployAccountWithDiagnostics(
-  account: { getDeployMethod: () => Promise<{ send: (opts: any) => any }>; address: any },
+  account: { getDeployMethod: () => Promise<{ simulate: (opts: any) => any; send: (opts: any) => any }>; address: any },
   paymentMethod: SponsoredFeePaymentMethod,
   aztecNode: AztecNode,
   logger: Logger,
   accountLabel: string,
+  estimateGas?: boolean,
 ): Promise<void> {
   const deployMethod = await account.getDeployMethod();
   let txHash;
   try {
-    txHash = await deployMethod.send({ from: AztecAddress.ZERO, fee: { paymentMethod }, wait: NO_WAIT });
+    let gasSettings;
+    if (estimateGas) {
+      const sim = await deployMethod.simulate({ from: NO_FROM, fee: { paymentMethod } });
+      gasSettings = sim.estimatedGas;
+      logger.info(`${accountLabel} estimated gas: DA=${gasSettings.gasLimits.daGas} L2=${gasSettings.gasLimits.l2Gas}`);
+    }
+    const deployResult = await deployMethod.send({
+      from: NO_FROM,
+      fee: { paymentMethod, gasSettings },
+      wait: NO_WAIT,
+    });
+    txHash = deployResult.txHash;
     await waitForTx(aztecNode, txHash, { timeout: 2400 });
     logger.info(`${accountLabel} deployed at ${account.address}`);
   } catch (error) {
@@ -149,18 +173,29 @@ async function deployAccountWithDiagnostics(
 }
 
 async function deployAccountsInBatches(
-  accounts: { getDeployMethod: () => Promise<{ send: (opts: any) => any }>; address: any }[],
+  accounts: {
+    getDeployMethod: () => Promise<{ simulate: (opts: any) => any; send: (opts: any) => any }>;
+    address: any;
+  }[],
   paymentMethod: SponsoredFeePaymentMethod,
   aztecNode: AztecNode,
   logger: Logger,
   labelPrefix: string,
   batchSize = 2,
+  estimateGas?: boolean,
 ): Promise<void> {
   for (let i = 0; i < accounts.length; i += batchSize) {
     const batch = accounts.slice(i, i + batchSize);
     await Promise.all(
       batch.map((account, idx) =>
-        deployAccountWithDiagnostics(account, paymentMethod, aztecNode, logger, `${labelPrefix}${i + idx + 1}`),
+        deployAccountWithDiagnostics(
+          account,
+          paymentMethod,
+          aztecNode,
+          logger,
+          `${labelPrefix}${i + idx + 1}`,
+          estimateGas,
+        ),
       ),
     );
   }
@@ -171,6 +206,7 @@ export async function deploySponsoredTestAccounts(
   aztecNode: AztecNode,
   logger: Logger,
   numberOfFundedWallets = 1,
+  opts?: { estimateGas?: boolean },
 ): Promise<TestAccountsWithoutTokens> {
   const [recipient, ...funded] = await generateSchnorrAccounts(numberOfFundedWallets + 1);
   const recipientAccount = await wallet.createSchnorrAccount(recipient.secret, recipient.salt);
@@ -180,8 +216,23 @@ export async function deploySponsoredTestAccounts(
 
   const paymentMethod = new SponsoredFeePaymentMethod(await getSponsoredFPCAddress());
 
-  await deployAccountWithDiagnostics(recipientAccount, paymentMethod, aztecNode, logger, 'Recipient account');
-  await deployAccountsInBatches(fundedAccounts, paymentMethod, aztecNode, logger, 'Funded account ', 2);
+  await deployAccountWithDiagnostics(
+    recipientAccount,
+    paymentMethod,
+    aztecNode,
+    logger,
+    'Recipient account',
+    opts?.estimateGas,
+  );
+  await deployAccountsInBatches(
+    fundedAccounts,
+    paymentMethod,
+    aztecNode,
+    logger,
+    'Funded account ',
+    2,
+    opts?.estimateGas,
+  );
 
   return {
     aztecNode,
@@ -219,7 +270,7 @@ export async function deployTestAccountsWithTokens(
     fundedAccounts.map(async (a, i) => {
       const paymentMethod = new FeeJuicePaymentMethodWithClaim(a.address, claims[i]);
       const deployMethod = await a.getDeployMethod();
-      await deployMethod.send({ from: AztecAddress.ZERO, fee: { paymentMethod } });
+      await deployMethod.send({ from: NO_FROM, fee: { paymentMethod } });
       logger.info(`Account deployed at ${a.address}`);
     }),
   );
@@ -263,7 +314,7 @@ async function bridgeL1FeeJuice(
   const claim = await portal.bridgeTokensPublic(recipient, amount, true /* mint */);
 
   const isSynced = async () =>
-    (await aztecNode.getL1ToL2MessageBlock(Fr.fromHexString(claim.messageHash))) !== undefined;
+    (await aztecNode.getL1ToL2MessageCheckpoint(Fr.fromHexString(claim.messageHash))) !== undefined;
   await retryUntil(isSynced, `message ${claim.messageHash} sync`, 24, 0.5);
 
   log.info(`Created a claim for ${amount} L1 fee juice to ${recipient}.`, claim);
@@ -295,13 +346,9 @@ async function deployTokenAndMint(
   logger: Logger,
 ) {
   logger.verbose(`Deploying TokenContract...`);
-  const { contract: tokenContract } = await TokenContract.deploy(
-    wallet,
-    admin,
-    TOKEN_NAME,
-    TOKEN_SYMBOL,
-    TOKEN_DECIMALS,
-  ).send({
+  const {
+    receipt: { contract: tokenContract },
+  } = await TokenContract.deploy(wallet, admin, TOKEN_NAME, TOKEN_SYMBOL, TOKEN_DECIMALS).send({
     from: admin,
     fee: {
       paymentMethod,
@@ -395,3 +442,42 @@ export async function createWalletAndAztecNodeClient(
     },
   };
 }
+
+export type WorkerWalletWrapper = {
+  wallet: WorkerWallet;
+  aztecNode: AztecNode;
+  cleanup: () => Promise<void>;
+};
+
+export async function createWorkerWalletClient(
+  nodeUrl: string,
+  proverEnabled: boolean,
+  logger: Logger,
+): Promise<WorkerWalletWrapper> {
+  const aztecNode = createAztecNodeClient(nodeUrl);
+  const [bbConfig, acvmConfig] = await Promise.all([getBBConfig(logger), getACVMConfig(logger)]);
+
+  // Strip cleanup functions — they can't be structured-cloned for worker transfer
+  const { cleanup: bbCleanup, ...bbPaths } = bbConfig ?? {};
+  const { cleanup: acvmCleanup, ...acvmPaths } = acvmConfig ?? {};
+
+  const pxeConfig = {
+    dataDirectory: undefined,
+    dataStoreMapSizeKb: 1024 * 1024,
+    ...bbPaths,
+    ...acvmPaths,
+    proverEnabled,
+  };
+
+  const wallet = await WorkerWallet.create(nodeUrl, pxeConfig);
+
+  return {
+    wallet,
+    aztecNode,
+    async cleanup() {
+      await wallet.stop();
+      await bbCleanup?.();
+      await acvmCleanup?.();
+    },
+  };
+}

package/src/spartan/tx_metrics.ts

@@ -296,7 +296,7 @@ export class TxInclusionMetrics {
           value: stats.mean,
         },
         {
-          name: `${group}/median_inclusion`,
+          name: `${group}/p50_inclusion`,
           unit: 's',
           value: stats.median,
         },

package/src/spartan/utils/bot.ts

@@ -34,7 +34,8 @@ export async function installTransferBot({
   logger: log,
   replicas = 1,
   txIntervalSeconds = 10,
-  followChain = 'PENDING',
+  followChain = 'CHECKPOINTED',
+  pxeSyncChainTip = 'proposed',
   mnemonic = process.env.LABS_INFRA_MNEMONIC ?? 'test test test test test test test test test test test junk',
   mnemonicStartIndex,
   botPrivateKey = process.env.BOT_TRANSFERS_L2_PRIVATE_KEY ?? '0xcafe01',
@@ -49,6 +50,7 @@ export async function installTransferBot({
   replicas?: number;
   txIntervalSeconds?: number;
   followChain?: string;
+  pxeSyncChainTip?: string;
   mnemonic?: string;
   mnemonicStartIndex?: number | string;
   botPrivateKey?: string;
@@ -67,6 +69,7 @@ export async function installTransferBot({
     'bot.replicaCount': replicas,
     'bot.txIntervalSeconds': txIntervalSeconds,
     'bot.followChain': followChain,
+    'bot.pxeSyncChainTip': pxeSyncChainTip,
     'bot.botPrivateKey': botPrivateKey,
     'bot.nodeUrl': resolvedNodeUrl,
     'bot.mnemonic': mnemonic,

package/src/spartan/utils/config.ts

@@ -8,6 +8,7 @@ const logger = createLogger('e2e:k8s-utils');
 const testConfigSchema = z.object({
   NAMESPACE: z.string().default('scenario'),
   REAL_VERIFIER: schemas.Boolean.optional().default(true),
+  DEBUG_FORCE_TX_PROOF_VERIFICATION: schemas.Boolean.optional().default(true),
   CREATE_ETH_DEVNET: schemas.Boolean.optional().default(false),
   L1_RPC_URLS_JSON: z.string().optional(),
   L1_ACCOUNT_MNEMONIC: z.string().optional(),
@@ -15,6 +16,8 @@ const testConfigSchema = z.object({
   AZTEC_EPOCH_DURATION: z.coerce.number().optional().default(32),
   AZTEC_PROOF_SUBMISSION_WINDOW: z.coerce.number().optional().default(5),
   AZTEC_LAG_IN_EPOCHS_FOR_VALIDATOR_SET: z.coerce.number().optional().default(2),
+  FUNDING_PRIVATE_KEY: z.string().optional(),
+  AZTEC_ADMIN_API_KEY: z.string().optional(),
 });
 
 export type TestConfig = z.infer<typeof testConfigSchema>;

package/src/spartan/utils/index.ts

@@ -5,7 +5,7 @@
 export { type TestConfig, setupEnvironment } from './config.js';
 
 // Scripts
-export { getGitProjectRoot, getAztecBin, runAztecBin, runProjectScript } from './scripts.js';
+export { type ScriptResult, getGitProjectRoot, getAztecBin, runAztecBin, runProjectScript } from './scripts.js';
 
 // K8s operations
 export {
@@ -25,6 +25,7 @@ export {
   getRPCEndpoint,
   getEthereumEndpoint,
   createResilientPrometheusConnection,
+  scaleProverAgents,
 } from './k8s.js';
 
 // Chaos Mesh
@@ -40,6 +41,9 @@ export {
   applyNetworkShaping,
 } from './chaos.js';
 
+// Helm
+export { hasDeployedHelmRelease } from './helm.js';
+
 // Bot management
 export { restartBot, installTransferBot, uninstallTransferBot } from './bot.js';
 
@@ -62,3 +66,6 @@ export { getPublicViemClient, getL1DeploymentAddresses, getNodeClient } from './
 
 // Health checks
 export { ChainHealth, type ChainHealthSnapshot } from './health.js';
+
+// Pod log extraction
+export { type BlockBuiltLogEntry, fetchBlockBuiltLogs } from './pod_logs.js';

package/src/spartan/utils/k8s.ts

@@ -522,6 +522,14 @@ export function createResilientPrometheusConnection(
   return { connect, runAlertCheck };
 }
 
+/** Scales the prover-agent Deployment to the given number of replicas. */
+export async function scaleProverAgents(namespace: string, replicas: number, log: Logger): Promise<void> {
+  const label = 'app.kubernetes.io/component=prover-agent';
+  const command = `kubectl scale deployment -l ${label} -n ${namespace} --replicas=${replicas} --timeout=2m`;
+  log.info(`Scaling prover agents to ${replicas}: ${command}`);
+  await execAsync(command);
+}
+
 export function getChartDir(spartanDir: string, chartName: string) {
   return path.join(spartanDir.trim(), chartName);
 }

package/src/spartan/utils/nodes.ts

@@ -21,6 +21,7 @@ import {
   getChartDir,
   startPortForward,
   waitForResourceByLabel,
+  waitForResourceByName,
   waitForStatefulSetsReady,
 } from './k8s.js';
 
@@ -154,6 +155,8 @@ export async function withSequencersAdmin<T>(env: TestConfig, fn: (node: AztecNo
   const results = [];
 
   for (const sequencer of sequencers) {
+    // Ensure pod is Ready before attempting port-forward.
+    await waitForResourceByName({ resource: 'pods', name: sequencer, namespace });
     // Wrap port-forward + fetch in a retry to handle flaky port-forwards
     const result = await retry(
       async () => {
@@ -170,7 +173,7 @@ export async function withSequencersAdmin<T>(env: TestConfig, fn: (node: AztecNo
           if (statusRes.status !== 200) {
             throw new Error(`Admin endpoint returned status ${statusRes.status}`);
           }
-          const client = createAztecNodeAdminClient(url);
+          const client = createAztecNodeAdminClient(url, {}, undefined, env.AZTEC_ADMIN_API_KEY);
           return { result: await fn(client), process };
         } catch (err) {
           // Kill the port-forward before retrying
@@ -252,21 +255,18 @@ export async function initHADb(namespace: string): Promise<void> {
 }
 
 /**
- * Enables or disables probabilistic transaction dropping on validators and waits for rollout.
- * Wired to env vars P2P_DROP_TX and P2P_DROP_TX_CHANCE via Helm values.
+ * Sets probabilistic transaction dropping on validators and waits for rollout.
+ * Use probability=0 to disable. Wired to env var P2P_DROP_TX_CHANCE via Helm values.
  */
 export async function setValidatorTxDrop({
   namespace,
-  enabled,
   probability,
   logger: log,
 }: {
   namespace: string;
-  enabled: boolean;
   probability: number;
   logger: Logger;
 }) {
-  const drop = enabled ? 'true' : 'false';
   const prob = String(probability);
 
   const selectors = ['app.kubernetes.io/name=validator', 'app.kubernetes.io/component=validator', 'app=validator'];
@@ -281,7 +281,7 @@ export async function setValidatorTxDrop({
       if (names.length === 0) {
         continue;
       }
-      const cmd = `kubectl set env statefulset -l ${selector} -n ${namespace} P2P_DROP_TX=${drop} P2P_DROP_TX_CHANCE=${prob}`;
+      const cmd = `kubectl set env statefulset -l ${selector} -n ${namespace} P2P_DROP_TX_CHANCE=${prob}`;
       log.info(`command: ${cmd}`);
       await execAsync(cmd);
       updated = true;
@@ -363,16 +363,24 @@ export async function enableValidatorDynamicBootNode(
  */
 export async function rollAztecPods(namespace: string, clearState: boolean = false) {
   // Pod components use 'validator', but StatefulSets and PVCs use 'sequencer-node' for validators
+  // RPC nodes have nodeType='rpc-node' in Helm values, so their component label is 'rpc-node' (not 'rpc')
   const podComponents = [
     'p2p-bootstrap',
     'prover-node',
     'prover-broker',
     'prover-agent',
     'sequencer-node',
-    'rpc',
+    'rpc-node',
+    'validator-ha-db',
+  ];
+  const pvcComponents = [
+    'p2p-bootstrap',
+    'prover-node',
+    'prover-broker',
+    'sequencer-node',
+    'rpc-node',
     'validator-ha-db',
   ];
-  const pvcComponents = ['p2p-bootstrap', 'prover-node', 'prover-broker', 'sequencer-node', 'rpc', 'validator-ha-db'];
   // StatefulSet components that need to be scaled down before PVC deletion
   // Note: validators use 'sequencer-node' as component label, not 'validator'
   const statefulSetComponents = [
@@ -380,7 +388,7 @@ export async function rollAztecPods(namespace: string, clearState: boolean = fal
     'prover-node',
     'prover-broker',
     'sequencer-node',
-    'rpc',
+    'rpc-node',
     'validator-ha-db',
   ];
 

package/src/spartan/utils/pod_logs.ts

@@ -0,0 +1,99 @@
+import type { Logger } from '@aztec/foundation/log';
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+import { getSequencers } from './nodes.js';
+
+const execAsync = promisify(exec);
+
+/** Parsed l2-block-built stats from a sequencer pod log line. */
+export type BlockBuiltLogEntry = {
+  blockNumber: number;
+  txCount: number;
+  duration: number;
+  publicProcessDuration: number;
+  manaPerSec: number;
+  privateLogCount: number;
+  publicLogCount: number;
+  contractClassLogCount: number;
+  contractClassLogSize: number;
+};
+
+const FIELDS: (keyof BlockBuiltLogEntry)[] = [
+  'blockNumber',
+  'txCount',
+  'duration',
+  'publicProcessDuration',
+  'manaPerSec',
+  'privateLogCount',
+  'publicLogCount',
+  'contractClassLogCount',
+  'contractClassLogSize',
+];
+
+/**
+ * Fetches l2-block-built log entries from sequencer pods for given block numbers.
+ * Queries all validator pods (only the proposer will have the log for a given block).
+ *
+ * @param namespace - Kubernetes namespace
+ * @param sinceTime - ISO 8601 timestamp to limit log search (e.g., from before block building was re-enabled)
+ * @param blockNumbers - Set of block numbers to filter for
+ * @param logger - Logger instance
+ * @returns Array of parsed BlockBuiltLogEntry, de-duplicated by blockNumber, sorted ascending
+ */
+export async function fetchBlockBuiltLogs(
+  namespace: string,
+  sinceTime: string,
+  blockNumbers: Set<number>,
+  logger: Logger,
+): Promise<BlockBuiltLogEntry[]> {
+  const pods = await getSequencers(namespace);
+  const entriesByBlock = new Map<number, BlockBuiltLogEntry>();
+
+  // Subtract 60s from sinceTime to account for clock skew between test runner and k8s pods.
+  // Block number filtering ensures we only match the right blocks, so extra lines are harmless.
+  const sinceDate = new Date(new Date(sinceTime).getTime() - 60_000);
+  const sinceFlag = sinceDate.toISOString();
+
+  for (const pod of pods) {
+    try {
+      const cmd = `kubectl logs ${pod} -n ${namespace} -c aztec --since-time=${sinceFlag}`;
+      logger.info(`Fetching logs: ${cmd}`);
+      const { stdout } = await execAsync(cmd, { maxBuffer: 10 * 1024 * 1024 });
+
+      const lines = stdout.split('\n');
+      const matchingLines = lines.filter(l => l.includes('l2-block-built'));
+      logger.info(`Pod ${pod}: ${lines.length} log lines, ${matchingLines.length} contain l2-block-built`);
+
+      for (const line of matchingLines) {
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed.eventName !== 'l2-block-built' || !blockNumbers.has(parsed.blockNumber)) {
+            continue;
+          }
+          if (entriesByBlock.has(parsed.blockNumber)) {
+            continue;
+          }
+          const entry: BlockBuiltLogEntry = {} as BlockBuiltLogEntry;
+          for (const field of FIELDS) {
+            entry[field] = parsed[field] ?? 0;
+          }
+          entriesByBlock.set(entry.blockNumber, entry);
+          logger.verbose(`Parsed l2-block-built log for block ${entry.blockNumber}`, entry);
+        } catch {
+          // Not valid JSON, skip
+        }
+      }
+    } catch (err) {
+      logger.warn(`Failed to fetch logs from pod ${pod}: ${err}`);
+    }
+  }
+
+  if (entriesByBlock.size < blockNumbers.size) {
+    const missing = [...blockNumbers].filter(bn => !entriesByBlock.has(bn));
+    logger.warn(`Missing l2-block-built logs for block(s): ${missing.join(', ')}`);
+  }
+
+  return [...entriesByBlock.values()].sort((a, b) => a.blockNumber - b.blockNumber);
+}

package/src/spartan/utils/scripts.ts

@@ -3,24 +3,47 @@ import type { Logger } from '@aztec/foundation/log';
 import { execSync, spawn } from 'child_process';
 import path from 'path';
 
+/** Result from running a script */
+export type ScriptResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
 /**
  * @param scriptPath - The path to the script, relative to the project root
  * @param args - The arguments to pass to the script
  * @param logger - The logger to use
- * @returns The exit code of the script
+ * @returns The exit code, stdout, and stderr of the script
  */
-function runScript(scriptPath: string, args: string[], logger: Logger, env?: Record<string, string>) {
+function runScript(
+  scriptPath: string,
+  args: string[],
+  logger: Logger,
+  env?: Record<string, string>,
+): Promise<ScriptResult> {
   const childProcess = spawn(scriptPath, args, {
     stdio: ['ignore', 'pipe', 'pipe'],
     env: env ? { ...process.env, ...env } : process.env,
   });
-  return new Promise<number>((resolve, reject) => {
-    childProcess.on('close', (code: number | null) => resolve(code ?? 0));
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+
+  return new Promise<ScriptResult>((resolve, reject) => {
+    childProcess.on('close', (code: number | null) =>
+      resolve({
+        exitCode: code ?? 0,
+        stdout: Buffer.concat(stdoutChunks).toString(),
+        stderr: Buffer.concat(stderrChunks).toString(),
+      }),
+    );
     childProcess.on('error', reject);
     childProcess.stdout?.on('data', (data: Buffer) => {
+      stdoutChunks.push(data);
       logger.info(data.toString());
     });
     childProcess.stderr?.on('data', (data: Buffer) => {
+      stderrChunks.push(data);
       logger.error(data.toString());
     });
   });
@@ -51,13 +74,26 @@ export function getAztecBin() {
  * @param args - The arguments to pass to the Aztec binary
  * @param logger - The logger to use
  * @param env - Optional environment variables to set for the process
- * @returns The exit code of the Aztec binary
+ * @returns The exit code, stdout, and stderr of the Aztec binary
  */
-export function runAztecBin(args: string[], logger: Logger, env?: Record<string, string>) {
+export function runAztecBin(args: string[], logger: Logger, env?: Record<string, string>): Promise<ScriptResult> {
   return runScript('node', [getAztecBin(), ...args], logger, env);
 }
 
-export function runProjectScript(script: string, args: string[], logger: Logger, env?: Record<string, string>) {
+/**
+ * Runs a script from the project root
+ * @param script - The path to the script, relative to the project root
+ * @param args - The arguments to pass to the script
+ * @param logger - The logger to use
+ * @param env - Optional environment variables to set for the process
+ * @returns The exit code, stdout, and stderr of the script
+ */
+export function runProjectScript(
+  script: string,
+  args: string[],
+  logger: Logger,
+  env?: Record<string, string>,
+): Promise<ScriptResult> {
   const scriptPath = script.startsWith('/') ? script : path.join(getGitProjectRoot(), script);
   return runScript(scriptPath, args, logger, env);
 }