Traverse: Solidity Analysis Tools

Analyze, visualize, and test Solidity smart contracts. Built with Rust and tree-sitter parsing.

📖 For architectural details and design principles, see DESIGN.md

Table of Contents

• Quick Start
• Installation
• Tools Included
• Tool: sol2cg - Call Graph & Sequence Diagram Generator
• Tool: sol2test - Foundry Test Generator
• Tool: sol-storage-analyzer - Storage Access Analyzer
• Tool: storage-trace - Storage Trace Comparator
• Tool: sol2bnd - Binding File Generator
• Development Workflow Integration
• Tool Integration & Workflows
• Building from Source
• Docker Usage
• Configuration
• Troubleshooting
• Performance & Limitations
• Compatibility
• Contributing
• License

Quick Start

# Download sol2cg (choose your platform)
# macOS Intel:
curl -sSfL -o /usr/local/bin/sol2cg https://github.com/calltrace/traverse/releases/latest/download/sol2cg-macos-amd64
chmod +x /usr/local/bin/sol2cg

# macOS Apple Silicon:
curl -sSfL -o /usr/local/bin/sol2cg https://github.com/calltrace/traverse/releases/latest/download/sol2cg-macos-arm64
chmod +x /usr/local/bin/sol2cg

# Linux x86_64:
curl -sSfL -o /usr/local/bin/sol2cg https://github.com/calltrace/traverse/releases/latest/download/sol2cg-linux-amd64
chmod +x /usr/local/bin/sol2cg

# Generate a call graph visualization
sol2cg contracts/*.sol -o callgraph.dot

# Convert to PNG using Graphviz
dot -Tpng callgraph.dot -o callgraph.png

Installation

Install via Homebrew (macOS/Linux)

brew tap calltrace/tap
brew install traverse

This installs all traverse tools: sol2cg, sol2test, sol-storage-analyzer, storage-trace, and sol2bnd.

Download Binaries

Get pre-built binaries from the releases page or use curl:

# Example: Download sol2cg on macOS Apple Silicon
curl -sSfL -o /usr/local/bin/sol2cg \
  https://github.com/calltrace/traverse/releases/latest/download/sol2cg-macos-arm64
chmod +x /usr/local/bin/sol2cg

Replace sol2cg with any tool name and choose your platform: - macos-amd64 (Intel Mac) - macos-arm64 (Apple Silicon) - linux-amd64 (Linux x86_64) - windows-amd64.exe (Windows)

Docker

Run tools without installation using Docker:

# Pull pre-built images from GitHub Container Registry
docker pull ghcr.io/calltrace/traverse:sol2cg
docker pull ghcr.io/calltrace/traverse:all  # All tools in one image

# Run a specific tool
docker run --rm -v $(pwd):/workspace ghcr.io/calltrace/traverse:sol2cg /workspace/contracts/*.sol

# Use docker-compose for complex workflows
curl -O https://raw.githubusercontent.com/calltrace/traverse/main/docker-compose.yml
docker-compose up

Install via Cargo

For Rust developers who have cargo installed:

# Install all CLI tools at once (available after rate limit expires)
cargo install traverse-cli

# This will install all binary tools:
# - sol2cg: Call graph generator
# - sol2test: Test generator
# - sol2bnd: Solidity boundary analyzer
# - sol-storage-analyzer: Storage access analyzer
# - storage-trace: Storage operation tracer

The traverse-cli package will be available after Sept 19, 2025 (crates.io rate limit). Build from source meanwhile.

Build from Source

For contributors and advanced users:

Prerequisites

• Rust toolchain: Version 1.83 or later (Install Rust)
• Git: For cloning the repository with submodules

# Clone the repository with submodules
git clone --recursive https://github.com/calltrace/traverse.git
cd traverse

# Build all tools in release mode
cargo build --release

# Binaries will be available in target/release/
ls -la target/release/sol*

# Optional: Install to system path
cargo install --path crates/cli

Tools Included

Tool	Purpose	Primary Use Case
sol2cg	Generate call graphs and sequence diagrams	Visualizing contract interactions and control flow
sol2test	Generate Foundry test stubs	Creating comprehensive test suites automatically
sol-storage-analyzer	Analyze storage read/write patterns	Understanding state variable access in functions
storage-trace	Compare storage traces between functions	Finding storage access differences
sol2bnd	Generate binding configuration files	Creating interface bindings from Natspec

sol2cg - Call Graph Generator

Visualize function calls and contract interactions as graphs (DOT) or sequence diagrams (Mermaid). Analyzes complete projects in ~500ms.

Usage

sol2cg [OPTIONS] <INPUT_PATHS>...

Options

• -o, --output-file <OUTPUT_FILE>: Output file path. If not specified, output goes to stdout
• -f, --format <FORMAT>: Output format [default: dot] [possible values: dot, mermaid]
• --disable-steps <DISABLE_STEPS>: Disable specific pipeline steps (comma-separated list). Available steps: Contract-Handling, Calls-Handling
• --enable-steps <ENABLE_STEPS>: Enable specific pipeline steps (comma-separated list)
• --config <CONFIG>: Configuration parameters for pipeline steps (format: key=value,key2=value2)
• --exclude-isolated-nodes: [DOT format only] Exclude nodes that have no incoming or outgoing edges
• --no-chunk: [Mermaid format only] Disable automatic chunking of large diagrams
• --chunk-dir <CHUNK_DIR>: [Mermaid format only] Directory for chunked output (default: ./mermaid-chunks/)
• --bindings <BINDINGS>: Optional path to the binding.yaml file for interface resolution
• --manifest-file <MANIFEST_FILE>: Optional path to a pre-generated manifest.yaml file
• -h, --help: Print help information
• -V, --version: Print version information

Examples

See the Smart Invoice Example for a complete real-world analysis of a production DeFi application.

# Generate DOT graph from a single file to stdout
sol2cg path/to/your/Contract.sol

# Generate Mermaid sequence diagram from multiple files
sol2cg -f mermaid -o output/diagram.mmd src/ContractA.sol src/ContractB.sol

# Generate DOT graph from all .sol files in a directory
sol2cg -f dot -o output/full_graph.dot ./contracts/

# Generate a call graph with specific pipeline steps disabled
sol2cg --disable-steps "Calls-Handling" -o output/definitions_only.dot ./contracts/

# Generate a call graph with custom configuration
sol2cg --config "max_depth=3,include_internal=false" -o output/custom_graph.dot ./contracts/

# Exclude isolated nodes from the graph
sol2cg --exclude-isolated-nodes -o clean_graph.dot ./contracts/

Output Formats

• DOT: For Graphviz visualization (dot -Tsvg graph.dot -o graph.svg)
• Mermaid: Works in GitHub/GitLab markdown, automatically chunks large diagrams

sol2test - Foundry Test Generator

Generates Foundry test suites from your contracts. Creates deployment scripts, setup functions, and test stubs for all public/external functions.

Requires: Foundry installed

Usage

sol2test [OPTIONS] [INPUT_PATHS]...

Options

• --project <PROJECT>: Process a Foundry project directory instead of individual files
• -o, --output-dir <OUTPUT_DIR>: Output directory for generated tests [default: foundry-tests/test]
• -t, --template-dir <TEMPLATE_DIR>: Template directory [default: templates]
• -v, --verbose: Enable verbose output
• --use-foundry: Use Foundry for compilation and validation
• --validate-compilation: Validate that generated tests compile
• --deployer-only: Generate only deployment tests
• --disable-steps <DISABLE_STEPS>: Disable specific pipeline steps
• --enable-steps <ENABLE_STEPS>: Enable specific pipeline steps
• --config <CONFIG>: Configuration parameters for pipeline steps
• --bindings <BINDINGS>: Path to binding.yaml file
• --manifest-file <MANIFEST_FILE>: Path to pre-generated manifest.yaml
• --foundry-root <FOUNDRY_ROOT>: Root directory of Foundry project
• -h, --help: Print help information
• -V, --version: Print version information

Examples

# Generate tests for a single contract
sol2test contracts/Token.sol -o test/

# Process an entire Foundry project
sol2test --project ./my-foundry-project --use-foundry

# Generate tests with compilation validation
sol2test contracts/*.sol --validate-compilation --use-foundry

# Generate only deployment tests
sol2test --deployer-only contracts/ComplexProtocol.sol

# Use custom templates
sol2test -t custom-templates/ contracts/*.sol

# Verbose output for debugging
sol2test -v contracts/*.sol

Output

The tool generates: * Test contract files with proper imports * Deployment and setup functions * Test function stubs for all public/external functions * Helper functions for common testing patterns

Example generated test structure:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Test.sol";
import "../src/Token.sol";

contract TokenTest is Test {
    Token token;

    function setUp() public {
        token = new Token();
    }

    function test_transfer() public {
        // TODO: Implement test
    }
}

sol-storage-analyzer

Maps storage reads and writes for all public/external functions. Identifies state modification patterns and optimization opportunities.

Usage

sol-storage-analyzer [OPTIONS] <INPUT_PATHS>...

Options

• -o, --output-file <OUTPUT_FILE>: Output file for the analysis report
• --bindings <BINDINGS>: Path to binding.yaml file
• --manifest-file <MANIFEST_FILE>: Path to pre-generated manifest.yaml
• -h, --help: Print help information
• -V, --version: Print version information

Examples

# Analyze a single contract
sol-storage-analyzer contracts/Vault.sol

# Analyze multiple contracts and save to file
sol-storage-analyzer contracts/*.sol -o storage-report.md

# Analyze with interface bindings
sol-storage-analyzer --bindings bindings.yaml contracts/

# Use pre-generated manifest
sol-storage-analyzer --manifest-file manifest.yaml contracts/Protocol.sol

Output

Generates a markdown table showing: * Function endpoints (Contract.function format) * Storage variables read * Storage variables written

Example output:

| Endpoint | Reads | Writes |
|----------|-------|--------|
| Token.transfer | balances, allowances | balances |
| Token.approve | | allowances |
| Token.balanceOf | balances | |

storage-trace

Compares storage access between two functions. Useful for upgrade compatibility and refactoring validation.

Usage

storage-trace [OPTIONS] --func1 <FUNC1> --func2 <FUNC2> <INPUT_PATHS>...

Options

• --func1 <FUNC1>: First function to compare (format: functionName or Contract.functionName)

• --func2 <FUNC2>: Second function to compare

• -o, --output-file <OUTPUT_FILE>: Output file for comparison report

• --bindings <BINDINGS>: Path to binding.yaml file
• --manifest-file <MANIFEST_FILE>: Path to pre-generated manifest.yaml
• -h, --help: Print help information
• -V, --version: Print version information

Examples

# Compare two functions in the same contract
storage-trace --func1 deposit --func2 depositFor contracts/Vault.sol

# Compare functions across contracts
storage-trace --func1 TokenV1.transfer --func2 TokenV2.transfer contracts/

# Save comparison to file
storage-trace --func1 stake --func2 stakeFor contracts/*.sol -o comparison.md

# Use with bindings
storage-trace --func1 swap --func2 swapExact --bindings bindings.yaml contracts/

Output

Generates a detailed comparison showing: * Storage variables accessed by each function * Differences in read patterns * Differences in write patterns * Common access patterns

Example output:

Storage Trace Comparison: deposit vs depositFor

Function 1 (deposit):
- Reads: [balance, totalSupply]
- Writes: [balance, totalSupply, lastUpdate]

Function 2 (depositFor):
- Reads: [balance, totalSupply, allowance]
- Writes: [balance, totalSupply, lastUpdate, allowance]

Differences:
- Only in depositFor reads: [allowance]
- Only in depositFor writes: [allowance]

sol2bnd

Generates binding configurations from Natspec annotations. Maps interfaces to implementations.

Usage

sol2bnd [OPTIONS] <PROJECT_PATH>

Arguments & Options

Arguments: * <PROJECT_PATH>: Path to the Solidity project directory

Options: * -o, --output-file <OUTPUT_FILE>: Output path for the binding file [default: binding.yaml] * -h, --help: Print help information * -V, --version: Print version information

Examples

# Generate bindings for a project
sol2bnd ./contracts -o bindings.yaml

# Generate bindings for current directory
sol2bnd .

# Generate with default output name
sol2bnd my-project/

Creates YAML file with interface mappings and contract metadata.

Development Workflow Integration

Editor Integration

Traverse provides first-class editor support through dedicated extensions and language server protocol (LSP) implementations:

VSCode Extension

Install the Traverse Solidity Analyzer extension for integrated Solidity analysis directly in VSCode:

• Repository: traverse-vscode
• **Marketp