Crate soldb_debugger

Expand description

Source-level debugging over an execution trace.

Given a soldb_core::TransactionTrace and the ETHDebug metadata for the contract it executed, this crate answers the questions a source-level debugger asks: which source span a step is at, which function contains a program counter, and which variables are live there with what values.

It is frontend-agnostic on purpose. variables_for_step is what backs both the CLI REPL’s vars/print commands and the DAP server’s variables view, so the terminal and the editor decode identically.

Variable values are only as good as the debug info: a location the backend did not capture decodes to DebugValueStatus::Unavailable, and a value whose declared type is not decodable is reported as DebugValueStatus::Raw rather than guessed at.

Re-exports§

pub use condition::Condition;
pub use condition::ConditionContext;
pub use condition::Evaluation;
pub use debug_diff::capture_debug_trace;
pub use debug_diff::compare_debug_traces;
pub use debug_diff::DebugCheckpoint;
pub use debug_diff::DebugDiffMode;
pub use debug_diff::DebugDiffReport;
pub use debug_diff::DebugDifference;
pub use debug_diff::DebugDifferenceKind;
pub use debug_diff::DebugExecution;
pub use debug_diff::DebugTrace;
pub use debug_diff::DebugTraceEvent;
pub use debug_diff::DebugTraceSummary;
pub use state::short_hex;
pub use state::state_value;
pub use state::state_variables;
pub use state::CachedChain;
pub use state::ChainRead;
pub use state::ChainStorage;
pub use state::StateSource;
pub use state::StateVariable;
pub use state::StorageTape;
pub use state::StorageWords;
pub use stepping::address_from_word;
pub use stepping::call_target;
pub use stepping::normalize_address;
pub use stepping::source_path_matches;
pub use stepping::ContractDebugInfo;
pub use stepping::Frame;
pub use stepping::FunctionId;
pub use stepping::InferredVariable;
pub use stepping::JumpMarker;
pub use stepping::LineKey;
pub use stepping::LocalsStatus;
pub use stepping::ResolvedFunction;
pub use stepping::ResolvedLine;
pub use stepping::SourceCache;
pub use stepping::SourceListing;
pub use stepping::StepLocation;
pub use stepping::StepMap;
pub use stepping::VariableKind;
pub use stepping::INFERRED_LOCALS_NOTE;
pub use stepping::INFERRED_LOCALS_WARNING;

Modules§

condition: Conditions on a breakpoint: break TestContract.sol:30 if counter > 4.
debug_diff: Differential testing for the source-level debugging experience.
state: State variables at a step, read through the compiler’s storage layout.
stepping: Source-level stepping over a recorded trace.

Structs§

ByteRange: A half-open byte range in a source.
DebugLocation
DebugSession
DebugStep
DebugValue
DebugVariable
FrameArgument: One argument of a function frame, as it was on the stack when the frame was entered.
FrameState: What a frame’s arguments are read from: the stack at its entry point, and the memory a pointer among them refers into.
SourceFunction
SourceLocal: A variable a function declares in its source: a return parameter or a local.
SourceParam
SourceSpan
SourceTypes: The struct, enum, and user-defined value type declarations of a set of sources.
StorageLayout: The layout of one contract’s storage as solc emitted it.
StructMember: One member of a struct, in declaration order.

Enums§

ArgumentLayout: What this trace proved about how a contract’s compiler passes arguments.
ArgumentOrder: Where the compiler leaves a function’s parameters on the stack when the function is entered. Solidity’s two code generators disagree, and nothing in the artifacts says which produced the code, so StepMap proves it from the trace instead of assuming.
CodeGenerator: Which of solc’s code generators produced a program.
DebugValueStatus

Functions§

check_root_calls: Fails when two top-level calls start at one step, which no execution produces.
decode_arguments: The arguments a function was entered with, read off the stack at its entry point.
is_value_type: Whether a value of this type is one stack word the debugger can decode.
parse_source_functions: Finds every function-like declaration in a source file by scanning its text: functions, modifiers, constructors, fallback, and receive. This is what the debugger attributes steps to when the compiler emits no function boundaries.
variables_for_step