Merge branch 'main' into ajl-ntx-tutorial

Author: partylikeits1983

docs/src/rust-client/counter_contract_tutorial.md

@@ -118,15 +118,14 @@ Create a directory named `masm` at the **root** of your `miden-counter-contract`
 Initialize the `masm` directory:
 
 ```bash
-mkdir -p masm/accounts masm/scripts masm/accounts/auth
+mkdir -p masm/accounts masm/scripts
 ```
 
 This will create:
 
 ```text
 masm/
 ├── accounts/
-│   └── auth/
 └── scripts/
 ```
 
@@ -149,13 +148,13 @@ The import `std::sys` contains a useful procedure for truncating the operand sta
 
 #### Here's a breakdown of what the `increment_count` procedure does:
 
-1. Pushes `0` onto the stack, representing the index of the storage slot to read.
-2. Calls `account::get_item` with the index of `0`.
+1. Pushes `COUNTER_SLOT`(=0) onto the stack, representing the index of the storage slot to read.
+2. Calls `account::get_item` with the index of `COUNTER_SLOT`.
 3. Pushes `1` onto the stack.
 4. Adds `1` to the count value returned from `account::get_item`.
-5. _For demonstration purposes_, calls `debug.stack` to see the state of the stack
-6. Pushes `0` onto the stack, which is the index of the storage slot we want to write to.
-7. Calls `account::set_item` which saves the incremented count to storage at index `0`
+5. _For demonstration purposes_, calls `debug.stack` to see the state of the stack.
+6. Pushes `COUNTER_SLOT` onto the stack again, which is the index of the storage slot we want to write to.
+7. Calls `account::set_item` which saves the incremented count to storage at index `COUNTER_SLOT`.
 8. Calls `sys::truncate_stack` to truncate the stack to size 16.
 
 Inside of the `masm/accounts/` directory, create the `counter.masm` file:
@@ -164,9 +163,10 @@ Inside of the `masm/accounts/` directory, create the `counter.masm` file:
 use.miden::account
 use.std::sys
 
+const.COUNTER_SLOT=0
 # => []
 export.get_count
-    push.0
+    push.COUNTER_SLOT
     # => [index]
 
     exec.account::get_item
@@ -178,7 +178,7 @@ end
 
 # => []
 export.increment_count
-    push.0
+    push.COUNTER_SLOT
     # => [index]
 
     exec.account::get_item
@@ -190,7 +190,7 @@ export.increment_count
     # debug statement with client
     debug.stack
 
-    push.0
+    push.COUNTER_SLOT
     # [index, count+1]
 
     exec.account::set_item

docs/src/rust-client/custom_note_how_to.md

@@ -50,32 +50,46 @@ Below is the Miden Assembly code for the note:
 use.miden::note
 use.miden::contracts::wallets::basic->wallet
 
-# => [HASH_PREIMAGE_SECRET]
-begin
+# CONSTANTS
+# =================================================================================================
 
-    # Hashing the secret number
-    hperm
-    # => [F,E,D]
-    # E is digest
+const.EXPECTED_DIGEST_PTR=0
+const.ASSET_PTR=100
+
+# ERRORS
+# =================================================================================================
+
+const.ERROR_DIGEST_MISMATCH="Expected digest does not match computed digest"
 
-    dropw swapw dropw
+#! Inputs (arguments):  [HASH_PREIMAGE_SECRET]
+#! Outputs: []
+#!
+#! Note inputs are assumed to be as follows:
+#!  => EXPECTED_DIGEST
+begin
+    # => HASH_PREIMAGE_SECRET
+    # Hashing the secret number
+    hash
     # => [DIGEST]
 
     # Writing the note inputs to memory
-    push.0 exec.note::get_inputs drop drop
-    # => [DIGEST]
+    push.EXPECTED_DIGEST_PTR exec.note::get_inputs drop drop
 
-    # Pad stack and load note inputs from memory
-    padw push.0 mem_loadw
-    # => [INPUTS, DIGEST]
+    # Pad stack and load expected digest from memory
+    padw push.EXPECTED_DIGEST_PTR mem_loadw
+    # => [EXPECTED_DIGEST, DIGEST]
 
     # Assert that the note input matches the digest
     # Will fail if the two hashes do not match
-    assert_eqw
+    assert_eqw.err=ERROR_DIGEST_MISMATCH
     # => []
 
-    # Write the asset in note to memory address 0
-    push.0 exec.note::get_assets
+    # ---------------------------------------------------------------------------------------------
+    # If the check is successful, we allow for the asset to be consumed
+    # ---------------------------------------------------------------------------------------------
+
+    # Write the asset in note to memory address ASSET_PTR
+    push.ASSET_PTR exec.note::get_assets
     # => [num_assets, dest_ptr]
 
     drop
@@ -93,14 +107,16 @@ end
 
 ### How the assembly code works:
 
-1. **Passing the Secret:**  
+1. **Constants and Error Handling:**  
+   The code defines memory pointers (`EXPECTED_DIGEST_PTR` and `ASSET_PTR`) for better code organization and an error message for digest mismatches.
+2. **Passing the Secret:**  
    The secret number is passed as `Note Arguments` into the note.
-2. **Hashing the Secret:**  
-   The `hperm` instruction applies a hash permutation to the secret number, resulting in a hash that takes up four stack elements.
-3. **Stack Cleanup and Comparison:**  
-   The assembly code extracts the digest, loads the note inputs from memory and checks if the computed hash matches the note’s stored hash.
-4. **Asset Transfer:**  
-   If the hash of the number passed in as `Note Arguments` matches the hash stored in the note inputs, the script continues, and the asset stored in the note is loaded from memory and passed to Bob’s wallet via the `wallet::receive_asset` function.
+3. **Hashing the Secret:**  
+   The `hash` instruction applies a hash permutation to the secret number, resulting in a digest that takes up four stack elements.
+4. **Digest Comparison:**  
+   The assembly code loads the expected digest from the note inputs stored in memory and compares it with the computed hash. If they don't match, the transaction fails with a clear error message.
+5. **Asset Transfer:**  
+   If the hash of the number passed in as `Note Arguments` matches the hash stored in the note inputs, the script continues, and the asset stored in the note is loaded from memory and passed to Bob's wallet via the `wallet::receive_asset` function.
 
 ### 5. Consuming the note
 
@@ -291,8 +307,7 @@ async fn main() -> Result<(), ClientError> {
     // STEP 3: Create custom note
     // -------------------------------------------------------------------------
     println!("\n[STEP 3] Create custom note");
-    let mut secret_vals = vec![Felt::new(1), Felt::new(2), Felt::new(3), Felt::new(4)];
-    secret_vals.splice(0..0, Word::default().iter().cloned());
+    let secret_vals = vec![Felt::new(1), Felt::new(2), Felt::new(3), Felt::new(4)];
     let digest = Hasher::hash_elements(&secret_vals);
     println!("digest: {:?}", digest);
 

masm/notes/hash_preimage_note.masm

@@ -1,32 +1,46 @@
 use.miden::note
 use.miden::contracts::wallets::basic->wallet
 
-# => [HASH_PREIMAGE_SECRET]
-begin
+# CONSTANTS
+# =================================================================================================
 
-    # Hashing the secret number
-    hperm
-    # => [F,E,D]
-    # E is digest
+const.EXPECTED_DIGEST_PTR=0
+const.ASSET_PTR=100
+
+# ERRORS
+# =================================================================================================
+
+const.ERROR_DIGEST_MISMATCH="Expected digest does not match computed digest"
 
-    dropw swapw dropw
+#! Inputs (arguments):  [HASH_PREIMAGE_SECRET]
+#! Outputs: []
+#!
+#! Note inputs are assumed to be as follows:
+#!  => EXPECTED_DIGEST
+begin
+    # => HASH_PREIMAGE_SECRET
+    # Hashing the secret number
+    hash
     # => [DIGEST]
 
     # Writing the note inputs to memory
-    push.0 exec.note::get_inputs drop drop
-    # => [DIGEST]
+    push.EXPECTED_DIGEST_PTR exec.note::get_inputs drop drop
 
-    # Pad stack and load note inputs from memory
-    padw push.0 mem_loadw
-    # => [INPUTS, DIGEST]
+    # Pad stack and load expected digest from memory
+    padw push.EXPECTED_DIGEST_PTR mem_loadw
+    # => [EXPECTED_DIGEST, DIGEST]
 
     # Assert that the note input matches the digest
     # Will fail if the two hashes do not match
-    assert_eqw
+    assert_eqw.err=ERROR_DIGEST_MISMATCH
     # => []
 
-    # Write the asset in note to memory address 0
-    push.0 exec.note::get_assets
+    # ---------------------------------------------------------------------------------------------
+    # If the check is successful, we allow for the asset to be consumed
+    # ---------------------------------------------------------------------------------------------
+
+    # Write the asset in note to memory address ASSET_PTR
+    push.ASSET_PTR exec.note::get_assets
     # => [num_assets, dest_ptr]
 
     drop

rust-client/src/bin/hash_preimage_note.rs

@@ -19,7 +19,7 @@ use miden_client::{
     rpc::{Endpoint, TonicRpcClient},
     store::InputNoteRecord,
     transaction::{OutputNote, TransactionKernel, TransactionRequestBuilder},
-    Client, ClientError, Felt, Word,
+    Client, ClientError, Felt,
 };
 use miden_objects::account::NetworkId;
 use miden_objects::Hasher;
@@ -176,8 +176,7 @@ async fn main() -> Result<(), ClientError> {
     // STEP 3: Create custom note
     // -------------------------------------------------------------------------
     println!("\n[STEP 3] Create custom note");
-    let mut secret_vals = vec![Felt::new(1), Felt::new(2), Felt::new(3), Felt::new(4)];
-    secret_vals.splice(0..0, Word::default().iter().cloned());
+    let secret_vals = vec![Felt::new(1), Felt::new(2), Felt::new(3), Felt::new(4)];
     let digest = Hasher::hash_elements(&secret_vals);
     println!("digest: {:?}", digest);