@walletmesh/aztec-rpc-wallet 0.3.0 → 0.4.0

package/src/wallet/handlers/event.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:event');
+
+/**
+ * Creates handlers for event-related Aztec wallet JSON-RPC methods.
+ * These handlers are responsible for querying private (encrypted) and public
+ * (unencrypted) events emitted by Aztec contracts.
+ *
+ * Each handler function receives an {@link AztecHandlerContext} which provides access
+ * to the {@link PXE} client, essential for event retrieval.
+ *
+ * @returns An object where keys are event-related method names
+ *          (e.g., "aztec_getPrivateEvents", "aztec_getPublicEvents") and values are
+ *          their corresponding handler functions.
+ * @see {@link AztecWalletMethodMap} for method definitions.
+ */
+export function createEventHandlers() {
+  return {
+    /**
+     * Handles the "aztec_getPrivateEvents" JSON-RPC method.
+     * Retrieves encrypted private events emitted by a specific contract within a given
+     * block range, for a specified set of recipients.
+     *
+     * Private events are decrypted by the {@link PXE} using the viewing keys
+     * associated with the recipient addresses.
+     *
+     * @param ctx - The {@link AztecHandlerContext} containing the `pxe` instance.
+     * @param paramsTuple - A tuple containing parameters for querying private events.
+     *                      Defined by {@link AztecWalletMethodMap.aztec_getPrivateEvents.params}.
+     * @param paramsTuple.0 - The {@link AztecAddress} of the contract that emitted the events.
+     * @param paramsTuple.1 - The {@link EventMetadataDefinition} describing the event structure.
+     * @param paramsTuple.2 - The starting block number (inclusive) from which to query.
+     * @param paramsTuple.3 - The number of blocks to scan from the `from` block.
+     * @param paramsTuple.4 - An array of {@link AztecAddress} recipients whose events are to be fetched and decrypted.
+     * @returns A promise that resolves to an array of decoded private event data. The specific type
+     *          of the event data depends on the `eventMetadata`.
+     *          Type defined by {@link AztecWalletMethodMap.aztec_getPrivateEvents.result}.
+     * @throws {Error} If any required parameters are missing or invalid, though type checking
+     *                 and serializer validation should catch this earlier.
+     */
+    aztec_getPrivateEvents: async (
+      ctx: AztecHandlerContext,
+      paramsTuple: AztecWalletMethodMap['aztec_getPrivateEvents']['params'],
+    ): Promise<AztecWalletMethodMap['aztec_getPrivateEvents']['result']> => {
+      const [contractAddress, eventMetadata, from, numBlocks, recipients] = paramsTuple;
+      logger.debug(
+        `[HANDLER] aztec_getPrivateEvents: contractAddress = ${contractAddress?.toString()}, from = ${from}, numBlocks = ${numBlocks}`,
+      );
+      // All parameters are mandatory in the tuple type definition.
+      // Add runtime checks if there's any doubt about them being undefined, though TS should catch.
+      if (
+        !contractAddress ||
+        !eventMetadata ||
+        from === undefined ||
+        numBlocks === undefined ||
+        !recipients
+      ) {
+        throw new Error('Invalid parameters received in tuple for aztec_getPrivateEvents');
+      }
+      return await ctx.pxe.getPrivateEvents(contractAddress, eventMetadata, from, numBlocks, recipients);
+    },
+
+    /**
+     * Handles the "aztec_getPublicEvents" JSON-RPC method.
+     * Retrieves unencrypted public events matching a specific {@link EventMetadataDefinition}
+     * starting from a given block number, up to a specified limit.
+     *
+     * Public events are visible to all network participants and are typically used for
+     * information that does not require privacy.
+     *
+     * @param ctx - The {@link AztecHandlerContext} containing the `pxe` instance.
+     * @param paramsTuple - A tuple containing parameters for querying public events.
+     *                      Defined by {@link AztecWalletMethodMap.aztec_getPublicEvents.params}.
+     * @param paramsTuple.0 - The {@link EventMetadataDefinition} describing the event structure.
+     * @param paramsTuple.1 - The starting block number (inclusive) from which to query.
+     * @param paramsTuple.2 - The maximum number of events to return.
+     * @returns A promise that resolves to an array of decoded public event data. The specific type
+     *          of the event data depends on the `eventMetadata`.
+     *          Type defined by {@link AztecWalletMethodMap.aztec_getPublicEvents.result}.
+     * @throws {Error} If any required parameters are missing or invalid, though type checking
+     *                 and serializer validation should catch this earlier.
+     */
+    aztec_getPublicEvents: async (
+      ctx: AztecHandlerContext,
+      paramsTuple: AztecWalletMethodMap['aztec_getPublicEvents']['params'],
+    ): Promise<AztecWalletMethodMap['aztec_getPublicEvents']['result']> => {
+      const [eventMetadata, from, limit] = paramsTuple;
+      logger.debug(`[HANDLER] aztec_getPublicEvents: from = ${from}, limit = ${limit}`);
+      // All parameters are mandatory in the tuple type definition.
+      if (!eventMetadata || from === undefined || limit === undefined) {
+        throw new Error('Invalid parameters received in tuple for aztec_getPublicEvents');
+      }
+      return await ctx.pxe.getPublicEvents(eventMetadata, from, limit);
+    },
+  };
+}

package/src/wallet/handlers/index.ts

@@ -0,0 +1,84 @@
+import type { AccountWallet, PXE } from '@aztec/aztec.js';
+import type { JSONRPCContext, JSONRPCParams } from '@walletmesh/jsonrpc';
+import type { ContractArtifactCache } from '../../contractArtifactCache.js';
+import type { AztecWalletMethodMap } from '../../types.js';
+
+import { createAccountHandlers } from './account.js';
+import { createTransactionHandlers } from './transaction.js';
+import { createContractHandlers } from './contract.js';
+import { createContractInteractionHandlers } from './contract-interaction.js';
+import { createEventHandlers } from './event.js';
+import { createNodeHandlers } from './node.js';
+import { createSenderHandlers } from './senders.js';
+
+/**
+ * Defines the context object that is passed to all Aztec wallet JSON-RPC method handlers.
+ * This context provides handlers with the necessary dependencies to perform their operations.
+ * It extends the base {@link JSONRPCContext} with Aztec-specific instances.
+ *
+ * @property wallet - An instance of {@link AccountWallet} from `aztec.js`,
+ *                    representing the user's account and signing capabilities.
+ * @property pxe - An instance of {@link PXE} (Private Execution Environment) client
+ *                 from `aztec.js`, used for interacting with the Aztec network.
+ * @property cache - An instance of {@link ContractArtifactCache} used for caching
+ *                   contract artifacts to optimize performance.
+ */
+export interface AztecHandlerContext extends JSONRPCContext {
+  wallet: AccountWallet;
+  pxe: PXE;
+  cache: ContractArtifactCache;
+}
+
+/**
+ * Defines the generic signature for an Aztec wallet JSON-RPC method handler function.
+ *
+ * @template M - A key from {@link AztecWalletMethodMap}, representing the specific Aztec method being handled.
+ * @param context - The {@link AztecHandlerContext} providing access to wallet, PXE, and cache.
+ * @param params - The parameters for the RPC method, typed as {@link JSONRPCParams} (typically an array or object).
+ *                 The specific structure of `params` is defined by `AztecWalletMethodMap[M]['params']`.
+ * @returns A promise that resolves to the result of the RPC method, typed according to `AztecWalletMethodMap[M]['result']`.
+ */
+export type AztecHandler<M extends keyof AztecWalletMethodMap> = (
+  context: AztecHandlerContext,
+  params: AztecWalletMethodMap[M]['params'], // More specific than JSONRPCParams
+) => Promise<AztecWalletMethodMap[M]['result']>;
+
+/**
+ * Creates and aggregates all Aztec JSON-RPC method handlers.
+ *
+ * This factory function consolidates handlers from various specialized modules
+ * (account, transaction, contract, etc.) into a single object. This object
+ * maps method names (as defined in {@link AztecWalletMethodMap}) to their
+ * respective handler functions.
+ *
+ * The resulting map of handlers is typically registered with a {@link JSONRPCNode}
+ * instance on the wallet-side.
+ *
+ * @returns An object where keys are Aztec method names (e.g., "aztec_getAddress")
+ *          and values are the corresponding handler functions. Each handler
+ *          conforms to the {@link AztecHandler} type.
+ *
+ * @see {@link createAccountHandlers}
+ * @see {@link createTransactionHandlers}
+ * @see {@link createContractHandlers}
+ * @see {@link createContractInteractionHandlers}
+ * @see {@link createSenderHandlers}
+ * @see {@link createEventHandlers}
+ * @see {@link createNodeHandlers}
+ * @see {@link createAztecWalletNode} where these handlers are typically used.
+ */
+export function createAztecHandlers() {
+  return {
+    // Note: The individual createXYZHandlers() functions return objects whose methods
+    // might have params typed as general JSONRPCParams or a more specific tuple.
+    // The createAztecWalletNode function correctly casts these to the specific
+    // handler signatures expected by JSONRPCNode.registerMethod, using AztecWalletMethodMap.
+    ...createAccountHandlers(),
+    ...createTransactionHandlers(),
+    ...createContractHandlers(),
+    ...createContractInteractionHandlers(),
+    ...createSenderHandlers(),
+    ...createEventHandlers(),
+    ...createNodeHandlers(),
+  };
+}

package/src/wallet/handlers/node.test.ts

@@ -0,0 +1,304 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createNodeHandlers } from './node.js';
+import type { AccountWallet, PXE } from '@aztec/aztec.js';
+import type { NodeInfo } from '@aztec/stdlib/contract';
+import type { GasFees } from '@aztec/stdlib/gas';
+import type { PXEInfo } from '@aztec/stdlib/interfaces/client';
+import type { L2Block } from '@aztec/aztec.js';
+import type { AztecHandlerContext } from './index.js';
+import type { ContractArtifactCache } from '../../contractArtifactCache.js';
+import { Fr } from '@aztec/aztec.js';
+
+// Mock dependencies
+const createMockWallet = () =>
+  ({
+    getChainId: vi.fn(),
+    getVersion: vi.fn(),
+    getNodeInfo: vi.fn(),
+    getCurrentBaseFees: vi.fn(),
+  }) as unknown as AccountWallet;
+
+const createMockPXE = () =>
+  ({
+    getPXEInfo: vi.fn(),
+    getBlock: vi.fn(),
+    getBlockNumber: vi.fn(),
+  }) as unknown as PXE;
+
+const createMockContext = (wallet: AccountWallet, pxe: PXE): AztecHandlerContext => ({
+  wallet,
+  pxe,
+  cache: {} as ContractArtifactCache,
+});
+
+describe('Node Handlers', () => {
+  let mockWallet: AccountWallet;
+  let mockPXE: PXE;
+  let context: AztecHandlerContext;
+  let handlers: ReturnType<typeof createNodeHandlers>;
+
+  beforeEach(() => {
+    mockWallet = createMockWallet();
+    mockPXE = createMockPXE();
+    context = createMockContext(mockWallet, mockPXE);
+    handlers = createNodeHandlers();
+  });
+
+  describe('wm_getSupportedMethods', () => {
+    it('should return array of supported Aztec methods', async () => {
+      const result = await handlers.wm_getSupportedMethods(context, []);
+
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toContain('aztec_getAddress');
+      expect(result).toContain('aztec_getChainId');
+      expect(result).toContain('aztec_sendTx');
+      expect(result).toContain('wm_getSupportedMethods');
+      expect(result.length).toBeGreaterThan(25); // Should have many methods
+    });
+
+    it('should include all essential wallet methods', async () => {
+      const result = await handlers.wm_getSupportedMethods(context, []);
+
+      const essentialMethods = [
+        'aztec_getAddress',
+        'aztec_getCompleteAddress',
+        'aztec_createAuthWit',
+        'aztec_sendTx',
+        'aztec_getTxReceipt',
+        'aztec_getNodeInfo',
+        'aztec_getChainId',
+        'aztec_getVersion',
+      ];
+
+      for (const method of essentialMethods) {
+        expect(result).toContain(method);
+      }
+    });
+  });
+
+  describe('aztec_getChainId', () => {
+    it('should call wallet.getChainId and return numeric value', async () => {
+      const chainId = new Fr(31337);
+      vi.mocked(mockWallet.getChainId).mockReturnValue(chainId);
+
+      const result = await handlers.aztec_getChainId(context, []);
+
+      expect(mockWallet.getChainId).toHaveBeenCalledOnce();
+      expect(result.toNumber()).toBe(31337);
+      expect(result).toBeInstanceOf(Fr);
+    });
+
+    it('should handle large chain IDs', async () => {
+      const chainId = new Fr(123456789);
+      vi.mocked(mockWallet.getChainId).mockReturnValue(chainId);
+
+      const result = await handlers.aztec_getChainId(context, []);
+
+      expect(mockWallet.getChainId).toHaveBeenCalledOnce();
+      expect(result.toNumber()).toBe(123456789);
+    });
+
+    it('should propagate errors from wallet.getChainId', async () => {
+      const error = new Error('Failed to get chain ID');
+      vi.mocked(mockWallet.getChainId).mockImplementation(() => {
+        throw error;
+      });
+
+      await expect(handlers.aztec_getChainId(context, [])).rejects.toThrow('Failed to get chain ID');
+    });
+  });
+
+  describe('aztec_getVersion', () => {
+    it('should call wallet.getVersion and return numeric value', async () => {
+      const version = new Fr(1);
+      vi.mocked(mockWallet.getVersion).mockReturnValue(version);
+
+      const result = await handlers.aztec_getVersion(context, []);
+
+      expect(mockWallet.getVersion).toHaveBeenCalledOnce();
+      expect(result.toNumber()).toBe(1);
+      expect(result).toBeInstanceOf(Fr);
+    });
+
+    it('should handle different version numbers', async () => {
+      const version = new Fr(42);
+      vi.mocked(mockWallet.getVersion).mockReturnValue(version);
+
+      const result = await handlers.aztec_getVersion(context, []);
+
+      expect(mockWallet.getVersion).toHaveBeenCalledOnce();
+      expect(result.toNumber()).toBe(42);
+    });
+
+    it('should propagate errors from wallet.getVersion', async () => {
+      const error = new Error('Failed to get version');
+      vi.mocked(mockWallet.getVersion).mockImplementation(() => {
+        throw error;
+      });
+
+      await expect(handlers.aztec_getVersion(context, [])).rejects.toThrow('Failed to get version');
+    });
+  });
+
+  describe('aztec_getNodeInfo', () => {
+    it('should call wallet.getNodeInfo and return node information', async () => {
+      const nodeInfo = {
+        nodeVersion: '0.1.0',
+        l1ChainId: 1,
+        protocolVersion: 1,
+        l1ContractAddresses: {
+          availabilityOracleAddress: '0x123' as unknown,
+          rollupAddress: '0x456' as unknown,
+          registryAddress: '0x789' as unknown,
+          inboxAddress: '0xabc' as unknown,
+          outboxAddress: '0xdef' as unknown,
+          gasTokenAddress: '0x111' as unknown,
+          gasPortalAddress: '0x222' as unknown,
+        },
+      } as unknown as NodeInfo;
+
+      vi.mocked(mockWallet.getNodeInfo).mockResolvedValue(nodeInfo);
+
+      const result = await handlers.aztec_getNodeInfo(context, []);
+
+      expect(mockWallet.getNodeInfo).toHaveBeenCalledOnce();
+      expect(result).toBe(nodeInfo);
+      expect(result.nodeVersion).toBe('0.1.0');
+      expect(result.l1ChainId).toBe(1);
+    });
+
+    it('should propagate errors from wallet.getNodeInfo', async () => {
+      const error = new Error('Failed to get node info');
+      vi.mocked(mockWallet.getNodeInfo).mockRejectedValue(error);
+
+      await expect(handlers.aztec_getNodeInfo(context, [])).rejects.toThrow('Failed to get node info');
+      expect(mockWallet.getNodeInfo).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('aztec_getCurrentBaseFees', () => {
+    it('should call wallet.getCurrentBaseFees and return fee information', async () => {
+      const gasFees = {
+        feePerDaGas: 100n,
+        feePerL2Gas: 200n,
+      } as unknown as GasFees;
+
+      vi.mocked(mockWallet.getCurrentBaseFees).mockResolvedValue(gasFees);
+
+      const result = await handlers.aztec_getCurrentBaseFees(context, []);
+
+      expect(mockWallet.getCurrentBaseFees).toHaveBeenCalledOnce();
+      expect(result).toBe(gasFees);
+    });
+
+    it('should propagate errors from wallet.getCurrentBaseFees', async () => {
+      const error = new Error('Failed to get base fees');
+      vi.mocked(mockWallet.getCurrentBaseFees).mockRejectedValue(error);
+
+      await expect(handlers.aztec_getCurrentBaseFees(context, [])).rejects.toThrow('Failed to get base fees');
+      expect(mockWallet.getCurrentBaseFees).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('aztec_getPXEInfo', () => {
+    it('should call pxe.getPXEInfo and return PXE information', async () => {
+      const pxeInfo = {
+        pxeVersion: '0.1.0',
+        protocolVersion: 1,
+        l1ContractAddresses: {
+          availabilityOracleAddress: '0x123' as unknown,
+          rollupAddress: '0x456' as unknown,
+          registryAddress: '0x789' as unknown,
+          inboxAddress: '0xabc' as unknown,
+          outboxAddress: '0xdef' as unknown,
+          gasTokenAddress: '0x111' as unknown,
+          gasPortalAddress: '0x222' as unknown,
+        },
+      } as unknown as PXEInfo;
+
+      vi.mocked(mockPXE.getPXEInfo).mockResolvedValue(pxeInfo);
+
+      const result = await handlers.aztec_getPXEInfo(context, []);
+
+      expect(mockPXE.getPXEInfo).toHaveBeenCalledOnce();
+      expect(result).toBe(pxeInfo);
+      expect(result.pxeVersion).toBe('0.1.0');
+    });
+
+    it('should propagate errors from pxe.getPXEInfo', async () => {
+      const error = new Error('Failed to get PXE info');
+      vi.mocked(mockPXE.getPXEInfo).mockRejectedValue(error);
+
+      await expect(handlers.aztec_getPXEInfo(context, [])).rejects.toThrow('Failed to get PXE info');
+      expect(mockPXE.getPXEInfo).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('aztec_getBlock', () => {
+    it('should call pxe.getBlock with block number and return block', async () => {
+      const blockNumber = 42;
+      const block = {
+        number: blockNumber,
+        hash: '0xabcdef1234567890',
+        timestamp: Date.now(),
+        l1BlockNumber: 100,
+      } as unknown as L2Block;
+
+      vi.mocked(mockPXE.getBlock).mockResolvedValue(block);
+
+      const result = await handlers.aztec_getBlock(context, [blockNumber]);
+
+      expect(mockPXE.getBlock).toHaveBeenCalledWith(blockNumber);
+      expect(result).toBe(block);
+      expect(result.number).toBe(blockNumber);
+    });
+
+    it('should throw error when block is not found', async () => {
+      const blockNumber = 999999;
+      vi.mocked(mockPXE.getBlock).mockResolvedValue(undefined);
+
+      await expect(handlers.aztec_getBlock(context, [blockNumber])).rejects.toThrow('Block not found');
+      expect(mockPXE.getBlock).toHaveBeenCalledWith(blockNumber);
+    });
+
+    it('should propagate errors from pxe.getBlock', async () => {
+      const blockNumber = 42;
+      const error = new Error('Failed to get block');
+      vi.mocked(mockPXE.getBlock).mockRejectedValue(error);
+
+      await expect(handlers.aztec_getBlock(context, [blockNumber])).rejects.toThrow('Failed to get block');
+      expect(mockPXE.getBlock).toHaveBeenCalledWith(blockNumber);
+    });
+  });
+
+  describe('aztec_getBlockNumber', () => {
+    it('should call pxe.getBlockNumber and return current block number', async () => {
+      const blockNumber = 12345;
+      vi.mocked(mockPXE.getBlockNumber).mockResolvedValue(blockNumber);
+
+      const result = await handlers.aztec_getBlockNumber(context, []);
+
+      expect(mockPXE.getBlockNumber).toHaveBeenCalledOnce();
+      expect(result).toBe(blockNumber);
+      expect(typeof result).toBe('number');
+    });
+
+    it('should handle block number of 0', async () => {
+      const blockNumber = 0;
+      vi.mocked(mockPXE.getBlockNumber).mockResolvedValue(blockNumber);
+
+      const result = await handlers.aztec_getBlockNumber(context, []);
+
+      expect(mockPXE.getBlockNumber).toHaveBeenCalledOnce();
+      expect(result).toBe(0);
+    });
+
+    it('should propagate errors from pxe.getBlockNumber', async () => {
+      const error = new Error('Failed to get block number');
+      vi.mocked(mockPXE.getBlockNumber).mockRejectedValue(error);
+
+      await expect(handlers.aztec_getBlockNumber(context, [])).rejects.toThrow('Failed to get block number');
+      expect(mockPXE.getBlockNumber).toHaveBeenCalledOnce();
+    });
+  });
+});