refactor: optimize inputs, improve docs and comments, impl digest! macro

docs/architecture/transactions/contexts.md

@@ -70,7 +70,7 @@ The [account API](https://github.com/0xPolygonMiden/miden-base/blob/main/miden-l
 #! Add the specified asset to the vault.
 #! ...
 export.add_asset
-    exec.kernel_invocation::account_vault_add_asset_offset
+    exec.kernel_proc_offsets::account_vault_add_asset_offset
     syscall.exec_kernel_proc
 end
 ```

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

@@ -12,10 +12,10 @@ use.kernel::tx
 # NOTE
 # =================================================================================================
 # `exec_kernel_proc` procedure is expected to be invoked using a `syscall` instruction. It makes  #
-# no guarantees about the contents of the `PAD` elements shown in the inputs and outputs. It is   #
+# 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.     #
-# All other procedures must be invoked only using a `dynexec` instruction by their hashes stored  #
-# in the memory.                                                                                  #
+# All other procedures must be invoked using a `dynexec` instruction by their hashes stored in    #
+# the memory.                                                                                     #
 # =================================================================================================
 
 # ERRORS
@@ -598,8 +598,8 @@ end
 
 #! Creates a new note and returns the index of the note.
 #!
-#! Inputs: [KERNEL_PROCEDURE_HASH, tag, aux, note_type, execution_hint, RECIPIENT, PAD(4)]
-#! Outputs: [note_idx, PAD(15)]
+#! Inputs: [KERNEL_PROCEDURE_HASH, tag, aux, note_type, execution_hint, RECIPIENT, pad(4)]
+#! Outputs: [note_idx, pad(15)]
 #!
 #! tag is the tag to be included in the note.
 #! aux is the auxiliary metadata to be included in the note.
@@ -613,16 +613,16 @@ export.create_note
 
     # authenticate that the procedure invocation originates from the account context
     exec.authenticate_account_origin drop
-    # => [tag, aux, note_type, execution_hint, RECIPIENT, PAD(8)]
+    # => [tag, aux, note_type, execution_hint, RECIPIENT, pad(8)]
 
     exec.tx::create_note
-    # => [note_idx, PAD(15)]
+    # => [note_idx, pad(15)]
 end
 
 #! Adds the ASSET to the note specified by the index.
 #!
-#! Inputs:  [KERNEL_PROCEDURE_HASH, note_idx, ASSET, PAD(7)]
-#! Outputs: [note_idx, ASSET, PAD(11)]
+#! Inputs:  [KERNEL_PROCEDURE_HASH, note_idx, ASSET, pad(7)]
+#! Outputs: [note_idx, ASSET, pad(11)]
 #!
 #! note_idx is the index of the the note to which the asset is added.
 #! ASSET can be a fungible or non-fungible asset.
@@ -766,32 +766,32 @@ end
 
 #! Executes a kernel procedure specified by its offset.
 #!
-#! Inputs: [procedure_offset, procedure_inputs, PAD(*)]
-#! Outputs: [procedure_outputs, PAD(*)]
+#! Inputs: [procedure_offset, <procedure_inputs>, <pad>]
+#! Outputs: [<procedure_outputs>, <pad>]
 #!
 #! Where:
 #! - procedure_offset is an offset of the kernel procedure, specified in the 
-#!   `miden/kernel_invocation.masm` file.
+#!   `miden/kernel_proc_offsets.masm` file.
 #! - procedure_inputs are inputs of the procedure to be executed, which is specified by the 
 #!   procedure_offset. Note that the length of this inputs cannot exceed 12 elements, since the 
 #!   first word on the stack will be occupied by the procedure hash. 
 #! - procedure_outputs are the outputs of the procedure to be executed. 
 export.exec_kernel_proc
     # compute the memory pointer at which desired procedure is stored
     exec.memory::get_kernel_procedures_ptr add
-    # => [procedure_pointer, procedure_inputs, PAD(*)]
+    # => [procedure_pointer, <procedure_inputs>, <pad>]
 
     # prepare stack for procedure hash obtaining
     padw movup.4
-    # => [procedure_pointer, 0, 0, 0, 0, procedure_inputs, PAD(*)]
+    # => [procedure_pointer, 0, 0, 0, 0, <procedure_inputs>, <pad>]
 
     # load kernel procedure hash
     mem_loadw
-    # => [KERNEL_PROCEDURE_HASH, procedure_inputs, PAD(*)]
+    # => [KERNEL_PROCEDURE_HASH, <procedure_inputs>, <pad>]
 
     # execute loaded procedure
     dynexec
-    # => [procedure_outputs, PAD(*)]
+    # => [<procedure_outputs>, <pad>]
 
     exec.sys::truncate_stack
 end

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

@@ -529,6 +529,17 @@ export.get_tx_hash
     padw push.TX_HASH_PTR mem_loadw
 end
 
+#! Returns the kernel root used in the last known block.
+#!
+#! Stack: []
+#! Output: [KERNEL_ROOT]
+#!
+#! Where:
+#! - KERNEL_ROOT is an accumulative hash from all kernel hashes.
+export.get_kernel_root
+    padw push.KERNEL_ROOT_PTR mem_loadw
+end
+
 #! Returns the proof hash of the last known block.
 #!
 #! Stack: []

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

@@ -101,16 +101,21 @@ end
 # KERNEL DATA
 # =================================================================================================
 
-#! Saves the hashes of the kernel procedures to memory and verifies that it matches the KERNEL_HASH
-#! public input.
+
+#! Saves the procedure hashes of the chosen kernel to memory. Verifies that kernel root and kernel 
+#! hash match the sequential hash of all kernels and sequential hash of kernel procedures 
+#! respectively. 
 #! 
-#! Stack: [kernel_offset]
-#! Advice Stack: [KERNEL_ROOT]
-#! Advice Map: {
+#! Inputs:
+#!   Stack: []
+#!   Advice stack: [kernel_offset]
+#!   Advice map: {
 #!     KERNEL_ROOT: [KERNEL_HASHES]
 #!     KERNEL_HASH: [KERNEL_PROCEDURE_HASHES]
-#! }
-#! Output: []
+#!   }
+#! Outputs:
+#!   Stack: []
+#!   Advice stack: []
 #! 
 #! Where:
 #! - kernel_offset, index of the desired kernel in the array of all kernels available for the 
@@ -119,69 +124,78 @@ end
 #! - [KERNEL_HASHES], array of each kernel hash
 #! - [KERNEL_PROCEDURE_HASHES], array of procedure hashes of the current kernel
 proc.process_kernel_data
-    # move the kernel root to the stack 
-    adv_loadw
-    # S  => [KERNEL_ROOT, kernel_offset]
+    # move the kernel offset to the operand stack 
+    adv_push.1
+    # OS  => [kernel_offset]
+    # AS => []
+
+    # load the kernel root from the memory
+    exec.memory::get_kernel_root
+    # OS  => [KERNEL_ROOT, kernel_offset]
     # AS => []
 
     # push the kernel hashes from the advice map to the advice stack 
     adv.push_mapvaln
-    # S  => [KERNEL_ROOT, kernel_offset]
+    # OS  => [KERNEL_ROOT, kernel_offset]
     # AS => [len_felts, [KERNEL_HASHES]]
 
     # move the number of felt elements in the [KERNEL_HASHES] array to the stack and get the 
     # number of Words from it
     adv_push.1 div.4
-    # S  => [len_words, KERNEL_ROOT, kernel_offset]
+    # OS  => [len_words, KERNEL_ROOT, kernel_offset]
     # AS => [[KERNEL_HASHES]]
 
     # get the pointer to the memory where kernel hashes will be stored
     # Note: for now we use the same address for kernel hash and for kernel procedures since there is
     # only one kernel and its hash will be overwritten by the procedures anyway. 
     exec.memory::get_kernel_procedures_ptr swap
-    # S  => [len_words, kernel_mem_ptr, KERNEL_ROOT, kernel_offset]
+    # OS  => [len_words, kernel_mem_ptr, KERNEL_ROOT, kernel_offset]
     # AS => [[KERNEL_HASHES]]
 
     # store the kernel hashes in memory
     exec.mem::pipe_words_to_memory
-    # S  => [SEQ_HASH, kernel_mem_ptr', KERNEL_ROOT, kernel_offset]
+    # OS  => [SEQ_HASH, kernel_mem_ptr', KERNEL_ROOT, kernel_offset]
     # AS => []
 
     # assert that sequential hash matches the precomputed kernel root
     movup.4 drop assert_eqw
-    # S  => [kernel_offset]
+    # OS  => [kernel_offset]
+    # AS => []
 
     # get the hash of the kernel which will be used in the current transaction
     exec.memory::get_kernel_procedures_ptr add 
-    # S  => [kernel_ptr]
+    # OS  => [kernel_ptr]
+    # AS => []
 
     padw movup.4 mem_loadw
-    # S  => [KERNEL_HASH]
+    # OS  => [KERNEL_HASH]
+    # AS => []
 
     # push the procedure hashes of the chosen kernel from the advice map to the advice stack    
     adv.push_mapvaln
-    # S  => [KERNEL_HASH]
+    # OS  => [KERNEL_HASH]
     # AS => [len_felts, [PROC_HASHES]]
 
     # move the number of felt elements in the [PROC_HASHES] array to the stack and get the 
     # number of Words from it
     adv_push.1 div.4
-    # S  => [len_words, KERNEL_HASH]
+    # OS  => [len_words, KERNEL_HASH]
     # AS => [[PROC_HASHES]]
 
     # get the pointer to the memory where hashes of the kernel procedures will be stored
     exec.memory::get_kernel_procedures_ptr swap
-    # S  => [len_words, kernel_procs_ptr, KERNEL_HASH]
+    # OS  => [len_words, kernel_procs_ptr, KERNEL_HASH]
     # AS => [[PROC_HASHES]]
 
     # store the kernel procedures to the memory
     exec.mem::pipe_words_to_memory
-    # S  => [SEQ_HASH, kernel_procs_ptr', KERNEL_HASH]
+    # OS  => [SEQ_HASH, kernel_procs_ptr', KERNEL_HASH]
     # AS => []
 
     # assert that the precomputed hash matches the computed one
     movup.4 drop assert_eqw
-    # S  => []
+    # OS  => []
+    # AS => []
 end
 
 # BLOCK DATA
@@ -1182,10 +1196,8 @@ end
 #!     account_id, 
 #!     INITIAL_ACCOUNT_HASH, 
 #!     INPUT_NOTES_COMMITMENT, 
-#!     kernel_offset,
 #!  ]
 #! Advice stack: [
-#!     KERNEL_ROOT
 #!     PREVIOUS_BLOCK_HASH,
 #!     CHAIN_MMR_HASH,
 #!     ACCOUNT_ROOT,
@@ -1195,6 +1207,7 @@ end
 #!     PROOF_HASH,
 #!     [block_num, version, timestamp, 0],
 #!     NOTE_ROOT,
+#!     kernel_offset
 #!     [account_id, 0, 0, account_nonce],
 #!     ACCOUNT_VAULT_ROOT,
 #!     ACCOUNT_STORAGE_ROOT,
@@ -1215,8 +1228,6 @@ end
 #! - account_id, the account that the transaction is being executed against.
 #! - INITIAL_ACCOUNT_HASH, account state prior to the transaction, EMPTY_WORD for new accounts.
 #! - INPUT_NOTES_COMMITMENT, see `transaction::api::get_input_notes_commitment`.
-#! - kernel_offset, index of the desired kernel in the array of all kernels available for the 
-#!   current transaction.
 #! - KERNEL_ROOT, accumulative hash from all kernel hashes.
 #! - PREVIOUS_BLOCK_HASH, hash of the previous block.
 #! - CHAIN_MMR_HASH, sequential hash of the reference MMR.
@@ -1228,6 +1239,8 @@ end
 #! - version, the current protocol version.
 #! - timestamp, the current timestamp.
 #! - NOTE_ROOT, root of the tree with all notes created in the block.
+#! - kernel_offset, index of the desired kernel in the array of all kernels available for the 
+#!   current transaction.
 #! - account_nonce, account's nonce.
 #! - ACCOUNT_VAULT_ROOT, account's vault root.
 #! - ACCOUNT_STORAGE_ROOT, account's storage root.
@@ -1240,8 +1253,8 @@ export.prepare_transaction
     exec.process_global_inputs
     # => []
 
-    exec.process_kernel_data
     exec.process_block_data
+    exec.process_kernel_data
     exec.process_chain_data
     exec.process_account_data
     exec.process_input_notes_data