From 9f06d88af38cabf5ffd752d2407ac0297a7fa3d1 Mon Sep 17 00:00:00 2001 From: Michael Turner Date: Thu, 27 Jul 2023 00:16:22 -0400 Subject: [PATCH 1/2] Add JsDoc style comments for all wasm functions --- wasm/src/account/address.rs | 21 +++ wasm/src/account/private_key.rs | 43 ++++-- wasm/src/account/private_key_ciphertext.rs | 18 ++- wasm/src/account/signature.rs | 18 +++ wasm/src/account/view_key.rs | 18 +++ wasm/src/programs/key_pair.rs | 12 +- wasm/src/programs/manager/deploy.rs | 3 + wasm/src/programs/manager/execute.rs | 3 + wasm/src/programs/manager/join.rs | 1 + wasm/src/programs/manager/split.rs | 1 + wasm/src/programs/manager/transfer.rs | 1 + wasm/src/programs/program.rs | 163 ++++++++++++++++++++- wasm/src/programs/proving_key.rs | 8 +- wasm/src/programs/response.rs | 2 + wasm/src/programs/transaction.rs | 9 ++ wasm/src/programs/verifying_key.rs | 6 + wasm/src/record/record_ciphertext.rs | 20 ++- wasm/src/record/record_plaintext.rs | 14 +- 18 files changed, 336 insertions(+), 25 deletions(-) diff --git a/wasm/src/account/address.rs b/wasm/src/account/address.rs index d7fc6f2aa..a31141ded 100644 --- a/wasm/src/account/address.rs +++ b/wasm/src/account/address.rs @@ -22,29 +22,50 @@ use crate::{ use core::{convert::TryFrom, fmt, ops::Deref, str::FromStr}; use wasm_bindgen::prelude::*; +/// Public address of an Aleo account #[wasm_bindgen] #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub struct Address(AddressNative); #[wasm_bindgen] impl Address { + /// Derive an Aleo address from a private key + /// + /// @param {PrivateKey} private_key The private key to derive the address from + /// @returns {Address} Address corresponding to the private key pub fn from_private_key(private_key: &PrivateKey) -> Self { Self(AddressNative::try_from(**private_key).unwrap()) } + /// Derive an Aleo address from a view key + /// + /// @param {ViewKey} view_key The view key to derive the address from + /// @returns {Address} Address corresponding to the view key pub fn from_view_key(view_key: &ViewKey) -> Self { Self(AddressNative::try_from(**view_key).unwrap()) } + /// Create an aleo address object from a string representation of an address + /// + /// @param {string} address String representation of an addressm + /// @returns {Address} Address pub fn from_string(address: &str) -> Self { Self::from_str(address).unwrap() } + /// Get a string representation of an Aleo address object + /// + /// @param {Address} Address + /// @returns {string} String representation of the address #[allow(clippy::inherent_to_string_shadow_display)] pub fn to_string(&self) -> String { self.0.to_string() } + /// Verify a signature for a message signed by the address + /// + /// @param {Uint8Array} Byte array representing a message signed by the address + /// @returns {boolean} Boolean representing whether or not the signature is valid pub fn verify(&self, message: &[u8], signature: &Signature) -> bool { signature.verify(self, message) } diff --git a/wasm/src/account/private_key.rs b/wasm/src/account/private_key.rs index 914325a00..6f0bba604 100644 --- a/wasm/src/account/private_key.rs +++ b/wasm/src/account/private_key.rs @@ -23,13 +23,16 @@ use core::{convert::TryInto, fmt, ops::Deref, str::FromStr}; use rand::{rngs::StdRng, SeedableRng}; use wasm_bindgen::prelude::*; +/// Private key of an Aleo account #[wasm_bindgen] #[derive(Clone, Debug, Eq, PartialEq)] pub struct PrivateKey(PrivateKeyNative); #[wasm_bindgen] impl PrivateKey { - /// Generate a new private key + /// Generate a new private key using a cryptographically secure random number generator + /// + /// @returns {PrivateKey} #[wasm_bindgen(constructor)] #[allow(clippy::new_without_default)] pub fn new() -> Self { @@ -38,6 +41,9 @@ impl PrivateKey { } /// Get a private key from a series of unchecked bytes + /// + /// @param {Uint8Array} seed Unchecked 32 byte long Uint8Array acting as the seed for the private key + /// @returns {PrivateKey} pub fn from_seed_unchecked(seed: &[u8]) -> PrivateKey { console_error_panic_hook::set_once(); // Cast into a fixed-size byte array. Note: This is a **hard** requirement for security. @@ -48,39 +54,50 @@ impl PrivateKey { Self(PrivateKeyNative::try_from(FromBytes::read_le(&*field.to_bytes_le().unwrap()).unwrap()).unwrap()) } - /// Create a private key from a string representation + /// Get a private key from a string representation of a private key /// - /// This function will fail if the text is not a valid private key + /// @param {string} seed String representation of a private key + /// @returns {PrivateKey} pub fn from_string(private_key: &str) -> Result { Self::from_str(private_key).map_err(|_| "Invalid private key".to_string()) } - /// Get a string representation of the private key + /// Get a string representation of the private key. This function should be used very carefully + /// as it exposes the private key plaintext /// - /// This function should be used very carefully as it exposes the private key plaintext + /// @returns {string} String representation of a private key #[allow(clippy::inherent_to_string_shadow_display)] pub fn to_string(&self) -> String { self.0.to_string() } /// Get the view key corresponding to the private key + /// + /// @returns {ViewKey} pub fn to_view_key(&self) -> ViewKey { ViewKey::from_private_key(self) } /// Get the address corresponding to the private key + /// + /// @returns {Address} pub fn to_address(&self) -> Address { Address::from_private_key(self) } /// Sign a message with the private key + /// + /// @param {Uint8Array} Byte array representing a message signed by the address + /// @returns {Signature} Signature generated by signing the message with the address pub fn sign(&self, message: &[u8]) -> Signature { Signature::sign(self, message) } - /// Get a private key ciphertext using a secret. + /// Get a new randomly generated private key ciphertext using a secret. The secret is sensitive + /// and will be needed to decrypt the private key later, so it should be stored securely /// - /// The secret is sensitive and will be needed to decrypt the private key later, so it should be stored securely + /// @param {string} secret Secret used to encrypt the private key + /// @returns {PrivateKeyCiphertext | Error} Ciphertext representation of the private key #[wasm_bindgen(js_name = newEncrypted)] pub fn new_encrypted(secret: &str) -> Result { let key = Self::new(); @@ -89,9 +106,11 @@ impl PrivateKey { Ok(PrivateKeyCiphertext::from(ciphertext)) } - /// Encrypt the private key with a secret. + /// Encrypt an existing private key with a secret. The secret is sensitive and will be needed to + /// decrypt the private key later, so it should be stored securely /// - /// The secret is sensitive and will be needed to decrypt the private key later, so it should be stored securely + /// @param {string} secret Secret used to encrypt the private key + /// @returns {PrivateKeyCiphertext | Error} Ciphertext representation of the private key #[wasm_bindgen(js_name = toCiphertext)] pub fn to_ciphertext(&self, secret: &str) -> Result { let ciphertext = @@ -99,7 +118,11 @@ impl PrivateKey { Ok(PrivateKeyCiphertext::from(ciphertext)) } - /// Get private key from a private key ciphertext using a secret. + /// Get private key from a private key ciphertext and secret originally used to encrypt it + /// + /// @param {PrivateKeyCiphertext} ciphertext Ciphertext representation of the private key + /// @param {string} secret Secret originally used to encrypt the private key + /// @returns {PrivateKey | Error} Private key #[wasm_bindgen(js_name = fromPrivateKeyCiphertext)] pub fn from_private_key_ciphertext(ciphertext: &PrivateKeyCiphertext, secret: &str) -> Result { let private_key = Encryptor::decrypt_private_key_with_secret(ciphertext, secret) diff --git a/wasm/src/account/private_key_ciphertext.rs b/wasm/src/account/private_key_ciphertext.rs index 636cbd17a..ccb82ad94 100644 --- a/wasm/src/account/private_key_ciphertext.rs +++ b/wasm/src/account/private_key_ciphertext.rs @@ -29,9 +29,12 @@ pub struct PrivateKeyCiphertext(CiphertextNative); #[wasm_bindgen] impl PrivateKeyCiphertext { - /// Encrypt a private key using a secret string. + /// Encrypt a private key using a secret string. The secret is sensitive and will be needed to + /// decrypt the private key later, so it should be stored securely /// - /// The secret is sensitive and will be needed to decrypt the private key later, so it should be stored securely. + /// @param {PrivateKey} private_key Private key to encrypt + /// @param {string} secret Secret to encrypt the private key with + /// @returns {PrivateKeyCiphertext | Error} Private key ciphertext #[wasm_bindgen(js_name = encryptPrivateKey)] pub fn encrypt_private_key(private_key: &PrivateKey, secret: &str) -> Result { let ciphertext = Encryptor::encrypt_private_key_with_secret(private_key, secret) @@ -39,9 +42,11 @@ impl PrivateKeyCiphertext { Ok(Self::from(ciphertext)) } - /// Decrypts a private ciphertext using a secret string. + /// Decrypts a private ciphertext using a secret string. This must be the same secret used to + /// encrypt the private key /// - /// This must be the same secret used to encrypt the private key + /// @param {string} secret Secret used to encrypt the private key + /// @returns {PrivateKey | Error} Private key #[wasm_bindgen(js_name = decryptToPrivateKey)] pub fn decrypt_to_private_key(&self, secret: &str) -> Result { let private_key = Encryptor::decrypt_private_key_with_secret(&self.0, secret) @@ -50,6 +55,8 @@ impl PrivateKeyCiphertext { } /// Returns the ciphertext string + /// + /// @returns {string} Ciphertext string #[allow(clippy::inherent_to_string)] #[wasm_bindgen(js_name = toString)] pub fn to_string(&self) -> String { @@ -57,6 +64,9 @@ impl PrivateKeyCiphertext { } /// Creates a PrivateKeyCiphertext from a string + /// + /// @param {string} ciphertext Ciphertext string + /// @returns {PrivateKeyCiphertext | Error} Private key ciphertext #[wasm_bindgen(js_name = fromString)] pub fn from_string(ciphertext: String) -> Result { Self::try_from(ciphertext).map_err(|_| "Invalid ciphertext".to_string()) diff --git a/wasm/src/account/signature.rs b/wasm/src/account/signature.rs index d400a15d9..09201775a 100644 --- a/wasm/src/account/signature.rs +++ b/wasm/src/account/signature.rs @@ -23,23 +23,41 @@ use core::{fmt, ops::Deref, str::FromStr}; use rand::{rngs::StdRng, SeedableRng}; use wasm_bindgen::prelude::*; +/// Cryptographic signature of a message signed by an Aleo account #[wasm_bindgen] pub struct Signature(SignatureNative); #[wasm_bindgen] impl Signature { + /// Sign a message with a private key + /// + /// @param {PrivateKey} private_key The private key to sign the message with + /// @param {Uint8Array} message Byte representation of the message to sign + /// @returns {Signature} Signature of the message pub fn sign(private_key: &PrivateKey, message: &[u8]) -> Self { Self(SignatureNative::sign_bytes(private_key, message, &mut StdRng::from_entropy()).unwrap()) } + /// Verify a signature of a message with an address + /// + /// @param {Address} address The address to verify the signature with + /// @param {Uint8Array} message Byte representation of the message to verify + /// @returns {boolean} True if the signature is valid, false otherwise pub fn verify(&self, address: &Address, message: &[u8]) -> bool { self.0.verify_bytes(address, message) } + /// Get a signature from a string representation of a signature + /// + /// @param {string} signature String representation of a signature + /// @returns {Signature} Signature pub fn from_string(signature: &str) -> Self { Self::from_str(signature).unwrap() } + /// Get a string representation of a signature + /// + /// @returns {string} String representation of a signature #[allow(clippy::inherent_to_string_shadow_display)] pub fn to_string(&self) -> String { self.0.to_string() diff --git a/wasm/src/account/view_key.rs b/wasm/src/account/view_key.rs index e380bf41c..2ec131866 100644 --- a/wasm/src/account/view_key.rs +++ b/wasm/src/account/view_key.rs @@ -26,23 +26,41 @@ pub struct ViewKey(ViewKeyNative); #[wasm_bindgen] impl ViewKey { + /// Create a new view key from a private key + /// + /// @param {PrivateKey} private_key Private key + /// @returns {ViewKey} View key pub fn from_private_key(private_key: &PrivateKey) -> Self { Self(ViewKeyNative::try_from(**private_key).unwrap()) } + /// Create a new view key from a string representation of a view key + /// + /// @param {string} view_key String representation of a view key + /// @returns {ViewKey} View key pub fn from_string(view_key: &str) -> Self { Self::from_str(view_key).unwrap() } + /// Get a string representation of a view key + /// + /// @returns {string} String representation of a view key #[allow(clippy::inherent_to_string_shadow_display)] pub fn to_string(&self) -> String { self.0.to_string() } + /// Get the address corresponding to a view key + /// + /// @returns {Address} Address pub fn to_address(&self) -> Address { Address::from_view_key(self) } + /// Decrypt a record ciphertext with a view key + /// + /// @param {string} ciphertext String representation of a record ciphertext + /// @returns {string} String representation of a record plaintext pub fn decrypt(&self, ciphertext: &str) -> Result { let ciphertext = RecordCiphertext::from_str(ciphertext).map_err(|error| error.to_string())?; match ciphertext.decrypt(self) { diff --git a/wasm/src/programs/key_pair.rs b/wasm/src/programs/key_pair.rs index 7b5c32abe..95bae49d9 100644 --- a/wasm/src/programs/key_pair.rs +++ b/wasm/src/programs/key_pair.rs @@ -28,18 +28,26 @@ pub struct KeyPair { #[wasm_bindgen] impl KeyPair { /// Create new key pair from proving and verifying keys + /// + /// @param {ProvingKey} proving_key Proving key corresponding to a function in an Aleo program + /// @param {VerifyingKey} verifying_key Verifying key corresponding to a function in an Aleo program + /// @returns {KeyPair} Key pair object containing both the function proving and verifying keys #[wasm_bindgen(constructor)] pub fn new(proving_key: ProvingKey, verifying_key: VerifyingKey) -> KeyPair { KeyPair { proving_key: Some(proving_key), verifying_key: Some(verifying_key) } } - /// Get the proving key + /// Get the proving key. This method will remove the proving key from the key pair + /// + /// @returns {ProvingKey | Error} #[wasm_bindgen(js_name = "provingKey")] pub fn proving_key(&mut self) -> Result { self.proving_key.take().ok_or("Proving key has already been removed".to_string()) } - /// Get the verifying key + /// Get the verifying key. This method will remove the verifying key from the key pair + /// + /// @returns {VerifyingKey | Error} #[wasm_bindgen(js_name = "verifyingKey")] pub fn verifying_key(&mut self) -> Result { self.verifying_key.take().ok_or("Proving key has already been removed".to_string()) diff --git a/wasm/src/programs/manager/deploy.rs b/wasm/src/programs/manager/deploy.rs index 2b34741f9..bc4301102 100644 --- a/wasm/src/programs/manager/deploy.rs +++ b/wasm/src/programs/manager/deploy.rs @@ -58,6 +58,7 @@ impl ProgramManager { /// are a string representing the program source code { "hello.aleo": "hello.aleo source code" } /// @param fee_proving_key (optional) Provide a proving key to use for the fee execution /// @param fee_verifying_key (optional) Provide a verifying key to use for the fee execution + /// @returns {Transaction | Error} #[wasm_bindgen] #[allow(clippy::too_many_arguments)] pub async fn deploy( @@ -142,6 +143,7 @@ impl ProgramManager { /// @param imports (optional) Provide a list of imports to use for the deployment fee estimation /// in the form of a javascript object where the keys are a string of the program name and the values /// are a string representing the program source code { "hello.aleo": "hello.aleo source code" } + /// @returns {u64 | Error} #[wasm_bindgen(js_name = estimateDeploymentFee)] pub async fn estimate_deployment_fee( &mut self, @@ -182,6 +184,7 @@ impl ProgramManager { /// Disclaimer: Fee estimation is experimental and may not represent a correct estimate on any current or future network /// /// @param name The name of the program to be deployed + /// @returns {u64 | Error} #[wasm_bindgen(js_name = estimateProgramNameCost)] pub fn program_name_cost(&self, name: &str) -> Result { log( diff --git a/wasm/src/programs/manager/execute.rs b/wasm/src/programs/manager/execute.rs index 823964a60..cb07749ca 100644 --- a/wasm/src/programs/manager/execute.rs +++ b/wasm/src/programs/manager/execute.rs @@ -111,6 +111,7 @@ impl ProgramManager { /// @param verifying_key (optional) Provide a verifying key to use for the function execution /// @param fee_proving_key (optional) Provide a proving key to use for the fee execution /// @param fee_verifying_key (optional) Provide a verifying key to use for the fee execution + /// @returns {Transaction | Error} #[wasm_bindgen] #[allow(clippy::too_many_arguments)] pub async fn execute( @@ -205,6 +206,7 @@ impl ProgramManager { /// are a string representing the program source code { "hello.aleo": "hello.aleo source code" } /// @param proving_key (optional) Provide a verifying key to use for the fee estimation /// @param verifying_key (optional) Provide a verifying key to use for the fee estimation + /// @returns {u64 | Error} Fee in microcredits #[wasm_bindgen(js_name = estimateExecutionFee)] #[allow(clippy::too_many_arguments)] pub async fn estimate_execution_fee( @@ -280,6 +282,7 @@ impl ProgramManager { /// /// @param program The program containing the function to estimate the finalize fee for /// @param function The function to estimate the finalize fee for + /// @returns {u64 | Error} Fee in microcredits #[wasm_bindgen(js_name = estimateFinalizeFee)] pub fn estimate_finalize_fee(&self, program: String, function: String) -> Result { log( diff --git a/wasm/src/programs/manager/join.rs b/wasm/src/programs/manager/join.rs index 65c6fce58..56a0a2150 100644 --- a/wasm/src/programs/manager/join.rs +++ b/wasm/src/programs/manager/join.rs @@ -51,6 +51,7 @@ impl ProgramManager { /// @param join_verifying_key (optional) Provide a verifying key to use for the join function /// @param fee_proving_key (optional) Provide a proving key to use for the fee execution /// @param fee_verifying_key (optional) Provide a verifying key to use for the fee execution + /// @returns {Transaction | Error} Transaction object #[wasm_bindgen] #[allow(clippy::too_many_arguments)] pub async fn join( diff --git a/wasm/src/programs/manager/split.rs b/wasm/src/programs/manager/split.rs index d2783cd74..134485a3b 100644 --- a/wasm/src/programs/manager/split.rs +++ b/wasm/src/programs/manager/split.rs @@ -46,6 +46,7 @@ impl ProgramManager { /// proving and verifying keys will be deallocated from memory after the transaction is executed /// @param split_proving_key (optional) Provide a proving key to use for the split function /// @param split_verifying_key (optional) Provide a verifying key to use for the split function + /// @returns {Transaction | Error} Transaction object #[wasm_bindgen] #[allow(clippy::too_many_arguments)] pub async fn split( diff --git a/wasm/src/programs/manager/transfer.rs b/wasm/src/programs/manager/transfer.rs index ed4d6ed7f..eda54e048 100644 --- a/wasm/src/programs/manager/transfer.rs +++ b/wasm/src/programs/manager/transfer.rs @@ -54,6 +54,7 @@ impl ProgramManager { /// function /// @param fee_proving_key (optional) Provide a proving key to use for the fee execution /// @param fee_verifying_key (optional) Provide a verifying key to use for the fee execution + /// @returns {Transaction | Error} #[wasm_bindgen] #[allow(clippy::too_many_arguments)] pub async fn transfer( diff --git a/wasm/src/programs/program.rs b/wasm/src/programs/program.rs index 1faa24fcb..c81699213 100644 --- a/wasm/src/programs/program.rs +++ b/wasm/src/programs/program.rs @@ -33,12 +33,17 @@ pub struct Program(ProgramNative); #[wasm_bindgen] impl Program { /// Create a program from a program string + /// + /// @param {string} program Aleo program source code + /// @returns {Program | Error} Program object #[wasm_bindgen(js_name = "fromString")] pub fn from_string(program: &str) -> Result { Ok(Self(ProgramNative::from_str(program).map_err(|err| err.to_string())?)) } /// Get a string representation of the program + /// + /// @returns {string} String containing the program source code #[wasm_bindgen(js_name = "toString")] #[allow(clippy::inherent_to_string)] pub fn to_string(&self) -> String { @@ -46,6 +51,24 @@ impl Program { } /// Get javascript array of functions names in the program + /// + /// @returns {Array} Array of all function names present in the program + /// + /// @example + /// const expected_functions = [ + /// "mint", + /// "transfer_private", + /// "transfer_private_to_public", + /// "transfer_public", + /// "transfer_public_to_private", + /// "join", + /// "split", + /// "fee" + /// ] + /// + /// const credits_program = aleo_wasm.Program.getCreditsProgram(); + /// const credits_functions = credits_program.getFunctions(); + /// console.log(credits_functions === expected_functions); // Output should be "true" #[wasm_bindgen(js_name = "getFunctions")] pub fn get_functions(&self) -> Array { let array = Array::new_with_length(self.0.functions().len() as u32); @@ -58,7 +81,41 @@ impl Program { } /// Get a javascript object representation of the function inputs and types. This can be used - /// to generate a webform to capture user inputs for an execution of a function. + /// to generate a web form to capture user inputs for an execution of a function. + /// + /// @param {string} function_name Name of the function to get inputs for + /// @returns {Array | Error} Array of function inputs + /// + /// @example + /// const expected_inputs = [ + /// { + /// type:"record", + /// visibility:"private", + /// record:"credits", + /// members:[ + /// { + /// name:"microcredits", + /// type:"u64", + /// visibility:"private" + /// } + /// ], + /// register:"r0" + /// }, + /// { + /// type:"address", + /// visibility:"private", + /// register:"r1" + /// }, + /// { + /// type:"u64", + /// visibility:"private", + /// register:"r2" + /// } + /// ]; + /// + /// const credits_program = aleo_wasm.Program.getCreditsProgram(); + /// const transfer_function_inputs = credits_program.getFunctionInputs("transfer_private"); + /// console.log(transfer_function_inputs === expected_inputs); // Output should be "true" #[wasm_bindgen(js_name = "getFunctionInputs")] pub fn get_function_inputs(&self, function_name: String) -> Result { let function_id = IdentifierNative::from_str(&function_name).map_err(|e| e.to_string())?; @@ -115,7 +172,7 @@ impl Program { /// Get a the list of a program's mappings and the names/types of their keys and values. /// - /// @returns {Array} - An array of objects representing the mappings in the program + /// @returns {Array | Error} - An array of objects representing the mappings in the program /// @example /// const expected_mappings = [ /// { @@ -153,7 +210,8 @@ impl Program { Ok(mappings) } - // Get the value of a plaintext input + // Get the value of a plaintext input as a javascript object (this function is not part of the + // public API) fn get_plaintext_input( &self, plaintext: &PlaintextType, @@ -189,6 +247,32 @@ impl Program { } /// Get a javascript object representation of a program record and its types + /// + /// @param {string} record_name Name of the record to get members for + /// @returns {Object | Error} Object containing the record name, type, and members + /// + /// @example + /// + /// const expected_record = { + /// type: "record", + /// record: "Credits", + /// members: [ + /// { + /// name: "owner", + /// type: "address", + /// visibility: "private" + /// }, + /// { + /// name: "microcredits", + /// type: "u64", + /// visibility: "private" + /// } + /// ]; + /// }; + /// + /// const credits_program = aleo_wasm.Program.getCreditsProgram(); + /// const credits_record = credits_program.getRecordMembers("Credits"); + /// console.log(credits_record === expected_record); // Output should be "true" #[wasm_bindgen(js_name = "getRecordMembers")] pub fn get_record_members(&self, record_name: String) -> Result { let record_id = IdentifierNative::from_str(&record_name).map_err(|e| e.to_string())?; @@ -225,6 +309,51 @@ impl Program { } /// Get a javascript object representation of a program struct and its types + /// + /// @param {string} struct_name Name of the struct to get members for + /// @returns {Array | Error} Array containing the struct members + /// + /// @example + /// + /// const STRUCT_PROGRAM = "program token_issue.aleo; + /// + /// struct token_metadata: + /// network as u32; + /// version as u32; + /// + /// struct token: + /// token_id as u32; + /// metadata as token_metadata; + /// + /// function no_op: + /// input r0 as u64; + /// output r0 as u64;" + /// + /// const expected_struct_members = [ + /// { + /// name: "token_id", + /// type: "u32", + /// }, + /// { + /// name: "metadata", + /// type: "struct", + /// struct_id: "token_metadata", + /// members: [ + /// { + /// name: "network", + /// type: "u32", + /// } + /// { + /// name: "version", + /// type: "u32", + /// } + /// ] + /// } + /// ]; + /// + /// const program = aleo_wasm.Program.fromString(STRUCT_PROGRAM); + /// const struct_members = program.getStructMembers("token"); + /// console.log(struct_members === expected_struct_members); // Output should be "true" #[wasm_bindgen(js_name = "getStructMembers")] pub fn get_struct_members(&self, struct_name: String) -> Result { let struct_id = IdentifierNative::from_str(&struct_name).map_err(|e| e.to_string())?; @@ -244,24 +373,52 @@ impl Program { } /// Get the credits.aleo program + /// + /// @returns {Program} The credits.aleo program #[wasm_bindgen(js_name = "getCreditsProgram")] pub fn get_credits_program() -> Program { Program::from(ProgramNative::credits().unwrap()) } /// Get the id of the program + /// + /// @returns {string} The id of the program #[wasm_bindgen] pub fn id(&self) -> String { self.0.id().to_string() } /// Determine equality with another program + /// + /// @param {Program} other The other program to compare + /// @returns {boolean} True if the programs are equal, false otherwise #[wasm_bindgen(js_name = "isEqual")] pub fn is_equal(&self, other: &Program) -> bool { self == other } /// Get program_imports + /// + /// @returns {Array} The program imports + /// + /// @example + /// + /// const DOUBLE_TEST = "import multiply_test.aleo; + /// + /// program double_test.aleo; + /// + /// function double_it: + /// input r0 as u32.private; + /// call multiply_test.aleo/multiply 2u32 r0 into r1; + /// output r1 as u32.private;"; + /// + /// const expected_imports = [ + /// "multiply_test.aleo" + /// ]; + /// + /// const program = aleo_wasm.Program.fromString(DOUBLE_TEST_PROGRAM); + /// const imports = program.getImports(); + /// console.log(imports === expected_imports); // Output should be "true" #[wasm_bindgen(js_name = "getImports")] pub fn get_imports(&self) -> Array { let imports = Array::new_with_length(self.0.imports().len() as u32); diff --git a/wasm/src/programs/proving_key.rs b/wasm/src/programs/proving_key.rs index 4d2f5761b..d97422120 100644 --- a/wasm/src/programs/proving_key.rs +++ b/wasm/src/programs/proving_key.rs @@ -19,6 +19,7 @@ use crate::types::{FromBytes, ProvingKeyNative, ToBytes}; use std::ops::Deref; use wasm_bindgen::prelude::wasm_bindgen; +/// Proving key for a function within an Aleo program #[wasm_bindgen] #[derive(Clone, Debug)] pub struct ProvingKey(ProvingKeyNative); @@ -26,12 +27,17 @@ pub struct ProvingKey(ProvingKeyNative); #[wasm_bindgen] impl ProvingKey { /// Construct a new proving key from a byte array + /// + /// @param {Uint8Array} bytes Byte array representation of a proving key + /// @returns {ProvingKey | Error} #[wasm_bindgen(js_name = "fromBytes")] pub fn from_bytes(bytes: &[u8]) -> Result { Ok(Self(ProvingKeyNative::from_bytes_le(bytes).map_err(|e| e.to_string())?)) } - /// Create a byte array from a proving key + /// Return the byte representation of a proving key + /// + /// @returns {Uint8Array | Error} Byte array representation of a proving key #[wasm_bindgen(js_name = "toBytes")] pub fn to_bytes(&self) -> Result, String> { self.0.to_bytes_le().map_err(|_| "Failed to serialize proving key".to_string()) diff --git a/wasm/src/programs/response.rs b/wasm/src/programs/response.rs index e04e33cc1..dba8b6010 100644 --- a/wasm/src/programs/response.rs +++ b/wasm/src/programs/response.rs @@ -29,6 +29,8 @@ pub struct ExecutionResponse(ResponseNative); #[wasm_bindgen] impl ExecutionResponse { /// Get the outputs of the executed function + /// + /// @returns {Array} Array of strings representing the outputs of the function #[wasm_bindgen(js_name = "getOutputs")] pub fn get_outputs(&self) -> js_sys::Array { let array = js_sys::Array::new_with_length(0u32); diff --git a/wasm/src/programs/transaction.rs b/wasm/src/programs/transaction.rs index 7d238d8f0..190875cfc 100644 --- a/wasm/src/programs/transaction.rs +++ b/wasm/src/programs/transaction.rs @@ -30,6 +30,9 @@ pub struct Transaction(TransactionNative); #[wasm_bindgen] impl Transaction { /// Create a transaction from a string + /// + /// @param {string} transaction String representation of a transaction + /// @returns {Transaction | Error} #[wasm_bindgen(js_name = fromString)] pub fn from_string(transaction: &str) -> Result { Transaction::from_str(transaction) @@ -37,6 +40,8 @@ impl Transaction { /// Get the transaction as a string. If you want to submit this transaction to the Aleo Network /// this function will create the string that should be submitted in the `POST` data. + /// + /// @returns {string} String representation of the transaction #[wasm_bindgen(js_name = toString)] #[allow(clippy::inherent_to_string)] pub fn to_string(&self) -> String { @@ -48,12 +53,16 @@ impl Transaction { /// This value can be used to query the status of the transaction on the Aleo Network to see /// if it was successful. If successful, the transaction will be included in a block and this /// value can be used to lookup the transaction data on-chain. + /// + /// @returns {string} Transaction id #[wasm_bindgen(js_name = transactionId)] pub fn transaction_id(&self) -> String { self.0.id().to_string() } /// Get the type of the transaction (will return "deploy" or "execute") + /// + /// @returns {string} Transaction type #[wasm_bindgen(js_name = transactionType)] pub fn transaction_type(&self) -> String { match &self.0 { diff --git a/wasm/src/programs/verifying_key.rs b/wasm/src/programs/verifying_key.rs index ec13be0ac..7481e52ca 100644 --- a/wasm/src/programs/verifying_key.rs +++ b/wasm/src/programs/verifying_key.rs @@ -20,6 +20,7 @@ use wasm_bindgen::prelude::wasm_bindgen; use std::ops::Deref; +/// Verifying key for a function within an Aleo program #[wasm_bindgen] #[derive(Clone, Debug)] pub struct VerifyingKey(VerifyingKeyNative); @@ -27,12 +28,17 @@ pub struct VerifyingKey(VerifyingKeyNative); #[wasm_bindgen] impl VerifyingKey { /// Construct a new verifying key from a byte array + /// + /// @param {Uint8Array} bytes Byte representation of a verifying key + /// @returns {VerifyingKey | Error} #[wasm_bindgen(js_name = "fromBytes")] pub fn from_bytes(bytes: &[u8]) -> Result { Ok(Self(VerifyingKeyNative::from_bytes_le(bytes).map_err(|e| e.to_string())?)) } /// Create a byte array from a verifying key + /// + /// @returns {Uint8Array | Error} Byte representation of a verifying key #[wasm_bindgen(js_name = "toBytes")] pub fn to_bytes(&self) -> Result, String> { self.0.to_bytes_le().map_err(|_| "Failed to serialize verifying key".to_string()) diff --git a/wasm/src/record/record_ciphertext.rs b/wasm/src/record/record_ciphertext.rs index ab35e6714..5d8b01798 100644 --- a/wasm/src/record/record_ciphertext.rs +++ b/wasm/src/record/record_ciphertext.rs @@ -27,27 +27,39 @@ pub struct RecordCiphertext(RecordCiphertextNative); #[wasm_bindgen] impl RecordCiphertext { - /// Return a record ciphertext from a string. + /// Create a record ciphertext from a string + /// + /// @param {string} record String representation of a record ciphertext + /// @returns {RecordCiphertext | Error} Record ciphertext #[wasm_bindgen(js_name = fromString)] pub fn from_string(record: &str) -> Result { Self::from_str(record).map_err(|_| "The record ciphertext string provided was invalid".to_string()) } - /// Return the record ciphertext string. + /// Return the string reprensentation of the record ciphertext + /// + /// @returns {string} String representation of the record ciphertext #[allow(clippy::inherent_to_string)] #[wasm_bindgen(js_name = toString)] pub fn to_string(&self) -> String { self.0.to_string() } - /// Decrypt the record ciphertext into plaintext using the view key. + /// Decrypt the record ciphertext into plaintext using the view key. The record will only + /// decrypt if the record was encrypted by the account corresponding to the view key + /// + /// @param {ViewKey} view_key View key used to decrypt the ciphertext + /// @returns {RecordPlaintext | Error} Record plaintext object pub fn decrypt(&self, view_key: &ViewKey) -> Result { Ok(RecordPlaintext::from( self.0.decrypt(view_key).map_err(|_| "Decryption failed - view key did not match record".to_string())?, )) } - /// Returns `true` if the view key can decrypt the record ciphertext. + /// Determines if the account corresponding to the view key is the owner of the record + /// + /// @param {ViewKey} view_key View key used to decrypt the ciphertext + /// @returns {boolean} #[wasm_bindgen(js_name = isOwner)] pub fn is_owner(&self, view_key: &ViewKey) -> bool { self.0.is_owner(view_key) diff --git a/wasm/src/record/record_plaintext.rs b/wasm/src/record/record_plaintext.rs index 4ff6e2697..a16419548 100644 --- a/wasm/src/record/record_plaintext.rs +++ b/wasm/src/record/record_plaintext.rs @@ -23,7 +23,7 @@ use aleo_rust::Credits; use std::{ops::Deref, str::FromStr}; use wasm_bindgen::prelude::*; -/// Aleo record plaintext +/// Plaintext representation of an Aleo record #[wasm_bindgen] #[derive(Clone)] pub struct RecordPlaintext(RecordPlaintextNative); @@ -31,12 +31,17 @@ pub struct RecordPlaintext(RecordPlaintextNative); #[wasm_bindgen] impl RecordPlaintext { /// Return a record plaintext from a string. + /// + /// @param {string} record String representation of a plaintext representation of an Aleo record + /// @returns {RecordPlaintext | Error} Record plaintext #[wasm_bindgen(js_name = fromString)] pub fn from_string(record: &str) -> Result { Self::from_str(record).map_err(|_| "The record plaintext string provided was invalid".into()) } /// Returns the record plaintext string + /// + /// @returns {string} String representation of the record plaintext #[allow(clippy::inherent_to_string)] #[wasm_bindgen(js_name = toString)] pub fn to_string(&self) -> String { @@ -44,11 +49,18 @@ impl RecordPlaintext { } /// Returns the amount of microcredits in the record + /// + /// @returns {u64} Amount of microcredits in the record pub fn microcredits(&self) -> u64 { self.0.microcredits().unwrap_or(0) } /// Attempt to get the serial number of a record to determine whether or not is has been spent + /// + /// @param {PrivateKey} private_key Private key of the account that owns the record + /// @param {string} program_id Program ID of the program that the record is associated with + /// @param {string} record_name Name of the record + /// @returns {string | Error} Serial number of the record #[wasm_bindgen(js_name = serialNumberString)] pub fn serial_number_string( &self, From 3d16e4d0824da2c4247fe51f3eac97fac3a0260f Mon Sep 17 00:00:00 2001 From: collin <16715212+collinc97@users.noreply.github.com> Date: Thu, 27 Jul 2023 17:10:38 -0700 Subject: [PATCH 2/2] escape brackets for jsdoc to markdown compatibility --- wasm/src/programs/manager/deploy.rs | 6 +++--- wasm/src/programs/manager/execute.rs | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/wasm/src/programs/manager/deploy.rs b/wasm/src/programs/manager/deploy.rs index bc4301102..65468d67d 100644 --- a/wasm/src/programs/manager/deploy.rs +++ b/wasm/src/programs/manager/deploy.rs @@ -46,7 +46,7 @@ impl ProgramManager { /// @param private_key The private key of the sender /// @param program The source code of the program being deployed /// @param imports A javascript object holding the source code of any imported programs in the - /// form {"program_name1": "program_source_code", "program_name2": "program_source_code", ..}. + /// form \{"program_name1": "program_source_code", "program_name2": "program_source_code", ..\}. /// Note that all imported programs must be deployed on chain before the main program in order /// for the deployment to succeed /// @param fee_credits The amount of credits to pay as a fee @@ -55,7 +55,7 @@ impl ProgramManager { /// @param cache Cache the synthesized keys for future use /// @param imports (optional) Provide a list of imports to use for the program deployment in the /// form of a javascript object where the keys are a string of the program name and the values - /// are a string representing the program source code { "hello.aleo": "hello.aleo source code" } + /// are a string representing the program source code \{ "hello.aleo": "hello.aleo source code" \} /// @param fee_proving_key (optional) Provide a proving key to use for the fee execution /// @param fee_verifying_key (optional) Provide a verifying key to use for the fee execution /// @returns {Transaction | Error} @@ -142,7 +142,7 @@ impl ProgramManager { /// @param cache Cache the synthesized keys for future use /// @param imports (optional) Provide a list of imports to use for the deployment fee estimation /// in the form of a javascript object where the keys are a string of the program name and the values - /// are a string representing the program source code { "hello.aleo": "hello.aleo source code" } + /// are a string representing the program source code \{ "hello.aleo": "hello.aleo source code" \} /// @returns {u64 | Error} #[wasm_bindgen(js_name = estimateDeploymentFee)] pub async fn estimate_deployment_fee( diff --git a/wasm/src/programs/manager/execute.rs b/wasm/src/programs/manager/execute.rs index cb07749ca..98df68288 100644 --- a/wasm/src/programs/manager/execute.rs +++ b/wasm/src/programs/manager/execute.rs @@ -53,7 +53,7 @@ impl ProgramManager { /// keys will be deallocated from memory after the transaction is executed. /// @param imports (optional) Provide a list of imports to use for the function execution in the /// form of a javascript object where the keys are a string of the program name and the values - /// are a string representing the program source code { "hello.aleo": "hello.aleo source code" } + /// are a string representing the program source code \{ "hello.aleo": "hello.aleo source code" \} /// @param proving_key (optional) Provide a verifying key to use for the function execution /// @param verifying_key (optional) Provide a verifying key to use for the function execution #[wasm_bindgen] @@ -106,7 +106,7 @@ impl ProgramManager { /// keys will be deallocated from memory after the transaction is executed. /// @param imports (optional) Provide a list of imports to use for the function execution in the /// form of a javascript object where the keys are a string of the program name and the values - /// are a string representing the program source code { "hello.aleo": "hello.aleo source code" } + /// are a string representing the program source code \{ "hello.aleo": "hello.aleo source code" \} /// @param proving_key (optional) Provide a verifying key to use for the function execution /// @param verifying_key (optional) Provide a verifying key to use for the function execution /// @param fee_proving_key (optional) Provide a proving key to use for the fee execution @@ -203,7 +203,7 @@ impl ProgramManager { /// @param cache Cache the proving and verifying keys in the ProgramManager's memory. /// @param imports (optional) Provide a list of imports to use for the fee estimation in the /// form of a javascript object where the keys are a string of the program name and the values - /// are a string representing the program source code { "hello.aleo": "hello.aleo source code" } + /// are a string representing the program source code \{ "hello.aleo": "hello.aleo source code" \} /// @param proving_key (optional) Provide a verifying key to use for the fee estimation /// @param verifying_key (optional) Provide a verifying key to use for the fee estimation /// @returns {u64 | Error} Fee in microcredits