@aztec/wallet-sdk 3.0.0-nightly.20251122

package/src/manager/wallet_manager.ts

@@ -0,0 +1,86 @@
+import { ExtensionProvider, ExtensionWallet } from '../providers/extension/index.js';
+import type { DiscoverWalletsOptions, ExtensionWalletConfig, WalletManagerConfig, WalletProvider } from './types.js';
+
+/**
+ * Manager for wallet discovery, configuration, and connection
+ */
+export class WalletManager {
+  private config: WalletManagerConfig = {
+    extensions: { enabled: true },
+    webWallets: { urls: [] },
+  };
+
+  private constructor() {}
+
+  /**
+   * Configures the WalletManager with provider settings
+   * @param config - Configuration options for wallet providers
+   */
+  static configure(config: WalletManagerConfig): WalletManager {
+    const instance = new WalletManager();
+    instance.config = {
+      extensions: config.extensions ?? { enabled: true },
+      webWallets: config.webWallets ?? { urls: [] },
+    };
+    return instance;
+  }
+
+  /**
+   * Discovers all available wallets for a given chain and version.
+   * Only returns wallets that support the requested chain and version.
+   * @param options - Discovery options including chain info and timeout
+   * @returns Array of wallet providers with baked-in chain info
+   */
+  async getAvailableWallets(options: DiscoverWalletsOptions): Promise<WalletProvider[]> {
+    const providers: WalletProvider[] = [];
+    const { chainInfo } = options;
+
+    // Discover extension wallets
+    if (this.config.extensions?.enabled) {
+      const extensions = await ExtensionProvider.discoverExtensions(chainInfo, options.timeout);
+      const extensionConfig = this.config.extensions;
+
+      for (const ext of extensions) {
+        // Apply allow/block lists
+        if (!this.isExtensionAllowed(ext.id, extensionConfig)) {
+          continue;
+        }
+
+        providers.push({
+          id: ext.id,
+          type: 'extension',
+          name: ext.name,
+          icon: ext.icon,
+          metadata: {
+            version: ext.version,
+          },
+          connect: (appId: string) => Promise.resolve(ExtensionWallet.create(chainInfo, appId, ext.id)),
+        });
+      }
+    }
+
+    // TODO: Add web wallet discovery when implemented
+
+    return providers;
+  }
+
+  /**
+   * Checks if an extension is allowed based on allow/block lists
+   * @param extensionId - The extension ID to check
+   * @param config - Extension wallet configuration containing allow/block lists
+   */
+  private isExtensionAllowed(extensionId: string, config: ExtensionWalletConfig): boolean {
+    // Check block list first
+    if (config.blockList && config.blockList.includes(extensionId)) {
+      return false;
+    }
+
+    // If allow list exists, extension must be in it
+    if (config.allowList && config.allowList.length > 0) {
+      return config.allowList.includes(extensionId);
+    }
+
+    // If no allow list, extension is allowed (unless blocked)
+    return true;
+  }
+}

package/src/providers/extension/extension_provider.ts

@@ -0,0 +1,72 @@
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+import { promiseWithResolvers } from '@aztec/foundation/promise';
+
+import type { DiscoveryRequest, DiscoveryResponse, WalletInfo } from '../types.js';
+
+/**
+ * Provider for discovering and managing Aztec wallet extensions
+ */
+export class ExtensionProvider {
+  private static discoveredExtensions: Map<string, WalletInfo> = new Map();
+  private static discoveryInProgress = false;
+
+  /**
+   * Discovers all installed Aztec wallet extensions
+   * @param chainInfo - Chain information to check if extensions support this network
+   * @param timeout - How long to wait for extensions to respond (ms)
+   * @returns Array of discovered extension information
+   */
+  static async discoverExtensions(chainInfo: ChainInfo, timeout: number = 1000): Promise<WalletInfo[]> {
+    // If discovery is in progress, wait for it to complete
+    if (this.discoveryInProgress) {
+      await new Promise(resolve => setTimeout(resolve, timeout));
+      return Array.from(this.discoveredExtensions.values());
+    }
+
+    this.discoveryInProgress = true;
+    this.discoveredExtensions.clear();
+
+    const { promise, resolve } = promiseWithResolvers<WalletInfo[]>();
+    const requestId = globalThis.crypto.randomUUID();
+    const responses: WalletInfo[] = [];
+
+    // Set up listener for discovery responses
+    const handleMessage = (event: MessageEvent) => {
+      if (event.source !== window) {
+        return;
+      }
+
+      let data: DiscoveryResponse;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+
+      if (data.type === 'aztec-wallet-discovery-response' && data.requestId === requestId) {
+        responses.push(data.walletInfo);
+        this.discoveredExtensions.set(data.walletInfo.id, data.walletInfo);
+      }
+    };
+
+    window.addEventListener('message', handleMessage);
+
+    // Send discovery message
+    const discoveryMessage: DiscoveryRequest = {
+      type: 'aztec-wallet-discovery',
+      requestId,
+      chainInfo,
+    };
+    window.postMessage(jsonStringify(discoveryMessage), '*');
+
+    // Wait for responses
+    setTimeout(() => {
+      window.removeEventListener('message', handleMessage);
+      this.discoveryInProgress = false;
+      resolve(responses);
+    }, timeout);
+
+    return promise;
+  }
+}

package/src/providers/extension/extension_wallet.ts

@@ -0,0 +1,124 @@
+import type { ChainInfo } from '@aztec/aztec.js/account';
+import { type Wallet, WalletSchema } from '@aztec/aztec.js/wallet';
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundation/promise';
+import { schemaHasMethod } from '@aztec/foundation/schemas';
+import type { FunctionsOf } from '@aztec/foundation/types';
+
+import type { WalletMessage, WalletResponse } from '../types.js';
+
+/**
+ * Message payload for posting to extension
+ */
+type WalletMethodCall = {
+  /**
+   * The wallet method name to invoke
+   */
+  type: keyof FunctionsOf<Wallet>;
+  /**
+   * Arguments to pass to the wallet method
+   */
+  args: unknown[];
+};
+
+/**
+ * A wallet implementation that communicates with browser extension wallets
+ * Supports multiple extensions by targeting specific extension IDs
+ */
+export class ExtensionWallet {
+  private inFlight = new Map<string, PromiseWithResolvers<unknown>>();
+
+  private constructor(
+    private chainInfo: ChainInfo,
+    private appId: string,
+    private extensionId: string,
+  ) {}
+
+  /**
+   * Creates an ExtensionWallet instance that proxies wallet calls to a browser extension
+   * @param chainInfo - The chain information (chainId and version)
+   * @param appId - Application identifier for the requesting dapp
+   * @param extensionId - Specific extension ID to communicate with
+   * @returns A Proxy object that implements the Wallet interface
+   */
+  static create(chainInfo: ChainInfo, appId: string, extensionId: string): Wallet {
+    const wallet = new ExtensionWallet(chainInfo, appId, extensionId);
+
+    // Set up message listener for responses from extensions
+    window.addEventListener('message', event => {
+      if (event.source !== window) {
+        return;
+      }
+
+      let data: WalletResponse;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+
+      // Ignore request messages (only process responses)
+      if ('type' in data) {
+        return;
+      }
+
+      const { messageId, result, error, walletId: responseWalletId } = data;
+
+      if (!messageId || !responseWalletId) {
+        return;
+      }
+
+      if (wallet.extensionId !== responseWalletId) {
+        return;
+      }
+
+      if (!wallet.inFlight.has(messageId)) {
+        return;
+      }
+
+      const { resolve, reject } = wallet.inFlight.get(messageId)!;
+
+      if (error) {
+        reject(new Error(jsonStringify(error)));
+      } else {
+        resolve(result);
+      }
+      wallet.inFlight.delete(messageId);
+    });
+
+    // Create a Proxy that intercepts wallet method calls and forwards them to the extension
+    return new Proxy(wallet, {
+      get: (target, prop) => {
+        if (schemaHasMethod(WalletSchema, prop.toString())) {
+          return async (...args: unknown[]) => {
+            const result = await target.postMessage({
+              type: prop.toString() as keyof FunctionsOf<Wallet>,
+              args,
+            });
+            return WalletSchema[prop.toString() as keyof typeof WalletSchema].returnType().parseAsync(result);
+          };
+        } else {
+          return target[prop as keyof ExtensionWallet];
+        }
+      },
+    }) as unknown as Wallet;
+  }
+
+  private postMessage(call: WalletMethodCall): Promise<unknown> {
+    const messageId = globalThis.crypto.randomUUID();
+    const message: WalletMessage = {
+      type: call.type,
+      args: call.args,
+      messageId,
+      chainInfo: this.chainInfo,
+      appId: this.appId,
+      walletId: this.extensionId,
+    };
+
+    window.postMessage(jsonStringify(message), '*');
+
+    const { promise, resolve, reject } = promiseWithResolvers<unknown>();
+    this.inFlight.set(messageId, { promise, resolve, reject });
+    return promise;
+  }
+}

package/src/providers/extension/index.ts

@@ -0,0 +1,3 @@
+export { ExtensionWallet } from './extension_wallet.js';
+export { ExtensionProvider } from './extension_provider.js';
+export type { WalletInfo, WalletMessage, WalletResponse, DiscoveryRequest, DiscoveryResponse } from '../types.js';

package/src/providers/types.ts

@@ -0,0 +1,71 @@
+import type { ChainInfo } from '@aztec/aztec.js/account';
+
+/**
+ * Information about an installed Aztec wallet wallet
+ */
+export interface WalletInfo {
+  /** Unique identifier for the wallet */
+  id: string;
+  /** Display name of the wallet */
+  name: string;
+  /** URL to the wallet's icon */
+  icon?: string;
+  /** Wallet version */
+  version: string;
+}
+
+/**
+ * Message format for wallet communication
+ */
+export interface WalletMessage {
+  /** Unique message ID for tracking responses */
+  messageId: string;
+  /** The wallet method to call */
+  type: string;
+  /** Arguments for the method */
+  args: unknown[];
+  /** Chain information */
+  chainInfo: ChainInfo;
+  /** Application ID making the request */
+  appId: string;
+  /** Wallet ID to target a specific wallet */
+  walletId: string;
+}
+
+/**
+ * Response message from wallet
+ */
+export interface WalletResponse {
+  /** Message ID matching the request */
+  messageId: string;
+  /** Result data (if successful) */
+  result?: unknown;
+  /** Error data (if failed) */
+  error?: unknown;
+  /** Wallet ID that sent the response */
+  walletId: string;
+}
+
+/**
+ * Discovery message for finding installed wallets
+ */
+export interface DiscoveryRequest {
+  /** Message type for discovery */
+  type: 'aztec-wallet-discovery';
+  /** Request ID */
+  requestId: string;
+  /** Chain information to check if wallet supports this network */
+  chainInfo: ChainInfo;
+}
+
+/**
+ * Discovery response from an wallet
+ */
+export interface DiscoveryResponse {
+  /** Message type for discovery response */
+  type: 'aztec-wallet-discovery-response';
+  /** Request ID matching the discovery request */
+  requestId: string;
+  /** Wallet information */
+  walletInfo: WalletInfo;
+}