moonbeam_evm_tracer/
lib.rs

1// Copyright 2019-2025 PureStake Inc.
2// This file is part of Moonbeam.
3
4// Moonbeam is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// Moonbeam is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with Moonbeam.  If not, see <http://www.gnu.org/licenses/>.
16
17//! Substrate EVM tracing.
18//!
19//! The purpose of this crate is enable tracing the EVM opcode execution and will be used by
20//! both Dapp developers - to get a granular view on their transactions - and indexers to access
21//! the EVM callstack (internal transactions).
22//!
23//! Proxies EVM messages to the host functions.
24
25#![cfg_attr(not(feature = "std"), no_std)]
26
27pub mod tracer {
28	use ethereum_types::H256;
29	use evm_tracing_events::{EvmEvent, GasometerEvent, RuntimeEvent, StepEventFilter};
30	use parity_scale_codec::{Decode, Encode};
31
32	use evm::tracing::{using as evm_using, EventListener as EvmListener};
33	use evm_gasometer::tracing::{using as gasometer_using, EventListener as GasometerListener};
34	use evm_runtime::tracing::{using as runtime_using, EventListener as RuntimeListener};
35	use sp_runtime::DispatchError;
36	use sp_std::{cell::RefCell, rc::Rc};
37
38	/// The current EthereumXcmTransaction trace status.
39	#[derive(Clone, Debug, Encode, Decode, PartialEq, Eq)]
40	pub enum EthereumTracingStatus {
41		/// A full block trace.
42		Block,
43		/// A single transaction.
44		Transaction(H256),
45		/// Exit signal.
46		TransactionExited,
47	}
48
49	environmental::environmental!(ETHEREUM_TRACING_STATUS: EthereumTracingStatus);
50
51	struct ListenerProxy<T>(pub Rc<RefCell<T>>);
52	impl<T: GasometerListener> GasometerListener for ListenerProxy<T> {
53		fn event(&mut self, event: evm_gasometer::tracing::Event) {
54			self.0.borrow_mut().event(event);
55		}
56	}
57
58	impl<T: RuntimeListener> RuntimeListener for ListenerProxy<T> {
59		fn event(&mut self, event: evm_runtime::tracing::Event) {
60			self.0.borrow_mut().event(event);
61		}
62	}
63
64	impl<T: EvmListener> EvmListener for ListenerProxy<T> {
65		fn event(&mut self, event: evm::tracing::Event) {
66			self.0.borrow_mut().event(event);
67		}
68	}
69
70	pub struct EthereumTracer;
71
72	impl EthereumTracer {
73		pub fn transaction(
74			tx_hash: H256,
75			func: impl FnOnce() -> Result<(), DispatchError>,
76		) -> Result<(), DispatchError> {
77			ETHEREUM_TRACING_STATUS::using(&mut EthereumTracingStatus::Transaction(tx_hash), func)
78		}
79
80		pub fn block(
81			func: impl FnOnce() -> Result<(), DispatchError>,
82		) -> Result<(), DispatchError> {
83			ETHEREUM_TRACING_STATUS::using(&mut EthereumTracingStatus::Block, func)
84		}
85
86		pub fn transaction_exited() {
87			ETHEREUM_TRACING_STATUS::with(|state| {
88				*state = EthereumTracingStatus::TransactionExited
89			});
90		}
91
92		pub fn status() -> Option<EthereumTracingStatus> {
93			ETHEREUM_TRACING_STATUS::with(|state| state.clone())
94		}
95	}
96
97	pub struct EvmTracer {
98		step_event_filter: StepEventFilter,
99	}
100
101	impl EvmTracer {
102		pub fn new() -> Self {
103			Self {
104				step_event_filter: moonbeam_primitives_ext::moonbeam_ext::step_event_filter(),
105			}
106		}
107
108		/// Setup event listeners and execute provided closure.
109		///
110		/// Consume the tracer and return it alongside the return value of
111		/// the closure.
112		pub fn trace<R, F: FnOnce() -> R>(self, f: F) {
113			let wrapped = Rc::new(RefCell::new(self));
114
115			let mut gasometer = ListenerProxy(Rc::clone(&wrapped));
116			let mut runtime = ListenerProxy(Rc::clone(&wrapped));
117			let mut evm = ListenerProxy(Rc::clone(&wrapped));
118
119			// Each line wraps the previous `f` into a `using` call.
120			// Listening to new events results in adding one new line.
121			// Order is irrelevant when registering listeners.
122			let f = || runtime_using(&mut runtime, f);
123			let f = || gasometer_using(&mut gasometer, f);
124			let f = || evm_using(&mut evm, f);
125			f();
126		}
127
128		pub fn emit_new() {
129			moonbeam_primitives_ext::moonbeam_ext::call_list_new();
130		}
131	}
132
133	impl EvmListener for EvmTracer {
134		/// Proxies `evm::tracing::Event` to the host.
135		fn event(&mut self, event: evm::tracing::Event) {
136			let event: EvmEvent = event.into();
137			let message = event.encode();
138			moonbeam_primitives_ext::moonbeam_ext::evm_event(message);
139		}
140	}
141
142	impl GasometerListener for EvmTracer {
143		/// Proxies `evm_gasometer::tracing::Event` to the host.
144		fn event(&mut self, event: evm_gasometer::tracing::Event) {
145			let event: GasometerEvent = event.into();
146			let message = event.encode();
147			moonbeam_primitives_ext::moonbeam_ext::gasometer_event(message);
148		}
149	}
150
151	impl RuntimeListener for EvmTracer {
152		/// Proxies `evm_runtime::tracing::Event` to the host.
153		fn event(&mut self, event: evm_runtime::tracing::Event) {
154			let event = RuntimeEvent::from_evm_event(event, self.step_event_filter);
155			let message = event.encode();
156			moonbeam_primitives_ext::moonbeam_ext::runtime_event(message);
157		}
158	}
159}
moonbeam_evm_tracer/lib.rs

moonbeam_evm_tracer/
lib.rs
