revive/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Revive is a Solidity compiler targeting RISC-V on PolkaVM. It uses solc (Ethereum Solidity compiler) as the frontend and LLVM as the backend. The main compiler binary is resolc.

Compilation pipeline:

1. solc lowers Solidity source to Yul IR
2. revive lowers Yul IR to LLVM IR
3. LLVM optimizes and emits RISC-V ELF via LLD
4. PolkaVM linker creates the final PolkaVM blob

Build Commands

Prerequisites: Requires LLVM_SYS_221_PREFIX environment variable pointing to a compatible LLVM 18.1.8 build. Download from releases or build with make install-llvm.

# Install resolc binary
make install-bin

# Run all quality checks (format, clippy, machete, tests)
make test

# Individual test targets
make test-workspace      # All workspace tests (excludes llvm-builder)
make test-integration    # Integration tests (requires resolc + geth evm tool)
make test-resolc         # resolc package tests
make test-yul            # Yul parser tests

# Linting
make format              # Check formatting (cargo fmt --all --check)
make clippy              # Run clippy with --deny warnings

For verifying work, claiming a task done, or pre-commit checks: only ever run make test* targets — never raw cargo test. Integration and resolc tests invoke the installed resolc binary as a subprocess. Each make test* target already declares install-bin (or install) as a dependency, so it always rebuilds and installs a fresh binary before running tests. Raw cargo test does not — it builds the test binary but leaves system resolc stale, so it passes against code the test isn't actually exercising. That mismatch is exactly why raw cargo test is an anti-pattern for validation.

The one legitimate exception is actively debugging a single test for fast iteration: run make install-bin first to refresh the binary, then iterate with cargo test --package <crate> <test_name>, re-running make install-bin between code changes. Never use this exception for validation.

Crate Architecture

All crates live in crates/. Key crates:

• resolc - Compiler driver binary and library; orchestrates the full pipeline
• revive-yul - Yul lexer, parser, and LLVM IR lowering; implements visitor pattern for AST traversal
• revive-llvm-context - LLVM code generation logic (decoupled from parser)
• revive-linker - Links RISC-V ELF to PolkaVM blob via LLD and polkavm-linker
• revive-runner - Executes contracts in simulated pallet-revive runtime; provides declarative test spec format
• revive-integration - Integration test cases using revive-runner
• revive-differential - Differential testing utilities against EVM
• revive-runtime-api - Low-level runtime API bindings to pallet-revive
• revive-stdlib - Compiler standard library components
• revive-common - Shared constants and utilities
• lld-sys - FFI bindings to LLVM's LLD linker

Testing Strategy

Integration tests use differential testing against the Ethereum solc/EVM stack. Test specs are declarative JSON that define contract actions:

{
    "differential": true,
    "actions": [
        {"Instantiate": {"code": {"Solidity": {"contract": "ContractName"}}}},
        {"Call": {"dest": {"Instantiated": 0}, "data": "..."}}
    ]
}

When differential: true, actions run on both EVM and PVM, asserting identical state changes.

Running integration tests requires the evm tool from go-ethereum in $PATH.

Code Style Requirements

• Use BTreeMap instead of HashMap for deterministic iteration (reproducible builds)
• Avoid magic numbers/strings; use module constants
• Avoid abbreviated names; use meaningful, readable symbols
• No unnecessary macros
• Avoid import aliasing; use parent/qualified paths for conflicts
• Public items must have doc comments
• Comments should provide semantic meaning, not restate code

Dependencies

• Add as workspace dependencies in root Cargo.toml
• Avoid pinning when possible
• Always include Cargo.lock in PRs
• Don't run cargo update with other changes (separate PR)