refactor: improve doc comments, other small fixes

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

@@ -66,7 +66,9 @@ proc.authenticate_account_origin
     # => [storage_offset, storage_size]
 end
 
-#! Authenticates that the invocation of a kernel procedure originates from the account context.
+#! Verifies that the procedure to be invoked against the foreign account is part of its code.
+#! TODO: it is a temporary solution. This and other `*_foreign` procedures should be removed after 
+#! the refactoring of the `DYN` operation (see miden-vm/#1091) and the fix of the CALLER operation. 
 #!
 #! Stack: [FOREIGN_PROC_ROOT]
 #! Output: [storage_offset, storage_size, ...]
@@ -953,15 +955,16 @@ export.get_note_serial_number
 end
 
 #! Tells the transaction kernel that we are about to execute a procedure on a foreign account.
-#! Loads the data of the specified foreign account to the memory and moves the pointer of the 
-#! currently accessing account to it. 
+#!
+#! Checks whether the current foreign account was already loaded to the memory, and loads it if not.
+#! Moves the account pointer to the currently accessing foreign account.
 #!
 #! Inputs:
 #!   Operand stack: [KERNEL_PROCEDURE_HASH, foreign_account_id, pad(11)]
 #!   Advice map: {
 #!     FOREIGN_ACCOUNT_ID: [[foreign_account_id, 0, 0, account_nonce], VAULT_ROOT, STORAGE_ROOT, CODE_ROOT],
 #!     STORAGE_ROOT: [[STORAGE_SLOT_DATA]],
-#!     CODE_ROOT: [[ACCOUNT_PROCEDURE_DATA]]
+#!     CODE_ROOT: [num_procs, [ACCOUNT_PROCEDURE_DATA]]
 #!   }
 #! Outputs:
 #!   Operand stack: []
@@ -1047,7 +1050,8 @@ export.start_foreign_context
         # AS => []
     end
 
-    # make sure that the state of the loaded foreign account is valid
+    # make sure that the state of the loaded foreign account corresponds to this commitment in the 
+    # account database
     exec.account::validate_current_foreign_account
     # => []
 end

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

@@ -109,6 +109,9 @@ const.MAX_NUM_STORAGE_SLOTS=MAX_STORAGE_SLOT_INDEX+1
 # Depth of the account database tree.
 const.ACCOUNT_TREE_DEPTH=64
 
+# The number of field elements it takes to store one account storage slot.
+const.ACCOUNT_STORAGE_SLOT_LENGTH=8
+
 # EVENTS
 # =================================================================================================
 
@@ -730,7 +733,7 @@ end
 #!   Operand stack: []
 #! 
 #! Where:
-#! - STORAGE_COMMITMENT is the commitment of the foreign account's storage.
+#! - STORAGE_COMMITMENT is the commitment of the current account's storage.
 #! - STORAGE_SLOT_DATA is the data contained in the storage slot which is constructed as follows: 
 #!   [SLOT_VALUE, slot_type, 0, 0, 0]
 #!
@@ -745,7 +748,7 @@ export.save_account_storage_data
 
     # push the length of the storage slot data onto the operand stack and compute the number of 
     # storage slots from it 
-    adv_push.1 div.8
+    adv_push.1 div.ACCOUNT_STORAGE_SLOT_LENGTH
     # OS => [num_storage_slots, STORAGE_COMMITMENT]
     # AS => [[STORAGE_SLOT_DATA]]
 
@@ -759,9 +762,9 @@ export.save_account_storage_data
     # OS => [num_storage_slots, STORAGE_COMMITMENT]
     # AS => [[STORAGE_SLOT_DATA]]
 
-    # setup acct_storage_slots_offset and end_ptr for reading from advice stack
+    # setup acct_storage_slots_ptr and end_ptr for reading from advice stack
     mul.2 exec.memory::get_acct_storage_slots_section_ptr dup movdn.2 add swap
-    # OS => [acct_storage_slots_offset, end_ptr, STORAGE_COMMITMENT]
+    # OS => [acct_storage_slots_ptr, end_ptr, STORAGE_COMMITMENT]
     # AS => [[STORAGE_SLOT_DATA]]
 
     # pad stack before reading from advice stack
@@ -799,10 +802,10 @@ end
 #!   Operand stack: []
 #! 
 #! Where:
-#! - CODE_COMMITMENT is the commitment of the foreign account's code.
+#! - CODE_COMMITMENT is the commitment of the current account's code.
 #! - num_procs is the number of foreign account's procedures.
 #! - ACCOUNT_PROCEDURE_DATA is the information about account procedure which is constructed as 
-#!   follows: [PROCEDURE_MAST_ROOT, storage_offset, 0, 0, 0]
+#!   follows: [PROCEDURE_MAST_ROOT, storage_offset, storage_size, 0, 0]
 #!
 #! Panics if:
 #! - the number of account procedures exceeded the maximum limit of 256
@@ -972,23 +975,19 @@ export.get_foreign_account_ptr
         padw dup.4 mem_loadw
         # => [FIRST_DATA_WORD, curr_account_ptr', foreign_account_id]
 
-        # check whether the first data words is an empty word, preserve the last value in this word 
-        # (account id)
-        dup.3 movdn.4 padw eqw movdn.8 dropw dropw
-        # => [is_empty_word, last_data_value, curr_account_ptr', foreign_account_id]
+        # check whether the last value in the word equals zero. If so, it will mean that this memory
+        # block was not initialized.
+        drop drop drop dup eq.0
+        # => [is_empty_block, last_data_value, curr_account_ptr', foreign_account_id]
 
         # check whether the current id matches the foreign id 
         swap dup.3 eq
         # => [is_equal_id, is_empty_word, curr_account_ptr', foreign_account_id]
 
-        # get the sum of the flags to obtain the loop flag
-        dup movdn.4 add
-        # => [flags_sum, curr_account_ptr', foreign_account_id, is_equal_id]
-
         # get the loop flag
-        # it equals 0 if both `is_equal_id` and `is_empty_word` flags equal 0, so we should continue 
-        # iterating
-        eq.0
+        # it equals 1 if both `is_equal_id` and `is_empty_block` flags are equal to 0, so we should 
+        # continue iterating
+        dup movdn.4 or not
         # => [loop_flag, curr_account_ptr', foreign_account_id, is_equal_id]
     end
 

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

@@ -124,7 +124,9 @@ const.KERNEL_PROCEDURES_PTR=401
 # ACCOUNT DATA
 # -------------------------------------------------------------------------------------------------
 
-# The largest memory address which can be used to load the foreign account data
+# The largest memory address which can be used to load the foreign account data.
+# It is computed as `2048 * 64` -- this is the memory address where the data block of the 64th 
+# account starts.
 const.MAX_FOREIGN_ACCOUNT_PTR=131072
 
 # The memory address at which the native account data is stored.

miden-lib/src/transaction/procedures/kernel_v0.rs

@@ -68,7 +68,7 @@ pub const KERNEL0_PROCEDURES: [Digest; 34] = [
     // get_block_number
     digest!(0xd483c8edceb956d, 0xf9f8d62043fcf072, 0xb917fc68b6e01ad1, 0x3ef8d736e7331692),
     // start_foreign_context
-    digest!(0x19d6597936952587, 0x877c5ec8486dde0e, 0xdc72b7bb6b2a23db, 0x59628465e2eca92b),
+    digest!(0x5d64e0991481cb12, 0x4ea85139f6c7672d, 0xcbcb5b1b94536c73, 0xd61b2581bc5ec88),
     // end_foreign_context
     digest!(0x3770db711ce9aaf1, 0xb6f3c929151a5d52, 0x3ed145ec5dbee85f, 0xf979d975d7951bf6),
     // update_expiration_block_num

objects/src/accounts/code/mod.rs

@@ -195,7 +195,7 @@ impl AccountCode {
     ///
     /// This is done by first converting each procedure into 8 field elements as follows:
     /// ```text
-    /// [PROCEDURE_MAST_ROOT, storage_offset, 0, 0, storage_size]
+    /// [PROCEDURE_MAST_ROOT, storage_offset, storage_size, 0, 0]
     /// ```
     /// And then concatenating the resulting elements into a single vector.
     pub fn as_elements(&self) -> Vec<Felt> {

objects/src/accounts/code/procedure.rs

@@ -94,7 +94,7 @@ impl From<AccountProcedureInfo> for [Felt; 8] {
         // copy the storage offset into value[4]
         result[4] = Felt::from(value.storage_offset);
 
-        // copy the storage size into value[7]
+        // copy the storage size into value[5]
         result[5] = Felt::from(value.storage_size);
 
         result