DID 核心 — 设计

日期: 2026-03-04 状态: 已批准 范围: 全量 PRD（P0 + P1 + P2），方案 A 分层渐进

---

1. 概述

1.1 目标

在 BabyDriver L2 上实现原生去中心化身份 (DID) 系统，作为系统合约部署，提供：

• W3C DID Core 兼容的身份注册与解析

• Verifiable Credentials (VC) 发行、验证、撤销

• PLONK ZK 身份证明（复用 zksync 原生证明系统）

• Ethereum L1 双向 DID 同步

• 社会恢复、企业 IAM、匿名凭证

1.2 设计决策

决策项	选择	理由
DID 方法	did:ethr:baby:0x...	成熟生态，复用 ethr-did-registry，Veramo 直接兼容
ZK 证明	PLONK (zksync 原生 boojum)	与底层 ZK 基础设施统一，universal trusted setup
部署方式	全部系统合约 (0x8017-0x8019)	原生内置、gas 特权、与 OracleHub 一致
跨链	Ethereum L1 双向 (Mailbox)	复用现有 L1⟷L2 消息通道
实现策略	分层渐进 (5a→5b→5c)	每阶段可独立验证，P0 最快落地

1.3 标准兼容

• W3C DID Core 1.0

• EIP-4361 (Sign-In with Ethereum)

• ethr-did-registry 合约接口

• W3C Verifiable Credentials Data Model

---

2. 系统合约架构

2.1 地址分配

地址	合约	用途	子阶段
0x8016	OracleHub	价格预言机 (已完成)	Phase 2
0x8017	DIDRegistry	DID 注册/解析/更新/撤销	5a (P0)
0x8018	CredentialRegistry	VC 发行/验证/撤销	5a (P0)
0x8019	IdentityVerifier	ZK 身份证明验证 + 合规授权	5a (P0)

2.2 DIDRegistry (0x8017)

核心存储：

mapping(address => DIDDocument) public documents;
mapping(address => address[]) public delegates;
mapping(address => address[]) public guardians;       // P2: 社会恢复
mapping(address => RecoveryConfig) public recoveryConfigs; // P2
mapping(address => uint256) public nonces;

DID 文档结构：

struct DIDDocument {
    bytes32[] verificationMethods;    // 公钥列表 (keccak256 of pubkey)
    address controller;               // 控制者
    uint64 created;
    uint64 updated;
    bool active;
    bytes32 serviceEndpointHash;      // 服务端点哈希 (链下完整文档)
}

DID 标识符格式： did:ethr:baby:0x1234...

关键函数：

函数	访问控制	子阶段
createDID()	onlySystemCall	5a
updateDocument(bytes32[] methods, bytes32 serviceHash)	onlyController	5a
addDelegate(address delegate, uint256 validity)	onlyController	5a
revokeDelegate(address delegate)	onlyController	5a
resolveDID(address identity) → DIDDocument	公开读取	5a
deactivateDID()	onlyController	5a
syncToL1(address identity)	onlyController	5b
receiveFromL1(address identity, bytes32 docHash)	onlyBootloader	5b
addGuardian(address guardian)	onlyController	5c
removeGuardian(address guardian)	onlyController	5c
socialRecover(address identity, address newController, bytes[] sigs)	公开	5c
cancelRecovery()	onlyController	5c

事件：

event DIDCreated(address indexed identity, address controller);
event DIDUpdated(address indexed identity, bytes32 documentHash);
event DIDDeactivated(address indexed identity);
event DelegateAdded(address indexed identity, address delegate, uint256 validity);
event DelegateRevoked(address indexed identity, address delegate);
event DIDSynced(address indexed identity, bytes32 documentHash);  // 5b: 跨链同步
event RecoveryInitiated(address indexed identity, address newController); // 5c
event RecoveryCancelled(address indexed identity);                       // 5c
event RecoveryExecuted(address indexed identity, address newController); // 5c

2.3 CredentialRegistry (0x8018)

核心存储：

mapping(bytes32 => Credential) public credentials;
mapping(bytes32 => bool) public revoked;
mapping(address => bytes32[]) public issuedByIssuer;
mapping(address => bytes32[]) public heldBySubject;

凭证结构：

struct Credential {
    address issuer;
    address subject;
    bytes32 credentialType;   // keccak256("KYC"), keccak256("CREDIT_SCORE"), etc.
    bytes32 claimHash;        // 声明数据哈希 (原始数据链下存储)
    uint64 issuedAt;
    uint64 expiresAt;
    bytes signature;          // 发行者 ECDSA 签名
}

关键函数：

函数	访问控制	子阶段
issueCredential(address subject, bytes32 credType, bytes32 claimHash, uint64 expiry, bytes sig)	onlySystemCall	5a
verifyCredential(bytes32 credId) → bool	公开读取	5a
revokeCredential(bytes32 credId)	onlyIssuer	5a
isCredentialValid(bytes32 credId) → bool	公开读取	5a
getCredentialsBySubject(address) → bytes32[]	公开读取	5a
getCredentialsByIssuer(address) → bytes32[]	公开读取	5a

CredentialId 计算： keccak256(abi.encode(issuer, subject, credType, claimHash, issuedAt))

2.4 IdentityVerifier (0x8019)

双模式验证（P0 ECDSA → P1 ZK PLONK 升级）：

enum VerificationMode { ECDSA, ZK_PLONK }
VerificationMode public currentMode;    // P0: ECDSA, P1: ZK_PLONK

mapping(address => mapping(bytes32 => bool)) public compliance;
// identity → requirement → isCompliant

关键函数：

函数	访问控制	子阶段
verifyIdentity(address identity, bytes32 credType) → bool	公开读取	5a
checkCompliance(address identity, bytes32 requirement) → bool	公开读取	5a
authorizeTransaction(address identity, bytes txData) → bool	onlySystemCall	5a
verifyZKProof(bytes proof, uint256[] publicInputs) → bool	公开	5b
getCreditScore(address identity) → uint256	公开读取	5b
setVerificationMode(VerificationMode mode)	onlyAdmin	5b

Oracle 集成 (5b)：

function getCreditScore(address identity) external view returns (uint256) {
    // 调用 OracleHub (0x8016) 获取信用评分
    IOracleHub oracle = IOracleHub(ORACLE_HUB_ADDRESS);
    (uint128 score, ) = oracle.getLatestPrice(
        keccak256(abi.encodePacked("CREDIT:", identity))
    );
    return uint256(score);
}

---

3. ZK 身份证明（PLONK）

3.1 架构

用户                          链下                              链上
┌──────────┐    ┌─────────────────────┐    ┌───────────────────────┐
│ KYC 机构 │───→│ 发行 VC (签名)       │───→│ CredentialRegistry    │
│ 验证身份  │    │ 存储链下             │    │ .issueCredential()    │
└──────────┘    └─────────────────────┘    └───────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │ 用户本地生成 ZK Proof │
              │ 输入: VC + 私有属性    │
              │ 输出: proof + public  │
              │ 电路: PLONK (boojum) │
              └──────────┬──────────┘
                         │
                         ▼
              ┌───────────────────────────┐
              │ IdentityVerifier (0x8019) │
              │ .verifyZKProof(proof,     │
              │   publicInputs)           │
              │ → 验证 PLONK proof        │
              │ → 更新合规状态             │
              └───────────────────────────┘

3.2 PLONK 电路

电路 1: KYC 合规证明 (P1)

类型	字段
私有输入	name, nationality, birthDate, kycLevel, issuerSignature
公开输入	credentialHash, isOver18, isNotSanctioned, kycLevelMeetsRequirement
证明	"我持有有效 KYC 凭证，满足年龄/制裁/等级要求" — 零知识

电路 2: 信用评分证明 (P1)

类型	字段
私有输入	creditHistory[], oracleSignatures[], actualScore
公开输入	scoreAboveThreshold, threshold
证明	"我的信用评分 >= X" — 不暴露具体分数

电路 3: 匿名集合成员证明 (P2)

类型	字段
私有输入	identity, merkleProof
公开输入	merkleRoot, nullifier
证明	"我是认证用户集合的成员" — 不暴露身份

3.3 PLONK 集成路径

复用 zksync-era 的 boojum 库：

1. 使用 boojum 定义 DID 电路约束

2. 电路编译为 Verifier key

3. 用户端用 boojum witness generator 生成 proof

4. IdentityVerifier.verifyZKProof() 调用预编译的 PLONK 验证逻辑

3.4 隐私保护机制

机制	实现	子阶段
选择性披露	ZK 电路只暴露公开输入	5b (P1)
匿名凭证	Nullifier-based（防双花）	5c (P2)
数据最小化	链上只存哈希，原始数据链下	5a (P0)
凭证撤销	Merkle Tree 撤销列表（高效批量查询）	5a (P0)

---

4. L1 ⟷ L2 跨链 DID 同步

4.1 架构

Ethereum L1                              BabyDriver L2
┌───────────────────┐    Mailbox    ┌────────────────────┐
│ DIDFacet          │◄────────────►│ DIDRegistry (0x8017)│
│ (Diamond Proxy)   │   L2→L1 msg  │                    │
│                   │   L1→L2 msg  │                    │
│ - syncFromL2()    │              │ - syncToL1()        │
│ - pushToL2()      │              │ - receiveFromL1()   │
│ - resolveDID()    │              │                     │
└───────────────────┘              └─────────────────────┘

4.2 同步流程

L2 → L1 同步（DID 创建/更新）:

1. 用户在 L2 调用 DIDRegistry.syncToL1(identity)

2. 合约 emit DIDSynced(identity, documentHash) 事件

3. L2→L1 消息通过 Mailbox 发送（batch finalize 时提交）

4. L1 DIDFacet.syncFromL2() 接收并存储最小镜像 (address → bytes32 docHash)

L1 → L2 同步（外部 DID 导入）:

1. 用户在 L1 调用 DIDFacet.pushToL2(identity, docHash)

2. 通过 Mailbox requestL2Transaction() 发送到 L2

3. L2 DIDRegistry.receiveFromL1() 处理导入

4. 验证 L1 消息来源（msg.sender == BOOTLOADER）

4.3 L1 DIDFacet

部署在 era Diamond Proxy 中：

• 只存储最小数据 mapping(address => bytes32) l2DidHashes

• 提供 resolveDID(address) → bytes32 查询接口

• 第三方 DApp 可通过 L1 验证用户是否拥有有效 BabyDriver DID

---

5. 社会恢复 + 企业 IAM (P2)

5.1 社会恢复

struct RecoveryConfig {
    address[] guardians;      // 守护人列表
    uint8 threshold;          // 恢复阈值 (如 3/5)
    uint64 recoveryDelay;     // 恢复延迟 (如 48h)
    uint256 nonce;
}

恢复流程：

1. 用户丢失密钥 → 联系 guardian

2. threshold 个 guardian 签名同意

3. DIDRegistry.socialRecover(identity, newController, signatures)

4. 48h delay 后生效（给原所有者反应时间）

5. 原 controller 可在 delay 内 cancelRecovery()

5.2 企业 IAM

struct EnterpriseConfig {
    address rootAdmin;
    mapping(bytes32 => Role) roles;
    mapping(address => bytes32[]) memberRoles;
}

struct Role {
    bytes32 name;
    bytes32[] permissions;
    uint256 maxMembers;
}

关键函数：

• createEnterprise(bytes32 name) — 创建企业身份空间

• addRole(bytes32 name, bytes32[] permissions) — 定义角色

• assignRole(address member, bytes32 role) — 分配角色

• revokeRole(address member, bytes32 role) — 撤销角色

• hasPermission(address member, bytes32 permission) → bool — 权限检查

---

6. 系统集成点

6.1 OracleHub (0x8016) 集成

• IdentityVerifier 调用 OracleHub 获取信用评分

• 信用评分 VC 的数据源来自 Oracle 聚合价格

6.2 Bridge 集成

• FastWithdrawalPool 调用 IdentityVerifier.checkCompliance() 做合规检查

• 大额跨链转账触发 DID 合规验证

6.3 SIWE 登录 (EIP-4361)

• 前端使用 Sign-In with Ethereum 消息签名

• 签名消息包含 BabyDriver chain_id (271)

• 后端验证签名 → 查询 DIDRegistry → 返回身份信息

---

7. 交付计划

5a (P0, ~5天) — 核心身份层

交付物：

• DIDRegistry 系统合约 (0x8017) — 注册/解析/更新/撤销/委托

• CredentialRegistry 系统合约 (0x8018) — VC 发行/验证/撤销

• IdentityVerifier 系统合约 (0x8019) — ECDSA 验证模式

• SIWE 登录集成 (EIP-4361)

• 完整 Foundry 测试套件

• Constants.sol + SYSTEM_CONTRACT_LIST 注册

验证标准： 创建 DID → 发行 VC → 验证 VC → 解析 DID 全流程

5b (P1, ~5天) — ZK + Oracle + 跨链

交付物：

• PLONK 电路: KYC 合规证明 + 信用评分证明 (boojum)

• IdentityVerifier 升级: verifyZKProof() 真实 PLONK 验证

• Oracle 集成: getCreditScore() 从 OracleHub 读取

• L1 DIDFacet (Diamond Proxy) + 双向 Mailbox 同步

• ZK witness generator (用户端)

验证标准： ZK proof 生成 → 链上验证 → L1 查询 L2 DID

5c (P2, ~4天) — 高级功能

交付物：

• 社会恢复 (Guardian + threshold 3/5 + 48h delay)

• 多设备管理 (多 verificationMethod)

• 匿名集合成员证明 (Nullifier-based)

• 企业 IAM (角色 + 权限 + 成员管理)

验证标准： 社会恢复 E2E + 企业角色权限检查 + 匿名证明验证

---

8. 需要修改的文件清单

era-contracts-l1 (系统合约)

文件	改动	子阶段
system-contracts/contracts/Constants.sol	添加 DID_REGISTRY/CREDENTIAL_REGISTRY/IDENTITY_VERIFIER 地址	5a
system-contracts/contracts/DIDRegistry.sol	新建系统合约	5a
system-contracts/contracts/CredentialRegistry.sol	新建系统合约	5a
system-contracts/contracts/IdentityVerifier.sol	新建系统合约	5a
system-contracts/contracts/interfaces/IDIDRegistry.sol	新建接口	5a
system-contracts/contracts/interfaces/ICredentialRegistry.sol	新建接口	5a
system-contracts/contracts/interfaces/IIdentityVerifier.sol	新建接口	5a
system-contracts/scripts/constants.ts	注册 DID 系统合约地址	5a
l1-contracts/contracts/state-transition/chain-deps/facets/DIDFacet.sol	L1 DID 查询 facet	5b

era-core (Rust 节点)

文件	改动	子阶段
core/lib/constants/src/contracts.rs	添加 DID 系统合约 Rust 常量	5a
core/lib/types/src/system_contracts.rs	注册到 SYSTEM_CONTRACT_LIST	5a

baby-modules (BabyDriver 自研)

路径	用途	子阶段
baby-modules/did-circuits/	PLONK 电路 (boojum)	5b
baby-modules/did-sdk/	TypeScript SDK (Veramo 集成)	5b

保留的参考仓库

仓库	用途
refs/ethr-did-registry/	DIDRegistry 合约参考
refs/veramo/	TypeScript DID 框架参考
refs/siwe/	SIWE 登录参考
refs/ERC725/	ERC-725 标准参考
refs/did-jwt/	JWT 签名/验证参考
refs/spruceid-ssi/	Rust SSI 基础设施参考