If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/argotorg/solidity shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit today
• 11 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live argotorg/solidity repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/argotorg/solidity.

What it runs against: a local clone of argotorg/solidity — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in argotorg/solidity | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of argotorg/solidity. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/argotorg/solidity.git
#   cd solidity
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of argotorg/solidity and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "argotorg/solidity(\\.git)?\\b" \\
  && ok "origin remote is argotorg/solidity" \\
  || miss "origin remote is not argotorg/solidity (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f "cmake/EthDependencies.cmake" \\
  && ok "cmake/EthDependencies.cmake" \\
  || miss "missing critical file: cmake/EthDependencies.cmake"
test -f ".circleci/config.yml" \\
  && ok ".circleci/config.yml" \\
  || miss "missing critical file: .circleci/config.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/argotorg/solidity"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

The official Solidity compiler—a statically-typed, contract-oriented language that compiles to EVM bytecode for Ethereum smart contracts. It provides a complete toolchain (solc CLI, liblangutil parser, semantic analysis, code generation, and optimization) that transforms human-readable Solidity source into executable bytecode and ABI definitions. Monolithic C++ compiler with layered architecture: libsolidity/ contains the parser and semantic analyzer; liblangutil/ provides error reporting and source locations; solc/ is the CLI entry point; test/ contains unit and integration tests; docs/ (Sphinx-based) generates the official documentation. CMake orchestrates multi-platform builds with optional dependency resolution (Z3, GMP) for advanced analysis features.

Smart contract developers writing dApps on Ethereum and EVM-compatible chains; compiler engineers maintaining or contributing to the language; tooling developers (Remix, Hardhat, Truffle) that embed the Solidity compiler; security researchers auditing contract compilation.

Highly mature and production-critical: 7.6M lines of C++ with 0.x versioning indicating intentional rapid iteration, comprehensive CMake/CI setup across CircleCI and GitHub Actions, active testing infrastructure (.circleci/soltest.sh, parallel_bytecode_report.sh), and governed by formal review processes (ReviewChecklist.md, ReleaseChecklist.md). The compiler is the de facto standard for Solidity; any regression impacts millions of deployed contracts.

Moderate technical risk: the codebase depends on external solvers (Z3, GMP via cmake/FindZ3.cmake, cmake/FindGMP.cmake) which can have version constraints; breaking language changes happen regularly (0.x versioning acknowledged in README). Security-critical since contract bugs originating from compiler defects are irreversible on-chain. Mitigated by formal security processes (SECURITY.md) and extensive test coverage, but compiler correctness is an existential property.

Active development on language features and optimizer improvements: the repo shows investment in CI/CD (GitHub Actions for code-style, CircleCI for parallel testing), recently updated Sphinx documentation setup (sphinx>=8.0.0 constraint in dependencies), and bytecode comparison tooling (.circleci/parallel_bytecode_report.sh) to track compiler output across versions. The 0.x version stream indicates regular feature releases and breaking changes.

git clone https://github.com/ethereum/solidity.git
cd solidity
mkdir build && cd build
cmake ..
cmake --build .
./solc/solc --version

Daily commands: After CMake build: ./solc/solc <file.sol> compiles to bytecode; ./solc/solc --help shows CLI options. For testing: ctest (CMake test runner) or .circleci/soltest.sh for full integration tests. Development iteration typically uses the compiled solc binary directly against .sol files.

• CMakeLists.txt — Root build configuration that orchestrates compilation of the entire Solidity compiler toolchain; essential for understanding how all components are assembled.
• README.md — Primary entry point documenting Solidity's purpose, community channels, and getting started guidance; required reading for orientation.
• CONTRIBUTING.md — Contribution guidelines defining workflow, review process, and expectations for all pull requests to the project.
• cmake/EthDependencies.cmake — Defines all external dependency resolution (Z3, GMP, CLN, boost) critical for reproducible builds and development environment setup.
• .circleci/config.yml — CI/CD pipeline configuration controlling automated testing, bytecode comparison, and multi-platform build validation across all commits.
• CODING_STYLE.md — Mandatory code style and formatting standards enforced via clang-format configuration; all code contributions must conform.
• .github/CODEOWNERS — Defines module ownership and review requirements; critical for understanding responsibility boundaries and approval routing.

Add a New Documentation Page

1. Create new .rst file in appropriate docs/ subdirectory following existing structure (e.g., docs/contracts/ for contract features) (docs/contracts/new-feature.rst)
2. Reference new file in parent toctree directive in docs/contracts.rst or relevant parent .rst file (docs/contracts.rst)
3. Follow RST syntax with code examples, notes, warnings using standard Sphinx directives (docs/conf.py)
4. Build documentation locally with 'make html' in docs/ directory and verify output renders correctly (docs/Makefile)

Add a New Build Configuration Option

1. Define option logic in cmake/EthOptions.cmake with option() command specifying name, description, and default value (cmake/EthOptions.cmake)
2. Add conditional logic to CMakeLists.txt or relevant cmake/*.cmake file to use the option value (CMakeLists.txt)
3. Update CONTRIBUTING.md with build instructions if option affects developer workflow (CONTRIBUTING.md)
4. Add CI/CD job variant to .circleci/config.yml if option requires new test matrix combination (.circleci/config.yml)

Add a New Code Style Rule

1. Document the style requirement in CODING_STYLE.md with rationale and examples (CODING_STYLE.md)
2. Update .clang-format configuration to enforce rule automatically or document manual verification step (.clang-format)
3. Run clang-format on entire codebase to ensure consistency: find . -name '.cpp' -o -name '.h' | xargs clang-format -i (cmake/EthCompilerSettings.cmake)
4. Add linting step to .circleci/config.yml code-style job if not already covered by existing checks (.circleci/config.yml)

Add a New Test Suite

1. Create test executable definition in CMakeLists.txt with add_executable() and target_link_libraries() for test dependencies (CMakeLists.txt)
2. Add test registration with add_test() command specifying test name and execution parameters (CMakeLists.txt)
3. Integrate test execution into .circleci/soltest.sh or create platform-specific runner script (.circleci/soltest.sh)
4. Add new test job or extend existing test jobs in .circleci/config.yml to run new suite on all supported platforms (.circleci/config.yml)

• CMake — Cross-platform build system enabling compilation on Linux, macOS, Windows with consistent configuration; supports modern C++ tooling and dependency resolution.
• C++ — Systems language providing performance-critical compiler implementation for parsing, type checking, code generation, and EVM bytecode emission.
• Sphinx + ReadTheDocs — Industry-standard documentation framework with hosted deployment, version management, and searchable offline access for multi-version language spec.
• CircleCI — Hosted CI/CD platform enabling parallel builds across multiple OS/architecture combinations with bytecode regression testing and automated deployment.
• Z3 SMT Solver + GMP/CLN — Formal verification and arbitrary-precision arithmetic libraries enabling compile-time type safety analysis, overflow detection, and mathematical correctness.

• Monolithic C++ compiler implementation vs. modular interpreter/LLVM backend

  • Why: Direct control over EVM bytecode generation, deterministic compilation, minimal runtime dependencies for reproducible builds.
  • Consequence: Larger codebase complexity, slower iteration on language features, tight coupling between frontend and codegen.

• Sphinx documentation in reStructuredText vs. Markdown

  • Why: Sphinx ecosystem provides versioning, cross-reference resolution, theme customization, and ReadTheDocs integration essential for language spec.
  • Consequence: Steeper contribution friction for documentation, requires special syntax for code examples and cross-links, less portable than Markdown.

• CMake build system vs. Bazel/Buck

  • Why: Simpler dependency management for external libraries, wider adoption in C++ ecosystem, easier Windows support.
  • Consequence: Less incremental build caching, verbose syntax, requires more manual target configuration than Bazel.

• Bytecode regression testing in CI vs. fuzzing-only approach

  • Why: Catches unintended output changes and optimization regressions; ensures deterministic compilation across versions.
  • Consequence: Additional CI job overhead, baseline management complexity, requires version-specific bytecode snapshots.

• Runtime execution of smart contracts (only compilation to bytecode)
• EVM simulation or local blockchain (bytecode is deployed to external networks)
• Package management system for smart contracts (language feature only, not a platform)
• Windows-native IDE integration beyond toolchain availability
• JavaScript/TypeScript runtime support (language targets EVM exclusively)

Z3/GMP optional but version-critical: cmake/FindZ3.cmake and cmake/FindGMP.cmake require specific versions if present; missing them silently degrades optimizer capabilities without build failure. Python 3 for CI scripting: .circleci/parallel_cli_tests.py assumes Python 3 in PATH. Bytecode reproducibility: .circleci/parallel_bytecode_report.sh compares outputs across compiler versions; optimization flags and dependency versions must match exactly or reports will flag spurious 'regressions'. Clang-format enforcement: code-style GitHub Action enforces .clang-format rules; PRs fail if not formatted. Breaking changes in 0.x: version bump can introduce language incompatibilities; always check Changelog.md when updating compiler versions.

• Abstract Syntax Tree (AST) Visitor Pattern — The Solidity compiler uses the Visitor pattern extensively (see libsolidity/analysis/ and libsolidity/codegen/) to traverse and transform the AST through parsing, type-checking, and code generation phases; understanding this pattern is foundational to modifying the compiler.
• EVM (Ethereum Virtual Machine) Bytecode — Solidity compiles to EVM bytecode, a stack-based instruction set; understanding opcodes (PUSH1, ADD, SSTORE, etc.) is critical to debugging compiler output and verifying ContractCompiler.cpp generates correct instructions.
• Semantic Analysis & Type Inference — libsolidity/analysis/TypeChecker.cpp is the second major compiler phase after parsing; it enforces Solidity's type system (uint256 vs address vs custom types) and catches errors early, making it critical for language correctness.
• SMT Solver Integration (Z3) — Optional Z3 integration via cmake/FindZ3.cmake enables formal verification of contract properties and advanced optimization; understanding solver-based analysis helps contribute to symbolic execution and overflow detection.
• Yul Intermediate Language — Solidity compiles to Yul (1.2M lines in repo) before final bytecode; Yul is a low-level, optimizer-friendly IL with its own syntax and semantics, and understanding Yul is essential to contributing optimizations or code generation.
• Cross-Platform CMake Build System — The repo uses CMake (cmake/) to build on Linux, macOS, Windows with optional dependencies (Z3, GMP); contributors must understand the build chain to add features, resolve dependency issues, or debug platform-specific failures.
• Bytecode Reproducibility & Deterministic Compilation — The .circleci/parallel_bytecode_report.sh tooling enforces that identical Solidity source produces identical bytecode across compiler versions; this property is crucial for trust and auditability in blockchain contexts and informs optimization pass ordering and metadata handling.

• ethereum/go-ethereum — Reference Ethereum implementation (go-ethereum/core/vm) that executes the bytecode solc produces; understanding EVM semantics is essential to compiler correctness.
• ethereum/remix-ide — Browser IDE that embeds solc-js (compiled solc) as the compiler backend; major consumer of the language and test bed for user-facing usability.
• ethereum/eth2.0-deposit-contract — High-stakes production Solidity contract deployed on Ethereum; exemplary test case for compiler correctness and optimization quality.
• hardhat/hardhat — Popular smart contract development framework that integrates solc; represents a key user of the compiler for CI/CD in contract projects.
• ethereum/solidity-docs — Official Solidity documentation repo (mirror of docs/ in this codebase); coordinates specification and user-facing language reference.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive GitHub Actions workflow for documentation build validation

The repo has .readthedocs.yml and docs/ folder with Sphinx configuration, but .github/workflows/ lacks a dedicated documentation CI job. Currently, only code-style.yml and buildpack-deps.yml exist. A docs validation workflow would catch sphinx-rtd-theme (>=3.0.0), sphinx (>=8.0.0, <9.0.0), and pygments-lexer-solidity (>=0.7.0) compatibility issues early, preventing broken documentation builds on ReadTheDocs. This is especially critical given the recent Sphinx 8.0+ requirement.

• [ ] Create .github/workflows/documentation.yml to run sphinx-build in docs/ directory
• [ ] Add build output validation against docs/Makefile and .readthedocs.yml configuration
• [ ] Test compatibility with sphinx>=8.0.0, <9.0.0 and sphinx-rtd-theme>=3.0.0 constraints
• [ ] Include warnings-as-errors flag to catch RST syntax issues (reference similar to code-style.yml pattern)

Add integration tests for CMake build system with different compiler toolchains

The repo has extensive cmake/ directory (EthCompilerSettings.cmake, EthDependencies.cmake, multiple toolchains) but no visible CMake-specific test workflow in .circleci/ or .github/workflows/. The soltest.sh and parallel_cli_tests.py suggest build testing exists, but not specifically for CMake configuration validation. Adding a workflow to test builds with different toolchains (cmake/toolchains/default.cmake, libfuzzer.cmake, ossfuzz.cmake) would catch CMake breakage early.

• [ ] Create .github/workflows/cmake-build-matrix.yml testing multiple toolchain configurations
• [ ] Test cmake/toolchains/default.cmake, cmake/toolchains/libfuzzer.cmake, and cmake/toolchains/ossfuzz.cmake
• [ ] Validate CMake dependency resolution (EthDependencies.cmake) for Z3, CLN, GMP via cmake/Find*.cmake modules
• [ ] Add build-only (no test) matrix for quick feedback on configuration errors

Create missing unit test suite for CODING_STYLE.md compliance tooling

The repo has CODING_STYLE.md and .clang-format defined, but .github/workflows/code-style.yml is minimal. There's no visible test suite in test/ or similar directories for validating the style guide enforcements. Contributing guidelines in CONTRIBUTING.md reference code style, but no automated checks exist for newcomers. A new test suite would help contributors understand style requirements and catch violations before PR submission.

• [ ] Create test/codestyle/ directory for style validation test cases
• [ ] Add test files covering .clang-format rules (indentation, spacing, line length based on CODING_STYLE.md)
• [ ] Implement validation script in .circleci/ (similar to parallel_bytecode_report.sh pattern) to run clang-format-check
• [ ] Document test execution in CONTRIBUTING.md with examples of passing/failing style checks

• Add Yul optimizer tests for new EVM opcodes: The codebase has 1.2M lines of Yul but .circleci/parallel_bytecode_report.sh only covers Solidity→bytecode; contribute targeted Yul assembly test cases in test/libyul/ for recently-added opcodes like PUSH0 or MCOPY.
• Improve error messages for common type mismatches: libsolidity/analysis/TypeChecker.cpp generates type errors, but many lack recovery suggestions; audit existing diagnostics and add fix hints (e.g., 'Did you mean to cast to uint256?') for the top 5 reported user issues on GitHub.
• Document Z3 solver integration for formal verification: cmake/FindZ3.cmake conditionally enables SMT solver support, but CODING_STYLE.md and README.md lack guidance on when/how to use it; write a concise doc explaining the optimization and formal verification capabilities enabled by Z3.

The Solidity repository demonstrates good security practices with a defined security policy, clear contribution guidelines, and structured CI/CD workflows. No critical vulnerabilities were identified in the visible configuration and documentation dependencies. However, minor improvements are recommended: (1) allowing more flexible Sphinx version constraints while maintaining compatibility testing, (2) implementing tighter version bounds for documentation dependencies, and (3) adding automated dependency vulnerability scanning to the CI/CD pipeline. The codebase itself appears to be a compiler implementation rather than a web application, which eliminates common web-based vulnerabilities (SQLi, XSS, CSRF). The architecture suggests security-focused development practices appropriate for a smart contract language compiler.

• Medium · Sphinx Documentation Build Version Constraint — Dependencies/Package file - sphinx version specification. The dependencies specify sphinx>=8.0.0, <9.0.0 with a tight upper bound. While this ensures compatibility with sphinx-syntax>=1.0.1, it may prevent security updates in future Sphinx minor versions (e.g., 8.1.x, 8.2.x) that could address vulnerabilities. The constraint should be reviewed and updated as new versions become available. Fix: Monitor Sphinx security releases and update the version constraint to allow patch and minor updates (e.g., sphinx>=8.0.0, <10.0.0) while maintaining compatibility testing with sphinx-syntax.
• Low · Dependency Version Pinning Best Practices — Dependencies/Package file - sphinx_rtd_theme and pygments-lexer-solidity specifications. The documentation dependencies use soft upper bounds (sphinx-rtd-theme>=3.0.0 and pygments-lexer-solidity>=0.7.0) without explicit upper version limits. While this allows flexibility, it could introduce breaking changes or security issues from unexpected major version updates. Fix: Consider using tighter version constraints with tested upper bounds (e.g., sphinx-rtd-theme>=3.0.0,<4.0.0) or implement continuous dependency scanning and automated testing for new releases.
• Low · Missing SBOM or Dependency Audit Configuration — .circleci/config.yml and .github/workflows/. No evidence of Software Bill of Materials (SBOM) generation, dependency audit tools (like pip-audit, safety, or snyk), or automated dependency vulnerability scanning in the visible CI/CD configuration. Fix: Implement automated dependency scanning in CI/CD pipelines using tools like Dependabot, Snyk, or pip-audit to detect known vulnerabilities in dependencies before deployment.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.