区块链原理 / 系统课时
安装 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:
git --version
rustc --version
cargo --version
node --version
npm --version预期结果:每条命令均输出版本信息。例如 Node.js 输出 v22.x.x,Rust 输出 rustc 1.x.x,npm 输出对应版本号。这里的 x 表示随实际安装版本变化的数字。
Ubuntu 可通过系统包管理器安装 Git 与常用编译工具:
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:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"
rustc --version
cargo --version预期结果:安装器可能要求选择默认安装选项;完成后,rustc 与 cargo 均能输出版本信息。上述第二条命令用于让当前 Shell 立即加载 Cargo 环境。
接下来从官方 GitHub 仓库获取 Circom 源码。以下命令在用户主目录下操作:
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:
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 |
创建目录:
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 创建完整源码:
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 保存调试时可用的信号映射。编译成功并不代表已经生成零知识证明。
继续创建测试输入并调用编译产物中的见证生成脚本:
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:
ls "$HOME/.cargo/bin/circom"
export PATH="$HOME/.cargo/bin:$PATH"
command -v circom预期结果:第一条命令能够找到编译器文件,最后一条输出其可执行文件路径。export 仅对当前终端会话有效;需要永久生效时,应将对应 PATH 配置写入正在使用的 Shell 启动文件。
如果找不到 snarkjs,检查 npm 全局安装位置与 PATH:
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 成功。满足这三项后,环境即可用于后续电路编写与证明实验。