ethrex_common/tracing.rs
1//! Trace data types and their wire-format serializers.
2//!
3//! ## Architecture
4//!
5//! Capture, data, and output format are separated:
6//!
7//! - **Capture** lives in `ethrex-levm` (`LevmOpcodeTracer`, the dispatch-loop hook).
8//! It runs once per tx and produces a [`Vec<OpcodeStep>`] plus the trailing
9//! metadata in [`OpcodeTraceResult`].
10//! - **Data** are the bare structs [`OpcodeStep`] and [`OpcodeTraceResult`] in this
11//! module. They carry no `Serialize` impl — they're consumer-agnostic. The same
12//! captured data feeds every downstream wire format.
13//! - **Wire format** is a newtype wrapper around one of those data structs with its
14//! own `Serialize` impl. Two shapes coexist:
15//! - [`StructLoggerStep`] / [`StructLoggerResult`] — the geth-RPC `debug_traceTransaction`
16//! structLogger shape: `op` as string mnemonic, no `opName`, decimal `gas`, etc.
17//! Used by the RPC handler and matches what every major client (geth, besu, …) emits
18//! from this endpoint. Consumers: Blockscout, Foundry, Tenderly, anything reading
19//! `debug_traceTransaction`.
20//! - [`Eip3155Step`] — strict [EIP-3155](https://eips.ethereum.org/EIPS/eip-3155)
21//! shape: numeric `op` byte + separate `opName`, `"0xN"` hex `gas`/`gasCost`/`refund`,
22//! `stack:[]` (never null) when disabled. Used by streaming sinks that want
23//! spec-conformant per-step JSONL — e.g. the `ef-tests-statev2 statetest` subcommand
24//! feeding goevmlab.
25//!
26//! Adding a third format (Parity-style flat call, opcode-count tracers, …) means another
27//! newtype with its own `Serialize` impl. No changes to the data types or capture layer.
28//!
29//! ## Why not match geth-RPC everywhere
30//!
31//! `debug_traceTransaction` predates EIP-3155 by years and its de-facto shape diverges
32//! from the spec on three points: `op` is a string, `opName` is absent, and `gas`/`gasCost`
33//! are decimal numbers instead of `"0xN"` hex strings. Every major client matches geth's
34//! shape there for tooling compat, not EIP-3155. So:
35//! - RPC consumer expects structLogger → use [`StructLoggerStep`]/[`StructLoggerResult`].
36//! - EIP-3155-conformant CLI consumer (goevmlab, fuzzers) → use [`Eip3155Step`].
37
38use bytes::Bytes;
39use ethereum_types::H256;
40use ethereum_types::{Address, U256};
41use serde::Serialize;
42use std::collections::BTreeMap;
43
44/// Collection of traces of each call frame as defined in geth's `callTracer` output
45/// https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#call-tracer
46pub type CallTrace = Vec<CallTraceFrame>;
47
48/// Trace of each call frame as defined in geth's `callTracer` output
49/// https://geth.ethereum.org/docs/developers/evm-tracing/built-in-tracers#call-tracer
50#[derive(Debug, Serialize, Default)]
51#[serde(rename_all = "camelCase")]
52pub struct CallTraceFrame {
53 /// Type of the Call
54 #[serde(rename = "type")]
55 pub call_type: CallType,
56 /// Address that initiated the call
57 pub from: Address,
58 /// Address that received the call
59 pub to: Address,
60 /// Amount transfered
61 pub value: U256,
62 /// Gas provided for the call
63 #[serde(with = "crate::serde_utils::u64::hex_str")]
64 pub gas: u64,
65 /// Gas used by the call
66 #[serde(with = "crate::serde_utils::u64::hex_str")]
67 pub gas_used: u64,
68 /// Call data
69 #[serde(with = "crate::serde_utils::bytes")]
70 pub input: Bytes,
71 /// Return data
72 #[serde(with = "crate::serde_utils::bytes")]
73 pub output: Bytes,
74 /// Error returned if the call failed
75 pub error: Option<String>,
76 /// Revert reason if the call reverted
77 pub revert_reason: Option<String>,
78 /// List of nested sub-calls
79 pub calls: Vec<CallTraceFrame>,
80 /// Logs (if enabled)
81 #[serde(skip_serializing_if = "Vec::is_empty")]
82 pub logs: Vec<CallLog>,
83}
84
85#[derive(Serialize, Debug, Default)]
86pub enum CallType {
87 #[default]
88 CALL,
89 CALLCODE,
90 STATICCALL,
91 DELEGATECALL,
92 CREATE,
93 CREATE2,
94 SELFDESTRUCT,
95}
96
97#[derive(Serialize, Debug)]
98#[serde(rename_all = "camelCase")]
99pub struct CallLog {
100 pub address: Address,
101 pub topics: Vec<H256>,
102 #[serde(with = "crate::serde_utils::bytes")]
103 pub data: Bytes,
104 pub position: u64,
105}
106
107/// Per-account state entry emitted by the prestateTracer.
108///
109/// `balance` is `Option<U256>`: `None` means "field absent from output",
110/// `Some(0)` still serializes (lets diff post emit a balance that became zero).
111#[derive(Debug, Serialize, Default, Clone)]
112#[serde(rename_all = "camelCase")]
113pub struct PrestateAccountState {
114 #[serde(default, skip_serializing_if = "Option::is_none")]
115 pub balance: Option<U256>,
116 #[serde(default, skip_serializing_if = "is_zero_nonce")]
117 pub nonce: u64,
118 #[serde(
119 default,
120 skip_serializing_if = "Bytes::is_empty",
121 with = "crate::serde_utils::bytes"
122 )]
123 pub code: Bytes,
124 #[serde(default, skip_serializing_if = "H256::is_zero")]
125 pub code_hash: H256,
126 #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
127 pub storage: BTreeMap<H256, H256>,
128}
129
130impl PrestateAccountState {
131 /// True when no field conveys information; `Some(0)` balance counts as empty.
132 pub fn is_empty(&self) -> bool {
133 self.balance.unwrap_or_default().is_zero()
134 && self.nonce == 0
135 && self.code.is_empty()
136 && self.code_hash.is_zero()
137 && self.storage.is_empty()
138 }
139}
140
141/// Per-transaction prestate trace (non-diff mode). `BTreeMap` keeps JSON output
142/// deterministic via sorted keys.
143pub type PrestateTrace = BTreeMap<Address, PrestateAccountState>;
144
145/// Result of a prestateTracer execution — either a plain prestate map or a diff.
146#[derive(Debug, Clone)]
147pub enum PrestateResult {
148 /// Non-diff mode: map of address → pre-tx account state.
149 Prestate(PrestateTrace),
150 /// Diff mode: pre-tx and post-tx state for all touched accounts.
151 Diff(PrePostState),
152}
153
154/// Per-transaction prestate trace (diff mode).
155/// Contains the pre-tx and post-tx state for all touched accounts.
156#[derive(Debug, Serialize, Default, Clone)]
157pub struct PrePostState {
158 pub pre: BTreeMap<Address, PrestateAccountState>,
159 pub post: BTreeMap<Address, PrestateAccountState>,
160}
161
162fn is_zero_nonce(n: &u64) -> bool {
163 *n == 0
164}
165
166// ─── OpcodeTracer types ──────────────────────────────────────────────────────
167
168/// Per-opcode trace entry — pure data, no `Serialize` impl.
169///
170/// To get this on the wire, wrap in one of the format newtypes:
171/// - [`StructLoggerStep`] for geth-RPC `debug_traceTransaction` shape.
172/// - [`Eip3155Step`] for EIP-3155 spec shape.
173///
174/// See the module-level doc for why both formats coexist.
175#[derive(Debug)]
176pub struct OpcodeStep {
177 pub pc: u64,
178 /// Raw opcode byte value (e.g. 0x60 for PUSH1). Each format serializer decides
179 /// how to render this (numeric byte, hex string, mnemonic string).
180 pub op: u8,
181 pub gas: u64,
182 pub gas_cost: u64,
183 /// Current memory size in bytes.
184 pub mem_size: u64,
185 pub depth: u32,
186 /// Return data from the previous sub-call.
187 pub return_data: bytes::Bytes,
188 /// Gas refund counter.
189 pub refund: u64,
190 /// `Some(vec)` when stack capture is enabled (bottom-first); `None` when disabled.
191 /// Each format serializer decides how to render `None`: structLogger emits JSON null,
192 /// EIP-3155 emits `[]` (per spec's "MUST initialize to empty array" rule).
193 pub stack: Option<Vec<U256>>,
194 /// `Some(chunks)` when memory capture is enabled; `None` when disabled (field omitted).
195 pub memory: Option<Vec<MemoryChunk>>,
196 /// `Some(map)` at SLOAD/SSTORE steps when storage capture is enabled; `None`
197 /// otherwise. The map is a cumulative snapshot of every slot touched by an
198 /// SLOAD/SSTORE so far in the transaction — matching geth's structLogger.
199 /// The tracer maintains this in `LevmOpcodeTracer::cumulative_storage`.
200 pub storage: Option<BTreeMap<H256, H256>>,
201 pub error: Option<String>,
202}
203
204/// A 32-byte chunk of EVM memory, serialized as `"0x" + 64 lowercase hex chars`.
205/// The *caller* zero-pads the last partial chunk before constructing this type.
206#[derive(Debug)]
207pub struct MemoryChunk(pub [u8; 32]);
208
209/// Top-level result of one opcode-traced transaction — pure data, no `Serialize` impl.
210///
211/// Wrap in [`StructLoggerResult`] to get the geth-RPC `{failed, gas, returnValue, structLogs}`
212/// wire shape. EIP-3155-conformant CLI consumers stream per-step [`OpcodeStep`]s
213/// directly (via [`Eip3155Step`]) and emit their own summary line, so there's no
214/// EIP-3155 wrapper newtype for the result.
215#[derive(Debug)]
216pub struct OpcodeTraceResult {
217 pub gas_used: u64,
218 /// True iff the transaction completed without error.
219 pub pass: bool,
220 pub output: bytes::Bytes,
221 pub steps: Vec<OpcodeStep>,
222}
223
224// ─── Helpers ──────────────────────────────────────────────────────────────
225
226/// Returns the opcode mnemonic for `byte`.
227///
228/// Known opcodes → their uppercase name (`"PUSH1"`, `"ADD"`, `"INVALID"` for
229/// 0xFE). Unassigned bytes → `None`; callers wanting the conventional unknown
230/// string should fall back to `format!("opcode 0x{:02x} not defined", byte)`.
231///
232/// The table is **fork-agnostic by design**, matching geth's
233/// `core/vm/opcodes.go::opCodeToString` (also a flat 256-entry table). Fork
234/// validity is enforced at *dispatch* via the VM's per-fork opcode table:
235/// e.g. byte `0x5F` (PUSH0) halts pre-Shanghai with `InvalidOpcode` before
236/// the tracer ever emits a step for it, so the name lookup never fires for
237/// invalid-for-this-fork bytes in practice.
238pub fn opcode_name(byte: u8) -> Option<&'static str> {
239 match byte {
240 0x00 => Some("STOP"),
241 0x01 => Some("ADD"),
242 0x02 => Some("MUL"),
243 0x03 => Some("SUB"),
244 0x04 => Some("DIV"),
245 0x05 => Some("SDIV"),
246 0x06 => Some("MOD"),
247 0x07 => Some("SMOD"),
248 0x08 => Some("ADDMOD"),
249 0x09 => Some("MULMOD"),
250 0x0A => Some("EXP"),
251 0x0B => Some("SIGNEXTEND"),
252 0x10 => Some("LT"),
253 0x11 => Some("GT"),
254 0x12 => Some("SLT"),
255 0x13 => Some("SGT"),
256 0x14 => Some("EQ"),
257 0x15 => Some("ISZERO"),
258 0x16 => Some("AND"),
259 0x17 => Some("OR"),
260 0x18 => Some("XOR"),
261 0x19 => Some("NOT"),
262 0x1A => Some("BYTE"),
263 0x1B => Some("SHL"),
264 0x1C => Some("SHR"),
265 0x1D => Some("SAR"),
266 0x1E => Some("CLZ"),
267 0x20 => Some("KECCAK256"),
268 0x30 => Some("ADDRESS"),
269 0x31 => Some("BALANCE"),
270 0x32 => Some("ORIGIN"),
271 0x33 => Some("CALLER"),
272 0x34 => Some("CALLVALUE"),
273 0x35 => Some("CALLDATALOAD"),
274 0x36 => Some("CALLDATASIZE"),
275 0x37 => Some("CALLDATACOPY"),
276 0x38 => Some("CODESIZE"),
277 0x39 => Some("CODECOPY"),
278 0x3A => Some("GASPRICE"),
279 0x3B => Some("EXTCODESIZE"),
280 0x3C => Some("EXTCODECOPY"),
281 0x3D => Some("RETURNDATASIZE"),
282 0x3E => Some("RETURNDATACOPY"),
283 0x3F => Some("EXTCODEHASH"),
284 0x40 => Some("BLOCKHASH"),
285 0x41 => Some("COINBASE"),
286 0x42 => Some("TIMESTAMP"),
287 0x43 => Some("NUMBER"),
288 0x44 => Some("PREVRANDAO"),
289 0x45 => Some("GASLIMIT"),
290 0x46 => Some("CHAINID"),
291 0x47 => Some("SELFBALANCE"),
292 0x48 => Some("BASEFEE"),
293 0x49 => Some("BLOBHASH"),
294 0x4A => Some("BLOBBASEFEE"),
295 0x4B => Some("SLOTNUM"),
296 0x50 => Some("POP"),
297 0x51 => Some("MLOAD"),
298 0x52 => Some("MSTORE"),
299 0x53 => Some("MSTORE8"),
300 0x54 => Some("SLOAD"),
301 0x55 => Some("SSTORE"),
302 0x56 => Some("JUMP"),
303 0x57 => Some("JUMPI"),
304 0x58 => Some("PC"),
305 0x59 => Some("MSIZE"),
306 0x5A => Some("GAS"),
307 0x5B => Some("JUMPDEST"),
308 0x5C => Some("TLOAD"),
309 0x5D => Some("TSTORE"),
310 0x5E => Some("MCOPY"),
311 0x5F => Some("PUSH0"),
312 0x60 => Some("PUSH1"),
313 0x61 => Some("PUSH2"),
314 0x62 => Some("PUSH3"),
315 0x63 => Some("PUSH4"),
316 0x64 => Some("PUSH5"),
317 0x65 => Some("PUSH6"),
318 0x66 => Some("PUSH7"),
319 0x67 => Some("PUSH8"),
320 0x68 => Some("PUSH9"),
321 0x69 => Some("PUSH10"),
322 0x6A => Some("PUSH11"),
323 0x6B => Some("PUSH12"),
324 0x6C => Some("PUSH13"),
325 0x6D => Some("PUSH14"),
326 0x6E => Some("PUSH15"),
327 0x6F => Some("PUSH16"),
328 0x70 => Some("PUSH17"),
329 0x71 => Some("PUSH18"),
330 0x72 => Some("PUSH19"),
331 0x73 => Some("PUSH20"),
332 0x74 => Some("PUSH21"),
333 0x75 => Some("PUSH22"),
334 0x76 => Some("PUSH23"),
335 0x77 => Some("PUSH24"),
336 0x78 => Some("PUSH25"),
337 0x79 => Some("PUSH26"),
338 0x7A => Some("PUSH27"),
339 0x7B => Some("PUSH28"),
340 0x7C => Some("PUSH29"),
341 0x7D => Some("PUSH30"),
342 0x7E => Some("PUSH31"),
343 0x7F => Some("PUSH32"),
344 0x80 => Some("DUP1"),
345 0x81 => Some("DUP2"),
346 0x82 => Some("DUP3"),
347 0x83 => Some("DUP4"),
348 0x84 => Some("DUP5"),
349 0x85 => Some("DUP6"),
350 0x86 => Some("DUP7"),
351 0x87 => Some("DUP8"),
352 0x88 => Some("DUP9"),
353 0x89 => Some("DUP10"),
354 0x8A => Some("DUP11"),
355 0x8B => Some("DUP12"),
356 0x8C => Some("DUP13"),
357 0x8D => Some("DUP14"),
358 0x8E => Some("DUP15"),
359 0x8F => Some("DUP16"),
360 0x90 => Some("SWAP1"),
361 0x91 => Some("SWAP2"),
362 0x92 => Some("SWAP3"),
363 0x93 => Some("SWAP4"),
364 0x94 => Some("SWAP5"),
365 0x95 => Some("SWAP6"),
366 0x96 => Some("SWAP7"),
367 0x97 => Some("SWAP8"),
368 0x98 => Some("SWAP9"),
369 0x99 => Some("SWAP10"),
370 0x9A => Some("SWAP11"),
371 0x9B => Some("SWAP12"),
372 0x9C => Some("SWAP13"),
373 0x9D => Some("SWAP14"),
374 0x9E => Some("SWAP15"),
375 0x9F => Some("SWAP16"),
376 0xA0 => Some("LOG0"),
377 0xA1 => Some("LOG1"),
378 0xA2 => Some("LOG2"),
379 0xA3 => Some("LOG3"),
380 0xA4 => Some("LOG4"),
381 0xE6 => Some("DUPN"),
382 0xE7 => Some("SWAPN"),
383 0xE8 => Some("EXCHANGE"),
384 0xF0 => Some("CREATE"),
385 0xF1 => Some("CALL"),
386 0xF2 => Some("CALLCODE"),
387 0xF3 => Some("RETURN"),
388 0xF4 => Some("DELEGATECALL"),
389 0xF5 => Some("CREATE2"),
390 0xFA => Some("STATICCALL"),
391 0xFD => Some("REVERT"),
392 0xFE => Some("INVALID"),
393 0xFF => Some("SELFDESTRUCT"),
394 _ => None,
395 }
396}
397
398/// Converts a `U256` to geth's `uint256.Int.Hex()` form: `"0x"` followed by
399/// lowercase hex with leading zeros stripped. Zero → `"0x0"` (not `"0x"`).
400pub fn geth_uint256_hex(v: &U256) -> String {
401 if v.is_zero() {
402 return "0x0".to_string();
403 }
404 // U256 words are little-endian; convert to big-endian bytes.
405 let bytes = crate::utils::u256_to_big_endian(*v);
406 let hex_str = hex::encode(bytes);
407 let stripped = hex_str.trim_start_matches('0');
408 format!("0x{}", stripped)
409}
410
411// ─── Serialize impls ──────────────────────────────────────────────────────
412
413impl serde::Serialize for MemoryChunk {
414 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
415 serializer.serialize_str(&format!("0x{}", hex::encode(self.0)))
416 }
417}
418
419// Shared utilities used by both wire-format serializers below.
420
421fn serialize_storage_map<S: serde::Serializer>(
422 serializer: S,
423 storage: &BTreeMap<H256, H256>,
424) -> Result<S::Ok, S::Error> {
425 use serde::ser::SerializeMap;
426 let mut m = serializer.serialize_map(Some(storage.len()))?;
427 for (k, v) in storage {
428 let k_str = format!("0x{}", hex::encode(k.as_bytes()));
429 let v_str = format!("0x{}", hex::encode(v.as_bytes()));
430 m.serialize_entry(&k_str, &v_str)?;
431 }
432 m.end()
433}
434
435/// Mnemonic string for an opcode byte, falling back to `"opcode 0xNN not defined"`
436/// for bytes outside the assigned table.
437fn opcode_name_or_fallback(byte: u8) -> String {
438 opcode_name(byte)
439 .map(str::to_owned)
440 .unwrap_or_else(|| format!("opcode 0x{byte:02x} not defined"))
441}
442
443// ─── Wire format: geth-RPC structLogger ───────────────────────────────────
444//
445// The de-facto `debug_traceTransaction` response shape, emitted by every major
446// execution client (geth, besu, reth, erigon, nethermind). Predates EIP-3155
447// and diverges from it on three per-step fields:
448//
449// - `op`: string mnemonic (`"PUSH1"`), not the numeric opcode byte.
450// - No separate `opName` field.
451// - `gas`, `gasCost`, `refund`: decimal JSON numbers, not `"0xN"` hex strings.
452//
453// `stack` is serialized as JSON `null` when capture is disabled — also a divergence
454// from EIP-3155, which mandates `[]` — but it matches geth's RPC behavior so we
455// preserve it on this code path.
456//
457// Verified against geth and besu on a kurtosis localnet via `debug_traceTransaction`:
458// byte-for-byte identical to the StructLogger output.
459
460/// Controls which always-populated per-step fields the structLogger wire format emits.
461///
462/// `mem_size`, `return_data`, and `refund` are always present in the captured
463/// [`OpcodeStep`] (the capture layer just defaults them to zero/empty when the
464/// corresponding capture config is off). geth's `debug_traceTransaction` *suppresses*
465/// these fields unless their data is actually captured. To match geth byte-for-byte
466/// we honor the caller's intent explicitly here.
467///
468/// Typical mapping at the RPC layer:
469///
470/// ```ignore
471/// let emit = StructLoggerEmit {
472/// mem_size: cfg.enable_memory, // memSize travels with memory
473/// return_data: cfg.enable_return_data,
474/// refund: false, // no equivalent geth flag; off by default
475/// };
476/// ```
477#[derive(Debug, Clone, Copy, Default)]
478pub struct StructLoggerEmit {
479 /// Emit `memSize` even when its value is meaningful at every step.
480 /// Geth ties this to memory capture; default `false` matches geth's default config.
481 pub mem_size: bool,
482 /// Emit `returnData` (as `"0x..."` hex). Default `false` matches geth.
483 pub return_data: bool,
484 /// Force-emit `refund` even when it's zero. Default `false` matches geth's
485 /// `omitempty` behavior — non-zero refund is always emitted regardless of this flag.
486 pub refund: bool,
487}
488
489/// Wraps an [`OpcodeStep`] to serialize in the geth-RPC `structLogger` shape used by
490/// `debug_traceTransaction`. See module-level docs and the comment above this type
491/// for the field-shape divergences from EIP-3155.
492pub struct StructLoggerStep<'a> {
493 pub step: &'a OpcodeStep,
494 pub emit: StructLoggerEmit,
495}
496
497impl serde::Serialize for StructLoggerStep<'_> {
498 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
499 use serde::ser::SerializeMap;
500 let step = self.step;
501 let emit = self.emit;
502
503 // pc, op, gas, gasCost, depth, stack are always emitted (6 base fields).
504 let mut field_count = 6;
505 if emit.mem_size {
506 field_count += 1;
507 }
508 if emit.return_data {
509 field_count += 1;
510 }
511 if emit.refund || step.refund != 0 {
512 field_count += 1;
513 }
514 if step.error.is_some() {
515 field_count += 1;
516 }
517 if step.memory.is_some() {
518 field_count += 1;
519 }
520 if step.storage.is_some() {
521 field_count += 1;
522 }
523
524 let mut map = serializer.serialize_map(Some(field_count))?;
525
526 map.serialize_entry("pc", &step.pc)?;
527 // op: string mnemonic, matching geth's wire output (NOT EIP-3155's numeric form).
528 map.serialize_entry("op", &opcode_name_or_fallback(step.op))?;
529 // gas/gasCost/refund: decimal JSON numbers, matching geth's wire output.
530 map.serialize_entry("gas", &step.gas)?;
531 map.serialize_entry("gasCost", &step.gas_cost)?;
532 map.serialize_entry("depth", &step.depth)?;
533
534 // stack: JSON null when disabled, array of `"0xN"` hex strings when enabled.
535 // Matches geth's RPC behavior; diverges from EIP-3155's "MUST be []" rule.
536 struct StackSerializer<'a>(&'a Option<Vec<U256>>);
537 impl serde::Serialize for StackSerializer<'_> {
538 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
539 use serde::ser::SerializeSeq;
540 match self.0 {
541 None => serializer.serialize_none(),
542 Some(vec) => {
543 let mut seq = serializer.serialize_seq(Some(vec.len()))?;
544 for v in vec {
545 seq.serialize_element(&geth_uint256_hex(v))?;
546 }
547 seq.end()
548 }
549 }
550 }
551 }
552 map.serialize_entry("stack", &StackSerializer(&step.stack))?;
553
554 if emit.mem_size {
555 map.serialize_entry("memSize", &step.mem_size)?;
556 }
557 if emit.return_data {
558 map.serialize_entry(
559 "returnData",
560 &format!("0x{}", hex::encode(&step.return_data)),
561 )?;
562 }
563 // `refund` is omitempty-for-zero in geth's wire output: always emitted when
564 // non-zero; emitted-when-zero only when the caller forces it via `emit.refund`.
565 if emit.refund || step.refund != 0 {
566 map.serialize_entry("refund", &step.refund)?;
567 }
568
569 if let Some(err) = &step.error {
570 map.serialize_entry("error", err)?;
571 }
572 if let Some(mem) = &step.memory {
573 map.serialize_entry("memory", mem)?;
574 }
575 if let Some(storage) = &step.storage {
576 struct Wrap<'a>(&'a BTreeMap<H256, H256>);
577 impl serde::Serialize for Wrap<'_> {
578 fn serialize<S: serde::Serializer>(
579 &self,
580 serializer: S,
581 ) -> Result<S::Ok, S::Error> {
582 serialize_storage_map(serializer, self.0)
583 }
584 }
585 map.serialize_entry("storage", &Wrap(storage))?;
586 }
587
588 map.end()
589 }
590}
591
592/// Wraps an [`OpcodeTraceResult`] to serialize as the geth-RPC `debug_traceTransaction`
593/// response: `{failed, gas, returnValue, structLogs: [...]}`. Each step inside
594/// `structLogs` is itself serialized via [`StructLoggerStep`] using the same `emit` flags.
595pub struct StructLoggerResult<'a> {
596 pub result: &'a OpcodeTraceResult,
597 pub emit: StructLoggerEmit,
598}
599
600impl serde::Serialize for StructLoggerResult<'_> {
601 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
602 use serde::ser::{SerializeMap, SerializeSeq};
603 let r = self.result;
604 let emit = self.emit;
605
606 // structLogs uses StructLoggerStep for each entry, with the same emit options.
607 struct Steps<'a> {
608 steps: &'a [OpcodeStep],
609 emit: StructLoggerEmit,
610 }
611 impl serde::Serialize for Steps<'_> {
612 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
613 let mut seq = serializer.serialize_seq(Some(self.steps.len()))?;
614 for s in self.steps {
615 seq.serialize_element(&StructLoggerStep {
616 step: s,
617 emit: self.emit,
618 })?;
619 }
620 seq.end()
621 }
622 }
623
624 let mut map = serializer.serialize_map(Some(4))?;
625 // `failed` is the inverse of `pass` — matches the geth wire shape.
626 map.serialize_entry("failed", &!r.pass)?;
627 map.serialize_entry("gas", &r.gas_used)?;
628 map.serialize_entry("returnValue", &format!("0x{}", hex::encode(&r.output)))?;
629 map.serialize_entry(
630 "structLogs",
631 &Steps {
632 steps: &r.steps,
633 emit,
634 },
635 )?;
636 map.end()
637 }
638}
639
640// ─── Wire format: EIP-3155 ────────────────────────────────────────────────
641//
642// The shape defined by EIP-3155 §"Required Fields":
643//
644// - `op`: numeric opcode byte (e.g. `96` for PUSH1).
645// - `opName`: separate string mnemonic, always emitted (technically optional per spec).
646// - `gas`, `gasCost`, `refund`: `"0xN"` hex strings ("Hex-Number" per spec).
647// - `stack`: always an array, never null (spec: "All array attributes MUST be
648// initialized to empty arrays NOT to null").
649//
650// Field order matches the spec's listed order. Used by streaming sinks that feed
651// EIP-3155-conformant tooling (goevmlab, fuzzers). NOT used by `debug_traceTransaction`,
652// where existing tooling expects the structLogger shape above.
653
654/// Wraps an [`OpcodeStep`] to serialize in strict EIP-3155 shape. See module-level
655/// docs and the comment above this type for the field-shape choices.
656pub struct Eip3155Step<'a>(pub &'a OpcodeStep);
657
658impl serde::Serialize for Eip3155Step<'_> {
659 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
660 use serde::ser::SerializeMap;
661 let step = self.0;
662
663 let mut field_count = 10; // required 9 + always-emitted opName
664 if step.error.is_some() {
665 field_count += 1;
666 }
667 if step.memory.is_some() {
668 field_count += 1;
669 }
670 if step.storage.is_some() {
671 field_count += 1;
672 }
673
674 let mut map = serializer.serialize_map(Some(field_count))?;
675
676 // Required fields in spec order.
677 map.serialize_entry("pc", &step.pc)?;
678 map.serialize_entry("op", &step.op)?;
679 map.serialize_entry("gas", &format!("{:#x}", step.gas))?;
680 map.serialize_entry("gasCost", &format!("{:#x}", step.gas_cost))?;
681 map.serialize_entry("memSize", &step.mem_size)?;
682
683 // stack: always an array; `None` (disabled) becomes `[]`.
684 struct StackSerializer<'a>(&'a Option<Vec<U256>>);
685 impl serde::Serialize for StackSerializer<'_> {
686 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
687 use serde::ser::SerializeSeq;
688 let vec_ref: &[U256] = self.0.as_deref().unwrap_or(&[]);
689 let mut seq = serializer.serialize_seq(Some(vec_ref.len()))?;
690 for v in vec_ref {
691 seq.serialize_element(&geth_uint256_hex(v))?;
692 }
693 seq.end()
694 }
695 }
696 map.serialize_entry("stack", &StackSerializer(&step.stack))?;
697
698 map.serialize_entry("depth", &step.depth)?;
699 map.serialize_entry(
700 "returnData",
701 &format!("0x{}", hex::encode(&step.return_data)),
702 )?;
703 map.serialize_entry("refund", &format!("{:#x}", step.refund))?;
704
705 // Optional fields in spec order: opName, error, memory, storage.
706 // opName always emitted (covers both known and unknown opcode bytes).
707 map.serialize_entry("opName", &opcode_name_or_fallback(step.op))?;
708
709 if let Some(err) = &step.error {
710 map.serialize_entry("error", err)?;
711 }
712 if let Some(mem) = &step.memory {
713 map.serialize_entry("memory", mem)?;
714 }
715 if let Some(storage) = &step.storage {
716 struct Wrap<'a>(&'a BTreeMap<H256, H256>);
717 impl serde::Serialize for Wrap<'_> {
718 fn serialize<S: serde::Serializer>(
719 &self,
720 serializer: S,
721 ) -> Result<S::Ok, S::Error> {
722 serialize_storage_map(serializer, self.0)
723 }
724 }
725 map.serialize_entry("storage", &Wrap(storage))?;
726 }
727
728 map.end()
729 }
730}