Lib.rs

› 密码学 › 神奇豆 › Cairo-vm
#starknet #element #vm #wasm #cairo #no-std

no-std cairo-felt

Cairo VM 的域元素表示

作者： Mario Rugiero，lambdaclass，klaus993

28 个版本 (8 个破坏性更新)

0.9.1 2023 年 11 月 16 日
0.8.7 2023 年 8 月 28 日
0.8.5 2023 年 7 月 31 日
0.8.2-hotfix12023 年 12 月 7 日
0.2.2 2023 年 3 月 28 日

#53 in 神奇豆

Download history 7736/week @ 2024-04-04 8237/week @ 2024-04-11 6136/week @ 2024-04-18 5700/week @ 2024-04-25 10130/week @ 2024-05-02 4163/week @ 2024-05-09 5586/week @ 2024-05-16 4710/week @ 2024-05-23 5417/week @ 2024-05-30 3947/week @ 2024-06-06 4333/week @ 2024-06-13 4683/week @ 2024-06-20 3331/week @ 2024-06-27 2284/week @ 2024-07-04 2970/week @ 2024-07-11 2879/week @ 2024-07-18

12,316 每月下载量
在 44 个crate中使用 (直接使用10个)

Apache-2.0

180KB
4K SLoC

⚡ Cairo-vm ⚡

在 Rust 中对 Cairo VM 的更快、更安全的实现

报告错误 · 请求功能

rust codecov license pr-welcome Telegram Chat

目录

⚠️ 免责声明

🚧 cairo-vm 正在构建中，因此可能会经常发生破坏性变更，请自行承担风险。🚧 Cargo 不遵守 semver，因此我们建议将版本锁定在 0.1.0。这可以通过将 cairo-vm = "0.1.0" 添加到您的 Cargo.toml 文件中来实现。

📖 关于

Cairo 虚拟机是 Cairo 语言 的虚拟机。

有一个用 Python 编写的较老版本的 Cairo 虚拟机，目前仍在生产中。

此存储库包含一个较新的版本，用 Rust 编写。它更快、更安全，类型表达更丰富。一旦完成，它将取代旧的版本，成为唯一的 Cairo 虚拟机。

Cairo 语言

Cairo 是生成通用计算 STARK 证明的第一个生产级平台。

它是图灵完备的，由 Starkware 创建，作为 Starknet 生态系统的一部分。

🌅 开始使用

依赖项

必需品

为了编译和使用此项目，需要以下内容。

可选

这些依赖项仅在运行原始虚拟机、编译 Cairo 程序和运行测试时是必要的。

  • make
  • PyEnv

安装脚本

您可以通过在存储库根目录下运行脚本 install.sh 来安装所有必需和可选的依赖项。

安装项目依赖项

为了编译程序，您需要安装 cairo-lang 包。

运行 make deps（如果您在 MacOS 上运行，则为 make deps-macos）命令将创建一个包含所有必需依赖项的虚拟环境。

然后您可以通过运行以下命令来激活此环境：

. cairo-vm-env/bin/activate

🚀 使用方法

将 cairo-vm 作为依赖项添加

您可以将以下内容添加到您的 rust 项目的 Cargo.toml 文件中

cairo-vm = { version = '0.7.0', features = ["lambdaworks-felt"] }

features = ["lambdaworks-felt"] 部分将使用 lambdaworks-math 作为 Felt252 的后端。这可以提高性能超过 20%，并将成为未来的默认选项。

从 CLI 运行 cairo-vm

要使用命令行运行程序，首先从 cairo-vm-cli 文件夹编译存储库

cd cairo-vm-cli; cargo build --release -F lambdaworks-felt; cd ..

-F lambdaworks-felt 部分将使用 lambdaworks-math 作为 Felt252 的后端。这可以提高性能超过 20%，并将成为未来的默认选项。

一旦构建了二进制文件，它可以在 target/release/ 下找到，名称为 cairo-vm-cli。

为了编译 Cairo 程序，您需要激活安装依赖项时创建的环境。要启动它，请运行

. cairo-vm-env/bin/activate

要编译程序，请使用 cairo-compile [路径_to_the_.cairo_file] --output [编译后的_json_file的期望路径]。例如

cairo-compile cairo_programs/abs_value_array.cairo --output cairo_programs/abs_value_array_compiled.json

要运行编译后的.json程序通过虚拟机，请调用可执行文件，并给出要执行文件的路径和名称。例如

target/release/cairo-vm-cli cairo_programs/abs_value_array_compiled.json --layout all_cairo

标志 --layout 决定了可以使用哪些内置函数。更多关于布局的信息 在这里。

总结一下，以下代码可以帮助您从零开始运行Cairo程序

git clone https://github.com/lambdaclass/cairo-vm.git

cd cairo-vm

cargo build --release

. cairo-vm-env/bin/activate

cairo-compile cairo_programs/abs_value_array.cairo --output cairo_programs/abs_value_array_compiled.json

target/release/cairo-vm-cli cairo_programs/abs_value_array_compiled.json --layout all_cairo

其他CLI参数

cairo-vm-cli支持以下可选参数

  • --trace_file <TRACE_FILE>：接收文件名，并将重定位的跟踪输出到该文件

  • --memory_file <MEMORY_FILE>：接收文件名，并将重定位的内存输出到该文件

  • --print_output：打印程序输出

  • --proof_mode：以证明模式运行程序

  • --secure_run：执行后运行安全检查。默认情况下在非证明模式下启用

  • --air_public_input <AIR_PUBLIC_INPUT>：接收文件名，并将AIR公共输入输出到该文件。只能在启用证明模式时使用

例如，要从fibonacci程序运行中获取air公共输入，我们可以运行

  target/release/cairo-vm-cli cairo_programs/proof_programs/fibonacci.json --layout all_cairo --proof_mode --air_public_input fibonacci_public_input.json

使用提示

目前，由于这个虚拟机正在建设中，它缺少原始虚拟机的一些功能。值得注意的是，这个虚拟机目前仅实现了有限的Python提示，而Python Cairo VM允许用户运行任何Python代码。

在这个虚拟机中使用非标准提示有两种方式

  • 扩展cairo-vm代码，并使用HintProcessor接口构建自己的二进制文件。
  • 使用cairo-vm-py，它支持在Python解释器中运行任何提示。

使用参数在 Cairo 程序中运行函数

当直接使用Cairo-vm仓库运行Cairo程序时，您首先需要准备一些事情。

  1. 指定您要运行的Cairo程序
let program =
        Program::from_file(Path::new(&file_path), None);
  1. 实例化虚拟机、cairo_runner、提示处理器和入口点
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. 最后，初始化内置函数和段
cairo_runner.initialize_builtins(&mut vm)?;
cairo_runner.initialize_segments(&mut vm, None);

当使用与Starknet devnet一起使用的cairo-vm时，有额外的参数是作为OS上下文传递给run_from_entrypoint方法的参数，当我们直接使用它时，这里没有这些参数。这些参数是，例如，内置函数的初始堆栈，它们是每个函数的基础，并且作为函数的隐含参数是必需的。

 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,
        );

运行cairo 1程序

要运行cairo 1程序，请进入文件夹cd cairo1-run，并遵循cairo1-run文档

WebAssembly 演示

关于如何使用cairo-vm与WebAssembly的演示可以在examples/wasm-demo中找到

测试

要运行测试套件，您需要cargo-llvm-cov依赖项，因此请确保先运行此命令

make deps

现在，您已经拥有了运行测试套件所需的依赖项，您可以运行

make test

📊 基准测试

运行获取第1.5百万个斐波那契数的Cairo程序，我们得到了以下基准测试结果

在运行基准测试套件之前请注意：名为 iai_benchmark 的基准测试依赖于Valgrind。请确保在运行 iai_benchmark 基准测试之前已安装。

使用cargo运行完整的基准测试套件

cargo bench

使用cargo仅运行 criterion_benchmark 基准测试套件

cargo bench --bench criterion_benchmark

使用cargo仅运行 iai_benchmark 基准测试套件

cargo bench --bench iai_benchmark

📜 更新日志

最新更改的跟踪请参见 此处。

🛠 贡献

开源社区是一个学习、灵感和创造的好地方，这一切都归功于像你这样的人的贡献。你的贡献受到极大的赞赏。

如果你有关于如何改进项目的建议，请随时fork存储库并创建一个pull请求，或者 打开带有'enhancement'标签的问题。

  1. Fork 项目
  2. 创建你的功能分支（git checkout -b feat/AmazingFeature）
  3. 提交你的更改（git commit -m 'feat: add some AmazingFeature'）
  4. 将更改推送到分支（git push origin feat/AmazingFeature）
  5. 打开Pull Request

别忘了给项目加星！⭐ 再次感谢你的支持。

更多详细说明请参阅 CONTRIBUTING.md 文档。

🌞 相关项目

📚 文档

Cairo

原始 Cairo VM 内部结构

我们编写了一份关于Cairo VM工作原理的文档。它可以在 此处 找到。

编译器和解释器

这是一份推荐书籍列表，帮助你学习如何实现编译器或解释器。

StarkNet

计算完整性和无知识证明

基础知识

ZK SNARKs

STARKs

简介

Vitalik Buterin关于zk-STARKs的博客系列

Alan Szepieniec的STARK教程

StarkWare的STARK Math博客系列

⚖️许可证

本项目采用Apache 2.0许可证。

更多信息请见LICENSE。

依赖项

~1–2.3MB
~50K SLoC