FPI: foreign account data loader

CHANGELOG.md

@@ -16,6 +16,7 @@
 - Added `AccountStorageHeader` (#876).
 - Implemented generation of transaction kernel procedure hashes in build.rs (#887).
 - [BREAKING] `send_asset` procedure was removed from the basic wallet (#829).
+- Implemented ability to invoke procedures against the foreign account (#882, #890, #896).
 
 ## 0.5.1 (2024-08-28) - `miden-objects` crate only
 

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

@@ -1,4 +1,5 @@
 use.std::collections::smt
+use.std::mem
 use.std::sys
 
 use.kernel::account
@@ -863,20 +864,99 @@ export.get_note_serial_number
 end
 
 #! Tells the transaction kernel that we are about to execute a procedure on a foreign account.
-#!
-#! Inputs:  [KERNEL_PROCEDURE_HASH, foreign_account_id, pad(11)]
-#! Outputs: [pad(16)]
+#! Loads the data of the specified foreign account to the memory and moves the pointer of the 
+#! currently accessing account to it. 
+#!
+#! 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]]
+#!   }
+#! Outputs:
+#!   Operand stack: []
 #!
 #! Where:
-#! - foreign_account_id is the ID of the foreign account whose procedure is going to be executed. 
+#! - foreign_account_id is the ID of the foreign account whose procedure is going to be executed.
+#! - FOREIGN_ACCOUNT_ID is the word constructed from the foreign_account_id as follows:
+#!   [foreign_account_id, 0, 0, 0].
+#! - account_nonce is the nonce of the foreign account.
+#! - VAULT_ROOT is the commitment of the foreign account's vault.
+#! - STORAGE_ROOT is the commitment of the foreign 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]
+#! - CODE_ROOT is the commitment of the foreign account's code.
+#! - ACCOUNT_PROCEDURE_DATA is the information about account procedure which is constructed as 
+#!   follows: [PROCEDURE_MAST_ROOT, storage_offset, 0, 0, 0]
 #!
 #! Panics if:
 #! - the current context is not a native context.
 export.start_foreign_context
     # check that this procedure was executed against the native account
     exec.memory::assert_native_account
+    # OS => [KERNEL_PROCEDURE_HASH, foreign_account_id]
 
-    dropw drop # unimplemented!
+    # drop the procedure's hash
+    dropw
+    # OS => [foreign_account_id]
+
+    # get the memory address and a flag whether this account was already loaded.
+    exec.memory::get_foreign_account_ptr
+    # OS => [was_loaded, ptr, foreign_account_id]
+
+    if.true
+        exec.memory::set_current_account_data_ptr drop
+        # OS => []
+    else
+        exec.memory::set_current_account_data_ptr
+        # OS => [foreign_account_id]
+
+        # construct the word with account ID to load the core account data from the advice map
+        push.0.0.0
+        # OS => [0, 0, 0, foreign_account_id]
+
+        # move the core account data to the advice stack
+        adv.push_mapval
+        # OS => [0, 0, 0, foreign_account_id]
+        # AS => [[foreign_account_id, 0, 0, account_nonce], VAULT_ROOT, STORAGE_ROOT, CODE_ROOT]
+
+        # store the id and nonce of the foreign account to the memory
+        dropw adv_loadw 
+        exec.memory::set_acct_id_and_nonce dropw
+        # OS => []
+        # AS => [VAULT_ROOT, STORAGE_ROOT, CODE_ROOT]
+
+        # store the vault root of the foreign account to the memory
+        adv_loadw exec.memory::set_acct_vault_root dropw
+        # OS => []
+        # AS => [STORAGE_ROOT, CODE_ROOT]
+
+        # move the storage root and the code root to the operand stack 
+        adv_loadw padw adv_loadw
+        # OS => [CODE_ROOT, STORAGE_ROOT]
+        # AS => []
+
+        # store the code root into the memory
+        exec.memory::set_acct_code_commitment
+        # OS => [CODE_ROOT, STORAGE_ROOT]
+        # AS => []
+
+        # save the account procedure data into the memory
+        exec.memory::save_account_procedure_data
+        # OS => [STORAGE_ROOT]
+        # AS => []
+
+        # store the storage root to the memory
+        exec.memory::set_acct_storage_commitment
+        # OS => [STORAGE_ROOT]
+        # AS => []
+
+        # save the storage slots data into the memory
+        exec.memory::save_account_storage_data
+        # OS => []
+        # AS => []
+    end
 end
 
 #! Tells the transaction kernel that we are done executing a procedure on a foreign account.