@miden-sdk/miden-sdk 0.14.3 → 0.14.5

package/dist/api-types.d.ts

@@ -84,9 +84,25 @@ export declare const AuthScheme: {
 };
 
 /**
- * Union of all values in the AuthScheme const.
+ * Union of all string values in the AuthScheme const. Merges with the
+ * `AuthScheme` value so `authScheme?: AuthScheme` resolves to
+ * `"falcon" | "ecdsa"` in type position while `AuthScheme.Falcon` /
+ * `AuthScheme.ECDSA` still work in value position.
  */
-export type AuthSchemeType = (typeof AuthScheme)[keyof typeof AuthScheme];
+export type AuthScheme = (typeof AuthScheme)[keyof typeof AuthScheme];
+
+/** @deprecated Alias for `AuthScheme` (the string union). */
+export type AuthSchemeType = AuthScheme;
+
+/**
+ * Resolves an `AuthScheme` string to the numeric value expected by low-level
+ * wasm-bindgen methods such as
+ * `AccountComponent.createAuthComponentFromCommitment(commitment, scheme)`.
+ *
+ * @param scheme - `AuthScheme.Falcon` or `AuthScheme.ECDSA`. Defaults to `"falcon"`.
+ * @returns The numeric AuthScheme enum value.
+ */
+export declare function resolveAuthScheme(scheme?: AuthScheme): number;
 
 /**
  * User-friendly note visibility constants.
@@ -921,6 +937,15 @@ export declare class MidenClient {
   static createDevnet(options?: ClientOptions): Promise<MidenClient>;
   /** Creates a mock client for testing. */
   static createMock(options?: MockOptions): Promise<MidenClient>;
+  /**
+   * Resolves once the WASM module is initialized and safe to use.
+   *
+   * Idempotent and shared across callers — concurrent invocations await the
+   * same in-flight promise, and post-init callers resolve immediately.
+   * Primarily useful on the `/lazy` entry (Next.js / Capacitor) where no
+   * top-level await runs at import time; harmless on the eager entry.
+   */
+  static ready(): Promise<void>;
 
   readonly accounts: AccountsResource;
   readonly transactions: TransactionsResource;
@@ -934,6 +959,30 @@ export declare class MidenClient {
   sync(options?: { timeout?: number }): Promise<SyncSummary>;
   /** Returns the current sync height. */
   getSyncHeight(): Promise<number>;
+  /**
+   * Resolves once every serialized WASM call that was already on the
+   * internal call chain when `waitForIdle()` was called (execute, submit,
+   * prove, apply, sync, or account creation) has settled. Use this from
+   * callers that need to perform a non-WASM-side action — e.g. clearing
+   * an in-memory auth key on wallet lock — after the kernel finishes, so
+   * its auth callback doesn't race with the key being cleared. Does NOT
+   * wait for calls enqueued after `waitForIdle()` returns.
+   *
+   * Caveat for `sync`: a `syncState` blocked on its sync lock (Web
+   * Locks) has not yet reached the internal chain, so `waitForIdle`
+   * does not await it. Other serialized methods are always observed.
+   *
+   * Returns immediately if nothing was in flight.
+   */
+  waitForIdle(): Promise<void>;
+  /**
+   * Returns the raw JS value that the most recent sign-callback invocation
+   * threw, or `null` if the last sign call succeeded (or no call has
+   * happened yet). Useful for recovering structured metadata (e.g. a
+   * `reason: 'locked'` property) that the kernel-level `auth::request`
+   * diagnostic would otherwise erase.
+   */
+  lastAuthError(): unknown;
   /** Returns the client-level default prover. */
   readonly defaultProver: TransactionProver | null;
   /** Terminates the underlying Web Worker. After this, all method calls throw. */

package/dist/crates/miden_client_web.d.ts

@@ -121,6 +121,14 @@ export class AccountArray {
     length(): number;
     constructor(elements?: Account[] | null);
     push(element: Account): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: Account): void;
 }
 
@@ -445,6 +453,14 @@ export class AccountIdArray {
     length(): number;
     constructor(elements?: AccountId[] | null);
     push(element: AccountId): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: AccountId): void;
 }
 
@@ -1005,6 +1021,15 @@ export class BlockHeader {
      * Returns the commitment to the block contents.
      */
     commitment(): Word;
+    /**
+     * Returns the account ID of the fungible faucet whose assets are accepted as the native
+     * asset of the blockchain (i.e. the asset used for paying transaction verification fees).
+     *
+     * This is stored on-chain as part of the block's fee parameters, which means consumers can
+     * discover the native faucet by reading any block header rather than hardcoding it per
+     * network.
+     */
+    nativeAssetId(): AccountId;
     /**
      * Returns the note commitment root.
      */
@@ -1313,6 +1338,14 @@ export class FeltArray {
     length(): number;
     constructor(elements?: Felt[] | null);
     push(element: Felt): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: Felt): void;
 }
 
@@ -1453,6 +1486,14 @@ export class ForeignAccountArray {
     length(): number;
     constructor(elements?: ForeignAccount[] | null);
     push(element: ForeignAccount): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: ForeignAccount): void;
 }
 
@@ -2103,6 +2144,14 @@ export class NoteAndArgsArray {
     length(): number;
     constructor(elements?: NoteAndArgs[] | null);
     push(element: NoteAndArgs): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: NoteAndArgs): void;
 }
 
@@ -2124,6 +2173,14 @@ export class NoteArray {
     length(): number;
     constructor(elements?: Note[] | null);
     push(element: Note): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: Note): void;
 }
 
@@ -2362,6 +2419,14 @@ export class NoteDetailsAndTagArray {
     length(): number;
     constructor(elements?: NoteDetailsAndTag[] | null);
     push(element: NoteDetailsAndTag): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: NoteDetailsAndTag): void;
 }
 
@@ -2588,6 +2653,14 @@ export class NoteIdAndArgsArray {
     length(): number;
     constructor(elements?: NoteIdAndArgs[] | null);
     push(element: NoteIdAndArgs): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: NoteIdAndArgs): void;
 }
 
@@ -2722,6 +2795,14 @@ export class NoteRecipientArray {
     length(): number;
     constructor(elements?: NoteRecipient[] | null);
     push(element: NoteRecipient): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: NoteRecipient): void;
 }
 
@@ -2943,6 +3024,14 @@ export class OutputNoteArray {
     length(): number;
     constructor(elements?: OutputNote[] | null);
     push(element: OutputNote): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: OutputNote): void;
 }
 
@@ -3609,6 +3698,14 @@ export class StorageSlotArray {
     length(): number;
     constructor(elements?: StorageSlot[] | null);
     push(element: StorageSlot): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: StorageSlot): void;
 }
 
@@ -4056,6 +4153,14 @@ export class TransactionScriptInputPairArray {
     length(): number;
     constructor(elements?: TransactionScriptInputPair[] | null);
     push(element: TransactionScriptInputPair): void;
+    /**
+     * Replace the element at `index`. Borrows + clones the input
+     * (mirrors `push`), so the caller's JS handle remains valid
+     * after the call. Without this borrow, passing `elem` by
+     * value would move the underlying Rust value out of the
+     * caller's JS handle and any subsequent method on it would
+     * panic with `"null pointer passed to rust"`.
+     */
     replaceAt(index: number, elem: TransactionScriptInputPair): void;
 }
 
@@ -4316,6 +4421,31 @@ export class WebClient {
     importNoteFile(note_file: NoteFile): Promise<NoteId>;
     importPublicAccountFromSeed(init_seed: Uint8Array, mutable: boolean, auth_scheme: AuthScheme): Promise<Account>;
     insertAccountAddress(account_id: AccountId, address: Address): Promise<void>;
+    /**
+     * Returns the raw JS value that the most recent sign-callback invocation
+     * threw, or `null` if the last sign call succeeded (or no call has
+     * happened yet).
+     *
+     * Combined with the serialized-call discipline enforced at the JS
+     * `WebClient` wrapper, this lets a caller that caught a failed
+     * `executeTransaction` / `submitNewTransaction` recover the original
+     * JS error the signing callback threw — preserving any structured
+     * metadata (e.g. a `reason: 'locked'` property) that the kernel-level
+     * `auth::request` diagnostic would otherwise have erased.
+     *
+     * # Usage (TS)
+     * ```ts
+     * try {
+     *   await client.submitNewTransaction(acc, req);
+     * } catch (e) {
+     *   const authErr = client.lastAuthError();
+     *   if (authErr && authErr.reason === 'locked') {
+     *     // wait for unlock, then retry
+     *   }
+     * }
+     * ```
+     */
+    lastAuthError(): any;
     /**
      * Returns all the existing setting keys from the store.
      */
@@ -4338,10 +4468,20 @@ export class WebClient {
     newWallet(storage_mode: AccountStorageMode, mutable: boolean, auth_scheme: AuthScheme, init_seed?: Uint8Array | null): Promise<Account>;
     proveBlock(): void;
     /**
-     * Generates a transaction proof using either the provided prover or the client's default
-     * prover if none is supplied.
+     * Generates a transaction proof using the client's default (local) prover.
      */
-    proveTransaction(transaction_result: TransactionResult, prover?: TransactionProver | null): Promise<ProvenTransaction>;
+    proveTransaction(transaction_result: TransactionResult): Promise<ProvenTransaction>;
+    /**
+     * Generates a transaction proof using the provided prover.
+     *
+     * Takes the prover by reference so the JS-side handle is NOT consumed
+     * by wasm-bindgen. Taking `TransactionProver` by value would transfer
+     * ownership on each call, invalidating the JS object's internal WASM
+     * handle; after one use, subsequent calls from JS would pass a dangling
+     * handle that wasm-bindgen interprets as `None`, silently falling back
+     * to the local prover.
+     */
+    proveTransactionWithProver(transaction_result: TransactionResult, prover: TransactionProver): Promise<ProvenTransaction>;
     /**
      * Prunes historical account states for the specified account up to the given nonce.
      *

package/dist/eager.js

@@ -0,0 +1,35 @@
+import { getWasmOrThrow } from './index.js';
+export { AccountArray, AccountIdArray, AccountType, AuthScheme, CompilerResource, FeltArray, ForeignAccountArray, Linking, MidenArrays, MidenClient, MockWasmWebClient, NoteAndArgsArray, NoteArray, NoteIdAndArgsArray, NoteRecipientArray, NoteVisibility, OutputNoteArray, StorageMode, StorageSlotArray, TransactionScriptInputPairArray, WasmWebClient, buildSwapTag, createP2IDENote, createP2IDNote, resolveAuthScheme } from './index.js';
+export { Account, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, ExecutedTransaction, Felt, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkId, NetworkType, Note, NoteAndArgs, NoteAssets, NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapInfo, StorageMapUpdate, StorageSlot, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, setupLogging } from './Cargo-M3382VZc.js';
+import './wasm.js';
+
+// Eager entry point for @miden-sdk/miden-sdk.
+//
+// Awaits WASM initialization at module top level, so importing this module
+// guarantees that any wasm-bindgen constructor (`new RpcClient(...)`,
+// `AccountId.fromHex(...)`, `TransactionProver.newRemoteProver(...)`, etc.)
+// is safe to call synchronously on the next line. No explicit
+// `await MidenClient.ready()` / `isReady` gate is required.
+//
+// This is the default entry (`@miden-sdk/miden-sdk` → `./dist/eager.js`).
+//
+// When NOT to use this entry:
+// - **Capacitor mobile apps** (Miden Wallet iOS/Android): Capacitor's
+//   `capacitor://localhost` scheme handler interacts poorly with top-level
+//   await in the main WKWebView. Verified empirically: TLA in a Capacitor
+//   host WKWebView hangs module evaluation indefinitely, while the same
+//   TLA in the dApp-browser WKWebView (vanilla HTTPS) resolves in <100ms.
+// - **Next.js / SSR**: TLA blocks server-side module evaluation.
+// - **Framework adapters (@miden-sdk/react, etc.)**: they manage readiness
+//   via their own state machine (e.g. `isReady`) and should not impose
+//   TLA on consumer bundles.
+//
+// For those contexts, import from `@miden-sdk/miden-sdk/lazy` — identical
+// API surface, no top-level await, callers are responsible for awaiting
+// `MidenClient.ready()` (or the equivalent) before touching wasm-bindgen
+// types.
+
+await getWasmOrThrow();
+
+export { getWasmOrThrow };
+//# sourceMappingURL=eager.js.map

package/dist/eager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eager.js","sources":["../js/eager.js"],"sourcesContent":["// Eager entry point for @miden-sdk/miden-sdk.\n//\n// Awaits WASM initialization at module top level, so importing this module\n// guarantees that any wasm-bindgen constructor (`new RpcClient(...)`,\n// `AccountId.fromHex(...)`, `TransactionProver.newRemoteProver(...)`, etc.)\n// is safe to call synchronously on the next line. No explicit\n// `await MidenClient.ready()` / `isReady` gate is required.\n//\n// This is the default entry (`@miden-sdk/miden-sdk` → `./dist/eager.js`).\n//\n// When NOT to use this entry:\n// - **Capacitor mobile apps** (Miden Wallet iOS/Android): Capacitor's\n//   `capacitor://localhost` scheme handler interacts poorly with top-level\n//   await in the main WKWebView. Verified empirically: TLA in a Capacitor\n//   host WKWebView hangs module evaluation indefinitely, while the same\n//   TLA in the dApp-browser WKWebView (vanilla HTTPS) resolves in <100ms.\n// - **Next.js / SSR**: TLA blocks server-side module evaluation.\n// - **Framework adapters (@miden-sdk/react, etc.)**: they manage readiness\n//   via their own state machine (e.g. `isReady`) and should not impose\n//   TLA on consumer bundles.\n//\n// For those contexts, import from `@miden-sdk/miden-sdk/lazy` — identical\n// API surface, no top-level await, callers are responsible for awaiting\n// `MidenClient.ready()` (or the equivalent) before touching wasm-bindgen\n// types.\nimport { getWasmOrThrow } from \"./index.js\";\n\nawait getWasmOrThrow();\n\nexport * from \"./index.js\";\n"],"names":[],"mappings":";;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,MAAM,cAAc,EAAE;;;;"}

package/dist/index.d.ts

@@ -4,6 +4,13 @@ export * from "./crates/miden_client_web";
 // Re-export all simplified API types
 export * from "./api-types";
 
+// Explicit re-export to shadow the wasm-bindgen `AuthScheme` enum declared
+// in `./crates/miden_client_web` with the user-facing string constant plus
+// merged string-union type from `./api-types`. Without this, `export *`
+// makes the name ambiguous and TypeScript resolves to the crates enum,
+// breaking `AuthScheme.Falcon` / `AuthScheme.ECDSA` lookups.
+export { AuthScheme, resolveAuthScheme } from "./api-types";
+
 // Import types needed for the @internal class declarations below
 import type {
   WebClient as WasmWebClientBase,