Merge pull request #404 from 0xPolygonMiden/bobbin-tx-events

Transaction host refactoring

miden-lib/Cargo.toml

@@ -28,7 +28,6 @@ miden-objects = { package = "miden-objects", path = "../objects", default-featur
     "testing",
 ] }
 miden-stdlib = { workspace = true }
-miden-tx = { package = "miden-tx", path = "../miden-tx", default-features = false }
 mock = { package = "miden-mock", path = "../mock", default-features = false }
 vm-processor = { workspace = true, features = ["internals"] }
 

miden-lib/src/transaction/errors.rs

@@ -0,0 +1,26 @@
+use core::fmt;
+
+// TRANSACTION EVENT PARSING ERROR
+// ================================================================================================
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub enum TransactionEventParsingError {
+    InvalidTransactionEvent(u32),
+    NotTransactionEvent(u32),
+}
+
+impl fmt::Display for TransactionEventParsingError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::InvalidTransactionEvent(event_id) => {
+                write!(f, "event {event_id} is not a valid transaction kernel event")
+            },
+            Self::NotTransactionEvent(event_id) => {
+                write!(f, "event {event_id} is not a transaction kernel event")
+            },
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for TransactionEventParsingError {}

miden-lib/src/transaction/events.rs

@@ -0,0 +1,47 @@
+use core::fmt;
+
+use super::TransactionEventParsingError;
+
+// TRANSACTION EVENT
+// ================================================================================================
+
+/// Events which may be emitted by a transaction kernel.
+///
+/// The events are emitted via the `emit.<event_id>` instruction. The event ID is a 32-bit
+/// unsigned integer which is used to identify the event type. For events emitted by the
+/// transaction kernel, the event_id is structured as follows:
+/// - The upper 16 bits of the event ID are set to 2.
+/// - The lower 16 bits represent a unique event ID within the transaction kernel.
+#[repr(u32)]
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub enum TransactionEvent {
+    AddAssetToAccountVault = 0x2_0000,      // 131072
+    RemoveAssetFromAccountVault = 0x2_0001, // 131073
+}
+
+impl TransactionEvent {
+    /// Value of the top 16 bits of a transaction kernel event ID.
+    pub const EVENT_ID_PREFIX: u16 = 2;
+}
+
+impl fmt::Display for TransactionEvent {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{self:?}")
+    }
+}
+
+impl TryFrom<u32> for TransactionEvent {
+    type Error = TransactionEventParsingError;
+
+    fn try_from(value: u32) -> Result<Self, Self::Error> {
+        if value >> 16 != Self::EVENT_ID_PREFIX as u32 {
+            return Err(TransactionEventParsingError::NotTransactionEvent(value));
+        }
+
+        match value {
+            0x2_0000 => Ok(TransactionEvent::AddAssetToAccountVault),
+            0x2_0001 => Ok(TransactionEvent::RemoveAssetFromAccountVault),
+            _ => Err(TransactionEventParsingError::InvalidTransactionEvent(value)),
+        }
+    }
+}

miden-lib/src/transaction/mod.rs

@@ -15,6 +15,9 @@ use super::MidenLib;
 
 pub mod memory;
 
+mod events;
+pub use events::TransactionEvent;
+
 mod inputs;
 pub use inputs::ToTransactionKernelInputs;
 
@@ -24,6 +27,9 @@ pub use outputs::{
     OUTPUT_NOTES_COMMITMENT_WORD_IDX, TX_SCRIPT_ROOT_WORD_IDX,
 };
 
+mod errors;
+pub use errors::TransactionEventParsingError;
+
 // TRANSACTION KERNEL
 // ================================================================================================
 

miden-tx/src/compiler/mod.rs

@@ -65,7 +65,7 @@ impl TransactionCompiler {
         Ok(account_code)
     }
 
-    /// Loads the provided account interface (vector of procedure digests) into the this compiler.
+    /// Loads the provided account interface (vector of procedure digests) into this compiler.
     /// Returns the old account interface if it previously existed.
     pub fn load_account_interface(
         &mut self,

miden-tx/src/executor/mod.rs

@@ -14,7 +14,6 @@ use super::{
     RecAdviceProvider, ScriptTarget, TransactionCompiler, TransactionExecutorError,
     TransactionHost,
 };
-use crate::host::EventHandler;
 
 mod data;
 pub use data::DataStore;
@@ -157,14 +156,12 @@ impl<D: DataStore> TransactionExecutor<D> {
 
         let (tx_program, tx_script, tx_inputs) = transaction.into_parts();
 
-        let (advice_recorder, event_handler) = host.into_parts();
         build_executed_transaction(
             tx_program,
             tx_script,
             tx_inputs,
-            advice_recorder,
             result.stack_outputs().clone(),
-            event_handler,
+            host,
         )
     }
 
@@ -212,12 +209,13 @@ fn build_executed_transaction(
     program: Program,
     tx_script: Option<TransactionScript>,
     tx_inputs: TransactionInputs,
-    advice_provider: RecAdviceProvider,
     stack_outputs: StackOutputs,
-    event_handler: EventHandler,
+    host: TransactionHost<RecAdviceProvider>,
 ) -> Result<ExecutedTransaction, TransactionExecutorError> {
+    let (advice_recorder, vault_delta) = host.into_parts();
+
     // finalize the advice recorder
-    let (advice_witness, _, map, store) = advice_provider.finalize();
+    let (advice_witness, _, map, store) = advice_recorder.finalize();
 
     // parse transaction results
     let tx_outputs = TransactionKernel::parse_transaction_outputs(&stack_outputs, &map.into())
@@ -247,9 +245,6 @@ fn build_executed_transaction(
         None
     };
 
-    // finalize the event handler
-    let vault_delta = event_handler.finalize();
-
     // construct the account delta
     let account_delta =
         AccountDelta::new(storage_delta, vault_delta, nonce_delta).expect("invalid account delta");

miden-tx/src/host/event/vault_delta.rs → miden-tx/src/host/account_delta.rs

@@ -4,41 +4,37 @@ use miden_objects::{
     utils::collections::{btree_map::Entry, BTreeMap},
     Digest,
 };
-use vm_processor::{ContextId, ExecutionError, HostResponse, ProcessState};
+use vm_processor::{ExecutionError, HostResponse, ProcessState};
 
-/// The [AccountVaultDeltaHandler] is responsible for tracking changes to the vault of the account
+// ACCOUNT VAULT DELTA TRACKER
+// ================================================================================================
+
+/// The account vault delta tracker is responsible for tracking changes to the vault of the account
 /// the transaction is being executed against.
 ///
 /// It is composed of two maps:
-/// - [AccountVaultDeltaHandler::fungible_assets] - tracks changes to the vault's fungible assets,
-/// where the key is the faucet ID of the asset, and the value is the amount of the asset being
-/// added or removed from the vault.
-/// - [AccountVaultDeltaHandler::non_fungible_assets] - tracks changes to the vault's non-fungible
-/// assets, where the key is the non-fungible asset, and the value is either 1 or -1 depending
-/// on whether the asset is being added or removed from the vault.
+/// - Fungible asset map: tracks changes to the vault's fungible assets, where the key is the
+///   faucet ID of the asset, and the value is the amount of the asset being added or removed from
+///   the vault (positive value for added assets, negative value for removed assets).
+/// - Non-fungible asset map: tracks changes to the vault's non-fungible assets, where the key is
+///   the non-fungible asset, and the value is either 1 or -1 depending on whether the asset is
+///   being added or removed from the vault.
 #[derive(Default, Debug)]
-pub struct AccountVaultDeltaHandler {
-    fungible_assets: BTreeMap<u64, i128>,
+pub struct AccountVaultDeltaTracker {
+    fungible_assets: BTreeMap<AccountId, i128>,
     non_fungible_assets: BTreeMap<Digest, i8>,
 }
 
-impl AccountVaultDeltaHandler {
+impl AccountVaultDeltaTracker {
     // MODIFIERS
     // --------------------------------------------------------------------------------------------
 
     /// Extracts the asset that is being added to the account's vault from the process state and
-    /// updates the appropriate [AccountVaultDeltaHandler::fungible_assets] or
-    /// [AccountVaultDeltaHandler::non_fungible_assets] map.
+    /// updates the appropriate fungible or non-fungible asset map.
     pub fn add_asset<S: ProcessState>(
         &mut self,
         process: &S,
     ) -> Result<HostResponse, ExecutionError> {
-        if process.ctx() != ContextId::root() {
-            return Err(ExecutionError::EventError(
-                "AddAssetToAccountVault event can only be emitted from the root context".into(),
-            ));
-        }
-
         let asset: Asset = process.get_stack_word(0).try_into().map_err(|err| {
             ExecutionError::EventError(format!(
                 "Failed to apply account vault delta - asset is malformed - {err}"
@@ -49,7 +45,7 @@ impl AccountVaultDeltaHandler {
             Asset::Fungible(asset) => {
                 update_asset_delta(
                     &mut self.fungible_assets,
-                    asset.faucet_id().into(),
+                    asset.faucet_id(),
                     asset.amount() as i128,
                 );
             },
@@ -68,13 +64,6 @@ impl AccountVaultDeltaHandler {
         &mut self,
         process: &S,
     ) -> Result<HostResponse, ExecutionError> {
-        if process.ctx() != ContextId::root() {
-            return Err(ExecutionError::EventError(
-                "RemoveAssetFromAccountVault event can only be emitted from the root context"
-                    .into(),
-            ));
-        }
-
         let asset: Asset = process.get_stack_word(0).try_into().map_err(|err| {
             ExecutionError::EventError(format!(
                 "Failed to apply account vault delta - asset is malformed - {err}"
@@ -85,7 +74,7 @@ impl AccountVaultDeltaHandler {
             Asset::Fungible(asset) => {
                 update_asset_delta(
                     &mut self.fungible_assets,
-                    asset.faucet_id().into(),
+                    asset.faucet_id(),
                     -(asset.amount() as i128),
                 );
             },
@@ -97,12 +86,12 @@ impl AccountVaultDeltaHandler {
         Ok(HostResponse::None)
     }
 
-    // CONSUMERS
+    // CONVERSIONS
     // --------------------------------------------------------------------------------------------
 
-    /// Consumes the [AccountVaultDeltaHandler] and returns the [AccountVaultDelta] that represents the
-    /// changes to the account's vault.
-    pub fn finalize(self) -> AccountVaultDelta {
+    /// Consumes this delta tracker and returns the [AccountVaultDelta] that represents the changes
+    /// to the account's vault.
+    pub fn into_vault_delta(self) -> AccountVaultDelta {
         let mut added_assets = Vec::new();
         let mut removed_assets = Vec::new();
 
@@ -148,8 +137,9 @@ impl AccountVaultDeltaHandler {
     }
 }
 
-// HELPERS
+// HELPER FUNCTIONS
 // ================================================================================================
+
 /// Updates the provided map with the provided key and amount. If the final amount is 0, the entry
 /// is removed from the map.
 fn update_asset_delta<K, V>(delta_map: &mut BTreeMap<K, V>, key: K, amount: V)