DOCSEARCHbyAlgolia
Submit Docs

Solar Compiler Documentation

repository·main·Indexed 20 days ago

https://github.com/paradigmxyz/solar

Solar is a high-performance, modular Solidity compiler written in Rust, designed for superior speed and memory efficiency compared to solc. The project includes crates for AST definitions (solar-ast), lexing and parsing (solar-parse), semantic analysis (solar-sema), and EVM bytecode generation (solar-codegen). It provides a C API (solar-capi), a WASM distribution for JavaScript/browser use, and LSP support for VS Code and Zed editor integrations.

Tokens
71.7K
Snippets
241
Records
333
Agent score
65%

What's inside Solar

  3. Use solar-ast for Solidity and Yul AST definitions

    main
    The solar-ast crate provides the core type definitions and visitor trait implementations for working with Solidity and Yul Abstract Syntax Trees (AST). Developers building tools that need to analyze, transform, or traverse Solidity or Yul code can use these definitions to ensure compatibility with the Solar ecosystem's representation of source code structures.

  4. Use solar-parse for Solidity and Yul lexing and parsing

    main
    The solar-parse crate provides a lexer and parser specifically designed for Solidity and Yul. The implementation is based on the rustc_lexer and rustc_parse modules from the Rust compiler, but has been modified to correctly handle the syntax and grammar differences between Rust and Solidity/Yul.

  5. Use the solar-capi C API and JavaScript wrapper

    main

    The solar-capi crate provides a Solidity-compatible C API by building the compiler as a cdylib. This same ABI is used by both the WebAssembly (WASM) build and the JavaScript wrapper.

    For C/C++ integration, the source of truth for function signatures, callback behavior, and memory ownership rules is the header file include/libsolc.h.

  6. Overview of solar-codegen architecture

    main

    The solar-codegen crate is responsible for transforming Solar's High-level Intermediate Representation (HIR) into EVM bytecode. The compilation pipeline follows this flow:

    1. HIR: Received from solar-sema.
    2. Lowering: The process of converting HIR into MIR.
    3. MIR: The Mid-level Intermediate Representation.
    4. Code Generation: Converting MIR into machine-level instructions.
    5. EVM Bytecode: The final executable output.

  7. Understand the Solar MIR structure

    main

    The Mid-level Intermediate Representation (MIR) is organized into a hierarchy of containers and SSA (Static Single Assignment) components:

    • Module: The top-level container that holds functions, data segments, and the storage layout.
    • Function: Functions represented in SSA-form, consisting of basic blocks, values, and instructions.
    • BasicBlock: A sequence of instructions that always ends with a Terminator.
    • Instruction: The fundamental operations, including arithmetic, memory access, storage access, and control flow.
    • Value: SSA values, which can be instruction results, function arguments, immediates, or phi nodes.

  8. Core concepts in solar-interface

    main

    The solar-interface module provides the fundamental building blocks for handling source code metadata, diagnostics, and text representation. It revolves around three primary concepts:

    1. Spans: Represented by the Span type, these track specific locations within source code.
    2. Source Maps: Represented by the SourceMap type, these manage the mapping of source code content.
    3. Interned Strings: Represented by Symbols, these provide efficient handling of strings. Common symbols can be accessed via the sym module.

  9. Understand solc Divergence in Solar

    main

    Solar intentionally diverges from solc in certain behaviors, specifically regarding how it accepts, rejects, warns, or reports source locations. These divergences are not necessarily missing features, but rather deliberate design choices in how the compiler frontend is structured.

    When using Solar, be aware that certain validation checks might occur at different stages of the compilation pipeline compared to solc. For example, a file that passes the parsing stage in Solar might still fail in a later AST validation stage, even if solc would have rejected it during its own parsing stage.

  10. Understand the Fandango and Foundry fuzzing flow

    main

    The fuzzing workflow combines Fandango, SolSmith, and Foundry to identify compiler discrepancies:

    1. Generation: Fandango and SolSmith generate ABI values and Solidity programs.
    2. Execution: Foundry's built-in fuzzer executes these generated targets using cheatcodes.
    3. Differential Analysis: The Foundry differential path compares different compiler runtimes by:
      • Installing solc and the target compiler runtimes at different addresses.
      • Fuzzing calls through Foundry.
      • Recording logs and state diffs using vm.recordLogs() and vm.startStateDiffRecording().
      • Comparing success/revert status, returndata, normalized logs, and normalized state side effects.

  11. Run the Solar benchmark workflow via GitHub Actions

    main

    The benchmark workflow (bench.yml) runs automatically for pull requests and updates to main. It supports several benchmark families:

    • codegen runtime comparisons
    • CodSpeed
    • Gungraun instruction counts

    You can manually dispatch the workflow using the GitHub CLI (gh). For example, to benchmark a specific branch (my-branch) using Gungraun, comparing it against main, and skipping the codegen runtime and CodSpeed jobs, use the following command:

    gh workflow run bench.yml --ref my-branch \
  -f benchmark=gungraun \
  -f comparison_ref=main

  12. Run integration tests with solar-tester

    main

    The solar-tester tool provides integration test support for the compiler. It allows you to run various test suites including UI, MIR, EVM IR, standard JSON, and upstream compatibility tests.

    To run individual test suites, use the cargo tq aliases. For example, to run the UI test suite, use cargo tq ui. To run the Solidity compatibility suite, use cargo tq solc-solidity.

    # Run UI tests
cargo tq ui

# Run Solidity compatibility tests
cargo tq solc-solidity