miden_tx/executor/
data_store.rs

1use alloc::collections::BTreeSet;
2use alloc::vec::Vec;
3
4use miden_processor::{FutureMaybeSend, MastForestStore, Word};
5use miden_protocol::account::{AccountId, PartialAccount, StorageMapKey, StorageMapWitness};
6use miden_protocol::asset::{AssetId, AssetWitness};
7use miden_protocol::block::{BlockHeader, BlockNumber};
8use miden_protocol::note::{NoteScript, NoteScriptRoot};
9use miden_protocol::protocol_config::ProtocolConfig;
10use miden_protocol::transaction::{AccountInputs, PartialBlockchain};
11
12use crate::DataStoreError;
13
14// DATA STORE TRAIT
15// ================================================================================================
16
17/// The [DataStore] trait defines the interface that transaction objects use to fetch data
18/// required for transaction execution.
19pub trait DataStore: MastForestStore {
20    /// Returns all the data required to execute a transaction against the account with the
21    /// specified ID and consuming input notes created in blocks in the input `ref_blocks` set.
22    ///
23    /// The returned partial blockchain must track every block in `ref_blocks`.
24    ///
25    /// The highest block number in `ref_blocks` will be the transaction reference block. In
26    /// general, it is recommended that the reference corresponds to the latest block available
27    /// in the data store.
28    ///
29    /// The returned [`ProtocolConfig`] must be the one the returned block header commits to, since
30    /// the header only carries its commitment.
31    ///
32    /// # Errors
33    /// Returns an error if:
34    /// - The account with the specified ID could not be found in the data store.
35    /// - The block with the specified number could not be found in the data store.
36    /// - The combination of specified inputs resulted in a transaction input error.
37    /// - The data store encountered some internal error
38    fn get_transaction_inputs(
39        &self,
40        account_id: AccountId,
41        ref_blocks: BTreeSet<BlockNumber>,
42    ) -> impl FutureMaybeSend<
43        Result<(PartialAccount, BlockHeader, ProtocolConfig, PartialBlockchain), DataStoreError>,
44    >;
45
46    /// Returns a partial foreign account state together with a witness, proving its validity in the
47    /// specified transaction reference block.
48    fn get_foreign_account_inputs(
49        &self,
50        foreign_account_id: AccountId,
51        ref_block: BlockNumber,
52    ) -> impl FutureMaybeSend<Result<AccountInputs, DataStoreError>>;
53
54    /// Returns witnesses for the asset IDs in the requested account's vault with the
55    /// requested vault root.
56    ///
57    /// These are the witnesses that need to be added to the advice provider's merkle store and
58    /// advice map to make access to the corresponding assets possible.
59    fn get_vault_asset_witnesses(
60        &self,
61        account_id: AccountId,
62        vault_root: Word,
63        asset_ids: BTreeSet<AssetId>,
64    ) -> impl FutureMaybeSend<Result<Vec<AssetWitness>, DataStoreError>>;
65
66    /// Returns a witness for a storage map item identified by `map_key` in the requested account's
67    /// storage with the requested storage `map_root`.
68    ///
69    /// Note that the `map_key` needs to be hashed in order to get the actual key into the storage
70    /// map.
71    ///
72    /// This is the witness that needs to be added to the advice provider's merkle store and advice
73    /// map to make access to the specified storage map item possible.
74    fn get_storage_map_witness(
75        &self,
76        account_id: AccountId,
77        map_root: Word,
78        map_key: StorageMapKey,
79    ) -> impl FutureMaybeSend<Result<StorageMapWitness, DataStoreError>>;
80
81    /// Returns a note script with the specified root, or `None` if not found.
82    ///
83    /// This method will try to find a note script with the specified root in the data store.
84    /// If the script is not found, it returns `Ok(None)` rather than an error, as "not found"
85    /// is a valid, expected outcome.
86    ///
87    /// **Note:** Data store implementers do not need to handle standard note scripts (e.g. P2ID).
88    /// These are resolved directly by the transaction executor and will not trigger this method.
89    ///
90    /// # Errors
91    /// Returns an error if the data store encountered an internal error while attempting to
92    /// retrieve the script.
93    fn get_note_script(
94        &self,
95        script_root: NoteScriptRoot,
96    ) -> impl FutureMaybeSend<Result<Option<NoteScript>, DataStoreError>>;
97}
miden_tx/executor/data_store.rs

miden_tx/executor/
data_store.rs
