@aztec/end-to-end 0.0.1-commit.f295ac2 → 0.0.1-commit.f8ca9b2f3

package/src/spartan/setup_test_wallets.ts

@@ -1,10 +1,11 @@
 import { generateSchnorrAccounts } from '@aztec/accounts/testing';
 import { AztecAddress } from '@aztec/aztec.js/addresses';
+import { NO_WAIT } from '@aztec/aztec.js/contracts';
 import { L1FeeJuicePortalManager } from '@aztec/aztec.js/ethereum';
 import { FeeJuicePaymentMethodWithClaim } from '@aztec/aztec.js/fee';
 import { type FeePaymentMethod, SponsoredFeePaymentMethod } from '@aztec/aztec.js/fee';
 import { Fr } from '@aztec/aztec.js/fields';
-import { type AztecNode, createAztecNodeClient } from '@aztec/aztec.js/node';
+import { type AztecNode, createAztecNodeClient, waitForTx } from '@aztec/aztec.js/node';
 import type { Wallet } from '@aztec/aztec.js/wallet';
 import { createEthereumChain } from '@aztec/ethereum/chain';
 import { createExtendedL1Client } from '@aztec/ethereum/client';
@@ -12,11 +13,13 @@ 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';
 
 export interface TestAccounts {
   aztecNode: AztecNode;
@@ -84,11 +87,11 @@ 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: AztecAddress.ZERO, 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: AztecAddress.ZERO, fee: { paymentMethod }, wait: { timeout: 2400 } }); // increase timeout on purpose in order to account for two empty epochs
       logger.info(`Account deployed at ${a.address}`);
     }),
   );
@@ -116,6 +119,55 @@ export async function deploySponsoredTestAccountsWithTokens(
   };
 }
 
+async function deployAccountWithDiagnostics(
+  account: { getDeployMethod: () => Promise<{ send: (opts: any) => any }>; address: any },
+  paymentMethod: SponsoredFeePaymentMethod,
+  aztecNode: AztecNode,
+  logger: Logger,
+  accountLabel: string,
+): Promise<void> {
+  const deployMethod = await account.getDeployMethod();
+  let txHash;
+  try {
+    txHash = await deployMethod.send({ from: AztecAddress.ZERO, fee: { paymentMethod }, wait: NO_WAIT });
+    await waitForTx(aztecNode, txHash, { timeout: 2400 });
+    logger.info(`${accountLabel} deployed at ${account.address}`);
+  } catch (error) {
+    const blockNumber = await aztecNode.getBlockNumber();
+    let receipt;
+    try {
+      receipt = await aztecNode.getTxReceipt(txHash);
+    } catch {
+      receipt = 'unavailable';
+    }
+    logger.error(`${accountLabel} deployment failed`, {
+      txHash: txHash.toString(),
+      receipt: JSON.stringify(receipt),
+      currentBlockNumber: blockNumber,
+      error: String(error),
+    });
+    throw error;
+  }
+}
+
+async function deployAccountsInBatches(
+  accounts: { getDeployMethod: () => Promise<{ send: (opts: any) => any }>; address: any }[],
+  paymentMethod: SponsoredFeePaymentMethod,
+  aztecNode: AztecNode,
+  logger: Logger,
+  labelPrefix: string,
+  batchSize = 2,
+): 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}`),
+      ),
+    );
+  }
+}
+
 export async function deploySponsoredTestAccounts(
   wallet: TestWallet,
   aztecNode: AztecNode,
@@ -129,15 +181,9 @@ export async function deploySponsoredTestAccounts(
   await registerSponsoredFPC(wallet);
 
   const paymentMethod = new SponsoredFeePaymentMethod(await getSponsoredFPCAddress());
-  const recipientDeployMethod = await recipientAccount.getDeployMethod();
-  await recipientDeployMethod.send({ from: AztecAddress.ZERO, 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
-      logger.info(`Account deployed at ${a.address}`);
-    }),
-  );
+
+  await deployAccountWithDiagnostics(recipientAccount, paymentMethod, aztecNode, logger, 'Recipient account');
+  await deployAccountsInBatches(fundedAccounts, paymentMethod, aztecNode, logger, 'Funded account ', 2);
 
   return {
     aztecNode,
@@ -175,7 +221,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 } }).wait();
+      await deployMethod.send({ from: AztecAddress.ZERO, fee: { paymentMethod } });
       logger.info(`Account deployed at ${a.address}`);
     }),
   );
@@ -251,14 +297,19 @@ async function deployTokenAndMint(
   logger: Logger,
 ) {
   logger.verbose(`Deploying TokenContract...`);
-  const tokenContract = await TokenContract.deploy(wallet, admin, TOKEN_NAME, TOKEN_SYMBOL, TOKEN_DECIMALS)
-    .send({
-      from: admin,
-      fee: {
-        paymentMethod,
-      },
-    })
-    .deployed({ timeout: 600 });
+  const { contract: tokenContract } = await TokenContract.deploy(
+    wallet,
+    admin,
+    TOKEN_NAME,
+    TOKEN_SYMBOL,
+    TOKEN_DECIMALS,
+  ).send({
+    from: admin,
+    fee: {
+      paymentMethod,
+    },
+    wait: { timeout: 600, returnReceipt: true },
+  });
 
   const tokenAddress = tokenContract.address;
 
@@ -268,8 +319,7 @@ async function deployTokenAndMint(
     accounts.map(acc =>
       TokenContract.at(tokenAddress, wallet)
         .methods.mint_to_public(acc, mintAmount)
-        .send({ from: admin, fee: { paymentMethod } })
-        .wait({ timeout: 600 }),
+        .send({ from: admin, fee: { paymentMethod }, wait: { timeout: 600 } }),
     ),
   );
 
@@ -309,7 +359,7 @@ export async function performTransfers({
 
     const provenTxs = await Promise.all(txs);
 
-    await Promise.all(provenTxs.map(t => t.send().wait({ timeout: 600 })));
+    await Promise.all(provenTxs.map(t => t.send({ wait: { timeout: 600 } })));
 
     logger.info(`Completed round ${i + 1} / ${rounds}`);
   }

package/src/spartan/tx_metrics.ts

@@ -1,10 +1,137 @@
 import type { AztecNode } from '@aztec/aztec.js/node';
-import type { L2BlockNew } from '@aztec/stdlib/block';
+import type { Logger } from '@aztec/foundation/log';
+import type { L2Block } from '@aztec/stdlib/block';
 import type { TopicType } from '@aztec/stdlib/p2p';
-import { Tx, type TxReceipt, TxStatus } from '@aztec/stdlib/tx';
+import { Tx, type TxReceipt } from '@aztec/stdlib/tx';
 
 import { createHistogram } from 'perf_hooks';
 
+/** Metrics class for proving-related benchmarks. */
+export class ProvingMetrics {
+  private successfulTxs: number | undefined;
+  private proofDuration: number | undefined;
+  private activeAgents: number | undefined;
+  private avgQueueTime: number | undefined;
+  private jobRetries: number | undefined;
+  private jobDuration: number | undefined;
+  private timedOutJobs: number | undefined;
+  private resolvedJobs: number | undefined;
+  private rejectedJobs: number | undefined;
+  private epochProvingDuration: number | undefined;
+  private provenTransactions: number | undefined;
+  private provenBlocks: number | undefined;
+
+  constructor(private prefix: string) {}
+
+  recordSuccessfulTxs(count: number): void {
+    this.successfulTxs = count;
+  }
+
+  recordProofDuration(seconds: number): void {
+    this.proofDuration = seconds;
+  }
+
+  recordActiveAgents(count: number): void {
+    this.activeAgents = count;
+  }
+
+  recordAvgQueueTime(ms: number): void {
+    this.avgQueueTime = ms;
+  }
+
+  recordJobRetries(count: number): void {
+    this.jobRetries = count;
+  }
+
+  recordJobDuration(ms: number): void {
+    this.jobDuration = ms;
+  }
+
+  recordTimedOutJobs(count: number): void {
+    this.timedOutJobs = count;
+  }
+
+  recordResolvedJobs(count: number): void {
+    this.resolvedJobs = count;
+  }
+
+  recordRejectedJobs(count: number): void {
+    this.rejectedJobs = count;
+  }
+
+  recordEpochProvingDuration(seconds: number): void {
+    this.epochProvingDuration = seconds;
+  }
+
+  recordProvenTransactions(count: number): void {
+    this.provenTransactions = count;
+  }
+
+  recordProvenBlocks(count: number): void {
+    this.provenBlocks = count;
+  }
+
+  toGithubActionBenchmarkJSON(): Array<{ name: string; unit: string; value: number }> {
+    const data: Array<{ name: string; unit: string; value: number }> = [];
+
+    if (this.successfulTxs !== undefined) {
+      data.push({ name: `${this.prefix}/successful_txs`, unit: 'count', value: this.successfulTxs });
+    }
+
+    if (this.proofDuration !== undefined) {
+      data.push({ name: `${this.prefix}/proof_duration`, unit: 's', value: this.proofDuration });
+    }
+
+    if (this.activeAgents !== undefined) {
+      data.push({ name: `${this.prefix}/active_agents`, unit: 'count', value: this.activeAgents });
+    }
+
+    if (this.avgQueueTime !== undefined) {
+      data.push({ name: `${this.prefix}/avg_queue_time`, unit: 'ms', value: this.avgQueueTime });
+    }
+
+    if (this.jobRetries !== undefined) {
+      data.push({ name: `${this.prefix}/job_retries`, unit: 'count', value: this.jobRetries });
+    }
+
+    if (this.jobDuration !== undefined) {
+      data.push({ name: `${this.prefix}/job_duration`, unit: 'ms', value: this.jobDuration });
+    }
+
+    if (this.timedOutJobs !== undefined) {
+      data.push({ name: `${this.prefix}/timed_out_jobs`, unit: 'count', value: this.timedOutJobs });
+    }
+
+    if (this.resolvedJobs !== undefined) {
+      data.push({ name: `${this.prefix}/resolved_jobs`, unit: 'count', value: this.resolvedJobs });
+    }
+
+    if (this.rejectedJobs !== undefined) {
+      data.push({ name: `${this.prefix}/rejected_jobs`, unit: 'count', value: this.rejectedJobs });
+    }
+
+    if (this.epochProvingDuration !== undefined) {
+      data.push({ name: `${this.prefix}/epoch_proving_duration`, unit: 's', value: this.epochProvingDuration });
+    }
+
+    if (this.provenTransactions !== undefined) {
+      data.push({ name: `${this.prefix}/proven_transactions`, unit: 'count', value: this.provenTransactions });
+    }
+
+    if (this.provenBlocks !== undefined) {
+      data.push({ name: `${this.prefix}/proven_blocks`, unit: 'count', value: this.provenBlocks });
+    }
+
+    const scenario = process.env.BENCH_SCENARIO?.trim();
+    if (!scenario) {
+      return data;
+    }
+
+    const scenarioPrefix = `scenario/${scenario}/`;
+    return data.map(entry => ({ ...entry, name: `${scenarioPrefix}${entry.name}` }));
+  }
+}
+
 export type TxInclusionData = {
   txHash: string;
   sentAt: number;
@@ -20,16 +147,31 @@ export type TxInclusionData = {
 export class TxInclusionMetrics {
   private data = new Map<string, TxInclusionData>();
   private groups = new Set<string>();
-  private blocks = new Map<number, Promise<L2BlockNew | undefined>>();
+  private blocks = new Map<number, Promise<L2Block | undefined>>();
 
   private p2pGossipLatencyByTopic: Partial<Record<TopicType, { p50: number; p95: number }>> = {};
 
-  constructor(private aztecNode: AztecNode) {}
+  private attestationLatency: { p50: number; p95: number } | undefined;
+  private attestationCounts: { success: number; failedBad: number; failedNode: number } | undefined;
+  private reqRespStats: { fraction: number; delayP50: number; delayP95: number } | undefined;
+  private peerStats: { avgCount: number; connectionDurationP50: number; connectionDurationP95: number } | undefined;
+  private mempoolMinedDelay:
+    | { txP50: number; txP95: number; attestationP50: number; attestationP95: number }
+    | undefined;
+
+  constructor(
+    private aztecNode: AztecNode,
+    private logger?: Logger,
+  ) {}
 
   recordSentTx(tx: Tx, group: string): void {
     const txHash = tx.getTxHash().toString();
     const priorityFees = tx.getGasSettings().maxPriorityFeesPerGas;
 
+    if (this.data.has(txHash)) {
+      this.logger?.debug(`Overwriting tx inclusion data for ${txHash}`, { txHash, group });
+    }
+
     this.data.set(txHash, {
       txHash,
       sentAt: Math.trunc(Date.now() / 1000),
@@ -45,8 +187,13 @@ export class TxInclusionMetrics {
   }
 
   async recordMinedTx(txReceipt: TxReceipt): Promise<void> {
-    const { status, txHash, blockNumber } = txReceipt;
-    if (status !== TxStatus.SUCCESS || !blockNumber) {
+    const { txHash, blockNumber } = txReceipt;
+    if (!txReceipt.isMined() || !txReceipt.hasExecutionSucceeded() || !blockNumber) {
+      this.logger?.debug('Skipping mined tx record due to receipt status', {
+        txHash: txHash.toString(),
+        status: txReceipt.status,
+        blockNumber,
+      });
       return;
     }
 
@@ -56,9 +203,15 @@ export class TxInclusionMetrics {
 
     const block = await this.blocks.get(blockNumber)!;
     if (!block) {
+      this.logger?.warn('Failed to load block for mined tx receipt', { txHash: txHash.toString(), blockNumber });
       return;
     }
-    const data = this.data.get(txHash.toString())!;
+    const data = this.data.get(txHash.toString());
+    if (!data) {
+      const message = `Missing sent tx record for mined tx ${txHash.toString()}`;
+      this.logger?.warn(message, { txHash: txHash.toString(), blockNumber });
+      throw new Error(message);
+    }
     data.blocknumber = blockNumber;
     data.minedAt = Number(block.header.globalVariables.timestamp);
     data.attestedAt = -1;
@@ -111,6 +264,26 @@ export class TxInclusionMetrics {
     this.p2pGossipLatencyByTopic[topicName] = { p50, p95 };
   }
 
+  public recordAttestationLatency(p50: number, p95: number): void {
+    this.attestationLatency = { p50, p95 };
+  }
+
+  public recordAttestationCounts(success: number, failedBad: number, failedNode: number): void {
+    this.attestationCounts = { success, failedBad, failedNode };
+  }
+
+  public recordReqRespStats(fraction: number, delayP50: number, delayP95: number): void {
+    this.reqRespStats = { fraction, delayP50, delayP95 };
+  }
+
+  public recordPeerStats(avgCount: number, connectionDurationP50: number, connectionDurationP95: number): void {
+    this.peerStats = { avgCount, connectionDurationP50, connectionDurationP95 };
+  }
+
+  public recordMempoolMinedDelay(txP50: number, txP95: number, attestationP50: number, attestationP95: number): void {
+    this.mempoolMinedDelay = { txP50, txP95, attestationP50, attestationP95 };
+  }
+
   toGithubActionBenchmarkJSON(): Array<{ name: string; unit: string; value: number; range?: number; extra?: string }> {
     const data: Array<{ name: string; unit: string; value: number; range?: number; extra?: string }> = [];
     for (const group of this.groups) {
@@ -148,6 +321,56 @@ export class TxInclusionMetrics {
       });
     }
 
-    return data;
+    if (this.attestationLatency) {
+      data.push(
+        { name: 'attestation_latency/p50', unit: 'ms', value: this.attestationLatency.p50 },
+        { name: 'attestation_latency/p95', unit: 'ms', value: this.attestationLatency.p95 },
+      );
+    }
+
+    if (this.attestationCounts) {
+      const { success, failedBad, failedNode } = this.attestationCounts;
+      const total = success + failedBad + failedNode;
+      const ratio = total > 0 ? success / total : 0;
+      data.push(
+        { name: 'attestation/success_count', unit: 'count', value: success },
+        { name: 'attestation/failed_bad_proposal_count', unit: 'count', value: failedBad },
+        { name: 'attestation/failed_node_issue_count', unit: 'count', value: failedNode },
+        { name: 'attestation/success_ratio', unit: 'ratio', value: ratio },
+      );
+    }
+
+    if (this.reqRespStats) {
+      data.push(
+        { name: 'req_resp/txs_requested_fraction', unit: 'ratio', value: this.reqRespStats.fraction },
+        { name: 'req_resp/delay_p50', unit: 'ms', value: this.reqRespStats.delayP50 },
+        { name: 'req_resp/delay_p95', unit: 'ms', value: this.reqRespStats.delayP95 },
+      );
+    }
+
+    if (this.peerStats) {
+      data.push(
+        { name: 'peers/avg_count', unit: 'peers', value: this.peerStats.avgCount },
+        { name: 'peers/connection_duration_p50', unit: 'ms', value: this.peerStats.connectionDurationP50 },
+        { name: 'peers/connection_duration_p95', unit: 'ms', value: this.peerStats.connectionDurationP95 },
+      );
+    }
+
+    if (this.mempoolMinedDelay) {
+      data.push(
+        { name: 'mempool/tx_mined_delay_p50', unit: 'ms', value: this.mempoolMinedDelay.txP50 },
+        { name: 'mempool/tx_mined_delay_p95', unit: 'ms', value: this.mempoolMinedDelay.txP95 },
+        { name: 'mempool/attestation_mined_delay_p50', unit: 'ms', value: this.mempoolMinedDelay.attestationP50 },
+        { name: 'mempool/attestation_mined_delay_p95', unit: 'ms', value: this.mempoolMinedDelay.attestationP95 },
+      );
+    }
+
+    const scenario = process.env.BENCH_SCENARIO?.trim();
+    if (!scenario) {
+      return data;
+    }
+
+    const scenarioPrefix = `scenario/${scenario}/`;
+    return data.map(entry => ({ ...entry, name: `${scenarioPrefix}${entry.name}` }));
   }
 }

package/src/spartan/utils/bot.ts

@@ -0,0 +1,185 @@
+import type { Logger } from '@aztec/foundation/log';
+import { sleep } from '@aztec/foundation/sleep';
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+import { execHelmCommand, forceDeleteHelmReleaseRecord, getHelmReleaseStatus, hasDeployedHelmRelease } from './helm.js';
+import { deleteResourceByLabel, getChartDir, waitForResourceByLabel } from './k8s.js';
+
+const execAsync = promisify(exec);
+
+export async function restartBot(namespace: string, log: Logger) {
+  log.info(`Restarting bot`);
+  await deleteResourceByLabel({ resource: 'pods', namespace, label: 'app.kubernetes.io/name=bot' });
+  await sleep(10 * 1000);
+  // Some bot images may take time to report Ready due to heavy boot-time proving.
+  // Waiting for PodReadyToStartContainers ensures the pod is scheduled and starting without blocking on full readiness.
+  await waitForResourceByLabel({
+    resource: 'pods',
+    namespace,
+    label: 'app.kubernetes.io/name=bot',
+    condition: 'PodReadyToStartContainers',
+  });
+  log.info(`Bot restarted`);
+}
+
+/**
+ * Installs or upgrades the transfer bot Helm release for the given namespace.
+ * Intended for test setup to enable L2 traffic generation only when needed.
+ */
+export async function installTransferBot({
+  namespace,
+  spartanDir,
+  logger: log,
+  replicas = 1,
+  txIntervalSeconds = 10,
+  followChain = 'PENDING',
+  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',
+  nodeUrl,
+  timeout = '15m',
+  reuseValues = true,
+  aztecSlotDuration = Number(process.env.AZTEC_SLOT_DURATION ?? 12),
+}: {
+  namespace: string;
+  spartanDir: string;
+  logger: Logger;
+  replicas?: number;
+  txIntervalSeconds?: number;
+  followChain?: string;
+  mnemonic?: string;
+  mnemonicStartIndex?: number | string;
+  botPrivateKey?: string;
+  nodeUrl?: string;
+  timeout?: string;
+  reuseValues?: boolean;
+  aztecSlotDuration?: number;
+}) {
+  const instanceName = `${namespace}-bot-transfers`;
+  const helmChartDir = getChartDir(spartanDir, 'aztec-bot');
+  const resolvedNodeUrl = nodeUrl ?? `http://${namespace}-rpc-aztec-node.${namespace}.svc.cluster.local:8080`;
+
+  log.info(`Installing/upgrading transfer bot: replicas=${replicas}, followChain=${followChain}`);
+
+  const values: Record<string, string | number | boolean> = {
+    'bot.replicaCount': replicas,
+    'bot.txIntervalSeconds': txIntervalSeconds,
+    'bot.followChain': followChain,
+    'bot.botPrivateKey': botPrivateKey,
+    'bot.nodeUrl': resolvedNodeUrl,
+    'bot.mnemonic': mnemonic,
+    'bot.feePaymentMethod': 'fee_juice',
+    'aztec.slotDuration': aztecSlotDuration,
+    // Ensure bot can reach its own PXE started in-process (default rpc.port is 8080)
+    // Note: since aztec-bot depends on aztec-node with alias `bot`, env vars go under `bot.node.env`.
+    'bot.node.env.BOT_PXE_URL': 'http://127.0.0.1:8080',
+    // Provide L1 execution RPC for bridging fee juice
+    'bot.node.env.ETHEREUM_HOSTS': `http://${namespace}-eth-execution.${namespace}.svc.cluster.local:8545`,
+    // Provide L1 mnemonic for bridging (falls back to labs mnemonic)
+    'bot.node.env.BOT_L1_MNEMONIC': mnemonic,
+
+    // The bot does not need Kubernetes API access. Disable RBAC + ServiceAccount creation so the chart
+    // can be installed by users without cluster-scoped RBAC permissions.
+    'bot.rbac.create': false,
+    'bot.serviceAccount.create': false,
+    'bot.serviceAccount.name': 'default',
+  };
+  // Ensure we derive a funded L1 key (index 0 is funded on anvil default mnemonic)
+  if (mnemonicStartIndex === undefined) {
+    values['bot.mnemonicStartIndex'] = 0;
+  }
+  // Also pass a funded private key directly if available
+  if (process.env.FUNDING_PRIVATE_KEY) {
+    values['bot.node.env.BOT_L1_PRIVATE_KEY'] = process.env.FUNDING_PRIVATE_KEY;
+  }
+  // Align bot image with the running network image: prefer env var, else detect from a validator pod
+  let repositoryFromEnv: string | undefined;
+  let tagFromEnv: string | undefined;
+  const aztecDockerImage = process.env.AZTEC_DOCKER_IMAGE;
+  if (aztecDockerImage && aztecDockerImage.includes(':')) {
+    const lastColon = aztecDockerImage.lastIndexOf(':');
+    repositoryFromEnv = aztecDockerImage.slice(0, lastColon);
+    tagFromEnv = aztecDockerImage.slice(lastColon + 1);
+  }
+
+  let repository = repositoryFromEnv;
+  let tag = tagFromEnv;
+  if (!repository || !tag) {
+    try {
+      const { stdout } = await execAsync(
+        `kubectl get pods -l app.kubernetes.io/name=validator -n ${namespace} -o jsonpath='{.items[0].spec.containers[?(@.name=="aztec")].image}' | cat`,
+      );
+      const image = stdout.trim().replace(/^'|'$/g, '');
+      if (image && image.includes(':')) {
+        const lastColon = image.lastIndexOf(':');
+        repository = image.slice(0, lastColon);
+        tag = image.slice(lastColon + 1);
+      }
+    } catch (err) {
+      log.warn(`Could not detect aztec image from validator pod: ${String(err)}`);
+    }
+  }
+  if (repository && tag) {
+    values['global.aztecImage.repository'] = repository;
+    values['global.aztecImage.tag'] = tag;
+  }
+  if (mnemonicStartIndex !== undefined) {
+    values['bot.mnemonicStartIndex'] =
+      typeof mnemonicStartIndex === 'string' ? mnemonicStartIndex : Number(mnemonicStartIndex);
+  }
+
+  // If a previous install attempt left the release in a non-deployed state (e.g. FAILED),
+  // `helm upgrade --install` can error with "has no deployed releases".
+  // In that case, clear the release record and do a clean install.
+  const existingStatus = await getHelmReleaseStatus(instanceName, namespace);
+  if (existingStatus && existingStatus.toLowerCase() !== 'deployed') {
+    log.warn(`Transfer bot release ${instanceName} is in status '${existingStatus}'. Reinstalling cleanly.`);
+    await execAsync(`helm uninstall ${instanceName} --namespace ${namespace} --wait --ignore-not-found`).catch(
+      () => undefined,
+    );
+    // If helm left the release in `uninstalling`, force-delete the record so we can reinstall.
+    const afterUninstallStatus = await getHelmReleaseStatus(instanceName, namespace);
+    if (afterUninstallStatus?.toLowerCase() === 'uninstalling') {
+      await forceDeleteHelmReleaseRecord(instanceName, namespace, log);
+    }
+  }
+
+  // `--reuse-values` fails if the release has never successfully deployed (e.g. first install, or a previous failed install).
+  // Only reuse values when we have a deployed release to reuse from.
+  const effectiveReuseValues = reuseValues && (await hasDeployedHelmRelease(instanceName, namespace));
+
+  await execHelmCommand({
+    instanceName,
+    helmChartDir,
+    namespace,
+    valuesFile: undefined,
+    timeout,
+    values: values as unknown as Record<string, string | number | boolean>,
+    reuseValues: effectiveReuseValues,
+  });
+
+  if (replicas > 0) {
+    await waitForResourceByLabel({
+      resource: 'pods',
+      namespace,
+      label: 'app.kubernetes.io/name=bot',
+      condition: 'PodReadyToStartContainers',
+    });
+  }
+}
+
+/**
+ * Uninstalls the transfer bot Helm release from the given namespace.
+ * Intended for test teardown to clean up bot resources.
+ */
+export async function uninstallTransferBot(namespace: string, log: Logger) {
+  const instanceName = `${namespace}-bot-transfers`;
+  log.info(`Uninstalling transfer bot release ${instanceName}`);
+  await execAsync(`helm uninstall ${instanceName} --namespace ${namespace} --wait --ignore-not-found`);
+  // Ensure any leftover pods are removed
+  await deleteResourceByLabel({ resource: 'pods', namespace, label: 'app.kubernetes.io/name=bot' }).catch(
+    () => undefined,
+  );
+}