@miden-sdk/miden-sdk 0.14.4 → 0.15.0-alpha.4

package/dist/index.js

@@ -1,5 +1,5 @@
 import loadWasm from './wasm.js';
-export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkId, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, 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, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, setupLogging } from './Cargo-Bwjf7IkR.js';
+export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkId, NetworkNoteStatusInfo, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapEntryJs, StorageMapInfo, StorageMapUpdate, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, setupLogging } from './Cargo-CVlXCH_2.js';
 
 const WorkerAction = Object.freeze({
   INIT: "init",
@@ -108,6 +108,7 @@ async function acquireSyncLock(dbId, timeoutMs = 0) {
       }
 
       const onResult = (result) => {
+        /* v8 ignore next 1 -- timeoutId only set when timeoutMs>0 AND another sync is in progress; combo rare in tests */
         if (timeoutId) clearTimeout(timeoutId);
         resolve({ acquired: false, coalescedResult: result });
       };
@@ -153,6 +154,7 @@ async function acquireSyncLock(dbId, timeoutMs = 0) {
 
       navigator.locks
         .request(lockName, { mode: "exclusive" }, async () => {
+          /* v8 ignore next 3 -- race: lock granted after timeout or newer generation */
           if (timedOut || state.syncGeneration !== currentGeneration) {
             return;
           }
@@ -165,6 +167,9 @@ async function acquireSyncLock(dbId, timeoutMs = 0) {
           });
         })
         .catch((err) => {
+          /* v8 ignore next 5 -- catch path requires Web Locks rejection combined with
+             optional timeout; tested via "rejects when Web Locks request rejects" but
+             the timeoutId-set branch needs Web Locks + timeout simultaneously */
           if (timeoutId) clearTimeout(timeoutId);
           if (state.syncGeneration === currentGeneration) {
             state.inProgress = false;
@@ -540,12 +545,21 @@ class AccountsResource {
     const authComponent =
       wasm.AccountComponent.createAuthComponentFromSecretKey(opts.auth);
 
+    // Schema commitment from `build()` is not a substitute for contract code; require explicit
+    // `components` so auth-only contracts are rejected at this layer.
+    const components = opts.components ?? [];
+    if (components.length === 0) {
+      throw new Error(
+        "Contract accounts require at least one non-auth procedure: pass at least one entry in `components`."
+      );
+    }
+
     let builder = new wasm.AccountBuilder(opts.seed)
       .accountType(accountTypeEnum)
       .storageMode(storageMode)
       .withAuthComponent(authComponent);
 
-    for (const component of opts.components ?? []) {
+    for (const component of components) {
       builder = builder.withComponent(component);
     }
 
@@ -587,7 +601,9 @@ class AccountsResource {
     if (!account) {
       throw new Error(`Account not found: ${id.toString()}`);
     }
-    const keys = await this.#inner.keystore.getCommitments(id);
+    const keys = this.#inner.keystore
+      ? await this.#inner.keystore.getCommitments(id)
+      : await this.#inner.getPublicKeyCommitmentsOfAccount(id);
     return {
       account,
       vault: account.vault(),
@@ -602,7 +618,7 @@ class AccountsResource {
     const wasm = await this.#getWasm();
     const accountId = resolveAccountRef(accountRef, wasm);
     const faucetId = resolveAccountRef(tokenRef, wasm);
-    const reader = this.#inner.accountReader(accountId);
+    const reader = await this.#inner.accountReader(accountId);
     return await reader.getBalance(faucetId);
   }
 
@@ -1195,13 +1211,8 @@ class TransactionsResource {
   async #submitOrSubmitWithProver(accountId, request, perCallProver) {
     const result = await this.#inner.executeTransaction(accountId, request);
     const prover = perCallProver ?? this.#client.defaultProver;
-    // Use proveTransactionWithProver (by-reference) when a prover is
-    // provided, so the JS-side handle is NOT consumed by wasm-bindgen.
-    // Passing the prover by value would transfer ownership and invalidate
-    // the JS object after one call, causing silent fallback to local
-    // proving on reuse.
     const proven = prover
-      ? await this.#inner.proveTransactionWithProver(result, prover)
+      ? await this.#inner.proveTransaction(result, prover)
       : await this.#inner.proveTransaction(result);
     const txId = result.id();
     const height = await this.#inner.submitProvenTransaction(proven, result);
@@ -1412,7 +1423,7 @@ class CompilerResource {
   async component({ code, slots = [], supportAllTypes = true }) {
     this.#client?.assertNotTerminated();
     const wasm = await this.#getWasm();
-    const builder = this.#inner.createCodeBuilder();
+    const builder = await this.#inner.createCodeBuilder();
     const compiled = builder.compileAccountComponentCode(code);
     const component = wasm.AccountComponent.compile(compiled, slots);
     return supportAllTypes ? component.withSupportsAllTypes() : component;
@@ -1428,7 +1439,7 @@ class CompilerResource {
     this.#client?.assertNotTerminated();
     // Ensure WASM is initialized (result unused — only #inner needs it)
     await this.#getWasm();
-    const builder = this.#inner.createCodeBuilder();
+    const builder = await this.#inner.createCodeBuilder();
     linkLibraries(builder, libraries);
     return builder.compileTxScript(code);
   }
@@ -1442,7 +1453,7 @@ class CompilerResource {
   async noteScript({ code, libraries = [] }) {
     this.#client?.assertNotTerminated();
     await this.#getWasm();
-    const builder = this.#inner.createCodeBuilder();
+    const builder = await this.#inner.createCodeBuilder();
     linkLibraries(builder, libraries);
     return builder.compileNoteScript(code);
   }
@@ -1478,32 +1489,47 @@ class KeystoreResource {
 
   async insert(accountId, secretKey) {
     this.#client.assertNotTerminated();
-    const ks = this.#inner.keystore;
-    return await ks.insert(accountId, secretKey);
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.insert(accountId, secretKey);
+    }
+    return await this.#inner.addAccountSecretKeyToWebStore(
+      accountId,
+      secretKey
+    );
   }
 
   async get(pubKeyCommitment) {
     this.#client.assertNotTerminated();
-    const ks = this.#inner.keystore;
-    return await ks.get(pubKeyCommitment);
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.get(pubKeyCommitment);
+    }
+    return await this.#inner.getAccountAuthByPubKeyCommitment(pubKeyCommitment);
   }
 
   async remove(pubKeyCommitment) {
     this.#client.assertNotTerminated();
-    const ks = this.#inner.keystore;
-    return await ks.remove(pubKeyCommitment);
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.remove(pubKeyCommitment);
+    }
+    throw new Error("remove() is not supported on this platform");
   }
 
   async getCommitments(accountId) {
     this.#client.assertNotTerminated();
-    const ks = this.#inner.keystore;
-    return await ks.getCommitments(accountId);
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.getCommitments(accountId);
+    }
+    return await this.#inner.getPublicKeyCommitmentsOfAccount(accountId);
   }
 
   async getAccountId(pubKeyCommitment) {
     this.#client.assertNotTerminated();
-    const ks = this.#inner.keystore;
-    return await ks.getAccountId(pubKeyCommitment);
+    if (this.#inner.keystore) {
+      return await this.#inner.keystore.getAccountId(pubKeyCommitment);
+    }
+    const account =
+      await this.#inner.getAccountByKeyCommitment(pubKeyCommitment);
+    return account ? account.id() : undefined;
   }
 }
 
@@ -1576,14 +1602,16 @@ class MidenClient {
         options?.storeName,
         options.keystore.getKey,
         options.keystore.insertKey,
-        options.keystore.sign
+        options.keystore.sign,
+        options?.debugMode
       );
     } else {
       inner = await WebClientClass.createClient(
         rpcUrl,
         noteTransportUrl,
         seed,
-        options?.storeName
+        options?.storeName,
+        options?.debugMode
       );
     }
 
@@ -1640,32 +1668,6 @@ class MidenClient {
     });
   }
 
-  /**
-   * Resolves once the WASM module is initialized and safe to use.
-   *
-   * Idempotent and shared across callers: the underlying loader memoizes the
-   * in-flight promise, so concurrent `ready()` calls await the same
-   * initialization and post-init callers resolve immediately from a cached
-   * module. Safe to call from `MidenProvider`, tutorial helpers, and any
-   * other consumer simultaneously.
-   *
-   * Useful on the `/lazy` entry (e.g. Next.js / Capacitor), where no
-   * top-level await runs at import time. On the default (eager) entry this
-   * is redundant — importing the module already awaits WASM — but calling it
-   * is still harmless.
-   *
-   * @returns {Promise<void>} Resolves when WASM is initialized.
-   */
-  static async ready() {
-    const getWasm = MidenClient._getWasmOrThrow;
-    if (!getWasm) {
-      throw new Error(
-        "MidenClient not initialized. Import from the SDK package entry point."
-      );
-    }
-    await getWasm();
-  }
-
   /**
    * Creates a mock client for testing.
    *
@@ -1722,54 +1724,6 @@ class MidenClient {
     return await this.#inner.getSyncHeight();
   }
 
-  /**
-   * Resolves once every serialized WASM call that was already on the
-   * internal `_serializeWasmCall` 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 —
-   * intentional, so a caller can drain and proceed without being blocked
-   * indefinitely by concurrent workload.
-   *
-   * Caveat for `syncState`: `syncStateWithTimeout` awaits the sync lock
-   * (`acquireSyncLock`, which uses Web Locks) BEFORE putting its WASM
-   * call onto the chain, so a `syncState` that is queued on the sync
-   * lock — but has not yet begun its WASM phase — is not visible to
-   * `waitForIdle` and will not be awaited. Other methods (`newWallet`,
-   * `executeTransaction`, etc.) route through the chain synchronously
-   * on call and are always observed.
-   *
-   * Safe to call at any time; returns immediately if nothing was in
-   * flight.
-   *
-   * @returns {Promise<void>}
-   */
-  async waitForIdle() {
-    this.assertNotTerminated();
-    await this.#inner.waitForIdle();
-  }
-
-  /**
-   * 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. Call immediately after catching a failed
-   * `transactions.submit` / `transactions.send` / `transactions.consume`.
-   *
-   * @returns {any} The raw thrown value, or `null`.
-   */
-  lastAuthError() {
-    this.assertNotTerminated();
-    return this.#inner.lastAuthError();
-  }
-
   /**
    * Terminates the underlying Web Worker. After this, all method calls will throw.
    */
@@ -1791,9 +1745,9 @@ class MidenClient {
    *
    * @returns {string} The store identifier.
    */
-  storeIdentifier() {
+  async storeIdentifier() {
     this.assertNotTerminated();
-    return this.#inner.storeIdentifier();
+    return await this.#inner.storeIdentifier();
   }
 
   // ── Mock-only methods ──
@@ -2006,6 +1960,339 @@ function buildNoteAssets(assets, wasm) {
   return new wasm.NoteAssets(fungibleAssets);
 }
 
+/**
+ * StorageView wraps the raw WASM AccountStorage to provide a developer-friendly
+ * (and AI-agent-friendly) API.
+ *
+ * Key behavior: `getItem()` returns a `StorageResult` that works intuitively for
+ * both Value and StorageMap slots. The result has `.toBigInt()`, `.toHex()`, and
+ * `.toString()` methods that do the right thing automatically. For StorageMap slots,
+ * `.entries` provides access to all map entries.
+ *
+ * Numeric ergonomics: `StorageResult` is usable directly in template strings,
+ * JSX, and arithmetic via `toString()` (lossless, BigInt-backed) and `valueOf()`
+ * (returns a JS number for values that fit, throws on overflow — never silently
+ * corrupts). For exact u64 access use `.toBigInt()`.
+ *
+ * The raw WASM AccountStorage is still accessible via `.raw` for advanced use cases
+ * that need the original behavior (e.g., comparing map commitment roots).
+ */
+/** @param {string} hex @param {typeof Word} WordClass @returns {Word | undefined} */
+function hexToWord(hex, WordClass) {
+  if (!hex || !WordClass) return undefined;
+  try {
+    return WordClass.fromHex(hex);
+  } catch {
+    return undefined;
+  }
+}
+
+class StorageView {
+  #storage;
+  #WordClass;
+
+  /**
+   * @param {AccountStorage} wasmStorage
+   * @param {typeof Word} WordClass
+   */
+  constructor(wasmStorage, WordClass) {
+    this.#storage = wasmStorage;
+    this.#WordClass = WordClass;
+  }
+
+  /**
+   * The raw WASM AccountStorage, for cases where you need the original
+   * primitive behavior (e.g., reading map commitment roots via raw.getItem()).
+   */
+  get raw() {
+    return this.#storage;
+  }
+
+  /**
+   * Returns the commitment to the full account storage.
+   */
+  commitment() {
+    return this.#storage.commitment();
+  }
+
+  /**
+   * Returns the names of all storage slots on this account.
+   * @returns {string[]}
+   */
+  getSlotNames() {
+    return this.#storage.getSlotNames();
+  }
+
+  /**
+   * Returns a StorageResult for the given slot.
+   *
+   * The result has convenience methods that work for both Value and StorageMap slots:
+   * - `.toBigInt()` — first felt as BigInt (full u64 precision)
+   * - `.toHex()` — first felt's Word as hex string
+   * - `.toString()` — renders as the BigInt value (works in JSX: {result})
+   * - `.isMap` — true if this is a StorageMap slot
+   * - `.entries` — all map entries (undefined for Value slots)
+   * - `.word` — the underlying Word value
+   *
+   * The result is also usable directly in arithmetic (`+result`, `result * 2`)
+   * via `valueOf()`, which returns a JS number for values that fit and throws
+   * `RangeError` for values exceeding `Number.MAX_SAFE_INTEGER` — use `.toBigInt()`
+   * for exact access to large u64 values.
+   *
+   * For explicit key-based map reads, use `getMapItem(slotName, key)`.
+   * For the raw commitment hash, use `raw.getItem(slotName)`.
+   *
+   * @param {string} slotName
+   * @returns {StorageResult | undefined}
+   */
+  getItem(slotName) {
+    // Type detection + value retrieval in one pass.
+    // We call getMapEntries to detect maps, but defer parsing the entries
+    // until .entries is actually accessed (lazy). Only the first entry's
+    // Word is parsed eagerly for the convenience methods (toBigInt, etc.).
+    const rawEntries = this.#storage.getMapEntries(slotName);
+    if (rawEntries !== undefined && rawEntries !== null) {
+      // StorageMap — parse only the first entry eagerly
+      const firstWord =
+        rawEntries.length > 0
+          ? hexToWord(rawEntries[0].value, this.#WordClass)
+          : undefined;
+      return new StorageResult(firstWord, true, rawEntries, this.#WordClass);
+    }
+
+    // Value slot — use raw getItem
+    const word = this.#storage.getItem(slotName);
+    if (!word) return undefined;
+    return new StorageResult(word, false, undefined, this.#WordClass);
+  }
+
+  /**
+   * Returns the value for a key in a StorageMap slot.
+   * Delegates directly to the raw WASM method.
+   *
+   * @param {string} slotName
+   * @param {Word} key
+   * @returns {Word | undefined}
+   */
+  getMapItem(slotName, key) {
+    return this.#storage.getMapItem(slotName, key);
+  }
+
+  /**
+   * Get all key-value pairs from a StorageMap slot.
+   * Returns undefined if the slot isn't a map, or an empty array if the map is empty.
+   */
+  getMapEntries(slotName) {
+    return this.#storage.getMapEntries(slotName);
+  }
+
+  /**
+   * Returns the commitment root of a storage slot as a Word.
+   *
+   * For Value slots, this is the stored Word itself.
+   * For StorageMap slots, this is the Merkle root hash of the map — useful for:
+   * - Verifying state hasn't changed between transactions
+   * - Merkle inclusion proofs against the account state
+   * - Comparing map state across accounts or sync cycles
+   *
+   * This is the raw protocol-level value. For reading stored data, use `getItem()`.
+   *
+   * @param {string} slotName
+   * @returns {Word | undefined}
+   */
+  getCommitment(slotName) {
+    return this.#storage.getItem(slotName);
+  }
+}
+
+/**
+ * Result of reading a storage slot. Works for both Value and StorageMap slots.
+ *
+ * Provides a unified interface so code like `storage.getItem(name).toBigInt()`
+ * works regardless of the underlying slot type.
+ *
+ * For StorageMap slots, the convenience methods (toHex, toBigInt) operate on
+ * the first entry's value. The full map data is available via `.entries`.
+ * Note: Miden storage maps are Merkle-based, so "first" is determined by key hash
+ * order — deterministic for a given map state, but not meaningful as an ordering.
+ */
+class StorageResult {
+  #word;
+  #isMap;
+  #rawEntries; // Raw JsStorageMapEntry[] from WASM — parsed lazily
+  #parsedEntries; // Parsed entries with Word objects — created on first .entries access
+  #WordClass;
+
+  /**
+   * @param {Word | undefined} word — the primary Word value (first entry for maps)
+   * @param {boolean} isMap — whether this came from a StorageMap slot
+   * @param {Array | undefined} rawEntries — raw WASM entries (parsed lazily on .entries access)
+   * @param {typeof Word} WordClass — Word constructor for hex parsing
+   */
+  constructor(word, isMap, rawEntries, WordClass) {
+    this.#word = word;
+    this.#isMap = isMap;
+    this.#rawEntries = rawEntries;
+    this.#WordClass = WordClass;
+  }
+
+  /** True if this slot is a StorageMap. */
+  get isMap() {
+    return this.#isMap;
+  }
+
+  /**
+   * All entries from a StorageMap slot (lazily parsed on first access).
+   * Each entry has { key: string (hex), value: string (hex), word: Word | undefined }.
+   * Returns undefined for Value slots.
+   */
+  get entries() {
+    if (!this.#isMap) return undefined;
+    if (this.#parsedEntries) return this.#parsedEntries;
+    if (!this.#rawEntries) return [];
+
+    // Parse entries lazily — only when the user actually accesses .entries
+    this.#parsedEntries = this.#rawEntries.map((e) => ({
+      key: e.key,
+      value: e.value,
+      word: hexToWord(e.value, this.#WordClass),
+    }));
+    this.#rawEntries = undefined; // Free raw entries
+    return this.#parsedEntries;
+  }
+
+  /**
+   * The underlying Word value.
+   * For Value slots: the stored Word.
+   * For StorageMap slots: the first entry's value as a Word (or undefined if empty).
+   */
+  get word() {
+    return this.#word;
+  }
+
+  /**
+   * Returns all four Felts of the stored Word as an array.
+   * Pass-through to Word.toFelts() — ensures code that expects a Word-like
+   * object (e.g., `result.toFelts()[0].asInt()`) works on StorageResult.
+   * @returns {Felt[]}
+   */
+  toFelts() {
+    if (!this.#word) return [];
+    return this.#word.toFelts();
+  }
+
+  /**
+   * The first Felt of the stored Word.
+   * Returns the WASM Felt object — use .asInt() to get its BigInt value.
+   * @returns {Felt | undefined}
+   */
+  felt() {
+    if (!this.#word) return undefined;
+    const felts = this.#word.toFelts();
+    return felts?.[0];
+  }
+
+  /**
+   * First felt as a BigInt. Preserves full u64 precision.
+   * @returns {bigint}
+   */
+  toBigInt() {
+    if (!this.#word) return 0n;
+    return wordToBigInt(this.#word);
+  }
+
+  /**
+   * The Word's hex representation.
+   * For Value slots: the stored Word hex.
+   * For StorageMap slots: the first entry's value Word hex.
+   * @returns {string}
+   */
+  toHex() {
+    if (!this.#word) return "0x" + "0".repeat(64);
+    return this.#word.toHex();
+  }
+
+  /**
+   * Renders as the BigInt value (lossless). Makes `{storageResult}` work in JSX
+   * and template literals: `` `value: ${result}` ``.
+   * @returns {string}
+   */
+  toString() {
+    return this.toBigInt().toString();
+  }
+
+  /**
+   * JSON serialization — returns the value as a string to avoid
+   * precision loss for large u64 felt values.
+   */
+  toJSON() {
+    return this.toBigInt().toString();
+  }
+
+  /**
+   * Allows `+result`, `result * 2`, etc. to work as expected.
+   *
+   * Returns a JS number for values that fit in `Number.MAX_SAFE_INTEGER`
+   * (2^53 - 1). For larger u64 values, throws `RangeError` rather than
+   * silently losing precision — use `.toBigInt()` to access the exact value.
+   *
+   * @returns {number}
+   * @throws {RangeError} if the underlying felt exceeds Number.MAX_SAFE_INTEGER
+   */
+  valueOf() {
+    const big = this.toBigInt();
+    if (big > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new RangeError(
+        `StorageResult value ${big} exceeds Number.MAX_SAFE_INTEGER ` +
+          `(${Number.MAX_SAFE_INTEGER}) — use .toBigInt() to read the exact value.`
+      );
+    }
+    return Number(big);
+  }
+}
+
+/**
+ * Convert a Word's first felt to a BigInt.
+ * Uses BigInt to preserve full u64 precision (felts are u64-backed).
+ * Handles the little-endian byte order of felt serialization.
+ *
+ * @param {Word} word
+ * @returns {bigint}
+ */
+function wordToBigInt(word) {
+  try {
+    const hex = word.toHex();
+    // Word.toHex() returns "0x" + 64 hex chars (4 felts × 16 hex chars each).
+    // Each felt is serialized as 8 little-endian bytes, so we take the first 16
+    // hex chars (first felt) and reverse the byte pairs to get the integer value.
+    const feltHex = hex.slice(2, 18);
+    const bytes = feltHex.match(/../g);
+    if (!bytes) return 0n;
+    return BigInt("0x" + bytes.reverse().join(""));
+  } catch {
+    return 0n;
+  }
+}
+
+/**
+ * Install the StorageView wrapper on Account.prototype.storage().
+ * After this, `account.storage()` returns a StorageView instead of raw AccountStorage.
+ *
+ * @param {object} wasmModule — the loaded WASM module containing Account, Word, etc.
+ */
+function installStorageView(wasmModule) {
+  const AccountProto = wasmModule.Account?.prototype;
+  if (!AccountProto || !AccountProto.storage) return;
+
+  const originalStorage = AccountProto.storage;
+  const WordClass = wasmModule.Word;
+
+  AccountProto.storage = function () {
+    const raw = originalStorage.call(this);
+    return new StorageView(raw, WordClass);
+  };
+}
+
 const AccountType = Object.freeze({
   // WASM-compatible numeric values — usable with AccountBuilder directly
   FungibleFaucet: 0,
@@ -2040,43 +2327,6 @@ const Linking = Object.freeze({
   Static: "static",
 });
 
-// Method classification sets — used by scripts/check-method-classification.js to ensure
-// every WASM export is explicitly categorised. Update when adding new WASM methods.
-//
-// Note on `SYNC_METHODS`: the classifier is "synchronous in JS" — i.e.
-// `pub fn ...` in Rust, not `pub async fn ...`. Two sub-cases:
-//   1. Factory methods that return a non-Promise value (`accountReader`
-//      returns `AccountReader`; the transaction-request builders return
-//      `TransactionRequestBuilder`; `createCodeBuilder` returns a builder).
-//      Wrapping these in `_serializeWasmCall` would turn their return
-//      value into `Promise<T>` and break callers that use the result
-//      immediately (e.g. `const reader = client.accountReader(id);
-//      await reader.nonce();`).
-//   2. Sync methods that still take `&mut self` in Rust (`proveBlock`,
-//      `serializeMockChain`, `setDebugMode`). Safe to opt out because JS
-//      is single-threaded — the event loop cannot interleave another
-//      call during their synchronous execution, so the RefCell borrow
-//      is always released before any other borrow can start.
-// Do NOT move a sync-in-JS method into `WRITE_METHODS` / `READ_METHODS`
-// just because it takes `&mut self` or `&self`; wrapping changes its
-// return shape and breaks every caller.
-const SYNC_METHODS = new Set([
-  "accountReader",
-  "buildSwapTag",
-  "createCodeBuilder",
-  "lastAuthError",
-  "newConsumeTransactionRequest",
-  "newMintTransactionRequest",
-  "newSendTransactionRequest",
-  "newSwapTransactionRequest",
-  "proveBlock",
-  "serializeMockChain",
-  "serializeMockNoteTransportNode",
-  "setDebugMode",
-  "storeIdentifier",
-  "usesMockChain",
-]);
-
 const MOCK_STORE_NAME = "mock_client_db";
 
 const buildTypedArraysExport = (exportObject) => {
@@ -2133,6 +2383,9 @@ const ensureWasm = async () => {
         }
         // Set WASM module for standalone utilities
         _setWasm(module);
+        // Install StorageView: account.storage() now returns a developer-friendly
+        // wrapper that makes getItem() work correctly for StorageMap slots.
+        installStorageView(module);
       }
       return module;
     });
@@ -2177,16 +2430,6 @@ const getWasmOrThrow = async () => {
 /**
  * Create a Proxy that forwards missing properties to the underlying WASM
  * WebClient.
- *
- * Async proxy-fallback methods (every WASM method that borrows the
- * WebClient's RefCell — reads included, since `&self` and `&mut self` both
- * trip wasm-bindgen's "recursive use of an object detected" panic if
- * another borrow is live) are routed through `_serializeWasmCall` so they
- * queue on the same chain as the explicitly-wrapped methods.
- *
- * `SYNC_METHODS` opts out: they are synchronous in JS and wrapping them
- * would change their return type to `Promise<T>`, which is a breaking
- * change for consumers that use them as plain getters or builders.
  */
 function createClientProxy(instance) {
   return new Proxy(instance, {
@@ -2197,13 +2440,7 @@ function createClientProxy(instance) {
       if (target.wasmWebClient && prop in target.wasmWebClient) {
         const value = target.wasmWebClient[prop];
         if (typeof value === "function") {
-          if (typeof prop === "string" && SYNC_METHODS.has(prop)) {
-            return value.bind(target.wasmWebClient);
-          }
-          return (...args) =>
-            target._serializeWasmCall(() =>
-              value.apply(target.wasmWebClient, args)
-            );
+          return value.bind(target.wasmWebClient);
         }
         return value;
       }
@@ -2434,13 +2671,6 @@ class WebClient {
    * Serialize a WASM call that requires exclusive (&mut self) access.
    * Concurrent calls are queued and executed one at a time.
    *
-   * Wraps both the direct (in-thread) path and the worker-dispatched path.
-   * On the worker path this is redundant with the worker's own message queue,
-   * but harmless (the chain resolves immediately on the main thread once the
-   * worker's postMessage returns). On the direct path it is load-bearing —
-   * without it, concurrent main-thread callers would panic with
-   * "recursive use of an object detected" (wasm-bindgen's internal RefCell).
-   *
    * @param {() => Promise<any>} fn - The async function to execute.
    * @returns {Promise<any>} The result of fn.
    */
@@ -2450,35 +2680,6 @@ class WebClient {
     return result;
   }
 
-  /**
-   * Returns a promise that resolves once every serialized WASM call that
-   * was already on `_wasmCallChain` when `waitForIdle()` was called has
-   * settled. Use this from callers that need to perform a non-WASM-side
-   * action (e.g. clear an in-memory auth key) AFTER any in-flight
-   * execute / submit / sync has completed, so the WASM kernel's auth
-   * callback doesn't race with the key being cleared.
-   *
-   * Does NOT wait for calls enqueued after `waitForIdle()` returns —
-   * this is intentional, so a caller can drain and then proceed without
-   * being blocked indefinitely by a concurrent workload.
-   *
-   * Caveat for `syncState`: `syncStateWithTimeout` awaits
-   * `acquireSyncLock` (Web Locks) BEFORE wrapping its WASM call in
-   * `_serializeWasmCall`, so a sync that is queued on the sync lock but
-   * has not yet reached its WASM phase is not on the chain and will not
-   * be awaited. Every other serialized method (`executeTransaction`,
-   * `newWallet`, `submitNewTransaction`, `proveTransaction`,
-   * `applyTransaction`, and the proxy-fallback reads) routes through
-   * the chain synchronously on call and is always observed.
-   *
-   * @returns {Promise<void>}
-   */
-  async waitForIdle() {
-    // Chain on `_wasmCallChain`; by the time this resolves, any in-flight
-    // serialized call has settled. Catch so the chain state doesn't leak.
-    await this._wasmCallChain.catch(() => {});
-  }
-
   // TODO: This will soon conflict with some changes in main.
   // More context here:
   // https://github.com/0xMiden/miden-client/pull/1645?notification_referrer_id=NT_kwHOA1yg7NoAJVJlcG9zaXRvcnk7NjU5MzQzNzAyO0lzc3VlOzM3OTY4OTU1Nzk&notifications_query=is%3Aunread#discussion_r2696075480
@@ -2684,171 +2885,147 @@ class WebClient {
   }
 
   async submitNewTransaction(accountId, transactionRequest) {
-    return this._serializeWasmCall(async () => {
-      try {
-        if (!this.worker) {
-          const wasmWebClient = await this.getWasmWebClient();
-          return await wasmWebClient.submitNewTransaction(
-            accountId,
-            transactionRequest
-          );
-        }
-
-        const wasm = await getWasmOrThrow();
-        const serializedTransactionRequest = transactionRequest.serialize();
-        const result = await this.callMethodWithWorker(
-          MethodName.SUBMIT_NEW_TRANSACTION,
-          accountId.toString(),
-          serializedTransactionRequest
+    try {
+      if (!this.worker) {
+        const wasmWebClient = await this.getWasmWebClient();
+        return await wasmWebClient.submitNewTransaction(
+          accountId,
+          transactionRequest
         );
+      }
 
-        const transactionResult = wasm.TransactionResult.deserialize(
-          new Uint8Array(result.serializedTransactionResult)
-        );
+      const wasm = await getWasmOrThrow();
+      const serializedTransactionRequest = transactionRequest.serialize();
+      const result = await this.callMethodWithWorker(
+        MethodName.SUBMIT_NEW_TRANSACTION,
+        accountId.toString(),
+        serializedTransactionRequest
+      );
 
-        return transactionResult.id();
-      } catch (error) {
-        console.error("INDEX.JS: Error in submitNewTransaction:", error);
-        throw error;
-      }
-    });
+      const transactionResult = wasm.TransactionResult.deserialize(
+        new Uint8Array(result.serializedTransactionResult)
+      );
+
+      return transactionResult.id();
+    } catch (error) {
+      console.error("INDEX.JS: Error in submitNewTransaction:", error);
+      throw error;
+    }
   }
 
   async submitNewTransactionWithProver(accountId, transactionRequest, prover) {
-    return this._serializeWasmCall(async () => {
-      try {
-        if (!this.worker) {
-          const wasmWebClient = await this.getWasmWebClient();
-          return await wasmWebClient.submitNewTransactionWithProver(
-            accountId,
-            transactionRequest,
-            prover
-          );
-        }
-
-        const wasm = await getWasmOrThrow();
-        const serializedTransactionRequest = transactionRequest.serialize();
-        const proverPayload = prover.serialize();
-        const result = await this.callMethodWithWorker(
-          MethodName.SUBMIT_NEW_TRANSACTION_WITH_PROVER,
-          accountId.toString(),
-          serializedTransactionRequest,
-          proverPayload
+    try {
+      if (!this.worker) {
+        const wasmWebClient = await this.getWasmWebClient();
+        return await wasmWebClient.submitNewTransactionWithProver(
+          accountId,
+          transactionRequest,
+          prover
         );
+      }
 
-        const transactionResult = wasm.TransactionResult.deserialize(
-          new Uint8Array(result.serializedTransactionResult)
-        );
+      const wasm = await getWasmOrThrow();
+      const serializedTransactionRequest = transactionRequest.serialize();
+      const proverPayload = prover.serialize();
+      const result = await this.callMethodWithWorker(
+        MethodName.SUBMIT_NEW_TRANSACTION_WITH_PROVER,
+        accountId.toString(),
+        serializedTransactionRequest,
+        proverPayload
+      );
 
-        return transactionResult.id();
-      } catch (error) {
-        console.error(
-          "INDEX.JS: Error in submitNewTransactionWithProver:",
-          error
-        );
-        throw error;
-      }
-    });
+      const transactionResult = wasm.TransactionResult.deserialize(
+        new Uint8Array(result.serializedTransactionResult)
+      );
+
+      return transactionResult.id();
+    } catch (error) {
+      console.error(
+        "INDEX.JS: Error in submitNewTransactionWithProver:",
+        error
+      );
+      throw error;
+    }
   }
 
   async executeTransaction(accountId, transactionRequest) {
-    return this._serializeWasmCall(async () => {
-      try {
-        if (!this.worker) {
-          const wasmWebClient = await this.getWasmWebClient();
-          return await wasmWebClient.executeTransaction(
-            accountId,
-            transactionRequest
-          );
-        }
-
-        const wasm = await getWasmOrThrow();
-        const serializedTransactionRequest = transactionRequest.serialize();
-        const serializedResultBytes = await this.callMethodWithWorker(
-          MethodName.EXECUTE_TRANSACTION,
-          accountId.toString(),
-          serializedTransactionRequest
-        );
-
-        return wasm.TransactionResult.deserialize(
-          new Uint8Array(serializedResultBytes)
+    try {
+      if (!this.worker) {
+        const wasmWebClient = await this.getWasmWebClient();
+        return await wasmWebClient.executeTransaction(
+          accountId,
+          transactionRequest
         );
-      } catch (error) {
-        console.error("INDEX.JS: Error in executeTransaction:", error);
-        throw error;
       }
-    });
+
+      const wasm = await getWasmOrThrow();
+      const serializedTransactionRequest = transactionRequest.serialize();
+      const serializedResultBytes = await this.callMethodWithWorker(
+        MethodName.EXECUTE_TRANSACTION,
+        accountId.toString(),
+        serializedTransactionRequest
+      );
+
+      return wasm.TransactionResult.deserialize(
+        new Uint8Array(serializedResultBytes)
+      );
+    } catch (error) {
+      console.error("INDEX.JS: Error in executeTransaction:", error);
+      throw error;
+    }
   }
 
   async proveTransaction(transactionResult, prover) {
-    return this._serializeWasmCall(async () => {
-      try {
-        if (!this.worker) {
-          const wasmWebClient = await this.getWasmWebClient();
-          return prover
-            ? await wasmWebClient.proveTransactionWithProver(
-                transactionResult,
-                prover
-              )
-            : await wasmWebClient.proveTransaction(transactionResult);
-        }
-
-        const wasm = await getWasmOrThrow();
-        const serializedTransactionResult = transactionResult.serialize();
-        const proverPayload = prover ? prover.serialize() : null;
+    try {
+      if (!this.worker) {
+        const wasmWebClient = await this.getWasmWebClient();
+        return await wasmWebClient.proveTransaction(transactionResult, prover);
+      }
 
-        const serializedProvenBytes = await this.callMethodWithWorker(
-          MethodName.PROVE_TRANSACTION,
-          serializedTransactionResult,
-          proverPayload
-        );
+      const wasm = await getWasmOrThrow();
+      const serializedTransactionResult = transactionResult.serialize();
+      const proverPayload = prover ? prover.serialize() : null;
 
-        return wasm.ProvenTransaction.deserialize(
-          new Uint8Array(serializedProvenBytes)
-        );
-      } catch (error) {
-        console.error("INDEX.JS: Error in proveTransaction:", error);
-        throw error;
-      }
-    });
-  }
+      const serializedProvenBytes = await this.callMethodWithWorker(
+        MethodName.PROVE_TRANSACTION,
+        serializedTransactionResult,
+        proverPayload
+      );
 
-  // Delegates to `proveTransaction`, which already routes through
-  // `_serializeWasmCall` and dispatches to the WASM `proveTransactionWithProver`
-  // binding when `prover` is present. Kept as a wrapper (rather than elided)
-  // so the method classification lint sees an explicit match for the WASM
-  // method name.
-  async proveTransactionWithProver(transactionResult, prover) {
-    return this.proveTransaction(transactionResult, prover);
+      return wasm.ProvenTransaction.deserialize(
+        new Uint8Array(serializedProvenBytes)
+      );
+    } catch (error) {
+      console.error("INDEX.JS: Error in proveTransaction:", error);
+      throw error;
+    }
   }
 
   async applyTransaction(transactionResult, submissionHeight) {
-    return this._serializeWasmCall(async () => {
-      try {
-        if (!this.worker) {
-          const wasmWebClient = await this.getWasmWebClient();
-          return await wasmWebClient.applyTransaction(
-            transactionResult,
-            submissionHeight
-          );
-        }
-
-        const wasm = await getWasmOrThrow();
-        const serializedTransactionResult = transactionResult.serialize();
-        const serializedUpdateBytes = await this.callMethodWithWorker(
-          MethodName.APPLY_TRANSACTION,
-          serializedTransactionResult,
+    try {
+      if (!this.worker) {
+        const wasmWebClient = await this.getWasmWebClient();
+        return await wasmWebClient.applyTransaction(
+          transactionResult,
           submissionHeight
         );
-
-        return wasm.TransactionStoreUpdate.deserialize(
-          new Uint8Array(serializedUpdateBytes)
-        );
-      } catch (error) {
-        console.error("INDEX.JS: Error in applyTransaction:", error);
-        throw error;
       }
-    });
+
+      const wasm = await getWasmOrThrow();
+      const serializedTransactionResult = transactionResult.serialize();
+      const serializedUpdateBytes = await this.callMethodWithWorker(
+        MethodName.APPLY_TRANSACTION,
+        serializedTransactionResult,
+        submissionHeight
+      );
+
+      return wasm.TransactionStoreUpdate.deserialize(
+        new Uint8Array(serializedUpdateBytes)
+      );
+    } catch (error) {
+      console.error("INDEX.JS: Error in applyTransaction:", error);
+      throw error;
+    }
   }
 
   /**
@@ -2887,25 +3064,21 @@ class WebClient {
         return lockHandle.coalescedResult;
       }
 
-      // We acquired the lock - perform the sync. Wrap the actual WASM
-      // call in _serializeWasmCall so it can't race with any other
-      // mutating method (executeTransaction, submitNewTransaction, etc.)
-      // on the same WebClient. The outer coalescing lock stays in place
-      // so concurrent syncState callers still share one in-flight sync.
+      // We acquired the lock - perform the sync
       try {
-        const result = await this._serializeWasmCall(async () => {
-          if (!this.worker) {
-            const wasmWebClient = await this.getWasmWebClient();
-            return await wasmWebClient.syncStateImpl();
-          }
+        let result;
+        if (!this.worker) {
+          const wasmWebClient = await this.getWasmWebClient();
+          result = await wasmWebClient.syncStateImpl();
+        } else {
           const wasm = await getWasmOrThrow();
           const serializedSyncSummaryBytes = await this.callMethodWithWorker(
             MethodName.SYNC_STATE
           );
-          return wasm.SyncSummary.deserialize(
+          result = wasm.SyncSummary.deserialize(
             new Uint8Array(serializedSyncSummaryBytes)
           );
-        });
+        }
 
         // Release the lock with the result
         releaseSyncLock(dbId, result);
@@ -2984,9 +3157,9 @@ class MockWebClient extends WebClient {
     // Wait for the underlying wasmWebClient to be initialized.
     const wasmWebClient = await instance.getWasmWebClient();
     await wasmWebClient.createMockClient(
-      seed,
-      serializedMockChain,
-      serializedMockNoteTransportNode
+      seed ?? null,
+      serializedMockChain ?? null,
+      serializedMockNoteTransportNode ?? null
     );
 
     // Wait for the worker to be ready
@@ -3031,9 +3204,11 @@ class MockWebClient extends WebClient {
         if (!this.worker) {
           result = await wasmWebClient.syncStateImpl();
         } else {
-          let serializedMockChain = wasmWebClient.serializeMockChain().buffer;
-          let serializedMockNoteTransportNode =
-            wasmWebClient.serializeMockNoteTransportNode().buffer;
+          let serializedMockChain = (await wasmWebClient.serializeMockChain())
+            .buffer;
+          let serializedMockNoteTransportNode = (
+            await wasmWebClient.serializeMockNoteTransportNode()
+          ).buffer;
 
           const wasm = await getWasmOrThrow();
 
@@ -3069,9 +3244,11 @@ class MockWebClient extends WebClient {
       const wasmWebClient = await this.getWasmWebClient();
       const wasm = await getWasmOrThrow();
       const serializedTransactionRequest = transactionRequest.serialize();
-      const serializedMockChain = wasmWebClient.serializeMockChain().buffer;
-      const serializedMockNoteTransportNode =
-        wasmWebClient.serializeMockNoteTransportNode().buffer;
+      const serializedMockChain = (await wasmWebClient.serializeMockChain())
+        .buffer;
+      const serializedMockNoteTransportNode = (
+        await wasmWebClient.serializeMockNoteTransportNode()
+      ).buffer;
 
       const result = await this.callMethodWithWorker(
         MethodName.SUBMIT_NEW_TRANSACTION_MOCK,
@@ -3123,9 +3300,11 @@ class MockWebClient extends WebClient {
       const wasm = await getWasmOrThrow();
       const serializedTransactionRequest = transactionRequest.serialize();
       const proverPayload = prover.serialize();
-      const serializedMockChain = wasmWebClient.serializeMockChain().buffer;
-      const serializedMockNoteTransportNode =
-        wasmWebClient.serializeMockNoteTransportNode().buffer;
+      const serializedMockChain = (await wasmWebClient.serializeMockChain())
+        .buffer;
+      const serializedMockNoteTransportNode = (
+        await wasmWebClient.serializeMockNoteTransportNode()
+      ).buffer;
 
       const result = await this.callMethodWithWorker(
         MethodName.SUBMIT_NEW_TRANSACTION_WITH_PROVER_MOCK,
@@ -3189,5 +3368,5 @@ MidenClient._MockWasmWebClient = MockWebClient;
 MidenClient._getWasmOrThrow = getWasmOrThrow;
 _setWebClient(WebClient);
 
-export { AccountType, AuthScheme, CompilerResource, Linking, MidenArrays, MidenClient, MockWebClient as MockWasmWebClient, NoteVisibility, StorageMode, WebClient as WasmWebClient, buildSwapTag, createP2IDENote, createP2IDNote, getWasmOrThrow };
+export { AccountType, AuthScheme, CompilerResource, Linking, MidenArrays, MidenClient, MockWebClient as MockWasmWebClient, MockWebClient, NoteVisibility, StorageMode, StorageResult, StorageView, WebClient as WasmWebClient, buildSwapTag, createP2IDENote, createP2IDNote, getWasmOrThrow, wordToBigInt };
 //# sourceMappingURL=index.js.map