@aztec/wallet-sdk 0.0.1-commit.96bb3f7 → 0.0.1-commit.993d240

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/README.md +218 -355
  2. package/dest/base-wallet/base_wallet.d.ts +109 -40
  3. package/dest/base-wallet/base_wallet.d.ts.map +1 -1
  4. package/dest/base-wallet/base_wallet.js +286 -71
  5. package/dest/base-wallet/index.d.ts +3 -2
  6. package/dest/base-wallet/index.d.ts.map +1 -1
  7. package/dest/base-wallet/index.js +1 -0
  8. package/dest/base-wallet/utils.d.ts +52 -0
  9. package/dest/base-wallet/utils.d.ts.map +1 -0
  10. package/dest/base-wallet/utils.js +137 -0
  11. package/dest/crypto.d.ts +111 -27
  12. package/dest/crypto.d.ts.map +1 -1
  13. package/dest/crypto.js +307 -41
  14. package/dest/emoji_alphabet.d.ts +35 -0
  15. package/dest/emoji_alphabet.d.ts.map +1 -0
  16. package/dest/emoji_alphabet.js +299 -0
  17. package/dest/extension/handlers/background_connection_handler.d.ts +168 -0
  18. package/dest/extension/handlers/background_connection_handler.d.ts.map +1 -0
  19. package/dest/extension/handlers/background_connection_handler.js +294 -0
  20. package/dest/extension/handlers/content_script_connection_handler.d.ts +57 -0
  21. package/dest/extension/handlers/content_script_connection_handler.d.ts.map +1 -0
  22. package/dest/extension/handlers/content_script_connection_handler.js +193 -0
  23. package/dest/extension/handlers/index.d.ts +12 -0
  24. package/dest/extension/handlers/index.d.ts.map +1 -0
  25. package/dest/extension/handlers/index.js +10 -0
  26. package/dest/extension/handlers/internal_message_types.d.ts +65 -0
  27. package/dest/extension/handlers/internal_message_types.d.ts.map +1 -0
  28. package/dest/extension/handlers/internal_message_types.js +24 -0
  29. package/dest/extension/provider/extension_provider.d.ts +107 -0
  30. package/dest/extension/provider/extension_provider.d.ts.map +1 -0
  31. package/dest/extension/provider/extension_provider.js +160 -0
  32. package/dest/extension/provider/extension_wallet.d.ts +152 -0
  33. package/dest/extension/provider/extension_wallet.d.ts.map +1 -0
  34. package/dest/extension/provider/extension_wallet.js +349 -0
  35. package/dest/extension/provider/index.d.ts +3 -0
  36. package/dest/extension/provider/index.d.ts.map +1 -0
  37. package/dest/{providers/extension → extension/provider}/index.js +0 -1
  38. package/dest/iframe/handlers/iframe_connection_handler.d.ts +122 -0
  39. package/dest/iframe/handlers/iframe_connection_handler.d.ts.map +1 -0
  40. package/dest/iframe/handlers/iframe_connection_handler.js +239 -0
  41. package/dest/iframe/handlers/index.d.ts +2 -0
  42. package/dest/iframe/handlers/index.d.ts.map +1 -0
  43. package/dest/iframe/handlers/index.js +1 -0
  44. package/dest/iframe/provider/iframe_discovery.d.ts +25 -0
  45. package/dest/iframe/provider/iframe_discovery.d.ts.map +1 -0
  46. package/dest/iframe/provider/iframe_discovery.js +167 -0
  47. package/dest/iframe/provider/iframe_provider.d.ts +65 -0
  48. package/dest/iframe/provider/iframe_provider.d.ts.map +1 -0
  49. package/dest/iframe/provider/iframe_provider.js +257 -0
  50. package/dest/iframe/provider/iframe_wallet.d.ts +85 -0
  51. package/dest/iframe/provider/iframe_wallet.d.ts.map +1 -0
  52. package/dest/iframe/provider/iframe_wallet.js +269 -0
  53. package/dest/iframe/provider/index.d.ts +4 -0
  54. package/dest/iframe/provider/index.d.ts.map +1 -0
  55. package/dest/iframe/provider/index.js +3 -0
  56. package/dest/manager/index.d.ts +2 -7
  57. package/dest/manager/index.d.ts.map +1 -1
  58. package/dest/manager/index.js +0 -4
  59. package/dest/manager/types.d.ts +109 -5
  60. package/dest/manager/types.d.ts.map +1 -1
  61. package/dest/manager/types.js +17 -1
  62. package/dest/manager/wallet_manager.d.ts +50 -7
  63. package/dest/manager/wallet_manager.d.ts.map +1 -1
  64. package/dest/manager/wallet_manager.js +208 -29
  65. package/dest/types.d.ts +117 -15
  66. package/dest/types.d.ts.map +1 -1
  67. package/dest/types.js +39 -2
  68. package/package.json +22 -11
  69. package/src/base-wallet/base_wallet.ts +395 -128
  70. package/src/base-wallet/index.ts +7 -1
  71. package/src/base-wallet/utils.ts +248 -0
  72. package/src/crypto.ts +367 -47
  73. package/src/emoji_alphabet.ts +317 -0
  74. package/src/extension/handlers/background_connection_handler.ts +456 -0
  75. package/src/extension/handlers/content_script_connection_handler.ts +264 -0
  76. package/src/extension/handlers/index.ts +25 -0
  77. package/src/extension/handlers/internal_message_types.ts +71 -0
  78. package/src/extension/provider/extension_provider.ts +233 -0
  79. package/src/extension/provider/extension_wallet.ts +410 -0
  80. package/src/extension/provider/index.ts +7 -0
  81. package/src/iframe/handlers/iframe_connection_handler.ts +341 -0
  82. package/src/iframe/handlers/index.ts +7 -0
  83. package/src/iframe/provider/iframe_discovery.ts +185 -0
  84. package/src/iframe/provider/iframe_provider.ts +331 -0
  85. package/src/iframe/provider/iframe_wallet.ts +323 -0
  86. package/src/iframe/provider/index.ts +3 -0
  87. package/src/manager/index.ts +3 -9
  88. package/src/manager/types.ts +113 -4
  89. package/src/manager/wallet_manager.ts +235 -30
  90. package/src/types.ts +129 -14
  91. package/dest/providers/extension/extension_provider.d.ts +0 -17
  92. package/dest/providers/extension/extension_provider.d.ts.map +0 -1
  93. package/dest/providers/extension/extension_provider.js +0 -56
  94. package/dest/providers/extension/extension_wallet.d.ts +0 -95
  95. package/dest/providers/extension/extension_wallet.d.ts.map +0 -1
  96. package/dest/providers/extension/extension_wallet.js +0 -225
  97. package/dest/providers/extension/index.d.ts +0 -5
  98. package/dest/providers/extension/index.d.ts.map +0 -1
  99. package/src/providers/extension/extension_provider.ts +0 -72
  100. package/src/providers/extension/extension_wallet.ts +0 -275
  101. package/src/providers/extension/index.ts +0 -11
@@ -1,6 +1,37 @@
1
1
  import type { ChainInfo } from '@aztec/aztec.js/account';
2
2
  import type { Wallet } from '@aztec/aztec.js/wallet';
3
3
 
4
+ /**
5
+ * A pending connection that requires user verification before finalizing.
6
+ *
7
+ * After key exchange, both dApp and wallet compute a verification hash independently.
8
+ * The dApp should display this hash (typically as emojis) and let the user confirm
9
+ * it matches what's shown in their wallet before calling `confirm()`.
10
+ *
11
+ * This protects the dApp from connecting to a malicious wallet that might be
12
+ * intercepting the connection (MITM attack).
13
+ */
14
+ export interface PendingConnection {
15
+ /**
16
+ * The verification hash computed from the shared secret.
17
+ * Use `hashToEmoji()` to convert to a visual representation for user verification.
18
+ * The user should confirm this matches what their wallet displays.
19
+ */
20
+ verificationHash: string;
21
+
22
+ /**
23
+ * Confirms the connection after user verifies the emojis match.
24
+ * @returns The connected wallet instance
25
+ */
26
+ confirm(): Promise<Wallet>;
27
+
28
+ /**
29
+ * Cancels the pending connection.
30
+ * Call this if the user indicates the emojis don't match.
31
+ */
32
+ cancel(): void;
33
+ }
34
+
4
35
  /**
5
36
  * Configuration for extension wallets
6
37
  */
@@ -34,7 +65,12 @@ export interface WalletManagerConfig {
34
65
  /**
35
66
  * Type of wallet provider
36
67
  */
37
- export type WalletProviderType = 'extension' | 'web' | 'embedded';
68
+ export type WalletProviderType = 'extension' | 'web';
69
+
70
+ /**
71
+ * Callback type for wallet disconnect events at the provider level.
72
+ */
73
+ export type ProviderDisconnectionCallback = () => void;
38
74
 
39
75
  /**
40
76
  * A wallet provider that can connect to create a wallet instance.
@@ -52,10 +88,47 @@ export interface WalletProvider {
52
88
  /** Additional metadata */
53
89
  metadata?: Record<string, unknown>;
54
90
  /**
55
- * Connect to this wallet provider with an application ID
91
+ * Establishes a secure channel with this wallet provider.
92
+ *
93
+ * This performs the ECDH key exchange and returns a pending connection with the
94
+ * verification hash. The channel is encrypted but NOT yet verified - the dApp
95
+ * should display the hash (as emojis) to the user and let them confirm it
96
+ * matches their wallet before calling `confirm()`.
97
+ *
56
98
  * @param appId - Application identifier for the requesting dapp
99
+ * @param options - Optional provider-specific options (e.g. container element for iframe wallets)
100
+ * @returns A pending connection with verification hash and confirm/cancel methods
101
+ *
102
+ * @example
103
+ * ```typescript
104
+ * const pending = await provider.establishSecureChannel('my-app');
105
+ *
106
+ * // Show emojis to user for verification
107
+ * const emojis = hashToEmoji(pending.verificationHash);
108
+ * showDialog(`Verify these match your wallet: ${emojis}`);
109
+ *
110
+ * // User confirms emojis match
111
+ * const wallet = await pending.confirm();
112
+ * ```
113
+ */
114
+ establishSecureChannel(appId: string, options?: Record<string, unknown>): Promise<PendingConnection>;
115
+ /**
116
+ * Disconnects the current wallet and cleans up resources.
117
+ * After calling this, the wallet returned from confirm() should no longer be used.
118
+ * @returns A promise that resolves when disconnection is complete
119
+ */
120
+ disconnect(): Promise<void>;
121
+ /**
122
+ * Registers a callback to be invoked when the wallet disconnects unexpectedly.
123
+ * @param callback - Function to call when wallet disconnects
124
+ * @returns A function to unregister the callback
125
+ */
126
+ onDisconnect(callback: ProviderDisconnectionCallback): () => void;
127
+ /**
128
+ * Returns whether the provider's wallet connection has been disconnected.
129
+ * @returns true if the wallet is no longer connected
57
130
  */
58
- connect(appId: string): Promise<Wallet>;
131
+ isDisconnected(): boolean;
59
132
  }
60
133
 
61
134
  /**
@@ -64,6 +137,42 @@ export interface WalletProvider {
64
137
  export interface DiscoverWalletsOptions {
65
138
  /** Chain information to filter by */
66
139
  chainInfo: ChainInfo;
67
- /** Discovery timeout in milliseconds */
140
+ /** Application ID making the request */
141
+ appId: string;
142
+ /** Discovery timeout in milliseconds. Default: 60000 (60s) */
68
143
  timeout?: number;
144
+ /**
145
+ * Callback invoked when a wallet provider is discovered.
146
+ * Use this to show wallets to users as they approve them, rather than
147
+ * waiting for the full timeout.
148
+ */
149
+ onWalletDiscovered?: (provider: WalletProvider) => void;
150
+ }
151
+
152
+ /**
153
+ * A cancellable discovery session.
154
+ *
155
+ * Returned by `WalletManager.getAvailableWallets()` to allow consumers to
156
+ * cancel discovery when no longer needed (e.g., network changes, user navigates away).
157
+ *
158
+ * @example
159
+ * ```typescript
160
+ * const discovery = WalletManager.configure({...}).getAvailableWallets({...});
161
+ *
162
+ * // Iterate over discovered wallets
163
+ * for await (const wallet of discovery.wallets) {
164
+ * console.log(`Found: ${wallet.name}`);
165
+ * }
166
+ *
167
+ * // Cancel discovery when no longer needed
168
+ * discovery.cancel();
169
+ * ```
170
+ */
171
+ export interface DiscoverySession {
172
+ /** Async iterator that yields wallet providers as they're discovered */
173
+ wallets: AsyncIterable<WalletProvider>;
174
+ /** Promise that resolves when discovery completes or is cancelled */
175
+ done: Promise<void>;
176
+ /** Cancel discovery immediately and clean up resources */
177
+ cancel: () => void;
69
178
  }
@@ -1,8 +1,49 @@
1
- import { ExtensionProvider, ExtensionWallet } from '../providers/extension/index.js';
2
- import type { DiscoverWalletsOptions, ExtensionWalletConfig, WalletManagerConfig, WalletProvider } from './types.js';
1
+ import type { ChainInfo } from '@aztec/aztec.js/account';
2
+ import { promiseWithResolvers } from '@aztec/foundation/promise';
3
+
4
+ import { type DiscoveredWallet, ExtensionProvider, ExtensionWallet } from '../extension/provider/index.js';
5
+ import { discoverWebWallets } from '../iframe/provider/iframe_discovery.js';
6
+ import { WalletMessageType } from '../types.js';
7
+ import type {
8
+ DiscoverWalletsOptions,
9
+ DiscoverySession,
10
+ ExtensionWalletConfig,
11
+ PendingConnection,
12
+ ProviderDisconnectionCallback,
13
+ WalletManagerConfig,
14
+ WalletProvider,
15
+ } from './types.js';
3
16
 
4
17
  /**
5
- * Manager for wallet discovery, configuration, and connection
18
+ * Manager for wallet discovery, configuration, and connection.
19
+ *
20
+ * This is the main entry point for dApps to discover and connect to wallets.
21
+ *
22
+ * @example Basic usage with async iterator
23
+ * ```typescript
24
+ * const discovery = WalletManager.configure({ extensions: { enabled: true } })
25
+ * .getAvailableWallets({ chainInfo, appId: 'my-app' });
26
+ *
27
+ * // Iterate over discovered wallets
28
+ * for await (const provider of discovery.wallets) {
29
+ * console.log(`Found wallet: ${provider.name}`);
30
+ * }
31
+ *
32
+ * // Or cancel early when done
33
+ * discovery.cancel();
34
+ * ```
35
+ *
36
+ * @example With callback for discovered wallets
37
+ * ```typescript
38
+ * const discovery = manager.getAvailableWallets({
39
+ * chainInfo,
40
+ * appId: 'my-app',
41
+ * onWalletDiscovered: (provider) => console.log(`Found: ${provider.name}`),
42
+ * });
43
+ *
44
+ * // Wait for discovery to complete or cancel it
45
+ * await discovery.done;
46
+ * ```
6
47
  */
7
48
  export class WalletManager {
8
49
  private config: WalletManagerConfig = {
@@ -27,41 +68,208 @@ export class WalletManager {
27
68
 
28
69
  /**
29
70
  * Discovers all available wallets for a given chain and version.
30
- * Only returns wallets that support the requested chain and version.
31
- * @param options - Discovery options including chain info and timeout
32
- * @returns Array of wallet providers with baked-in chain info
71
+ *
72
+ * Returns a `DiscoverySession` with:
73
+ * - `wallets`: AsyncIterable to iterate over discovered wallets
74
+ * - `done`: Promise that resolves when discovery completes or is cancelled
75
+ * - `cancel()`: Function to stop discovery immediately
76
+ *
77
+ * If `onWalletDiscovered` callback is provided, wallets are also streamed via callback.
78
+ *
79
+ * @param options - Discovery options including chain info, appId, and timeout
80
+ * @returns A cancellable discovery session
33
81
  */
34
- async getAvailableWallets(options: DiscoverWalletsOptions): Promise<WalletProvider[]> {
35
- const providers: WalletProvider[] = [];
36
- const { chainInfo } = options;
82
+ getAvailableWallets(options: DiscoverWalletsOptions): DiscoverySession {
83
+ const { chainInfo, appId } = options;
84
+ const abortController = new AbortController();
85
+
86
+ const pendingProviders: WalletProvider[] = [];
87
+ let pendingResolve: ((result: IteratorResult<WalletProvider>) => void) | null = null;
88
+ let completed = false;
89
+
90
+ const { promise: donePromise, resolve: resolveDone } = promiseWithResolvers<void>();
91
+
92
+ const pendingSources = new Set<string>();
93
+
94
+ const emit = (provider: WalletProvider) => {
95
+ options.onWalletDiscovered?.(provider);
96
+
97
+ if (pendingResolve) {
98
+ const resolve = pendingResolve;
99
+ pendingResolve = null;
100
+ resolve({ value: provider, done: false });
101
+ } else {
102
+ pendingProviders.push(provider);
103
+ }
104
+ };
105
+
106
+ const markComplete = () => {
107
+ completed = true;
108
+ resolveDone();
109
+ if (pendingResolve) {
110
+ const resolve = pendingResolve;
111
+ pendingResolve = null;
112
+ resolve({ value: undefined, done: true });
113
+ }
114
+ };
115
+
116
+ const sourceComplete = (source: string) => {
117
+ pendingSources.delete(source);
118
+ if (pendingSources.size === 0) {
119
+ markComplete();
120
+ }
121
+ };
37
122
 
38
- // Discover extension wallets
39
123
  if (this.config.extensions?.enabled) {
40
- const extensions = await ExtensionProvider.discoverExtensions(chainInfo, options.timeout);
124
+ pendingSources.add('extensions');
41
125
  const extensionConfig = this.config.extensions;
42
126
 
43
- for (const ext of extensions) {
44
- // Apply allow/block lists
45
- if (!this.isExtensionAllowed(ext.id, extensionConfig)) {
46
- continue;
127
+ void ExtensionProvider.discoverWallets(chainInfo, {
128
+ appId,
129
+ timeout: options.timeout,
130
+ signal: abortController.signal,
131
+ onWalletDiscovered: discoveredWallet => {
132
+ const provider = this.createProviderFromDiscoveredWallet(discoveredWallet, chainInfo, extensionConfig);
133
+ if (provider) {
134
+ emit(provider);
135
+ }
136
+ },
137
+ }).then(() => sourceComplete('extensions'));
138
+ }
139
+
140
+ if (this.config.webWallets?.urls && this.config.webWallets.urls.length > 0) {
141
+ pendingSources.add('webWallets');
142
+ const webSession = discoverWebWallets(this.config.webWallets.urls, chainInfo);
143
+
144
+ // Forward discovered web wallets into the shared iterator
145
+ void (async () => {
146
+ try {
147
+ for await (const provider of webSession.wallets) {
148
+ if (abortController.signal.aborted) {
149
+ break;
150
+ }
151
+ emit(provider);
152
+ }
153
+ } finally {
154
+ sourceComplete('webWallets');
47
155
  }
156
+ })();
157
+
158
+ abortController.signal.addEventListener('abort', () => webSession.cancel(), { once: true });
159
+ }
160
+
161
+ if (pendingSources.size === 0) {
162
+ markComplete();
163
+ }
48
164
 
49
- providers.push({
50
- id: ext.id,
51
- type: 'extension',
52
- name: ext.name,
53
- icon: ext.icon,
54
- metadata: {
55
- version: ext.version,
165
+ const wallets: AsyncIterable<WalletProvider> = {
166
+ // eslint-disable-next-line jsdoc/require-jsdoc
167
+ [Symbol.asyncIterator](): AsyncIterator<WalletProvider> {
168
+ return {
169
+ // eslint-disable-next-line jsdoc/require-jsdoc
170
+ next(): Promise<IteratorResult<WalletProvider>> {
171
+ if (pendingProviders.length > 0) {
172
+ return Promise.resolve({ value: pendingProviders.shift()!, done: false });
173
+ }
174
+
175
+ if (completed) {
176
+ return Promise.resolve({ value: undefined, done: true });
177
+ }
178
+
179
+ return new Promise(resolve => {
180
+ pendingResolve = resolve;
181
+ });
56
182
  },
57
- connect: (appId: string) => ExtensionWallet.create(ext, chainInfo, appId),
58
- });
59
- }
183
+ };
184
+ },
185
+ };
186
+
187
+ return {
188
+ wallets,
189
+ done: donePromise,
190
+ cancel: () => abortController.abort(),
191
+ };
192
+ }
193
+
194
+ /**
195
+ * Creates a WalletProvider from a discovered wallet.
196
+ * Returns null if the wallet is not allowed by config.
197
+ * @param discoveredWallet - The discovered wallet from extension discovery.
198
+ * @param chainInfo - Network information.
199
+ * @param extensionConfig - Extension wallet configuration.
200
+ */
201
+ private createProviderFromDiscoveredWallet(
202
+ discoveredWallet: DiscoveredWallet,
203
+ chainInfo: ChainInfo,
204
+ extensionConfig: ExtensionWalletConfig,
205
+ ): WalletProvider | null {
206
+ const { info } = discoveredWallet;
207
+
208
+ if (!this.isExtensionAllowed(info.id, extensionConfig)) {
209
+ return null;
60
210
  }
61
211
 
62
- // TODO: Add web wallet discovery when implemented
212
+ let extensionWallet: ExtensionWallet | null = null;
213
+
214
+ const provider: WalletProvider = {
215
+ id: info.id,
216
+ type: 'extension',
217
+ name: info.name,
218
+ icon: info.icon,
219
+ metadata: {
220
+ version: info.version,
221
+ },
222
+ establishSecureChannel: async (connectAppId: string): Promise<PendingConnection> => {
223
+ const connection = await discoveredWallet.establishSecureChannel();
224
+
225
+ provider.metadata = {
226
+ ...provider.metadata,
227
+ verificationHash: connection.info.verificationHash,
228
+ };
229
+
230
+ return {
231
+ verificationHash: connection.info.verificationHash!,
232
+ confirm: () => {
233
+ extensionWallet = ExtensionWallet.create(
234
+ connection.info.id,
235
+ connection.port,
236
+ connection.sharedKey,
237
+ chainInfo,
238
+ connectAppId,
239
+ );
240
+ return Promise.resolve(extensionWallet.asWallet());
241
+ },
242
+ cancel: () => {
243
+ // Send disconnect to terminate the session on the extension side
244
+ // but keep the port open so we can retry key exchange
245
+ connection.port.postMessage({
246
+ type: WalletMessageType.DISCONNECT,
247
+ requestId: discoveredWallet.requestId,
248
+ });
249
+ },
250
+ };
251
+ },
252
+ disconnect: async () => {
253
+ if (extensionWallet) {
254
+ await extensionWallet.disconnect();
255
+ extensionWallet = null;
256
+ }
257
+ },
258
+ onDisconnect: (callback: ProviderDisconnectionCallback) => {
259
+ if (extensionWallet) {
260
+ return extensionWallet.onDisconnect(callback);
261
+ }
262
+ return () => {};
263
+ },
264
+ isDisconnected: () => {
265
+ if (extensionWallet) {
266
+ return extensionWallet.isDisconnected();
267
+ }
268
+ return true;
269
+ },
270
+ };
63
271
 
64
- return providers;
272
+ return provider;
65
273
  }
66
274
 
67
275
  /**
@@ -70,17 +278,14 @@ export class WalletManager {
70
278
  * @param config - Extension wallet configuration containing allow/block lists
71
279
  */
72
280
  private isExtensionAllowed(extensionId: string, config: ExtensionWalletConfig): boolean {
73
- // Check block list first
74
281
  if (config.blockList && config.blockList.includes(extensionId)) {
75
282
  return false;
76
283
  }
77
284
 
78
- // If allow list exists, extension must be in it
79
285
  if (config.allowList && config.allowList.length > 0) {
80
286
  return config.allowList.includes(extensionId);
81
287
  }
82
288
 
83
- // If no allow list, extension is allowed (unless blocked)
84
289
  return true;
85
290
  }
86
291
  }
package/src/types.ts CHANGED
@@ -3,7 +3,40 @@ import type { ChainInfo } from '@aztec/aztec.js/account';
3
3
  import type { ExportedPublicKey } from './crypto.js';
4
4
 
5
5
  /**
6
- * Information about an installed Aztec wallet
6
+ * Message types for wallet SDK communication.
7
+ * All types are prefixed with 'aztec-wallet-' for namespacing.
8
+ */
9
+ export enum WalletMessageType {
10
+ /** Discovery request to find installed wallets */
11
+ DISCOVERY = 'aztec-wallet-discovery',
12
+ /** Discovery response from a wallet */
13
+ DISCOVERY_RESPONSE = 'aztec-wallet-discovery-response',
14
+ /** Disconnect message (unencrypted control message, bidirectional) */
15
+ DISCONNECT = 'aztec-wallet-disconnect',
16
+ /** Key exchange request sent over MessageChannel */
17
+ KEY_EXCHANGE_REQUEST = 'aztec-wallet-key-exchange-request',
18
+ /** Key exchange response sent over MessageChannel */
19
+ KEY_EXCHANGE_RESPONSE = 'aztec-wallet-key-exchange-response',
20
+ /** Wallet ready signal */
21
+ WALLET_READY = 'aztec-wallet-ready',
22
+ /** Encrypted wallet message wrapper */
23
+ SECURE_MESSAGE = 'aztec-wallet-secure-message',
24
+ /** Encrypted wallet response wrapper */
25
+ SECURE_RESPONSE = 'aztec-wallet-secure-response',
26
+ /** Session disconnected notification */
27
+ SESSION_DISCONNECTED = 'aztec-wallet-session-disconnected',
28
+ /** Liveness probe sent by the dApp while a request is in flight */
29
+ PING = 'aztec-wallet-ping',
30
+ /** Liveness response from the wallet. Any inbound message (including a regular
31
+ * encrypted response) is treated as proof of liveness, so a missing PONG alone
32
+ * never trips disconnect — the dApp also resets its liveness timer on traffic.
33
+ */
34
+ PONG = 'aztec-wallet-pong',
35
+ }
36
+
37
+ /**
38
+ * Information about an installed Aztec wallet.
39
+ * Used during discovery phase before key exchange.
7
40
  */
8
41
  export interface WalletInfo {
9
42
  /** Unique identifier for the wallet */
@@ -14,8 +47,21 @@ export interface WalletInfo {
14
47
  icon?: string;
15
48
  /** Wallet version */
16
49
  version: string;
50
+ }
51
+
52
+ /**
53
+ * Full information about a connected Aztec wallet including crypto material.
54
+ * Available after key exchange completes.
55
+ */
56
+ export interface ConnectedWalletInfo extends WalletInfo {
17
57
  /** Wallet's ECDH public key for secure channel establishment */
18
58
  publicKey: ExportedPublicKey;
59
+ /**
60
+ * Verification hash for verification.
61
+ * Both dApp and wallet independently compute this from the ECDH shared secret.
62
+ * Use {@link hashToEmoji} to convert to a visual representation for user verification.
63
+ */
64
+ verificationHash?: string;
19
65
  }
20
66
 
21
67
  /**
@@ -51,39 +97,108 @@ export interface WalletResponse {
51
97
  }
52
98
 
53
99
  /**
54
- * Discovery message for finding installed wallets (public, unencrypted)
100
+ * Discovery message for finding installed wallets (public, unencrypted).
55
101
  */
56
102
  export interface DiscoveryRequest {
57
103
  /** Message type for discovery */
58
- type: 'aztec-wallet-discovery';
104
+ type: WalletMessageType.DISCOVERY;
59
105
  /** Request ID */
60
106
  requestId: string;
107
+ /** Application ID making the request */
108
+ appId: string;
61
109
  /** Chain information to check if wallet supports this network */
62
110
  chainInfo: ChainInfo;
63
111
  }
64
112
 
65
113
  /**
66
- * Discovery response from a wallet (public, unencrypted)
114
+ * Discovery response from a wallet (public, unencrypted).
67
115
  */
68
116
  export interface DiscoveryResponse {
69
117
  /** Message type for discovery response */
70
- type: 'aztec-wallet-discovery-response';
118
+ type: WalletMessageType.DISCOVERY_RESPONSE;
71
119
  /** Request ID matching the discovery request */
72
120
  requestId: string;
73
- /** Wallet information */
121
+ /** Basic wallet information */
74
122
  walletInfo: WalletInfo;
75
123
  }
76
124
 
77
125
  /**
78
- * Connection request to establish secure channel
126
+ * Key exchange request sent over MessageChannel after discovery approval.
79
127
  */
80
- export interface ConnectRequest {
81
- /** Message type for connection */
82
- type: 'aztec-wallet-connect';
83
- /** Target wallet ID */
84
- walletId: string;
85
- /** Application ID */
86
- appId: string;
128
+ export interface KeyExchangeRequest {
129
+ /** Message type */
130
+ type: WalletMessageType.KEY_EXCHANGE_REQUEST;
131
+ /** Request ID matching the discovery request */
132
+ requestId: string;
87
133
  /** dApp's ECDH public key for deriving shared secret */
88
134
  publicKey: ExportedPublicKey;
89
135
  }
136
+
137
+ /**
138
+ * Key exchange response sent over MessageChannel.
139
+ */
140
+ export interface KeyExchangeResponse {
141
+ /** Message type */
142
+ type: WalletMessageType.KEY_EXCHANGE_RESPONSE;
143
+ /** Request ID matching the discovery request */
144
+ requestId: string;
145
+ /** Wallet's ECDH public key for deriving shared secret */
146
+ publicKey: ExportedPublicKey;
147
+ }
148
+
149
+ /**
150
+ * Callback invoked when a wallet connection is disconnected.
151
+ */
152
+ export type DisconnectCallback = () => void;
153
+
154
+ /**
155
+ * Default heartbeat tuning shared by both transports.
156
+ *
157
+ * - `intervalMs`: how often the dApp sends PING probes while a request is in flight.
158
+ * - `deadAfterMs`: how long the channel can stay silent (no PONG, no encrypted
159
+ * response, no DISCONNECT) before the dApp declares the wallet unreachable
160
+ * and rejects all in-flight requests. Generous enough that long-running
161
+ * operations (proveTx, sendTx) on legacy wallets that don't reply to PING
162
+ * still succeed — any inbound traffic resets the timer.
163
+ */
164
+ export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
165
+ export const DEFAULT_HEARTBEAT_DEAD_AFTER_MS = 300_000;
166
+
167
+ /** Override knobs for the heartbeat — mostly useful for tests. */
168
+ export interface HeartbeatOptions {
169
+ /** How often to send PING probes while a request is in flight (ms). */
170
+ intervalMs?: number;
171
+ /** Idle ceiling before declaring disconnect (ms). */
172
+ deadAfterMs?: number;
173
+ }
174
+
175
+ /**
176
+ * Minimal logger surface used by the wallet SDK.
177
+ *
178
+ * Defined locally so that wallet hosts (browser extensions, iframe wallet pages)
179
+ * can pass a simple `console`-backed logger without pulling in the full
180
+ * `@aztec/foundation` logging runtime, which is non-trivial to bundle in those
181
+ * contexts. Structurally compatible with `Logger` from `@aztec/foundation/log`,
182
+ * so dApp-side callers can pass that type directly.
183
+ */
184
+ export interface WalletSdkLogger {
185
+ /** Diagnostic messages — typically discarded in production. */
186
+ debug: (message: string, data?: unknown) => void;
187
+ /** Informational messages — significant lifecycle events. */
188
+ info: (message: string, data?: unknown) => void;
189
+ /** Recoverable problems — channel decryption failure, missed heartbeats, etc. */
190
+ warn: (message: string, data?: unknown) => void;
191
+ /** Errors that prevent normal operation. */
192
+ error: (message: string, errOrData?: unknown, data?: unknown) => void;
193
+ }
194
+
195
+ /**
196
+ * No-op logger used as the default when callers don't provide one. Discards all
197
+ * messages — wallet hosts that want diagnostics should pass their own logger.
198
+ */
199
+ export const NOOP_LOGGER: WalletSdkLogger = {
200
+ debug: () => {},
201
+ info: () => {},
202
+ warn: () => {},
203
+ error: () => {},
204
+ };
@@ -1,17 +0,0 @@
1
- import type { ChainInfo } from '@aztec/aztec.js/account';
2
- import type { WalletInfo } from '../../types.js';
3
- /**
4
- * Provider for discovering and managing Aztec wallet extensions
5
- */
6
- export declare class ExtensionProvider {
7
- private static discoveredExtensions;
8
- private static discoveryInProgress;
9
- /**
10
- * Discovers all installed Aztec wallet extensions
11
- * @param chainInfo - Chain information to check if extensions support this network
12
- * @param timeout - How long to wait for extensions to respond (ms)
13
- * @returns Array of discovered extension information
14
- */
15
- static discoverExtensions(chainInfo: ChainInfo, timeout?: number): Promise<WalletInfo[]>;
16
- }
17
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXh0ZW5zaW9uX3Byb3ZpZGVyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvcHJvdmlkZXJzL2V4dGVuc2lvbi9leHRlbnNpb25fcHJvdmlkZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFJekQsT0FBTyxLQUFLLEVBQXVDLFVBQVUsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBRXRGOztHQUVHO0FBQ0gscUJBQWEsaUJBQWlCO0lBQzVCLE9BQU8sQ0FBQyxNQUFNLENBQUMsb0JBQW9CLENBQXNDO0lBQ3pFLE9BQU8sQ0FBQyxNQUFNLENBQUMsbUJBQW1CLENBQVM7SUFFM0M7Ozs7O09BS0c7SUFDSCxPQUFhLGtCQUFrQixDQUFDLFNBQVMsRUFBRSxTQUFTLEVBQUUsT0FBTyxHQUFFLE1BQWEsR0FBRyxPQUFPLENBQUMsVUFBVSxFQUFFLENBQUMsQ0FtRG5HO0NBQ0YifQ==
@@ -1 +0,0 @@
1
- {"version":3,"file":"extension_provider.d.ts","sourceRoot":"","sources":["../../../src/providers/extension/extension_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAIzD,OAAO,KAAK,EAAuC,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEtF;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAsC;IACzE,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAS;IAE3C;;;;;OAKG;IACH,OAAa,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAmDnG;CACF"}