区块链原理 / 系统课时
定位编译错误和见证计算失败
定位编译错误和见证计算失败
Circom 项目报错时,最有效的做法不是反复重跑整条证明链,而是把问题切成编译、输入解析、见证计算、约束检查和证明验证五个阶段。下面用 Circom 2 与 snarkjs 的常用命令建立一条可重复的诊断顺序,并说明怎样根据错误出现的位置判断根因。
学习目标
- 按编译、见证、约束和证明验证的顺序缩小故障范围
- 区分模板或信号定义错误、输入 JSON 错误、见证不满足约束与证明参数不匹配
- 使用
.sym、r1cs info、wtns check和 Groth16 验证命令确认修复结果
先把故障固定在一个阶段
不要从 groth16 prove 的最终报错反推全部原因。先删除旧产物或换到干净目录,然后依次执行编译、生成见证、检查见证、生成证明和验证证明;第一次失败的位置就是当前优先检查的边界。

假设源码文件为 circuit.circom,下面这组命令适用于 Circom 2.x 与 snarkjs 0.7.x 的常见 Groth16 工作流:
rm -rf build && mkdir build
circom circuit.circom --r1cs --wasm --sym -o build
snarkjs r1cs info build/circuit.r1cs
node build/circuit_js/generate_witness.js build/circuit_js/circuit.wasm input.json build/witness.wtns
snarkjs wtns check build/circuit.r1cs build/witness.wtns预期结果是四步都成功;具体约束数取决于电路:
[INFO] snarkJS: WITNESS IS CORRECT如果 circom 就失败,先处理源码;如果见证生成失败,先检查输入和值域;如果见证生成成功但 wtns check 失败,则重点检查约束逻辑或产物是否混用了不同版本的电路。
编译失败时先看源码位置和符号
Circom 编译器会在模板实例化、信号声明、约束表达式等位置直接报告错误。不要先检查 input.json,因为编译阶段还没有读取运行时输入。
例如下面的电路把同一个信号声明了两次,属于模板定义错误:
pragma circom 2.1.6;
template Demo() {
signal input a;
signal input a;
signal output out;
out <== a;
}
component main = Demo();片段示例:把内容保存为 circuit.circom 后运行编译命令即可复现;实际错误文字会随 Circom 小版本略有差异,但会指向重复声明附近的源码位置。
circom circuit.circom --r1cs --wasm --sym -o build预期结果:命令以非零状态退出,并指出 a 的声明存在冲突;不会生成一套可用于后续证明的新产物。
修正源码后保留 --sym。生成的 circuit.sym 是信号编号到信号名称的映射,后续遇到约束索引或信号索引时,可以用它判断故障对应哪个业务变量。还可以先检查新电路的规模:
snarkjs r1cs info build/circuit.r1cs预期输出形式如下,数字随电路变化:
[INFO] snarkJS: Curve: bn-128
[INFO] snarkJS: # of Wires: <ID>
[INFO] snarkJS: # of Constraints: <ID>如果你刚修改了电路,但约束数、.sym 内容或文件时间仍与旧版本一致,应优先怀疑正在使用旧的 build 目录,而不是怀疑证明算法本身。
见证计算失败先核对输入字段和数值
见证计算器读取的是 input.json。顶层键必须对应 main 组件可见的输入信号;数组输入还必须匹配电路声明的维度。大整数建议使用十进制字符串,避免先经过 JavaScript Number 后丢失精度。
例如电路需要 a 和 b 两个输入时,输入文件可以写成:
{
"a": "3",
"b": "7"
}配置文件本身没有控制台输出。验证方法是执行见证生成器,并确认 build/witness.wtns 被成功写出:
node build/circuit_js/generate_witness.js build/circuit_js/circuit.wasm input.json build/witness.wtns
snarkjs wtns check build/circuit.r1cs build/witness.wtns预期结果:第一条命令正常退出,第二条命令报告:
[INFO] snarkJS: WITNESS IS CORRECT常见错误可以按出现位置快速区分:缺少输入字段、字段名拼错或数组长度错误,通常会在见证计算阶段暴露;输入字段完整但其值无法满足电路约束,则可能在计算期间触发断言,也可能生成见证后由约束检查发现问题。
见证存在但约束失败时检查是否混用了产物
一个很隐蔽的错误是:witness.wtns 由新版 WASM 生成,却拿旧版 circuit.r1cs 检查。两边都能正常打开文件,但它们代表的约束系统已经不同。
先直接执行:
snarkjs wtns check build/circuit.r1cs build/witness.wtns正常结果应为:
[INFO] snarkJS: WITNESS IS CORRECT如果失败,按下面顺序处理:先重新编译 r1cs、wasm、sym;再使用新 WASM 重新生成 witness.wtns;最后重新执行 wtns check。不要只替换其中一个文件。
还可以导出见证为 JSON 检查具体数值。该操作主要用于开发环境,因为大电路的 witness JSON 会很大:
snarkjs wtns export json build/witness.wtns build/witness.json预期结果:命令正常结束并生成 build/witness.json。其中元素按有限域整数表示,不应把数组位置直接当成业务信号名称;需要结合编译生成的 .sym 文件解释信号编号。
证明验证失败时检查 r1cs、zkey 和验证密钥是否同源
如果 wtns check 已通过,而 groth16 prove 或 groth16 verify 失败,问题通常已经不在 input.json。这时重点检查 circuit.r1cs、最终 .zkey 和 verification_key.json 是否来自同一套电路与 Phase 2 参数。
使用同一份最终 zkey 重新导出验证密钥,再生成并验证证明:
snarkjs zkey export verificationkey circuit_final.zkey verification_key.json
snarkjs groth16 prove circuit_final.zkey build/witness.wtns proof.json public.json
snarkjs groth16 verify verification_key.json public.json proof.json预期结果:
[INFO] snarkJS: OK!如果证明生成阶段失败,先确认 circuit_final.zkey 是针对当前 circuit.r1cs 完成的 Groth16 Phase 2;如果证明能够生成而验证返回无效,则重新从当前 circuit_final.zkey 导出 verification_key.json,避免继续使用旧目录中的验证密钥。
可以再用 zkey 校验检查参数文件自身及其与 R1CS 的关系:
snarkjs zkey verify build/circuit.r1cs pot_final.ptau circuit_final.zkey预期结果包含验证通过的信息;若校验失败,就不要继续用该 zkey 生成链上验证器或证明,而应回到当前 R1CS 重新完成对应的 Groth16 setup 与贡献流程。
实际项目中最省时间的顺序可以固定为:circom 编译成功 → r1cs info 确认新电路 → 生成 witness → wtns check → zkey verify → groth16 prove → groth16 verify。哪一步第一次失败,就只检查该阶段及它的直接输入;这样能把“电路错、输入错、见证错、参数错”四类问题明确分开。