@walletmesh/aztec-rpc-wallet 0.3.0 → 0.4.0

package/src/wallet/handlers/account.ts

@@ -0,0 +1,99 @@
+import type { AztecHandlerContext } from './index.js';
+import type { AztecWalletMethodMap } from '../../types.js';
+import { createLogger } from '@aztec/foundation/log';
+
+const logger = createLogger('aztec-rpc-wallet:account');
+
+/**
+ * Creates handlers for account-related Aztec wallet JSON-RPC methods.
+ * These handlers are responsible for managing wallet identity, retrieving addresses,
+ * and creating authorization witnesses.
+ *
+ * Each handler function receives an {@link AztecHandlerContext} which provides access
+ * to the core {@link AccountWallet} instance, the {@link PXE} client, and a
+ * {@link ContractArtifactCache}.
+ *
+ * @returns An object where keys are account-related method names
+ *          (e.g., "aztec_getAddress", "aztec_createAuthWit") and values are their
+ *          corresponding handler functions.
+ * @see {@link AztecWalletMethodMap} for method definitions.
+ */
+export function createAccountHandlers() {
+  return {
+    /**
+     * Handles the "aztec_getAddress" JSON-RPC method.
+     * Retrieves the primary {@link AztecAddress} of the account associated with the
+     * {@link AccountWallet} in the current context.
+     *
+     * @param ctx - The {@link AztecHandlerContext} containing the `wallet` instance.
+     * @param _paramsTuple - Parameters for this method (expected to be an empty array).
+     *                       Defined by {@link AztecWalletMethodMap.aztec_getAddress.params}.
+     * @returns A promise that resolves to the {@link AztecAddress} of the wallet.
+     *          Type defined by {@link AztecWalletMethodMap.aztec_getAddress.result}.
+     */
+    aztec_getAddress: async (
+      ctx: AztecHandlerContext,
+      _paramsTuple: AztecWalletMethodMap['aztec_getAddress']['params'], // Will be `[]`
+    ): Promise<AztecWalletMethodMap['aztec_getAddress']['result']> => {
+      logger.debug('[HANDLER] aztec_getAddress');
+      return ctx.wallet.getAddress();
+    },
+
+    /**
+     * Handles the "aztec_getCompleteAddress" JSON-RPC method.
+     * Retrieves the {@link CompleteAddress} (which includes public keys and partial address)
+     * of the account associated with the {@link AccountWallet} in the current context.
+     *
+     * The complete address typically contains:
+     * - The {@link AztecAddress}
+     * - Public keys (e.g., nullifier key, incoming viewing key)
+     * - Partial address
+     *
+     * @param ctx - The {@link AztecHandlerContext} containing the `wallet` instance.
+     * @param _paramsTuple - Parameters for this method (expected to be an empty array).
+     *                       Defined by {@link AztecWalletMethodMap.aztec_getCompleteAddress.params}.
+     * @returns A promise that resolves to the {@link CompleteAddress} of the wallet.
+     *          Type defined by {@link AztecWalletMethodMap.aztec_getCompleteAddress.result}.
+     */
+    aztec_getCompleteAddress: async (
+      ctx: AztecHandlerContext,
+      _paramsTuple: AztecWalletMethodMap['aztec_getCompleteAddress']['params'], // Will be `[]`
+    ): Promise<AztecWalletMethodMap['aztec_getCompleteAddress']['result']> => {
+      logger.debug('[HANDLER] aztec_getCompleteAddress');
+      return ctx.wallet.getCompleteAddress();
+    },
+
+    /**
+     * Handles the "aztec_createAuthWit" JSON-RPC method.
+     * Creates an {@link AuthWitness} for a given message hash or intent, using the
+     * {@link AccountWallet} in the current context.
+     *
+     * Authorization witnesses are used to delegate actions, allowing a contract or another
+     * entity to perform operations on behalf of the wallet owner (e.g., for token approvals).
+     *
+     * @param ctx - The {@link AztecHandlerContext} containing the `wallet` instance.
+     * @param paramsTuple - A tuple containing the intent to authorize.
+     *                      Defined by {@link AztecWalletMethodMap.aztec_createAuthWit.params}.
+     * @param paramsTuple.0 - The intent to authorize, which can be a message hash ({@link Fr} or `Buffer`),
+     *                        an {@link IntentInnerHash}, or an {@link IntentAction}.
+     * @returns A promise that resolves to the created {@link AuthWitness}.
+     *          Type defined by {@link AztecWalletMethodMap.aztec_createAuthWit.result}.
+     * @throws {Error} If the `intent` parameter is missing or invalid, though type checking
+     *                 and serializer validation should ideally catch this earlier.
+     */
+    aztec_createAuthWit: async (
+      ctx: AztecHandlerContext,
+      paramsTuple: AztecWalletMethodMap['aztec_createAuthWit']['params'],
+    ): Promise<AztecWalletMethodMap['aztec_createAuthWit']['result']> => {
+      const [intent] = paramsTuple;
+      logger.debug(`[HANDLER] aztec_createAuthWit: intent type = ${typeof intent}`);
+      // Intent is not optional in the tuple type.
+      // Add runtime check for robustness if needed.
+      if (intent === undefined) {
+        // Basic check, though TS should prevent this if tuple type is correct
+        throw new Error('Invalid intent parameter received in tuple');
+      }
+      return await ctx.wallet.createAuthWit(intent);
+    },
+  };
+}

package/src/wallet/handlers/contract-interaction.test.ts

@@ -0,0 +1,248 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createContractInteractionHandlers } from './contract-interaction.js';
+import type { AztecHandlerContext } from './index.js';
+import { AztecAddress, Fr, type TxReceipt, TxHash } from '@aztec/aztec.js';
+import { GasFees } from '@aztec/stdlib/gas';
+import { FeeJuicePaymentMethod } from '@aztec/aztec.js';
+import type { ExecutionPayload } from '@aztec/entrypoints/payload';
+
+// Mock the aztec.js module
+vi.mock('@aztec/aztec.js', async () => {
+  const actual = await vi.importActual('@aztec/aztec.js');
+  return {
+    ...actual,
+    Contract: {
+      deploy: vi.fn(),
+    },
+  };
+});
+
+describe('createContractInteractionHandlers', () => {
+  let mockContext: AztecHandlerContext;
+  let handlers: ReturnType<typeof createContractInteractionHandlers>;
+
+  const mockAddress = AztecAddress.fromString(
+    '0x1111111111111111111111111111111111111111111111111111111111111111',
+  );
+  const mockTxHash = TxHash.fromString('0x2222222222222222222222222222222222222222222222222222222222222222');
+  const mockTxReceipt = {
+    txHash: mockTxHash,
+    blockNumber: 1,
+    status: 'success',
+  } as unknown as TxReceipt;
+
+  const mockExecutionPayload: ExecutionPayload = {
+    calls: [], // Add calls property
+  } as unknown as ExecutionPayload;
+
+  beforeEach(() => {
+    mockContext = {
+      wallet: {
+        getAddress: vi.fn().mockReturnValue(mockAddress),
+        getCurrentBaseFees: vi.fn().mockResolvedValue(new GasFees(new Fr(100n), new Fr(100n))),
+        createTxExecutionRequest: vi.fn().mockResolvedValue({}),
+        simulateTx: vi.fn().mockResolvedValue({ privateExecutionResult: {} }),
+        proveTx: vi.fn().mockResolvedValue({ toTx: vi.fn().mockReturnValue({}) }),
+        sendTx: vi.fn().mockResolvedValue(mockTxHash),
+        getTxReceipt: vi.fn().mockResolvedValue(mockTxReceipt),
+        registerContract: vi.fn().mockResolvedValue(undefined),
+        getContractClassMetadata: vi.fn().mockResolvedValue({
+          artifactHash: new Fr(123n),
+          privateFunctionsRoot: new Fr(456n),
+          publicBytecodeCommitment: new Fr(789n),
+        }),
+        getContractMetadata: vi.fn().mockResolvedValue(undefined),
+        registerContractClass: vi.fn().mockResolvedValue(undefined),
+      },
+      pxe: {},
+      cache: {},
+    } as unknown as AztecHandlerContext;
+
+    handlers = createContractInteractionHandlers();
+  });
+
+  describe('aztec_wmExecuteTx', () => {
+    it('should execute a contract interaction', async () => {
+      const result = await handlers.aztec_wmExecuteTx(mockContext, [mockExecutionPayload]);
+
+      expect(result).toBe(mockTxHash);
+      expect(mockContext.wallet.getCurrentBaseFees).toHaveBeenCalled();
+      expect(mockContext.wallet.createTxExecutionRequest).toHaveBeenCalled();
+      expect(mockContext.wallet.simulateTx).toHaveBeenCalled();
+      expect(mockContext.wallet.proveTx).toHaveBeenCalled();
+      expect(mockContext.wallet.sendTx).toHaveBeenCalled();
+    });
+
+    it('should handle contract interaction with proper fee configuration', async () => {
+      await handlers.aztec_wmExecuteTx(mockContext, [mockExecutionPayload]);
+
+      // Verify fee configuration
+      const createTxCall = vi.mocked(mockContext.wallet.createTxExecutionRequest).mock.calls[0];
+      expect(createTxCall).toBeDefined();
+      expect(createTxCall?.[0]).toBe(mockExecutionPayload);
+
+      const feeOpts = createTxCall?.[1];
+      expect(feeOpts).toBeDefined();
+      expect(feeOpts?.paymentMethod).toBeInstanceOf(FeeJuicePaymentMethod);
+      expect(feeOpts?.gasSettings).toBeDefined();
+    });
+  });
+
+  describe('aztec_wmDeployContract', () => {
+    it('should deploy a contract with new interface', async () => {
+      const { Contract } = await import('@aztec/aztec.js');
+
+      // Create a minimal artifact that won't trigger complex contract deployment logic
+      const mockArtifact = {
+        name: 'TestContract',
+        functions: [],
+      } as unknown as import('@aztec/aztec.js').ContractArtifact;
+
+      const mockArgs: unknown[] = [];
+
+      const mockSentTx = {
+        getTxHash: vi.fn().mockResolvedValue(mockTxHash),
+      };
+
+      const mockProvenTx = {
+        send: vi.fn().mockResolvedValue(mockSentTx),
+      };
+
+      const mockDeployMethod = {
+        prove: vi.fn().mockResolvedValue(mockProvenTx),
+        getInstance: vi.fn().mockResolvedValue({
+          address: mockAddress,
+        }),
+      };
+
+      vi.mocked(Contract.deploy).mockReturnValue(
+        mockDeployMethod as unknown as ReturnType<typeof Contract.deploy>,
+      );
+
+      const params = {
+        artifact: mockArtifact,
+        args: mockArgs,
+      };
+
+      const result = await handlers.aztec_wmDeployContract(mockContext, [params]);
+
+      expect(result).toEqual({
+        txHash: mockTxHash,
+        contractAddress: mockAddress,
+      });
+      expect(Contract.deploy).toHaveBeenCalledWith(mockContext.wallet, mockArtifact, mockArgs, undefined);
+      expect(mockDeployMethod.prove).toHaveBeenCalled();
+      expect(mockProvenTx.send).toHaveBeenCalled();
+      expect(mockSentTx.getTxHash).toHaveBeenCalled();
+      expect(mockContext.wallet.getCurrentBaseFees).toHaveBeenCalled();
+    });
+
+    it('should deploy a contract with custom constructor name', async () => {
+      const { Contract } = await import('@aztec/aztec.js');
+
+      const mockArtifact = {
+        name: 'TestContract',
+        functions: [],
+      } as unknown as import('@aztec/aztec.js').ContractArtifact;
+
+      const mockArgs: unknown[] = [];
+
+      const mockSentTx = {
+        getTxHash: vi.fn().mockResolvedValue(mockTxHash),
+      };
+
+      const mockProvenTx = {
+        send: vi.fn().mockResolvedValue(mockSentTx),
+      };
+
+      const mockDeployMethod = {
+        prove: vi.fn().mockResolvedValue(mockProvenTx),
+        getInstance: vi.fn().mockResolvedValue({
+          address: mockAddress,
+        }),
+      };
+
+      vi.mocked(Contract.deploy).mockReturnValue(
+        mockDeployMethod as unknown as ReturnType<typeof Contract.deploy>,
+      );
+
+      const params = {
+        artifact: mockArtifact,
+        args: mockArgs,
+        constructorName: 'customConstructor',
+      };
+
+      const result = await handlers.aztec_wmDeployContract(mockContext, [params]);
+
+      expect(result).toEqual({
+        txHash: mockTxHash,
+        contractAddress: mockAddress,
+      });
+      expect(Contract.deploy).toHaveBeenCalledWith(
+        mockContext.wallet,
+        mockArtifact,
+        mockArgs,
+        'customConstructor',
+      );
+      expect(mockDeployMethod.prove).toHaveBeenCalled();
+      expect(mockProvenTx.send).toHaveBeenCalled();
+      expect(mockSentTx.getTxHash).toHaveBeenCalled();
+    });
+
+    it('should register contract instance before deployment', async () => {
+      const { Contract } = await import('@aztec/aztec.js');
+
+      const mockArtifact = {
+        name: 'TestContract',
+        functions: [],
+      } as unknown as import('@aztec/aztec.js').ContractArtifact;
+
+      const mockSentTx = {
+        getTxHash: vi.fn().mockResolvedValue(mockTxHash),
+      };
+
+      const mockProvenTx = {
+        send: vi.fn().mockResolvedValue(mockSentTx),
+      };
+
+      const mockDeployMethod = {
+        prove: vi.fn().mockResolvedValue(mockProvenTx),
+        getInstance: vi.fn().mockResolvedValue({
+          address: mockAddress,
+        }),
+      };
+
+      vi.mocked(Contract.deploy).mockReturnValue(
+        mockDeployMethod as unknown as ReturnType<typeof Contract.deploy>,
+      );
+
+      const params = {
+        artifact: mockArtifact,
+        args: [],
+      };
+
+      // Track the order of calls
+      const callOrder: string[] = [];
+      vi.mocked(mockContext.wallet.getCurrentBaseFees).mockImplementation(async () => {
+        callOrder.push('getCurrentBaseFees');
+        return new GasFees(new Fr(100n), new Fr(100n));
+      });
+      vi.mocked(mockDeployMethod.prove).mockImplementation(async () => {
+        callOrder.push('prove');
+        return mockProvenTx;
+      });
+      vi.mocked(mockProvenTx.send).mockImplementation(async () => {
+        callOrder.push('send');
+        return mockSentTx;
+      });
+
+      await handlers.aztec_wmDeployContract(mockContext, [params]);
+
+      // Verify that the deployment flow is correct
+      expect(callOrder.includes('getCurrentBaseFees')).toBe(true);
+      expect(callOrder.includes('prove')).toBe(true);
+      expect(callOrder.includes('send')).toBe(true);
+      expect(callOrder.indexOf('prove') < callOrder.indexOf('send')).toBe(true);
+    });
+  });
+});

package/src/wallet/handlers/contract-interaction.ts

@@ -0,0 +1,269 @@
+import type { AztecHandlerContext } from './index.js';
+import type { AztecWalletMethodMap } from '../../types.js';
+import { Contract, FeeJuicePaymentMethod, Fr, type DeployOptions, type TxHash } from '@aztec/aztec.js';
+import type { ExecutionPayload } from '@aztec/entrypoints/payload';
+import type { FeeOptions, TxExecutionOptions } from '@aztec/entrypoints/interfaces';
+import { GasSettings } from '@aztec/stdlib/gas';
+import { createLogger } from '@aztec/foundation/log';
+import type { TxExecutionRequest, TxSimulationResult } from '@aztec/stdlib/tx';
+
+const logger = createLogger('aztec-rpc-wallet:contract-interaction:handler');
+
+/**
+ * @module @walletmesh/aztec-rpc-wallet/wallet/handlers/contract-interaction
+ * This module provides handlers for WalletMesh-specific high-level contract
+ * interaction and deployment methods (e.g., `aztec_wmExecuteTx`, `aztec_wmDeployContract`).
+ * These methods simplify common contract operations for dApp developers by accepting
+ * an {@link ExecutionPayload} or deployment parameters, with the wallet-side
+ * handling more of the transaction construction, simulation, proving, and sending flow.
+ */
+
+/**
+ * Creates handlers for WalletMesh-specific contract interaction and deployment JSON-RPC methods.
+ *
+ * These handlers manage high-level contract operations such as:
+ * - `aztec_wmExecuteTx`: Executing a pre-constructed {@link ExecutionPayload}.
+ * - `aztec_wmSimulateTx`: Simulating an {@link ExecutionPayload}.
+ * - `aztec_wmDeployContract`: Deploying a new contract from its artifact and arguments.
+ *
+ * The primary goal of these "wm" (WalletMesh) methods is to simplify the dApp's
+ * interaction with the wallet by abstracting parts of the standard Aztec transaction
+ * lifecycle (e.g., fee estimation, `createTxExecutionRequest`, `proveTx`, `sendTx`).
+ * The wallet takes on more responsibility, which can lead to a better user experience
+ * as the wallet can provide more context or apply its own policies.
+ *
+ * @returns An object where keys are "wm" prefixed method names and values are their
+ *          corresponding handler functions.
+ * @see {@link AztecWalletMethodMap} for method definitions.
+ */
+export function createContractInteractionHandlers() {
+  /** @internal Helper to configure fee options. TODO: Make this more configurable. */
+  async function getFeeOptions(ctx: AztecHandlerContext): Promise<FeeOptions> {
+    // TODO: Provide gas settings from the context
+    logger.debug('Getting current base fees...');
+    const baseFees = await ctx.wallet.getCurrentBaseFees();
+    logger.debug('Base fees:', baseFees);
+
+    const maxFeesPerGas = baseFees.mul(1.5);
+    logger.debug('Calculated max fees per gas:', maxFeesPerGas);
+
+    const feeOpts: FeeOptions = {
+      paymentMethod: new FeeJuicePaymentMethod(ctx.wallet.getAddress()),
+      gasSettings: GasSettings.default({ maxFeesPerGas }),
+    };
+    logger.debug('Fee options configured:', feeOpts);
+
+    return feeOpts;
+  }
+
+  /** @internal Helper to configure transaction execution options. TODO: Make this more configurable. */
+  async function getTxOptions(_ctx: AztecHandlerContext): Promise<TxExecutionOptions> {
+    // TODO(twt): Enable setting cancellable flag & nonce in the options
+    const txOpts: TxExecutionOptions = {};
+    return txOpts;
+  }
+
+  async function createTxExecutionRequest(
+    ctx: AztecHandlerContext,
+    executionPayload: ExecutionPayload,
+  ): Promise<TxExecutionRequest> {
+    logger.debug('Creating transaction execution request...');
+    try {
+      // TODO(twt): Provide gas settings from the context
+      logger.debug('Getting current base fees...');
+      const baseFees = await ctx.wallet.getCurrentBaseFees();
+      logger.debug('Base fees:', baseFees);
+
+      const maxFeesPerGas = baseFees.mul(1.5);
+      logger.debug('Calculated max fees per gas:', maxFeesPerGas);
+
+      const feeOpts = await getFeeOptions(ctx);
+      const txOpts = await getTxOptions(ctx);
+
+      // Create a transaction execution request from the payload
+      const txRequest = await ctx.wallet.createTxExecutionRequest(executionPayload, feeOpts, txOpts);
+
+      return txRequest;
+    } catch (error) {
+      logger.error('Failed to create transaction execution request:', error);
+      throw error;
+    }
+  }
+
+  async function simulateTransaction(
+    ctx: AztecHandlerContext,
+    executionPayload: ExecutionPayload,
+    txExecutionRequest?: TxExecutionRequest,
+  ): Promise<TxSimulationResult> {
+    try {
+      const txRequest = txExecutionRequest || (await createTxExecutionRequest(ctx, executionPayload));
+      // Execute the transaction using the standard flow
+      logger.debug('Starting transaction simulation...');
+      const simStartTime = Date.now();
+      const simulationResult = await ctx.wallet.simulateTx(txRequest, true);
+      logger.debug(`Transaction simulation completed in ${Date.now() - simStartTime}ms`);
+      return simulationResult;
+    } catch (error) {
+      logger.error('Transaction simulation failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * @internal
+   * Helper function to execute a transaction from an {@link ExecutionPayload}.
+   * This consolidates the common flow:
+   * 1. Create TxExecutionRequest (if needed, though typically done by `aztec_wmExecuteTx` caller or here).
+   * 2. Simulate transaction.
+   * 3. Prove transaction.
+   * 4. Send transaction.
+   *
+   * @param ctx - The {@link AztecHandlerContext}.
+   * @param executionPayload - The {@link ExecutionPayload} for the transaction.
+   * @returns A promise resolving to the {@link TxHash} of the sent transaction.
+   */
+  async function executeTransaction(
+    ctx: AztecHandlerContext,
+    executionPayload: ExecutionPayload,
+  ): Promise<TxHash> {
+    const startTime = Date.now();
+    logger.debug(
+      `Starting transaction execution. Wallet: ${ctx.wallet.getAddress().toString()}, Payload: ${executionPayload.calls.length} calls`,
+    );
+    logger.debug('Execution payload:', executionPayload);
+
+    try {
+      const txRequest = await createTxExecutionRequest(ctx, executionPayload);
+      const simulationResult = await simulateTransaction(ctx, executionPayload, txRequest);
+
+      logger.debug('Starting transaction proving...');
+      const proveStartTime = Date.now();
+      const provingResult = await ctx.wallet.proveTx(txRequest, simulationResult.privateExecutionResult);
+      logger.debug(`Transaction proving completed in ${Date.now() - proveStartTime}ms`);
+      logger.debug('Proving result:', provingResult);
+
+      logger.debug('Creating transaction from proving result...');
+      const tx = provingResult.toTx();
+      logger.debug('Transaction created:', tx);
+
+      logger.debug('Sending transaction to network...');
+      const sendStartTime = Date.now();
+      const txHash = await ctx.wallet.sendTx(tx);
+      logger.debug(`Transaction sent in ${Date.now() - sendStartTime}ms, hash: ${txHash.toString()}`);
+
+      return txHash;
+    } catch (error) {
+      const totalTime = Date.now() - startTime;
+      logger.error(`Transaction execution failed after ${totalTime}ms}`);
+      logger.error('Error details:', error);
+      throw error;
+    }
+  }
+
+  return {
+    /**
+     * Handles the "aztec_wmExecuteTx" JSON-RPC method.
+     * This WalletMesh-specific method takes an {@link ExecutionPayload} and handles
+     * the full lifecycle of simulating, proving, and sending the transaction.
+     *
+     * @param ctx - The {@link AztecHandlerContext}.
+     * @param paramsTuple - A tuple containing the {@link ExecutionPayload}.
+     *                      Defined by {@link AztecWalletMethodMap.aztec_wmExecuteTx.params}.
+     * @param paramsTuple.0 - The {@link ExecutionPayload} to execute.
+     * @returns A promise that resolves to the {@link TxHash} of the sent transaction.
+     *          Type defined by {@link AztecWalletMethodMap.aztec_wmExecuteTx.result}.
+     */
+    aztec_wmExecuteTx: async (
+      ctx: AztecHandlerContext,
+      paramsTuple: AztecWalletMethodMap['aztec_wmExecuteTx']['params'],
+    ): Promise<AztecWalletMethodMap['aztec_wmExecuteTx']['result']> => {
+      const [executionPayload] = paramsTuple;
+      return executeTransaction(ctx, executionPayload);
+    },
+
+    /**
+     * Handles the "aztec_wmSimulateTx" JSON-RPC method.
+     * This WalletMesh-specific method takes an {@link ExecutionPayload} and simulates
+     * the transaction, returning the {@link TxSimulationResult}.
+     *
+     * @param ctx - The {@link AztecHandlerContext}.
+     * @param paramsTuple - A tuple containing the {@link ExecutionPayload}.
+     *                      Defined by {@link AztecWalletMethodMap.aztec_wmSimulateTx.params}.
+     * @param paramsTuple.0 - The {@link ExecutionPayload} to simulate.
+     * @returns A promise that resolves to the {@link TxSimulationResult}.
+     *          Type defined by {@link AztecWalletMethodMap.aztec_wmSimulateTx.result}.
+     */
+    aztec_wmSimulateTx: async (
+      ctx: AztecHandlerContext,
+      paramsTuple: AztecWalletMethodMap['aztec_wmSimulateTx']['params'],
+    ): Promise<AztecWalletMethodMap['aztec_wmSimulateTx']['result']> => {
+      const [executionPayload] = paramsTuple;
+      return await simulateTransaction(ctx, executionPayload);
+    },
+
+    /**
+     * Handles the "aztec_wmDeployContract" JSON-RPC method.
+     * This WalletMesh-specific method deploys a new contract using its {@link ContractArtifact}
+     * and constructor arguments. It manages the deployment transaction lifecycle, including
+     * computing the contract address, proving, and sending the deployment transaction.
+     *
+     * Fee configuration is determined internally by the `getFeeOptions` helper.
+     *
+     * @param ctx - The {@link AztecHandlerContext}.
+     * @param paramsTuple - A tuple containing the deployment parameters (artifact, args, constructorName).
+     *                      Defined by {@link AztecWalletMethodMap.aztec_wmDeployContract.params}.
+     * @param paramsTuple.0.artifact - The {@link ContractArtifact} of the contract to deploy.
+     * @param paramsTuple.0.args - An array of arguments for the contract's constructor.
+     * @param paramsTuple.0.constructorName - Optional name of the constructor function if the artifact has multiple.
+     * @returns A promise that resolves to an object containing the `txHash` ({@link TxHash})
+     *          of the deployment transaction and the `contractAddress` ({@link AztecAddress})
+     *          of the newly deployed contract.
+     *          Type defined by {@link AztecWalletMethodMap.aztec_wmDeployContract.result}.
+     */
+    aztec_wmDeployContract: async (
+      ctx: AztecHandlerContext,
+      paramsTuple: AztecWalletMethodMap['aztec_wmDeployContract']['params'],
+    ): Promise<AztecWalletMethodMap['aztec_wmDeployContract']['result']> => {
+      const [params] = paramsTuple;
+      const { artifact, args, constructorName } = params;
+
+      logger.debug(`aztec_wmDeployContract: deploying ${artifact.name} with ${args.length} args`);
+
+      try {
+        // Create deployment method using the server-side wallet
+        const deployMethod = Contract.deploy(ctx.wallet, artifact, args, constructorName);
+
+        const contractAddressSalt = Fr.random();
+        const txOpts = await getTxOptions(ctx);
+        const opts: DeployOptions = {
+          contractAddressSalt,
+          fee: await getFeeOptions(ctx),
+        };
+        if (txOpts.nonce) {
+          opts.nonce = txOpts.nonce;
+        }
+        if (txOpts.cancellable) {
+          opts.cancellable = txOpts.cancellable;
+        }
+
+        // Compute the contract address
+        const { address: contractAddress } = await deployMethod.getInstance(opts);
+        logger.debug(`Computed contract address: ${contractAddress.toString()}`);
+
+        const deployProvenTx = await deployMethod.prove(opts);
+
+        const deploySentTx = await deployProvenTx.send();
+        const txHash = await deploySentTx.getTxHash();
+        logger.debug(`Contract deployed, hash: ${txHash.toString()}`);
+
+        return {
+          txHash,
+          contractAddress,
+        };
+      } catch (error) {
+        logger.error(`Contract deployment failed for ${artifact.name}:`, error);
+        throw error;
+      }
+    },
+  };
+}