home / skills / multiversx / mx-ai-skills / mvx_wasm_debug

mvx_wasm_debug skill

safe

This skill analyzes WASM binaries and maps DWARF debug info to Rust sources to help diagnose size, panics, and debugging.

npx playbooks add skill multiversx/mx-ai-skills --skill mvx_wasm_debug

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

830 B

---
name: mvx_wasm_debug
description: Analyzing WASM binaries and debugging via DWARF.
---

# MultiversX WASM Debugging

This skill helps you analyze the compiled `output.wasm` file.

## 1. Binary Size Analysis
- **Twiggy**: Use `twiggy top output.wasm` to see what takes up space.
- **Bloat**: Heavy JSON deserialization code? Large static strings?

## 2. Panic Analysis
- **Abort Messages**: By default, `sc_panic!` adds a string message.
- **Optimization**: `wasm-opt` removes these in production builds (`--opt-level z`).
- **Debugging**: If the contract traps with `unreachable`, check if it ran out of gas or hit a panic without a message.

## 3. DWARF Info
- MultiversX supports building with debug symbols (`mxpy contract build --debug`).
- This allows mapping WASM instructions back to Rust source lines in the debugger.

Overview

This skill helps analyze MultiversX WebAssembly binaries and debug contracts using DWARF debug symbols. It guides binary size inspection, panic root-cause analysis, and how to build with debug info for source-level debugging. The goal is faster diagnosis of size bloat, runtime traps, and mapping runtime behavior back to Rust source.

How this skill works

The skill inspects the compiled output.wasm to reveal size contributors and common bloat sources using tools like twiggy. It examines trap patterns and abort messages to distinguish panics, out-of-gas conditions, and optimized-away messages. It explains how to enable DWARF debug symbols during build so a debugger can map WASM offsets to Rust lines for step-through debugging.

When to use it

You need to reduce WASM binary size before deployment.
A contract is trapping with unreachable or abort but no clear message.
You want to profile which functions or static data dominate size.
You want to perform source-level debugging of a deployed or local contract using DWARF.
You are preparing a production build and must confirm panic messages and optimizations.

Best practices

Run twiggy (twiggy top output.wasm) early to spot large functions and data sections.
Build with debug enabled (mxpy contract build --debug) for local debugging cycles, then strip for production.
Check for heavy JSON deserialization or large static strings as common bloat sources.
Be mindful that wasm-opt and optimization levels may remove panic messages; confirm behavior in both debug and release builds.
When investigating traps, correlate gas usage and panic sites to distinguish out-of-gas from logic panics.

Example use cases

Identify which modules or functions contribute most to output.wasm using twiggy and reduce dependencies.
Diagnose an unreachable trap: determine whether it came from a panic without a message or an out-of-gas condition.
Build with DWARF to step through Rust source in a WASM-aware debugger and find the failing line.
Compare debug and optimized builds to ensure panic messages are preserved during local testing, and removed on production builds as intended.
Audit contract for large static assets or serialization code that can be moved off-chain or optimized.

FAQ

How do I enable source-level debugging for my contract?

Build with debug symbols using the debug build command (mxpy contract build --debug). This emits DWARF info that a WASM-aware debugger can use to map instructions back to Rust source.

Why do I see unreachable without a panic message?

Optimizers like wasm-opt can strip string messages in production builds. Also an out-of-gas condition or an explicit unreachable can produce the same trap; check both gas accounting and debug symbols to pinpoint the cause.