klaus993 / cairo-vm

⚡ Cairo-vm ⚡ A faster and safer implementation of the Cairo VM in Rust Report Bug · Request Feature [![pr-welcome]](#-contributing) [![Telegram Chat][tg-badge]][tg-url] [pr-welcome]: https://img.shields.io/static/v1?color=orange&label=PRs&style=flat&message=welcome [tg-badge]: https://img.shields.io/endpoint?url=https%3A%2F%2Ftg.sumanjay.workers.dev%2FLambdaStarkNet%2F&logo=telegram&label=chat&color=neon [tg-url]: https://t.me/LambdaStarkNet Table of Contents • Table of Contents • 📖 About • The Cairo language • 🌅 Getting Started • Dependencies • Required • Optional • Installation script • 🚀 Usage • Adding cairo-vm as a dependency • Running cairo-vm from CLI • Using hints • Running a function in a Cairo program with arguments • Testing • Tracer • 📊 Benchmarks • 📜 Changelog • 🛠 Contributing • 🌞 Related Projects • 📚 Documentation • Cairo • Original Cairo VM Internals • Compilers and Interpreters • StarkNet • Computational Integrity and Zero Knowledge Proofs • Basics • ZK SNARKs • STARKs • ⚖️ License 📖 About Cairo VM is the virtual machine for the Cairo language. Previously, there was a version of Cairo VM written in Python, which **was used in production**. This repository contains the newer version, written in Rust. It's faster and has safer and more expressive typing. Now in production, 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's Turing-complete and it was created by Starkware as part of the Starknet ecosystem. 🌅 Getting Started Dependencies Required These are needed in order to compile and use the project. • Rust 1.85.0 or newer • Cargo Optional These dependencies are only necessary in order to run the original VM, compile Cairo programs, and run tests. • make • uv You can install , a modern python package and env manager made in Rust with the following command: Installation script You can install all of the required and optional dependencies by running the script while in the repository root. Installing project dependencies In order to compile programs you need to install the cairo-lang package. Running the command will create a virtual environment with all the required dependencies. You can then activate this environment by running 🚀 Usage Adding cairo-vm as a dependency You can add the following to your rust project's : Running cairo-vm from CLI To run programs from the command line, first compile the repository from the cairo-vm-cli folder: Once the binary is built, it can be found in under the name . In order to compile Cairo programs you need to activate the environment created while installing dependencies. To start it, run: To compile a program, use . For example: To run a compiled .json program through the VM, call the executable giving it the path and name of the file to be executed. For example: The flag determines which builtins can be used. More info about layouts here. To sum up, the following code will get you from zero to running a Cairo program: Other CLI arguments The cairo-vm-cli supports the following optional arguments: • : Receives the name of a file and outputs the relocated trace into it • : Receives the name of a file and outputs the relocated memory into it • : Prints the program output • : Runs the program in proof_mode • : Runs security checks after execution. Enabled by default when not in proof_mode. • : Receives the name of a file and outputs the AIR public inputs into it. Can only be used if proof_mode is also enabled. • : Receives the name of a file and outputs the AIR private inputs into it. Can only be used if proof_mode, trace_file & memory_file are also enabled. • : Receives the name of a file and outputs the Cairo PIE into it. Can only be used if proof_mode is not enabled. • : Disables the check that all builtins used by the program need to be included in the selected layout. Enabled by default when in proof_mode. • : Runs a Cairo PIE instead of a compiled json file. The name of the file will be the first argument received by the CLI (as if it were to run a normal compiled program). Can only be used if proof_mode is not enabled. Note: When using the flag, the layout specified must be the same as the one used to create the PIE file, otherwise you may encounter compatibility issues. • : Only used with dynamic layout. Receives the name of a json file with the dynamic layout parameters. For example, to obtain the air public inputs from a fibonacci program run, we can run : Using hints Currently, as this VM is under construction, it's missing some of the features of the original VM. Notably, this VM only implements a limited number of Python hints at the moment, while the Python Cairo VM allows users to run any Python code. There are two ways to use non-standard hints in this VM: • Extend the cairo-vm code and build your own binary using the interface HintProcessor. • Use cairo-vm-py which supports running any hint in a Python interpreter. Running a function in a Cairo program with arguments When running a Cairo program directly using the Cairo-vm repository you would first need to prepare a couple of things. • Specify the Cairo program you want to run • Instantiate the VM, the cairo_runner, the hint processor, and the entrypoint • Lastly, initialize the builtins and segments. When using cairo-vm with the Starknet devnet there are additional parameters that are part of the OS context passed on to the method 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. Running cairo 1 programs To run a cairo 1 program enter in the folder and follow the Testing To run the test suite you'll need dependency so make sure to run this command beforehand: Now that you have the dependencies necessary…