hello_wasm.debug.json

Overview

The hello_wasm.debug.json file is a debug information mapping artifact that associates offsets in the compiled WebAssembly (WASM) bytecode with corresponding source code locations in Solidity (hello_wasm.sol) and the WASM code files (hello_wasm.code). This mapping facilitates debugging by enabling precise source-level traceability during execution or analysis of the compiled contract.

The file contains a JSON structure where keys are cryptographic hash identifiers (likely representing compilation units, functions, or code segments), and values are objects mapping bytecode offsets (expressed as numbers) to source file and line number pairs. This allows tools to resolve runtime addresses back to source lines.

Structure and Contents

• Top-level keys: Unique hashes (e.g., "08899a87a7d1a079a87cb156204b3332ae7eac0fabdee2cf4bbe36293199c417") representing code segments or compilation units.

• Offset keys: Numerical offsets (e.g., "0", "16", "24", ...) within the compiled code segment.

• Mapping values: Objects containing:

  • "filename": The source file name (either hello_wasm.sol for Solidity or hello_wasm.code for WASM code).

  • "line": The line number in the source file corresponding to that offset.

Purpose of Mappings

• Provides correlation between bytecode offsets and source code for debugging.

• Supports breakpoints, stack traces, and variable inspection by debuggers.

• Allows tracing execution flow back to original Solidity code lines or WASM code lines.

Key Files Mapped

• hello_wasm.sol: Solidity source file containing the contract or library code.

• hello_wasm.code: WASM compiled code corresponding to the Solidity source, likely in a textual or annotated format.

Usage

This file is used primarily by debugging tools or development environments that support source-level debugging of WASM contracts compiled from Solidity. When an error or breakpoint occurs at a certain bytecode offset, this file enables the debugger to locate the exact line in the Solidity source or WASM code.

Example usage in a debugging session:

1. The debugger hits an instruction at offset 88 within the code segment identified by hash "08899a87a7d1a079a87cb156204b3332ae7eac0fabdee2cf4bbe36293199c417".

2. The debugger looks up this offset in the JSON file.

3. It finds the corresponding source location: hello_wasm.sol, line 81.

4. The debugger shows this source line to the developer for inspection.

Interaction with Other System Components

• Compiler: Generates this debug mapping during compilation of Solidity to WASM.

• Debugger/IDE: Consumes this file to provide source-level debugging features.

• Runtime Environment: Uses offsets in WASM execution to correlate runtime state with source code.

This file acts as a bridge between runtime bytecode and human-readable source code, enabling effective debugging and analysis workflows.

Important Implementation Details

• The file uses cryptographic hashes as keys for code segments, which could represent functions or sections.

• The offsets are bytecode instruction offsets in the WASM module.

• Multiple offsets often map to the same source line, reflecting multiple instructions generated from a single source line.

• The file includes mappings for both Solidity source and intermediate WASM textual code.

• Some entries show empty mappings, possibly placeholders or unused segments.

Visual Diagram of File Structure

flowchart TD
A[hello_wasm.debug.json]
A --> B[Code Segment Hashes]
B --> C1[Offset 0]
B --> C2[Offset 16]
B --> C3[Offset 24]
B --> Cn[...]
C1 --> D1{Source Mapping}
C2 --> D2{Source Mapping}
C3 --> D3{Source Mapping}
D1 --> E1[File: hello_wasm.sol]
D1 --> E2[Line: 76]
D2 --> F1[File: hello_wasm.sol]
D2 --> F2[Line: 81]
D3 --> G1[File: hello_wasm.code]
D3 --> G2[Line: 2]

Notes on Source Code Line Distribution

• Many offsets in the same segment map to a single source line (e.g., multiple offsets pointing to line 81 in hello_wasm.sol), indicating complex instruction generation from that line.

• WASM code lines range from low lines (1-20) to higher lines (500+), showing extensive code generation.

• Solidity source lines referenced span from early lines (23, 26, 31) to higher lines (240-250), showing the contract’s code coverage.

No direct functions or classes are defined in this JSON file since it serves purely as a mapping database rather than executable code.

For detailed understanding of the Solidity contract source at referenced lines, see Solidity Contract Source Overview. For WASM code structure and semantics, refer to WebAssembly Code Structure. Debugging process and tools are covered in Debugging WASM Contracts.