区块链原理 / 系统课时

用 Poseidon 验证哈希承诺

用 Poseidon 验证哈希承诺

当用户需要证明自己知道某个承诺对应的原始数据,却不希望公开数据与随机盐时,可以在 Circom 电路中复用 Poseidon 哈希组件。本篇实现一个可编译、可生成见证的承诺验证电路,并通过正确输入、错误盐值和输入顺序变化检查约束是否真正生效。

学习目标

  • 使用 circomlib 的 Poseidon(2) 计算私有数据与随机盐的哈希承诺。
  • 将计算结果约束到公开承诺值,理解公开输入与私有输入的区别。
  • 编译电路并生成见证,验证正确承诺通过、错误承诺失败。

承诺验证的约束关系

设私有数据为 mm,随机盐为 rr,公开承诺值为 CC。本例采用两个输入的 Poseidon 哈希函数,要求满足:

C=Poseidon⁡(m,r)C=\operatorname{Poseidon}(m,r)

证明者提供 m 和 r,验证者只需要知道 C。电路检查等式成立,但不会因为等式成立就主动公开两个私有输入。

这里的随机盐用于避免低熵数据被直接枚举。假设业务数据只有 0~100,即使使用密码学哈希,如果没有足够随机性,攻击者也可能逐个尝试候选值。因此,随机盐应由安全随机数生成器生成,并在业务允许的范围内保持秘密。

本例使用 BN254 标量域上的字段元素作为输入。字段元素不是任意长度字符串;字符串、字节数组和业务对象必须先按照固定编码规则转换,不能直接把 UTF-8 文本当作 Circom 信号。

Poseidon 哈希承诺的生成与验证数据流

使用 circomlib 构建电路

本例以 Circom 2.x、circomlib 2.x 和 Node.js 20 环境为基础。首先在空目录中安装电路组件与 JavaScript 侧的 Poseidon 实现。需要提前安装 Circom 2 编译器,并确保 circom --version 可以执行。

bash
npm init -y
npm install circomlib@2 circomlibjs@0.1.7
circom --version

预期结果:依赖安装成功,最后一条命令显示本机 Circom 2.x 的实际版本号;具体补丁版本可能不同。circomlib 提供电路模板,circomlibjs 提供用于生成公开承诺的 JavaScript 实现,两者必须采用兼容的 Poseidon 参数。

新建 commitment.circom:

circom
pragma circom 2.1.0;

include "circomlib/circuits/poseidon.circom";

template VerifyCommitment() {
    signal input value;
    signal input salt;
    signal input commitment;

    component hasher = Poseidon(2);

    // 输入顺序属于承诺协议的一部分,不能随意交换。
    hasher.inputs[0] <== value;
    hasher.inputs[1] <== salt;

    // 公开承诺必须等于电路实际计算的哈希。
    hasher.out === commitment;
}

component main {public [commitment]} = VerifyCommitment();

该电路包含三个输入信号。value 与 salt 默认是私有输入,commitment 通过 public 显式声明为公开输入。Poseidon(2) 表示哈希接收两个字段元素,不是哈希两次。

<== 会建立信号赋值对应的约束;=== 用于声明左右两侧必须相等。这里直接约束 hasher.out === commitment,避免仅在链下比较字符串而没有在电路内部真正约束承诺。

在链下生成公开承诺

公开承诺必须在生成见证之前按照同一 Poseidon 实现计算。创建 prepare-input.mjs,使用 circomlibjs 的 buildPoseidon 生成与电路兼容的哈希,并将大整数转换为十进制字符串,避免 JavaScript 数字精度损失。

js
import { buildPoseidon } from 'circomlibjs';
import { writeFileSync } from 'node:fs';

const poseidon = await buildPoseidon();
const value = 42n;
const salt = 987654321n;

// 电路顺序为 value、salt,链下计算必须完全一致。
const hash = poseidon([value, salt]);
const commitment = poseidon.F.toString(hash);

const input = {
  value: value.toString(),
  salt: salt.toString(),
  commitment
};

writeFileSync('input.json', JSON.stringify(input, null, 2));
console.log('input.json generated');

执行:

bash
node prepare-input.mjs

预期输出:

text
input.json generated

生成的 input.json 包含 value、salt 和 commitment 三个字段,均采用十进制字符串表示。承诺是确定性的:相同的两个字段元素和相同的 Poseidon 参数会生成相同结果;更改随机盐通常会得到不同承诺。

需要特别区分演示输入与生产输入。本例的 987654321 是便于复现的固定测试盐,不具备生产级随机性;真实业务应使用密码学安全随机源生成盐,并根据应用威胁模型选择足够大的随机空间。

编译电路并验证见证

先编译电路,-l node_modules 用于解析 circomlib/circuits/poseidon.circom 的依赖路径。--r1cs 输出约束系统,--wasm 生成 WebAssembly 见证计算器,--sym 生成调试符号。

bash
circom commitment.circom --r1cs --wasm --sym -l node_modules

预期结果:当前目录生成 commitment.r1cs、commitment.sym 和 commitment_js 目录,后者包含 commitment.wasm 与见证生成脚本。编译日志中的约束数量取决于所使用的实现版本,不应把某个固定数值当成正确性依据。

生成并检查正确输入的见证:

bash
node commitment_js/generate_witness.js commitment_js/commitment.wasm input.json witness.wtns
npx snarkjs wtns check commitment.r1cs witness.wtns

预期结果:见证生成命令正常退出,snarkjs wtns check 报告见证满足约束,常见成功信息为 WITNESS IS CORRECT。这只能说明当前见证符合 R1CS,尚不代表已经生成或验证了零知识证明。

接下来进行反向测试。在保持公开承诺不变的情况下,将 input.json 的 salt 修改为 987654322,然后重新执行见证生成命令:

bash
node commitment_js/generate_witness.js commitment_js/commitment.wasm input.json invalid.wtns

预期结果:见证计算器因承诺相等约束不成立而报错,通常能看到 Assert Failed 或相关约束失败信息;具体报错位置随 Circom 版本变化。不能将这类失败忽略后继续生成证明。

还可以恢复原始输入并交换 value、salt,但保留原来的 commitment。由于这里约定的是有序输入,交换后通常无法通过约束。严格意义上,验证失败来源是两个有序输入计算出的哈希不再等于原承诺,而不是组件自行判断哪个字段叫随机盐。

输入一致性与安全边界

在实际项目中,承诺协议需要固定以下规则,否则即使电路和前端各自能运行,也可能出现无法验证或错误接受的情况。

检查项 本例约定 不一致时的结果
哈希组件 circomlib 的 Poseidon(2) 参数或实现不同,承诺可能不一致
输入顺序 inputs[0]=value、inputs[1]=salt 交换位置后通常得到不同哈希
输入类型 BN254 标量域元素 超出字段范围时可能被按模数归约
承诺表示 十进制字段元素字符串 编码解析规则不一致可能导致比较失败
公开信号 commitment 未声明公开将改变证明接口
随机盐 每次新承诺使用安全生成的随机值 固定或可预测盐会削弱隐藏性

还需要注意三个容易遗漏的边界。

首先,Circom 字段运算具有模数语义。例如业务规定用户年龄为 18~120 时,只用 Poseidon 承诺年龄并不能保证年龄属于该范围。必须额外增加范围约束,且链下编码和链上解释都要采用同一规则。

其次,如果相同字段值允许多种业务编码方式,例如字符串 42、整数 42 和带前导零的文本 042,应在进入电路之前定义规范编码,防止不同系统对同一个业务值计算出不同承诺。

最后,哈希承诺约束只证明输入与公开哈希之间的关系。真正对外验证零知识证明时,还需要选择证明系统,完成可信设置或相应参数准备、生成证明,并通过验证密钥检查证明与公开输入。仅生成 witness.wtns 不具备隐藏私有数据的对外证明效果,也不应把见证文件交给验证者。

当正确见证通过、错误盐值失败、交换输入顺序失败,并且公开信号中只有预期承诺值时,这个最小电路便完成了哈希承诺关系的约束验证。后续可以在同一电路中继续加入年龄范围、资格条件或余额阈值等业务规则。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 Poseidon 验证哈希承诺

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

登录哪都通