@miden-sdk/react 0.13.0 → 0.13.2

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.
package/CLAUDE.md ADDED
@@ -0,0 +1,398 @@
1
+ # Miden React SDK - Usage Guide
2
+
3
+ ## Installation
4
+
5
+ ```bash
6
+ npm install @miden-sdk/react @miden-sdk/miden-sdk
7
+ # or
8
+ yarn add @miden-sdk/react @miden-sdk/miden-sdk
9
+ ```
10
+
11
+ ## Getting Started
12
+
13
+ ```tsx
14
+ import { MidenProvider } from "@miden-sdk/react";
15
+
16
+ function App() {
17
+ return (
18
+ <MidenProvider config={{ rpcUrl: "testnet" }}>
19
+ <YourApp />
20
+ </MidenProvider>
21
+ );
22
+ }
23
+ ```
24
+
25
+ ## Configuration
26
+
27
+ ```tsx
28
+ <MidenProvider
29
+ config={{
30
+ rpcUrl: "testnet", // "devnet" | "testnet" | "localhost" | custom URL
31
+ prover: "testnet", // "local" | "devnet" | "testnet" | custom URL
32
+ autoSyncInterval: 15000, // ms, set to 0 to disable
33
+ noteTransportUrl: "...", // optional: for private note delivery
34
+ }}
35
+ loadingComponent={<Loading />} // shown during WASM init
36
+ errorComponent={<Error />} // shown on init failure
37
+ >
38
+ ```
39
+
40
+ | Network | Use When |
41
+ |---------|----------|
42
+ | `devnet` | Development, testing with fake tokens |
43
+ | `testnet` | Pre-production testing |
44
+ | `localhost` | Local node at `http://localhost:57291` |
45
+
46
+ ## Reading Data (Query Hooks)
47
+
48
+ All query hooks return `{ data, isLoading, error, refetch }`.
49
+
50
+ ### List Accounts
51
+ ```tsx
52
+ const { data: accounts, isLoading } = useAccounts();
53
+
54
+ // accounts.wallets - regular accounts
55
+ // accounts.faucets - token faucets
56
+ // accounts.all - everything
57
+ ```
58
+
59
+ ### Get Account Details
60
+ ```tsx
61
+ const { data: account } = useAccount(accountId);
62
+
63
+ // account.id, account.nonce, account.bech32id()
64
+ // account.balance(faucetId) - get token balance
65
+ ```
66
+
67
+ ### Get Notes
68
+ ```tsx
69
+ const { data: notes } = useNotes();
70
+
71
+ // notes.input - incoming notes
72
+ // notes.consumable - ready to claim
73
+ ```
74
+
75
+ ### Check Sync Status
76
+ ```tsx
77
+ const { syncHeight, isSyncing, sync } = useSyncState();
78
+
79
+ // Manual sync
80
+ await sync();
81
+ ```
82
+
83
+ ### Get Token Metadata
84
+ ```tsx
85
+ const { data: metadata } = useAssetMetadata(faucetId);
86
+ // metadata.symbol, metadata.decimals
87
+ ```
88
+
89
+ ## Writing Data (Mutation Hooks)
90
+
91
+ All mutation hooks return `{ mutate, data, isLoading, stage, error, reset }`.
92
+
93
+ **Transaction stages:** `idle` → `executing` → `proving` → `submitting` → `complete`
94
+
95
+ ### Create Wallet
96
+ ```tsx
97
+ const { mutate: createWallet, isLoading } = useCreateWallet();
98
+
99
+ const account = await createWallet({
100
+ storageMode: "private", // "private" | "public" | "network"
101
+ });
102
+ ```
103
+
104
+ ### Send Tokens
105
+ ```tsx
106
+ const { mutate: send, stage } = useSend();
107
+
108
+ await send({
109
+ from: senderAccountId,
110
+ to: recipientAccountId,
111
+ faucetId: tokenFaucetId,
112
+ amount: 1000n,
113
+ noteType: "private", // "private" | "public"
114
+ });
115
+ ```
116
+
117
+ ### Send to Multiple Recipients
118
+ ```tsx
119
+ const { mutate: multiSend } = useMultiSend();
120
+
121
+ await multiSend({
122
+ from: senderAccountId,
123
+ outputs: [
124
+ { to: recipient1, faucetId, amount: 500n },
125
+ { to: recipient2, faucetId, amount: 300n },
126
+ ],
127
+ });
128
+ ```
129
+
130
+ ### Claim Notes
131
+ ```tsx
132
+ const { mutate: consume } = useConsume();
133
+
134
+ await consume({
135
+ accountId: myAccountId,
136
+ noteIds: [noteId1, noteId2], // optional: consume specific notes
137
+ });
138
+ ```
139
+
140
+ ### Mint Tokens (Faucet Owner)
141
+ ```tsx
142
+ const { mutate: mint } = useMint();
143
+
144
+ await mint({
145
+ faucetId: myFaucetId,
146
+ to: recipientAccountId,
147
+ amount: 10000n,
148
+ });
149
+ ```
150
+
151
+ ### Create Faucet
152
+ ```tsx
153
+ const { mutate: createFaucet } = useCreateFaucet();
154
+
155
+ const faucet = await createFaucet({
156
+ symbol: "TOKEN",
157
+ decimals: 8,
158
+ maxSupply: 1000000n,
159
+ storageMode: "public",
160
+ });
161
+ ```
162
+
163
+ ## Common Patterns
164
+
165
+ ### Show Transaction Progress
166
+ ```tsx
167
+ function SendButton() {
168
+ const { mutate: send, stage, isLoading, error } = useSend();
169
+
170
+ const handleSend = async () => {
171
+ try {
172
+ await send({ from, to, faucetId, amount });
173
+ } catch (err) {
174
+ console.error("Transaction failed:", err);
175
+ }
176
+ };
177
+
178
+ return (
179
+ <div>
180
+ <button onClick={handleSend} disabled={isLoading}>
181
+ {isLoading ? `${stage}...` : "Send"}
182
+ </button>
183
+ {error && <p>Error: {error.message}</p>}
184
+ </div>
185
+ );
186
+ }
187
+ ```
188
+
189
+ ### Format Token Amounts
190
+ ```tsx
191
+ import { formatAssetAmount, parseAssetAmount } from "@miden-sdk/react";
192
+
193
+ // Display: 1000000n with 8 decimals → "0.01"
194
+ const display = formatAssetAmount(balance, 8);
195
+
196
+ // User input: "0.01" with 8 decimals → 1000000n
197
+ const amount = parseAssetAmount("0.01", 8);
198
+ ```
199
+
200
+ ### Display Note Summary
201
+ ```tsx
202
+ import { getNoteSummary, formatNoteSummary } from "@miden-sdk/react";
203
+
204
+ const summary = getNoteSummary(note);
205
+ const text = formatNoteSummary(summary); // "1.5 TOKEN"
206
+ ```
207
+
208
+ ### Wait for Transaction Confirmation
209
+ ```tsx
210
+ const { mutate: waitForCommit } = useWaitForCommit();
211
+
212
+ // After sending
213
+ const result = await send({ ... });
214
+ await waitForCommit({ transactionId: result.transactionId });
215
+ ```
216
+
217
+ ### Access Client Directly
218
+ ```tsx
219
+ const client = useMidenClient();
220
+
221
+ // For advanced operations not covered by hooks
222
+ const blockHeader = await client.getBlockHeaderByNumber(100);
223
+ ```
224
+
225
+ ### Prevent Race Conditions
226
+ ```tsx
227
+ const { runExclusive } = useMiden();
228
+
229
+ // Ensures sequential execution
230
+ await runExclusive(async (client) => {
231
+ // Multiple operations that must not interleave
232
+ });
233
+ ```
234
+
235
+ ## External Signer Integration
236
+
237
+ For wallets using external key management, use the pre-built signer providers:
238
+
239
+ ### Para (EVM Wallets)
240
+ ```tsx
241
+ import { ParaSignerProvider } from "@miden-sdk/para";
242
+
243
+ <ParaSignerProvider apiKey="your-api-key" environment="PRODUCTION">
244
+ <MidenProvider config={{ rpcUrl: "testnet" }}>
245
+ <App />
246
+ </MidenProvider>
247
+ </ParaSignerProvider>
248
+
249
+ // Access Para-specific data
250
+ const { para, wallet, isConnected } = useParaSigner();
251
+ ```
252
+
253
+ ### Turnkey
254
+ ```tsx
255
+ import { TurnkeySignerProvider } from "@miden-sdk/miden-turnkey-react";
256
+
257
+ // Config is optional — defaults to https://api.turnkey.com
258
+ // and reads VITE_TURNKEY_ORG_ID from environment
259
+ <TurnkeySignerProvider>
260
+ <MidenProvider config={{ rpcUrl: "testnet" }}>
261
+ <App />
262
+ </MidenProvider>
263
+ </TurnkeySignerProvider>
264
+
265
+ // Or with explicit config:
266
+ <TurnkeySignerProvider config={{
267
+ apiBaseUrl: "https://api.turnkey.com",
268
+ defaultOrganizationId: "your-org-id",
269
+ }}>
270
+ ...
271
+ </TurnkeySignerProvider>
272
+ ```
273
+
274
+ Connect via passkey authentication:
275
+ ```tsx
276
+ import { useSigner } from "@miden-sdk/react";
277
+ import { useTurnkeySigner } from "@miden-sdk/miden-turnkey-react";
278
+
279
+ // useSigner() handles connect/disconnect
280
+ const { isConnected, connect, disconnect } = useSigner();
281
+ await connect(); // triggers passkey flow, auto-selects account
282
+
283
+ // useTurnkeySigner() exposes Turnkey-specific extras
284
+ const { client, account, setAccount } = useTurnkeySigner();
285
+ ```
286
+
287
+ ### MidenFi Wallet Adapter
288
+ ```tsx
289
+ import { MidenFiSignerProvider } from "@miden-sdk/wallet-adapter-react";
290
+
291
+ <MidenFiSignerProvider network="Testnet">
292
+ <MidenProvider config={{ rpcUrl: "testnet" }}>
293
+ <App />
294
+ </MidenProvider>
295
+ </MidenFiSignerProvider>
296
+ ```
297
+
298
+ ### Using the Unified Signer Interface
299
+ ```tsx
300
+ import { useSigner } from "@miden-sdk/react";
301
+
302
+ // Works with any signer provider above
303
+ const { isConnected, connect, disconnect, name } = useSigner();
304
+
305
+ if (!isConnected) {
306
+ return <button onClick={connect}>Connect {name}</button>;
307
+ }
308
+ ```
309
+
310
+ ### Building a Custom Signer Provider
311
+ ```tsx
312
+ import { SignerContext } from "@miden-sdk/react";
313
+
314
+ <SignerContext.Provider value={{
315
+ name: "MyWallet",
316
+ storeName: `mywallet_${userAddress}`, // unique per user for DB isolation
317
+ isConnected: true,
318
+ accountConfig: {
319
+ publicKey: userPublicKeyCommitment, // Uint8Array
320
+ storageMode: "private",
321
+ },
322
+ signCb: async (pubKey, signingInputs) => {
323
+ // Route to your signing service
324
+ return signature; // Uint8Array
325
+ },
326
+ connect: async () => { /* trigger wallet connection */ },
327
+ disconnect: async () => { /* clear session */ },
328
+ }}>
329
+ <MidenProvider config={{ rpcUrl: "testnet" }}>
330
+ <App />
331
+ </MidenProvider>
332
+ </SignerContext.Provider>
333
+ ```
334
+
335
+ ## Account ID Formats
336
+
337
+ Both formats work interchangeably in all hooks:
338
+
339
+ ```tsx
340
+ // Hex format
341
+ useAccount("0x1234567890abcdef");
342
+
343
+ // Bech32 format
344
+ useAccount("miden1qy35...");
345
+
346
+ // Convert to bech32 for display
347
+ account.bech32id(); // "miden1qy35..."
348
+ ```
349
+
350
+ ## Hook Reference
351
+
352
+ | Hook | Returns | Purpose |
353
+ |------|---------|---------|
354
+ | `useAccounts()` | `{ wallets, faucets, all }` | List all accounts |
355
+ | `useAccount(id)` | `Account` | Account details + balances |
356
+ | `useNotes(filter?)` | `{ input, consumable }` | Available notes |
357
+ | `useSyncState()` | `{ syncHeight, sync() }` | Sync status |
358
+ | `useAssetMetadata(id)` | `{ symbol, decimals }` | Token info |
359
+ | `useCreateWallet()` | `Account` | Create wallet |
360
+ | `useCreateFaucet()` | `Account` | Create faucet |
361
+ | `useImportAccount()` | `Account` | Import account |
362
+ | `useSend()` | `TransactionResult` | Send tokens |
363
+ | `useMultiSend()` | `TransactionResult` | Multi-recipient send |
364
+ | `useMint()` | `TransactionResult` | Mint tokens |
365
+ | `useConsume()` | `TransactionResult` | Claim notes |
366
+ | `useSwap()` | `TransactionResult` | Atomic swap |
367
+ | `useTransaction()` | `TransactionResult` | Custom transaction |
368
+
369
+ ## Type Imports
370
+
371
+ ```tsx
372
+ import type {
373
+ // Config
374
+ MidenConfig,
375
+
376
+ // Hook results
377
+ QueryResult,
378
+ MutationResult,
379
+ AccountsResult,
380
+
381
+ // SDK types (re-exported)
382
+ Account,
383
+ AccountId,
384
+ Note,
385
+ TransactionRecord,
386
+ FungibleAsset,
387
+ } from "@miden-sdk/react";
388
+ ```
389
+
390
+ ## Troubleshooting
391
+
392
+ | Issue | Solution |
393
+ |-------|----------|
394
+ | "Client not ready" | Wrap component in `MidenProvider`, check `useMiden().isReady` |
395
+ | Transaction stuck | Check `stage` value, network connectivity, prover availability |
396
+ | Notes not appearing | Call `sync()` manually, check `autoSyncInterval` config |
397
+ | Bech32 address wrong | Verify `rpcUrl` matches intended network |
398
+ | WASM init fails | Check browser compatibility, ensure WASM served with correct MIME type |
package/dist/index.d.mts CHANGED
@@ -1,6 +1,7 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import * as react from 'react';
2
3
  import { ReactNode } from 'react';
3
- import { Account, AccountHeader, AccountId, TransactionRequest, WebClient, AccountFile, InputNoteRecord, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver } from '@miden-sdk/miden-sdk';
4
+ import { AccountStorageMode, Account, AccountHeader, AccountId, TransactionRequest, WebClient, AccountFile, InputNoteRecord, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver } from '@miden-sdk/miden-sdk';
4
5
  export { Account, AccountFile, AccountHeader, AccountId, AccountStorageMode, ConsumableNoteRecord, InputNoteRecord, NoteType, TransactionFilter, TransactionId, TransactionRecord, TransactionRequest, WebClient } from '@miden-sdk/miden-sdk';
5
6
 
6
7
  declare module "@miden-sdk/miden-sdk" {
@@ -10,6 +11,79 @@ declare module "@miden-sdk/miden-sdk" {
10
11
  }
11
12
  }
12
13
 
14
+ /**
15
+ * Sign callback for WebClient.createClientWithExternalKeystore.
16
+ * Called when a transaction needs to be signed.
17
+ *
18
+ * @param pubKey - Public key commitment bytes
19
+ * @param signingInputs - Serialized signing inputs
20
+ * @returns Promise resolving to the signature bytes
21
+ */
22
+ type SignCallback = (pubKey: Uint8Array, signingInputs: Uint8Array) => Promise<Uint8Array>;
23
+ /**
24
+ * Account type for signer accounts.
25
+ * Matches the AccountType enum from the SDK.
26
+ */
27
+ type SignerAccountType = "RegularAccountImmutableCode" | "RegularAccountUpdatableCode" | "FungibleFaucet" | "NonFungibleFaucet";
28
+ /**
29
+ * Account configuration provided by the signer.
30
+ * Used to initialize the account in the client store.
31
+ */
32
+ interface SignerAccountConfig {
33
+ /** Public key commitment (for auth component) */
34
+ publicKeyCommitment: Uint8Array;
35
+ /** Account type */
36
+ accountType: SignerAccountType;
37
+ /** Storage mode (public/private/network) */
38
+ storageMode: AccountStorageMode;
39
+ /** Optional seed for deterministic account ID */
40
+ accountSeed?: Uint8Array;
41
+ }
42
+ /**
43
+ * Context value provided by signer providers (Para, Turnkey, MidenFi, etc.).
44
+ * Includes everything needed for MidenProvider to create an external keystore client
45
+ * and for apps to show connect/disconnect UI.
46
+ */
47
+ interface SignerContextValue {
48
+ /** Sign callback for external keystore */
49
+ signCb: SignCallback;
50
+ /** Account config for initialization (only valid when connected) */
51
+ accountConfig: SignerAccountConfig;
52
+ /** Store name suffix for IndexedDB isolation (e.g., "para_walletId") */
53
+ storeName: string;
54
+ /** Display name for UI (e.g., "Para", "Turnkey", "MidenFi") */
55
+ name: string;
56
+ /** Whether the signer is connected and ready */
57
+ isConnected: boolean;
58
+ /** Connect to the signer (triggers auth flow) */
59
+ connect: () => Promise<void>;
60
+ /** Disconnect from the signer */
61
+ disconnect: () => Promise<void>;
62
+ }
63
+ /**
64
+ * React context for signer - null when no signer provider is present.
65
+ * Signer providers (ParaSignerProvider, TurnkeySignerProvider, etc.) populate this context.
66
+ */
67
+ declare const SignerContext: react.Context<SignerContextValue | null>;
68
+ /**
69
+ * Hook for apps and MidenProvider to interact with the current signer.
70
+ * Returns null if no signer provider is present (local keystore mode).
71
+ *
72
+ * @example
73
+ * ```tsx
74
+ * function ConnectButton() {
75
+ * const signer = useSigner();
76
+ * if (!signer) return null; // Local keystore mode
77
+ *
78
+ * const { isConnected, connect, disconnect, name } = signer;
79
+ * return isConnected
80
+ * ? <button onClick={disconnect}>Disconnect {name}</button>
81
+ * : <button onClick={connect}>Connect with {name}</button>;
82
+ * }
83
+ * ```
84
+ */
85
+ declare function useSigner(): SignerContextValue | null;
86
+
13
87
  type RpcUrlConfig = string | "devnet" | "testnet" | "localhost" | "local";
14
88
  type ProverConfig = "local" | "devnet" | "testnet" | string | {
15
89
  url: string;
@@ -307,6 +381,8 @@ interface MidenContextValue {
307
381
  sync: () => Promise<void>;
308
382
  runExclusive: <T>(fn: () => Promise<T>) => Promise<T>;
309
383
  prover: ReturnType<typeof resolveTransactionProver>;
384
+ /** Account ID from signer (only set when using external signer) */
385
+ signerAccountId: string | null;
310
386
  }
311
387
  interface MidenProviderProps {
312
388
  children: ReactNode;
@@ -924,4 +1000,4 @@ declare const parseAssetAmount: (input: string, decimals?: number) => bigint;
924
1000
  declare const getNoteSummary: (note: ConsumableNoteRecord | InputNoteRecord, getAssetMetadata?: (assetId: string) => AssetMetadata | undefined) => NoteSummary | null;
925
1001
  declare const formatNoteSummary: (summary: NoteSummary, formatAsset?: (asset: NoteAsset) => string) => string;
926
1002
 
927
- export { type AccountResult, type AccountsResult, type AssetBalance, type AssetMetadata, type ConsumeOptions, type CreateFaucetOptions, type CreateWalletOptions, DEFAULTS, type ExecuteTransactionOptions, type ImportAccountOptions, type InternalTransferChainOptions, type InternalTransferOptions, type InternalTransferResult, type MidenConfig, MidenProvider, type MidenState, type MintOptions, type MultiSendOptions, type MultiSendRecipient, type MutationResult, type NoteAsset, type NoteSummary, type NotesFilter, type NotesResult, type ProverConfig, type ProverUrls, type QueryResult, type RpcUrlConfig, type SendOptions, type SwapOptions, type SyncState, type TransactionHistoryOptions, type TransactionHistoryResult, type TransactionResult, type TransactionStage, type TransactionStatus, type UseConsumeResult, type UseCreateFaucetResult, type UseCreateWalletResult, type UseImportAccountResult, type UseInternalTransferResult, type UseMintResult, type UseMultiSendResult, type UseSendResult, type UseSwapResult, type UseSyncStateResult, type UseTransactionHistoryResult, type UseTransactionResult, type UseWaitForCommitResult, type UseWaitForNotesResult, type WaitForCommitOptions, type WaitForNotesOptions, formatAssetAmount, formatNoteSummary, getNoteSummary, parseAssetAmount, toBech32AccountId, useAccount, useAccounts, useAssetMetadata, useConsume, useCreateFaucet, useCreateWallet, useImportAccount, useInternalTransfer, useMiden, useMidenClient, useMint, useMultiSend, useNotes, useSend, useSwap, useSyncState, useTransaction, useTransactionHistory, useWaitForCommit, useWaitForNotes };
1003
+ export { type AccountResult, type AccountsResult, type AssetBalance, type AssetMetadata, type ConsumeOptions, type CreateFaucetOptions, type CreateWalletOptions, DEFAULTS, type ExecuteTransactionOptions, type ImportAccountOptions, type InternalTransferChainOptions, type InternalTransferOptions, type InternalTransferResult, type MidenConfig, MidenProvider, type MidenState, type MintOptions, type MultiSendOptions, type MultiSendRecipient, type MutationResult, type NoteAsset, type NoteSummary, type NotesFilter, type NotesResult, type ProverConfig, type ProverUrls, type QueryResult, type RpcUrlConfig, type SendOptions, type SignCallback, type SignerAccountConfig, type SignerAccountType, SignerContext, type SignerContextValue, type SwapOptions, type SyncState, type TransactionHistoryOptions, type TransactionHistoryResult, type TransactionResult, type TransactionStage, type TransactionStatus, type UseConsumeResult, type UseCreateFaucetResult, type UseCreateWalletResult, type UseImportAccountResult, type UseInternalTransferResult, type UseMintResult, type UseMultiSendResult, type UseSendResult, type UseSwapResult, type UseSyncStateResult, type UseTransactionHistoryResult, type UseTransactionResult, type UseWaitForCommitResult, type UseWaitForNotesResult, type WaitForCommitOptions, type WaitForNotesOptions, formatAssetAmount, formatNoteSummary, getNoteSummary, parseAssetAmount, toBech32AccountId, useAccount, useAccounts, useAssetMetadata, useConsume, useCreateFaucet, useCreateWallet, useImportAccount, useInternalTransfer, useMiden, useMidenClient, useMint, useMultiSend, useNotes, useSend, useSigner, useSwap, useSyncState, useTransaction, useTransactionHistory, useWaitForCommit, useWaitForNotes };
package/dist/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import * as react from 'react';
2
3
  import { ReactNode } from 'react';
3
- import { Account, AccountHeader, AccountId, TransactionRequest, WebClient, AccountFile, InputNoteRecord, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver } from '@miden-sdk/miden-sdk';
4
+ import { AccountStorageMode, Account, AccountHeader, AccountId, TransactionRequest, WebClient, AccountFile, InputNoteRecord, ConsumableNoteRecord, TransactionId, TransactionFilter, TransactionRecord, TransactionProver } from '@miden-sdk/miden-sdk';
4
5
  export { Account, AccountFile, AccountHeader, AccountId, AccountStorageMode, ConsumableNoteRecord, InputNoteRecord, NoteType, TransactionFilter, TransactionId, TransactionRecord, TransactionRequest, WebClient } from '@miden-sdk/miden-sdk';
5
6
 
6
7
  declare module "@miden-sdk/miden-sdk" {
@@ -10,6 +11,79 @@ declare module "@miden-sdk/miden-sdk" {
10
11
  }
11
12
  }
12
13
 
14
+ /**
15
+ * Sign callback for WebClient.createClientWithExternalKeystore.
16
+ * Called when a transaction needs to be signed.
17
+ *
18
+ * @param pubKey - Public key commitment bytes
19
+ * @param signingInputs - Serialized signing inputs
20
+ * @returns Promise resolving to the signature bytes
21
+ */
22
+ type SignCallback = (pubKey: Uint8Array, signingInputs: Uint8Array) => Promise<Uint8Array>;
23
+ /**
24
+ * Account type for signer accounts.
25
+ * Matches the AccountType enum from the SDK.
26
+ */
27
+ type SignerAccountType = "RegularAccountImmutableCode" | "RegularAccountUpdatableCode" | "FungibleFaucet" | "NonFungibleFaucet";
28
+ /**
29
+ * Account configuration provided by the signer.
30
+ * Used to initialize the account in the client store.
31
+ */
32
+ interface SignerAccountConfig {
33
+ /** Public key commitment (for auth component) */
34
+ publicKeyCommitment: Uint8Array;
35
+ /** Account type */
36
+ accountType: SignerAccountType;
37
+ /** Storage mode (public/private/network) */
38
+ storageMode: AccountStorageMode;
39
+ /** Optional seed for deterministic account ID */
40
+ accountSeed?: Uint8Array;
41
+ }
42
+ /**
43
+ * Context value provided by signer providers (Para, Turnkey, MidenFi, etc.).
44
+ * Includes everything needed for MidenProvider to create an external keystore client
45
+ * and for apps to show connect/disconnect UI.
46
+ */
47
+ interface SignerContextValue {
48
+ /** Sign callback for external keystore */
49
+ signCb: SignCallback;
50
+ /** Account config for initialization (only valid when connected) */
51
+ accountConfig: SignerAccountConfig;
52
+ /** Store name suffix for IndexedDB isolation (e.g., "para_walletId") */
53
+ storeName: string;
54
+ /** Display name for UI (e.g., "Para", "Turnkey", "MidenFi") */
55
+ name: string;
56
+ /** Whether the signer is connected and ready */
57
+ isConnected: boolean;
58
+ /** Connect to the signer (triggers auth flow) */
59
+ connect: () => Promise<void>;
60
+ /** Disconnect from the signer */
61
+ disconnect: () => Promise<void>;
62
+ }
63
+ /**
64
+ * React context for signer - null when no signer provider is present.
65
+ * Signer providers (ParaSignerProvider, TurnkeySignerProvider, etc.) populate this context.
66
+ */
67
+ declare const SignerContext: react.Context<SignerContextValue | null>;
68
+ /**
69
+ * Hook for apps and MidenProvider to interact with the current signer.
70
+ * Returns null if no signer provider is present (local keystore mode).
71
+ *
72
+ * @example
73
+ * ```tsx
74
+ * function ConnectButton() {
75
+ * const signer = useSigner();
76
+ * if (!signer) return null; // Local keystore mode
77
+ *
78
+ * const { isConnected, connect, disconnect, name } = signer;
79
+ * return isConnected
80
+ * ? <button onClick={disconnect}>Disconnect {name}</button>
81
+ * : <button onClick={connect}>Connect with {name}</button>;
82
+ * }
83
+ * ```
84
+ */
85
+ declare function useSigner(): SignerContextValue | null;
86
+
13
87
  type RpcUrlConfig = string | "devnet" | "testnet" | "localhost" | "local";
14
88
  type ProverConfig = "local" | "devnet" | "testnet" | string | {
15
89
  url: string;
@@ -307,6 +381,8 @@ interface MidenContextValue {
307
381
  sync: () => Promise<void>;
308
382
  runExclusive: <T>(fn: () => Promise<T>) => Promise<T>;
309
383
  prover: ReturnType<typeof resolveTransactionProver>;
384
+ /** Account ID from signer (only set when using external signer) */
385
+ signerAccountId: string | null;
310
386
  }
311
387
  interface MidenProviderProps {
312
388
  children: ReactNode;
@@ -924,4 +1000,4 @@ declare const parseAssetAmount: (input: string, decimals?: number) => bigint;
924
1000
  declare const getNoteSummary: (note: ConsumableNoteRecord | InputNoteRecord, getAssetMetadata?: (assetId: string) => AssetMetadata | undefined) => NoteSummary | null;
925
1001
  declare const formatNoteSummary: (summary: NoteSummary, formatAsset?: (asset: NoteAsset) => string) => string;
926
1002
 
927
- export { type AccountResult, type AccountsResult, type AssetBalance, type AssetMetadata, type ConsumeOptions, type CreateFaucetOptions, type CreateWalletOptions, DEFAULTS, type ExecuteTransactionOptions, type ImportAccountOptions, type InternalTransferChainOptions, type InternalTransferOptions, type InternalTransferResult, type MidenConfig, MidenProvider, type MidenState, type MintOptions, type MultiSendOptions, type MultiSendRecipient, type MutationResult, type NoteAsset, type NoteSummary, type NotesFilter, type NotesResult, type ProverConfig, type ProverUrls, type QueryResult, type RpcUrlConfig, type SendOptions, type SwapOptions, type SyncState, type TransactionHistoryOptions, type TransactionHistoryResult, type TransactionResult, type TransactionStage, type TransactionStatus, type UseConsumeResult, type UseCreateFaucetResult, type UseCreateWalletResult, type UseImportAccountResult, type UseInternalTransferResult, type UseMintResult, type UseMultiSendResult, type UseSendResult, type UseSwapResult, type UseSyncStateResult, type UseTransactionHistoryResult, type UseTransactionResult, type UseWaitForCommitResult, type UseWaitForNotesResult, type WaitForCommitOptions, type WaitForNotesOptions, formatAssetAmount, formatNoteSummary, getNoteSummary, parseAssetAmount, toBech32AccountId, useAccount, useAccounts, useAssetMetadata, useConsume, useCreateFaucet, useCreateWallet, useImportAccount, useInternalTransfer, useMiden, useMidenClient, useMint, useMultiSend, useNotes, useSend, useSwap, useSyncState, useTransaction, useTransactionHistory, useWaitForCommit, useWaitForNotes };
1003
+ export { type AccountResult, type AccountsResult, type AssetBalance, type AssetMetadata, type ConsumeOptions, type CreateFaucetOptions, type CreateWalletOptions, DEFAULTS, type ExecuteTransactionOptions, type ImportAccountOptions, type InternalTransferChainOptions, type InternalTransferOptions, type InternalTransferResult, type MidenConfig, MidenProvider, type MidenState, type MintOptions, type MultiSendOptions, type MultiSendRecipient, type MutationResult, type NoteAsset, type NoteSummary, type NotesFilter, type NotesResult, type ProverConfig, type ProverUrls, type QueryResult, type RpcUrlConfig, type SendOptions, type SignCallback, type SignerAccountConfig, type SignerAccountType, SignerContext, type SignerContextValue, type SwapOptions, type SyncState, type TransactionHistoryOptions, type TransactionHistoryResult, type TransactionResult, type TransactionStage, type TransactionStatus, type UseConsumeResult, type UseCreateFaucetResult, type UseCreateWalletResult, type UseImportAccountResult, type UseInternalTransferResult, type UseMintResult, type UseMultiSendResult, type UseSendResult, type UseSwapResult, type UseSyncStateResult, type UseTransactionHistoryResult, type UseTransactionResult, type UseWaitForCommitResult, type UseWaitForNotesResult, type WaitForCommitOptions, type WaitForNotesOptions, formatAssetAmount, formatNoteSummary, getNoteSummary, parseAssetAmount, toBech32AccountId, useAccount, useAccounts, useAssetMetadata, useConsume, useCreateFaucet, useCreateWallet, useImportAccount, useInternalTransfer, useMiden, useMidenClient, useMint, useMultiSend, useNotes, useSend, useSigner, useSwap, useSyncState, useTransaction, useTransactionHistory, useWaitForCommit, useWaitForNotes };