Cairo-vm

Cairo VM

Cairo-vm ⚡ is a faster and safer implementation of the Cairo VM, written in 🦀 Rust 🦀. This project offers a robust environment for compiling and running Cairo programs, optimized for performance and security.

Cairo VM is the virtual machine for the Cairo language. Previously, Cairo VM was written in Python, but this newer version in Rust offers improved speed, safety, and expressive typing. It has replaced the older Python version to become the primary Cairo VM.

Cairo is the first production-grade platform for generating STARK proofs for general computation. It is Turing-complete and was created by Starkware as part of the Starknet ecosystem.

These dependencies are needed to compile and use the project:

• Rust 1.74.1 or newer
• Cargo

These dependencies are only necessary to run the original VM, compile Cairo programs, and run tests:

• make
• PyEnv

You can install all required and optional dependencies by running the install.sh script from the repository root.

To compile programs, install the cairo-lang package. Use the following command to create a virtual environment with all the required dependencies:

make deps

For macOS users, use:

make deps-macos

Activate the environment by running:

. cairo-vm-env/bin/activate

To add Cairo-vm to your Rust project, include the following in your Cargo.toml file:

cairo-vm = { version = '0.7.0' }

Compile the repository from the cairo-vm-cli folder:

cd cairo-vm-cli; cargo build --release; cd ..

The binary will be located in target/release/ under the name cairo-vm-cli.

Activate the environment created during installation:

. cairo-vm-env/bin/activate

To compile a program, use:

cairo-compile [path_to_the_.cairo_file] --output [desired_path_of_the_compiled_.json_file]

For example:

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

To run a compiled .json program through the VM:

target/release/cairo-vm-cli cairo_programs/abs_value_array_compiled.json --layout all_cairo

The --layout flag determines which builtins can be used. More information about layouts can be found in the documentation.

Cairo-vm-cli supports several optional arguments, including:

• --trace_file <TRACE_FILE>
• --memory_file <MEMORY_FILE>
• --print_output
• --proof_mode
• --secure_run
• --air_public_input <AIR_PUBLIC_INPUT>
• --air_private_input <AIR_PRIVATE_INPUT>
• --cairo_pie_output <CAIRO_PIE_OUTPUT>
• --allow_missing_builtins
• run_from_cairo_pie

For example, to obtain the air public inputs from a Fibonacci program run:

target/release/cairo-vm-cli cairo_programs/proof_programs/fibonacci.json --layout all_cairo --proof_mode --air_public_input fibonacci_public_input.json

This VM is under construction and currently supports a limited number of Python hints. Non-standard hints can be used by:

• Extending the cairo-vm code and building your own binary using the HintProcessor interface.
• Using cairo-vm-py, which supports running any hint in a Python interpreter.

To run a Cairo program directly, specify the program and prepare the VM, cairo_runner, hint processor, and entrypoint:

let program = Program::from_file(Path::new(&file_path), None);
let mut cairo_runner = CairoRunner::new(&program, LayoutName::all_cairo, false, false);
let mut hint_processor = BuiltinHintProcessor::new_empty();
let entrypoint = program.identifiers.get(&format!("__main__.{}", &func_name))?.pc;
cairo_runner.initialize_builtins(false)?;
cairo_runner.initialize_segments(None);

For Starknet devnet, additional parameters are required for the run_from_entrypoint method.

Navigate to the folder cd cairo1-run and follow the cairo1-run documentation.

A demo on using cairo-vm with WebAssembly is available in examples/wasm-demo.

To run the test suite, install cargo-llvm-cov dependency:

make deps

Run the test suite with:

make test

Cairo-vm includes a tracer for visualizing memory and register changes during execution. More information can be found here.

Running a Cairo program to get the 1.5 millionth Fibonacci number provides benchmarks, including execution time with Criterion and flamegraph results. Ensure Valgrind is installed for the iai_benchmark.

Run the complete benchmark suite with:

cargo bench

Run only the criterion_benchmark suite with:

cargo bench --bench criterion_benchmark

Run only the iai_benchmark suite with:

cargo bench --bench iai_benchmark

Benchmark the cairo-vm in a hyper-threaded environment with:

make hyper-threading-benchmarks