Skip to main content

foundry_debugger/
soldb.rs

1//! [soldb](https://github.com/walnuthq/soldb) frontend.
2//!
3//! Converts a recorded call trace into a soldb transaction trace and the local artifacts' source
4//! maps into soldb debug info, then runs a soldb session over them or writes them as a bundle that
5//! soldb's own tools read.
6
7use 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
44/// The frames that run a breakpoint location, as the steps they span and their depth.
45type BreakpointFrames = Vec<(Range<usize>, u64)>;
46
47/// The frames that run each breakpoint's code address and program counter.
48type BreakpointSteps = BTreeMap<(Address, usize), BreakpointFrames>;
49
50/// A soldb session over the recorded call traces.
51#[derive(Debug)]
52pub(crate) struct SoldbDebugger {
53    trace: TransactionTrace,
54    contracts: Vec<ContractDebugInfo>,
55    /// The program counter of each `vm.breakpoint` location and the frames that run it.
56    breakpoints: Vec<(u64, BreakpointFrames)>,
57}
58
59impl SoldbDebugger {
60    /// Converts `arenas`, whose node contracts are identified by `contract_names`.
61    ///
62    /// The steps are the ones `recordings` hold, one per arena, or the arenas' own steps when
63    /// `recordings` is empty.
64    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    /// Runs the session.
87    ///
88    /// If the full-screen view can run, it opens first. Then commands are read from stdin, one per
89    /// line, until `quit` or the end of the input, with a prompt if stdin is a terminal.
90    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        // soldb breakpoints match a program counter in any contract, so each one is limited to
94        // the own steps of the frames that run the `vm.breakpoint` location: the steps they span
95        // at their depth, which leaves out their subcalls.
96        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        // The prompt goes to stderr, so it shows even when stdout is piped.
109        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/// What the session asks the frontend to do after a command.
141#[derive(Clone, Copy, Debug, PartialEq, Eq)]
142enum Flow {
143    Continue,
144    Tui,
145    Quit,
146}
147
148/// Prints the session's answers.
149fn 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
162/// Opens the full-screen view until the user leaves it.
163fn 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
179/// Converts `arenas` into a soldb trace: their steps in execution order, with each call and
180/// creation recorded at the steps it spans.
181///
182/// The steps are the ones `recordings` hold, one per arena, or the arenas' own steps when
183/// `recordings` is empty. Also returns the steps that run each `breakpoints` location. The steps
184/// move out of `arenas`, so each one is dropped once converted.
185fn 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    // The arenas run in order, such as the deployment, the setup, and the test, so the last one
225    // is the call being debugged.
226    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/// Collects the soldb steps, calls, and creations of a trace in execution order.
262#[derive(Default)]
263struct TraceBuilder {
264    steps: StepTable,
265    calls: Vec<ExecutionCall>,
266    creations: Vec<ContractCreation>,
267    /// Converts the return data and storage of the steps.
268    converter: StepConverter,
269    /// The frames that run each `vm.breakpoint` location, as code address and program counter.
270    breakpoints: BreakpointSteps,
271}
272
273impl TraceBuilder {
274    /// Records node `idx` and its subcalls. `parent` is the id of the enclosing call.
275    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        // The ordering lists the steps in recording order.
288        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                        // Free the converted snapshots now, not when the frame ends.
303                        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    /// Records node `idx` and its subcalls, whose steps `frames` locate in the step table from
320    /// `offset`. `parent` is the id of the enclosing call.
321    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        // The frame's own steps are the ones between its subcalls.
337        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    /// Adds the program counters of the `steps` that run a breakpoint location of `address` to
360    /// `hits`.
361    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    /// Records that the frame of `address` that spans `steps` at `depth` runs the breakpoint
374    /// locations at the program counters `hits`.
375    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    /// Records the call or creation `trace` that starts at `entry_step`, and returns its
384    /// creation or call id.
385    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        // The code the frame runs, as `executed_programs` hashes it, so each frame maps through
395        // its own program when several run at one address.
396        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            // A delegated call runs `address`'s code against the storage of `caller`.
420            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    /// Records that the creation or call that `open_frame` returned ends before `exit_step`, and
446    /// whether it `runs_steps` of its own.
447    ///
448    /// SolDB finds the frame that runs a step by the step it was entered at. A frame that runs no
449    /// step of its own but whose subcalls do, such as `vm.deployCode` around the creation it
450    /// makes, would share its entry step with its first subcall and take the subcall's steps, so
451    /// it records no entry step.
452    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    /// Records `step`. `next` is the following step of the same frame, if any.
475    fn push_step(&mut self, step: &CallTraceStep, next: Option<&CallTraceStep>, depth: u64) {
476        let stack = step.stack.as_deref().unwrap_or_default();
477        // The tracer shares one buffer between steps that leave memory unchanged, so this only
478        // bumps a reference count.
479        let memory = step.memory.as_ref().map(|memory| memory.as_bytes().0.clone());
480        // The full stack snapshots do not record pushes, but an `SLOAD` or `TLOAD` leaves its
481        // value on top of the next step's stack.
482        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        // The converter spells out the buffer of the first step and of every change, including
490        // to an empty one; `None` keeps the previous step's.
491        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
511/// The step table that holds the steps of `recordings`, and where each recording's steps start in
512/// it.
513///
514/// The recorders of one session append to one table in execution order, so it is taken as it is
515/// when the recordings cover it in order. Otherwise their steps are copied into a new table.
516fn 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
551/// A program the trace executes and the local artifact that describes it.
552struct ExecutedProgram<'a> {
553    address: Address,
554    name: &'a str,
555    code: &'a Bytes,
556    /// The hash of `code`, which tells apart programs run at one address.
557    code_hash: B256,
558    /// The hash of the deployed code: `code_hash` for deployed code, and for creation code the
559    /// hash of the code it returned, so a contract's two programs share a bundle entry.
560    deployed_hash: B256,
561    /// Whether the program is creation code.
562    init: bool,
563    artifact: &'a ArtifactData,
564    /// Solc indexes source maps by instruction counter, but Vyper indexes by program counter.
565    solc: bool,
566    source_map: &'a SourceMap,
567    pc_ic_map: Option<&'a PcIcMap>,
568    /// The sources of the build that compiled the program, by source id.
569    build_sources: &'a HashMap<u32, Arc<SourceData>>,
570    /// The contract's storage layout, as solc writes it.
571    storage_layout: Option<Value>,
572}
573
574/// The programs `arenas` run that local artifacts describe, once per address and environment.
575fn 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
633/// Adapts the source map of `program` to its instructions, in the ETHDebug shape soldb reads.
634fn 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    // The code generator decides whether soldb can infer local variables from the stack.
676    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
697/// Checks that a SolDB bundle can be written to `dir`, before the run that records it.
698pub fn ensure_dump_dir(dir: &Path) -> Result<()> {
699    // Before 1.9, `--dump` wrote a single file, which a later run would otherwise fail on only
700    // after recording the trace.
701    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    // The bundle copies the compiler's sources under their project paths, and they can differ
708    // from the files on disk, so a directory with files, such as the project root, could have its
709    // files replaced.
710    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
719/// Writes a bundle that soldb's own tools read, for example
720/// `soldb profile --trace-file <dir>/trace.json --contracts <dir>/contracts.json`.
721///
722/// The bundle holds the transaction trace, a contracts mapping, one `combined.json` per contract
723/// address with the legacy source maps and bytecode `solc --combined-json` writes, and the sources
724/// under their project paths, where soldb looks for them.
725pub(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    // One entry per deployed code, so code replaced at an address keeps its own source maps.
735    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        // soldb reads legacy source maps by instruction counter, which Vyper's are not.
739        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                    // Ids without a build source stay unreadable placeholders.
756                    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            // Only project-relative paths are copied, so nothing is written outside `dir`.
787            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
834/// One contract of a bundle's `combined.json`.
835struct CombinedJson {
836    name: String,
837    /// The contract's key, `<source path>:<name>`.
838    key: String,
839    source_list: Vec<String>,
840    /// The source maps, bytecode, and storage layout, under solc's field names.
841    fields: Map<String, Value>,
842}
843
844/// The ETHDebug context of one source map element: its source range, if the build has the
845/// source, and the `invoke` or `return` marker of a jump into or out of a function.
846fn instruction_context(
847    element: &SourceElement,
848    build_sources: &HashMap<u32, Arc<SourceData>>,
849    used_sources: &mut BTreeSet<u32>,
850) -> SourceMapContext {
851    // Compiler-generated code points at sources that are not in the build.
852    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
871/// The error a failed step or call ended with.
872fn 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    /// A step as debug mode records it: the full stack, without pushes.
885    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        // A delegated call records the storage context as its caller.
936        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    /// `PUSH1 0x80; JUMPDEST; STOP` as contract `C` at `0x0c..0c`. The last source map element
1018    /// points at a generated source.
1019    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        // The header describes the test call, not the deployment.
1129        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        // A second bundle would replace the files of the first, as it would a project's sources.
1207        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}