miden_testing/mock_transaction/

transaction.rs

use alloc::collections::{BTreeMap, BTreeSet};
use alloc::sync::Arc;
use alloc::vec::Vec;

#[cfg(test)]
use miden_processor::{ExecutionOutput, Felt};
use miden_processor::{FutureMaybeSend, LoadedMastForest, MastForestStore, Word};
use miden_protocol::account::{
    Account,
    AccountId,
    PartialAccount,
    StorageMapKey,
    StorageMapWitness,
    StorageSlotContent,
};
use miden_protocol::assembly::SourceManagerSync;
use miden_protocol::asset::{AssetId, AssetWitness};
use miden_protocol::block::account_tree::AccountWitness;
use miden_protocol::block::{BlockHeader, BlockNumber};
use miden_protocol::note::{Note, NoteScript, NoteScriptRoot};
use miden_protocol::protocol_config::ProtocolConfig;
use miden_protocol::transaction::{
    AccountInputs,
    ExecutedTransaction,
    InputNote,
    InputNotes,
    PartialBlockchain,
    TransactionArgs,
    TransactionInputs,
};
use miden_tx::auth::BasicAuthenticator;
use miden_tx::{
    DataStore,
    DataStoreError,
    TransactionExecutor,
    TransactionExecutorError,
    TransactionMastStore,
};

#[cfg(test)]
use crate::mock_transaction::ExecError;

// MOCK TRANSACTION
// ================================================================================================

/// Represents all needed data for executing a transaction, or arbitrary code.
///
/// It implements [`DataStore`], so transactions may be executed with
/// [TransactionExecutor](miden_tx::TransactionExecutor)
pub struct MockTransaction {
    pub(super) account: Account,
    pub(super) expected_output_notes: Vec<Note>,
    pub(super) foreign_account_inputs: BTreeMap<AccountId, (Account, AccountWitness)>,
    pub(super) tx_inputs: TransactionInputs,
    pub(super) mast_store: TransactionMastStore,
    pub(super) authenticator: Option<BasicAuthenticator>,
    pub(super) source_manager: Arc<dyn SourceManagerSync>,
    pub(super) note_scripts: BTreeMap<NoteScriptRoot, NoteScript>,
}

impl MockTransaction {
    /// Executes the transaction through a [TransactionExecutor]
    pub async fn execute(self) -> Result<ExecutedTransaction, TransactionExecutorError> {
        let account_id = self.account().id();
        let block_num = self.tx_inputs().block_header().block_num();
        let notes = self.tx_inputs().input_notes().clone();
        let tx_args = self.tx_args().clone();

        let mut tx_executor =
            TransactionExecutor::new(&self).with_source_manager(self.source_manager.clone());

        if let Some(authenticator) = self.authenticator() {
            tx_executor = tx_executor.with_authenticator(authenticator);
        }

        tx_executor.execute_transaction(account_id, block_num, notes, tx_args).await
    }

    pub fn account(&self) -> &Account {
        &self.account
    }

    pub fn expected_output_notes(&self) -> &[Note] {
        &self.expected_output_notes
    }

    pub fn tx_args(&self) -> &TransactionArgs {
        self.tx_inputs.tx_args()
    }

    pub fn input_notes(&self) -> &InputNotes<InputNote> {
        self.tx_inputs.input_notes()
    }

    pub fn set_tx_args(&mut self, tx_args: TransactionArgs) {
        self.tx_inputs.set_tx_args(tx_args);
    }

    pub fn tx_inputs(&self) -> &TransactionInputs {
        &self.tx_inputs
    }

    pub fn authenticator(&self) -> Option<&BasicAuthenticator> {
        self.authenticator.as_ref()
    }

    /// Returns the source manager used in the assembler of the mock transaction.
    pub fn source_manager(&self) -> Arc<dyn SourceManagerSync> {
        Arc::clone(&self.source_manager)
    }
}

// CODE EXECUTION
// ================================================================================================

#[cfg(test)]
impl MockTransaction {
    /// Executes arbitrary code within the context of a mocked transaction environment and returns
    /// the resulting [`ExecutionOutput`].
    ///
    /// The code is compiled with the assembler built by
    /// [`CodeBuilder::with_mock_packages_with_source_manager`] and executed with advice inputs
    /// constructed from the data stored in the context. The program
    /// is run on a modified [`TransactionExecutorHost`] which is loaded with the procedures exposed
    /// by the transaction kernel, and also individual kernel functions (not normally exposed).
    ///
    /// This executes in the memory context of the transaction kernel and requires invoking internal
    /// kernel APIs to be used correctly, so it is restricted to this crate's tests. Use
    /// [`MockTransaction::execute`] to execute a transaction.
    ///
    /// # Errors
    ///
    /// Returns an error if the assembly or execution of the provided code fails.
    ///
    /// # Panics
    ///
    /// - If the provided `code` is not a valid program.
    pub(crate) async fn execute_code(&self, code: &str) -> Result<ExecutionOutput, ExecError> {
        self.execute_code_inner(code, true, None).await
    }

    /// Same as [`MockTransaction::execute_code`], except that the host does _not_ handle lazy
    /// loading events, which lets a kernel procedure be tested in isolation from them.
    pub(crate) async fn execute_code_without_lazy_loading(
        &self,
        code: &str,
    ) -> Result<ExecutionOutput, ExecError> {
        self.execute_code_inner(code, false, None).await
    }

    /// Same as [`MockTransaction::execute_code`], but overrides the host response to an input-note
    /// index request with `[note_idx, is_found]`.
    pub(crate) async fn execute_code_with_input_note_index_response(
        &self,
        code: &str,
        response: [Felt; 2],
    ) -> Result<ExecutionOutput, ExecError> {
        self.execute_code_inner(code, true, Some(response)).await
    }

    async fn execute_code_inner(
        &self,
        code: &str,
        is_lazy_loading_enabled: bool,
        input_note_index_response: Option<[Felt; 2]>,
    ) -> Result<ExecutionOutput, ExecError> {
        use alloc::borrow::ToOwned;

        use miden_protocol::assembly::debuginfo::{SourceLanguage, Uri};
        use miden_protocol::assembly::{Assembler, SourceManager};
        use miden_protocol::asset::Asset;
        use miden_protocol::transaction::TransactionKernel;
        use miden_standards::code_builder::CodeBuilder;
        use miden_tx::auth::UnreachableAuth;
        use miden_tx::{AccountProcedureIndexMap, ScriptMastForestStore, TransactionExecutorHost};

        use crate::executor::CodeExecutor;
        use crate::mock_host::MockHost;

        // Fetch all witnesses for note assets.
        let asset_ids = self
            .tx_inputs
            .input_notes()
            .iter()
            .flat_map(|note| note.note().assets().iter().map(Asset::id))
            .collect::<BTreeSet<_>>();

        let (account, _block_header, _protocol_config, _blockchain) = self
            .get_transaction_inputs(
                self.tx_inputs.account().id(),
                BTreeSet::from_iter([self.tx_inputs.block_header().block_num()]),
            )
            .await
            .expect("failed to fetch transaction inputs");

        // Fetch the witnesses for all asset IDs.
        let asset_witnesses = self
            .get_vault_asset_witnesses(account.id(), account.vault().root(), asset_ids)
            .await
            .expect("failed to fetch asset witnesses");

        let tx_inputs = self.tx_inputs.clone().with_asset_witnesses(asset_witnesses);
        let (stack_inputs, advice_inputs) = TransactionKernel::prepare_inputs(&tx_inputs);

        // Virtual file name should be unique.
        let virtual_source_file = self.source_manager.load(
            SourceLanguage::Masm,
            Uri::new("_mock_tx_code"),
            code.to_owned(),
        );

        let assembler: Assembler =
            CodeBuilder::with_mock_packages_with_source_manager(self.source_manager.clone()).into();

        let program = assembler
            .assemble_program("mock-tx-code", virtual_source_file)
            .expect("code was not well formed");

        // Load transaction kernel and the program into the mast forest in self.
        // Note that native and foreign account's code are already loaded by the
        // MockTransactionBuilder.
        self.mast_store.insert_package(&TransactionKernel::core_package());
        self.mast_store.insert_package(&program);

        let account_procedure_idx_map = AccountProcedureIndexMap::new(
            [tx_inputs.account().code()]
                .into_iter()
                .chain(self.foreign_account_inputs.values().map(|(account, _)| account.code())),
        );

        // The host validates the tx summary's block commitment against these values, so they
        // must come from the tx inputs.
        let ref_block = tx_inputs.block_header().block_num();
        let block_commitments = tx_inputs.collect_block_commitments();

        let exec_host = TransactionExecutorHost::<'_, '_, _, UnreachableAuth>::new(
            &PartialAccount::from(self.account()),
            tx_inputs.input_notes().clone(),
            self,
            ScriptMastForestStore::default(),
            account_procedure_idx_map,
            None,
            ref_block,
            block_commitments,
            self.source_manager(),
        );

        let advice_inputs = advice_inputs.into_advice_inputs();

        let mut mock_host = MockHost::new(exec_host);
        if is_lazy_loading_enabled {
            mock_host.enable_lazy_loading()
        }
        if let Some(response) = input_note_index_response {
            mock_host.set_input_note_index_response(response);
        }

        CodeExecutor::new(mock_host)
            .stack_inputs(stack_inputs)
            .extend_advice_inputs(advice_inputs)
            .execute_package(program)
            .await
    }
}

impl DataStore for MockTransaction {
    fn get_transaction_inputs(
        &self,
        account_id: AccountId,
        ref_blocks: BTreeSet<BlockNumber>,
    ) -> impl FutureMaybeSend<
        Result<(PartialAccount, BlockHeader, ProtocolConfig, PartialBlockchain), DataStoreError>,
    > {
        // Sanity checks
        assert_eq!(account_id, self.account().id());
        assert_eq!(account_id, self.tx_inputs.account().id());
        assert_eq!(
            ref_blocks
                .last()
                .copied()
                .expect("at least the tx ref block should be provided"),
            self.tx_inputs().blockchain().chain_length(),
            "tx reference block should match partial blockchain length"
        );

        let account = self.tx_inputs.account().clone();
        let block_header = self.tx_inputs.block_header().clone();
        let protocol_config = self.tx_inputs.protocol_config().clone();
        let blockchain = self.tx_inputs.blockchain().clone();

        async move { Ok((account, block_header, protocol_config, blockchain)) }
    }

    fn get_foreign_account_inputs(
        &self,
        foreign_account_id: AccountId,
        _ref_block: BlockNumber,
    ) -> impl FutureMaybeSend<Result<AccountInputs, DataStoreError>> {
        // Note that we cannot validate that the foreign account inputs are valid for the
        // transaction's reference block.
        async move {
            let (foreign_account, account_witness) =
                self.foreign_account_inputs.get(&foreign_account_id).ok_or_else(|| {
                    DataStoreError::other(format!(
                        "failed to find foreign account {foreign_account_id}"
                    ))
                })?;

            Ok(AccountInputs::new(
                PartialAccount::from(foreign_account),
                account_witness.clone(),
            ))
        }
    }

    fn get_vault_asset_witnesses(
        &self,
        account_id: AccountId,
        vault_root: Word,
        asset_ids: BTreeSet<AssetId>,
    ) -> impl FutureMaybeSend<Result<Vec<AssetWitness>, DataStoreError>> {
        async move {
            let asset_vault = if account_id == self.account().id() {
                if self.account().vault().root() != vault_root {
                    return Err(DataStoreError::other(format!(
                        "native account {account_id} has vault root {} but {vault_root} was requested",
                        self.account().vault().root()
                    )));
                }
                self.account().vault()
            } else {
                let (foreign_account, _witness) = self
                    .foreign_account_inputs
                    .iter()
                    .find_map(
                        |(id, account_inputs)| {
                            if account_id == *id { Some(account_inputs) } else { None }
                        },
                    )
                    .ok_or_else(|| {
                        DataStoreError::other(format!(
                            "failed to find foreign account {account_id} in foreign account inputs"
                        ))
                    })?;

                if foreign_account.vault().root() != vault_root {
                    return Err(DataStoreError::other(format!(
                        "foreign account {account_id} has vault root {} but {vault_root} was requested",
                        foreign_account.vault().root()
                    )));
                }
                foreign_account.vault()
            };

            Ok(asset_ids.into_iter().map(|asset_id| asset_vault.open(asset_id)).collect())
        }
    }

    fn get_storage_map_witness(
        &self,
        account_id: AccountId,
        map_root: Word,
        map_key: StorageMapKey,
    ) -> impl FutureMaybeSend<Result<StorageMapWitness, DataStoreError>> {
        async move {
            if account_id == self.account().id() {
                // Iterate the account storage to find the map with the requested root.
                let storage_map = self
                    .account()
                    .storage()
                    .slots()
                    .iter()
                    .find_map(|slot| match slot.content() {
                        StorageSlotContent::Map(storage_map) if storage_map.root() == map_root => {
                            Some(storage_map)
                        },
                        _ => None,
                    })
                    .ok_or_else(|| {
                        DataStoreError::other(format!(
                            "failed to find storage map with root {map_root} in account storage"
                        ))
                    })?;

                Ok(storage_map.open(&map_key))
            } else {
                let (foreign_account, _witness) = self
                    .foreign_account_inputs
                    .iter()
                    .find_map(
                        |(id, account_inputs)| {
                            if account_id == *id { Some(account_inputs) } else { None }
                        },
                    )
                    .ok_or_else(|| {
                        DataStoreError::other(format!(
                            "failed to find foreign account {account_id} in foreign account inputs"
                        ))
                    })?;

                let map = foreign_account
                    .storage()
                    .slots()
                    .iter()
                    .find_map(|slot| match slot.content() {
                        StorageSlotContent::Map(storage_map) if storage_map.root() == map_root => {Some(storage_map)},
                        _ => None,
                    })
                    .ok_or_else(|| {
                        DataStoreError::other(format!(
                            "failed to find storage map with root {map_root} in foreign account {account_id}"
                        ))
                    })?;

                Ok(map.open(&map_key))
            }
        }
    }

    fn get_note_script(
        &self,
        script_root: NoteScriptRoot,
    ) -> impl FutureMaybeSend<Result<Option<NoteScript>, DataStoreError>> {
        async move { Ok(self.note_scripts.get(&script_root).cloned()) }
    }
}

impl MastForestStore for MockTransaction {
    fn get(&self, procedure_hash: &Word) -> Option<LoadedMastForest> {
        self.mast_store.get(procedure_hash)
    }
}

// TESTS
// ================================================================================================

#[cfg(test)]
mod tests {
    use std::string::ToString;

    use miden_protocol::errors::tx_kernel::ERR_TX_COMPUTE_FEE_EXTRA_CYCLES_NOT_U32;
    use miden_standards::code_builder::CodeBuilder;

    use super::*;
    use crate::{Auth, MockChain, TestTransactionBuilder};

    #[tokio::test]
    async fn test_get_note_scripts() {
        // Create two note scripts
        let script1_code = "@note_script\npub proc main\n    push.1\nend";
        let note_script1 = CodeBuilder::default()
            .compile_note_script(script1_code)
            .expect("failed to assemble note script 1");
        let script_root1 = note_script1.root();

        let script2_code = "@note_script\npub proc main\n    push.2 push.3 add\nend";
        let note_script2 = CodeBuilder::default()
            .compile_note_script(script2_code)
            .expect("failed to assemble note script 2");
        let script_root2 = note_script2.root();

        // Build a mock transaction with both note scripts
        let mock_tx = TestTransactionBuilder::with_existing_mock_account()
            .add_note_script(note_script1.clone())
            .add_note_script(note_script2.clone())
            .build()
            .expect("failed to build mock transaction");

        // Assert that fetching both note scripts works
        let retrieved_script1 = mock_tx
            .get_note_script(script_root1)
            .await
            .expect("failed to get note script 1")
            .expect("note script 1 should exist");
        assert_eq!(retrieved_script1, note_script1);

        let retrieved_script2 = mock_tx
            .get_note_script(script_root2)
            .await
            .expect("failed to get note script 2")
            .expect("note script 2 should exist");
        assert_eq!(retrieved_script2, note_script2);

        // Fetching a non-existent one returns None
        let non_existent_root = NoteScriptRoot::from_array([1, 2, 3, 4]);
        let result = mock_tx.get_note_script(non_existent_root).await;
        assert!(matches!(result, Ok(None)));
    }

    /// Regression test: an error raised in a dynamically-linked library (here `compute_fee` from
    /// the protocol library) must render its human-readable message, not just an opaque error
    /// code. This relies on the assembled packages retaining their debug info.
    #[tokio::test]
    async fn execute_code_renders_masm_error_message() -> anyhow::Result<()> {
        let mut builder = MockChain::builder();
        let account = builder.add_existing_mock_account(Auth::IncrNonce)?;
        let mock_chain = builder.build()?;

        let mock_tx = mock_chain.build_transaction(account).build()?;

        // A value that exceeds u32::MAX triggers the `u32assert` inside `compute_fee`.
        let code = format!(
            r#"
        use miden::tx_kernel_core::prologue
        use miden::protocol::tx

        begin
            exec.prologue::prepare_transaction

            padw
            push.{num_extra_cycles}
            exec.tx::compute_fee
        end"#,
            num_extra_cycles = u64::from(u32::MAX) + 1
        );

        let Err(error) = mock_tx.execute_code(&code).await else {
            anyhow::bail!("execution should fail on non-u32 extra cycles");
        };

        let rendered = error.to_string();
        let expected_error = ERR_TX_COMPUTE_FEE_EXTRA_CYCLES_NOT_U32;
        assert!(
            rendered.contains(expected_error.message()),
            "rendered error should contain the masm error message",
        );

        Ok(())
    }
}