Stylus Debug Suite

A comprehensive toolkit for Arbitrum Stylus (Rust-based smart contracts) development, debugging, and migration.

Built by ILE Labs.

Table of Contents

• Overview
• Installation
• Quick Start
• CLI Reference
• Library Usage
• Feature Details
• Architecture
• License

Overview

The Stylus Debug Suite provides essential tools for the next generation of smart contract development on Arbitrum Stylus:

• High-Fidelity VM Debugging: Real wasmtime execution with DWARF source mapping.
• Smart Migration: AST-based Solidity-to-Rust conversion guidance.
• Security First: Automated trace analysis for reentrancy, CEI violations, and gas-heavy patterns.
• Actionable Profiling: Deep gas hotspot analysis with contextual optimization tips.

Installation

Globally via crates.io

cargo install stylus-debug

From source

git clone https://github.com/ILE-Labs/stylus-debug-suite.git
cd stylus-debug-suite
cargo install --path stylus-debug

Quick Start

Run the end-to-end demo to see the suite in action:

stylus-debug demo

Export a visual report:

stylus-debug demo --export report.html

CLI Reference

The unified stylus-debug binary provides the following commands:

stylus-debug migrate [INPUT]

Analyzes Solidity source files and provides high-fidelity Rust/Stylus equivalents.

• Arguments:
  • INPUT: Path to the .sol file (optional, defaults to examples/demo-contracts/Demo.sol).
• Options:
  • --format <format>: Output format (text or json).
  • --verbose: Shows matched source lines and line numbers.

stylus-debug adapter

Starts a Debug Adapter Protocol (DAP) server on stdio.

• Options:
  • --port <port>: Port for the DAP server (currently stdio by default).

stylus-debug demo

Runs a pre-defined debug scenario through the Stylus VM.

• Options:
  • --export <path>: Path to export the HTML report (e.g., report.html).

Library Usage

You can also use the suite's core logic as a library in your own Rust projects. Add the following to your Cargo.toml:

[dependencies]
stylus-debug = "0.1.0"

Example: Running a Debug Session

use stylus_debug::{DebugSession, DebugConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = DebugConfig {
        contract_path: "path/to/contract.rs".into(),
        entrypoint: "my_function".into(),
        breakpoints: vec!["contract.rs:42".into()],
    };

    let mut session = DebugSession::new(config);
    
    // Step-by-step execution
    while session.step() {
        println!("PC: {}", session.vm().current_ptr());
    }

    Ok(())
}

Feature Details

Security Analysis

Automatically detects 5 core vulnerability patterns in execution traces:

• Reentrancy: External CALL after SSTORE without a guard.
• Unchecked Calls: CALL operations not followed by status checks.
• CEI Violations: Non-standard Checks-Effects-Interactions flows.
• Gas Inefficiencies: Redundant SSTORE and large loops.

Gas Profiling

Provides a breakdown of gas consumption by opcode and contract function, highlighting expensive hotspots and offering Stylus-specific optimizations (e.g., caching storage in memory).

DWARF Debugging

Leverages gimli to parse DWARF debug information from WASM binaries, enabling accurate source-to-PC mapping and a real-world debugging experience.

Architecture

The suite is modularized into several crates:

• stylus-debug: Unified CLI entrypoint.
• debug-engine: Core VM execution engine and analyzer.
• engine-model: Shared data structures.
• gas-profiler: Gas analysis and optimization.

License

This project is licensed under the MIT License.