🐍 Cairo-vm-py 🐍

FFI Python bindings for cairo-vm

Report Bug · Request Feature

Table of Contents

• About
• Getting Started
  • Dependencies
  • Installation
• Usage
  • Testing
  • Demo
  • How to manually install the script dependencies
• Benchmarking
• Related Projects
• License

📖 About

cairo-vm-py adds Python bindings to the Cairo VM.

🌅 Getting Started

Dependencies

• Rust and Cargo
• Pyenv and Python 3.9
• GMP
• make

Installation

To set up the Python environment, and install necessary Python libraries, run make deps. This command builds two virtual environments, one intended for the Rust VM and the other one for the Original Python VM. It also initializes the submodules of some of the projects we integrated with.

After setting up the environments, you can install the python binary using maturin develop --release.

Finally, install into the Python environment with maturin develop --release. For mac installation, these flags might be necessary: maturin develop --release -m cairo-vm-py/Cargo.toml --no-default-features --features extension.

🚀 Usage

After installation, you can access the Cairo VM from Python code. As an example, after compiling the program array_sum into cairo_programs/array_sum.json, you can run it with the VM using:

import cairo_vm_py

with open(f"cairo_programs/array_sum.json") as file:
    runner = cairo_vm_py.CairoRunner(file.read(), "main", "all", False)
    runner.cairo_run(True)

Testing

To run the test suite:

make full-test

Demo

The build_envs.sh script will build two Python virtual environments:

• cairo-lang containing a pristine installation of cairo-lang==0.10.3;
• cairo-vm-py containing a patched installation of cairo-lang==0.10.3 that uses cairo-vm-py as dependency. It will also install the required dependencies automatically in Debian-based distributions, CentOs, Fedora and OSX. If you use another OS, you can check how to install them manually below.

To run the script:

./scripts/build_envs.sh

Both virtual environment will be created under the /scripts directory.

To actually use any of the implementations, you would have to activate the environment you want. For example, to use the cairo-vm-py integration you need to run:

source scripts/cairo-vm-py/bin/activate

After activating the cairo-vm-py virtualenv you can try out any Cairo project and it will use cairo-vm. In some cases some projects are coupled to cairo-run or need some extra patching to be able to use the cairo-vm runner (e.g. Protostar, Zerosync).

Note that the script assumes you have a Rust toolchain, Python 3.9 and the venv program installed.

How to manually install the script dependencies

cairo-lang requires the gmp library to build. You can install it on Debian-based GNU/Linux distributions with:

sudo apt install -y libgmp3-dev

In Mac you can use Homebrew:

brew install gmp

In Mac you'll also need to tell the script where to find the gmp lib:

export CFLAGS=-I/opt/homebrew/opt/gmp/include LDFLAGS=-L/opt/homebrew/opt/gmp/lib
sh build_envs.sh

📊 Benchmarking

To run the benchmarks of the projects we integrated with, first you need to set up the dependencies:

make benchmark-deps

Lastly, run make + the project you desire to try:

benchmark-devnet

🌞 Related Projects

• cairo-vm: A fast implementation of the Cairo VM in Rust.
• starknet_in_rust: implementation of Starknet in Rust, powered by the cairo-vm.

⚖️ License

This project is licensed under the Apache 2.0 license.

See LICENSE for more information.