Show reverse-transformed events in the debugging trace

CHANGELOG.md

@@ -24,7 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `#[should_panic(expected: (...))]` now supports regular strings inside mixed tuples, alongside short strings and numbers.
 - `#[derive(Fuzzable)]` macro that automatically generates `Fuzzable` trait implementations for structs and enums
 - `SNFOUNDRY_CACHE` environment variable to allow to specify a custom cache directory
-- Contract debug traces now include emitted Starknet events via the `events` trace component and `detailed` trace verbosity.
+- Contract debug traces now include emitted Starknet events via the `events` trace component and `detailed` trace verbosity, rendering ABI-decodable events in a struct-like format.
 
 #### Changed
 

crates/debugging/src/trace/collect.rs

@@ -7,7 +7,10 @@ use crate::{Context, Trace};
 use blockifier::execution::call_info::OrderedEvent;
 use cheatnet::runtime_extensions::outer_call_runtime_extension::rpc::{CallFailure, CallSuccess};
 use cheatnet::trace_data::{CallTrace, CallTraceNode};
-use data_transformer::{ReverseTransformError, reverse_transform_input, reverse_transform_output};
+use data_transformer::{
+    ReverseTransformError, ReverseTransformEventError, reverse_transform_event,
+    reverse_transform_input, reverse_transform_output,
+};
 use starknet_api::core::ClassHash;
 use starknet_api::execution_utils::format_panic_data;
 use starknet_rust::core::types::contract::AbiEntry;
@@ -52,7 +55,7 @@ impl<'a> Collector<'a> {
             call_type: components.call_type(entry_point.call_type),
             nested_calls,
             call_result: components.call_result_lazy(|| self.collect_transformed_call_result(abi)),
-            events: components.events_lazy(|| self.collect_events()),
+            events: components.events_lazy(|| self.collect_events(abi)),
             gas: components.gas_lazy(|| self.collect_gas()),
         };
 
@@ -150,23 +153,16 @@ impl<'a> Collector<'a> {
             .l2_gas)
     }
 
-    fn collect_events(&self) -> Events {
+    fn collect_events(&self, abi: &[AbiEntry]) -> Events {
         Events(
             self.call_trace
                 .events
                 .iter()
-                .map(Self::collect_event)
+                .map(|event| collect_event(event, abi))
                 .collect(),
         )
     }
 
-    fn collect_event(event: &OrderedEvent) -> Event {
-        Event {
-            keys: event.event.keys.iter().map(|key| key.0).collect(),
-            data: event.event.data.0.clone(),
-        }
-    }
-
     fn class_hash(&self) -> &ClassHash {
         self.call_trace
             .entry_point
@@ -196,6 +192,20 @@ fn format_raw_felts(felts: &[Felt]) -> String {
         .join(", ")
 }
 
+fn collect_event(event: &OrderedEvent, abi: &[AbiEntry]) -> Event {
+    let keys: Vec<_> = event.event.keys.iter().map(|key| key.0).collect();
+    let data = event.event.data.0.clone();
+
+    match reverse_transform_event(&keys, &data, abi) {
+        Ok(decoded) => Event::Decoded(decoded),
+        Err(
+            ReverseTransformEventError::EventNotFound(_)
+            | ReverseTransformEventError::UnsupportedUntypedEvent(_),
+        ) => Event::Raw { keys, data },
+        Err(error) => panic!("Failed to decode event: {error}"),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -210,7 +220,11 @@ mod tests {
     use cheatnet::trace_data::CallTrace;
     use starknet_api::core::{ClassHash, EntryPointSelector};
     use starknet_api::transaction::fields::Calldata;
-    use starknet_rust::core::types::contract::AbiEntry;
+    use starknet_api::transaction::{EventContent, EventData, EventKey};
+    use starknet_rust::core::types::contract::{
+        AbiEntry, AbiEvent, AbiEventEnum, EventField, EventFieldKind, TypedAbiEvent,
+    };
+    use starknet_rust::core::utils::get_selector_from_name;
     use starknet_types_core::felt::Felt;
     use std::collections::{HashMap, HashSet};
     use std::sync::Arc;
@@ -242,6 +256,34 @@ mod tests {
         Context::for_testing(store, Components::new(HashSet::new()))
     }
 
+    fn make_ordered_event(keys: Vec<Felt>, data: Vec<Felt>) -> OrderedEvent {
+        OrderedEvent {
+            order: 0,
+            event: EventContent {
+                keys: keys.into_iter().map(EventKey).collect(),
+                data: EventData(data),
+            },
+        }
+    }
+
+    fn typed_enum_event(name: &str, variants: &[(&str, &str, EventFieldKind)]) -> AbiEntry {
+        AbiEntry::Event(AbiEvent::Typed(TypedAbiEvent::Enum(AbiEventEnum {
+            name: name.to_string(),
+            variants: variants
+                .iter()
+                .map(|(name, ty, kind)| EventField {
+                    name: (*name).to_string(),
+                    r#type: (*ty).to_string(),
+                    kind: kind.clone(),
+                })
+                .collect(),
+        })))
+    }
+
+    fn selector(name: &str) -> Felt {
+        get_selector_from_name(name).unwrap()
+    }
+
     #[test]
     fn collect_selector_falls_back_to_hex_when_not_in_map() {
         let class_hash = ClassHash::default();
@@ -325,4 +367,31 @@ mod tests {
         let result = collector.collect_transformed_call_result(&[]);
         assert_eq!(result.0, "success: 0x1, 0x2a, 0xff");
     }
+
+    #[test]
+    fn collect_event_falls_back_to_raw_when_event_not_in_abi() {
+        let event = make_ordered_event(vec![Felt::from(0x123)], vec![Felt::from(0x456)]);
+
+        let result = collect_event(&event, &[]);
+
+        match result {
+            Event::Raw { keys, data } => {
+                assert_eq!(keys, vec![Felt::from(0x123)]);
+                assert_eq!(data, vec![Felt::from(0x456)]);
+            }
+            Event::Decoded(decoded) => panic!("expected raw event fallback, got {decoded}"),
+        }
+    }
+
+    #[test]
+    #[should_panic(expected = "Failed to decode event: abi is invalid")]
+    fn collect_event_panics_on_invalid_event_abi() {
+        let abi = vec![typed_enum_event(
+            "test::Event",
+            &[("Missing", "test::MissingEvent", EventFieldKind::Nested)],
+        )];
+        let event = make_ordered_event(vec![selector("Missing")], vec![]);
+
+        collect_event(&event, &abi);
+    }
 }

crates/debugging/src/trace/types.rs

@@ -67,9 +67,11 @@ pub struct Gas(pub ApiGasAmount);
 pub struct Events(pub Vec<Event>);
 
 #[derive(Debug, Clone)]
-pub struct Event {
-    pub keys: Vec<Felt>,
-    pub data: Vec<Felt>,
+pub enum Event {
+    /// A successfully reverse-transformed event, pretty-formatted as a human-readable struct.
+    Decoded(String),
+    /// A fallback for legacy Cairo1 events, events without matching ABI entries, or non-standard raw events.
+    Raw { keys: Vec<Felt>, data: Vec<Felt> },
 }
 
 impl Trace {

crates/debugging/src/tree/ui/display.rs

@@ -119,18 +119,19 @@ fn string_debug(data: impl Debug) -> String {
 
 impl Event {
     fn string_pretty(&self) -> String {
-        format!(
-            "Event {{ keys: [{}], data: [{}] }}",
-            self.keys
-                .iter()
-                .map(Felt::to_hex_string)
-                .collect::<Vec<_>>()
-                .join(", "),
-            self.data
-                .iter()
-                .map(Felt::to_hex_string)
-                .collect::<Vec<_>>()
-                .join(", "),
-        )
+        match self {
+            Event::Decoded(value) => value.clone(),
+            Event::Raw { keys, data } => format!(
+                "Event {{ keys: [{}], data: [{}] }}",
+                keys.iter()
+                    .map(Felt::to_hex_string)
+                    .collect::<Vec<_>>()
+                    .join(", "),
+                data.iter()
+                    .map(Felt::to_hex_string)
+                    .collect::<Vec<_>>()
+                    .join(", "),
+            ),
+        }
     }
 }

crates/forge/tests/data/debugging_events/src/lib.cairo

@@ -3,10 +3,13 @@ trait IEventsChecker<TContractState> {
     fn emit_event(ref self: TContractState, value: felt252);
     fn emit_two_events(ref self: TContractState, first_value: felt252, second_value: felt252);
     fn do_not_emit(self: @TContractState);
+    fn emit_custom_event(ref self: TContractState, key: felt252, value: felt252);
 }
 
 #[starknet::contract]
 mod EventsChecker {
+    use starknet::SyscallResultTrait;
+
     #[storage]
     struct Storage {}
 
@@ -33,5 +36,9 @@ mod EventsChecker {
         }
 
         fn do_not_emit(self: @ContractState) {}
+
+        fn emit_custom_event(ref self: ContractState, key: felt252, value: felt252) {
+            starknet::emit_event_syscall(array![key].span(), array![value].span()).unwrap_syscall();
+        }
     }
 }

crates/forge/tests/data/debugging_events/tests/test_trace.cairo

@@ -25,3 +25,11 @@ fn test_debugging_trace_eventless_success() {
 
     IEventsCheckerDispatcher { contract_address }.do_not_emit();
 }
+
+#[test]
+fn test_debugging_trace_raw_event_fallback() {
+    let contract_class = declare("EventsChecker").unwrap().contract_class();
+    let (contract_address, _) = contract_class.deploy(@array![]).unwrap();
+
+    IEventsCheckerDispatcher { contract_address }.emit_custom_event(0x123, 0x456);
+}

crates/forge/tests/e2e/debugging.rs

@@ -256,7 +256,7 @@ fn detailed_debugging_trace_message(test_name: &str, package_name: &str) -> Stri
         │  ├─ [caller address] [..]
         │  ├─ [call type] Call
         │  ├─ [call result] success: array![RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}, RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}] }}, RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}]
-        │  ├─ [events] [Event {{ keys: [[..]], data: [0x2] }}]
+        │  ├─ [events] [CallsExecuted {{ calls_len: 0x2 }}]
         │  ├─ [L2 gas] [..]
         │  ├─ [selector] execute_calls
         │  │  ├─ [contract name] SimpleContract
@@ -266,7 +266,7 @@ fn detailed_debugging_trace_message(test_name: &str, package_name: &str) -> Stri
         │  │  ├─ [caller address] [..]
         │  │  ├─ [call type] Call
         │  │  ├─ [call result] success: array![RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}, RecursiveCall {{ contract_address: ContractAddress([..]), payload: array![] }}]
-        │  │  ├─ [events] [Event {{ keys: [[..]], data: [0x2] }}]
+        │  │  ├─ [events] [CallsExecuted {{ calls_len: 0x2 }}]
         │  │  ├─ [L2 gas] [..]
         │  │  ├─ [selector] execute_calls
         │  │  │  ├─ [contract name] SimpleContract
@@ -276,7 +276,7 @@ fn detailed_debugging_trace_message(test_name: &str, package_name: &str) -> Stri
         │  │  │  ├─ [caller address] [..]
         │  │  │  ├─ [call type] Call
         │  │  │  ├─ [call result] success: array![]
-        │  │  │  ├─ [events] [Event {{ keys: [[..]], data: [0x0] }}]
+        │  │  │  ├─ [events] [CallsExecuted {{ calls_len: 0x0 }}]
         │  │  │  └─ [L2 gas] [..]
         │  │  └─ [selector] execute_calls
         │  │     ├─ [contract name] SimpleContract
@@ -286,7 +286,7 @@ fn detailed_debugging_trace_message(test_name: &str, package_name: &str) -> Stri
         │  │     ├─ [caller address] [..]
         │  │     ├─ [call type] Call
         │  │     ├─ [call result] success: array![]
-        │  │     ├─ [events] [Event {{ keys: [[..]], data: [0x0] }}]
+        │  │     ├─ [events] [CallsExecuted {{ calls_len: 0x0 }}]
         │  │     └─ [L2 gas] [..]
         │  └─ [selector] execute_calls
         │     ├─ [contract name] SimpleContract
@@ -296,7 +296,7 @@ fn detailed_debugging_trace_message(test_name: &str, package_name: &str) -> Stri
         │     ├─ [caller address] [..]
         │     ├─ [call type] Call
         │     ├─ [call result] success: array![]
-        │     ├─ [events] [Event {{ keys: [[..]], data: [0x0] }}]
+        │     ├─ [events] [CallsExecuted {{ calls_len: 0x0 }}]
         │     └─ [L2 gas] [..]
         └─ [selector] fail
            ├─ [contract name] SimpleContract

crates/forge/tests/e2e/snapshots/debugging/main__e2e__debugging__debugging_trace_events_component_only@2.18.0.snap

@@ -8,4 +8,4 @@ expression: stdout
 [PASS] debugging_events_integrationtest::test_trace::test_debugging_trace_events_component (l1_gas: ~0, l1_data_gas: ~96, l2_gas: ~304300)
 [test name] debugging_events_integrationtest::test_trace::test_debugging_trace_events_component
 └─ [selector] emit_event
-   └─ [events] [Event { keys: [0x2b0cdef3c28f9d954382f060df168ae56204d5937d2f0cd1fd9ce759afaf095], data: [0x2a] }]
+   └─ [events] [ValueEmitted { value: 0x2a }]

crates/forge/tests/e2e/snapshots/debugging/main__e2e__debugging__debugging_trace_multiple_events_component@2.18.0.snap

@@ -8,4 +8,4 @@ expression: stdout
 [PASS] debugging_events_integrationtest::test_trace::test_debugging_trace_multiple_events (l1_gas: ~0, l1_data_gas: ~96, l2_gas: ~332360)
 [test name] debugging_events_integrationtest::test_trace::test_debugging_trace_multiple_events
 └─ [selector] emit_two_events
-   └─ [events] [Event { keys: [0x2b0cdef3c28f9d954382f060df168ae56204d5937d2f0cd1fd9ce759afaf095], data: [0x2a] }, Event { keys: [0x2b0cdef3c28f9d954382f060df168ae56204d5937d2f0cd1fd9ce759afaf095], data: [0x2b] }]
+   └─ [events] [ValueEmitted { value: 0x2a }, ValueEmitted { value: 0x2b }]