ITADN
cartesi/machine-emulator
代码 动态 Issues98 合并请求181 版本35
cartesi/machine-emulator · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

Cartesi 机器模拟器

Latest Release Build Status License

Cartesi 机器模拟器是 Cartesi 可验证计算框架的基础。 它是一个可移植、确定性、高性能的 RISC-V 模拟器（又称虚拟机），可以在链下运行复杂计算，但支持通过欺诈证明进行链上验证。

在底层，该模拟器实现了 RISC-V RV64GC 指令集架构（包括非特权和特权规范）。 这使得它能够启动 Linux，进而让创建者在开发和运行其应用程序时能够访问传统的软件开发工具栈。

Cartesi 机器模拟器使用 C++ 编写，可作为独立的 CLI 应用程序或作为库嵌入到其他应用程序中。 它可以通过一个定义明确的 C API 进行控制，该 API 可以从多种编程语言轻松访问。 特别是，它可以使用 Lua 进行脚本编写，以实现快速的原型设计和测试。

TL;DR:

我可以使用 Cartesi 机器来反驳计算的不诚实结果 M' = F(M)，其中 F 是一个确定性状态转换函数，对应于在 Linux 操作系统之上运行应用程序以处理某些输入，M = (S, I) 是机器的初始状态 S 和输入 I，而 M' = (S', O') 是机器的最终状态 S' 及其输出 O'。

功能

  • Powerful
    • High-performance RISC-V emulation, delivering high execution speed for demanding applications.
    • Complete RISC-V RV64GC ISA support, covering both privileged and unprivileged specifications.
    • Linux kernel execution, enabling running of standard Linux distributions (e.g., Ubuntu).
    • Full-featured Linux environment, enabling applications to use traditional software stacks.
    • Large state address space, enabling applications to utilize gigabytes of data.
    • Forking support, enabling parallel execution and efficient rollback of state transitions.
    • State inspection capabilities, enabling examination of the entire address space and processor.
  • Developer Friendly
    • Simple C API, facilitating integration with various languages (e.g., C++, Rust, Go, Python, JavaScript).
    • Lua scripting interface, for rapid prototyping and testing.
    • JSON-RPC API endpoint, enabling remote machine control.
    • Interactive CLI application, for prototyping in the terminal.
    • VirtIO network and shared filesystem devices, allowing access to host state during prototyping.
    • State serialization, for storing and loading of machine snapshots.
  • Verifiable
    • Deterministic execution, ensuring every instruction is reproducible (including floating-point).
    • State Merkle tree computation, for generating cryptographic proofs.
  • 状态转换访问日志，支持对状态转换进行链上验证。
    • 周期级执行控制，用于交互式欺诈证明二分法。
    • 基于微架构的仿真，用于简化其解释器的链上验证。
    • 通用 I/O 接口，支持通过状态转换处理数据输入/输出。
  • 可移植性
    • 跨平台兼容性，包括 Linux、macOS 和 Windows。
    • WebAssembly 兼容性，将所有功能带到浏览器环境中。
    • 独立编译，适合嵌入到其他应用程序中（例如，在 zkVM 中）。
    • 最小运行时依赖，确保轻松安装和集成。
    • RISC Zero zkVM 集成，支持机器状态转换的零知识证明。

概述

如需全面了解 Cartesi Machine 模拟器及其区块链用例， 您可以观看由 Cartesi Machine 首席架构师 Diego Nehab 在 Ethereum Engineering Group 上进行的这场详细演示：

Cartesi Machine Overview

此外，你可以在 Cartesi 的 YouTube 频道上观看关于 Cartesi Machine 的 Diego Nehab 的精彩访谈：

Cartesi Machine Deep Dive

入门指南

安装

我们为部分发行版提供官方软件包，但您也可以从源码构建。

注意： 下面列出的官方软件包仓库目前尚不可用。这些说明介绍了软件包可用后的安装过程。

Debian 或 Ubuntu

我们维护了一个 APT 软件包仓库，其中包含 amd64、arm64 和 riscv64 的二进制软件包，您可以使用以下命令安装：

# Add package repository
wget -qO - https://dist.cartesi.io/apt/keys/cartesi-deb-key.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/cartesi-deb-key.gpg
echo "deb https://dist.cartesi.io/apt stable/" | sudo tee /etc/apt/sources.list.d/cartesi-deb-apt.list
sudo apt-get update
# Install cartesi-machine
sudo apt-get install cartesi-machine

本 APT 仓库中提供的软件包已知可与 Debian 13 (Trixie) 和 Ubuntu 24.04 (Noble) 配合使用。

Alpine Linux

我们维护了一个 APK 软件包仓库，其中包含 amd64、arm64 和 riscv64 的二进制软件包，您可以通过以下方式安装：

# Add package repository
wget -qO /etc/apk/keys/cartesi-apk-key.rsa.pub https://dist.cartesi.io/apk/keys/cartesi-apk-key.rsa.pub
echo "https://dist.cartesi.io/apk/stable" >> /etc/apk/repositories
apk update
# Install cartesi-machine
apk add cartesi-machine

Arch Linux

我们在 AUR 中维护了一个官方的 Arch Linux 软件包，你可以使用以下命令安装：

yay -S cartesi-machine

Homebrew

我们为 macOS 维护了一个 Homebrew tap，您可以通过以下方式安装：

brew tap cartesi/tap
brew install cartesi-machine

来源

系统要求
  • 支持 C++23 的 C++ 编译器（已在 GCC >= 14.x 和 Clang >= 19.x 上测试）。
  • GNU Make >= 3.81
  • Boost >= 1.83
  • Lua >= 5.4.6（可选，脚本支持和交互式终端所需）
  • Libslirp >= 4.6.0（可选，网络支持所需）
  • Rust 和 RISC Zero 工具链（可选，构建 RISC Zero prover 所需）
Debian 要求
sudo apt-get install build-essential git wget libgomp-dev libboost1.83-dev liblua5.4-dev libslirp-dev lua5.4
MacPorts 要求
sudo port install clang libomp boost181 wget pkgconfig lua54 libslirp
Homebrew 要求
brew install llvm libomp boost wget pkg-config lua libslirp
RISC Zero 要求（可选）

如果您想要构建 RISC Zero prover，您需要 Rust 和 RISC Zero 工具链。首先通过 rustup 安装 Rust，然后：

cargo install rzup
rzup install rust
rzup install cpp
rzup install r0vm

然后使用 make risc0 进行构建。

Foundry 要求（可选，仅适用于 Solidity 测试）
curl -L https://foundry.paradigm.xyz | bash
foundryup

构建

首先，确保已满足所有系统要求，然后运行以下命令以构建并安装该设备的稳定版本：

# clone a stable branch of the emulator
git clone --branch v0.21.0 https://github.com/cartesi/machine-emulator.git
cd machine-emulator

# patch the sources with required generated files
wget https://github.com/cartesi/machine-emulator/releases/download/v0.21.0/add-generated-files.diff
git apply add-generated-files.diff

# compile
make

注意：我们建议仅运行稳定版本。如果您希望构建 main 开发分支，则需要重新生成文件而不是修补源代码，这要求您的系统上安装 Docker。更多详情请参阅我们的开发指南。

最后，您可以使用以下命令将其安装到系统中的任意路径：

# install the emulator
sudo make install PREFIX=/usr/local

安装完成后，若要使用 cartesi-machine 命令启动 Linux 系统，您还需要下载：

  • 来宾 Linux 镜像 并将其放置于 $PREFIX/share/cartesi/images/linux.bin
  • 来宾 rootfs 镜像 并将其放置于 $PREFIX/share/cartesi/images/rootfs.ext2。

用法

当您已安装好模拟器、来宾 Linux 镜像和来宾 rootfs 镜像后，可以通过运行以下命令启动 Linux 操作系统：

cartesi-machine

它应该输出类似以下内容：


         .
        / \
      /    \
\---/---\  /----\
 \       X       \
  \----/  \---/---\
       \    / CARTESI
        \ /   MACHINE
         '

Nothing to do.

Halted
Cycles: 48415113

你可以启动一个交互式终端来尝试：

cartesi-machine -it bash

现在，你就拥有了一个运行在 RISC-V 模拟 CPU 上的完整 Linux 系统，你可以与之交互。 你可以查阅 cartesi-machine --help 以获取有关如何使用 CLI 应用程序的更多信息。

库

你可以在其他应用程序中将模拟器用作库，其 libcartesi 库提供了一个 C API，使用起来非常简单。

请查阅以下 wiki 指南，了解如何使用不同语言：

用例

以下项目已在使用该模拟器：

  • Cartesi Rollups Node - 在 Go 中使用模拟器的库，用于以太坊上的 Layer 2 rollups。
  • Cartesi Dave - 在 Rust 中使用模拟器的库，用于链上欺诈证明验证。
  • Cartesi CLI - 在 TypeScript 中使用模拟器的 CLI，用于 DApp 开发。

相关项目

Cartesi Machine 模拟器与以下由我们维护的重要项目直接相关：

基准测试

该模拟器的 RISC-V 解释器针对链上验证的要求进行了优化，以实现高性能。 有关将模拟器与裸机执行及其他虚拟机进行对比的详细性能指标， 请参阅我们的 基准测试 页面。

文档

Cartesi Machine 的全面文档在 doc/README 中保持最新状态。 我们还在 wiki 中提供了一些指南。

变更日志

模拟器版本之间的变更记录在 CHANGELOG 中。

路线图

我们不断通过新功能和增强功能来改进模拟器。 查看我们的 GitHub Projects 以了解未来的计划。

社区与支持

  • 加入我们的 Discord #cartesi-machine 频道，与模拟器用户和开发者互动。
  • 在我们的 GitHub Issues 上报告问题。

开发

有关模拟器开发的更详细信息，包括运行测试、使用 linter 和代码格式化的说明，请参阅 wiki 中的 开发指南。

贡献

请参阅我们的 贡献指南 以了解如何开始为该项目做出贡献。 请注意，我们有一份 行为准则，请在与项目的所有互动中遵守它。

作者

Cartesi Machine 模拟器由 Cartesi 的 Machine Reference Unit 积极开发，并得到了许多开源开发者的重大贡献。 有关作者的完整列表，请参阅 AUTHORS 文件。

许可证

该仓库及其所有贡献均遵循 LGPL 3.0 许可，除非下文或子目录中的 LICENSE / COPYING 文件另有说明。 请查阅我们的 COPYING 文件以了解 LGPL 3.0 许可证，并查阅 LICENSES 文件以获取有关第三方软件许可证的附加信息。