refactor(PXE)!: move getNotes to debug submodule (#19053)

I would rather not have to explain that `getNotes`, despite being a
public method in PXE, is not really intended for production usage in
every public facing doc about PXE we write, so I'm proposing to
"conceal" it under a `debug` accessor so it looks like:

`pxe.debug.getNotes()` instead of `pxe.getNotes()`

A potential discussion point: moving `getFunctionCall` to
`ContractDataProvider`: this function is only used as part of the
"invoke contract sync" hack, currently only used by the `getNotes` and
`getPrivateEvents`. So it doesn't seem to be a function with a lot of
potential for reuse. The decision to move it to `ContractDataProvider`
stems from trying to clean PXE a bit and make it available from the new
`PXEDebugUtils` module. But I expect this to change and not be necessary
once we sort out how we handle contract sync

Author: mverzilli

docs/docs-developers/docs/resources/migration_notes.md

@@ -9,6 +9,16 @@ Aztec is in full-speed development. Literally every version breaks compatibility
 
 ## TBD
 
+### [PXE] deprecated `getNotes`
+
+This function serves only for debugging purposes so we are taking it out of the main PXE API. If you still need to consume it, you can
+do so through the new `debug` sub-module.
+
+```diff
+- this.pxe.getNotes(filter);
++ this.pxe.debug.getNotes(filter);
+```
+
 ### [Aztec node, archiver] Deprecated `getPrivateLogs`
 
 Aztec node no longer offers a `getPrivateLogs` method. If you need to process the logs of a block, you can instead use `getBlock` and call `getPrivateLogs` on an `L2BlockNew` instance. See the diff below for before/after equivalent code samples.

yarn-project/cli-wallet/src/utils/wallet.ts

@@ -261,6 +261,6 @@ export class CLIWallet extends BaseWallet {
   // Exposed because of the `aztec-wallet get-tx` command. It has been decided that it's fine to keep around because
   // this is just a CLI wallet.
   getNotes(filter: NotesFilter): Promise<NoteDao[]> {
-    return this.pxe.getNotes(filter);
+    return this.pxe.debug.getNotes(filter);
   }
 }

yarn-project/pxe/src/debug/pxe_debug_utils.ts

@@ -0,0 +1,47 @@
+import type { NoteDao, NotesFilter } from '@aztec/stdlib/note';
+
+import type { PXE } from '../pxe.js';
+import type { ContractDataProvider, NoteDataProvider } from '../storage/index.js';
+
+/**
+ * Methods provided by this class might help debugging but must not be used in production.
+ * No backwards compatibility or API stability should be expected. Use at your own risk.
+ */
+export class PXEDebugUtils {
+  #pxe: PXE | undefined = undefined;
+
+  constructor(
+    private contractDataProvider: ContractDataProvider,
+    private noteDataProvider: NoteDataProvider,
+  ) {}
+
+  /**
+   * Not injected through constructor since they're are co-dependant.
+   */
+  public setPXE(pxe: PXE) {
+    this.#pxe = pxe;
+  }
+
+  /**
+   * A debugging utility to get notes based on the provided filter.
+   *
+   * Note that this should not be used in production code because the structure of notes is considered to be
+   * an implementation detail of contracts. This is only meant to be used for debugging purposes. If you need to obtain
+   * note-related information in production code, please implement a custom utility function on your contract and call
+   * that function instead (e.g. `get_balance(owner: AztecAddress) -> u128` utility function on a Token contract).
+   *
+   * @param filter - The filter to apply to the notes.
+   * @returns The requested notes.
+   */
+  public async getNotes(filter: NotesFilter): Promise<NoteDao[]> {
+    if (!this.#pxe) {
+      throw new Error('Cannot getNotes because no PXE is set');
+    }
+
+    // We need to manually trigger private state sync to have a guarantee that all the notes are available.
+    const call = await this.contractDataProvider.getFunctionCall('sync_private_state', [], filter.contractAddress);
+    await this.#pxe.simulateUtility(call);
+
+    return this.noteDataProvider.getNotes(filter);
+  }
+}

yarn-project/pxe/src/pxe.ts

@@ -12,10 +12,8 @@ import {
   type ContractArtifact,
   EventSelector,
   FunctionCall,
-  FunctionSelector,
   FunctionType,
   decodeFunctionSignature,
-  encodeArguments,
 } from '@aztec/stdlib/abi';
 import type { AuthWitness } from '@aztec/stdlib/auth-witness';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -35,8 +33,6 @@ import type {
   PrivateKernelExecutionProofOutput,
   PrivateKernelTailCircuitPublicInputs,
 } from '@aztec/stdlib/kernel';
-import type { NotesFilter } from '@aztec/stdlib/note';
-import { NoteDao } from '@aztec/stdlib/note';
 import {
   type ContractOverrides,
   type InTx,
@@ -66,6 +62,7 @@ import { readCurrentClassId } from './contract_function_simulator/oracle/private
 import { ProxiedContractDataProviderFactory } from './contract_function_simulator/proxied_contract_data_source.js';
 import { ProxiedNodeFactory } from './contract_function_simulator/proxied_node.js';
 import { PXEOracleInterface } from './contract_function_simulator/pxe_oracle_interface.js';
+import { PXEDebugUtils } from './debug/pxe_debug_utils.js';
 import { enrichPublicSimulationError, enrichSimulationError } from './error_enriching.js';
 import { PrivateEventFilterValidator } from './events/private_event_filter_validator.js';
 import {
@@ -108,6 +105,7 @@ export class PXE {
     private protocolContractsProvider: ProtocolContractsProvider,
     private log: Logger,
     private jobQueue: SerialQueue,
+    public debug: PXEDebugUtils,
   ) {}
 
   /**
@@ -151,6 +149,8 @@ export class PXE {
       loggerOrSuffix,
     );
 
+    const debugUtils = new PXEDebugUtils(contractDataProvider, noteDataProvider);
+
     const jobQueue = new SerialQueue();
 
     const pxe = new PXE(
@@ -170,8 +170,11 @@ export class PXE {
       protocolContractsProvider,
       log,
       jobQueue,
+      debugUtils,
     );
 
+    debugUtils.setPXE(pxe);
+
     pxe.jobQueue.start();
 
     await pxe.#registerProtocolContracts();
@@ -254,31 +257,6 @@ export class PXE {
     return !!(await this.node.getNullifierMembershipWitness('latest', initNullifier));
   }
 
-  async #getFunctionCall(functionName: string, args: any[], to: AztecAddress): Promise<FunctionCall> {
-    const contract = await this.contractDataProvider.getContract(to);
-    if (!contract) {
-      throw new Error(
-        `Unknown contract ${to}: add it to PXE by calling server.addContracts(...).\nSee docs for context: https://docs.aztec.network/developers/resources/debugging/aztecnr-errors#unknown-contract-0x0-add-it-to-pxe-by-calling-serveraddcontracts`,
-      );
-    }
-
-    const functionDao = contract.functions.find(f => f.name === functionName);
-    if (!functionDao) {
-      throw new Error(`Unknown function ${functionName} in contract ${contract.name}.`);
-    }
-
-    return {
-      name: functionDao.name,
-      args: encodeArguments(functionDao, args),
-      selector: await FunctionSelector.fromNameAndParameters(functionDao.name, functionDao.parameters),
-      type: functionDao.functionType,
-      to,
-      hideMsgSender: false,
-      isStatic: functionDao.isStatic,
-      returnTypes: functionDao.returnTypes,
-    };
-  }
-
   // Executes the entrypoint private function, as well as all nested private
   // functions that might arise.
   async #executePrivate(
@@ -663,25 +641,6 @@ export class PXE {
     return this.contractDataProvider.getContractsAddresses();
   }
 
-  /**
-   * A debugging utility to get notes based on the provided filter.
-   *
-   * Note that this should not be used in production code because the structure of notes is considered to be
-   * an implementation detail of contracts. This is only meant to be used for debugging purposes. If you need to obtain
-   * note-related information in production code, please implement a custom utility function on your contract and call
-   * that function instead (e.g. `get_balance(owner: AztecAddress) -> u128` utility function on a Token contract).
-   *
-   * @param filter - The filter to apply to the notes.
-   * @returns The requested notes.
-   */
-  public async getNotes(filter: NotesFilter): Promise<NoteDao[]> {
-    // We need to manually trigger private state sync to have a guarantee that all the notes are available.
-    const call = await this.#getFunctionCall('sync_private_state', [], filter.contractAddress);
-    await this.simulateUtility(call);
-
-    return this.noteDataProvider.getNotes(filter);
-  }
-
   /**
    * Proves the private portion of a simulated transaction, ready to send to the network
    * (where validators prove the public portion).
@@ -1066,7 +1025,7 @@ export class PXE {
     filter: PrivateEventFilter,
   ): Promise<PackedPrivateEvent[]> {
     // We need to manually trigger private state sync to have a guarantee that all the events are available.
-    const call = await this.#getFunctionCall('sync_private_state', [], filter.contractAddress);
+    const call = await this.contractDataProvider.getFunctionCall('sync_private_state', [], filter.contractAddress);
     await this.simulateUtility(call);
 
     const sanitizedFilter = await new PrivateEventFilterValidator(this.anchorBlockDataProvider).validate(filter);

yarn-project/pxe/src/storage/contract_data_provider/contract_data_provider.ts

@@ -8,11 +8,13 @@ import {
   type FunctionAbi,
   type FunctionArtifact,
   type FunctionArtifactWithContractName,
+  FunctionCall,
   type FunctionDebugMetadata,
   FunctionSelector,
   FunctionType,
   contractArtifactFromBuffer,
   contractArtifactToBuffer,
+  encodeArguments,
   getFunctionDebugMetadata,
 } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -274,4 +276,29 @@ export class ContractDataProvider {
       }
     }
   }
+
+  public async getFunctionCall(functionName: string, args: any[], to: AztecAddress): Promise<FunctionCall> {
+    const contract = await this.getContract(to);
+    if (!contract) {
+      throw new Error(
+        `Unknown contract ${to}: add it to PXE by calling server.addContracts(...).\nSee docs for context: https://docs.aztec.network/developers/resources/debugging/aztecnr-errors#unknown-contract-0x0-add-it-to-pxe-by-calling-serveraddcontracts`,
+      );
+    }
+
+    const functionDao = contract.functions.find(f => f.name === functionName);
+    if (!functionDao) {
+      throw new Error(`Unknown function ${functionName} in contract ${contract.name}.`);
+    }
+
+    return {
+      name: functionDao.name,
+      args: encodeArguments(functionDao, args),
+      selector: await FunctionSelector.fromNameAndParameters(functionDao.name, functionDao.parameters),
+      type: functionDao.functionType,
+      to,
+      hideMsgSender: false,
+      isStatic: functionDao.isStatic,
+      returnTypes: functionDao.returnTypes,
+    };
+  }
 }

yarn-project/test-wallet/src/wallet/test_wallet.ts

@@ -252,7 +252,7 @@ export abstract class BaseTestWallet extends BaseWallet {
    * @returns The requested notes.
    */
   getNotes(filter: NotesFilter): Promise<NoteDao[]> {
-    return this.pxe.getNotes(filter);
+    return this.pxe.debug.getNotes(filter);
   }
 
   /**