Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install stylus-debug

It will make the stylus-debug command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall stylus-debug uninstalls.

Back to the crate overview.

Readme

Stylus Debug Suite

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

Built by ILE Labs.

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.