区块链原理 / 系统课时
导出 Solidity 链上验证合约
导出 Solidity 链上验证合约
已经使用 Groth16 生成证明后,可以将验证密钥导出为 Solidity 合约,让以太坊兼容链直接验证证明。本篇使用 snarkjs 完成导出,拆解验证入口、公开输入和椭圆曲线配对校验,并确认生成合约与特定电路验证密钥的绑定关系。
学习目标
- 使用 snarkjs 从
.zkey文件导出 Solidity 验证合约。 - 识别
verifyProof的参数、公开信号数组和配对校验逻辑。 - 理解验证密钥与电路的绑定关系,并完成导出结果的初步检查。
准备证明产物并导出合约
本例使用 snarkjs 的 Groth16 证明系统,假设已经完成 Circom 电路编译、可信设置和证明生成。工作目录中至少有以下文件:
| 文件 | 作用 |
|---|---|
circuit_final.zkey |
包含证明所需材料及对应的验证密钥 |
proof.json |
Groth16 证明数据 |
public.json |
公开输出与公开输入信号 |
其中,导出 Solidity 验证器只需要 .zkey 文件。proof.json 和 public.json 用于之后检查验证效果,不能替代验证密钥。
在项目目录执行以下命令,适用于支持 Bash 的 Linux、macOS 或 Git Bash 环境。要求当前目录存在有效的 Groth16 circuit_final.zkey,并已安装 Node.js 和 npm。
# 安装 snarkjs 命令行工具
npm install --save-dev snarkjs
# 导出便于本地核对的验证密钥
npx snarkjs zkey export verificationkey circuit_final.zkey verification_key.json
# 将同一份 zkey 中的验证密钥嵌入 Solidity 合约
npx snarkjs zkey export solidityverifier circuit_final.zkey verifier.sol
test -s verifier.sol && echo "verifier.sol ready"预期结果:前面的命令没有报错时,最后一行输出为:
verifier.sol ready目录中还会出现 verification_key.json 和 verifier.sol。安装日志、导出日志随环境和 snarkjs 版本变化,不需要与某个固定输出逐字一致。
打开 verifier.sol,应能找到 Groth16Verifier 合约及 verifyProof 函数。这里采用 snarkjs 官方 Groth16 导出流程,不要直接把 PLONK 或 FFLONK 的证明文件套用到该验证器。
理解验证密钥如何进入合约
Groth16 的 Solidity 验证器不是一个能够验证任意电路的通用合约。snarkjs 会读取 .zkey 中的验证密钥,将与当前电路及其可信设置对应的椭圆曲线点写入生成的 Solidity 源码。
生成合约通常包含 alphax、alphay、betax1 等常量,以及 IC0x、IC1x 等公开信号线性组合所需的坐标常量。这些数字来自实际验证密钥,不应该由开发者手工填写或随意替换。

理解这些常量时,可以抓住两个关系。
第一,IC 点用于把公开信号组合成一个椭圆曲线点。假设有两个公开信号 、,对应的线性组合为:
这里的乘法是椭圆曲线点的标量乘法,加法是椭圆曲线点加法,不是普通整数加法。
第二,验证器会将证明中的曲线点、固定验证密钥和计算出的 送入配对校验。以 snarkjs 的 BN254 Groth16 验证器为例,EVM 预编译地址 0x06、0x07 和 0x08 分别用于椭圆曲线点加法、标量乘法和配对检查。
对于使用当前 .zkey 生成的正确证明,验证器应返回 true。如果重新修改电路并完成新的可信设置,产生了不同的验证密钥,就必须重新导出并部署相应验证器。仅改变同一电路的私有输入、重新生成证明,不需要重新导出合约。
识别 verifyProof 的参数
在 snarkjs 生成的 Groth16 合约中,验证入口通常是 verifyProof,它接收四组参数并返回布尔值。
| 参数 | Solidity 类型形态 | 含义 |
|---|---|---|
_pA |
uint[2] |
证明中的 G1 曲线点 A |
_pB |
uint[2][2] |
证明中的 G2 曲线点 B |
_pC |
uint[2] |
证明中的 G1 曲线点 C |
_pubSignals |
uint[N] |
当前电路暴露的 N 个公开信号 |
这里的 N 是实际生成时确定的常量,不是 Solidity 泛型占位符。例如,只有一个公开信号时,生成的参数类型可以是 uint[1];有三个公开信号时,则是 uint[3]。
在 Circom 中,公开信号通常包括主组件输出以及声明为公开的输入。私有输入参与证明生成,但不会作为 _pubSignals 参数直接传递给验证器。
假设一个电路约束 ,其中 为私有输入、 为公开输出。当 时,证明对应的公开输出是 。合约无需收到私有值 7,但必须使用证明对应的公开信号 49。
生成的代码还会检查公开信号是否属于正确的标量域。对于 snarkjs 使用的 BN254 标量域,公开值必须小于:
公开信号顺序同样重要。即使两个数组包含相同的值,顺序变化也会改变验证密钥线性组合,通常导致验证失败。不要通过猜测手动排列参数,应使用 snarkjs 生成调用数据。
另一个容易出错的地方是 G2 点坐标顺序。Solidity 验证器采用 EVM 预编译要求的编码顺序,不能简单地把 proof.json 中的嵌套数组原样复制到合约调用参数里。
生成调用参数并检查验证结果
在实际部署前,先用同一个验证密钥验证已有证明,再生成 Solidity 调用参数。这样可以把证明本身的问题与链上调用编码的问题分开。
下面的命令假设 proof.json、public.json 来自与 circuit_final.zkey 匹配的一次成功 Groth16 证明生成。
# 先在链下确认验证密钥、公开信号与证明匹配
npx snarkjs groth16 verify verification_key.json public.json proof.json && echo "offchain-ok"
# 转换为 Solidity 验证器所需的四组调用参数
npx snarkjs zkey export soliditycalldata public.json proof.json > calldata.txt
test -s calldata.txt && echo "calldata-ready"预期结果:当证明验证通过且导出成功时,终端会出现 snarkjs 的 OK 验证提示,并包含以下自定义确认信息:
offchain-ok
calldata-ready这些信息之间可能还存在工具日志。生成的 calldata.txt 包含四组适用于 verifyProof 的调用参数,实际坐标和公开信号取决于当前证明,不能使用固定示例数字代替。
可以使用 Remix 进行一次手动验证:
- 将
verifier.sol导入 Remix,在 Solidity Compiler 面板选择满足文件pragma的编译器版本并编译。 - 在 Deploy & Run Transactions 面板选择
Groth16Verifier,部署到测试环境或 Remix VM。 - 展开已部署实例中的
verifyProof,按照其 ABI 要求提供 A、B、C 和公开信号数组。使用calldata.txt的对应数组值,不要把整个文件当成一个字符串输入。 - 调用验证函数,检查返回的布尔值。
对于原始有效证明及未修改的公开信号,预期结果是 true。若改变其中一个公开值而保持证明不变,通常返回 false;不过实际也可能因为 ABI 编码错误、数组长度错误或不符合曲线要求的数据而发生调用失败。
排查验证失败和密钥错配
遇到链下成功、链上失败时,按照下面的顺序检查,通常比直接修改生成的配对汇编更有效。
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
| Solidity 编译失败 | pragma 与编译器版本 |
选择满足生成文件版本范围的编译器 |
| ABI 参数无法输入 | 公开信号数组长度、数组层级 | 使用实际合约 ABI 和 soliditycalldata 结果 |
| 链下验证通过,链上返回 false | 是否部署了旧验证器 | 从证明对应的 .zkey 重新导出并部署 |
| 更改公开信号后验证失败 | 公开信号与证明不匹配 | 使用原始 public.json 或重新生成证明 |
| 配对调用失败 | 曲线点编码、网络预编译支持情况 | 检查链环境与证明数据,不直接改生成常量 |
一个特别需要避免的错误是把电路升级当作普通合约逻辑升级。例如原电路验证 x < 100,新电路改为 x < 200,这已经是不同的约束关系。继续部署旧验证器并不能自动识别新规则。
还要检查公开输入是否与业务语义绑定。例如应用验证某个用户的资格证明,如果用户身份或业务上下文没有被约束进公开信号并由合约检查,那么一个有效证明未必能证明当前调用者拥有该资格。
最终交付时应保留 circuit_final.zkey 对应的 verification_key.json、verifier.sol 和一组能够通过验证的测试证明。上线时固定生成合约的版本与验证密钥来源,避免不同电路或不同可信设置的证明被误送到同一个验证入口。