refactor: update comments, update padding for called and syscalled procs

miden-lib/asm/kernels/transaction/api.masm

@@ -8,6 +8,13 @@ use.miden::kernels::tx::memory
 use.miden::kernels::tx::note
 use.miden::kernels::tx::tx
 
+# NOTE
+# =================================================================================================
+# Procedures in this module are expected to be invoked using a `call` instruction. It makes no    #
+# guarantees about the contents of the `PAD` elements shown in the inputs and outputs. It is the  #
+# caller's responsibility to make sure these elements do not contain any meaningful data.         #
+# =================================================================================================
+
 # ERRORS
 # =================================================================================================
 
@@ -504,7 +511,7 @@ end
 
 #! Creates a new note and returns the index of the note.
 #!
-#! Inputs: [tag, aux, note_type, RECIPIENT, PAD(9)]
+#! Inputs:  [tag, aux, note_type, RECIPIENT, PAD(9)]
 #! Outputs: [note_idx, PAD(15)]
 #!
 #! tag is the tag to be included in the note.
@@ -523,10 +530,6 @@ end
 
 #! Adds the ASSET to the note specified by the index.
 #!
-#! This procedure is expected to be invoked using a `call` instruction. It makes no guarantees about
-#! the contents of the `PAD` elements shown below. It is the caller's responsibility to make sure
-#! these elements do not contain any meaningful data.
-#!
 #! Inputs:  [note_idx, ASSET, PAD(11)]
 #! Outputs: [note_idx, ASSET, PAD(11)]
 #!

miden-lib/asm/miden/tx.masm

@@ -55,32 +55,46 @@ end
 
 #! Creates a new note and returns the index of the note.
 #!
-#! Inputs: [tag, aux, note_type, RECIPIENT, PAD(9)]
-#! Outputs: [note_idx, PAD(15)]
+#! Inputs:  [tag, aux, note_type, RECIPIENT, ...]
+#! Outputs: [note_idx, ...]
 #!
 #! tag is the tag to be included in the note.
 #! aux is the auxiliary metadata to be included in the note.
 #! note_type is the storage type of the note
 #! RECIPIENT is the recipient of the note.
 #! note_idx is the index of the crated note.
 export.create_note
+    # pad the stack before the syscall to prevent accidental modification of the deeper stack 
+    # elements 
+    push.0 movdn.7 padw padw movdnw.3 movdnw.3
+    # => [tag, aux, note_type, RECIPIENT, PAD(9)]
+
     syscall.create_note
     # => [note_idx, PAD(15)]
+
+    # remove excess PADs from the stack 
+    movdnw.3 dropw dropw dropw movdn.3 drop drop drop
+    # => [note_idx]
 end
 
 #! Adds the ASSET to the note specified by the index.
 #!
-#! This procedure is expected to be invoked using a `call` instruction. It makes no guarantees about
-#! the contents of the `PAD` elements shown below. It is the caller's responsibility to make sure
-#! these elements do not contain any meaningful data.
-#!
-#! Inputs:  [ASSET, note_idx, PAD(11)]
-#! Outputs: [ASSET, note_idx, PAD(11)]
+#! Inputs:  [ASSET, note_idx, ...]
+#! Outputs: [ASSET, note_idx, ...]
 #!
 #! note_idx is the index of the note to which the asset is added.
 #! ASSET can be a fungible or non-fungible asset.
 export.add_asset_to_note
-    movup.4 syscall.add_asset_to_note movdn.4
+    # pad the stack before the syscall to prevent accidental modification of the deeper stack 
+    # elements 
+    push.0.0.0 padw padw movupw.3 movup.15 movup.4
+    # => [note_idx, ASSET, PAD(11)]
+
+    syscall.add_asset_to_note 
+    # => [note_idx, ASSET, PAD(11)]
+
+    # remove excess PADs from the stack 
+    movdn.15 movdnw.3 dropw dropw drop drop drop movdn.4
     # => [ASSET, note_idx]
 end
 

miden-tx/src/tests/mod.rs

@@ -686,14 +686,30 @@ fn executed_transaction_output_notes() {
         ## ========================================================================================
         #TODO: Move this into an account library
         proc.create_note
+            # pad the stack before the call to prevent accidental modification of the deeper stack 
+            # elements 
+            push.0 movdn.7 padw padw movdnw.3 movdnw.3
+            # => [tag, aux, note_type, RECIPIENT, PAD(9)]
+
             call.{ACCOUNT_CREATE_NOTE_MAST_ROOT}
+            # => [note_idx, PAD(15)]
 
-            swapw dropw swapw dropw swapw dropw
+            # remove excess PADs from the stack 
+            movdnw.3 dropw dropw dropw movdn.3 drop drop drop
             # => [note_idx]
         end
 
         proc.add_asset_to_note
+            # pad the stack before the syscall to prevent accidental modification of the deeper stack 
+            # elements 
+            push.0.0.0 padw padw movupw.3 movup.15
+            # => [ASSET, note_idx, PAD(11)]
+
             call.{ACCOUNT_ADD_ASSET_TO_NOTE_MAST_ROOT}
+            # => [ASSET, note_idx, PAD(11)]
+
+            # remove excess PADs from the stack 
+            movdn.15 movdnw.3 dropw dropw drop drop drop
             # => [ASSET, note_idx]
 
             dropw

objects/src/testing/account_code.rs

@@ -5,16 +5,16 @@ use crate::accounts::AccountCode;
 // The MAST root of the default account's interface. Use these constants to interact with the
 // account's procedures.
 const MASTS: [&str; 13] = [
-    "0x48752d42a7d72e35e970d80acd1eedec97235bb7d764dd0afb68a04f46f19b8d",
-    "0x97e51e5e50b5c23140730dfa076e6c0931d4894b7b04ebf2b7dc917e99ed5df2",
+    "0x8afef26974e7fdb12d7e2af49e92f68b09c504e5c530c1283711653f242fd350",
+    "0x9a51f741356a6c27dd116c590ca116463ff41d46fddc890c0aa6c2dc0a5c86a9",
     "0xe3c24a1109379344874ac5dec91a6311e5563d0194ded29b44ed71535e78b34a",
-    "0x0dd674e785258d8b2d9ccd4d6765ff9e68bab1ce44e3fc7fb7d441e1fad8deab",
+    "0x10271f1549303e22f9562bfdb73da948407a276ea0ec470deb7ce6793c316562",
     "0x28c514e509fc044a2ea6cddbab0abf2b5fa589d5c91978ae9c935ab40e6ec402",
     "0xa61cdf8c75943d293ffcfca73ea07a6639dad1820d64586a2a292bb9f80a4296",
     "0x6877f03ef52e490f7c9e41b297fb79bb78075ff28c6e018aaa1ee30f73e7ea4b",
     "0x24e0a1587d4d1ddff74313518f5187f6042ffbe8f2ddc97d367a5c3da4b17d82",
-    "0x3d398ee00c42c35af0af9d14b7912d96360e43940e3927e42d1fcebb14c7142b",
-    "0x0450a7d4e19d66a6dbea52209b2a2334e0faa00d8bb09f87a0cc9e9f1e0c1b41",
+    "0x8afef26974e7fdb12d7e2af49e92f68b09c504e5c530c1283711653f242fd350",
+    "0x1e7fdec663be004a894d024a9354e5721f0c1b439ecce73a40e1689cf5379511",
     "0xcd34115714cdcda24f1d6968cbfb67b8b51c1751a2e25e9d6b4e18c35323e5ba",
     "0xff06b90f849c4b262cbfbea67042c4ea017ea0e9c558848a951d44b23370bec5",
     "0x8ef0092134469a1330e3c468f57c7f085ce611645d09cc7516c786fefc71d794",
@@ -117,8 +117,6 @@ impl AccountCode {
         export.create_note
             exec.tx::create_note
             # => [note_idx]
-
-            swapw dropw swap drop
         end
 
         # acct proc 9