/cairo-rs

Cleopatra Cairo is a Rust implementation of the Cairo VM. Cairo is a programming language for writing provable programs, where one party can prove to another that a certain computation was executed correctly. Cairo and similar proof systems can be used to provide scalability to blockchains.

Primary LanguageRustMIT LicenseMIT

cairo-rs

rust benchmark codecov

Table of Contents

About

cairo-rs is a Rust implementation of the Cairo VM.

The code of the original Cairo VM can be found here.

Getting Started

Dependencies

  • Rust
  • Cargo
  • PyEnv for running the original VM and compiling cairo programs
  • cairo-lang (optional)

Usage

Running cairo-rs

Compile with cargo build --release, once the binary is built, it can be found in target/release/ under the name cairo-rs-run. To run a compiled json program through the VM, call the executable giving it the path and name of the file to be executed.

Full compilation and execution example:

git clone https://github.com/lambdaclass/cairo-rs.git

cd cairo-rs

cargo build --release

cairo-compile cairo_programs/abs_value_array.cairo --output cairo_programs/abs_value_array_compiled.json

target/release/cairo-rs-run cairo_programs/abs_value_array_compiled.json --layout all

Running a function in a Cairo program with arguments

When running a Cairo program directly using the Cairo-rs repository you would first need to prepare a couple of things.

  1. Specify the cairo program and the function you want to run
let program =
        Program::from_file(Path::new(&file_path), Some(&func_name));
  1. Instantiate the VM, the cairo_runner, the hint processor, and the entrypoint
let mut vm = VirtualMachine::new(
            BigInt::new(Sign::Plus, vec![1, 0, 0, 0, 0, 0, 17, 134217728]),
            false,
        );

let mut cairo_runner = CairoRunner::new(&program, "all", false);

let mut hint_processor = BuiltinHintProcessor::new_empty();

let entrypoint = program
        .identifiers
        .get(&format!("__main__.{}", &func_name))?
        .pc;
  1. Lastly, initialize the builtins and segments.
cairo_runner.initialize_builtins(&mut vm)?;
cairo_runner.initialize_segments(&mut vm, None);

When using cairo-rs with the starknet devnet there are additional parameters that are part of the OS context passed on to the run_from_entrypoint function that we do not have here when using it directly. These parameters are, for example, initial stacks of the builtins, which are the base of each of them and are needed as they are the implicit arguments of the function.

 let _var = cairo_runner.run_from_entrypoint(
            entrypoint,
            vec![
                &mayberelocatable!(2),  //this is the entry point selector
                &MaybeRelocatable::from((2,0)) //this would be the output_ptr for example if our cairo function uses it
                ],
            false,
            true,
            true,
            &mut vm,
            &mut hint_processor,
        );

WebAssembly Demo

A demo on how to use cairo-rs with WebAssembly can be found here.

Testing

Run the test suite:

make test

Code Coverage

Track of the project's code coverage: Codecov.

Benchmarks

Running a Cairo program that gets the 1000th Fibonacci number we got the following benchmarks:

Run the benchmark suite with cargo:

cargo bench

Related Projects

  • starknet_in_rust: implementation of Starknet in Rust, powered by the cairo-rs VM.
  • cairo-rs-py: Bindings for using cairo-rs from Python code.

Documentation

Cairo

Original Cairo VM Internals

We wrote a document explaining how the Cairo VM works. It can be found here.

Compilers and Interpreters

This is a list of recommended books to learn how to implement a compiler or an interpreter.

StarkNet

Computational Integrity and Zero Knowledge Proofs

Basics

ZK SNARKs

STARKs

Introduction:

Vitalik Buterin's blog series on zk-STARKs:

Alan Szepieniec's STARK tutorial:

StarkWare's STARK Math blog series:

Possible changes for the future

  • Make the alloc functionality an internal feature of the VM rather than a hint.

Changelog

Keep track of the latest changes here.

License

MIT