Cairo-vm

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.

📖 About

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.

The Cairo Language

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.

🌅 Getting Started

Dependencies

Required

These dependencies are needed to compile and use the project:

  • Rust 1.74.1 or newer
  • Cargo

Optional

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

  • make
  • PyEnv

Installation Script

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

🚀 Usage

Adding Cairo-vm as a Dependency

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

cairo-vm = { version = '0.7.0' }

Running Cairo-vm from CLI

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.

Other CLI Arguments

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

Using Hints

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.

Running a Function in a Cairo Program with Arguments

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.

Running Cairo 1 Programs

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

WebAssembly Demo

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

Testing

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

make deps

Run the test suite with:

make test

Tracer

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

📊 Benchmarks

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

Similar Projects

Rustfinity.com

Links

  1. Home
  2. Learn Rust
  3. Get Started
  4. Practice Rust
  5. Challenges
  6. Tutorials
  7. Blog
  8. Open source
  9. Learn Gleam

Socials

  1. GitHub
  2. X

Legal

  1. Privacy Policy
  2. Terms of Service