@walletmesh/aztec-rpc-wallet 0.3.0 → 0.4.0

package/src/types.ts

@@ -1,296 +1,458 @@
 import type {
   AuthWitness,
   AztecAddress,
-  ContractArtifact,
-  ContractInstanceWithAddress,
-  ExtendedNote,
   Fr,
   PXE,
   TxExecutionRequest,
   TxHash,
   TxReceipt,
   L2Block,
-  LogFilter,
-  Point,
-  SiblingPath,
-  PartialAddress,
   CompleteAddress,
-  NodeInfo,
   AccountWallet,
   Tx,
 } from '@aztec/aztec.js';
 import type { IntentAction, IntentInnerHash } from '@aztec/aztec.js/utils';
-import type { ExecutionRequestInit } from '@aztec/aztec.js/entrypoint';
-import type { AbiDecoded } from '@aztec/foundation/abi';
+import type { ExecutionPayload } from '@aztec/entrypoints/payload';
+
+/**
+ * @module @walletmesh/aztec-rpc-wallet/types
+ *
+ * This module defines core types and interfaces used throughout the Aztec RPC Wallet package.
+ * Key definitions include:
+ * - {@link AztecChainId}: A type-safe representation of Aztec chain identifiers.
+ * - {@link AztecWalletContext}: The context object passed to wallet-side RPC method handlers.
+ * - {@link AztecWalletMethodMap}: A comprehensive map detailing all supported Aztec JSON-RPC
+ *   methods, their parameters, and return types. This is central to the typed RPC system.
+ */
+
 import type {
-  InBlock,
-  NotesFilter,
-  EventMetadataDefinition,
   PrivateExecutionResult,
-  TxEffect,
+  TxProfileResult,
   TxProvingResult,
-  UniqueNote,
-  PXEInfo,
   TxSimulationResult,
-  GetPublicLogsResponse,
-  GetContractClassLogsResponse,
-  ContractMetadata,
+  UtilitySimulationResult,
+} from '@aztec/stdlib/tx';
+
+import type { ContractArtifact } from '@aztec/stdlib/abi';
+
+import type {
   ContractClassMetadata,
-} from '@aztec/circuit-types';
-import type { GasFees, L1_TO_L2_MSG_TREE_HEIGHT } from '@aztec/circuits.js';
-import type { JSONRPCEventMap, JSONRPCMiddleware } from '@walletmesh/jsonrpc';
-import type { JSONRPCWalletClient, WalletMethodMap } from '@walletmesh/router';
+  ContractMetadata,
+  EventMetadataDefinition,
+  PXEInfo,
+} from '@aztec/stdlib/interfaces/client';
+
+import type { GasFees } from '@aztec/stdlib/gas';
+import type { ContractInstanceWithAddress, NodeInfo } from '@aztec/stdlib/contract';
+
+import type { WalletMethodMap } from '@walletmesh/router';
 import type { ContractArtifactCache } from './contractArtifactCache.js';
 
 /**
- * Represents a single function call to a contract.
- * @public
+ * Type-safe Aztec chain ID format following the CAIP-2 standard.
+ *
+ * Format: `aztec:{reference}` where reference is typically:
+ * - "mainnet" for the main Aztec network
+ * - A numeric chain ID for test networks (e.g., "31337" for local development)
+ *
+ * @example
+ * ```typescript
+ * const mainnetChainId: AztecChainId = "aztec:mainnet";
+ * const localChainId: AztecChainId = "aztec:31337";
+ * ```
  */
-export type TransactionFunctionCall = {
-  /** The address of the contract to interact with */
-  contractAddress: string;
-  /** The name of the function to call */
-  functionName: string;
-  /** The arguments to pass to the function */
-  args: unknown[];
-};
+export type AztecChainId = `aztec:${string}`;
 
 /**
- * Parameters for sending transactions.
- * @public
+ * Defines the context object provided to all Aztec wallet-side JSON-RPC method handlers.
+ * This context aggregates essential dependencies required by handlers to perform their operations.
+ *
+ * @see {@link createAztecWalletNode} where this context is constructed and provided to handlers.
  */
-export type TransactionParams = {
-  /** Array of function calls to execute */
-  functionCalls: TransactionFunctionCall[];
-  /** Optional array of authorization witnesses for the transaction */
-  authwits?: string[];
-};
+export interface AztecWalletContext {
+  /**
+   * The `aztec.js` {@link AccountWallet} instance. This wallet holds the user's account keys
+   * and provides methods for signing, creating transactions, and interacting with the PXE.
+   */
+  wallet: AccountWallet;
+  /**
+   * The `aztec.js` {@link PXE} (Private Execution Environment) client instance.
+   * This is used for interacting with the Aztec network, such as simulating transactions,
+   * getting node information, fetching blocks, and managing private state.
+   */
+  pxe: PXE;
+  /**
+   * An instance of {@link ContractArtifactCache} used for caching contract artifacts.
+   * This helps optimize performance by avoiding redundant fetches of artifact data.
+   */
+  cache: ContractArtifactCache;
+}
 
-export const BASE_WALLET_METHODS: (keyof AztecWalletBaseMethodMap)[] = [
-  'wm_getSupportedMethods',
-  'aztec_connect',
-  'aztec_getAccount',
-  'aztec_sendTransaction',
-  'aztec_simulateTransaction',
-] as const;
+/**
+ * A constant array defining a set of base wallet methods.
+ * These methods might be intended for initial wallet discovery or basic connection negotiation.
+ * Note: Current connection helpers like `connectAztec` default to `ALL_AZTEC_METHODS`.
+ * The `aztec_connect` method listed here is not currently defined in {@link AztecWalletMethodMap}.
+ *
+ * @readonly
+ */
+export const BASE_WALLET_METHODS = ['wm_getSupportedMethods', 'aztec_connect', 'aztec_getAddress'] as const;
 
 /**
- * A mapping of JSON-RPC methods to their parameters and return types for Aztec Wallets.
+ * Defines the complete map of all JSON-RPC methods supported by the Aztec RPC Wallet.
+ * This interface extends the base {@link WalletMethodMap} from `@walletmesh/router`
+ * and specifies the parameter (`params`) and return (`result`) types for each Aztec-specific method.
+ *
+ * This map is crucial for:
+ * - Type safety in both client-side calls and wallet-side handlers.
+ * - Guiding the implementation of serializers and deserializers.
+ * - Documentation generation, as it serves as a single source of truth for method signatures.
+ *
+ * Methods are loosely grouped by functionality (Chain/Node, Account, Sender, etc.).
+ * "wm_" prefixed methods are typically WalletMesh-specific extensions or conveniences.
  *
- * This extends the base WalletMethodMap with Aztec-specific methods.
- * @public
+ * @see {@link AztecDappWallet} for the client-side implementation that calls these methods.
+ * @see {@link createAztecHandlers} for the wallet-side implementation that handles these methods.
  */
-export interface AztecWalletBaseMethodMap extends WalletMethodMap {
+export interface AztecWalletMethodMap extends WalletMethodMap {
+  // Add wm_getSupportedMethods explicitly to ensure its params type is correctly overridden
+  // if WalletMethodMap already defines it differently.
   /**
-   * Connects to the Aztec network.
-   * @returns A boolean indicating if the connection was successful
+   * Retrieves a list of all JSON-RPC methods supported by this wallet implementation.
+   * Allows clients to discover the capabilities of the wallet.
+   * @param params - No parameters.
+   * @returns result - An array of strings, where each string is a supported method name.
    */
-  aztec_connect: { result: boolean };
+  wm_getSupportedMethods: { params: []; result: string[] };
 
+  /* Chain/Node Methods */
   /**
-   * Gets the account address from the wallet.
-   * @returns The account address as a string
+   * Retrieves a specific L2 block by its number.
+   * @param params - A tuple containing the block number.
+   * @param params.0 blockNumber - The number of the block to retrieve.
+   * @returns result - The {@link L2Block} data, or null/undefined if not found (behavior depends on PXE).
    */
-  aztec_getAccount: { result: string };
-
+  aztec_getBlock: { params: [number]; result: L2Block };
   /**
-   * Sends transactions to the Aztec network.
-   * @param params - The transactions to execute and optional authorization witnesses
-   * @returns The transaction hash as a string
+   * Retrieves the current (latest) L2 block number.
+   * @param params - No parameters.
+   * @returns result - The current block number.
    */
-  aztec_sendTransaction: {
-    params: TransactionParams;
-    result: string;
-  };
+  aztec_getBlockNumber: { params: []; result: number };
+  /**
+   * Retrieves the chain ID of the connected Aztec network.
+   * @param params - No parameters.
+   * @returns result - The chain ID as an {@link Fr}.
+   */
+  aztec_getChainId: { params: []; result: Fr };
+  /**
+   * Retrieves the version of the connected PXE (Private Execution Environment) or node.
+   * @param params - No parameters.
+   * @returns result - The version as an {@link Fr}.
+   */
+  aztec_getVersion: { params: []; result: Fr };
+  /**
+   * Retrieves comprehensive information about the connected Aztec node.
+   * @param params - No parameters.
+   * @returns result - A {@link NodeInfo} object.
+   */
+  aztec_getNodeInfo: { params: []; result: NodeInfo };
+  /**
+   * Retrieves the latest L2 block number that has been proven.
+   * @param params - No parameters.
+   * @returns result - The latest proven block number.
+   */
+  aztec_getProvenBlockNumber: { params: []; result: number };
+  /**
+   * Retrieves information about the PXE service, including capabilities and version.
+   * @param params - No parameters.
+   * @returns result - A {@link PXEInfo} object.
+   */
+  aztec_getPXEInfo: { params: []; result: PXEInfo };
+  /**
+   * Retrieves the current base gas fees on the network.
+   * @param params - No parameters.
+   * @returns result - A {@link GasFees} object.
+   */
+  aztec_getCurrentBaseFees: { params: []; result: GasFees };
 
+  /* Account Methods */
   /**
-   * Simulates a transaction without executing it.
-   * @param params - The transaction to simulate
-   * @returns The simulation result
+   * Retrieves the primary {@link AztecAddress} of the wallet's account.
+   * @param params - No parameters.
+   * @returns result - The wallet's {@link AztecAddress}.
    */
-  aztec_simulateTransaction: {
-    params: TransactionFunctionCall;
-    result: unknown;
-  };
+  aztec_getAddress: { params: []; result: AztecAddress };
+  /**
+   * Retrieves the {@link CompleteAddress} of the wallet's account, including public keys.
+   * @param params - No parameters.
+   * @returns result - The wallet's {@link CompleteAddress}.
+   */
+  aztec_getCompleteAddress: { params: []; result: CompleteAddress };
 
+  /* AuthWitness Methods */
   /**
-   * Returns the list of supported methods for the wallet.
-   * @returns An array of supported methods
+   * Creates an {@link AuthWitness} (authorization witness) for a given message hash or intent.
+   * Used for delegating actions.
+   * @param params - A tuple containing the intent to authorize.
+   * @param params.0 intent - The message hash ({@link Fr} or `Buffer`), {@link IntentInnerHash}, or {@link IntentAction} to authorize.
+   * @returns result - The created {@link AuthWitness}.
    */
-  wm_getSupportedMethods: {
-    result: string[];
+  aztec_createAuthWit: {
+    params: [Fr | Buffer | IntentAction | IntentInnerHash];
+    result: AuthWitness;
   };
-}
-
-export interface AztecWalletEventMap extends JSONRPCEventMap {
-  // TODO: What events do we need?
-}
-
-/**
- * Holds the context passed through RPC middleware.
- * @public
- */
-export type AztecWalletContext = Record<string, unknown> & {
-  /** The PXE instance for the wallet */
-  pxe: PXE;
-  wallet: AccountWallet;
-  contractArtifactCache: ContractArtifactCache;
-};
-
-/**
- * Type for Aztec Router Wallet middleware.
- * @public
- */
-export type AztecWalletMiddleware = JSONRPCMiddleware<AztecWalletBaseMethodMap, AztecWalletContext>;
-
-/**
- * Type for Aztec Chain Wallet middleware.
- */
-export type AztecChainWalletMiddleware = JSONRPCMiddleware<AztecWalletMethodMap, AztecWalletContext>;
 
-/**
- * Type for Aztec wallet router client.
- * @public
- */
-export type AztecWalletRouterClient = JSONRPCWalletClient<AztecWalletMethodMap>;
-
-/**
- * Type for Aztec wallet RPC method map.
- * This extends the AztecWalletBaseMethodMap with the methods used in by Aztec's `AccountWallet`
- */
-export interface AztecWalletMethodMap extends AztecWalletBaseMethodMap {
-  /* Chain */
-  aztec_getBlock: { params: { number: number }; result: L2Block };
-  aztec_getBlockNumber: { result: number };
-  aztec_getChainId: { result: number };
-  aztec_getVersion: { result: number };
-  aztec_getNodeInfo: { result: NodeInfo };
-  aztec_getProvenBlockNumber: { result: number };
-  aztec_getPXEInfo: { result: PXEInfo };
-  aztec_getCurrentBaseFees: { result: GasFees };
-
-  /* Scopes */
-  aztec_setScopes: { params: { scopes: AztecAddress[] }; result: boolean };
-  aztec_getScopes: { result: AztecAddress[] };
-
-  /* L1->L2 Messages */
-  aztec_isL1ToL2MessageSynced: { params: { l1ToL2Message: Fr }; result: boolean };
-  aztec_getL1ToL2MembershipWitness: {
-    params: { contractAddress: AztecAddress; messageHash: Fr; secret: Fr };
-    result: [bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>];
+  /* Sender Methods */
+  /**
+   * Registers a new authorized sender {@link AztecAddress}.
+   * @param params - A tuple containing the sender's address.
+   * @param params.0 senderAddress - The {@link AztecAddress} to authorize.
+   * @returns result - The registered {@link AztecAddress}.
+   */
+  aztec_registerSender: {
+    params: [AztecAddress];
+    result: AztecAddress;
   };
-
-  /* Capsules */
-  aztec_addCapsule: { params: { capsule: Fr[] }; result: boolean };
-
-  /* Accounts */
-  aztec_getAddress: { result: AztecAddress };
-  aztec_getCompleteAddress: { result: CompleteAddress };
-  aztec_registerAccount: {
-    params: { secretKey: Fr; partialAddress: PartialAddress };
-    result: CompleteAddress;
+  /**
+   * Retrieves a list of all currently authorized sender {@link AztecAddress}es.
+   * @param params - No parameters.
+   * @returns result - An array of authorized {@link AztecAddress}es.
+   */
+  aztec_getSenders: { params: []; result: AztecAddress[] };
+  /**
+   * Removes an {@link AztecAddress} from the list of authorized senders.
+   * @param params - A tuple containing the sender's address.
+   * @param params.0 senderAddress - The {@link AztecAddress} to de-authorize.
+   * @returns result - `true` if removal was successful.
+   */
+  aztec_removeSender: {
+    params: [AztecAddress];
+    result: boolean;
   };
-  aztec_getRegisteredAccounts: { result: CompleteAddress[] };
 
-  /* AuthWitness */
-  aztec_addAuthWitness: { params: { authWitness: AuthWitness }; result: boolean };
-  aztec_getAuthWitness: { params: { messageHash: Fr }; result: Fr[] };
-  aztec_createAuthWit: {
-    params: { intent: Fr | Buffer | IntentAction | IntentInnerHash };
-    result: AuthWitness;
+  /* Contract Methods */
+  /**
+   * Retrieves a list of all {@link AztecAddress}es of contracts known to the PXE/wallet.
+   * @param params - No parameters.
+   * @returns result - An array of contract {@link AztecAddress}es.
+   */
+  aztec_getContracts: { params: []; result: AztecAddress[] };
+  /**
+   * Retrieves {@link ContractMetadata} for a specific deployed contract.
+   * @param params - A tuple containing the contract's address.
+   * @param params.0 contractAddress - The {@link AztecAddress} of the contract.
+   * @returns result - The {@link ContractMetadata} for the specified contract.
+   */
+  aztec_getContractMetadata: {
+    params: [AztecAddress];
+    result: ContractMetadata;
   };
-
-  /* Senders */
-
   /**
-   * Registers a contact in the user's PXE
-   * @param params - The sender (contact) address to register
-   * @returns True if registration was successful
+   * Retrieves {@link ContractClassMetadata} for a specific contract class.
+   * @param params - A tuple containing the class ID and an optional flag.
+   * @param params.0 classId - The {@link Fr} ID of the contract class.
+   * @param params.1 includeArtifact - Optional: Boolean indicating whether to include the full {@link ContractArtifact}.
+   * @returns result - The {@link ContractClassMetadata}.
    */
-  aztec_registerSender: { params: { sender: AztecAddress }; result: AztecAddress };
-  aztec_getSenders: { result: AztecAddress[] };
-  aztec_removeSender: { params: { sender: AztecAddress }; result: boolean };
-
-  /* Contracts */
-
-  aztec_getContracts: { result: AztecAddress[] };
-  aztec_getContractMetadata: { params: { address: AztecAddress }; result: ContractMetadata };
   aztec_getContractClassMetadata: {
-    params: { id: Fr; includeArtifact?: boolean };
+    params: [Fr, boolean | undefined];
     result: ContractClassMetadata;
   };
-
   /**
-   * Registers a contract instance in the user's PXE.
-   * @param params - The contract details to register
-   * @returns True if registration was successful
+   * Registers a deployed contract instance with the wallet.
+   * @param params - A tuple containing the instance and optional artifact.
+   * @param params.0 instance - The {@link ContractInstanceWithAddress} to register.
+   * @param params.1 artifact - Optional: The {@link ContractArtifact} for the instance.
+   * @returns result - `true` if registration was successful.
    */
   aztec_registerContract: {
-    params: { instance: ContractInstanceWithAddress; artifact?: ContractArtifact | undefined };
+    params: [ContractInstanceWithAddress, ContractArtifact | undefined];
     result: boolean;
   };
-
   /**
-   * Registers a contract class in the user's PXE.
-   * @param params - The contract artifact to register
-   * @returns True if registration was successful
+   * Registers a contract class (bytecode and ABI) with the wallet.
+   * @param params - A tuple containing the artifact.
+   * @param params.0 artifact - The {@link ContractArtifact} to register.
+   * @returns result - `true` if registration was successful.
    */
-  aztec_registerContractClass: { params: { artifact: ContractArtifact }; result: boolean };
-  // biome-ignore lint/suspicious/noExplicitAny: return type from aztec.js is `any`
-  aztec_getPublicStorageAt: { params: { contract: AztecAddress; storageSlot: Fr }; result: any };
+  aztec_registerContractClass: {
+    params: [ContractArtifact];
+    result: boolean;
+  };
 
-  /* Transactions */
-  aztec_sendTx: { params: { tx: Tx }; result: TxHash };
-  aztec_createTxExecutionRequest: { params: { exec: ExecutionRequestInit }; result: TxExecutionRequest };
+  /* Transaction Methods */
+  /**
+   * Generates proofs for a transaction execution request.
+   * @param params - A tuple containing the request and optional private execution result.
+   * @param params.0 txRequest - The {@link TxExecutionRequest} to prove.
+   * @param params.1 privateExecutionResult - Optional: {@link PrivateExecutionResult} from a prior private simulation.
+   * @returns result - The {@link TxProvingResult}, including the proven transaction.
+   */
   aztec_proveTx: {
-    params: { txRequest: TxExecutionRequest; privateExecutionResult: PrivateExecutionResult };
+    params: [TxExecutionRequest, (PrivateExecutionResult | undefined)?];
     result: TxProvingResult;
   };
-  aztec_getTxEffect: { params: { txHash: TxHash }; result: InBlock<TxEffect> };
-  aztec_getTxReceipt: { params: { txHash: TxHash }; result: TxReceipt };
-
+  /**
+   * Sends a proven {@link Tx} (transaction) to the network.
+   * @param params - A tuple containing the proven transaction.
+   * @param params.0 tx - The proven {@link Tx} object to send.
+   * @returns result - The {@link TxHash} of the sent transaction.
+   */
+  aztec_sendTx: {
+    params: [Tx];
+    result: TxHash;
+  };
+  /**
+   * Retrieves the {@link TxReceipt} for a transaction.
+   * @param params - A tuple containing the transaction hash.
+   * @param params.0 txHash - The {@link TxHash} of the transaction.
+   * @returns result - The {@link TxReceipt}.
+   */
+  aztec_getTxReceipt: {
+    params: [TxHash];
+    result: TxReceipt;
+  };
+  /**
+   * Simulates a {@link TxExecutionRequest} without sending it to the network.
+   * @param params - A tuple containing the simulation parameters.
+   * @param params.0 txRequest - The {@link TxExecutionRequest} to simulate.
+   * @param params.1 simulatePublic - Optional: Whether to simulate public parts. Defaults to `false`.
+   * @param params.2 msgSender - Optional: {@link AztecAddress} for simulation context.
+   * @param params.3 skipTxValidation - Optional: Flag to skip validation. Defaults to `false`.
+   * @param params.4 skipFeeEnforcement - Optional: Flag to skip fee enforcement. Defaults to `false`.
+   * @returns result - The {@link TxSimulationResult}.
+   */
   aztec_simulateTx: {
-    params: {
-      txRequest: TxExecutionRequest;
-      simulatePublic: boolean;
-      msgSender?: AztecAddress;
-      skipTxValidation?: boolean;
-      enforceFeePayment?: boolean;
-      profile?: boolean;
-    };
+    params: [
+      TxExecutionRequest,
+      (boolean | undefined)?, // simulatePublic
+      (AztecAddress | undefined)?, // msgSender
+      (boolean | undefined)?, // skipTxValidation
+      (boolean | undefined)?, // skipFeeEnforcement
+    ];
     result: TxSimulationResult;
   };
-  aztec_simulateUnconstrained: {
-    params: { functionName: string; args: unknown[]; to: AztecAddress; from?: AztecAddress };
-    result: AbiDecoded;
+  /**
+   * Profiles a {@link TxExecutionRequest} for performance analysis.
+   * @param params - A tuple containing the profiling parameters.
+   * @param params.0 txRequest - The {@link TxExecutionRequest} to profile.
+   * @param params.1 profileMode - Optional: Profiling mode ('gates', 'execution-steps', 'full'). Defaults to 'gates'.
+   * @param params.2 skipProofGeneration - Optional: Flag to skip proof generation. Defaults to `false`.
+   * @param params.3 msgSender - Optional: {@link AztecAddress} for profiling context.
+   * @returns result - The {@link TxProfileResult}.
+   */
+  aztec_profileTx: {
+    params: [
+      TxExecutionRequest,
+      ('gates' | 'execution-steps' | 'full' | undefined)?, // profileMode
+      (boolean | undefined)?, // skipProofGeneration
+      (AztecAddress | undefined)?, // msgSender
+    ];
+    result: TxProfileResult;
+  };
+  /**
+   * Simulates a utility (view) function call.
+   * @param params - A tuple containing the utility call parameters.
+   * @param params.0 functionName - Name of the utility function.
+   * @param params.1 args - Arguments for the function.
+   * @param params.2 to - {@link AztecAddress} of the contract/account.
+   * @param params.3 authWits - Optional: Array of {@link AuthWitness}.
+   * @param params.4 from - Optional: Sender {@link AztecAddress}.
+   * @returns result - The {@link UtilitySimulationResult}.
+   */
+  aztec_simulateUtility: {
+    params: [
+      string, // functionName
+      unknown[], // args
+      AztecAddress, // to
+      (AuthWitness[] | undefined)?, // authWits
+      (AztecAddress | undefined)?, // from
+    ];
+    result: UtilitySimulationResult;
   };
 
-  /* Notes */
-  aztec_getNotes: { params: { filter: NotesFilter }; result: UniqueNote[] };
-  aztec_addNote: { params: { note: ExtendedNote }; result: boolean };
-  aztec_addNullifiedNote: { params: { note: ExtendedNote }; result: boolean };
-
-  /* Logs and Events */
-  aztec_getPublicLogs: { params: { filter: LogFilter }; result: GetPublicLogsResponse };
-  aztec_getContractClassLogs: { params: { filter: LogFilter }; result: GetContractClassLogsResponse };
+  /* Event Methods */
+  /**
+   * Retrieves private (encrypted) events from the blockchain.
+   * @param params - A tuple containing the query parameters.
+   * @param params.0 contractAddress - {@link AztecAddress} of the emitting contract.
+   * @param params.1 eventMetadata - {@link EventMetadataDefinition} for the event.
+   * @param params.2 fromBlock - Starting block number.
+   * @param params.3 numBlocks - Number of blocks to scan.
+   * @param params.4 recipients - Array of recipient {@link AztecAddress}es.
+   * @returns result - An array of decoded private event data (type `unknown[]`, actual type depends on `eventMetadata`).
+   */
   aztec_getPrivateEvents: {
-    params: { event: EventMetadataDefinition; from: number; limit: number; vpks?: Point[] };
+    params: [
+      AztecAddress, // contractAddress
+      EventMetadataDefinition, // eventMetadata
+      number, // from
+      number, // numBlocks
+      AztecAddress[], // recipients
+    ];
     result: unknown[];
   };
+  /**
+   * Retrieves public (unencrypted) events from the blockchain.
+   * @param params - A tuple containing the query parameters.
+   * @param params.0 eventMetadata - {@link EventMetadataDefinition} for the event.
+   * @param params.1 fromBlock - Starting block number.
+   * @param params.2 limit - Maximum number of events to return.
+   * @returns result - An array of decoded public event data (type `unknown[]`, actual type depends on `eventMetadata`).
+   */
   aztec_getPublicEvents: {
-    params: { event: EventMetadataDefinition; from: number; limit: number };
+    params: [
+      EventMetadataDefinition, // eventMetadata
+      number, // from
+      number, // limit
+    ];
     result: unknown[];
   };
-}
 
-export type AztecWalletMethodHandler<
-  T extends AztecWalletMethodMap,
-  M extends keyof T,
-  C extends AztecWalletContext,
-> = (
-  context: C,
-  params: T[M]['params'],
-  accountWallet: AccountWallet,
-) => Promise<T[M]['result']> | T[M]['result'];
+  /* Contract Interaction Methods */
+  /**
+   * WalletMesh specific: Executes a contract function interaction using a pre-constructed {@link ExecutionPayload}.
+   * The wallet handles simulation, proving, and sending.
+   * @param params - A tuple containing the execution payload.
+   * @param params.0 executionPayload - The {@link ExecutionPayload} to execute.
+   * @returns result - The {@link TxHash} of the sent transaction.
+   */
+  aztec_wmExecuteTx: {
+    params: [executionPayload: ExecutionPayload];
+    result: TxHash;
+  };
 
-export type AztecChainId = `aztec:${string}`;
+  /**
+   * WalletMesh specific: Deploys a new contract using its artifact and constructor arguments.
+   * The wallet handles address computation, proving, and sending the deployment transaction.
+   * @param params - A tuple containing the deployment parameters.
+   * @param params.0 deploymentParams - Object containing `artifact` ({@link ContractArtifact}), `args` (array),
+   *                            and optional `constructorName` (string).
+   * @returns result - An object with `txHash` ({@link TxHash}) and `contractAddress` ({@link AztecAddress}).
+   */
+  aztec_wmDeployContract: {
+    params: [
+      {
+        artifact: ContractArtifact;
+        args: unknown[];
+        constructorName?: string;
+      },
+    ];
+    result: {
+      txHash: TxHash;
+      contractAddress: AztecAddress;
+    };
+  };
+
+  /**
+   * WalletMesh specific: Simulates a contract function interaction using a pre-constructed {@link ExecutionPayload}.
+   * @param params - A tuple containing the execution payload.
+   * @param params.0 executionPayload - The {@link ExecutionPayload} to simulate.
+   * @returns result - The {@link TxSimulationResult}.
+   */
+  aztec_wmSimulateTx: {
+    params: [executionPayload: ExecutionPayload];
+    result: TxSimulationResult;
+  };
+}