Giter Site home page Giter Site logo

omerfirmak / cairo-rs Goto Github PK

View Code? Open in Web Editor NEW

This project forked from lambdaclass/cairo-vm

0.0 0.0 0.0 6.76 MB

cairo-rs is a Rust implementation of the Cairo VM. Cairo (CPU Algebraic Intermediate Representation) 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.

Home Page: https://lambdaclass.github.io/cairo-rs

License: Apache License 2.0

Shell 0.24% Python 0.12% Rust 88.48% Makefile 0.44% Cairo 10.73%

cairo-rs's Introduction

⚡ Cairo-rs ⚡

A faster and safer implementation of the Cairo VM in Rust

Report Bug · Request Feature

rust codecov license pr-welcome Telegram Chat

Table of Contents

⚠️ Disclaimer

🚧 cairo-rs is still being built therefore breaking changes might happen often so use it at your own risk. 🚧 Cargo doesn't comply with semver, so we advise to pin the version to 0.1.0. This can be done adding cairo-vm = "0.1.0" to your Cargo.toml

📖 About

Cairo VM is the virtual machine for the Cairo language.

There's an older version of Cairo VM written in Python, which is currently in production.

This repository contains the newer version, written in Rust. It's faster and has safer and more expressive typing. Once completed, it will replace the older one as the sole 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

Optional

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

  • PyEnv with Python 3.9
  • cairo-lang

🚀 Usage

Running cairo-rs

To compile the repository, run:

cargo build --release

Once the binary is built, it can be found in target/release/ under the name cairo-rs-run.

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, call the executable giving it the path and name of the file to be executed. For example:

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

The flag --layout 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:

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_cairo

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-rs code and build your own binary using the interface hint processor
  • Use cairo-rs-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-rs repository you would first need to prepare a couple of things.

  1. Specify the Cairo program you want to run
let program =
        Program::from_file(Path::new(&file_path), None);
  1. Instantiate the VM, the cairo_runner, the hint processor, and the entrypoint
let mut vm = VirtualMachine::new(false);

let mut cairo_runner = CairoRunner::new(&program, "all_cairo", 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 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.

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

WebAssembly Demo

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

Testing

To run the test suite you'll need cargo-llvm-cov dependency so make sure to run this command beforehand:

make deps

Now that you have the dependencies necessary to run the test suite you can run:

make test

📊 Benchmarks

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

Note before running the benchmark suite: the benchmark named iai_benchmark depends on Valgrind. Please make sure it is installed prior to running the iai_benchmark benchmark.

Run the complete benchmark suite with cargo:

cargo bench

Run only the criterion_benchmark benchmark suite with cargo:

cargo bench --bench criterion_benchmark

Run only the iai_benchmark benchmark suite with cargo:

cargo bench --bench iai_benchmark

📜 Changelog

Keeps track of the latest changes here.

🛠 Contributing

The open-source community is a fantastic place for learning, inspiration, and creation, and this is all thanks to contributions from people like you. Your contributions are greatly appreciated.

If you have any suggestions for how to improve the project, please feel free to fork the repo and create a pull request, or open an issue with the tag 'enhancement'.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

And don't forget to give the project a star! ⭐ Thank you again for your support.

🌞 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:

⚖️ License

This project is licensed under the Apache 2.0 license.

See LICENSE for more information.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.