@aztec/end-to-end 0.0.1-commit.a072138 → 0.0.1-commit.a4600f49

package/src/test-wallet/test_wallet.ts

@@ -0,0 +1,429 @@
+import { EcdsaKAccountContract, EcdsaRAccountContract } from '@aztec/accounts/ecdsa';
+import { StubEcdsaAccountContractArtifact, createStubEcdsaAccount } from '@aztec/accounts/ecdsa/stub';
+import { SchnorrAccountContract, SchnorrInitializerlessAccountContract } from '@aztec/accounts/schnorr';
+import { StubSchnorrAccountContractArtifact, createStubSchnorrAccount } from '@aztec/accounts/schnorr/stub';
+import { type Account, type AccountContract, NO_FROM } from '@aztec/aztec.js/account';
+import type { CompleteAddress } from '@aztec/aztec.js/addresses';
+import {
+  type CallIntent,
+  type ContractFunctionInteractionCallIntent,
+  type IntentInnerHash,
+  SetPublicAuthwitContractInteraction,
+  computeInnerAuthWitHashFromAction,
+  isContractFunctionInteractionCallIntent,
+  lookupValidity,
+} from '@aztec/aztec.js/authorization';
+import { ContractFunctionInteraction } from '@aztec/aztec.js/contracts';
+import type { AztecNode } from '@aztec/aztec.js/node';
+import { AccountManager, type SendOptions } from '@aztec/aztec.js/wallet';
+import { TxSimulationResultWithAppOffset } from '@aztec/aztec.js/wallet';
+import type { DefaultAccountEntrypointOptions } from '@aztec/entrypoints/account';
+import { DefaultEntrypoint } from '@aztec/entrypoints/default';
+import { Fq, Fr } from '@aztec/foundation/curves/bn254';
+import { GrumpkinScalar } from '@aztec/foundation/curves/grumpkin';
+import type { NotesFilter } from '@aztec/pxe/client/lazy';
+import { type PXEConfig, getPXEConfig } from '@aztec/pxe/config';
+import { PXE, type PXECreationOptions, type TaggingSecretSource, createPXE } from '@aztec/pxe/server';
+import { AuthWitness } from '@aztec/stdlib/auth-witness';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { getContractClassFromArtifact } from '@aztec/stdlib/contract';
+import { deriveSigningKey } from '@aztec/stdlib/keys';
+import type { NoteDao } from '@aztec/stdlib/note';
+import {
+  type BlockHeader,
+  type ContractOverrides,
+  SimulationOverrides,
+  type TxExecutionRequest,
+  type TxHash,
+  type TxReceipt,
+} from '@aztec/stdlib/tx';
+import { ExecutionPayload, mergeExecutionPayloads } from '@aztec/stdlib/tx';
+import { BaseWallet, type SimulateViaEntrypointOptions } from '@aztec/wallet-sdk/base-wallet';
+import type { AccountType } from '@aztec/wallets/embedded';
+
+import { DEFAULT_MIN_FEE_PADDING } from '../fixtures/fixtures.js';
+import { AztecNodeProxy, ProvenTx } from './utils.js';
+
+/**
+ * Data for generating an account.
+ */
+export interface AccountData {
+  secret: Fr;
+  salt: Fr;
+  type?: AccountType;
+  contract: AccountContract;
+}
+
+/**
+ * Wallet implementation that stores accounts in memory and provides extra debugging
+ * utilities
+ * It is intended to be used in e2e tests.
+ */
+/**
+ * Poll interval (in seconds) for in-process TestWallet tx waits. In-process nodes reach CHECKPOINTED synchronously
+ * under automine and cheaply otherwise, so a sub-second cadence removes almost-pure dead time from every send().wait().
+ * Spartan tests run against remote JSON-RPC nodes and restore the 1s default via setDefaultWaitInterval.
+ */
+export const IN_PROCESS_WAIT_INTERVAL_SECONDS = 0.25;
+
+export class TestWallet extends BaseWallet {
+  constructor(
+    pxe: PXE,
+    private readonly nodeRef: AztecNodeProxy,
+  ) {
+    super(pxe, nodeRef);
+    this.minFeePadding = DEFAULT_MIN_FEE_PADDING;
+    this.defaultWaitInterval = IN_PROCESS_WAIT_INTERVAL_SECONDS;
+  }
+
+  /**
+   * Overrides the poll interval (in seconds) used when a send().wait() caller does not specify one. Pass `undefined`
+   * to fall back to the DefaultWaitOpts cadence. Spartan tests set this to 1 so they do not hammer remote nodes.
+   */
+  setDefaultWaitInterval(interval?: number): void {
+    this.defaultWaitInterval = interval;
+  }
+
+  static async create(
+    node: AztecNode,
+    overridePXEConfig?: Partial<PXEConfig>,
+    options: PXECreationOptions = { loggers: {} },
+  ): Promise<TestWallet> {
+    const nodeRef = new AztecNodeProxy(node);
+    const pxeConfig = Object.assign(getPXEConfig(), {
+      proverEnabled: overridePXEConfig?.proverEnabled ?? false,
+      ...overridePXEConfig,
+    });
+    const pxe = await createPXE(nodeRef, pxeConfig, options);
+    const wallet = new TestWallet(pxe, nodeRef);
+    await wallet.initStubClasses();
+    return wallet;
+  }
+
+  /**
+   * Updates the underlying node that this wallet and its PXE communicate with.
+   * @param node - The new AztecNode to forward all calls to.
+   */
+  updateNode(node: AztecNode): void {
+    this.nodeRef.updateTargetNode(node);
+  }
+
+  createSchnorrAccount(secret: Fr, salt: Fr, signingKey?: Fq): Promise<AccountManager> {
+    signingKey = signingKey ?? deriveSigningKey(secret);
+    return this.createAccount({ secret, salt, type: 'schnorr', contract: new SchnorrAccountContract(signingKey) });
+  }
+
+  createSchnorrInitializerlessAccount(secret: Fr, salt: Fr, signingKey?: Fq): Promise<AccountManager> {
+    signingKey = signingKey ?? deriveSigningKey(secret);
+    return this.createAccount({
+      secret,
+      salt,
+      type: 'schnorr_initializerless',
+      contract: new SchnorrInitializerlessAccountContract(signingKey),
+    });
+  }
+
+  createECDSARAccount(secret: Fr, salt: Fr, signingKey: Buffer): Promise<AccountManager> {
+    return this.createAccount({
+      secret,
+      salt,
+      type: 'ecdsasecp256r1',
+      contract: new EcdsaRAccountContract(signingKey),
+    });
+  }
+
+  createECDSAKAccount(secret: Fr, salt: Fr, signingKey: Buffer): Promise<AccountManager> {
+    return this.createAccount({
+      secret,
+      salt,
+      type: 'ecdsasecp256k1',
+      contract: new EcdsaKAccountContract(signingKey),
+    });
+  }
+
+  // Stub class ids, populated on wallet startup
+  // to avoid redundant work per simulation
+  private stubClassIds = new Map<AccountType, Fr>();
+
+  /**
+   * Hashes and registers the stub class for every supported account type with PXE, populating
+   * stubClassIds. Called on wallet initialization.
+   */
+  private async initStubClasses(): Promise<void> {
+    const { id: schnorrClassId } = await getContractClassFromArtifact(StubSchnorrAccountContractArtifact);
+    await this.pxe.registerContractClass(StubSchnorrAccountContractArtifact);
+
+    // ecdsa stubs share the same class id
+    const { id: ecdsaClassId } = await getContractClassFromArtifact(StubEcdsaAccountContractArtifact);
+    await this.pxe.registerContractClass(StubEcdsaAccountContractArtifact);
+
+    this.stubClassIds.set('schnorr', schnorrClassId);
+    // Initializerless accounts share the schnorr stub class for kernelless simulation.
+    this.stubClassIds.set('schnorr_initializerless', schnorrClassId);
+    this.stubClassIds.set('ecdsasecp256k1', ecdsaClassId);
+    this.stubClassIds.set('ecdsasecp256r1', ecdsaClassId);
+  }
+
+  /**
+   * Builds contract overrides for all provided addresses by replacing their account contracts with stub implementations.
+   */
+  protected async buildAccountOverrides(addresses: AztecAddress[]): Promise<ContractOverrides> {
+    const accounts = await this.getAccounts();
+    const contracts: ContractOverrides = {};
+
+    const filtered = accounts.filter(acc => addresses.some(addr => addr.equals(acc.item)));
+
+    for (const account of filtered) {
+      const address = account.item;
+      const originalAccount = await this.getAccountFromAddress(address);
+      const completeAddress = originalAccount.getCompleteAddress();
+      const contractInstance = await this.pxe.getContractInstance(completeAddress.address);
+      if (!contractInstance) {
+        throw new Error(
+          `No contract instance found for address: ${completeAddress.address} during account override building. This is a bug!`,
+        );
+      }
+
+      const type = this.getTypeFor(address);
+      const stubClassId = this.stubClassIds.get(type);
+      if (!stubClassId) {
+        throw new Error(
+          `Stub class for account type '${type}' was not registered at wallet init. This is a bug — initStubClasses should cover every supported AccountType.`,
+        );
+      }
+
+      contracts[address.toString()] = {
+        instance: { ...contractInstance, currentContractClassId: stubClassId },
+      };
+    }
+
+    return contracts;
+  }
+
+  protected accounts: Map<string, { account: Account; type: AccountType }> = new Map();
+
+  private getTypeFor(address: AztecAddress): AccountType {
+    return this.accounts.get(address.toString())?.type ?? 'schnorr';
+  }
+
+  private getStubAccountFor(address: AztecAddress, completeAddress: CompleteAddress) {
+    const type = this.getTypeFor(address);
+    return type === 'schnorr' || type === 'schnorr_initializerless'
+      ? createStubSchnorrAccount(completeAddress)
+      : createStubEcdsaAccount(completeAddress);
+  }
+
+  /**
+   * Controls how the test wallet simulates transactions:
+   * - `kernelless`: Skips kernel circuits but uses the real account contract. Default.
+   * - `kernelless-override`: Skips kernels and replaces the account with a stub that doesn't do authwit validation.
+   * - `full`: Uses real kernel circuits and real account contracts. Slow!
+   */
+  private simulationMode: 'kernelless' | 'kernelless-override' | 'full' = 'kernelless';
+
+  setSimulationMode(mode: 'kernelless' | 'kernelless-override' | 'full') {
+    this.simulationMode = mode;
+  }
+
+  setMinFeePadding(value?: number) {
+    this.minFeePadding = value ?? DEFAULT_MIN_FEE_PADDING;
+  }
+
+  protected getAccountFromAddress(address: AztecAddress): Promise<Account> {
+    const entry = this.accounts.get(address?.toString() ?? '');
+
+    if (!entry) {
+      throw new Error(`Account not found in wallet for address: ${address}`);
+    }
+
+    return Promise.resolve(entry.account);
+  }
+
+  getAccounts() {
+    return Promise.resolve(
+      Array.from(this.accounts.values()).map(entry => ({ alias: '', item: entry.account.getAddress() })),
+    );
+  }
+
+  async createAccount(accountData?: AccountData): Promise<AccountManager> {
+    const secret = accountData?.secret ?? Fr.random();
+    const salt = accountData?.salt ?? Fr.random();
+    const type = accountData?.type ?? 'schnorr';
+    const contract = accountData?.contract ?? new SchnorrAccountContract(GrumpkinScalar.random());
+
+    // Initializerless accounts have no deployment tx: the address commits to the signing public key
+    // (via the contract's immutablesHash, resolved by AccountManager.create) and the constructor's
+    // storage writes are materialized locally via a simulated "store" call below.
+    // Mirrors EmbeddedWallet.createAccountInternal.
+    const accountManager = await AccountManager.create(this, secret, contract, { salt });
+
+    const instance = accountManager.getInstance();
+    const artifact = await contract.getContractArtifact();
+
+    await this.registerContract(instance, artifact, secret);
+
+    const address = accountManager.address.toString();
+    this.accounts.set(address, { account: await accountManager.getAccount(), type });
+
+    if (contract instanceof SchnorrInitializerlessAccountContract) {
+      const constructorAbi = artifact.functions.find(f => f.name === 'constructor');
+      if (!constructorAbi) {
+        throw new Error('Could not create SchnorrInitializerlessAccount: constructor ABI not found');
+      }
+      const { x, y } = await contract.getSigningPublicKey();
+      const storeCall = new ContractFunctionInteraction(this, instance.address, constructorAbi, [x, y]);
+      await storeCall.simulate({ from: instance.address });
+    }
+
+    return accountManager;
+  }
+
+  lookupValidity(
+    onBehalfOf: AztecAddress,
+    intent: IntentInnerHash | CallIntent | ContractFunctionInteractionCallIntent,
+    witness: AuthWitness,
+  ): Promise<{
+    isValidInPrivate: boolean;
+    isValidInPublic: boolean;
+  }> {
+    return lookupValidity(this, onBehalfOf, intent, witness);
+  }
+
+  public setPublicAuthWit(
+    from: AztecAddress,
+    messageHashOrIntent: Fr | IntentInnerHash | CallIntent | ContractFunctionInteractionCallIntent,
+    authorized: boolean,
+  ): Promise<SetPublicAuthwitContractInteraction> {
+    return SetPublicAuthwitContractInteraction.create(this, from, messageHashOrIntent, authorized);
+  }
+
+  public override async createAuthWit(
+    from: AztecAddress,
+    intent: IntentInnerHash | CallIntent | ContractFunctionInteractionCallIntent,
+  ): Promise<AuthWitness> {
+    const account = await this.getAccountFromAddress(from);
+    const chainInfo = await this.getChainInfo();
+    let intentInnerHash: IntentInnerHash;
+    if ('caller' in intent) {
+      const call = isContractFunctionInteractionCallIntent(intent)
+        ? await intent.action.getFunctionCall()
+        : intent.call;
+      const innerHash = await computeInnerAuthWitHashFromAction(intent.caller, call);
+      intentInnerHash = { innerHash, consumer: call.to };
+    } else {
+      intentInnerHash = intent;
+    }
+    return account.createAuthWit(intentInnerHash, chainInfo);
+  }
+
+  protected override async simulateViaEntrypoint(
+    executionPayload: ExecutionPayload,
+    opts: SimulateViaEntrypointOptions,
+  ): Promise<TxSimulationResultWithAppOffset> {
+    const { from, feeOptions, additionalScopes, skipTxValidation, skipFeeEnforcement, sendMessagesAs } = opts;
+    const scopes = this.scopesFrom(from, additionalScopes);
+    const skipKernels = this.simulationMode !== 'full';
+    const useOverride = this.simulationMode === 'kernelless-override';
+
+    const feeExecutionPayload = await feeOptions.walletFeePaymentMethod?.getExecutionPayload();
+    const finalExecutionPayload = feeExecutionPayload
+      ? mergeExecutionPayloads([feeExecutionPayload, executionPayload])
+      : executionPayload;
+    const chainInfo = await this.getChainInfo();
+
+    let overrides = opts.overrides;
+    let txRequest: TxExecutionRequest;
+    if (useOverride) {
+      const accountOverrides = await this.buildAccountOverrides(scopes);
+      overrides = new SimulationOverrides({
+        publicStorage: overrides?.publicStorage,
+        contracts: { ...overrides?.contracts, ...accountOverrides },
+      });
+    }
+
+    if (from === NO_FROM) {
+      const entrypoint = new DefaultEntrypoint();
+      txRequest = await entrypoint.createTxExecutionRequest(finalExecutionPayload, feeOptions.gasSettings, chainInfo);
+    } else {
+      let fromAccount: Account;
+      if (useOverride) {
+        const originalAccount = await this.getAccountFromAddress(from);
+        fromAccount = this.getStubAccountFor(from, originalAccount.getCompleteAddress());
+      } else {
+        fromAccount = await this.getAccountFromAddress(from);
+      }
+      const executionOptions: DefaultAccountEntrypointOptions = {
+        txNonce: Fr.random(),
+        cancellable: this.cancellableTransactions,
+        // If from is an address, feeOptions include the way the account contract should handle the fee payment
+        feePaymentMethodOptions: feeOptions.accountFeePaymentMethodOptions!,
+      };
+      txRequest = await fromAccount.createTxExecutionRequest(
+        finalExecutionPayload,
+        feeOptions.gasSettings,
+        chainInfo,
+        executionOptions,
+      );
+    }
+
+    const result = await this.pxe.simulateTx(txRequest, {
+      simulatePublic: true,
+      skipKernels,
+      skipFeeEnforcement,
+      skipTxValidation,
+      overrides,
+      scopes,
+      senderForTags: this.senderForTagsFrom(from, sendMessagesAs),
+    });
+    const appCallOffset = await this.computeAppCallOffset(from, feeOptions);
+    return TxSimulationResultWithAppOffset.fromResultAndOffset(result, appCallOffset);
+  }
+
+  async proveTx(exec: ExecutionPayload, opts: Omit<SendOptions, 'wait'>): Promise<ProvenTx> {
+    const fee = await this.completeFeeOptions({
+      from: opts.from,
+      feePayer: exec.feePayer,
+      gasSettings: opts.fee?.gasSettings,
+    });
+    const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(exec, opts.from, fee);
+    const txProvingResult = await this.pxe.proveTx(txRequest, {
+      scopes: this.scopesFrom(opts.from, opts.additionalScopes),
+      senderForTags: this.senderForTagsFrom(opts.from, opts.sendMessagesAs),
+    });
+    return new ProvenTx(
+      this.aztecNode,
+      await txProvingResult.toTx(),
+      txProvingResult.getOffchainEffects(),
+      txProvingResult.stats,
+    );
+  }
+
+  getTxReceipt(txHash: TxHash): Promise<TxReceipt> {
+    return this.aztecNode.getTxReceipt(txHash);
+  }
+
+  getNotes(filter: NotesFilter): Promise<NoteDao[]> {
+    return this.pxe.debug.getNotes(filter);
+  }
+
+  getSyncedBlockHeader(): Promise<BlockHeader> {
+    return this.pxe.getSyncedBlockHeader();
+  }
+
+  sync(): Promise<void> {
+    return this.pxe.sync();
+  }
+
+  /**
+   * Registers a non-sender tagging-secret source (e.g. a raw out-of-band shared secret) so this PXE discovers messages
+   * tagged with it. Test-only surface over {@link PXE.registerTaggingSecretSource}, which the base `Wallet` does not
+   * expose. The `address-derived` (sender) variant is excluded: use {@link Wallet.registerSender} for that.
+   */
+  registerTaggingSecretSource(source: Exclude<TaggingSecretSource, { kind: 'address-derived' }>): Promise<void> {
+    return this.pxe.registerTaggingSecretSource(source);
+  }
+
+  stop(): Promise<void> {
+    return this.pxe.stop();
+  }
+}

package/src/test-wallet/utils.ts

@@ -0,0 +1,205 @@
+import type { AztecAddress } from '@aztec/aztec.js/addresses';
+import {
+  BatchCall,
+  ContractFunctionInteraction,
+  DeployMethod,
+  type DeployOptions,
+  NO_WAIT,
+  type NoWait,
+  type SendInteractionOptions,
+  type WaitOpts,
+  toSendOptions,
+} from '@aztec/aztec.js/contracts';
+import { type AztecNode, waitForTx } from '@aztec/aztec.js/node';
+import { timesAsync } from '@aztec/foundation/collection';
+import type { Logger } from '@aztec/foundation/log';
+import { sleep } from '@aztec/foundation/sleep';
+import { SimulationError } from '@aztec/stdlib/errors';
+import { type OffchainEffect, type ProvingStats, Tx, TxHash, type TxReceipt } from '@aztec/stdlib/tx';
+
+import { inspect } from 'util';
+
+import { testSpan, withTestSpanOwner } from '../fixtures/timing.js';
+import type { TestWallet } from './test_wallet.js';
+
+export type ProvenTxSendOpts = {
+  wait?: NoWait | WaitOpts;
+};
+
+export type ProvenTxSendReturn<T extends NoWait | WaitOpts | undefined> = T extends NoWait ? TxHash : TxReceipt;
+
+export class ProvenTx extends Tx {
+  constructor(
+    private node: AztecNode,
+    tx: Tx,
+    public offchainEffects: OffchainEffect[],
+    public stats?: ProvingStats,
+  ) {
+    super(tx.getTxHash(), tx.data, tx.chonkProof, tx.contractClassLogFields, tx.publicFunctionCalldata);
+  }
+
+  send(options?: Omit<ProvenTxSendOpts, 'wait'>): Promise<TxReceipt>;
+  send<W extends ProvenTxSendOpts['wait']>(options: ProvenTxSendOpts & { wait: W }): Promise<ProvenTxSendReturn<W>>;
+  send(options?: ProvenTxSendOpts): Promise<TxHash | TxReceipt> {
+    return testSpan('tx:send', () => this.sendInner(options));
+  }
+
+  private async sendInner(options?: ProvenTxSendOpts): Promise<TxHash | TxReceipt> {
+    const txHash = this.getTxHash();
+    await this.node.sendTx(this).catch(err => {
+      throw this.contextualizeError(err, inspect(this));
+    });
+
+    if (options?.wait === NO_WAIT) {
+      return txHash;
+    }
+
+    const waitOpts = typeof options?.wait === 'object' ? options.wait : undefined;
+    return await waitForTx(this.node, txHash, waitOpts);
+  }
+
+  private contextualizeError(err: Error, ...context: string[]): Error {
+    let contextStr = '';
+    if (context.length > 0) {
+      contextStr = `\nContext:\n${context.join('\n')}`;
+    }
+    if (err instanceof SimulationError) {
+      err.setAztecContext(contextStr);
+    }
+    return err;
+  }
+}
+
+export function proveInteraction(
+  wallet: TestWallet,
+  interaction: ContractFunctionInteraction | DeployMethod | BatchCall,
+  options: SendInteractionOptions | DeployOptions,
+): Promise<ProvenTx> {
+  return testSpan('tx:prove', async () => {
+    const execPayload = await interaction.request(options);
+    return wallet.proveTx(execPayload, toSendOptions(options));
+  });
+}
+
+/** Builds an interaction for index `i` of a batch. */
+export type MakeBatchCall = (i: number) => ContractFunctionInteraction | DeployMethod | BatchCall;
+
+/**
+ * Pre-proves `count` interactions built by `makeCall(i)` against `wallet`, all with the same
+ * `options`. Returns the proven txs so the caller can send them individually (e.g. with sleeps
+ * between sends, or anchored to intermediate tips). For the common "send the whole batch at once"
+ * case use {@link proveAndSendTxs}.
+ */
+export function proveTxs(
+  wallet: TestWallet,
+  count: number,
+  makeCall: MakeBatchCall,
+  options: SendInteractionOptions | DeployOptions,
+): Promise<ProvenTx[]> {
+  return timesAsync(count, i => proveInteraction(wallet, makeCall(i), options));
+}
+
+/**
+ * Pre-proves `count` interactions built by `makeCall(i)` and sends each one with `NO_WAIT`, all at
+ * once. Returns the tx hashes in batch order. Pairs with `waitForTxs` for the "send N, wait for N"
+ * arc. Use {@link proveTxs} instead when the sends need bespoke sequencing.
+ */
+export async function proveAndSendTxs(
+  wallet: TestWallet,
+  count: number,
+  makeCall: MakeBatchCall,
+  options: SendInteractionOptions | DeployOptions,
+): Promise<TxHash[]> {
+  const txs = await proveTxs(wallet, count, makeCall, options);
+  return Promise.all(txs.map(tx => tx.send({ wait: NO_WAIT })));
+}
+
+/** Options for {@link startMempoolFeeder}. */
+export type MempoolFeederOpts = {
+  /** The account the txs are sent from. */
+  from: AztecAddress;
+  /** Keep the pending-tx count at or above this threshold; defaults to 3. */
+  minPending?: number;
+  /** Milliseconds between top-up polls; defaults to 1000. */
+  intervalMs?: number;
+  /** Logger for verbose top-up traces. */
+  logger?: Logger;
+};
+
+/**
+ * Starts a background loop that keeps `node`'s mempool topped up: whenever the pending-tx count drops
+ * below `opts.minPending`, it proves and sends one interaction built by `makeCall()` (NO_WAIT). Errors
+ * are swallowed and retried. Returns an {@link AsyncDisposable}; disposing stops the loop and awaits it.
+ */
+export function startMempoolFeeder(
+  wallet: TestWallet,
+  node: AztecNode,
+  makeCall: () => ContractFunctionInteraction | DeployMethod | BatchCall,
+  opts: MempoolFeederOpts,
+): AsyncDisposable {
+  const minPending = opts.minPending ?? 3;
+  const intervalMs = opts.intervalMs ?? 1000;
+  let stopped = false;
+
+  // Pin the feeder's prove/send spans to a fixed non-test owner. It runs interleaved with arbitrary
+  // tests, so without this its tx:prove/tx:send spans would smear onto whichever test was current
+  // when each round fired; the pinned owner matches no test/suite record, excluding them cleanly.
+  const loop = withTestSpanOwner('other:mempool-feeder', async () => {
+    while (!stopped) {
+      try {
+        const pendingCount = await node.getPendingTxCount();
+        if (pendingCount < minPending) {
+          await proveAndSendTxs(wallet, 1, makeCall, { from: opts.from });
+          opts.logger?.verbose(`Topped up mempool (was ${pendingCount})`);
+        }
+      } catch (err) {
+        opts.logger?.verbose(`Mempool top-up error (will retry): ${err}`);
+      }
+      await sleep(intervalMs);
+    }
+  });
+
+  return {
+    async [Symbol.asyncDispose]() {
+      stopped = true;
+      await loop;
+    },
+  };
+}
+
+/**
+ * Extends AztecNode via declaration merging so instances can be used wherever AztecNode is expected.
+ * The actual method forwarding is handled by a Proxy in the class constructor.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export interface AztecNodeProxy extends AztecNode {}
+
+/**
+ * Mutable wrapper around an AztecNode that forwards all calls to the current target.
+ * Allows swapping the underlying node at runtime via updateTargetNode, which is useful
+ * for tests that need to redirect a wallet from one node to another without recreating it.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class AztecNodeProxy {
+  constructor(private target: AztecNode) {
+    return new Proxy(this, {
+      get: (obj, prop, receiver) => {
+        // Own properties and methods (updateTargetNode, target) are served directly.
+        if (Reflect.has(obj, prop)) {
+          return Reflect.get(obj, prop, receiver);
+        }
+        // Everything else is forwarded to the current target node.
+        const val = (obj.target as unknown as Record<string | symbol, unknown>)[prop];
+        return typeof val === 'function' ? val.bind(obj.target) : val;
+      },
+    });
+  }
+
+  /**
+   * Updates the underlying node that this reference points to.
+   * @param node - The new node to forward calls to.
+   */
+  updateTargetNode(node: AztecNode): void {
+    this.target = node;
+  }
+}