feat(web-client): add getMapEntries API for StorageMap iteration (0xMiden#1323)

Author: swarna1101

CHANGELOG.md

@@ -13,6 +13,7 @@
 * Implemented account lazy loading with more granular account data getters ([#1321](https://github.com/0xMiden/miden-client/pull/1321)).
 * Added `NoAuth` component to the web client ([#1330](https://github.com/0xMiden/miden-client/pull/1330)).
 * Implemented shared source manager for better error reporting ([#1275](https://github.com/0xMiden/miden-client/pull/1275)).
+* Added `getMapEntries` method to `AccountStorage` in web client for iterating storage map entries ([#1323](https://github.com/0xMiden/miden-client/pull/1323)).
 
 ### Changes
 

crates/web-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demox-labs/miden-sdk",
-  "version": "0.12.0-next.22",
+  "version": "0.12.0-next.23",
   "description": "Miden Wasm SDK",
   "collaborators": [
     "Miden",

crates/web-client/src/models/account_storage.rs

@@ -1,4 +1,5 @@
-use miden_client::account::AccountStorage as NativeAccountStorage;
+use idxdb_store::account::JsStorageMapEntry;
+use miden_client::account::{AccountStorage as NativeAccountStorage, StorageSlot};
 use wasm_bindgen::prelude::*;
 
 use crate::models::word::Word;
@@ -22,6 +23,26 @@ impl AccountStorage {
     pub fn get_map_item(&self, index: u8, key: &Word) -> Option<Word> {
         self.0.get_map_item(index, key.into()).ok().map(Into::into)
     }
+
+    /// Get all key-value pairs from the map slot at `index`.
+    /// Returns `undefined` if the slot isn't a map or `index` is out of bounds (0-255).
+    /// Returns `[]` if the map exists but is empty.
+    #[wasm_bindgen(js_name = "getMapEntries")]
+    pub fn get_map_entries(&self, index: u8) -> Option<Vec<JsStorageMapEntry>> {
+        let slots = self.0.slots();
+        match slots.get(index as usize) {
+            Some(StorageSlot::Map(map)) => Some(
+                map.entries()
+                    .map(|(key, value)| JsStorageMapEntry {
+                        root: map.root().to_hex(),
+                        key: key.to_hex(),
+                        value: value.to_hex(),
+                    })
+                    .collect(),
+            ),
+            _ => None,
+        }
+    }
 }
 
 // CONVERSIONS

crates/web-client/test/new_account.test.ts

@@ -187,3 +187,45 @@ test.describe("new_faucet tests", () => {
     );
   });
 });
+
+// AccountStorage.getMapEntries tests
+// =======================================================================================================
+
+test.describe("AccountStorage.getMapEntries tests", () => {
+  test("returns null for invalid indices and adds test for storage map", async ({
+    page,
+  }) => {
+    const result = await page.evaluate(async () => {
+      const client = window.client;
+
+      // Create a new wallet with private storage
+      const account = await client.newWallet(
+        window.AccountStorageMode.private(),
+        true
+      );
+
+      // Get the account to access its storage
+      const accountRecord = await client.getAccount(account.id());
+      if (!accountRecord) {
+        throw new Error("Account not found");
+      }
+
+      const storage = accountRecord.storage();
+
+      // Test non-map storage slot (slot 0 should be empty for a new account)
+      const nonMapResult = storage.getMapEntries(0);
+
+      // Test out of bounds index
+      const outOfBoundsResult = storage.getMapEntries(255);
+
+      return {
+        nonMap: nonMapResult,
+        outOfBounds: outOfBoundsResult,
+      };
+    });
+
+    // For invalid cases, getMapEntries should return undefined
+    expect(result.nonMap).toBeUndefined();
+    expect(result.outOfBounds).toBeUndefined();
+  });
+});

crates/web-client/test/new_transactions.test.ts

@@ -1207,6 +1207,12 @@ export const testStorageMap = async (page: Page): Promise<any> => {
     const client = window.client;
     await client.syncState();
 
+    const normalizeHexWord = (hex) => {
+      if (!hex) return undefined;
+      const normalized = hex.replace(/^0x/, "").replace(/^0+|0+$/g, "");
+      return normalized;
+    };
+
     // BUILD ACCOUNT WITH COMPONENT THAT MODIFIES STORAGE MAP
     // --------------------------------------------------------------------------
 
@@ -1217,6 +1223,10 @@ export const testStorageMap = async (page: Page): Promise<any> => {
 
     let storageMap = new window.StorageMap();
     storageMap.insert(MAP_KEY, FPI_STORAGE_VALUE);
+    storageMap.insert(
+      new window.Word(new BigUint64Array([2n, 2n, 2n, 2n])),
+      new window.Word(new BigUint64Array([0n, 0n, 0n, 9n]))
+    );
 
     const accountCode = `export.bump_map_item
                     # map key
@@ -1230,12 +1240,7 @@ export const testStorageMap = async (page: Page): Promise<any> => {
                     push.0
                     # => [index, KEY, BUMPED_VALUE]
                     exec.::miden::account::set_map_item
-                    dropw
-                    # => [OLD_VALUE]
-                    dupw
-                    push.0
-                    # Set a new item each time as the value keeps changing
-                    exec.::miden::account::set_map_item
+                    # => [OLD_MAP_ROOT, OLD_VALUE]
                     dropw dropw
                 end
         `;
@@ -1261,6 +1266,7 @@ export const testStorageMap = async (page: Page): Promise<any> => {
 
     await client.addAccountSecretKeyToWebStore(secretKey);
     await client.newAccount(bumpItemAccountBuilderResult.account, false);
+    await client.syncState();
 
     let initialMapValue = (
       await client.getAccount(bumpItemAccountBuilderResult.account.id())
@@ -1305,20 +1311,51 @@ export const testStorageMap = async (page: Page): Promise<any> => {
       .getMapItem(1, MAP_KEY)
       ?.toHex();
 
+    // Test getMapEntries() functionality
+    let accountStorage = (
+      await client.getAccount(bumpItemAccountBuilderResult.account.id())
+    )?.storage();
+    let mapEntries = accountStorage?.getMapEntries(1);
+
+    // Verify we get the expected entries
+    let expectedKey = MAP_KEY.toHex();
+    let expectedValue = normalizeHexWord(finalMapValue);
+
+    let mapEntriesData = {
+      entriesCount: mapEntries?.length || 0,
+      hasExpectedEntry: false,
+      expectedKey: expectedKey,
+      expectedValue: expectedValue,
+    };
+
+    if (expectedValue && mapEntries && mapEntries.length > 0) {
+      mapEntriesData.hasExpectedEntry = mapEntries.some(
+        (entry) =>
+          entry.key === expectedKey &&
+          normalizeHexWord(entry.value) === expectedValue
+      );
+    }
+
     return {
-      initialMapValue: initialMapValue
-        ?.replace(/^0x/, "")
-        .replace(/^0+|0+$/g, ""),
-      finalMapValue: finalMapValue?.replace(/^0x/, "").replace(/^0+|0+$/g, ""),
+      initialMapValue: normalizeHexWord(initialMapValue),
+      finalMapValue: normalizeHexWord(finalMapValue),
+      mapEntries: mapEntriesData,
     };
   });
 };
 
 test.describe("storage map test", () => {
   test.setTimeout(50000);
   test("storage map is updated correctly in transaction", async ({ page }) => {
-    let { initialMapValue, finalMapValue } = await testStorageMap(page);
+    let { initialMapValue, finalMapValue, mapEntries } =
+      await testStorageMap(page);
     expect(initialMapValue).toBe("1");
     expect(finalMapValue).toBe("2");
+
+    // Test getMapEntries() functionality
+    expect(mapEntries.entriesCount).toBeGreaterThan(1);
+    expect(mapEntries.hasExpectedEntry).toBe(true);
+    expect(mapEntries.expectedKey).toBeDefined();
+    expect(mapEntries.expectedValue).toBe("2");
   });
 });

docs/src/web-client/api/classes/AccountStorage.md

@@ -44,6 +44,26 @@
 
 ***
 
+### getMapEntries()
+
+> **getMapEntries**(`index`): [`JsStorageMapEntry`](JsStorageMapEntry.md)[]
+
+Get all key-value pairs from the map slot at `index`.
+Returns `undefined` if the slot isn't a map or `index` is out of bounds (0-255).
+Returns `[]` if the map exists but is empty.
+
+#### Parameters
+
+##### index
+
+`number`
+
+#### Returns
+
+[`JsStorageMapEntry`](JsStorageMapEntry.md)[]
+
+***
+
 ### getMapItem()
 
 > **getMapItem**(`index`, `key`): [`Word`](Word.md)