feat(simulator): Capture WASM stack frames at snapshot points

[DegenerateAlchemist]

TITLE:

feat(simulator): Capture WASM stack frames at snapshot points - Issue #985

DESCRIPTION:

Overview

Enhances the WASM simulator's debugging capabilities by capturing and storing the current WASM call stack (function name and instruction pointer) at snapshot points. This data is included in the SimulationResponse to enable tools like the CLI and IDE to display exactly where execution stopped.

Changes

Core Implementation

• WasmModule Inspector: New helper in vm.rs to resolve function names from WASM bytes.

  • Efficiently maps WASM offsets to function indices.
  • Extracts function names from the WASM name section.
  • Robust handling of imported functions using Debug-representation fallbacks for wasmparser version compatibility.

• Data Structures: Updated types.rs with WasmLocation and StateSnapshot.

  • WasmLocation: Stores the human-readable function name and decimal instruction pointer offset.
  • StateSnapshot: Captures the execution step, timestamp, and location metadata.

• Simulation Flow: Updated main.rs to populate snapshots during simulation.

  • Integrated WasmModule into the diagnostic event processing loop.
  • Automatically captures locations for every instruction execution ("budget tick") event.
  • Aggregates snapshots into the final SimulationResponse.

Testing

• Unit Tests: Updated simulator unit tests in main.rs to reflect the new SimulationResponse and DiagnosticEvent signatures.
• Integration Tests: Verified that simulations with WASM bytes now return the expected location payload in snapshots.
• Regression: Confirmed all existing simulator tests pass via cargo test.

Security Properties

• Safe Parsing: Uses wasmparser's robust streaming parser for safe handling of developer-provided WASM blobs.
• Integrity: Snapshot metadata is derived directly from the host environment during execution.

Configuration

• Automatically enabled when contract WASM is provided in the SimulationRequest.
• No new environment variables or setup steps required.

Verification

• All tests pass without lint suppressions.
• Code follows DRY principles.
• Verified that JSON output contains the necessary fields for the CLI to show "Stopped at: contract_id.function_name".
• Backward compatible with existing audit and simulation flows.

Related Issues

Closes #985

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Checklist

• Code follows project style guidelines
• Self-review completed
• Tests added/updated
• Documentation updated
• No new linting issues
• Changes verified locally

[drips-wave]

@DegenerateAlchemist Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits