1use alloy_primitives::{Address, B256, Bytes, hex, keccak256, map::HashSet};
8use evm2::interpreter::{InstrStop, opcode::OpCode};
9use eyre::{OptionExt, Result};
10use foundry_common::{
11 ContractsByArtifact, Shell,
12 fs::{self, write_json_file},
13};
14use foundry_compilers::{
15 artifacts::sourcemap::{Jump, SourceElement, SourceMap},
16 multi::MultiCompilerLanguage,
17};
18use foundry_evm_core::{Breakpoints, ic::PcIcMap};
19use foundry_evm_traces::{
20 CallTrace, CallTraceArena, CallTraceNode, CallTraceStep, TraceMemberOrder,
21 debug::{
22 ArtifactData, ContractSources, DebugRecording, RecordedFrame, SourceData, StepConverter,
23 quantity, step_record,
24 },
25};
26use foundry_tui::{TuiMode, restore_terminal_on_panic, tui_mode};
27use serde_json::{Map, Value, json};
28use soldb_core::{
29 ContractCreation, EvmWord, ExecutionCall, StepRecord, StepTable, TraceArtifacts,
30 TraceCapabilities, TransactionTrace,
31};
32use soldb_debugger::{CodeGenerator, ContractDebugInfo, SourceCache, StorageLayout};
33use soldb_ethdebug::{EthdebugInfo, Instruction, SourceLocation, SourceMapContext, SourceMapJump};
34use soldb_repl::{BreakpointTarget, DebuggerCommand, DebuggerState, Output, Renderer, Session};
35use soldb_tui::Exit;
36use std::{
37 collections::{BTreeMap, BTreeSet, HashMap},
38 io::{self, IsTerminal, Write},
39 ops::Range,
40 path::{Component, Path, PathBuf},
41 sync::Arc,
42};
43
44type BreakpointFrames = Vec<(Range<usize>, u64)>;
46
47type BreakpointSteps = BTreeMap<(Address, usize), BreakpointFrames>;
49
50#[derive(Debug)]
52pub(crate) struct SoldbDebugger {
53 trace: TransactionTrace,
54 contracts: Vec<ContractDebugInfo>,
55 breakpoints: Vec<(u64, BreakpointFrames)>,
57}
58
59impl SoldbDebugger {
60 pub(crate) fn new(
65 mut arenas: Vec<CallTraceArena>,
66 recordings: Vec<DebugRecording>,
67 contract_names: &[Vec<Option<String>>],
68 sources: &ContractSources,
69 known_contracts: &ContractsByArtifact,
70 breakpoints: &Breakpoints,
71 ) -> Result<Self> {
72 let mut source_cache = SourceCache::default();
73 let contracts = executed_programs(&arenas, contract_names, sources, known_contracts)
74 .iter()
75 .filter_map(|program| contract_debug_info(program, &mut source_cache))
76 .collect();
77 let (trace, breakpoints) = transaction_trace(&mut arenas, recordings, breakpoints)?;
78 let breakpoints = breakpoints
79 .into_iter()
80 .filter(|(_, frames)| !frames.is_empty())
81 .map(|((_, pc), frames)| (pc as u64, frames))
82 .collect();
83 Ok(Self { trace, contracts, breakpoints })
84 }
85
86 pub(crate) fn try_run(self) -> Result<()> {
91 let mut state = DebuggerState::new();
92 state.load_trace_with_debug_info(self.trace, self.contracts)?;
93 for (pc, frames) in self.breakpoints {
97 let condition = frames
98 .iter()
99 .map(|(steps, depth)| {
100 format!("step >= {} && step < {} && depth == {depth}", steps.start, steps.end)
101 })
102 .collect::<Vec<_>>()
103 .join(" || ");
104 state.set_conditional_breakpoint_target(&BreakpointTarget::Pc(pc), Some(&condition));
105 }
106 let mut session = Session::new(state);
107 let renderer = Renderer::new(Shell::get().out_supports_color());
108 let prompt = io::stdin().is_terminal();
110
111 emit(&renderer, vec![session.loaded()])?;
112 emit(&renderer, session.initial_stop())?;
113 if tui_mode().is_interactive() && open_tui(&mut session)? == Flow::Quit {
114 return Ok(());
115 }
116 if prompt {
117 sh_eprintln!("Type `help` for the command list, `tui` for the full-screen view.")?;
118 }
119
120 let mut line = String::new();
121 loop {
122 if prompt {
123 sh_eprint!("soldb> ")?;
124 io::stderr().flush()?;
125 }
126 line.clear();
127 if io::stdin().read_line(&mut line)? == 0 {
128 break;
129 }
130 match emit(&renderer, session.execute(DebuggerCommand::parse(&line)))? {
131 Flow::Continue => {}
132 Flow::Tui if open_tui(&mut session)? == Flow::Continue => {}
133 Flow::Tui | Flow::Quit => break,
134 }
135 }
136 Ok(())
137 }
138}
139
140#[derive(Clone, Copy, Debug, PartialEq, Eq)]
142enum Flow {
143 Continue,
144 Tui,
145 Quit,
146}
147
148fn emit(renderer: &Renderer, outputs: Vec<Output>) -> Result<Flow> {
150 let mut flow = Flow::Continue;
151 for output in outputs {
152 match output {
153 Output::Tui => flow = Flow::Tui,
154 Output::Quit => flow = Flow::Quit,
155 _ => {}
156 }
157 sh_print!("{}", renderer.render(&output))?;
158 }
159 Ok(flow)
160}
161
162fn open_tui(session: &mut Session) -> Result<Flow> {
164 if let TuiMode::Fallback(reason) = tui_mode() {
165 sh_warn!("cannot open the full-screen view: {}", reason.as_str())?;
166 return Ok(Flow::Continue);
167 }
168 match restore_terminal_on_panic(|| soldb_tui::run(session)) {
169 Ok(Exit::Repl) => Ok(Flow::Continue),
170 Ok(Exit::Quit) => Ok(Flow::Quit),
171 Err(error) if error.kind() == io::ErrorKind::Unsupported => {
172 sh_warn!("cannot open the full-screen view: {error}")?;
173 Ok(Flow::Continue)
174 }
175 Err(error) => Err(error.into()),
176 }
177}
178
179fn transaction_trace(
186 arenas: &mut [CallTraceArena],
187 recordings: Vec<DebugRecording>,
188 breakpoints: &Breakpoints,
189) -> Result<(TransactionTrace, BreakpointSteps)> {
190 let nodes = arenas.iter().flat_map(|arena| arena.nodes());
191 let (steps, frames) =
192 nodes.fold((0, 0), |(steps, frames), node| (steps + node.trace.steps.len(), frames + 1));
193 let mut builder = TraceBuilder {
194 calls: Vec::with_capacity(frames),
195 creations: Vec::with_capacity(frames),
196 breakpoints: breakpoints.values().map(|location| (*location, Vec::new())).collect(),
197 ..Default::default()
198 };
199 if recordings.is_empty() {
200 builder.steps = StepTable::with_capacity(steps);
201 for arena in &mut *arenas {
202 builder.visit(arena.nodes_mut(), 0, None);
203 }
204 } else {
205 eyre::ensure!(recordings.len() == arenas.len(), "a debug trace has no recorded steps");
206 let offsets;
207 (builder.steps, offsets) = recorded_steps(&recordings)?;
208 for ((arena, recording), offset) in arenas.iter_mut().zip(&recordings).zip(offsets) {
209 let nodes = arena.nodes_mut();
210 eyre::ensure!(
211 recording.frames.len() == nodes.len()
212 && recording
213 .frames
214 .iter()
215 .zip(&*nodes)
216 .all(|(frame, node)| frame.depth == node.trace.depth),
217 "the recorded steps do not match the call trace"
218 );
219 builder.visit_recorded(nodes, 0, None, &recording.frames, offset);
220 }
221 }
222 let TraceBuilder { steps, calls, creations, breakpoints, .. } = builder;
223
224 let root = &arenas.last().ok_or_eyre("debug arena is empty")?.nodes()[0].trace;
227 let create = root.kind.is_any_create();
228 let trace = TransactionTrace {
229 tx_hash: None,
230 from_addr: hex::encode_prefixed(root.caller),
231 to_addr: (!create).then(|| hex::encode_prefixed(root.address)),
232 value: quantity(root.value),
233 input_data: hex::encode_prefixed(&root.data),
234 gas_used: arenas
235 .iter()
236 .fold(0u64, |gas, arena| gas.saturating_add(arena.nodes()[0].trace.gas_used)),
237 output: hex::encode_prefixed(&root.output),
238 success: arenas.iter().all(|arena| arena.nodes()[0].trace.success),
239 error: arenas.iter().find_map(|arena| status_error(arena.nodes()[0].trace.status)),
240 debug_trace_available: true,
241 contract_address: create.then(|| hex::encode_prefixed(root.address)),
242 backend: Some("foundry".to_string()),
243 capabilities: TraceCapabilities {
244 opcode_steps: true,
245 stack: true,
246 memory: true,
247 storage: true,
248 storage_diff: true,
249 call_trace: true,
250 contract_creation: true,
251 transient_storage: true,
252 return_data: true,
253 ..Default::default()
254 },
255 artifacts: TraceArtifacts { calls, creations, ..Default::default() },
256 steps,
257 };
258 Ok((trace, breakpoints))
259}
260
261#[derive(Default)]
263struct TraceBuilder {
264 steps: StepTable,
265 calls: Vec<ExecutionCall>,
266 creations: Vec<ContractCreation>,
267 converter: StepConverter,
269 breakpoints: BreakpointSteps,
271}
272
273impl TraceBuilder {
274 fn visit(&mut self, nodes: &mut [CallTraceNode], idx: usize, parent: Option<usize>) {
276 let node = &mut nodes[idx];
277 let ordering = std::mem::take(&mut node.ordering);
278 let children = std::mem::take(&mut node.children);
279 let mut steps = std::mem::take(&mut node.trace.steps);
280 let runs_steps = !steps.is_empty();
281 let trace = &node.trace;
282 let address = trace.address;
283 let depth = trace.depth as u64 + 1;
284 let entry_step = self.steps.len();
285 let (creation, call) = self.open_frame(trace, parent, entry_step);
286
287 let mut next_step = 0;
289 let mut hits = Vec::new();
290 for order in ordering {
291 match order {
292 TraceMemberOrder::Step(_) => {
293 if next_step < steps.len() {
294 let (done, rest) = steps.split_at_mut(next_step + 1);
295 let step = &mut done[next_step];
296 if self.breakpoints.contains_key(&(address, step.pc))
297 && !hits.contains(&step.pc)
298 {
299 hits.push(step.pc);
300 }
301 self.push_step(step, rest.first(), depth);
302 step.stack = None;
304 step.memory = None;
305 next_step += 1;
306 }
307 }
308 TraceMemberOrder::Call(child) => {
309 self.visit(nodes, children[child], call.or(parent));
310 }
311 TraceMemberOrder::Log(_) => {}
312 }
313 }
314
315 self.close_frame(creation, call, self.steps.len(), runs_steps);
316 self.record_hits(address, hits, entry_step..self.steps.len(), depth);
317 }
318
319 fn visit_recorded(
322 &mut self,
323 nodes: &mut [CallTraceNode],
324 idx: usize,
325 parent: Option<usize>,
326 frames: &[RecordedFrame],
327 offset: usize,
328 ) {
329 let node = &mut nodes[idx];
330 let ordering = std::mem::take(&mut node.ordering);
331 let children = std::mem::take(&mut node.children);
332 let address = node.trace.address;
333 let frame = frames[idx];
334 let (creation, call) = self.open_frame(&node.trace, parent, offset + frame.entry_step);
335
336 let mut next_step = offset + frame.entry_step;
338 let mut runs_steps = false;
339 let mut hits = Vec::new();
340 for order in ordering {
341 if let TraceMemberOrder::Call(child) = order {
342 let child = children[child];
343 let own = next_step..offset + frames[child].entry_step;
344 runs_steps |= !own.is_empty();
345 self.find_hits(address, own, &mut hits);
346 self.visit_recorded(nodes, child, call.or(parent), frames, offset);
347 next_step = offset + frames[child].exit_step;
348 }
349 }
350 let own = next_step..offset + frame.exit_step;
351 runs_steps |= !own.is_empty();
352 self.find_hits(address, own, &mut hits);
353
354 let steps = offset + frame.entry_step..offset + frame.exit_step;
355 self.close_frame(creation, call, steps.end, runs_steps);
356 self.record_hits(address, hits, steps, frame.depth as u64 + 1);
357 }
358
359 fn find_hits(&self, address: Address, steps: Range<usize>, hits: &mut Vec<usize>) {
362 if self.breakpoints.range((address, 0)..=(address, usize::MAX)).next().is_none() {
363 return;
364 }
365 for index in steps {
366 let pc = self.steps.step(index).pc() as usize;
367 if self.breakpoints.contains_key(&(address, pc)) && !hits.contains(&pc) {
368 hits.push(pc);
369 }
370 }
371 }
372
373 fn record_hits(&mut self, address: Address, hits: Vec<usize>, steps: Range<usize>, depth: u64) {
376 for pc in hits {
377 if let Some(frames) = self.breakpoints.get_mut(&(address, pc)) {
378 frames.push((steps.clone(), depth));
379 }
380 }
381 }
382
383 fn open_frame(
386 &mut self,
387 trace: &CallTrace,
388 parent: Option<usize>,
389 entry_step: usize,
390 ) -> (Option<usize>, Option<usize>) {
391 let depth = trace.depth as u64 + 1;
392 let entry_step = Some(entry_step);
393 let error = status_error(trace.status);
394 let code_hash = trace.bytecode.as_ref().map(|code| keccak256(code).to_string());
397 let creation = trace.kind.is_any_create().then_some(self.creations.len());
398 let mut call = None;
399 if creation.is_some() {
400 self.creations.push(ContractCreation {
401 id: self.creations.len(),
402 parent_id: parent,
403 depth,
404 entry_step,
405 exit_step: None,
406 create_type: trace.kind.to_string(),
407 caller: hex::encode_prefixed(trace.caller),
408 address: Some(hex::encode_prefixed(trace.address)),
409 value: quantity(trace.value),
410 init_code: hex::encode_prefixed(&trace.data),
411 gas_limit: trace.gas_limit,
412 gas_used: Some(trace.gas_used),
413 output: Some(hex::encode_prefixed(&trace.output)),
414 success: Some(trace.success),
415 error,
416 code_hash,
417 });
418 } else {
419 let to = if trace.kind.is_delegate() { trace.caller } else { trace.address };
421 call = Some(self.calls.len());
422 self.calls.push(ExecutionCall {
423 id: self.calls.len(),
424 parent_id: parent,
425 depth,
426 entry_step,
427 exit_step: None,
428 call_type: trace.kind.to_string(),
429 from: hex::encode_prefixed(trace.caller),
430 to: hex::encode_prefixed(to),
431 bytecode_address: hex::encode_prefixed(trace.address),
432 value: quantity(trace.value),
433 input: hex::encode_prefixed(&trace.data),
434 gas_limit: trace.gas_limit,
435 gas_used: Some(trace.gas_used),
436 output: Some(hex::encode_prefixed(&trace.output)),
437 success: Some(trace.success),
438 error,
439 code_hash,
440 });
441 }
442 (creation, call)
443 }
444
445 fn close_frame(
453 &mut self,
454 creation: Option<usize>,
455 call: Option<usize>,
456 exit_step: usize,
457 runs_steps: bool,
458 ) {
459 let (entry, exit) = if let Some(id) = creation {
460 let creation = &mut self.creations[id];
461 (&mut creation.entry_step, &mut creation.exit_step)
462 } else if let Some(id) = call {
463 let call = &mut self.calls[id];
464 (&mut call.entry_step, &mut call.exit_step)
465 } else {
466 return;
467 };
468 if !runs_steps && entry.is_some_and(|entry| entry < exit_step) {
469 *entry = None;
470 }
471 *exit = Some(exit_step);
472 }
473
474 fn push_step(&mut self, step: &CallTraceStep, next: Option<&CallTraceStep>, depth: u64) {
476 let stack = step.stack.as_deref().unwrap_or_default();
477 let memory = step.memory.as_ref().map(|memory| memory.as_bytes().0.clone());
480 let loaded = next.and_then(|next| next.stack.as_deref()?.last().copied());
483 let had_value = step
484 .storage_change
485 .as_ref()
486 .filter(|_| step.op == OpCode::SSTORE)
487 .and_then(|change| change.had_value);
488 let storage = self.converter.storage(step.op.get(), stack, loaded, had_value);
489 let return_data = self.converter.return_data(&step.returndata);
492 self.steps.append(
493 StepRecord {
494 pc: step.pc as u64,
495 op: step.op.get(),
496 gas: step.gas_remaining,
497 gas_cost: step.gas_cost,
498 depth,
499 error: status_error(step.status),
500 memory,
501 storage: Some(storage.storage),
502 storage_diff: storage.storage_diff,
503 transient_storage: storage.transient_storage,
504 return_data,
505 },
506 stack.iter().map(|word| EvmWord(word.to_be_bytes())),
507 );
508 }
509}
510
511fn recorded_steps(recordings: &[DebugRecording]) -> Result<(StepTable, Vec<usize>)> {
517 let first = &recordings[0].sink;
518 let mut offsets = Vec::with_capacity(recordings.len());
519 let mut next = 0;
520 for recording in recordings {
521 if !recording.sink.same(first)
522 || (!recording.steps.is_empty() && recording.steps.start != next)
523 {
524 offsets.clear();
525 break;
526 }
527 offsets.push(next);
528 next = recording.steps.end.max(next);
529 }
530 let mut shared = first.lock();
531 let len = shared.as_ref().ok_or_eyre("the recorded steps are in use")?.len();
532 if offsets.len() == recordings.len() && next == len {
533 return Ok((shared.take().unwrap_or_default(), offsets));
534 }
535 drop(shared);
536
537 offsets.clear();
538 let mut table = StepTable::with_capacity(recordings.iter().map(|r| r.steps.len()).sum());
539 for recording in recordings {
540 offsets.push(table.len());
541 let source = recording.sink.lock();
542 let source = source.as_ref().ok_or_eyre("the recorded steps are in use")?;
543 for index in recording.steps.clone() {
544 let step = source.step(index);
545 table.append(step_record(&step), step.stack().iter());
546 }
547 }
548 Ok((table, offsets))
549}
550
551struct ExecutedProgram<'a> {
553 address: Address,
554 name: &'a str,
555 code: &'a Bytes,
556 code_hash: B256,
558 deployed_hash: B256,
561 init: bool,
563 artifact: &'a ArtifactData,
564 solc: bool,
566 source_map: &'a SourceMap,
567 pc_ic_map: Option<&'a PcIcMap>,
568 build_sources: &'a HashMap<u32, Arc<SourceData>>,
570 storage_layout: Option<Value>,
572}
573
574fn executed_programs<'a>(
576 arenas: &'a [CallTraceArena],
577 contract_names: &'a [Vec<Option<String>>],
578 sources: &'a ContractSources,
579 known_contracts: &ContractsByArtifact,
580) -> Vec<ExecutedProgram<'a>> {
581 let mut seen = HashSet::<(Address, bool, B256)>::default();
582 let mut programs = Vec::new();
583 for (node, name) in
584 arenas.iter().zip(contract_names).flat_map(|(arena, names)| arena.nodes().iter().zip(names))
585 {
586 let trace = &node.trace;
587 let init = trace.kind.is_any_create();
588 if let Some(name) = name
589 && let Some(code) = &trace.bytecode
590 && let code_hash = keccak256(code)
591 && seen.insert((trace.address, init, code_hash))
592 && let Some(sources_for_name) = sources.get_sources(name)
593 && let Some((artifact, source)) = sources_for_name.into_iter().find(|(artifact, _)| {
594 if init {
595 artifact.source_map.is_some()
596 } else {
597 artifact.source_map_runtime.is_some()
598 }
599 })
600 && let Some(build_sources) = sources.sources_by_id.get(&artifact.build_id)
601 {
602 let (source_map, pc_ic_map) = if init {
603 (artifact.source_map.as_ref(), artifact.pc_ic_map.as_ref())
604 } else {
605 (artifact.source_map_runtime.as_ref(), artifact.pc_ic_map_runtime.as_ref())
606 };
607 let Some(source_map) = source_map else { continue };
608 let storage_layout = known_contracts
609 .find_by_name_or_identifier(name)
610 .ok()
611 .flatten()
612 .and_then(|(_, contract)| contract.storage_layout.as_deref())
613 .and_then(|layout| serde_json::to_value(layout).ok());
614 programs.push(ExecutedProgram {
615 address: trace.address,
616 name,
617 code,
618 code_hash,
619 deployed_hash: if init { keccak256(&trace.output) } else { code_hash },
620 init,
621 artifact,
622 solc: matches!(source.language, MultiCompilerLanguage::Solc(_)),
623 source_map,
624 pc_ic_map,
625 build_sources,
626 storage_layout,
627 });
628 }
629 }
630 programs
631}
632
633fn contract_debug_info(
635 program: &ExecutedProgram<'_>,
636 source_cache: &mut SourceCache,
637) -> Option<ContractDebugInfo> {
638 let mut instructions = Vec::new();
639 let mut used_sources = BTreeSet::new();
640 let mut pc = 0;
641 while let Some(&byte) = program.code.get(pc) {
642 let op = OpCode::new(byte);
643 let index = if program.solc {
644 program.pc_ic_map.and_then(|map| map.get(pc as u32))
645 } else {
646 Some(pc as u32)
647 };
648 if let Some(element) = index.and_then(|index| program.source_map.get(index as usize)) {
649 let context = instruction_context(element, program.build_sources, &mut used_sources);
650 instructions.extend(Instruction::from_bytecode(program.code, pc, context));
651 }
652 pc += 1 + op.map_or(0, |op| op.info().immediate_size() as usize);
653 }
654 if instructions.is_empty() {
655 return None;
656 }
657
658 let used_sources = used_sources
659 .into_iter()
660 .filter_map(|id| program.build_sources.get(&id).map(|source| (u64::from(id), source)))
661 .collect::<Vec<_>>();
662 let info = EthdebugInfo {
663 compilation: Value::Null,
664 contract_name: program.name.to_string(),
665 environment: if program.init { "create" } else { "call" }.to_string(),
666 instructions,
667 sources: used_sources
668 .iter()
669 .map(|(id, source)| (*id, source.path.to_string_lossy().into_owned()))
670 .collect(),
671 variable_locations: BTreeMap::new(),
672 };
673 let source_contents =
674 used_sources.iter().map(|(id, source)| (*id, source.source.to_string())).collect();
675 let code_generator = program
677 .artifact
678 .via_ir
679 .filter(|_| program.solc)
680 .map(|via_ir| if via_ir { CodeGenerator::ViaIr } else { CodeGenerator::Legacy });
681 let storage_layout =
682 program.storage_layout.as_ref().and_then(|layout| StorageLayout::parse(layout).ok());
683 Some(
684 ContractDebugInfo::with_source_cache(
685 Some(&hex::encode_prefixed(program.address)),
686 program.name,
687 info,
688 source_contents,
689 source_cache,
690 )
691 .with_code_generator(code_generator)
692 .with_code_hash(Some(&program.code_hash.to_string()))
693 .with_storage_layout(storage_layout),
694 )
695}
696
697pub fn ensure_dump_dir(dir: &Path) -> Result<()> {
699 if dir.exists() && !dir.is_dir() {
702 eyre::bail!(
703 "--dump now takes a directory, but {} is not one; remove it or pass a directory path",
704 dir.display()
705 );
706 }
707 if std::fs::read_dir(dir).is_ok_and(|mut entries| entries.next().is_some()) {
711 eyre::bail!(
712 "cannot write the SolDB bundle to {}: the directory is not empty",
713 dir.display()
714 );
715 }
716 Ok(())
717}
718
719pub(crate) fn write_bundle(
726 dir: &Path,
727 mut arenas: Vec<CallTraceArena>,
728 recordings: Vec<DebugRecording>,
729 contract_names: &[Vec<Option<String>>],
730 sources: &ContractSources,
731 known_contracts: &ContractsByArtifact,
732) -> Result<()> {
733 ensure_dump_dir(dir)?;
734 let mut contracts = BTreeMap::<(Address, B256), CombinedJson>::new();
736 let mut written_sources = HashSet::<PathBuf>::default();
737 for program in executed_programs(&arenas, contract_names, sources, known_contracts) {
738 if !program.solc {
740 continue;
741 }
742 let contract =
743 contracts.entry((program.address, program.deployed_hash)).or_insert_with(|| {
744 let path = |id: &u32| {
745 program.build_sources.get(id).map(|source| source.path.to_string_lossy())
746 };
747 let max_id = program.build_sources.keys().max().copied().unwrap_or_default();
748 CombinedJson {
749 name: program.name.to_string(),
750 key: format!(
751 "{}:{}",
752 path(&program.artifact.file_id).unwrap_or_default(),
753 program.name
754 ),
755 source_list: (0..=max_id)
757 .map(|id| path(&id).map_or_else(|| format!("<missing-{id}>"), Into::into))
758 .collect(),
759 fields: Map::new(),
760 }
761 });
762 let (source_map_key, bytecode_key) =
763 if program.init { ("srcmap", "bin") } else { ("srcmap-runtime", "bin-runtime") };
764 let source_map = program
765 .source_map
766 .iter()
767 .map(|element| {
768 format!(
769 "{}:{}:{}:{}:{}",
770 element.offset(),
771 element.length(),
772 element.index_i32(),
773 element.jump().to_str(),
774 element.modifier_depth()
775 )
776 })
777 .collect::<Vec<_>>()
778 .join(";");
779 contract.fields.insert(source_map_key.to_string(), source_map.into());
780 contract.fields.insert(bytecode_key.to_string(), hex::encode(program.code).into());
781 if let Some(layout) = &program.storage_layout {
782 contract.fields.insert("storage-layout".to_string(), layout.clone());
783 }
784
785 for source in program.build_sources.values() {
786 let relative = source.path.is_relative()
788 && source
789 .path
790 .components()
791 .all(|component| matches!(component, Component::Normal(_)));
792 if relative && written_sources.insert(source.path.clone()) {
793 let path = dir.join(&source.path);
794 if let Some(parent) = path.parent() {
795 fs::create_dir_all(parent)?;
796 }
797 fs::write(path, source.source.as_bytes())?;
798 }
799 }
800 }
801
802 let mut programs_at = HashMap::<Address, usize>::new();
803 for (address, _) in contracts.keys() {
804 *programs_at.entry(*address).or_default() += 1;
805 }
806 let mut mapping = Vec::new();
807 for ((address, code_hash), contract) in contracts {
808 let debug_dir = if programs_at[&address] > 1 {
809 format!("{}-{}", hex::encode_prefixed(address), hex::encode(&code_hash[..4]))
810 } else {
811 hex::encode_prefixed(address)
812 };
813 fs::create_dir_all(dir.join(&debug_dir))?;
814 write_json_file(
815 &dir.join(&debug_dir).join("combined.json"),
816 &json!({
817 "sourceList": contract.source_list,
818 "contracts": { contract.key: contract.fields },
819 }),
820 )?;
821 mapping.push(json!({
822 "address": hex::encode_prefixed(address),
823 "name": contract.name,
824 "debug_dir": debug_dir,
825 "code_hash": code_hash.to_string(),
826 }));
827 }
828 write_json_file(&dir.join("contracts.json"), &json!({ "contracts": mapping }))?;
829 let (trace, _) = transaction_trace(&mut arenas, recordings, &Breakpoints::default())?;
830 write_json_file(&dir.join("trace.json"), &trace)?;
831 Ok(())
832}
833
834struct CombinedJson {
836 name: String,
837 key: String,
839 source_list: Vec<String>,
840 fields: Map<String, Value>,
842}
843
844fn instruction_context(
847 element: &SourceElement,
848 build_sources: &HashMap<u32, Arc<SourceData>>,
849 used_sources: &mut BTreeSet<u32>,
850) -> SourceMapContext {
851 let code = element.index().filter(|index| build_sources.contains_key(index)).map(|index| {
853 used_sources.insert(index);
854 SourceLocation {
855 source_id: u64::from(index),
856 offset: u64::from(element.offset()),
857 length: u64::from(element.length()),
858 }
859 });
860 SourceMapContext {
861 code,
862 jump: match element.jump() {
863 Jump::In => SourceMapJump::Into,
864 Jump::Out => SourceMapJump::Out,
865 Jump::Regular => SourceMapJump::Regular,
866 },
867 modifier_depth: element.modifier_depth().into(),
868 }
869}
870
871fn status_error(status: Option<InstrStop>) -> Option<String> {
873 status.filter(|status| !status.is_success()).map(|status| format!("{status:?}"))
874}
875
876#[cfg(test)]
877mod tests {
878 use super::*;
879 use alloy_primitives::U256;
880 use foundry_compilers::artifacts::sourcemap;
881 use foundry_evm_traces::CallKind;
882 use soldb_ethdebug::SourceMapEnvironment;
883
884 fn step(pc: usize, op: OpCode, stack: &[u64]) -> CallTraceStep {
886 CallTraceStep {
887 pc,
888 op,
889 stack: Some(stack.iter().map(|word| U256::from(*word)).collect()),
890 push_stack: None,
891 memory: None,
892 returndata: Bytes::new(),
893 gas_remaining: 0,
894 gas_refund_counter: 0,
895 gas_cost: 0,
896 state_gas_cost: None,
897 state_gas_reservoir: None,
898 state_gas_spent: 0,
899 storage_change: None,
900 status: (op == OpCode::STOP).then_some(InstrStop::Stop),
901 immediate_bytes: None,
902 decoded: None,
903 }
904 }
905
906 #[test]
907 fn converts_steps_calls_and_storage_in_execution_order() {
908 let (caller, proxy, implementation) =
909 (Address::repeat_byte(1), Address::repeat_byte(0xa), Address::repeat_byte(0xb));
910 let mut arena = CallTraceArena::default();
911 {
912 let root = &mut arena.nodes_mut()[0];
913 root.trace = CallTrace {
914 caller,
915 address: proxy,
916 kind: CallKind::Call,
917 success: true,
918 steps: vec![
919 step(0, OpCode::PUSH1, &[]),
920 step(2, OpCode::SLOAD, &[0]),
921 step(3, OpCode::DELEGATECALL, &[0x29]),
922 step(4, OpCode::STOP, &[]),
923 ],
924 ..Default::default()
925 };
926 root.children.push(1);
927 root.ordering = vec![
928 TraceMemberOrder::Step(0),
929 TraceMemberOrder::Step(1),
930 TraceMemberOrder::Step(2),
931 TraceMemberOrder::Call(0),
932 TraceMemberOrder::Step(3),
933 ];
934 }
935 arena.nodes_mut().push(CallTraceNode {
937 parent: Some(0),
938 idx: 1,
939 trace: CallTrace {
940 caller: proxy,
941 address: implementation,
942 kind: CallKind::DelegateCall,
943 depth: 1,
944 success: true,
945 steps: vec![step(0, OpCode::SSTORE, &[0x2a, 0]), step(1, OpCode::STOP, &[])],
946 ..Default::default()
947 },
948 ordering: vec![TraceMemberOrder::Step(0), TraceMemberOrder::Step(1)],
949 ..Default::default()
950 });
951
952 let breakpoints = Breakpoints::from_iter([('a', (proxy, 3)), ('b', (implementation, 9))]);
953 let (trace, breakpoints) =
954 transaction_trace(&mut [arena], Vec::new(), &breakpoints).unwrap();
955 assert_eq!(
956 breakpoints,
957 BTreeMap::from([((proxy, 3), vec![(0..6, 1)]), ((implementation, 9), Vec::new())])
958 );
959
960 let steps = trace
961 .steps
962 .iter()
963 .map(|step| (step.pc(), step.mnemonic().to_string(), step.depth()))
964 .collect::<Vec<_>>();
965 assert_eq!(
966 steps,
967 [
968 (0, "PUSH1".to_string(), 1),
969 (2, "SLOAD".to_string(), 1),
970 (3, "DELEGATECALL".to_string(), 1),
971 (0, "SSTORE".to_string(), 2),
972 (1, "STOP".to_string(), 2),
973 (4, "STOP".to_string(), 1),
974 ]
975 );
976 let storage_diff =
977 |index: usize| serde_json::to_value(trace.steps.step(index).storage_diff()).unwrap();
978 assert_eq!(storage_diff(1), json!({ "0x0": { "before": null, "after": "0x29" } }));
979 assert_eq!(storage_diff(3), json!({ "0x0": { "before": null, "after": "0x2a" } }));
980 assert_eq!(storage_diff(4), json!({}));
981
982 let calls = trace
983 .artifacts
984 .calls
985 .iter()
986 .map(|call| {
987 (
988 call.parent_id,
989 call.entry_step,
990 call.exit_step,
991 call.call_type.as_str(),
992 call.to.as_str(),
993 call.bytecode_address.as_str(),
994 )
995 })
996 .collect::<Vec<_>>();
997 let (proxy, implementation) =
998 (hex::encode_prefixed(proxy), hex::encode_prefixed(implementation));
999 assert_eq!(
1000 calls,
1001 [
1002 (None, Some(0), Some(6), "CALL", proxy.as_str(), proxy.as_str()),
1003 (
1004 Some(0),
1005 Some(3),
1006 Some(5),
1007 "DELEGATECALL",
1008 proxy.as_str(),
1009 implementation.as_str()
1010 ),
1011 ]
1012 );
1013 assert_eq!(trace.to_addr.as_deref(), Some(proxy.as_str()));
1014 assert_eq!(trace.from_addr, hex::encode_prefixed(caller));
1015 }
1016
1017 fn executed_c() -> (ContractSources, CallTraceArena, Vec<Option<String>>) {
1020 const CODE: [u8; 4] = [0x60, 0x80, 0x5b, 0x00];
1021 let mut sources = ContractSources::default();
1022 sources.sources_by_id.entry("build".to_string()).or_default().insert(
1023 0,
1024 Arc::new(SourceData {
1025 source: Arc::new("contract C {}".to_string()),
1026 language: Default::default(),
1027 path: PathBuf::from("src/C.sol"),
1028 contract_definitions: Vec::new(),
1029 }),
1030 );
1031 sources.artifacts_by_name.insert(
1032 "C".to_string(),
1033 vec![ArtifactData {
1034 source_map: None,
1035 source_map_runtime: Some(sourcemap::parse("0:8:0:-;9:3:0:i;1:2:1:o").unwrap()),
1036 pc_ic_map: None,
1037 pc_ic_map_runtime: Some(PcIcMap::new(&CODE)),
1038 build_id: "build".to_string(),
1039 file_id: 0,
1040 via_ir: Some(false),
1041 }],
1042 );
1043 let mut arena = CallTraceArena::default();
1044 let root = &mut arena.nodes_mut()[0].trace;
1045 root.address = Address::repeat_byte(0xc);
1046 root.bytecode = Some(Bytes::from_static(&CODE));
1047 root.steps = vec![step(0, OpCode::PUSH1, &[]), step(2, OpCode::JUMPDEST, &[0x80])];
1048 arena.nodes_mut()[0].ordering = vec![TraceMemberOrder::Step(0), TraceMemberOrder::Step(1)];
1049 (sources, arena, vec![Some("C".to_string())])
1050 }
1051
1052 #[test]
1053 fn adapts_source_maps_to_ethdebug_instructions() {
1054 let (sources, arena, names) = executed_c();
1055 let address = Address::repeat_byte(0xc);
1056
1057 let arenas = [arena];
1058 let names = [names];
1059 let programs = executed_programs(&arenas, &names, &sources, &Default::default());
1060 let contract = contract_debug_info(&programs[0], &mut SourceCache::default()).unwrap();
1061
1062 assert_eq!(contract.address, Some(hex::encode_prefixed(address)));
1063 assert_eq!(contract.code_generator, Some(CodeGenerator::Legacy));
1064 assert_eq!(contract.info.environment, "call");
1065 assert_eq!(contract.info.sources, BTreeMap::from([(0, "src/C.sol".to_string())]));
1066 let instructions = contract
1067 .info
1068 .instructions
1069 .iter()
1070 .map(|instruction| {
1071 json!({
1072 "offset": instruction.offset,
1073 "mnemonic": instruction.mnemonic(),
1074 "arguments": instruction.arguments(),
1075 "context": serde_json::to_value(instruction).unwrap()["context"],
1076 })
1077 })
1078 .collect::<Vec<_>>();
1079 assert_eq!(
1080 Value::Array(instructions),
1081 json!([
1082 {
1083 "offset": 0,
1084 "mnemonic": "PUSH1",
1085 "arguments": ["0x80"],
1086 "context": {
1087 "modifierDepth": 0,
1088 "code": { "source": { "id": 0 }, "range": { "offset": 0, "length": 8 } },
1089 },
1090 },
1091 {
1092 "offset": 2,
1093 "mnemonic": "JUMPDEST",
1094 "arguments": [],
1095 "context": {
1096 "modifierDepth": 0,
1097 "code": { "source": { "id": 0 }, "range": { "offset": 9, "length": 3 } },
1098 "invoke": {},
1099 },
1100 },
1101 {
1102 "offset": 3,
1103 "mnemonic": "STOP",
1104 "arguments": [],
1105 "context": { "modifierDepth": 0, "return": {} },
1106 },
1107 ])
1108 );
1109 }
1110
1111 #[test]
1112 fn keeps_all_root_calls_and_breakpoints() {
1113 let (_, mut deployment, _) = executed_c();
1114 deployment.nodes_mut()[0].trace.kind = CallKind::Create;
1115 deployment.nodes_mut()[0].trace.gas_used = 10;
1116 deployment.nodes_mut()[0].trace.success = true;
1117 let (_, mut set_up, _) = executed_c();
1118 set_up.nodes_mut()[0].trace.gas_used = 20;
1119 set_up.nodes_mut()[0].trace.success = true;
1120 let (_, mut test, _) = executed_c();
1121 test.nodes_mut()[0].trace.gas_used = 30;
1122 test.nodes_mut()[0].trace.status = Some(InstrStop::Revert);
1123 let breakpoints = Breakpoints::from_iter([('a', (Address::repeat_byte(0xc), 2))]);
1124 let (trace, hits) =
1125 transaction_trace(&mut [deployment, set_up, test], Vec::new(), &breakpoints).unwrap();
1126 soldb_debugger::check_root_calls(&trace).unwrap();
1127 assert_eq!(trace.gas_used, 60);
1128 assert_eq!(trace.to_addr, Some(hex::encode_prefixed(Address::repeat_byte(0xc))));
1130 assert_eq!(trace.contract_address, None);
1131 assert!(!trace.success);
1132 assert_eq!(trace.error.as_deref(), Some("Revert"));
1133 assert_eq!(trace.steps.len(), 6);
1134 assert_eq!(trace.artifacts.creations[0].entry_step, Some(0));
1135 assert_eq!(trace.artifacts.creations[0].exit_step, Some(2));
1136 assert_eq!(trace.artifacts.calls[0].entry_step, Some(2));
1137 assert_eq!(trace.artifacts.calls[1].entry_step, Some(4));
1138 assert_eq!(trace.artifacts.calls[1].exit_step, Some(6));
1139 assert!(trace.artifacts.calls.iter().all(|call| call.parent_id.is_none()));
1140 assert_eq!(hits[&(Address::repeat_byte(0xc), 2)], [(0..2, 1), (2..4, 1), (4..6, 1)]);
1141 assert!(transaction_trace(&mut [], Vec::new(), &Breakpoints::default()).is_err());
1142 }
1143
1144 #[test]
1145 fn records_transient_storage_and_return_data() {
1146 let mut builder = TraceBuilder::default();
1147 let store = step(0, OpCode::TSTORE, &[42, 7]);
1148 let load = step(1, OpCode::TLOAD, &[7]);
1149 let mut stop = step(2, OpCode::STOP, &[42]);
1150 stop.returndata = Bytes::from_static(&[0xab, 0xcd]);
1151 builder.push_step(&store, Some(&load), 1);
1152 builder.push_step(&load, Some(&stop), 1);
1153 builder.push_step(&stop, None, 1);
1154 builder.push_step(&stop, None, 1);
1155 builder.push_step(&store, None, 1);
1156 let expected = BTreeMap::from([("0x7".to_string(), "0x2a".to_string())]);
1157 assert_eq!(*builder.steps.step(0).transient_storage(), expected);
1158 assert_eq!(*builder.steps.step(1).transient_storage(), expected);
1159 assert!(builder.steps.step(2).transient_storage().is_empty());
1160 assert!(builder.steps.step(0).return_data().is_none());
1161 assert_eq!(builder.steps.step(2).return_data(), Some("abcd"));
1162 assert!(builder.steps.step(4).return_data().is_none());
1163 assert_eq!(
1164 builder.steps.step(2).return_data().unwrap().as_ptr(),
1165 builder.steps.step(3).return_data().unwrap().as_ptr(),
1166 );
1167 }
1168
1169 #[test]
1170 fn writes_a_bundle_soldb_loads() {
1171 let (sources, arena, names) = executed_c();
1172 let dir = tempfile::tempdir().unwrap();
1173
1174 write_bundle(dir.path(), vec![arena], Vec::new(), &[names], &sources, &Default::default())
1175 .unwrap();
1176
1177 let address = hex::encode_prefixed(Address::repeat_byte(0xc));
1178 let mapping = soldb_ethdebug::read_json_file(&dir.path().join("contracts.json")).unwrap();
1179 let code_hash = keccak256([0x60, 0x80, 0x5b, 0x00]).to_string();
1180 assert_eq!(
1181 mapping,
1182 json!({ "contracts": [{
1183 "address": address,
1184 "name": "C",
1185 "debug_dir": address,
1186 "code_hash": code_hash,
1187 }] })
1188 );
1189 let program = soldb_ethdebug::load_debug_program_with_sources(
1190 &dir.path().join(&address),
1191 "C",
1192 SourceMapEnvironment::Runtime,
1193 &[],
1194 )
1195 .unwrap()
1196 .unwrap();
1197 assert!(program.legacy);
1198 assert!(program.missing_sources.is_empty());
1199 assert_eq!(program.source_contents, BTreeMap::from([(0, "contract C {}".to_string())]));
1200 let offsets = program.info.instructions.iter().map(|i| i.offset).collect::<Vec<_>>();
1201 assert_eq!(offsets, [0, 2, 3]);
1202 let trace = std::fs::read_to_string(dir.path().join("trace.json")).unwrap();
1203 let trace = serde_json::from_str::<TransactionTrace>(&trace).unwrap();
1204 assert_eq!(trace.steps.len(), 2);
1205
1206 let (sources, arena, names) = executed_c();
1208 let error = write_bundle(
1209 dir.path(),
1210 vec![arena],
1211 Vec::new(),
1212 &[names],
1213 &sources,
1214 &Default::default(),
1215 )
1216 .unwrap_err();
1217 assert!(error.to_string().ends_with("the directory is not empty"));
1218 }
1219}