feat(web-client): note transport integration (0xMiden#1374)

* feat: web-client note transport

* Fix typo

* Use `js_error_with_context` in web-client's note-transport

* Use paginated fetch-notes in fetchPrivateNotes

Author: v0-e

CHANGELOG.md

@@ -37,6 +37,7 @@
 * [BREAKING] Implemented `AccountFile` in the WebClient ([#1258](https://github.com/0xMiden/miden-client/pull/1258)).
 * [BREAKING] Added remote key storage and signature requesting to the `WebKeyStore` ([#1371](https://github.com/0xMiden/miden-client/pull/1371))
 * Added `sqlite_store` under `ClientBuilderSqliteExt` method to the `ClientBuilder` ([#1416](https://github.com/0xMiden/miden-client/pull/1416))
+* [BREAKING] Updated the Web Client to integrate Note Transport ([#1374](https://github.com/0xMiden/miden-client/pull/1374))
 
 ## 0.11.8 (2025-09-29)
 

crates/rust-client/src/note_transport/grpc.rs

@@ -63,15 +63,15 @@ impl GrpcNoteTransportClient {
 
     /// gRPC client (WASM) constructor
     #[cfg(target_arch = "wasm32")]
-    pub fn connect(endpoint: String, _timeout_ms: u64) -> Result<Self, NoteTransportError> {
+    pub fn new(endpoint: String) -> Self {
         let wasm_client = tonic_web_wasm_client::Client::new(endpoint);
         let health_client = HealthClient::new(wasm_client.clone());
         let client = MidenNoteTransportClient::new(wasm_client);
 
-        Ok(Self {
+        Self {
             client: RwLock::new(client),
             health_client: RwLock::new(health_client),
-        })
+        }
     }
 
     /// Get a lock to the main client

crates/rust-client/src/note_transport/mod.rs

@@ -11,7 +11,7 @@ use futures::Stream;
 use miden_lib::utils::Serializable;
 use miden_objects::address::Address;
 use miden_objects::note::{Note, NoteDetails, NoteHeader, NoteTag};
-use miden_tx::utils::{Deserializable, DeserializationError, SliceReader};
+use miden_tx::utils::{ByteReader, ByteWriter, Deserializable, DeserializationError, SliceReader};
 
 pub use self::errors::NoteTransportError;
 use crate::store::{InputNoteRecord, Store};
@@ -223,7 +223,7 @@ pub trait NoteStream:
 {
 }
 
-/// Information about a note in API responses
+/// Information about a note fetched from the note transport network
 #[derive(Debug, Clone)]
 pub struct NoteInfo {
     /// Note header
@@ -232,6 +232,37 @@ pub struct NoteInfo {
     pub details_bytes: Vec<u8>,
 }
 
+// SERIALIZATION
+// ================================================================================================
+
+impl Serializable for NoteInfo {
+    fn write_into<W: ByteWriter>(&self, target: &mut W) {
+        self.header.write_into(target);
+        self.details_bytes.write_into(target);
+    }
+}
+
+impl Deserializable for NoteInfo {
+    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
+        let header = NoteHeader::read_from(source)?;
+        let details_bytes = Vec::<u8>::read_from(source)?;
+        Ok(NoteInfo { header, details_bytes })
+    }
+}
+
+impl Serializable for NoteTransportCursor {
+    fn write_into<W: ByteWriter>(&self, target: &mut W) {
+        self.0.write_into(target);
+    }
+}
+
+impl Deserializable for NoteTransportCursor {
+    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
+        let value = u64::read_from(source)?;
+        Ok(Self::new(value))
+    }
+}
+
 fn rejoin_note(header: &NoteHeader, details_bytes: &[u8]) -> Result<Note, DeserializationError> {
     let mut reader = SliceReader::new(details_bytes);
     let details = NoteDetails::read_from(&mut reader)?;

crates/rust-client/src/test_utils/note_transport.rs

@@ -9,6 +9,7 @@ use chrono::Utc;
 use futures::Stream;
 use miden_objects::note::{NoteHeader, NoteTag};
 use miden_tx::utils::sync::RwLock;
+use miden_tx::utils::{ByteReader, ByteWriter, Deserializable, DeserializationError, Serializable};
 
 use crate::note_transport::{
     NoteInfo,
@@ -84,8 +85,9 @@ impl Default for MockNoteTransportNode {
 /// Mock Note Transport API
 ///
 /// Simulates communications with the note transport node.
+#[derive(Clone, Default)]
 pub struct MockNoteTransportApi {
-    mock_node: Arc<RwLock<MockNoteTransportNode>>,
+    pub mock_node: Arc<RwLock<MockNoteTransportNode>>,
 }
 
 impl MockNoteTransportApi {
@@ -146,3 +148,20 @@ impl NoteTransportClient for MockNoteTransportApi {
         Ok(Box::new(DummyNoteStream {}))
     }
 }
+
+// SERIALIZATION
+// ================================================================================================
+
+impl Serializable for MockNoteTransportNode {
+    fn write_into<W: ByteWriter>(&self, target: &mut W) {
+        self.notes.write_into(target);
+    }
+}
+
+impl Deserializable for MockNoteTransportNode {
+    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
+        let notes = BTreeMap::<NoteTag, Vec<(NoteInfo, NoteTransportCursor)>>::read_from(source)?;
+
+        Ok(Self { notes })
+    }
+}

crates/web-client/js/index.js

@@ -205,8 +205,9 @@ export class WebClient {
    *   `SigningInputs.serialize()`. Must return an array of numeric values (numbers or numeric
    *   strings) representing the signature elements, either directly or wrapped in a `Promise`.
    */
-  constructor(rpcUrl, seed, getKeyCb, insertKeyCb, signCb) {
+  constructor(rpcUrl, noteTransportUrl, seed, getKeyCb, insertKeyCb, signCb) {
     this.rpcUrl = rpcUrl;
+    this.noteTransportUrl = noteTransportUrl;
     this.seed = seed;
     this.getKeyCb = getKeyCb;
     this.insertKeyCb = insertKeyCb;
@@ -278,6 +279,7 @@ export class WebClient {
           action: WorkerAction.INIT,
           args: [
             this.rpcUrl,
+            this.noteTransportUrl,
             this.seed,
             this.getKeyCb,
             this.insertKeyCb,
@@ -303,15 +305,16 @@ export class WebClient {
    * This method is async so you can await the asynchronous call to createClient().
    *
    * @param {string} rpcUrl - The RPC URL.
+   * @param {string} noteTransportUrl - The note transport URL (optional).
    * @param {string} seed - The seed for the account.
    * @returns {Promise<WebClient>} The fully initialized WebClient.
    */
-  static async createClient(rpcUrl, seed) {
+  static async createClient(rpcUrl, noteTransportUrl, seed) {
     // Construct the instance (synchronously).
-    const instance = new WebClient(rpcUrl, seed);
+    const instance = new WebClient(rpcUrl, noteTransportUrl, seed);
 
     // Wait for the underlying wasmWebClient to be initialized.
-    await instance.wasmWebClient.createClient(rpcUrl, seed);
+    await instance.wasmWebClient.createClient(rpcUrl, noteTransportUrl, seed);
 
     // Wait for the worker to be ready
     await instance.ready;
@@ -341,6 +344,7 @@ export class WebClient {
    * This method is async so you can await the asynchronous call to createClientWithExternalKeystore().
    *
    * @param {string} rpcUrl - The RPC URL.
+   * @param {string | undefined} noteTransportUrl - The note transport URL (optional).
    * @param {string | undefined} seed - The seed for the account.
    * @param {Function | undefined} getKeyCb - The get key callback.
    * @param {Function | undefined} insertKeyCb - The insert key callback.
@@ -349,15 +353,24 @@ export class WebClient {
    */
   static async createClientWithExternalKeystore(
     rpcUrl,
+    noteTransportUrl,
     seed,
     getKeyCb,
     insertKeyCb,
     signCb
   ) {
     // Construct the instance (synchronously).
-    const instance = new WebClient(rpcUrl, seed, getKeyCb, insertKeyCb, signCb);
+    const instance = new WebClient(
+      rpcUrl,
+      noteTransportUrl,
+      seed,
+      getKeyCb,
+      insertKeyCb,
+      signCb
+    );
     await instance.wasmWebClient.createClientWithExternalKeystore(
       rpcUrl,
+      noteTransportUrl,
       seed,
       getKeyCb,
       insertKeyCb,
@@ -551,15 +564,24 @@ export class MockWebClient extends WebClient {
    * Factory method to create a WebClient with a mock chain for testing purposes.
    *
    * @param serializedMockChain - Serialized mock chain data (optional). Will use an empty chain if not provided.
+   * @param serializedMockNoteTransportNode - Serialized mock note transport node data (optional). Will use a new instance if not provided.
    * @param seed - The seed for the account (optional).
    * @returns A promise that resolves to a MockWebClient.
    */
-  static async createClient(serializedMockChain, seed) {
+  static async createClient(
+    serializedMockChain,
+    serializedMockNoteTransportNode,
+    seed
+  ) {
     // Construct the instance (synchronously).
     const instance = new MockWebClient(seed);
 
     // Wait for the underlying wasmWebClient to be initialized.
-    await instance.wasmWebClient.createMockClient(seed, serializedMockChain);
+    await instance.wasmWebClient.createMockClient(
+      seed,
+      serializedMockChain,
+      serializedMockNoteTransportNode
+    );
 
     // Wait for the worker to be ready
     await instance.ready;
@@ -591,10 +613,13 @@ export class MockWebClient extends WebClient {
       }
 
       let serializedMockChain = this.wasmWebClient.serializeMockChain().buffer;
+      let serializedMockNoteTransportNode =
+        this.wasmWebClient.serializeMockNoteTransportNode().buffer;
 
       const serializedSyncSummaryBytes = await this.callMethodWithWorker(
         MethodName.SYNC_STATE_MOCK,
-        serializedMockChain
+        serializedMockChain,
+        serializedMockNoteTransportNode
       );
 
       return wasm.SyncSummary.deserialize(
@@ -625,17 +650,25 @@ export class MockWebClient extends WebClient {
       }
 
       args.push(this.wasmWebClient.serializeMockChain().buffer);
+      args.push(this.wasmWebClient.serializeMockNoteTransportNode().buffer);
 
       // Always call the same worker method.
-      let serializedMockChain = await this.callMethodWithWorker(
+      let result = await this.callMethodWithWorker(
         MethodName.SUBMIT_TRANSACTION_MOCK,
         ...args
       );
 
-      serializedMockChain = new Uint8Array(serializedMockChain);
+      const serializedMockChain = new Uint8Array(result.serializedMockChain);
+      const serializedMockNoteTransportNode = new Uint8Array(
+        result.serializedMockNoteTransportNode
+      );
 
       this.wasmWebClient = new WasmWebClient();
-      await this.wasmWebClient.createMockClient(this.seed, serializedMockChain);
+      await this.wasmWebClient.createMockClient(
+        this.seed,
+        serializedMockChain,
+        serializedMockNoteTransportNode
+      );
     } catch (error) {
       console.error("INDEX.JS: Error in submitTransaction:", error.toString());
       throw error;

crates/web-client/js/types/index.d.ts

@@ -87,11 +87,13 @@ export declare class WebClient extends WasmWebClient {
    * Factory method to create and initialize a new wrapped WebClient.
    *
    * @param rpcUrl - The RPC URL (optional).
+   * @param noteTransportUrl - The note transport URL (optional).
    * @param seed - The seed for the account (optional).
    * @returns A promise that resolves to a fully initialized WebClient.
    */
   static createClient(
     rpcUrl?: string,
+    noteTransportUrl?: string,
     seed?: string
   ): Promise<WebClient & WasmWebClient>;
 

crates/web-client/js/workers/web-client-methods-worker.js

@@ -123,22 +123,41 @@ const methodHandlers = {
 
 // Add mock methods to the handler mapping.
 methodHandlers[MethodName.SYNC_STATE_MOCK] = async (args) => {
-  let [serializedMockChain] = args;
+  let [serializedMockChain, serializedMockNoteTransportNode] = args;
   serializedMockChain = new Uint8Array(serializedMockChain);
-  await wasmWebClient.createMockClient(wasmSeed, serializedMockChain);
+  serializedMockNoteTransportNode = serializedMockNoteTransportNode
+    ? new Uint8Array(serializedMockNoteTransportNode)
+    : null;
+  await wasmWebClient.createMockClient(
+    wasmSeed,
+    serializedMockChain,
+    serializedMockNoteTransportNode
+  );
 
   return await methodHandlers[MethodName.SYNC_STATE]();
 };
 
 methodHandlers[MethodName.SUBMIT_TRANSACTION_MOCK] = async (args) => {
+  let serializedMockNoteTransportNode = args.pop();
   let serializedMockChain = args.pop();
   serializedMockChain = new Uint8Array(serializedMockChain);
+  serializedMockNoteTransportNode = serializedMockNoteTransportNode
+    ? new Uint8Array(serializedMockNoteTransportNode)
+    : null;
   wasmWebClient = new wasm.WebClient();
-  await wasmWebClient.createMockClient(wasmSeed, serializedMockChain);
+  await wasmWebClient.createMockClient(
+    wasmSeed,
+    serializedMockChain,
+    serializedMockNoteTransportNode
+  );
 
   await methodHandlers[MethodName.SUBMIT_TRANSACTION](args);
 
-  return wasmWebClient.serializeMockChain().buffer;
+  return {
+    serializedMockChain: wasmWebClient.serializeMockChain().buffer,
+    serializedMockNoteTransportNode:
+      wasmWebClient.serializeMockNoteTransportNode().buffer,
+  };
 };
 
 /**
@@ -148,10 +167,10 @@ async function processMessage(event) {
   const { action, args, methodName, requestId } = event.data;
   try {
     if (action === WorkerAction.INIT) {
-      const [rpcUrl, seed] = args;
+      const [rpcUrl, noteTransportUrl, seed] = args;
       // Initialize the WASM WebClient.
       wasmWebClient = new wasm.WebClient();
-      await wasmWebClient.createClient(rpcUrl, seed);
+      await wasmWebClient.createClient(rpcUrl, noteTransportUrl, seed);
 
       wasmSeed = seed;
       ready = true;

crates/web-client/package.json

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