GO — Healthy across the board

• Last commit today
• 8 active contributors
• Distributed ownership (top contributor 34% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Leo is a statically-typed imperative programming language that compiles to zero-knowledge circuits, enabling developers to write formally verified private applications without low-level cryptographic expertise. It abstracts ZK-SNARK construction (via Aleo) into high-level syntax similar to Rust/JavaScript, making it practical to build privacy-preserving dApps that prove computation correctness without revealing inputs. Monorepo in crates/ with modular architecture: crates/parser/ and crates/parser-rowan/ handle lexing/parsing, crates/ast/ defines the abstract syntax tree, crates/passes/ runs compiler passes, crates/compiler/ orchestrates code generation to Aleo bytecode, crates/cli/ provides the CLI entrypoint. Companion crates include leo-fmt (formatter), leo-lsp (language server), leo-test-framework (test harness). CircleCI examples in .circleci/lottery|tictactoe|token/ serve as reference programs.

Blockchain developers and protocol engineers building privacy-first applications on Aleo who want to write ZK circuits in a high-level language rather than low-level constraint systems. Contributors range from compiler engineers optimizing circuit generation to dApp developers using Leo for production applications.

Actively developed but explicitly alpha-stage with breaking changes expected. The repo shows significant maturity signals: 3.7M lines of Rust, comprehensive CI/CD via CircleCI, example projects (lottery, tictactoe, token in .circleci/), published to crates.io as leo-lang (version 4.0.2), and modern Rust tooling. However, the alpha label and ecosystem youth mean production use requires caution.

Moderate risk from language immaturity and rapid evolution—expect breaking changes between minor versions (currently v4.0.2). The monorepo spans 15+ interdependent crates (leo-parser, leo-compiler, leo-passes, etc.) creating high coupling; changes to AST in crates/ast/ ripple widely. Single organization (ProvableHQ) maintains it; community contribution surface area is growing but still concentrated. Dependency on Aleo ecosystem (aleo-std) creates external breaking-change risk.

Active development on v4.0.2 with recent focus on parser robustness (rowan-based rewrite in progress), compiler optimization passes, and LSP improvements. CircleCI workflows test integration of example programs continuously. No explicit issue/PR data visible in file list, but the modular crate structure and frequent updates suggest ongoing work on type system refinement and code generation improvements.

# Install Rust first
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build from source
git clone https://github.com/ProvableHQ/leo.git
cd leo
cargo build --release

# Or install released binary
cargo install leo-lang leo-fmt

# Verify installation
leo --version

Daily commands:

# Development build (slower, debugging symbols)
cargo build

# Run the CLI
./target/debug/leo --help

# Build an example program
cd .circleci/lottery
leo build
leo run main

# Run tests
cargo test --workspace

# Format code
cargo fmt

# Run a specific crate's tests
cargo test -p leo-compiler

• Cargo.toml — Workspace root configuration defining all Leo crates and their version (4.0.2); essential for understanding the mono-repo structure and dependency graph.
• crates/ast/src/common/mod.rs — Core AST abstraction module (Identifier, NetworkName, ProgramId, ConstParameter) that all language semantic passes depend on; foundational to parsing and type-checking.
• crates/compiler/Cargo.toml — Compiler crate manifest that orchestrates lexing, parsing, type-checking, and code generation; the critical compilation pipeline for Leo source to Aleo bytecode.
• crates/errors/src/lib.rs — Centralized error handling and reporting framework used across all crates; understanding error types is crucial for debugging compilation issues.
• ARCHITECTURE.md — High-level design document explaining Leo's compilation phases, intermediate representations, and module organization; mandatory onboarding for contributors.
• DEVELOPMENT.md — Development workflow, build instructions, and testing conventions; required for setting up local environment and running the test suite.
• .circleci/config.yml — CI/CD pipeline configuration that validates builds, runs tests on example projects (lottery, tictactoe, token), and gates commits; shows integration testing patterns.

Add a new built-in function to the Leo standard library

1. Define the function signature in the intrinsics module (typically in crates/compiler/src/lib.rs or a standard library definition file) (crates/compiler/Cargo.toml)
2. Implement type-checking rules for the function in the type checker pass (crates/compiler/src (check for type_checker.rs or similar))
3. Implement code generation lowering to Aleo bytecode instructions (crates/compiler/src (check for codegen.rs or similar))
4. Add test cases validating the function's type correctness and runtime behavior (.circleci/test-examples.sh or crates/compiler/tests/)

Add a new language syntax feature (e.g., loop construct, operator)

1. Extend the AST node enum in crates/ast/src to represent the new syntax construct (crates/ast/src/composite (or statements/expressions subdirectory))
2. Update the parser to recognize and build AST nodes for the new syntax (crates/compiler/src/parser.rs (or similar))
3. Add type-checking logic in the semantic analysis phase to validate the feature (crates/compiler/src/type_checker.rs or constraints module)
4. Implement code generation to lower the new construct to Aleo bytecode (crates/compiler/src/codegen.rs or similar)
5. Write integration tests using the new syntax in .circleci example programs (.circleci/lottery/src/main.leo or new test file)

Improve error messages for a compilation phase

1. Identify the error emission site in the compiler (parsing, type-checking, codegen, etc.) (crates/compiler/src (relevant pass module))
2. Define or extend error type in crates/errors/src/lib.rs with detailed diagnostic context (crates/errors/src/lib.rs)
3. Update the error emitter to include source location, suggestions, and contextual snippets (crates/errors/src/lib.rs (emitter implementation))
4. Test the improved message against failing examples and add regression test (.circleci/test-examples.sh or new test case in crates/compiler/tests/)

Add LSP feature for IDE support (e.g., hover, completion)

1. Define the LSP handler method in crates/lsp/src/lib.rs or server.rs (crates/lsp/src/lib.rs)
2. Query the AST and type information to gather IDE metadata (definitions, types, docs) (crates/lsp/src/lib.rs (integration with crates/compiler and crates/ast))
3. Format response according to LSP specification (e.g., Hover, Completion, Location) (crates/lsp/src/lib.rs)
4. Test with an LSP client (VS Code, Neovim, etc.) to validate end-to-end IDE integration (Manual testing with code editor)

• Rust — Systems-level performance and memory safety guarantees; essential for a compiler that must be fast and reliable without garbage collection overhead.
• Aleo VM / Bytecode — Compilation target for zero-knowledge proofs; Leo generates Aleo bytecode to leverage Aleo's proving and verification infrastructure.
• AST-based approach — Enables multi-pass compilation (parsing → type-checking → codegen) with clear separation of concerns; supports both static analysis and LSP features.
• LSP (Language Server Protocol) — Provides IDE/editor integration (VS Code, Neovim, Sublime, etc.) without reimplementing language support for each tool.

• Static typing with inference

  • Why: Type safety and early error detection; prevents runtime surprises in cryptographic code.
  • Consequence: Developer must annotate function signatures; less flexibility than dynamic typing but more assurance of correctness.

• Imperative language design (not functional)

  • Why: Familiarity for developers coming from C/Java/Rust; easier onboarding than functional paradigms.
  • Consequence: State mutations and side effects are allowed; developers must manage invariants carefully, especially in zero-knowledge contexts.

• Single-pass optimization in codegen

  • Why: Compiler speed; avoids multiple IR traversals.
  • Consequence: May miss optimization opportunities that multi-pass approaches would catch; trade compile speed for output size/performance.

• Aleo backend coupling

  • Why: Deep integration with Aleo ecosystem enables native zero-knowledge proof generation.
  • Consequence: Leo is not portable to other blockchain or proving systems without significant rewrite of code generation.

• Does not provide a runtime interpreter; Leo is a compiled language only.
• Does not handle on-chain deployment or blockchain execution directly; Aleo network handles that layer.
• Not a general-purpose language; designed specifically for private/zero-knowledge applications.
• Does not offer cross-chain interoperability; targets Aleo ecosystem exclusively.
• Not designed for concurrent/parallel program execution; single-threaded execution model.

No required env vars listed in .cargo/config.toml, but CircleCI jobs may inject secrets (check .circleci/config.yml). Breaking changes: Workspace version is pinned to 4.0.2 across all crates—bumping one requires bumping all (resolver = 3 enforces this). Aleo dependency: Requires aleo-std 1.0.3; incompatible Aleo versions will silently fail at codegen. Parser rowan migration: Codebase is transitioning from hand-written to rowan-based parser; both may coexist, causing confusion in which one is used. Test framework limitation: .circleci examples compile but actual execution depends on Aleo snarkVM runtime, not bundled—tests verify structure, not ZK correctness. Nextest config: Uses .config/nextest.toml for test parallelization; standard cargo test behavior may differ.

• Zero-Knowledge Proofs (ZK-SNARKs) — Leo's entire purpose is abstracting ZK-SNARK construction; understanding what a ZK proof proves and what it hides is essential to using Leo correctly
• Circuit Compilation & Constraint Systems — Leo doesn't compile to machine code—it compiles to arithmetic circuits (R1CS or similar); understanding circuit structure explains why some Leo features are restricted and why output verification is expensive
• Multi-Pass Compiler Architecture — Leo uses classic separated phases (parsing → type checking → optimization → codegen); contributing requires understanding which phase handles which errors and invariants
• Immutable AST & Tree Walks — Leo's AST is immutable and each compiler pass walks it independently; enables clear separation of concerns but requires understanding visitor/fold patterns used throughout crates/compiler/
• Type Inference & Constraint Solving — Leo's type checker uses inference (similar to Rust/Haskell) rather than explicit annotation; understanding how types flow through expressions is crucial for bug fixes in crates/compiler/src/type_checker/
• Incremental Parsing (Rowan) — Leo is migrating to rowan for IDE support; rowan enables fast reparsing of changed regions, improving LSP responsiveness; understand this for contributions to crates/parser-rowan/
• Field Arithmetic in Finite Fields — Leo programs execute in a finite field (Aleo's native field); integer overflow wraps silently, not panics; critical for understanding why Leo integers don't behave like unbounded integers

• AleoHQ/snarkVM — Low-level virtual machine and constraint system that Leo compiles to; required runtime for executing Leo programs
• AleoHQ/aleo — Blockchain platform that Leo targets; ecosystem container for ZK applications; Leo is the canonical language for Aleo programs
• zcash/halo2 — Alternative ZK proof system (not used by Leo/Aleo but conceptually related); represents competing approach to circuit abstraction
• o1-labs/o1js — JavaScript/TypeScript DSL for building ZK applications on Mina Protocol; similar problem domain (high-level ZK language) with different target blockchain
• circom-lang/circom — Domain-specific language for writing ZK circuits directly; Leo is a higher-level alternative that hides circuit details with traditional language semantics

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 integration tests for CircleCI example programs (lottery, tictactoe, token)

The repo contains three example Leo programs in .circleci/ (lottery, tictactoe, token) with build outputs and input files, but there's no comprehensive test suite validating that these examples compile and execute correctly. Given that these are reference implementations for the language, adding structured tests would catch regressions early and serve as documentation for users.

• [ ] Create a new test module in crates/test-framework/ or crates/compiler/tests/ specifically for example programs
• [ ] Add tests that invoke leo build and leo run against .circleci/lottery/src/main.leo, .circleci/tictactoe/src/main.leo, and .circleci/token/src/main.leo
• [ ] Validate that build outputs match expected program.json and main.aleo files
• [ ] Add input file execution tests using .circleci//inputs/.in files and verify execution succeeds
• [ ] Integrate into .circleci/test-examples.sh or create a new GitHub Action workflow that runs these tests on every PR

Create comprehensive LSP (Language Server Protocol) feature tests

The crates/lsp/ directory exists but there's no visible test coverage for LSP features in the file structure. Given that IDE support is critical for developer experience and the repo has axum/tower dependencies suggesting server infrastructure, adding dedicated LSP tests would improve reliability and enable new contributor contributions to language tooling.

• [ ] Create crates/lsp/tests/ directory with integration test modules
• [ ] Add tests for core LSP capabilities: hover information, code completion, diagnostics, and go-to-definition against sample .leo files
• [ ] Test LSP server initialization and shutdown sequences using a test client
• [ ] Add tests for error recovery and handling malformed Leo code without crashing
• [ ] Create GitHub Action workflow (.github/workflows/lsp-tests.yml) to run LSP tests on pull requests

Add compiler pass benchmarking and regression detection

The repo has crates/compiler/benchmarks in the workspace members list and benchmarks.yml workflow, but there's no visible integration between pass-level performance metrics and CI. Leo's multi-stage compilation (parser → AST → passes → code gen) makes tracking pass performance critical; adding structured benchmarks for each pass would help prevent performance regressions.

• [ ] Extend crates/compiler/benchmarks/ with per-pass benchmarks for leo-passes modules (type checking, dead code elimination, loop unrolling)
• [ ] Use the existing benchmarks.yml workflow to run benchmarks on main and PR branches, storing results in .github/archive/
• [ ] Add a benchmark comparison script that alerts maintainers if any pass degrades >5% in performance
• [ ] Document benchmark methodology in a BENCHMARKING.md file referencing specific .circleci example programs as test inputs
• [ ] Add benchmark results tracking to prevent silent performance regressions in the compiler

• Add missing error recovery in crates/parser/src/parser.rs for incomplete expressions—currently parser panics on let x = ; instead of emitting a recoverable error with suggestions: Low risk, high UX impact; parser error messages are the first impression users get: crates/parser/src/parser.rs, look for expect() calls that should be recover_with()
• Implement formatter for Leo comments in crates/fmt/ to match Rust's comment alignment rules—currently comments are passed through unchanged, causing alignment issues in formatted code: Self-contained feature; leo-fmt is a separate crate with clear boundaries; no compiler changes needed: crates/fmt/src/item.rs, add CommentFormatter struct
• Add unit tests for bitwise operations (&, |, ^, <<, >>) in crates/compiler/src/code_generation/ to match existing arithmetic operation coverage—currently only basic ops have dedicated tests: Mechanical but important; validates circuit generation for critical operations; existing test structure is documented and consistent: crates/compiler/src/code_generation/mod.rs, add to BinaryOpCodegenTests or create BitOpCodegenTests

The Leo codebase demonstrates generally good security practices with exact version pinning for internal dependencies and structured CI/CD. However, there are concerns regarding an exposed CircleCI token in the public README, potential sensitive test data in version control, and missing evidence of web security header configuration. The project appears to be a programming language compiler/framework with moderate security maturity. Key recommendations include removing the hardcoded token, auditing test fixtures for credentials, implementing security headers in web services, and establishing regular dependency vulnerability scanning.

• Medium · Hardcoded CircleCI Token in Repository — README.md (badge URL). The CircleCI build badge URL in README.md contains what appears to be a hardcoded CircleCI token (circle-token=00960191919c40be0774e00ce8f7fa1fcaa20c00). This token could potentially be used to access CircleCI API endpoints or trigger builds if it has sufficient permissions. Fix: Remove the explicit token from the public README. Use CircleCI's environment variables or secrets management for authentication instead. If this token is active, rotate it immediately.
• Medium · Test Fixtures and Credentials in CI Configuration — .circleci/lottery, .circleci/tictactoe, .circleci/token directories. CircleCI test examples (.circleci/lottery, .circleci/tictactoe, .circleci/token) contain build artifacts and input files that may contain sensitive test data or credentials. The .circleci/token directory is particularly concerning as it suggests token-related test data. Fix: Review all test input files for sensitive data. Use environment variables or secrets for test credentials. Consider moving sensitive test data outside the repository or using placeholder values.
• Low · Missing Security Headers Configuration — Cargo.toml dependencies and web service configuration. The Axum web framework is included in dependencies (axum = '0.8', axum-extra), but no evidence of security headers (HSTS, CSP, X-Frame-Options, etc.) configuration is visible in the provided file structure. Fix: Implement security headers middleware in any web services using Axum. Add HSTS, CSP, X-Content-Type-Options, X-Frame-Options, and other appropriate headers.
• Low · Dependency Version Pinning Best Practice — Cargo.toml workspace.dependencies. While most internal crates use exact version pinning (=4.0.2), some external dependencies use flexible version specifications (e.g., 'anyhow = "1.0"', 'aleo-std = "1.0.3"'). This could allow minor/patch version updates that introduce vulnerabilities. Fix: Consider using more restrictive version specifications (e.g., '=1.0.3' instead of '1.0.3') for critical dependencies, or use a lockfile for reproducible builds. Implement regular dependency audits using 'cargo audit'.
• Low · Potential Information Disclosure in Error Output — Cargo.toml (backtrace, color-backtrace, ariadne dependencies). The backtrace (backtrace = '0.3'), color-backtrace, and detailed error reporting dependencies suggest detailed error information may be exposed to users. This could leak internal implementation details in production. Fix: Ensure detailed backtraces and error messages are only exposed in development/debug builds. Implement proper error handling that provides user-friendly messages in production while logging detailed errors server-side.

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

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

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/ProvableHQ/leo 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.

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

What it runs against: a local clone of ProvableHQ/leo — 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 ProvableHQ/leo | 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 master 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 ProvableHQ/leo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ProvableHQ/leo.git
#   cd leo
#
# 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 ProvableHQ/leo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ProvableHQ/leo(\\.git)?\\b" \\
  && ok "origin remote is ProvableHQ/leo" \\
  || miss "origin remote is not ProvableHQ/leo (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "crates/ast/src/common/mod.rs" \\
  && ok "crates/ast/src/common/mod.rs" \\
  || miss "missing critical file: crates/ast/src/common/mod.rs"
test -f "crates/compiler/Cargo.toml" \\
  && ok "crates/compiler/Cargo.toml" \\
  || miss "missing critical file: crates/compiler/Cargo.toml"
test -f "crates/errors/src/lib.rs" \\
  && ok "crates/errors/src/lib.rs" \\
  || miss "missing critical file: crates/errors/src/lib.rs"
test -f "ARCHITECTURE.md" \\
  && ok "ARCHITECTURE.md" \\
  || miss "missing critical file: ARCHITECTURE.md"

# 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/ProvableHQ/leo"
  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).

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