sol2seq

A Rust library and CLI tool for generating sequence diagrams from Solidity smart contracts.

Features

• Generate Mermaid sequence diagrams from Solidity AST JSON files
• Process Solidity source files directly
• Supports both solc-generated and Aderyn-generated AST formats
• Visualize contract interactions, function calls, and events
• Customize diagram appearance with light/dark themes
• Use as a library in your Rust projects or as a CLI tool

Installation

# As a CLI tool
cargo install sol2seq

# Or from source
git clone https://github.com/sumitvekariya/sol2seq.git
cd sol2seq
cargo install --path .

CLI Usage

# Generate a sequence diagram from Solidity source files directly
sol2seq source Contract.sol Library.sol output_diagram.md

# Generate a sequence diagram from an AST JSON file
sol2seq ast path/to/ast.json output_diagram.md

# Generate with lighter colors
sol2seq source --light-colors Contract.sol output_diagram.md
sol2seq ast --light-colors path/to/ast.json output_diagram.md

Command-Line Arguments

Usage: sol2seq [OPTIONS] <COMMAND>

Commands:
  source  Generate diagram from Solidity source files
  ast     Generate diagram from AST JSON file
  help    Print this message or the help of the given subcommand(s)

Options:
  -l, --light-colors  Use lighter colors for the sequence diagram
  -h, --help          Print help information
  -V, --version       Print version information

Source Command

Usage: sol2seq source [OPTIONS] <SOURCE_FILES>... [OUTPUT_FILE]

Arguments:
  <SOURCE_FILES>...  Solidity source files to process
  [OUTPUT_FILE]      Output file path (optional, will print to stdout if not provided)

Options:
  -l, --light-colors  Use lighter colors for the sequence diagram
  -h, --help          Print help information

AST Command

Usage: sol2seq ast [OPTIONS] <AST_FILE> [OUTPUT_FILE]

Arguments:
  <AST_FILE>       AST JSON file path
  [OUTPUT_FILE]    Output file path (optional, will print to stdout if not provided)

Options:
  -l, --light-colors  Use lighter colors for the sequence diagram
  -h, --help          Print help information

Generating AST JSON

If you prefer to generate the AST JSON manually and then use it with sol2seq, you can use one of the following methods:

Using Solidity Compiler

# Generate AST JSON for a Solidity file
solc --combined-json ast Contract.sol > contract_ast.json

# Then use sol2seq to generate a sequence diagram
sol2seq ast contract_ast.json diagram.md

Using Aderyn

sol2seq also supports the AST format generated by Aderyn:

# Generate AST using Aderyn
aderyn /path/to/contracts --ast-json

# Then use sol2seq with the Aderyn-generated AST
sol2seq ast reports/combined_ast.json diagram.md

Library Usage

use anyhow::Result;
use sol2seq::{generate_diagram_from_file, generate_diagram_from_sources, Config};

fn main() -> Result<()> {
    // Create a configuration
    let config = Config {
        light_colors: false,
        output_file: Some("diagram.md".into()),
    };

    // Generate diagram from AST file
    let diagram = generate_diagram_from_file("path/to/ast.json", config.clone())?;
    println!("AST diagram generated successfully!");
    
    // Generate diagram directly from Solidity source files
    let source_files = vec!["Contract.sol", "Library.sol"];
    let diagram = generate_diagram_from_sources(&source_files, config)?;
    println!("Source files diagram generated successfully!");
    
    Ok(())
}

API Reference

The library provides the following main functions:

generate_diagram_from_file

Generates a sequence diagram from an AST JSON file.

pub fn generate_diagram_from_file<P: AsRef<std::path::Path>>(
    ast_file: P,
    config: Config,
) -> Result<String>

Parameters:

• ast_file: Path to the AST JSON file.
• config: Configuration for diagram generation.

Returns:

• The generated diagram as a string.

generate_diagram_from_sources

Generates a sequence diagram directly from Solidity source files.

pub fn generate_diagram_from_sources<P: AsRef<std::path::Path>>(
    source_files: &[P],
    config: Config,
) -> Result<String>