feat: expose note export and imports as a struct (0xMiden#1383)

fkrause98 · web-flow · commit de8026ab7a53 · 2025-10-22T10:24:20.000-03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,7 @@
 * 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)).
 * Refactored code into their own files and added `ProvenTransaction` and `TransactionStoreUpdate` bindings for the WebClient ([#1408](https://github.com/0xMiden/miden-client/pull/1408)).
+* Added `NoteFile` type, used for exporting and importing `Notes`([#1378](https://github.com/0xMiden/miden-client/pull/1383))
 
 ### Changes
 
diff --git a/crates/rust-client/src/lib.rs b/crates/rust-client/src/lib.rs
@@ -151,6 +151,10 @@ mod errors;
 // RE-EXPORTS
 // ================================================================================================
 
+pub mod notes {
+    pub use miden_objects::note::NoteFile;
+}
+
 /// Provides types and utilities for working with Miden Assembly.
 pub mod assembly {
     pub use miden_objects::assembly::debuginfo::SourceManagerSync;
diff --git a/crates/web-client/js/index.js b/crates/web-client/js/index.js
@@ -36,9 +36,11 @@ const {
   NoteAndArgsArray,
   NoteAssets,
   NoteConsumability,
+  NoteDetails,
   NoteExecutionHint,
   NoteExecutionMode,
   NoteFilter,
+  NoteFile,
   NoteFilterTypes,
   NoteId,
   NoteIdAndArgs,
@@ -115,9 +117,11 @@ export {
   NoteAndArgsArray,
   NoteAssets,
   NoteConsumability,
+  NoteDetails,
   NoteExecutionHint,
   NoteExecutionMode,
   NoteFilter,
+  NoteFile,
   NoteFilterTypes,
   NoteId,
   NoteIdAndArgs,
diff --git a/crates/web-client/js/types/index.d.ts b/crates/web-client/js/types/index.d.ts
@@ -38,8 +38,10 @@ export {
   NoteAndArgsArray,
   NoteAssets,
   NoteConsumability,
+  NoteDetails,
   NoteExecutionHint,
   NoteExecutionMode,
+  NoteFile,
   NoteFilter,
   NoteFilterTypes,
   NoteId,
diff --git a/crates/web-client/package.json b/crates/web-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@demox-labs/miden-sdk",
-  "version": "0.12.0-next.28",
+  "version": "0.12.0-next.29",
   "description": "Miden Wasm SDK",
   "collaborators": [
     "Miden",
diff --git a/crates/web-client/src/export.rs b/crates/web-client/src/export.rs
@@ -1,11 +1,12 @@
 use miden_client::Word;
 use miden_client::account::AccountFile as NativeAccountFile;
 use miden_client::store::NoteExportType;
-use miden_client::utils::{Serializable, get_public_keys_from_account};
+use miden_client::utils::get_public_keys_from_account;
 use wasm_bindgen::prelude::*;
 
 use crate::models::account_file::AccountFile;
 use crate::models::account_id::AccountId;
+use crate::models::note_file::NoteFile;
 use crate::{WebClient, js_error_with_context};
 
 #[wasm_bindgen]
@@ -15,16 +16,26 @@ impl WebClient {
         &mut self,
         note_id: String,
         export_type: String,
-    ) -> Result<JsValue, JsValue> {
+    ) -> Result<NoteFile, JsValue> {
         if let Some(client) = self.get_mut_inner() {
             let note_id = Word::try_from(note_id)
-                .map_err(|err| js_error_with_context(err, "failed to parse input note id"))?
+                .map_err(|err| {
+                    js_error_with_context(
+                        err,
+                        "error exporting note file: failed to parse input note id",
+                    )
+                })?
                 .into();
 
             let output_note = client
                 .get_output_note(note_id)
                 .await
-                .map_err(|err| js_error_with_context(err, "failed to get output notes"))?
+                .map_err(|err| {
+                    js_error_with_context(
+                        err,
+                        "error exporting note file: failed to get output notes",
+                    )
+                })?
                 .ok_or(JsValue::from_str("No output note found"))?;
 
             let export_type = match export_type.as_str() {
@@ -44,12 +55,7 @@ impl WebClient {
                 js_error_with_context(err, "failed to convert output note to note file")
             })?;
 
-            let input_note_bytes = note_file.to_bytes();
-
-            let serialized_input_note_bytes = serde_wasm_bindgen::to_value(&input_note_bytes)
-                .map_err(|_| JsValue::from_str("Serialization error"))?;
-
-            Ok(serialized_input_note_bytes)
+            Ok(note_file.into())
         } else {
             Err(JsValue::from_str("Client not initialized"))
         }
diff --git a/crates/web-client/src/import.rs b/crates/web-client/src/import.rs
@@ -1,15 +1,14 @@
 use miden_client::account::{AccountFile as NativeAccountFile, AccountId as NativeAccountId};
 use miden_client::auth::AuthSecretKey;
-use miden_client::note::NoteFile;
-use miden_client::utils::Deserializable;
-use serde_wasm_bindgen::from_value;
 use wasm_bindgen::prelude::*;
 
 use crate::helpers::generate_wallet;
 use crate::models::account::Account;
 use crate::models::account_file::AccountFile;
 use crate::models::account_id::AccountId as JsAccountId;
 use crate::models::account_storage_mode::AccountStorageMode;
+use crate::models::note_file::NoteFile;
+use crate::models::note_id::NoteId;
 use crate::{WebClient, js_error_with_context};
 
 #[wasm_bindgen]
@@ -88,20 +87,13 @@ impl WebClient {
     }
 
     #[wasm_bindgen(js_name = "importNoteFile")]
-    pub async fn import_note_file(&mut self, note_bytes: JsValue) -> Result<JsValue, JsValue> {
+    pub async fn import_note_file(&mut self, note_file: NoteFile) -> Result<NoteId, JsValue> {
         if let Some(client) = self.get_mut_inner() {
-            let note_bytes_result: Vec<u8> =
-                from_value(note_bytes).map_err(|err| err.to_string())?;
-
-            let note_file =
-                NoteFile::read_from_bytes(&note_bytes_result).map_err(|err| err.to_string())?;
-
-            let imported = client
-                .import_note(note_file)
+            Ok(client
+                .import_note(note_file.into())
                 .await
-                .map_err(|err| js_error_with_context(err, "failed to import note"))?;
-
-            Ok(JsValue::from_str(&imported.to_string()))
+                .map_err(|err| js_error_with_context(err, "failed to import note"))?
+                .into())
         } else {
             Err(JsValue::from_str("Client not initialized"))
         }
diff --git a/crates/web-client/src/models/input_note.rs b/crates/web-client/src/models/input_note.rs
@@ -8,7 +8,7 @@ use super::note_location::NoteLocation;
 
 #[derive(Clone)]
 #[wasm_bindgen]
-pub struct InputNote(NativeInputNote);
+pub struct InputNote(pub(crate) NativeInputNote);
 
 #[wasm_bindgen]
 impl InputNote {
diff --git a/crates/web-client/src/models/input_note_record.rs b/crates/web-client/src/models/input_note_record.rs
@@ -1,11 +1,14 @@
 use miden_client::store::InputNoteRecord as NativeInputNoteRecord;
+use miden_client::transaction::InputNote as NativeInputNote;
 use wasm_bindgen::prelude::*;
 
 use super::input_note_state::InputNoteState;
 use super::note_details::NoteDetails;
 use super::note_id::NoteId;
 use super::note_inclusion_proof::NoteInclusionProof;
 use super::note_metadata::NoteMetadata;
+use crate::js_error_with_context;
+use crate::models::input_note::InputNote;
 
 #[derive(Clone)]
 #[wasm_bindgen]
@@ -57,6 +60,14 @@ impl InputNoteRecord {
     pub fn is_processing(&self) -> bool {
         self.0.is_processing()
     }
+
+    #[wasm_bindgen(js_name = "toInputNote")]
+    pub fn to_input_note(&self) -> Result<InputNote, JsValue> {
+        let input_note: NativeInputNote = self.0.clone().try_into().map_err(|err| {
+            js_error_with_context(err, "could not create InputNote from InputNoteRecord")
+        })?;
+        Ok(InputNote(input_note))
+    }
 }
 
 // CONVERSIONS
diff --git a/crates/web-client/src/models/mod.rs b/crates/web-client/src/models/mod.rs
@@ -63,6 +63,7 @@ pub mod note_assets;
 pub mod note_details;
 pub mod note_execution_hint;
 pub mod note_execution_mode;
+pub mod note_file;
 pub mod note_filter;
 pub mod note_header;
 pub mod note_id;
diff --git a/crates/web-client/src/models/note_file.rs b/crates/web-client/src/models/note_file.rs
@@ -0,0 +1,111 @@
+use miden_client::note::{NoteDetails as NativeNoteDetails, NoteId as NativeNoteId};
+use miden_client::notes::NoteFile as NativeNoteFile;
+use miden_client::{Deserializable, Serializable};
+use wasm_bindgen::prelude::*;
+
+use super::input_note::InputNote;
+use super::output_note::OutputNote;
+use crate::js_error_with_context;
+use crate::models::note_details::NoteDetails;
+use crate::models::note_id::NoteId;
+
+/// A serialized representation of a note.
+#[wasm_bindgen(inspectable)]
+pub struct NoteFile {
+    pub(crate) inner: NativeNoteFile,
+}
+
+#[wasm_bindgen]
+impl NoteFile {
+    /// Returns this `NoteFile`'s types.
+    #[wasm_bindgen(js_name = noteType)]
+    pub fn note_type(&self) -> String {
+        match &self.inner {
+            NativeNoteFile::NoteId(_) => "NoteId".to_owned(),
+            NativeNoteFile::NoteDetails { .. } => "NoteDetails".to_owned(),
+            NativeNoteFile::NoteWithProof(..) => "NoteWithProof".to_owned(),
+        }
+    }
+
+    /// Turn a notefile into its byte representation.
+    #[wasm_bindgen(js_name = serialize)]
+    pub fn serialize(&self) -> Vec<u8> {
+        let mut buffer = vec![];
+        self.inner.write_into(&mut buffer);
+        buffer
+    }
+
+    /// Given a valid byte representation of a `NoteFile`,
+    /// return it as a struct.
+    #[wasm_bindgen(js_name = deserialize)]
+    pub fn deserialize(bytes: &[u8]) -> Result<Self, JsValue> {
+        let deserialized = NativeNoteFile::read_from_bytes(bytes)
+            .map_err(|err| js_error_with_context(err, "notefile deserialization failed"))?;
+        Ok(Self { inner: deserialized })
+    }
+
+    #[wasm_bindgen(js_name = fromInputNote)]
+    pub fn from_input_note(note: &InputNote) -> Self {
+        if let Some(inclusion_proof) = note.proof() {
+            Self {
+                inner: NativeNoteFile::NoteWithProof(note.note().into(), inclusion_proof.into()),
+            }
+        } else {
+            let assets = note.note().assets();
+            let recipient = note.note().recipient();
+            let details = NativeNoteDetails::new(assets.into(), recipient.into());
+            Self { inner: details.into() }
+        }
+    }
+
+    #[wasm_bindgen(js_name = fromOutputNote)]
+    pub fn from_output_note(note: &OutputNote) -> Self {
+        let native_note = note.note();
+        match (native_note.assets(), native_note.recipient()) {
+            (Some(assets), Some(recipient)) => {
+                let details = NativeNoteDetails::new(assets.clone(), recipient.clone());
+                Self { inner: details.into() }
+            },
+            _ => Self { inner: native_note.id().into() },
+        }
+    }
+
+    #[wasm_bindgen(js_name = fromNoteDetails)]
+    pub fn from_note_details(note_details: &NoteDetails) -> Self {
+        note_details.into()
+    }
+
+    #[wasm_bindgen(js_name = fromNoteId)]
+    pub fn from_note_id(note_details: &NoteId) -> Self {
+        note_details.into()
+    }
+}
+
+// CONVERSIONS
+// ================================================================================================
+
+impl From<NativeNoteFile> for NoteFile {
+    fn from(note_file: NativeNoteFile) -> Self {
+        NoteFile { inner: note_file }
+    }
+}
+
+impl From<NoteFile> for NativeNoteFile {
+    fn from(note_file: NoteFile) -> Self {
+        note_file.inner
+    }
+}
+
+impl From<&NoteDetails> for NoteFile {
+    fn from(details: &NoteDetails) -> Self {
+        let note_details: NativeNoteDetails = details.into();
+        Self { inner: note_details.into() }
+    }
+}
+
+impl From<&NoteId> for NoteFile {
+    fn from(note_id: &NoteId) -> Self {
+        let note_id: NativeNoteId = note_id.into();
+        NoteFile { inner: note_id.into() }
+    }
+}
diff --git a/crates/web-client/src/models/note_inclusion_proof.rs b/crates/web-client/src/models/note_inclusion_proof.rs
@@ -35,3 +35,8 @@ impl From<&NativeNoteInclusionProof> for NoteInclusionProof {
         NoteInclusionProof(native_proof.clone())
     }
 }
+impl From<NoteInclusionProof> for NativeNoteInclusionProof {
+    fn from(proof: NoteInclusionProof) -> Self {
+        proof.0
+    }
+}
diff --git a/crates/web-client/src/models/output_note.rs b/crates/web-client/src/models/output_note.rs
@@ -64,6 +64,10 @@ impl OutputNote {
             _ => None,
         }
     }
+
+    pub(crate) fn note(&self) -> &NativeOutputNote {
+        &self.0
+    }
 }
 
 // CONVERSIONS
diff --git a/crates/web-client/test/global.test.d.ts b/crates/web-client/test/global.test.d.ts
@@ -32,6 +32,7 @@ import {
   NoteExecutionHint,
   NoteExecutionMode,
   NoteFilter,
+  NoteFile,
   NoteFilterTypes,
   NoteId,
   NoteIdAndArgs,
@@ -118,6 +119,7 @@ declare global {
     NoteExecutionHint: typeof NoteExecutionHint;
     NoteExecutionMode: typeof NoteExecutionMode;
     NoteFilter: typeof NoteFilter;
+    NoteFile: typeof NoteFile;
     NoteFilterTypes: typeof NoteFilterTypes;
     NoteId: typeof NoteId;
     NoteIdAndArgs: typeof NoteIdAndArgs;
diff --git a/crates/web-client/test/import_export.test.ts b/crates/web-client/test/import_export.test.ts
diff --git a/crates/web-client/test/playwright.global.setup.ts b/crates/web-client/test/playwright.global.setup.ts
diff --git a/docs/src/web-client/api/README.md b/docs/src/web-client/api/README.md
diff --git a/docs/src/web-client/api/classes/InputNoteRecord.md b/docs/src/web-client/api/classes/InputNoteRecord.md
diff --git a/docs/src/web-client/api/classes/NoteFile.md b/docs/src/web-client/api/classes/NoteFile.md
diff --git a/docs/src/web-client/api/classes/WebClient.md b/docs/src/web-client/api/classes/WebClient.md

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@demox-labs/miden-sdk",`
`3`		`- "version": "0.12.0-next.28",`
	`3`	`+ "version": "0.12.0-next.29",`
`4`	`4`	`"description": "Miden Wasm SDK",`
`5`	`5`	`"collaborators": [`
`6`	`6`	`"Miden",`