区块链原理 / 系统课时
绑定公开输入与合约业务语义
绑定公开输入与合约业务语义
一个 Groth16 证明即使通过密码学验证,也未必对应当前业务请求。本篇将操作类型、接收方、应用上下文和部署环境绑定为公开声明,并在 Solidity 合约中逐项检查,最终阻止证明跨用户、跨应用或跨合约复用。
学习目标
- 理解公开输入与业务授权条件的区别,设计可检查的公开信号结构。
- 在电路中约束业务字段,并在 Solidity 中验证其与实际请求一致。
- 使用 nullifier 防止重复领取,验证跨请求复用会被正确拒绝。
为业务请求定义公开输入
假设应用提供一次性权益领取功能:用户持有一个私密凭据,证明自己属于授权集合后,可以领取一次权益。电路不公开凭据本身,只公开验证所需的业务声明。
我们约定操作类型为 1,应用标识为 73001,并使用 Groth16 和 BN254 曲线。以下七个字段组成验证器的公开输入数组。
| 索引 | 字段 | 示例或来源 | 业务含义 |
|---|---|---|---|
| 0 | action | 1 | 仅允许权益领取 |
| 1 | receiver | 用户地址的 uint160 数值 | 指定接收方 |
| 2 | appId | 73001 | 指定业务应用 |
| 3 | chainId | 11155111 | 示例为 Sepolia 网络 |
| 4 | verifyingContract | 业务合约地址 | 指定验证入口 |
| 5 | root | 授权集合的 Merkle 根 | 指定可信凭据集合 |
| 6 | nullifierHash | 电路计算的域隔离哈希 | 防止同一凭据重复领取 |
这些数值属于公开信息,不能包含密码、私钥或需要保密的原始凭据。地址转换成整数后必须保留完整的 160 位,不能截断或随意哈希。
公开输入还有一个容易忽略的要求:数组顺序属于证明协议的一部分。Circom 主组件的公开信号顺序必须与 public.json、Solidity 验证器及业务合约的索引约定一致。Circom 的公开输出也会进入公开信号列表,不能只按输入变量的声明顺序猜测。
例如在 Sepolia 上运行时,第三个索引必须是实际链 ID 11155111,而不是前端配置中随意填写的网络名称。合约应从 block.chainid 获取可信值。
在电路中真正绑定业务字段
仅把 receiver、action 等变量声明为公开输入还不够。如果它们没有参与有效约束,公开值就可能与私密凭据无关,形成可跨业务重用的证明关系。
对于一次性领取,可以采用以下电路约束方案。
- 私密输入为
secret,以及证明 Merkle 成员资格所需的路径元素和方向信息。 - 使用
Poseidon(secret, receiver)计算授权叶子,证明该叶子属于公开root对应的 Merkle 树。 - 使用
Poseidon(secret, action, appId, chainId, verifyingContract)计算nullifierHash,并约束计算结果等于公开声明。 - 电路必须实际约束 Merkle 路径、哈希结果及相关布尔方向位,而不能只在见证计算代码中赋值。
这里的 Poseidon 表示选定参数和输入数量的哈希电路。证明端、授权集合构建端必须使用完全相同的字段编码、Poseidon 参数和 Merkle 树规则。
授权叶子同时包含 secret 与 receiver,意味着用户不能拿一张绑定地址 A 的授权叶子直接为地址 B 生成有效证明。nullifier 不包含接收方,而包含操作与部署域,因此同一凭据不能通过切换接收方在同一个业务域内再次领取。

在 Solidity 中检查业务语义
以下示例适用于 Solidity 0.8.24,假定已有经过检查的 Circom Groth16 电路、可信的授权 Merkle 根,以及与该电路完全匹配的七公开信号验证器。
这是完整的业务合约集成示例,依赖独立部署的真实验证器和有效证明才能完成领取。示例只记录领取资格和消费 nullifier,不执行资产转账。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
interface IGroth16Verifier {
function verifyProof(
uint256[2] calldata a,
uint256[2][2] calldata b,
uint256[2] calldata c,
uint256[7] calldata input
) external view returns (bool);
}
contract ClaimGate {
uint256 public constant ACTION_CLAIM = 1;
uint256 public constant APP_ID = 73001;
IGroth16Verifier public immutable verifier;
uint256 public immutable authorizedRoot;
mapping(uint256 => bool) public nullifierUsed;
event ClaimAuthorized(
address indexed receiver,
uint256 indexed nullifierHash
);
constructor(address verifierAddress, uint256 initialRoot) {
require(verifierAddress.code.length > 0, "bad verifier");
verifier = IGroth16Verifier(verifierAddress);
authorizedRoot = initialRoot;
}
function claim(
uint256[2] calldata a,
uint256[2][2] calldata b,
uint256[2] calldata c,
uint256[7] calldata publicSignals
) external {
// 索引必须与电路的公开信号顺序完全一致。
require(publicSignals[0] == ACTION_CLAIM, "bad action");
require(
publicSignals[1] == uint256(uint160(msg.sender)),
"bad receiver"
);
require(publicSignals[2] == APP_ID, "bad app");
require(publicSignals[3] == block.chainid, "bad chain");
require(
publicSignals[4] == uint256(uint160(address(this))),
"bad contract"
);
require(publicSignals[5] == authorizedRoot, "bad root");
uint256 nullifierHash = publicSignals[6];
require(!nullifierUsed[nullifierHash], "already claimed");
// 业务字段检查通过后,再执行密码学验证。
require(
verifier.verifyProof(a, b, c, publicSignals),
"invalid proof"
);
// 验证成功才消费 nullifier,防止再次领取。
nullifierUsed[nullifierHash] = true;
emit ClaimAuthorized(msg.sender, nullifierHash);
}
}预期结果:在部署了匹配的验证器、配置了正确的授权根并提交有效证明后,claim 成功执行,发出 ClaimAuthorized 事件,对应 nullifierUsed 变为 true。不满足检查条件时交易回滚,不会消费 nullifier。
这段代码采用三层校验。第一层检查操作、接收方、应用、网络、合约和授权根;第二层查询 nullifier 是否已经使用;第三层调用 Groth16 验证器,检查证明与公开信号是否满足电路约束。
验证器应使用同一套证明密钥导出,例如执行 snarkjs zkey export solidityverifier circuit_final.zkey verifier.sol。导出前须确保电路与 zkey 匹配,并检查生成合约的 verifyProof ABI 是否与接口一致。如果生成版本的函数签名不同,需要按实际 ABI 调整适配,不能直接假设兼容。
authorizedRoot 在此示例中不可修改,适合固定授权批次。如果业务需要不断加入用户,应增加带严格权限控制的根更新机制,并定义旧根证明的有效期及撤销规则。
用失败用例验证防复用效果
验证通过不等于防复用设计正确。应先为地址 A 生成一份真实有效的证明,再尝试改变业务环境,确认合约在预期位置拒绝请求。
| 测试场景 | 修改内容 | 预期结果 |
|---|---|---|
| 正常领取 | A 提交自己的有效证明 | 成功并记录 nullifier |
| 重复领取 | A 再次提交相同证明 | already claimed |
| 冒用接收方 | B 直接提交 A 的证明 | bad receiver |
| 修改操作类型 | 将 action 从 1 改为 2 | bad action |
| 修改应用标识 | 将 appId 从 73001 改为 73002 | bad app |
| 跨链提交 | 在链 ID 不同的网络使用原证明 | bad chain |
| 跨合约提交 | 向另一个 ClaimGate 实例提交原证明 | bad contract |
| 使用错误授权根 | 提交不同 root 对应的公开信号 | bad root |
| 篡改证明 | 保持公开信号不变,修改证明元素 | invalid proof,或验证器自身回滚 |
这些预期结果针对逐项检查顺序而言。若同时改变多个字段,实际首先触发哪一个错误,取决于合约中的检查顺序。证明元素格式非法时,底层验证器也可能直接回滚,而不是返回 false。
还要执行一项更重要的测试:尝试用合法私密凭据为另一接收方重新生成证明。如果授权树中不存在该接收方对应的叶子,电路应无法构造满足约束的有效见证。这能检验安全边界是否真正存在于电路中,而不仅是 Solidity 的条件判断。
最后还应检查两个工程边界。第一,示例要求 msg.sender 就是接收方;如果业务通过中继器提交交易,需要重新设计接收方授权方式,不能简单删除地址检查。第二,公开输入只保证证明与声明绑定,并不自动保证授权根来源可信。用于生产的授权集合、根更新权限、凭据撤销和实际权益交付仍须单独审计。
只要电路中的凭据关系、公开信号中的业务声明和 Solidity 中的真实请求三者保持一致,证明才能被安全地用于具体操作;任何一处缺失,都可能把原本有效的密码学证明变成可被错误业务请求利用的授权漏洞。