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 a directory of Solidity files
sol2seq source ./contracts output_diagram.md

# Process multiple files and directories
sol2seq source Contract.sol ./contracts ./lib/interfaces 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.clone())?;
    println!("Source files diagram generated successfully!");
    
    // Generate diagram from a directory of Solidity files
    let source_dirs = vec!["./contracts"];
    let diagram = generate_diagram_from_sources(&source_dirs, config)?;
    println!("Directory 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 or directories.

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

Parameters:

• source_paths: Paths to Solidity source files or directories. Directories will be recursively searched for .sol files.
• config: Configuration for diagram generation.

Returns:

• The generated diagram as a string.

Example Output

The generated sequence diagrams use Mermaid syntax and can be viewed in markdown editors that support Mermaid (like GitHub, VS Code with the Mermaid extension, etc.). Here's an example of what the output looks like:

sequenceDiagram
    title Smart Contract Interaction Sequence Diagram
    autonumber
    
    participant User as "External User"
    participant Token as "TokenContract<br/>(name: string,<br/>symbol: string,<br/>decimals: uint8,<br/>totalSupply: uint256)"
    participant SimpleStorage as "SimpleStorage<br/>(value: uint256)"
    participant Events as "Blockchain Events"
    
    %% User Interactions Section
    Note over User: User Interactions
    
    Note over User,Token: Contract initialization
    User->>+Token: constructor(_name: string, _symbol: string, _decimals: uint8, _initialSupply: uint256, _storageAddress: address)
    
    Note over User,Token: Transfer tokens
    User->>+Token: transfer(to: address, value: uint256)
    Token-->>-User: returns bool: success
    
    User->>+Token: approve(spender: address, value: uint256)
    Token-->>-User: returns bool: success
    
    User->>+Token: transferFrom(from: address, to: address, value: uint256)
    Token-->>-User: returns bool: success
    
    User->>+Token: updateStorage(newValue: uint256)
    Token->>SimpleStorage: setValue(newValue: uint256)
    Token->>Events: Emit StorageUpdated(newValue: uint256)
    Token-->>-User: returns bool: success
    
    User->>+Token: getStorageValue()
    Token->>SimpleStorage: getValue()
    SimpleStorage-->>Token: returns uint256
    Token-->>-User: returns uint256
    
    %% Event Definitions
    Note over Events: Event Definitions
    Note over Token,Events: Event: Transfer(from: address, to: address, value: uint256)
    Note over Token,Events: Event: Approval(owner: address, spender: address, value: uint256)
    Note over Token,Events: Event: StorageUpdated(newValue: uint256)
    Note over SimpleStorage,Events: Event: ValueSet(newValue: uint256)

The diagram clearly shows:

• Contract participants with their state variables
• User interactions with contracts
• Contract-to-contract interactions
• Event emissions
• Return values
• Categorized sections with notes