Rue

Rue is a statically typed programming language that compiles to CLVM bytecode. It's designed as an alternative to Chialisp for writing coin puzzles on the Chia blockchain.

Docs · Playground · Discord

fn main(public_key: PublicKey, conditions: List<Condition>) -> List<Condition> {
    let agg_sig = AggSigMe { public_key, message: tree_hash(conditions) };
    [agg_sig, ...conditions]
}

Highlights

• Type safe: Structs, generics, type guards, and flow-sensitive narrowing catch entire classes of mistakes at compile time, before a puzzle ever touches the chain.
• Optimized: The compiler works hard to minimize the size and runtime cost of the generated bytecode.
• Familiar: A simplified, Rust-like syntax that feels more at home for most developers than Lisp.
• Batteries included: A standard library with conditions, tree hashing, currying, singletons, offers, and more.
• Tooling: A built-in test runner, formatter, CLVM debugger, and language server.

Installation

Install the CLI from crates.io:

cargo install rue-cli

See the Installation page for more options. If you just want to try the language, the Playground runs entirely in your browser.

Quick Start

Create a new project:

rue init my-project
cd my-project

This creates a Rue.toml manifest and a puzzles/main.rue entrypoint:

fn main() -> String {
    "Hello, world!"
}

Compile it to CLVM:

$ rue build
(q . "Hello, world!")

CLI

Command	Description
rue init [path]	Create a new project with a Rue.toml manifest.
rue build [file]	Compile the project (or a single file) and print the CLVM output.
rue test [file]	Run every test fn in the project (or a single file).
rue fmt [paths...] [--check]	Format Rue source files, or check that they're already formatted.
rue debug <program> [solution]	Run a CLVM program against a solution and print the result.
rue lints	List every lint, along with its default level.

Useful build flags:

• --export <name> - compile a specific exported function instead of main
• --hex - output serialized bytecode as hex
• --hash - output the tree hash of the compiled program
• --debug - include debug information such as assertion messages
• --all - compile every export in the project and write each one to a file (next to its source, or in dist_dir if set in Rue.toml)

Lints

Warnings such as unused bindings or unnecessary casts are lints, which can be configured to be allowed, reported as warnings, or denied (which fails compilation). Run rue lints to see every lint and its default level.

Levels can be set in Rue.toml:

[lints]
unused_binding = "deny"
unnecessary_cast = "allow"

They can also be overridden for a single build or test with -A/--allow, -W/--warn and -D/--deny, which take precedence over Rue.toml. If a lint is passed more than once, the last flag wins:

rue build -D unused_binding -A unused_import

Testing

Tests are just functions marked with test, and they live right alongside your code:

fn factorial(num: Int) -> Int {
    if num > 1 {
        num * factorial(num - 1)
    } else {
        1
    }
}

test fn factorial_works() {
    assert factorial(0) == 1;
    assert factorial(5) == 120;
}

rue test

Examples

The examples directory contains small programs like FizzBuzz, a JSON parser, and a Brainf*ck interpreter, as well as real-world puzzles such as a CAT, singleton, and royalty split.

Warning

The example puzzles have not been audited and are for educational purposes only.

Repository Layout

Path	Description
crates/rue-cli	The rue command line tool.
crates/rue-compiler	The compiler driver and the standard library.
crates/rue-lexer, rue-parser, rue-ast	Tokenizing, parsing, and the syntax tree.
crates/rue-hir, rue-types	Semantic analysis and the type system.
crates/rue-lir	Low-level IR, optimization, and CLVM code generation.
crates/rue-formatter	The source code formatter.
crates/rue-lsp	The language server.
wasm	WebAssembly bindings for the compiler.
playground	The web-based Rue Playground.
tests	Snapshot tests for the compiler.

Contributing

Contributions are welcome! The project builds with a stable Rust toolchain (pinned in rust-toolchain.toml).

# Run the full test suite
cargo test --workspace

# Regenerate the .yaml snapshots for tests/ and examples/ (optionally filtered by name)
cargo run -p rue-tests [filter]

# Lint and format
cargo clippy --workspace --all-targets
cargo fmt --all
cargo run -p rue-cli -- fmt 'examples/**/*.rue' 'tests/**/*.rue' 'crates/rue-compiler/src/std/**/*.rue'

Each .rue file in tests and examples has a matching .yaml snapshot with its compiled output, runtime cost, and test results. Review snapshot diffs carefully, since they show exactly how a change affects the generated bytecode.

To run the playground locally:

cd wasm && pnpm install && pnpm build
cd ../playground && pnpm install && pnpm dev

Community

Join the Sage Discord to get help with Rue, suggest ideas, or chat about the project.

License

Rue is licensed under the Apache License 2.0.