Skip to content

source-mapping.md

Latest commit

 

History

History
100 lines (71 loc) · 2.96 KB

source-mapping.md

File metadata and controls

100 lines (71 loc) · 2.96 KB

Source Mapping Implementation

This document describes the implementation of Rust source code mapping for the erst simulator.

Overview

The source mapping feature allows erst to map WASM instruction failures back to specific lines in the original Rust source code when debug symbols are available. This is the "Holy Grail" feature that tells developers exactly which line in their Rust code failed.

Architecture

Components

  1. SourceMapper (src/source_mapper.rs): Core module that handles DWARF debug symbol parsing
  2. SourceLocation: Data structure representing a source code location (file, line, column)
  3. Enhanced SimulationRequest: Extended to accept contract WASM bytecode
  4. Enhanced SimulationResponse: Extended to include source location information

Key Features

  • Debug Symbol Detection: Automatically detects if WASM contains debug symbols
  • Graceful Fallback: Works seamlessly when debug symbols are missing
  • Performance Optimized: Minimal overhead for large DWARF sections
  • Comprehensive Testing: Full unit test coverage

Usage

Input Format

The simulator now accepts an optional contract_wasm field in the simulation request:

{
  "envelope_xdr": "...",
  "result_meta_xdr": "...",
  "ledger_entries": {},
  "contract_wasm": "base64-encoded-wasm-with-debug-symbols"
}

Output Format

When a failure occurs and debug symbols are available, the response includes source location:

{
  "status": "error",
  "error": "Contract execution failed. Failed at line 45 in token.rs",
  "events": [],
  "logs": [],
  "source_location": {
    "file": "token.rs",
    "line": 45,
    "column": 12
  }
}

Implementation Details

Debug Symbol Detection

The implementation checks for the presence of DWARF debug sections in the WASM:

  • .debug_info: Contains debugging information entries
  • .debug_line: Contains line number information

Future Enhancements

The current implementation provides the foundation for full source mapping. Future enhancements will include:

  1. Full DWARF Parsing: Complete integration with addr2line crate for precise mapping
  2. Instruction Offset Mapping: Map specific WASM instruction offsets to source lines
  3. Stack Trace Support: Provide full call stack with source locations
  4. Optimization Handling: Handle optimized code mappings

Testing

Run the unit tests:

cd simulator
cargo test

The test suite covers:

  • Source mapper without debug symbols
  • Source mapper with mock debug symbols
  • Source location serialization
  • Error handling and graceful fallbacks

Dependencies

  • object: WASM/ELF file parsing
  • addr2line: DWARF debug information parsing (future enhancement)
  • gimli: Low-level DWARF parsing (future enhancement)

Performance Considerations

  • Debug symbol parsing is performed only once during initialization
  • Minimal memory overhead for contracts without debug symbols
  • Lazy loading of DWARF sections for large contracts