区块链原理 / 系统课时

安装 Circom 与 snarkjs

安装 Circom 与 snarkjs

本课在 Linux 或 macOS 终端搭建 Circom 2 开发环境:安装 Rust 编译器、Node.js 和 snarkjs,验证命令是否可用,并建立电路源码、输入文件和编译产物目录。完成后将实际编译一个最小电路,确认整套工具链能够正常工作。

学习目标

  • 从 Rust 源码安装 Circom 2,并通过版本命令检查编译器。
  • 安装 Node.js 与 snarkjs,区分电路编译器和证明工具的职责。
  • 创建标准项目目录,编译示例电路并检查生成的文件。

检查系统与基础依赖

以下命令适用于 Ubuntu 等 Linux 发行版及 macOS 的 Bash 或 Zsh。Windows 建议使用 WSL2 Ubuntu 执行 Linux 步骤;不要直接把这些 Bash 命令复制到 PowerShell。

建议使用 Node.js 22 LTS、Rust stable 工具链,并预留至少 2 GB 可用磁盘空间。磁盘空间是本地开发的建议值,不是 Circom 的固定最低要求。

先检查 Git、Rust、Node.js 和 npm:

bash
git --version
rustc --version
cargo --version
node --version
npm --version

预期结果:每条命令均输出版本信息。例如 Node.js 输出 v22.x.x,Rust 输出 rustc 1.x.x,npm 输出对应版本号。这里的 x 表示随实际安装版本变化的数字。

Ubuntu 可通过系统包管理器安装 Git 与常用编译工具:

bash
sudo apt update
sudo apt install -y git curl build-essential

预期结果:APT 完成依赖安装,最终没有未解决的安装错误。macOS 应先执行 xcode-select --install 安装 Apple Command Line Tools;已安装时系统会给出相应提示。

尚未安装 Node.js 时,可从 Node.js 官方下载页面 选择 22 LTS 及对应操作系统的安装方式。安装完成后重新打开终端,再运行 node --version 和 npm --version。

编译并安装 Rust 版 Circom 2

Circom 2 的官方编译器由 Rust 实现。不要使用 npm install -g circom 安装旧版 JavaScript 编译器,它与本课需要的 Rust 版 Circom 2 不是同一个工具。

没有 Rust 时,在 Linux 或 macOS 中安装 rustup:

bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"
rustc --version
cargo --version

预期结果:安装器可能要求选择默认安装选项;完成后,rustc 与 cargo 均能输出版本信息。上述第二条命令用于让当前 Shell 立即加载 Cargo 环境。

接下来从官方 GitHub 仓库获取 Circom 源码。以下命令在用户主目录下操作:

bash
cd "$HOME"
git clone https://github.com/iden3/circom.git
cd circom
cargo build --release
cargo install --path circom
circom --version

预期结果:cargo build --release 成功结束,cargo install 将可执行文件安装到默认的 $HOME/.cargo/bin,最后一条命令输出以 circom compiler 2. 开头的版本信息。具体补丁版本取决于检出的仓库源码。

cargo build --release 生成优化后的本地编译器,cargo install --path circom 则安装仓库中的编译器包。第一次构建需要下载并编译 Rust 依赖,耗时随机器性能和网络情况变化。

安装 snarkjs 并验证命令

Circom 负责把 .circom 电路编译为约束系统和见证计算程序;snarkjs 用于生成见证、执行证明系统初始化、生成证明以及验证证明。二者功能不同,必须分别检查。

安装 snarkjs:

bash
npm install -g snarkjs
snarkjs --version
snarkjs --help

预期结果:npm 安装成功,snarkjs --version 输出已安装版本,snarkjs --help 显示可用命令与子命令说明。snarkjs 的版本号与 Circom 编译器版本号不需要相同。

这里使用全局安装以便直接运行 snarkjs。正式项目也可以将 snarkjs 固定为项目开发依赖,通过 npx snarkjs 执行指定版本,减少不同开发机器之间的版本差异。

创建电路项目目录

本课将项目命名为 zk-demo,使用三个目录分离源文件、输入数据和生成产物。

目录 用途 示例内容
circuits/ 保存 Circom 源码 square.circom
inputs/ 保存见证输入数据 square.json
build/ 保存编译和见证产物 .r1cs、.wasm、.wtns

创建目录:

bash
cd "$HOME"
mkdir -p zk-demo/circuits zk-demo/inputs zk-demo/build
cd zk-demo
pwd

预期结果:pwd 输出项目的绝对路径,例如 /home/<USER>/zk-demo 或 /Users/<USER>/zk-demo,其中 <USER> 代表实际用户名。

这种目录划分可以防止编译产物与手写源码混在一起。build/ 中的文件通常能够重新生成,适合根据团队仓库策略加入 .gitignore;源码和测试输入则建议纳入版本管理。

编译最小电路验证工具链

用平方电路检查编译器能否完成一次真实编译。该电路接受私有输入 a,计算公开输出 b = a * a。下面使用 cat 创建完整源码:

bash
cat > circuits/square.circom <<'EOF'
pragma circom 2.0.0;

template Square() {
    signal input a;
    signal output b;

    // 用约束运算同时表达平方关系与输出赋值
    b <== a * a;
}

component main = Square();
EOF

circom circuits/square.circom --r1cs --wasm --sym -o build

预期结果:编译成功,没有语法错误。build/ 中生成 square.r1cs、square.sym 及 square_js/ 目录,后者包含 square.wasm 和 generate_witness.js 等文件。

其中 .r1cs 保存电路约束,.wasm 用于计算见证,.sym 保存调试时可用的信号映射。编译成功并不代表已经生成零知识证明。

继续创建测试输入并调用编译产物中的见证生成脚本:

bash
cat > inputs/square.json <<'EOF'
{
  "a": "3"
}
EOF

node build/square_js/generate_witness.js build/square_js/square.wasm inputs/square.json build/square.wtns
snarkjs wtns check build/square.r1cs build/square.wtns

预期结果:Node.js 生成 build/square.wtns,随后 snarkjs 报告见证检查通过,并显示类似 WITNESS IS CORRECT 的成功信息。对应的公开输出 b 应为 9。

wtns check 检查见证是否满足 R1CS 约束,不会生成证明,也不能替代后续的密码学验证。此时已经验证了 Circom 编译器、Node.js 见证计算程序与 snarkjs 的基本协作。

处理命令找不到与编译失败

如果执行 circom --version 出现 command not found,首先确认 Cargo 的可执行文件目录是否加入 PATH:

bash
ls "$HOME/.cargo/bin/circom"
export PATH="$HOME/.cargo/bin:$PATH"
command -v circom

预期结果:第一条命令能够找到编译器文件,最后一条输出其可执行文件路径。export 仅对当前终端会话有效;需要永久生效时,应将对应 PATH 配置写入正在使用的 Shell 启动文件。

如果找不到 snarkjs,检查 npm 全局安装位置与 PATH:

bash
npm config get prefix
command -v snarkjs
npm list -g --depth=0

预期结果:第一条显示全局安装前缀,最后一条列出包含 snarkjs 的全局依赖;command -v 应返回可执行命令的路径。Linux 与 macOS 上,npm 全局命令通常位于该前缀下的 bin 目录。

遇到其他问题时,按实际报错定位:

  • cargo: command not found:重新加载 $HOME/.cargo/env,检查 Rust 是否安装完成。
  • Rust 构建提示缺少 C 编译器或链接器:Ubuntu 检查 build-essential,macOS 检查 Command Line Tools。
  • npm 报 EACCES:优先使用 Node.js 版本管理器或用户可写的 npm 全局目录,不建议直接修改系统目录权限。
  • Circom 报 Unknown version 或版本不兼容:检查源码中的 pragma circom 和 circom --version,不要混用旧版编译器。
  • 见证生成时报输入缺失:检查 JSON 中的 a 是否存在,并确认传入的是正确的输入文件路径。

最终以三项结果作为验收:circom --version 显示 2.x、snarkjs --version 正常返回、snarkjs wtns check 成功。满足这三项后,环境即可用于后续电路编写与证明实验。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

安装 Circom 与 snarkjs

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通