@walletmesh/aztec-rpc-wallet 0.3.1 → 0.4.0

package/src/contractArtifactCache.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, it, vi, beforeEach, type Mock } from 'vitest';
 import type { AztecAddress, ContractArtifact, Fr, Wallet } from '@aztec/aztec.js';
-import { randomDeployedContract } from '@aztec/circuit-types';
 import { ContractArtifactCache } from './contractArtifactCache.js';
 import { AztecWalletError } from './errors.js';
 
@@ -13,13 +12,25 @@ describe('ContractArtifactCache', () => {
 
   beforeEach(async () => {
     // Mock contract address and class ID
-    // Create a complete mock of AztecAddress
-
-    const { instance, artifact } = await randomDeployedContract();
-
-    mockContractAddress = instance.address;
-    mockContractClassId = instance.contractClassId;
-    mockArtifact = artifact;
+    // Create mocks instead of using randomDeployedContract to avoid native binding issues
+    mockContractAddress = {
+      toString: () => '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+      equals: () => false,
+      isZero: () => false,
+      toField: () => mockContractClassId,
+    } as unknown as AztecAddress;
+
+    mockContractClassId = {
+      toString: () => '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
+      toBigInt: () => BigInt(123),
+    } as unknown as Fr;
+
+    mockArtifact = {
+      name: 'TestContract',
+      functions: [],
+      outputs: {},
+      fileMap: {},
+    } as unknown as ContractArtifact;
 
     // Create mock wallet
     wallet = {
@@ -50,7 +61,7 @@ describe('ContractArtifactCache', () => {
   it('fetches and caches artifact on cache miss', async () => {
     // Setup: Configure wallet mocks
     (wallet.getContractMetadata as Mock).mockResolvedValue({
-      contractInstance: { contractClassId: mockContractClassId },
+      contractInstance: { currentContractClassId: mockContractClassId },
     });
     (wallet.getContractClassMetadata as Mock).mockResolvedValue({ artifact: mockArtifact });
 
@@ -90,7 +101,7 @@ describe('ContractArtifactCache', () => {
   it('throws error if contract class metadata not found', async () => {
     // Setup: Mock contract metadata found but class metadata missing
     (wallet.getContractMetadata as Mock).mockResolvedValue({
-      contractInstance: { contractClassId: mockContractClassId },
+      contractInstance: { currentContractClassId: mockContractClassId },
     });
     (wallet.getContractClassMetadata as Mock).mockResolvedValue({ artifact: undefined });
 

package/src/contractArtifactCache.ts

@@ -1,57 +1,74 @@
-/**
- * @module contractArtifactCache
- *
- * This module provides caching functionality for Aztec contract artifacts.
- * It helps improve performance by avoiding repeated fetches of the same contract artifacts.
- */
-
 import type { AztecAddress, ContractArtifact, Wallet } from '@aztec/aztec.js';
 
 import { AztecWalletError } from './errors.js';
 
 /**
- * Caches contract artifacts to optimize contract interactions.
+ * Manages an in-memory cache for Aztec {@link ContractArtifact}s.
+ *
+ * This class is designed to optimize performance by reducing redundant fetches
+ * of contract artifacts. When an artifact is requested for a given contract address,
+ * the cache first checks its local store. If the artifact is not found (a cache miss),
+ * it uses the provided {@link Wallet} instance to retrieve the contract's metadata,
+ * then its class metadata (which includes the artifact), stores it in the cache,
+ * and finally returns it. Subsequent requests for the same artifact will be served
+ * directly from the cache.
+ *
+ * This caching strategy helps to:
+ * - Minimize network requests to the PXE or node for contract data.
+ * - Reduce processing overhead associated with fetching and parsing artifacts.
+ * - Conserve memory by reusing already loaded artifact instances.
  *
- * This class maintains an in-memory cache of contract artifacts indexed by contract address.
- * When a contract artifact is requested:
- * 1. First checks the cache for an existing artifact
- * 2. If not found, fetches the contract instance and its artifact from the wallet
- * 3. Stores the artifact in the cache for future use
- * 4. Returns the artifact to the caller
+ * The cache is typically used within the `AztecHandlerContext` on the wallet-side
+ * to provide efficient artifact access to RPC method handlers.
  *
- * This caching mechanism helps reduce:
- * - Network requests to fetch contract data
- * - Processing overhead of parsing contract artifacts
- * - Memory usage by reusing existing artifacts
+ * @see {@link AztecHandlerContext}
+ * @see {@link Wallet}
+ * @see {@link ContractArtifact}
  */
 export class ContractArtifactCache {
-  /** Map of contract addresses to their artifacts */
+  /**
+   * In-memory map storing contract artifacts, keyed by their stringified {@link AztecAddress}.
+   * @internal
+   */
   private cache = new Map<string, ContractArtifact>();
-  /** Reference to the wallet instance for fetching contract data */
+
+  /**
+   * Reference to the `aztec.js` {@link Wallet} instance used to fetch contract
+   * metadata and artifacts in case of a cache miss.
+   * @internal
+   */
   private wallet: Wallet;
 
   /**
-   * Creates a new ContractArtifactCache instance.
-   * @param wallet - Wallet instance used to fetch contract data when cache misses occur
+   * Creates a new `ContractArtifactCache` instance.
+   *
+   * @param wallet - The `aztec.js` {@link Wallet} instance that will be used to
+   *                 fetch contract metadata and artifacts if they are not found
+   *                 in the cache. This wallet should be capable of calling
+   *                 `getContractMetadata` and `getContractClassMetadata`.
    */
   constructor(wallet: Wallet) {
     this.wallet = wallet;
   }
 
   /**
-   * Retrieves the contract artifact for a given contract address.
-   * First checks the cache, then falls back to fetching from the wallet if needed.
+   * Retrieves the {@link ContractArtifact} for a given {@link AztecAddress}.
    *
-   * The process:
-   * 1. Check if artifact exists in cache
-   * 2. If not, get contract instance from wallet
-   * 3. Use instance to get contract class ID
-   * 4. Fetch artifact using class ID
-   * 5. Cache the artifact for future use
+   * This method implements a cache-aside pattern:
+   * 1. It first checks if the artifact for the `contractAddress` is already in the cache.
+   * 2. If found (cache hit), the cached artifact is returned immediately.
+   * 3. If not found (cache miss):
+   *    a. It fetches the {@link ContractMetadata} for the `contractAddress` using the wallet.
+   *    b. It then fetches the {@link ContractClassMetadata} using the class ID from the contract metadata.
+   *       This class metadata is expected to contain the artifact.
+   *    c. The retrieved artifact is stored in the cache, associated with the `contractAddress`.
+   *    d. The artifact is then returned.
    *
-   * @param contractAddress - The contract address to retrieve the artifact for
-   * @returns Promise resolving to the contract artifact
-   * @throws {AztecWalletError} If contract instance or class not registered
+   * @param contractAddress - The {@link AztecAddress} of the contract whose artifact is to be retrieved.
+   * @returns A promise that resolves to the {@link ContractArtifact}.
+   * @throws {AztecWalletError} if the contract instance or its class (and thus artifact)
+   *                            is not registered with the wallet or cannot be found.
+   *                            Also re-throws other errors encountered during wallet calls.
    */
   public async getContractArtifact(contractAddress: AztecAddress): Promise<ContractArtifact> {
     const addressStr = contractAddress.toString();
@@ -67,10 +84,12 @@ export class ContractArtifactCache {
         throw new AztecWalletError('contractInstanceNotRegistered', addressStr);
       }
 
-      const contractClassMetadata = await this.wallet.getContractClassMetadata(contract.contractClassId);
+      const contractClassMetadata = await this.wallet.getContractClassMetadata(
+        contract.currentContractClassId,
+      );
       const artifact = contractClassMetadata.artifact;
       if (!artifact) {
-        throw new AztecWalletError('contractClassNotRegistered', contract.contractClassId.toString());
+        throw new AztecWalletError('contractClassNotRegistered', contract.currentContractClassId.toString());
       }
       this.cache.set(addressStr, artifact);
       return artifact;

package/src/errors.ts

@@ -1,8 +1,21 @@
+/**
+ * @module @walletmesh/aztec-rpc-wallet/errors
+ *
+ * This module defines custom error types and codes specific to the Aztec RPC Wallet.
+ * It provides a structured way to represent errors that can occur during
+ * interactions with the Aztec wallet, aligning with JSON-RPC error standards
+ * while offering more specific error information.
+ */
+
 import { JSONRPCError } from '@walletmesh/jsonrpc';
 
 /**
- * Enum of available Aztec Wallet RPC error types.
+ * An object acting as an enum for specific Aztec Wallet RPC error types.
+ * Each key represents a distinct error condition that can occur within the Aztec wallet system.
+ * These keys are used to look up corresponding error codes and messages in {@link AztecWalletErrorMap}.
+ *
  * @public
+ * @readonly
  */
 export const AztecWalletErrorType = {
   unknownInternalError: 'unknownInternalError',
@@ -25,18 +38,27 @@ export const AztecWalletErrorType = {
 } as const;
 
 /**
- * Type representing valid Aztec Wallet RPC error types.
+ * A type alias representing the string literal union of all valid keys from {@link AztecWalletErrorType}.
+ * This provides type safety when referring to specific Aztec wallet error types.
+ *
  * @public
  */
 export type AztecWalletErrorType = (typeof AztecWalletErrorType)[keyof typeof AztecWalletErrorType];
 
 /**
- * Map of error codes and messages for Aztec Wallet RPC errors.
+ * A map associating each {@link AztecWalletErrorType} with a specific JSON-RPC error code
+ * and a human-readable message. This map is used by the {@link AztecWalletError} class
+ * to construct standardized error objects.
+ *
+ * The error codes are chosen from the range typically reserved for server-defined errors
+ * in JSON-RPC (e.g., -32000 to -32099).
+ *
  * @public
+ * @readonly
  */
 export const AztecWalletErrorMap: Record<AztecWalletErrorType, { code: number; message: string }> = {
   unknownInternalError: { code: -32000, message: 'Unknown internal error' },
-  refused: { code: -32001, message: 'User refused transaction' },
+  refused: { code: -32001, message: 'User refused transaction' }, // Or request
   walletNotConnected: { code: -32002, message: 'Wallet not connected' },
   contractInstanceNotRegistered: { code: -32003, message: 'Contract instance not registered' },
   contractClassNotRegistered: { code: -32004, message: 'Contract class not registered' },
@@ -55,16 +77,42 @@ export const AztecWalletErrorMap: Record<AztecWalletErrorType, { code: number; m
 };
 
 /**
- * Custom error class for Aztec Wallet RPC errors.
+ * Custom error class for representing errors specific to the Aztec RPC Wallet.
+ * It extends the base {@link JSONRPCError} from `@walletmesh/jsonrpc` and uses
+ * predefined error types and messages from {@link AztecWalletErrorMap}.
+ *
+ * This class allows for consistent error handling and reporting within the
+ * Aztec wallet system, providing both a standard JSON-RPC error code and
+ * a more specific Aztec error type.
+ *
  * @public
+ * @example
+ * ```typescript
+ * if (!isConnected) {
+ *   throw new AztecWalletError('walletNotConnected', 'Attempted to call method while disconnected.');
+ * }
+ * ```
  */
 export class AztecWalletError extends JSONRPCError {
   /**
-   * Creates a new AztecWalletError.
-   * @param err - The error type from AztecWalletErrorMap
-   * @param data - Optional additional error data
+   * The specific Aztec wallet error type.
+   */
+  public readonly aztecErrorType: AztecWalletErrorType;
+
+  /**
+   * Creates a new `AztecWalletError` instance.
+   *
+   * @param errorType - The specific {@link AztecWalletErrorType} identifying the error.
+   *                    This key is used to look up the code and message from {@link AztecWalletErrorMap}.
+   * @param data - Optional additional data associated with the error. This can be a string
+   *               or a record, providing more context. It will be included in the `data`
+   *               field of the JSON-RPC error object.
    */
-  constructor(err: AztecWalletErrorType, data?: string) {
-    super(AztecWalletErrorMap[err].code, AztecWalletErrorMap[err].message, data);
+  constructor(errorType: AztecWalletErrorType, data?: string | Record<string, unknown>) {
+    const errorDetails = AztecWalletErrorMap[errorType];
+    super(errorDetails.code, errorDetails.message, data);
+    this.aztecErrorType = errorType;
+    // Ensure the name property is set to the class name
+    this.name = 'AztecWalletError';
   }
 }

package/src/index.test.ts

@@ -2,12 +2,8 @@ import { describe, it, expect } from 'vitest';
 import * as exports from './index.js';
 
 describe('index exports', () => {
-  it('should export AztecProvider', () => {
-    expect(exports.AztecProvider).toBeDefined();
-  });
-
-  it('should export AztecChainWallet', () => {
-    expect(exports.AztecChainWallet).toBeDefined();
+  it('should export AztecDappWallet', () => {
+    expect(exports.AztecDappWallet).toBeDefined();
   });
 
   it('should export error utilities', () => {

package/src/index.ts

@@ -1,64 +1,100 @@
 /**
  * @module @walletmesh/aztec-rpc-wallet
  *
- * This module provides a JSON-RPC implementation for interacting with Aztec Network.
- * It enables communication between dApps and wallets through a standardized interface.
+ * JSON-RPC wallet integration for Aztec Protocol, built on WalletMesh router for multi-chain support.
+ * This package provides both wallet-side and dApp-side implementations for Aztec integration.
  */
 
+// Wallet-side exports
 /**
- * Provider class for dApps to interact with Aztec wallets
- * @see AztecProvider
+ * Creates an Aztec wallet node that can be used with WalletRouter.
+ * This is the wallet-side implementation that handles JSON-RPC requests.
+ * @see {@link createAztecWalletNode}
  */
-export { AztecProvider } from './provider.js';
+export { createAztecWalletNode } from './wallet/create-node.js';
 
 /**
- * Minimal provider for direct interaction with an Aztec chain wallet
- * @see AztecChainProvider
+ * Context interface provided to all handler functions in the wallet implementation.
+ * @see {@link AztecHandlerContext}
  */
-export { AztecChainProvider } from './chainProvider.js';
+export type { AztecHandlerContext } from './wallet/handlers/index.js';
 
+// Client-side exports
 /**
- * Wallet implementation that handles RPC requests from dApps
- * @see AztecChainWallet
+ * DApp-side wallet class that implements the aztec.js Wallet interface.
+ * @see {@link AztecDappWallet}
  */
-export { AztecChainWallet } from './wallet.js';
-export { AztecChainWalletMiddleware } from './types.js';
+export { AztecDappWallet, createAztecWallet } from './client/aztec-dapp-wallet.js';
 
 /**
- * Cache for contract artifacts
- * @see ContractArtifactCache
+ * Extended WalletRouterProvider with built-in Aztec serialization support.
+ * Use this instead of the base WalletRouterProvider for automatic serialization
+ * of Aztec types on the client side.
+ * @see {@link AztecRouterProvider}
  */
-export { ContractArtifactCache } from './contractArtifactCache.js';
+export { AztecRouterProvider } from './client/aztec-router-provider.js';
 
 /**
- * Error handling utilities for RPC communication
- * @see AztecWalletError
- * @see AztecWalletErrorMap
+ * Helper constants and functions for connecting to Aztec wallets.
+ * - ALL_AZTEC_METHODS: Complete list of all available Aztec methods
+ * - connectAztec: Helper to connect to Aztec and create wallet instance
  */
-export { AztecWalletError, AztecWalletErrorMap } from './errors.js';
+export {
+  ALL_AZTEC_METHODS,
+  connectAztec,
+} from './client/helpers.js';
+
+/**
+ * Helper function to register Aztec serializers with a WalletRouterProvider.
+ * This enables proper serialization of Aztec types when using the router.
+ * @see {@link registerAztecSerializers}
+ */
+export { registerAztecSerializers } from './client/register-serializers.js';
 
+// Shared types
 /**
- * Type definitions for RPC interfaces
+ * Core type definitions used throughout the package.
+ * - AztecChainId: Type-safe Aztec chain ID format (e.g., "aztec:mainnet")
+ * - AztecWalletContext: Context object for wallet implementations
+ * - AztecWalletMethodMap: Complete method map for all Aztec wallet methods
  */
 export type {
-  /** Chain identifier type */
   AztecChainId,
-  /** Context passed through RPC middleware */
   AztecWalletContext,
-  /** Event map for wallet events */
-  AztecWalletEventMap,
-  /** Base method map for core wallet functionality */
-  AztecWalletBaseMethodMap,
-  /** Complete method map including all Aztec methods */
   AztecWalletMethodMap,
-  /** Middleware type for processing RPC requests */
-  AztecWalletMiddleware,
-  /** Router client type for wallet mesh integration */
-  AztecWalletRouterClient,
-  /** Handler type for wallet methods */
-  AztecWalletMethodHandler,
-  /** Type for contract function calls */
-  TransactionFunctionCall,
-  /** Parameters for transaction requests */
-  TransactionParams,
 } from './types.js';
+
+// Utilities
+/**
+ * Cache utility for managing contract artifacts in wallet implementations.
+ * @see {@link ContractArtifactCache}
+ */
+export { ContractArtifactCache } from './contractArtifactCache.js';
+
+// Error utilities
+/**
+ * Error handling utilities for Aztec wallet operations.
+ * - AztecWalletError: Custom error class for Aztec wallet errors
+ * - AztecWalletErrorMap: Map of error codes to error messages
+ */
+export { AztecWalletError, AztecWalletErrorMap } from './errors.js';
+
+// Re-export serializers
+/**
+ * Re-exports the primary {@link AztecWalletSerializer} and the wallet-side
+ * `registerAztecSerializers` function from the `wallet/serializers` module.
+ * These are crucial for handling Aztec-specific data types over JSON-RPC
+ * on the wallet (node) side.
+ *
+ * @see {@link AztecWalletSerializer} - The main serializer object.
+ * @see {@link module:@walletmesh/aztec-rpc-wallet/wallet/serializers} - The module providing these utilities.
+ * Note: The client-side `registerAztecSerializers` is exported separately from `./client/register-serializers.js`.
+ */
+export {
+  AztecWalletSerializer,
+  registerAztecSerializers as registerWalletAztecSerializers,
+} from './wallet/serializers.js';
+// To avoid naming collision with client/register-serializers.ts,
+// the wallet-side registerAztecSerializers is re-exported as registerWalletAztecSerializers.
+// AztecWalletSerializer is unique and can be re-exported directly.
+// Other internal details of wallet/serializers.ts are not re-exported here.