Lib.rs

⚡ Cairo-vm ⚡

在Rust中实现的开罗虚拟机的更快、更安全的版本

报告错误 · 请求功能

目录

• 目录
• 📖 关于
  • 开罗语言
• 🌅 入门
  • 依赖项
    • 必需
    • 可选
    • 安装脚本
• 🚀 使用
  • 将cairo-vm作为依赖项添加
  • 从CLI运行cairo-vm
  • 使用提示
  • 在开罗程序中运行带有参数的函数
  • WebAssembly演示
  • 测试
  • 追踪器
• 📊 基准
• 📜 更新日志
• 🛠 贡献
• 🌞 相关项目
• 📚 文档
  • Cairo
  • 原始开罗虚拟机内部结构
  • 编译器和解释器
  • StarkNet
  • 计算完整性和零知识证明
    • 基础
    • ZK SNARKs
    • STARKs
• ⚖️ 许可证

📖 关于

开罗虚拟机是开罗语言的虚拟机。

之前有一个用Python编写的开罗虚拟机版本，该版本曾在生产中使用。

本存储库包含较新版本的代码，使用Rust编写。它速度更快，类型更安全，表达性更强。现在已投入生产，已取代旧的Python版本，成为主要的Cairo虚拟机。

开罗语言

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

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

🌅 入门

依赖项

必需

以下是编译和使用项目所需的。

• Rust 1.76.0或更高版本
• Cargo

可选

这些依赖项仅用于运行原始虚拟机、编译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'}

从CLI运行cairo-vm

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

cd cairo-vm-cli; cargo build --release; cd ..

二进制文件构建完成后，可以在target/release/下找到，名称为cairo-vm-cli。

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

. cairo-vm-env/bin/activate

要编译程序，请使用cairo-compile [path_to_the_.cairo_file] --output [desired_path_of_the_compiled_.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公共输入输出到该文件。如果启用证明模式，则可以使用。

• --air_private_input <AIR_PRIVATE_INPUT>：接收文件名并将AIR私有输入输出到该文件。如果启用证明模式、跟踪文件和内存文件，则可以使用。

• --cairo_pie_output <CAIRO_PIE_OUTPUT>：接收文件名并将Cairo PIE输出到该文件。只有在proof_mode未启用时才能使用。

• --allow_missing_builtins：禁用检查程序使用的所有内置函数是否包含在所选布局中的功能。在proof_mode中默认启用。

• run_from_cairo_pie：运行Cairo PIE而不是编译后的json文件。文件名将是CLI接收到的第一个参数（就像运行一个正常的编译程序一样）。只有在proof_mode未启用时才能使用。

例如，要从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虚拟机允许用户运行任何Python代码。

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

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

在开罗程序中运行带有参数的函数

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

1. 指定您想要运行的Cairo程序

let program =
        Program::from_file(Path::new(&file_path), None);

2. 实例化VM、cairo_runner、hint_processor和entrypoint

let mut cairo_runner = CairoRunner::new(&program, LayoutName::all_cairo, false, false);

let mut hint_processor = BuiltinHintProcessor::new_empty();

let entrypoint = program
        .identifiers
        .get(&format!("__main__.{}", &func_name))?
        .pc;

3. 最后，初始化内置函数和段。

cairo_runner.initialize_builtins(false)?;
cairo_runner.initialize_segments(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 hint_processor,
        );

运行cairo 1程序

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

WebAssembly演示

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

测试

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

make deps

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

make test

追踪器

Cairo-vm提供了一个跟踪器，它以可视化的方式显示虚拟机执行代码时内存和寄存器逐行变化的情况。您可以在这里了解更多信息这里

📊 基准

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

• 使用Criterion的执行时间
• 火焰图
• Github动作结果

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

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

cargo bench

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

cargo bench --bench criterion_benchmark

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

cargo bench --bench iai_benchmark

在超线程环境中基准测试 cairo-vm，使用以下示例 examples/hyper_threading/ crate

make hyper-threading-benchmarks