@walletmesh/aztec-rpc-wallet 0.1.0

package/src/serializers/core.ts

@@ -0,0 +1,141 @@
+import { Fr, AztecAddress, CompleteAddress, AuthWitness, TxHash } from '@aztec/aztec.js';
+import { encodeBase64, decodeBase64 } from './types.js';
+import type { TypeSerializer } from './types.js';
+
+/**
+ * Serializer for Fr (field element) values in the Aztec protocol.
+ * Handles conversion of field elements to/from base64-encoded strings for RPC transport.
+ * Field elements are fundamental to Aztec's cryptographic operations.
+ */
+export class FrSerializer implements TypeSerializer<Fr> {
+  /**
+   * Converts an Fr value to a base64-encoded string.
+   * @param value - The field element to serialize
+   * @returns Base64-encoded string representation
+   */
+  serialize(value: Fr): string {
+    return encodeBase64(value.toString());
+  }
+
+  /**
+   * Reconstructs an Fr value from a base64-encoded string.
+   * @param data - The base64-encoded string to deserialize
+   * @returns Reconstructed field element
+   * @throws If the input string is not a valid field element representation
+   */
+  deserialize(data: string): Fr {
+    return Fr.fromHexString(decodeBase64(data));
+  }
+}
+
+/**
+ * Serializer for Aztec protocol addresses.
+ * Handles conversion of AztecAddress instances to/from base64-encoded strings.
+ * Aztec addresses represent accounts and contracts in the protocol.
+ */
+export class AztecAddressSerializer implements TypeSerializer<AztecAddress> {
+  /**
+   * Converts an AztecAddress to a base64-encoded string.
+   * @param value - The Aztec address to serialize
+   * @returns Base64-encoded string representation
+   */
+  serialize(value: AztecAddress): string {
+    return encodeBase64(value.toString());
+  }
+
+  /**
+   * Reconstructs an AztecAddress from a base64-encoded string.
+   * @param data - The base64-encoded string to deserialize
+   * @returns Reconstructed Aztec address
+   * @throws If the input string is not a valid address representation
+   */
+  deserialize(data: string): AztecAddress {
+    return AztecAddress.fromString(decodeBase64(data));
+  }
+}
+
+/**
+ * Serializer for complete Aztec addresses that include additional metadata.
+ * CompleteAddress extends AztecAddress with extra information needed for certain operations.
+ */
+export class CompleteAddressSerializer implements TypeSerializer<CompleteAddress> {
+  /**
+   * Converts a CompleteAddress to a base64-encoded string.
+   * @param value - The complete address to serialize
+   * @returns Base64-encoded string representation
+   */
+  serialize(value: CompleteAddress): string {
+    return encodeBase64(value.toString());
+  }
+
+  /**
+   * Reconstructs a CompleteAddress from a base64-encoded string.
+   * @param data - The base64-encoded string to deserialize
+   * @returns Reconstructed complete address
+   * @throws If the input string is not a valid complete address representation
+   */
+  deserialize(data: string): CompleteAddress {
+    return CompleteAddress.fromString(decodeBase64(data));
+  }
+}
+
+/**
+ * Serializer for authentication witnesses in the Aztec protocol.
+ * AuthWitness values are used to prove transaction authorization.
+ */
+export class AuthWitnessSerializer implements TypeSerializer<AuthWitness> {
+  /**
+   * Converts an AuthWitness to a base64-encoded string.
+   * @param value - The authentication witness to serialize
+   * @returns Base64-encoded string representation
+   */
+  serialize(value: AuthWitness): string {
+    return encodeBase64(value.toString());
+  }
+
+  /**
+   * Reconstructs an AuthWitness from a base64-encoded string.
+   * @param data - The base64-encoded string to deserialize
+   * @returns Reconstructed authentication witness
+   * @throws If the input string is not a valid auth witness representation
+   */
+  deserialize(data: string): AuthWitness {
+    return AuthWitness.fromString(decodeBase64(data));
+  }
+}
+
+/**
+ * Serializer for transaction hashes in the Aztec protocol.
+ * TxHash values uniquely identify transactions and are used for lookups and references.
+ */
+export class TxHashSerializer implements TypeSerializer<TxHash> {
+  /**
+   * Converts a TxHash to a base64-encoded string.
+   * @param value - The transaction hash to serialize
+   * @returns Base64-encoded string representation
+   */
+  serialize(value: TxHash): string {
+    return encodeBase64(value.toString());
+  }
+
+  /**
+   * Reconstructs a TxHash from a base64-encoded string.
+   * @param data - The base64-encoded string to deserialize
+   * @returns Reconstructed transaction hash
+   * @throws If the input string is not a valid transaction hash representation
+   */
+  deserialize(data: string): TxHash {
+    return TxHash.fromString(decodeBase64(data));
+  }
+}
+
+/**
+ * Pre-instantiated serializer instances for common Aztec types.
+ * These singletons should be used instead of creating new instances
+ * to ensure consistent serialization across the application.
+ */
+export const frSerializer = new FrSerializer();
+export const aztecAddressSerializer = new AztecAddressSerializer();
+export const completeAddressSerializer = new CompleteAddressSerializer();
+export const authWitnessSerializer = new AuthWitnessSerializer();
+export const txHashSerializer = new TxHashSerializer();

package/src/serializers/index.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it, beforeEach, vi } from 'vitest';
+import { AztecWalletSerializer } from './index.js';
+import { AztecAddress, Tx } from '@aztec/aztec.js';
+import type { JSONRPCSerializer } from './types.js';
+
+describe('AztecWalletSerializer', () => {
+  // Test known method (using aztec_setScopes as an example)
+  const knownMethod = 'aztec_setScopes';
+
+  // Test unknown method
+  const unknownMethod = 'unknown_method';
+
+  // Type assertion since we verify result exists in beforeEach
+  const resultSerializer = (AztecWalletSerializer as Required<JSONRPCSerializer<unknown, unknown>>).result;
+
+  describe('params', () => {
+    it('should serialize params for known methods', () => {
+      const params = { scopes: [AztecAddress.random()] };
+      const result = AztecWalletSerializer.params.serialize(knownMethod, params);
+      expect(result).toBeDefined();
+      expect(result.method).toBe(knownMethod);
+      expect(typeof result.serialized).toBe('string');
+    });
+
+    it('should wrap unknown method params in JSONRPCSerializedData format', () => {
+      const params = { someParam: 'value' };
+      const result = AztecWalletSerializer.params.serialize(unknownMethod, params);
+      expect(result).toBeDefined();
+      expect(result.method).toBe(unknownMethod);
+      expect(typeof result.serialized).toBe('string');
+    });
+
+    it('should pass through serialized data for unknown methods', () => {
+      const serializedData = { serialized: 'base64data', method: unknownMethod };
+      const result = AztecWalletSerializer.params.deserialize(unknownMethod, serializedData);
+      expect(result).toEqual(serializedData);
+    });
+
+    it('should throw error when params serializer fails', () => {
+      const params = { scopes: undefined }; // Invalid - scopes must be an array
+      expect(() => AztecWalletSerializer.params.serialize(knownMethod, params)).toThrow(
+        /Failed to serialize params/,
+      );
+    });
+
+    it('should throw error when params deserializer fails', () => {
+      const serializedData = { serialized: 'invalid-data', method: knownMethod };
+      expect(() => AztecWalletSerializer.params.deserialize(knownMethod, serializedData)).toThrow(
+        /Failed to deserialize params/,
+      );
+    });
+  });
+
+  describe('result', () => {
+    beforeEach(() => {
+      // Ensure result serializer exists
+      expect(resultSerializer).toBeDefined();
+    });
+
+    it('should serialize result for known methods', () => {
+      const value = true;
+      const result = resultSerializer.serialize(knownMethod, value);
+      expect(result).toBeDefined();
+      expect(result.method).toBe(knownMethod);
+      expect(typeof result.serialized).toBe('string');
+    });
+
+    it('should wrap unknown method result in JSONRPCSerializedData format', () => {
+      const testResult = { someResult: 'value' };
+      const result = resultSerializer.serialize(unknownMethod, testResult);
+      expect(result).toBeDefined();
+      expect(result.method).toBe(unknownMethod);
+      expect(typeof result.serialized).toBe('string');
+    });
+
+    it('should pass through serialized data for unknown methods', () => {
+      const serializedData = { serialized: 'base64data', method: unknownMethod };
+      const result = resultSerializer.deserialize(unknownMethod, serializedData);
+      expect(result).toEqual(serializedData);
+    });
+
+    it('should throw error when result serializer fails', () => {
+      interface CircularRef {
+        ref: CircularRef | null;
+      }
+      const circular: CircularRef = { ref: null };
+      circular.ref = circular; // Create circular reference which can't be JSON stringified
+      expect(() => resultSerializer.serialize(knownMethod, circular)).toThrow(/Failed to serialize result/);
+    });
+
+    it('should throw error when result deserializer fails', () => {
+      const serializedData = { serialized: 'invalid-data', method: knownMethod };
+      expect(() => resultSerializer.deserialize(knownMethod, serializedData)).toThrow(
+        /Failed to deserialize result/,
+      );
+    });
+  });
+
+  describe('integration', () => {
+    it('should handle contract methods', () => {
+      const method = 'aztec_getContractInstance';
+      const params = { address: AztecAddress.random() };
+
+      const serializedParams = AztecWalletSerializer.params.serialize(method, params);
+      expect(serializedParams).toBeDefined();
+      expect(serializedParams.method).toBe(method);
+      expect(typeof serializedParams.serialized).toBe('string');
+    });
+
+    it('should handle transaction methods', () => {
+      const method = 'aztec_sendTx';
+      const params = {
+        tx: Tx.random(),
+      };
+
+      const serializedParams = AztecWalletSerializer.params.serialize(method, params);
+      expect(serializedParams).toBeDefined();
+      expect(serializedParams.method).toBe(method);
+      expect(typeof serializedParams.serialized).toBe('string');
+    });
+  });
+});

package/src/serializers/index.ts

@@ -0,0 +1,213 @@
+import type { AztecWalletMethodMap } from '../types.js';
+import type { JSONRPCSerializer, JSONRPCSerializedData } from './types.js';
+import { encodeBase64 } from './types.js';
+
+/**
+ * Re-export all serializer types and implementations.
+ * This provides a single entry point for importing any serializer functionality.
+ */
+export * from './types.js';
+export * from './core.js';
+export * from './account.js';
+export * from './contract.js';
+export * from './transaction.js';
+export * from './note.js';
+export * from './log.js';
+
+// Import all serializer instances
+import {
+  aztecSetScopesSerializer,
+  aztecRegisterAccountSerializer,
+  aztecAddAuthWitnessSerializer,
+  aztecGetAuthWitnessSerializer,
+} from './account.js';
+import {
+  aztecGetContractInstanceSerializer,
+  aztecGetContractClassSerializer,
+  aztecGetContractArtifactSerializer,
+  aztecRegisterContractSerializer,
+} from './contract.js';
+import {
+  aztecCreateTxExecutionRequestSerializer,
+  aztecProveTxSerializer,
+  aztecSendTxSerializer,
+  aztecGetTxReceiptSerializer,
+} from './transaction.js';
+import {
+  aztecGetIncomingNotesSerializer,
+  aztecAddNoteSerializer,
+  aztecAddNullifiedNoteSerializer,
+} from './note.js';
+import {
+  aztecGetUnencryptedLogsSerializer,
+  aztecGetEncryptedEventsSerializer,
+  aztecGetUnencryptedEventsSerializer,
+} from './log.js';
+
+/**
+ * Type alias for Aztec RPC method names.
+ * Represents all available methods in the Aztec wallet RPC interface.
+ */
+type AztecMethodName = keyof AztecWalletMethodMap;
+
+/**
+ * Type helper for extracting parameter types for a given method.
+ * @typeParam T - The method name to get parameters for
+ */
+type AztecMethodParams<T extends AztecMethodName> = AztecWalletMethodMap[T]['params'];
+
+/**
+ * Type helper for extracting result types for a given method.
+ * @typeParam T - The method name to get result type for
+ */
+type AztecMethodResult<T extends AztecMethodName> = AztecWalletMethodMap[T]['result'];
+
+/**
+ * Registry of all available method serializers.
+ * Maps each RPC method name to its corresponding serializer implementation.
+ * This mapping is used by the main AztecWalletSerializer to route method calls
+ * to the appropriate specialized serializer.
+ */
+const methodSerializers: Record<AztecMethodName, JSONRPCSerializer<unknown, unknown>> = {
+  // Account methods
+  aztec_setScopes: aztecSetScopesSerializer,
+  aztec_registerAccount: aztecRegisterAccountSerializer,
+  aztec_addAuthWitness: aztecAddAuthWitnessSerializer,
+  aztec_getAuthWitness: aztecGetAuthWitnessSerializer,
+
+  // Contract methods
+  aztec_getContractInstance: aztecGetContractInstanceSerializer,
+  aztec_getContractClass: aztecGetContractClassSerializer,
+  aztec_getContractArtifact: aztecGetContractArtifactSerializer,
+  aztec_registerContract: aztecRegisterContractSerializer,
+
+  // Transaction methods
+  aztec_createTxExecutionRequest: aztecCreateTxExecutionRequestSerializer,
+  aztec_proveTx: aztecProveTxSerializer,
+  aztec_sendTx: aztecSendTxSerializer,
+  aztec_getTxReceipt: aztecGetTxReceiptSerializer,
+
+  // Note methods
+  aztec_getIncomingNotes: aztecGetIncomingNotesSerializer,
+  aztec_addNote: aztecAddNoteSerializer,
+  aztec_addNullifiedNote: aztecAddNullifiedNoteSerializer,
+
+  // Log methods
+  aztec_getUnencryptedLogs: aztecGetUnencryptedLogsSerializer,
+  aztec_getEncryptedEvents: aztecGetEncryptedEventsSerializer,
+  aztec_getUnencryptedEvents: aztecGetUnencryptedEventsSerializer,
+};
+
+/**
+ * Helper function to wrap unknown values in a standard JSON-RPC format.
+ * Used as a fallback when no specific serializer is available for a method.
+ *
+ * @param method - The RPC method name
+ * @param value - The value to wrap
+ * @returns Standardized JSON-RPC data structure
+ */
+function wrapUnknownValue(method: string, value: unknown): JSONRPCSerializedData {
+  return {
+    method,
+    serialized: encodeBase64(JSON.stringify(value)),
+  };
+}
+
+/**
+ * Main serializer for the Aztec wallet RPC interface.
+ * Provides a unified interface for serializing all supported RPC methods.
+ *
+ * This serializer:
+ * 1. Routes each method call to its specialized serializer from methodSerializers
+ * 2. Provides fallback handling for unknown methods
+ * 3. Wraps all serialization operations in proper error handling
+ *
+ * The serializer handles both:
+ * - Parameters: Incoming RPC call parameters
+ * - Results: Outgoing RPC call results
+ */
+export const AztecWalletSerializer: JSONRPCSerializer<unknown, unknown> = {
+  params: {
+    /**
+     * Serializes RPC method parameters using the appropriate method serializer.
+     * @param method - The RPC method name
+     * @param value - The parameters to serialize
+     * @returns Serialized parameter data
+     * @throws If serialization fails or encounters an error
+     */
+    serialize: (method: string, value: unknown): JSONRPCSerializedData => {
+      const serializer = methodSerializers[method as AztecMethodName];
+      if (!serializer?.params) {
+        return wrapUnknownValue(method, value);
+      }
+
+      try {
+        return serializer.params.serialize(method, value);
+      } catch (error) {
+        throw new Error(`Failed to serialize params for method ${method}: ${error}`);
+      }
+    },
+    /**
+     * Deserializes RPC method parameters using the appropriate method serializer.
+     * @param method - The RPC method name
+     * @param data - The serialized parameter data
+     * @returns Deserialized parameters
+     * @throws If deserialization fails or encounters an error
+     */
+    deserialize: (method: string, data: JSONRPCSerializedData): unknown => {
+      const serializer = methodSerializers[method as AztecMethodName];
+      if (!serializer?.params) {
+        return data;
+      }
+
+      try {
+        return serializer.params.deserialize(method, data);
+      } catch (error) {
+        throw new Error(`Failed to deserialize params for method ${method}: ${error}`);
+      }
+    },
+  },
+  result: {
+    /**
+     * Serializes RPC method results using the appropriate method serializer.
+     * @param method - The RPC method name
+     * @param value - The result to serialize
+     * @returns Serialized result data
+     * @throws If serialization fails or encounters an error
+     */
+    serialize: (method: string, value: unknown): JSONRPCSerializedData => {
+      const serializer = methodSerializers[method as AztecMethodName];
+      if (!serializer?.result) {
+        return wrapUnknownValue(method, value);
+      }
+
+      try {
+        return serializer.result.serialize(method, value);
+      } catch (error) {
+        throw new Error(`Failed to serialize result for method ${method}: ${error}`);
+      }
+    },
+    /**
+     * Deserializes RPC method results using the appropriate method serializer.
+     * @param method - The RPC method name
+     * @param data - The serialized result data
+     * @returns Deserialized result
+     * @throws If deserialization fails or encounters an error
+     */
+    deserialize: (method: string, data: JSONRPCSerializedData): unknown => {
+      const serializer = methodSerializers[method as AztecMethodName];
+      if (!serializer?.result) {
+        return data;
+      }
+
+      try {
+        return serializer.result.deserialize(method, data);
+      } catch (error) {
+        throw new Error(`Failed to deserialize result for method ${method}: ${error}`);
+      }
+    },
+  },
+};
+
+// Export the main serializer interface
+export type { JSONRPCSerializer } from './types.js';

package/src/serializers/log.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+import { Point, AztecAddress } from '@aztec/aztec.js';
+import { EventSelector } from '@aztec/foundation/abi';
+import type { AbiType } from '@aztec/foundation/abi';
+import {
+  ExtendedUnencryptedL2Log,
+  type GetUnencryptedLogsResponse,
+  type LogFilter,
+  LogId,
+  TxHash,
+} from '@aztec/circuit-types';
+import {
+  aztecGetUnencryptedLogsSerializer,
+  aztecGetEncryptedEventsSerializer,
+  aztecGetUnencryptedEventsSerializer,
+} from './log.js';
+
+describe('Log Serializers', () => {
+  describe('aztec_getUnencryptedLogs', () => {
+    const METHOD = 'aztec_getUnencryptedLogs';
+
+    it('should serialize and deserialize params', () => {
+      const filter: LogFilter = {
+        txHash: TxHash.random(),
+        fromBlock: 0,
+        toBlock: 100,
+        afterLog: LogId.random(),
+        contractAddress: AztecAddress.random(),
+      };
+
+      const params = { filter };
+
+      const serialized = aztecGetUnencryptedLogsSerializer.params.serialize(METHOD, params);
+      expect(serialized.method).toBe(METHOD);
+
+      const deserialized = aztecGetUnencryptedLogsSerializer.params.deserialize(METHOD, serialized);
+      expect(deserialized.filter.contractAddress?.toString()).toBe(filter.contractAddress?.toString());
+      expect(deserialized.filter.txHash?.toString()).toBe(filter.txHash?.toString());
+      expect(deserialized.filter.fromBlock).toBe(filter.fromBlock);
+      expect(deserialized.filter.toBlock).toBe(filter.toBlock);
+      expect(deserialized.filter.afterLog?.toString()).toBe(filter.afterLog?.toString());
+    });
+
+    it('should serialize and deserialize result', () => {
+      const result: GetUnencryptedLogsResponse = {
+        logs: [ExtendedUnencryptedL2Log.random()],
+        maxLogsHit: false,
+      };
+
+      const serialized = aztecGetUnencryptedLogsSerializer.result.serialize(METHOD, result);
+      expect(serialized.method).toBe(METHOD);
+
+      const deserialized = aztecGetUnencryptedLogsSerializer.result.deserialize(METHOD, serialized);
+      expect(deserialized.logs[0].toString()).toBe(result.logs[0].toString());
+      expect(deserialized.logs.length).toBe(result.logs.length);
+      expect(deserialized.maxLogsHit).toBe(result.maxLogsHit);
+    });
+  });
+
+  describe('aztec_getEncryptedEvents', () => {
+    const METHOD = 'aztec_getEncryptedEvents';
+
+    it('should serialize and deserialize params', () => {
+      const event = {
+        eventSelector: EventSelector.fromString('0x12345678'),
+        abiType: {
+          kind: 'field',
+        } as AbiType,
+        fieldNames: ['field1', 'field2'],
+      };
+      const params = {
+        event,
+        from: 0,
+        limit: 10,
+        vpks: [Point.random(), Point.random()],
+      };
+
+      const serialized = aztecGetEncryptedEventsSerializer.params.serialize(METHOD, params);
+      expect(serialized.method).toBe(METHOD);
+
+      const deserialized = aztecGetEncryptedEventsSerializer.params.deserialize(METHOD, serialized);
+      expect(deserialized.event.eventSelector.toString()).toBe(event.eventSelector.toString());
+      expect(deserialized.event.abiType).toEqual(event.abiType);
+      expect(deserialized.event.fieldNames).toEqual(event.fieldNames);
+      expect(deserialized.from).toBe(params.from);
+      expect(deserialized.limit).toBe(params.limit);
+      expect(deserialized.vpks?.map((p) => p.toString())).toEqual(params.vpks.map((p) => p.toString()));
+    });
+  });
+
+  describe('aztec_getUnencryptedEvents', () => {
+    const METHOD = 'aztec_getUnencryptedEvents';
+
+    it('should serialize and deserialize params', () => {
+      const event = {
+        eventSelector: EventSelector.fromString('0x12345678'),
+        abiType: {
+          kind: 'field',
+        } as AbiType,
+        fieldNames: ['field1', 'field2'],
+      };
+      const params = {
+        event,
+        from: 0,
+        limit: 10,
+      };
+
+      const serialized = aztecGetUnencryptedEventsSerializer.params.serialize(METHOD, params);
+      expect(serialized.method).toBe(METHOD);
+
+      const deserialized = aztecGetUnencryptedEventsSerializer.params.deserialize(METHOD, serialized);
+      expect(deserialized.event.eventSelector.toString()).toBe(event.eventSelector.toString());
+      expect(deserialized.event.abiType).toEqual(event.abiType);
+      expect(deserialized.event.fieldNames).toEqual(event.fieldNames);
+      expect(deserialized.from).toBe(params.from);
+      expect(deserialized.limit).toBe(params.limit);
+    });
+  });
+});