ZK 身份 + Oracle — 设计

日期: 2026-03-04 状态: 已批准 前置: Phase 5a (DID 核心 — 已完成) 范围: ZK 身份证明 + Oracle 信用评分（不含 L1 DIDFacet）

---

1. 概述

1.1 目标

在 Phase 5a 的 DID 系统合约基础上，添加：

• ZK 身份证明: 用户本地生成零知识证明，链上验证合规性而不暴露隐私数据

• Oracle 信用评分: 链上行为分析 + 链下数据聚合，通过 OracleHub (0x8016) 提供信用评分

• 企业身份维度: KYC/信用评分均支持个人 + 企业机构两个维度

1.2 关键设计决策

决策项	选择	理由
ZK 证明系统	Groth16/circom	boojum 使用 Goldilocks field，电路为 VM 专用，自定义电路需 recursion wrapping 极其复杂
链上验证	BN256 ecPairing 预编译	EIP-197，~200k gas，成熟稳定
信用评分数据源	混合模式（链上+链下）	链上行为客观可验证，链下数据补充监管需求
电路数量	3 个（KYC + 信用 + 企业）	覆盖个人 + 企业合规场景
可信设置	Powers of Tau ceremony	Groth16 需要 circuit-specific trusted setup

1.3 为什么不用 boojum

经过对 zksync-era boojum 库的深入研究：

1. Goldilocks field (p ≈ 2^64): boojum 使用 64-bit 域，与 BN256 (254-bit) 不兼容，链上验证需要递归包装

2. VM 专用电路: 13 个 base circuits 全部服务于 VM 执行（MainVM, CodeDecommitter, RAM, etc.），不支持自定义逻辑

3. 递归开销: 自定义电路 → Goldilocks proof → 递归 wrapping → BN256 proof，工程量巨大

4. circom 优势: 直接生成 BN256 proof，社区成熟（Semaphore, Tornado Cash, zkSync 自身的 Account Abstraction 也用 ECDSA 验证），开发效率高 10x+

---

2. ZK 电路架构

2.1 整体流程

用户端 (链下)                                         链上
┌──────────────────────┐                    ┌───────────────────────────┐
│ 1. 持有 VC 凭证       │                    │ IdentityVerifier (0x8019) │
│    (KYC/信用/企业)     │                    │                           │
│                       │                    │ verifyZKProof(            │
│ 2. 选择电路 + 构建     │    submit proof    │   proof,                  │
│    witness (私有输入)   │ ─────────────────→ │   publicInputs            │
│                       │                    │ )                         │
│ 3. snarkjs 生成       │                    │ → ecPairing 验证           │
│    Groth16 proof      │                    │ → 更新 compliance 状态     │
└──────────────────────┘                    └───────────────────────────┘

2.2 电路 1: KYCComplianceProof（个人 + 企业）

用途: 证明 "我持有有效 KYC 凭证且满足合规要求" — 不暴露姓名、国籍等隐私

私有输入 (witness):

字段	类型	说明
name	string→hash	姓名哈希
nationality	uint8	国籍代码
birthDate	uint64	出生日期
kycLevel	uint8	KYC 等级 (1-4)
issuerSignature	(R, S)	发行者 ECDSA 签名
orgType	uint8	机构类型: 0=个人, 1=企业, 2=DAO, 3=政府
orgLicenseHash	bytes32	营业执照/注册证哈希
orgComplianceLevel	uint8	企业合规等级 (1-5)
employeeRole	uint8	操作者在企业中的角色

公开输入:

字段	类型	说明
credentialHash	bytes32	凭证哈希 (链上可验)
isOver18	bool	年龄满足
isNotSanctioned	bool	非制裁名单
kycLevelMeetsRequirement	bool	KYC 等级达标
isOrgCompliant	bool	企业合规 (orgType=0 时固定 true)
orgComplianceMeetsLevel	bool	企业合规等级达标
issuerPubKey	(Qx, Qy)	发行者公钥 (链上校验可信)

电路约束 (~15,000 constraints):

1. ECDSA 签名验证: verify(issuerPubKey, message, (R, S)) — ~10,000 constraints

2. 年龄计算: currentTimestamp - birthDate >= 18 years

3. 制裁名单: nationality ∉ sanctionedList (Poseidon Merkle 成员证明)

4. KYC 等级: kycLevel >= requiredLevel

5. 凭证哈希: credentialHash == Poseidon(name, nationality, birthDate, ...)

6. 企业维度 (orgType > 0 时启用):

   • orgLicenseHash ≠ 0 (持有有效执照)

   • orgComplianceLevel >= requiredOrgLevel

   • employeeRole ∈ authorizedRoles (操作者有权限)

2.3 电路 2: CreditScoreProof（个人 + 企业）

用途: 证明 "我的信用评分 >= 阈值" — 不暴露具体分数

私有输入 (witness):

字段	类型	说明
personalScore	uint256	个人信用分 (0-1000)
personalFactors	uint256[8]	评分因子 (tx count, holding time, etc.)
orgScore	uint256	企业信用分 (0-1000，个人填 0)
orgFactors	uint256[8]	企业评分因子 (revenue, audit, etc.)
oracleSignature	(R, S)	Oracle 签名证明评分真实性
oracleTimestamp	uint64	评分时间

公开输入:

字段	类型	说明
personalScoreAboveThreshold	bool	个人分 >= 阈值
orgScoreAboveThreshold	bool	企业分 >= 阈值
personalThreshold	uint256	个人阈值
orgThreshold	uint256	企业阈值
oraclePubKey	(Qx, Qy)	Oracle 公钥
freshnessValid	bool	评分未过期

电路约束 (~12,000 constraints):

1. Oracle 签名验证: verify(oraclePubKey, (personalScore, orgScore, timestamp), sig)

2. 个人分比较: personalScore >= personalThreshold

3. 企业分比较: orgScore >= orgThreshold (orgScore=0 时跳过)

4. 时效性: currentTimestamp - oracleTimestamp <= maxAge

5. 评分范围: 0 <= personalScore <= 1000, 0 <= orgScore <= 1000

2.4 电路 3: EnterpriseIdentityProof

用途: 证明 "我是某认证企业的授权操作者" — 不暴露企业内部架构

私有输入 (witness):

字段	类型	说明
operatorAddress	address	操作者地址
orgRootDID	address	企业根 DID
orgMerkleProof	bytes32[]	企业成员 Merkle 证明
roleLevel	uint8	角色级别
delegationChain	address[]	委托链路

公开输入:

字段	类型	说明
orgMerkleRoot	bytes32	企业成员树根
isAuthorized	bool	操作者被授权
minRoleLevel	uint8	最低角色级别
nullifier	bytes32	防重放

电路约束 (~8,000 constraints):

1. Merkle 包含证明: verify(orgMerkleRoot, operatorAddress, orgMerkleProof)

2. 角色验证: roleLevel >= minRoleLevel

3. 委托链有效性: 每级委托有 DID 签名

4. Nullifier: nullifier = Poseidon(operatorAddress, actionNonce) — 防重放

2.5 链上验证合约 (Groth16Verifier)

/// @dev 由 snarkjs 自动生成 (每个电路一个)
contract KYCVerifier {
    // BN256 G1/G2 点 (验证密钥)
    uint256[2] alfa1;
    uint256[2][2] beta2;
    uint256[2][2] gamma2;
    uint256[2][2] delta2;
    uint256[2][] IC;  // 公开输入承诺

    function verifyProof(
        uint256[2] calldata _pA,    // proof.A (G1)
        uint256[2][2] calldata _pB, // proof.B (G2)
        uint256[2] calldata _pC,    // proof.C (G1)
        uint256[] calldata _pubSignals
    ) external view returns (bool) {
        // ecPairing(A, B, C, vk) — ~200k gas
    }
}

部署模式: 每个电路生成一个 Verifier 合约，IdentityVerifier (0x8019) 持有各 Verifier 地址，统一调度。

---

3. Oracle 信用评分系统

3.1 架构

链上行为数据                链下 API 数据               OracleHub (0x8016)
┌──────────────┐     ┌──────────────────┐     ┌───────────────────────┐
│ tx count     │     │ 监管评级 API      │     │                       │
│ DeFi 参与度   │     │ 企业审计报告      │     │ CREDIT:PERSONAL:0x..  │
│ 持币时间      │     │ 信用局 (征信)     │     │ CREDIT:ORG:0x...      │
│ 违约记录      │ ──→ │ 行业黑名单        │ ──→ │ CREDIT:COMPOSITE:0x.. │
│ Gas 使用模式  │     │ 公开财务数据      │     │                       │
└──────────────┘     └──────────────────┘     └───────────────────────┘
        │                    │                         │
        └────────────────────┘                         │
                    │                                  ▼
        ┌───────────────────────┐          ┌────────────────────┐
        │ CreditScoreAggregator │          │ IdentityVerifier   │
        │ (Rust baby-module)    │          │ (0x8019)           │
        │                       │          │                    │
        │ - 链上事件分析         │          │ getCreditScore()   │
        │ - 链下 API 轮询       │          │ → 读取 OracleHub   │
        │ - 评分算法 (加权)     │          │                    │
        │ - 签名 + 提交到 Oracle │          │ verifyZKProof()    │
        └───────────────────────┘          │ → 验证信用ZK证明   │
                                           └────────────────────┘

3.2 评分因子

个人评分 (CREDIT:PERSONAL:)

因子	权重	数据来源	计算方式
交易活跃度	20%	链上	tx_count / time_period
DeFi 参与	15%	链上	unique_protocols * avg_tvl
持币时长	15%	链上	weighted_avg_hold_days
违约记录	-25%	链上+链下	清算/违约次数
KYC 等级	10%	链上	kyc_level * weight
账户年龄	10%	链上	days_since_first_tx
外部信用	5%	链下	credit_bureau_score / normalize

企业评分 (CREDIT:ORG:)

因子	权重	数据来源	计算方式
链上交易量	20%	链上	volume / time_period
合规等级	20%	链上+链下	compliance_level
审计状态	15%	链下	audit_passed ? bonus : penalty
员工 DID 覆盖率	10%	链上	active_employee_dids / total
运营历史	15%	链上	months_active * consistency
监管评级	10%	链下	regulatory_rating / normalize
行业黑名单	-10%	链下	blacklist_check

综合评分 (CREDIT:COMPOSITE:): max(personalScore, orgScore) * 0.6 + min(personalScore, orgScore) * 0.4

3.3 OracleHub Symbol 扩展

现有 OracleHub 使用 string symbol 作为键（如 "ETH/USD"）。信用评分复用相同接口：

CREDIT:PERSONAL:0x1234...abcd   → 个人信用分 (0-1000)
CREDIT:ORG:0x1234...abcd        → 企业信用分 (0-1000)
CREDIT:COMPOSITE:0x1234...abcd  → 综合信用分 (0-1000)

无需修改 OracleHub 合约 — 评分数据通过现有 updatePrice() 接口写入，getLatestPrice() 读取。

3.4 CreditScoreAggregator (Rust 服务)

位于 baby-modules/credit-score/，作为 WiringLayer 集成到节点：

pub struct CreditScoreAggregator {
    // 链上数据源
    l2_rpc: L2RpcClient,           // 读取 L2 交易/事件
    did_registry: DIDRegistryClient, // 读取 DID 状态

    // 链下数据源
    credit_apis: Vec<CreditApiClient>, // 外部信用 API

    // 输出
    oracle_service: SharedOracleService, // 写入 OracleHub
}

更新频率: 每 10 分钟重新计算活跃用户/企业的信用评分。

---

4. IdentityVerifier 升级方案

4.1 新增函数

在现有 IdentityVerifier (0x8019) 基础上添加：

// ── ZK 验证 ─────────────────────────────────────────
/// @notice 验证 Groth16 ZK 证明并更新合规状态
function verifyZKProof(
    uint8 circuitType,          // 0=KYC, 1=CreditScore, 2=Enterprise
    uint256[2] calldata _pA,
    uint256[2][2] calldata _pB,
    uint256[2] calldata _pC,
    uint256[] calldata publicInputs
) external returns (bool);

/// @notice 注册/更新电路验证器地址 (仅 bootloader)
function setCircuitVerifier(
    uint8 circuitType,
    address verifierAddress
) external; // onlyCallFromBootloader

/// @notice 查询电路验证器地址
function getCircuitVerifier(uint8 circuitType) external view returns (address);

// ── Oracle 信用评分 ─────────────────────────────────
/// @notice 从 OracleHub 读取个人信用评分
function getPersonalCreditScore(address identity) external view returns (uint256);

/// @notice 从 OracleHub 读取企业信用评分
function getOrgCreditScore(address identity) external view returns (uint256);

/// @notice 从 OracleHub 读取综合信用评分
function getCompositeCreditScore(address identity) external view returns (uint256);

4.2 新增存储

// 电路验证器注册表
mapping(uint8 => address) private _circuitVerifiers;
// circuitType => Groth16Verifier 合约地址

// ZK 证明记录 (防重放)
mapping(bytes32 => bool) private _usedProofs;
// keccak256(proof) => used

4.3 verifyZKProof 实现逻辑

1. 检查 circuitType 是否已注册验证器
2. 检查 proof 是否已使用 (防重放)
3. 调用对应 Groth16Verifier.verifyProof()
4. 如果验证通过:
   a. 从 publicInputs 解析合规结果
   b. 更新 _compliance[identity][requirement]
   c. emit ZKProofVerified(identity, circuitType)
5. 标记 proof 为已使用

---

5. 项目结构

baby-modules/
├── did-circuits/                  # circom 电路
│   ├── circuits/
│   │   ├── kyc_compliance.circom  # 电路 1: KYC (个人+企业)
│   │   ├── credit_score.circom    # 电路 2: 信用评分
│   │   ├── enterprise_identity.circom # 电路 3: 企业身份
│   │   └── lib/
│   │       ├── ecdsa.circom       # ECDSA 验证子电路
│   │       ├── poseidon.circom    # Poseidon 哈希
│   │       └── merkle.circom      # Merkle 证明
│   ├── build/                     # 编译输出
│   │   ├── kyc_compliance.r1cs
│   │   ├── kyc_compliance.wasm
│   │   └── kyc_compliance_final.zkey
│   ├── contracts/                 # snarkjs 生成的验证合约
│   │   ├── KYCVerifier.sol
│   │   ├── CreditScoreVerifier.sol
│   │   └── EnterpriseVerifier.sol
│   ├── test/
│   │   ├── kyc_compliance.test.js
│   │   ├── credit_score.test.js
│   │   └── enterprise_identity.test.js
│   ├── scripts/
│   │   ├── compile.sh             # circom 编译脚本
│   │   ├── setup.sh               # trusted setup (Powers of Tau + phase 2)
│   │   └── generate_proof.sh      # 测试用 proof 生成
│   ├── input/                     # 测试用 witness 输入
│   │   ├── kyc_input.json
│   │   ├── credit_input.json
│   │   └── enterprise_input.json
│   └── package.json               # circomlib, snarkjs 依赖
│
├── credit-score/                  # Rust 信用评分聚合器 (Phase 5b 后期)
│   ├── src/
│   │   ├── lib.rs
│   │   ├── aggregator.rs          # 评分算法
│   │   ├── on_chain.rs            # 链上数据采集
│   │   ├── off_chain.rs           # 链下 API 对接
│   │   └── wiring.rs              # WiringLayer 集成
│   └── Cargo.toml

---

6. 交付计划

Task 1: circom 环境搭建 + 项目结构 (~0.5 天)

• 安装 circom 2.x + snarkjs

• 创建 baby-modules/did-circuits/ 结构

• 配置 package.json (circomlib 依赖)

• 验证: circom --version + 编译示例电路

Task 2: KYCComplianceProof 电路 (~1 天)

• 编写 circom 电路 (私有输入/公开输出/约束)

• 包含 ECDSA 验证 + 年龄检查 + 制裁名单 + 企业维度

• 编写 JS 测试 (witness 生成 + proof 生成 + 验证)

• 验证: 全部测试通过

Task 3: CreditScoreProof 电路 (~1 天)

• 编写信用评分电路 (个人+企业双维度)

• Oracle 签名验证 + 阈值比较

• JS 测试

• 验证: 全部测试通过

Task 4: EnterpriseIdentityProof 电路 (~0.5 天)

• 编写企业身份电路 (Merkle 成员证明 + 角色验证)

• JS 测试

• 验证: 全部测试通过

Task 5: Trusted Setup + Verifier 合约生成 (~0.5 天)

• Powers of Tau ceremony (开发用)

• 每个电路 phase 2 setup

• snarkjs 导出 Solidity Verifier 合约

• 验证: 3 个 Verifier 合约编译通过

Task 6: IdentityVerifier 升级 (~1 天)

• 添加 verifyZKProof() + setCircuitVerifier() + getCreditScore()

• 更新 IIdentityVerifier 接口

• 更新 Local 版本 + Foundry 测试

• 集成测试: 完整 proof 生成 → 链上验证 → compliance 更新

• 验证: 所有现有测试 + 新测试通过

Task 7: Oracle 信用评分集成 (~0.5 天)

• IdentityVerifier 读取 OracleHub credit symbols

• Foundry 测试: mock OracleHub 返回评分 → getCreditScore() 验证

• 验证: 信用评分读取 + ZK 信用证明端到端

总计: ~5 天

---

7. 风险和缓解

风险	影响	缓解措施
circom ECDSA 电路约束数过多	证明生成慢	使用 circom-ecdsa 优化库，约束 ~10k 可接受
Groth16 trusted setup 安全性	生产安全	开发用小规模 ceremony，主网前用 Hermez 的 Powers of Tau
信用评分 Oracle 被操纵	评分不可信	多源聚合 + 异常检测 + 最低源数量 (复用 OracleHub 机制)
ZK proof 链上验证 gas 过高	成本	Groth16 固定 ~200k gas，BabyDriver L2 gas 成本远低于 L1
企业维度增加电路复杂度	开发时间	orgType=0 时自动跳过企业约束，保持个人路径简洁