Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: rename cairo-rs-py to cairo-vm-py #1296

Merged
merged 7 commits into from
Jun 29, 2023
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

#### Upcoming Changes

* chore: change mentions of *cairo-rs-py* to *cairo-vm-py*

* fix: add `to_bytes_be` to the felt when `lambdaworks-felt` feature is active [#1290](https://github.com/lambdaclass/cairo-vm/pull/1290)

* chore: mark `modpow` and `to_signed_bytes_le` as *deprecated* [#1290](https://github.com/lambdaclass/cairo-vm/pull/1290)
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ Currently, as this VM is under construction, it's missing some of the features o
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 [HintProcessor](docs/hint_processor/README.md).
- Use [cairo-rs-py](https://github.com/lambdaclass/cairo-rs-py) which supports running any hint in a Python interpreter.
- Use [cairo-vm-py](https://github.com/lambdaclass/cairo-vm-py) which supports running any hint in a Python interpreter.

### Running a function in a Cairo program with arguments

Expand Down Expand Up @@ -258,7 +258,7 @@ You can find more detailed instructions in the [CONTRIBUTING.md](CONTRIBUTING.md
## 🌞 Related Projects

- [starknet_in_rust](https://github.com/lambdaclass/starknet_in_rust): implementation of Starknet in Rust, powered by the cairo-rs VM.
- [cairo-rs-py](https://github.com/lambdaclass/cairo-rs-py): Bindings for using cairo-rs from Python code.
- [cairo-vm-py](https://github.com/lambdaclass/cairo-vm-py): Bindings for using cairo-rs from Python code.

## 📚 Documentation

Expand Down
55 changes: 29 additions & 26 deletions docs/python_rust_integration_specs.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,37 +3,40 @@ LambdaClass - StarkWare
#### 20th September 2022

### OVERVIEW
In order to allow cairo-rs to execute any Python code embedded into a Cairo program and to allow a Python context to call cairo-rs, we are adding support to provide communication of the VM state between Rust and Python via FFI bindings using PyO3, as an external crate.

In order to allow cairo-rs to execute any Python code embedded into a Cairo program and to allow a Python context to call cairo-rs, we are adding support to provide communication of the VM state between Rust and Python via FFI bindings using PyO3, as an external crate.

### GOAL
* Be able to efficiently and conveniently allow interactions between Python and cairo-rs.

* Be able to efficiently and conveniently allow interactions between Python and cairo-rs.
* Have an external crate which encapsulates the Python hint execution, and which is able to both run cairo-rs, and be imported as a Python module so that the VM can be ran from a Python process.

### SPECIFICATION
* FFI integration and functionality will be encapsulated in a crate external to cairo-rs. This crate will be called cairo-rs-py.
* The crate cairo-rs-py will behave as a cairo-rs VM wrapper, which can also be imported as a Python module.
* The cairo-rs-py VM can be run for a set number of steps.
* The cairo-rs-py VM can be run for a set number of steps, paused, and then continue its execution.
* Variables defined by a hint can only be accessed by hints implemented in the same language, i.e., Rust hints are aware only of variables defined by Rust hints and Python hints are aware only of variables defined by Python hints. By Rust hints we refer to those implemented by the built-in hint processor.
* The cairo-rs-py VM can be instantiated by a Python interpreter as a regular object.
* A Rust or Python program can instantiate one or more independent cairo-rs-py VMs, allowing for multiple coexisting VMs.
* When instantiated by a Python interpreter, that same interpreter will be used to execute Python hints.

* FFI integration and functionality will be encapsulated in a crate external to cairo-rs. This crate will be called cairo-vm-py.
* The crate cairo-vm-py will behave as a cairo-rs VM wrapper, which can also be imported as a Python module.
* The cairo-vm-py VM can be run for a set number of steps.
* The cairo-vm-py VM can be run for a set number of steps, paused, and then continue its execution.
* Variables defined by a hint can only be accessed by hints implemented in the same language, i.e., Rust hints are aware only of variables defined by Rust hints and Python hints are aware only of variables defined by Python hints. By Rust hints we refer to those implemented by the built-in hint processor.
* The cairo-vm-py VM can be instantiated by a Python interpreter as a regular object.
* A Rust or Python program can instantiate one or more independent cairo-vm-py VMs, allowing for multiple coexisting VMs.
* When instantiated by a Python interpreter, that same interpreter will be used to execute Python hints.
* Python hints have limited access to the running context (code paths, modules, scopes created by previous hints).
* The syscall handler will be instantiated before the VM run and should be available on the hint locals.
* An instance of a cairo-rs-py VM will be running either a cairo program interpretation loop or a Python hint, but not both at the same time.
* i.e. hints do not run concurrently
* The VM state shared with hints can only be accessed by a single hint at a time.
* The VM memory is private to a VM instance and cannot be shared across different VM instances.
* An instance of a VM will always run on the same thread.
* Multiple instances of a VM can run on the same thread.
* An instance of a cairo-vm-py VM will be running either a cairo program interpretation loop or a Python hint, but not both at the same time.
* i.e. hints do not run concurrently
* The VM state shared with hints can only be accessed by a single hint at a time.
* The VM memory is private to a VM instance and cannot be shared across different VM instances.
* An instance of a VM will always run on the same thread.
* Multiple instances of a VM can run on the same thread.
* Hint interaction with the VM will be restricted to:
* read-write access to memory (with the methods __setitem__ and __getitem__),
* segments manager (with the methods add, write_arg, get_segments_used_sizes, add_temporary_segments),
* ids (with the methods __setattr__ and __getattr__),
* hint execution scopes,
* read-only access to ap and fp registers.
* Nice to have:
* Drop the GIL during Rust operation to allow to parallelism when using multi-threads instead of process.
* The cairo-rs-py VM can be instantiated by a Rust program, still allowing Python hints in Cairo programs.
* Python hints are supported when running the cairo-rs-py standalone binary (as opposed to importing it from Python) only with the CPython interpreter.
* read-write access to memory (with the methods __setitem__ and __getitem__),
* segments manager (with the methods add, write_arg, get_segments_used_sizes, add_temporary_segments),
* ids (with the methods __setattr__ and __getattr__),
* hint execution scopes,
* read-only access to ap and fp registers.

* Nice to have:
* Drop the GIL during Rust operation to allow to parallelism when using multi-threads instead of process.
* The cairo-vm-py VM can be instantiated by a Rust program, still allowing Python hints in Cairo programs.
* Python hints are supported when running the cairo-vm-py standalone binary (as opposed to importing it from Python) only with the CPython interpreter.
2 changes: 1 addition & 1 deletion vm/src/types/program.rs
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ use std::path::Path;
// a `CairoRunner` becomes a bottleneck, but the following solutions were tried and
// discarded:
// - Store only a reference in `CairoRunner` rather than cloning; this doesn't work
// because then we need to introduce explicit lifetimes, which broke `cairo-rs-py`
// because then we need to introduce explicit lifetimes, which broke `cairo-vm-py`
// since PyO3 doesn't support Python objects containing structures with lifetimes.
// - Directly pass an `Arc<Program>` to `CairoRunner::new()` and simply copy that:
// there was a prohibitive performance hit of 10-15% when doing so, most likely
Expand Down
2 changes: 1 addition & 1 deletion vm/src/vm/runners/builtin_runner/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ pub const KECCAK_BUILTIN_NAME: &str = "keccak_builtin";
pub const POSEIDON_BUILTIN_NAME: &str = "poseidon_builtin";
pub const SEGMENT_ARENA_BUILTIN_NAME: &str = "segment_arena_builtin";

/* NB: this enum is no accident: we may need (and cairo-rs-py *does* need)
/* NB: this enum is no accident: we may need (and cairo-vm-py *does* need)
* structs containing this to be `Send`. The only two ways to achieve that
* are either storing a `dyn Trait` inside an `Arc<Mutex<&dyn Trait>>` or
* making the type itself `Send`. We opted for not complicating the user nor
Expand Down
2 changes: 1 addition & 1 deletion vm/src/vm/runners/cairo_runner.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1076,7 +1076,7 @@ impl CairoRunner {
}

// Iterates over the program builtins in reverse, calling BuiltinRunner::final_stack on each of them and returns the final pointer
// This method is used by cairo_rs_py to replace starknet functionality
// This method is used by cairo-vm-py to replace starknet functionality
pub fn get_builtins_final_stack(
&self,
vm: &mut VirtualMachine,
Expand Down