社会恢复 + 企业 IAM — 设计

日期: 2026-03-06 状态: 已批准 前置: Phase 5a (DID 核心) + Phase 5b (ZK 身份证明 + Genesis 部署)

---

概览

Phase 5c 在现有 DID 系统（0x8017 DIDRegistry, 0x8018 CredentialRegistry, 0x8019 IdentityVerifier）基础上扩展三项能力：

1. 社会恢复 — 扩展 DIDRegistry (0x8017)

2. 企业 IAM — 新增 EnterpriseIAM (0x801A) 系统合约

3. 选择性披露 — 扩展 IdentityVerifier (0x8019)

架构决策：最小化新合约数量，优先扩展现有合约，仅在职责不同时新建。

---

Part 1: 社会恢复（扩展 DIDRegistry 0x8017）

模型

混合模式：N-of-M 多签 + 时间锁。

• 用户设置 M 个 guardian（最多 7 个），恢复需 N 个批准

• 执行前强制 24h 时间锁，原 controller 可在此期间取消

• Guardian 变更自动清除所有待处理恢复请求

新增存储

struct RecoveryConfig {
    address[] guardians;       // M 个 guardian 地址
    uint8 threshold;           // N-of-M 的 N
    uint64 timelockDuration;   // 时间锁（默认 24h = 86400）
}

struct RecoveryRequest {
    address newController;     // 恢复目标地址
    uint64 initiatedAt;        // 发起时间戳
    uint8 approvalCount;       // 已批准数
    mapping(address => bool) hasApproved;  // guardian 是否已批准
}

mapping(address => RecoveryConfig) private _recoveryConfigs;
mapping(address => RecoveryRequest) private _recoveryRequests;

新增函数

函数	调用者	说明
setRecovery(address[] guardians, uint8 threshold, uint64 timelockDuration)	controller	设置/更新恢复配置
initiateRecovery(address identity, address newController)	guardian	发起恢复 + 第一票
approveRecovery(address identity)	guardian	批准恢复
executeRecovery(address identity)	任何人	时间锁到期后执行
cancelRecovery()	controller	取消待处理恢复
getRecoveryConfig(address identity)	任何人 (view)	查询恢复配置
getRecoveryRequest(address identity)	任何人 (view)	查询恢复请求状态

约束

• threshold > 0 && threshold <= guardians.length && guardians.length <= 7

• timelockDuration >= 1 hours（最少 1 小时）

• Guardian 不能是 identity 自己

• Guardian 不能重复

• setRecovery 清除所有待处理请求（防止 guardian 更改攻击）

事件

event RecoveryConfigured(address indexed identity, uint8 threshold, uint8 guardianCount);
event RecoveryInitiated(address indexed identity, address indexed newController, address indexed initiator);
event RecoveryApproved(address indexed identity, address indexed guardian, uint8 approvalCount);
event RecoveryExecuted(address indexed identity, address indexed oldController, address indexed newController);
event RecoveryCancelled(address indexed identity);

L1 同步

• Type 8: RecoveryInitiated → abi.encode(uint8(8), identity, newController, initiatedAt)

• Type 9: RecoveryExecuted → abi.encode(uint8(9), identity, oldController, newController, nonce)

---

Part 2: 企业 IAM（新增 EnterpriseIAM 0x801A）

理由

企业 IAM 涉及组织、角色、权限位图等独立于 DID 的概念，放入新系统合约更清晰。

核心数据结构

struct Organization {
    address orgDID;           // 对应 DIDRegistry 中的身份
    address owner;            // 组织管理员
    uint256[] roleIds;        // 角色 ID 列表
    uint256 memberCount;      // 成员数
    bool active;
}

struct Role {
    bytes32 name;             // 角色名 (keccak256)
    uint256 permissions;      // 权限位图 (uint256 = 256 位)
    address admin;            // 可分配此角色的管理员
}

权限常量（位图）

uint256 constant PERM_ISSUE_CREDENTIAL   = 1 << 0;   // 发行凭证
uint256 constant PERM_REVOKE_CREDENTIAL  = 1 << 1;   // 撤销凭证
uint256 constant PERM_MANAGE_MEMBERS     = 1 << 2;   // 管理成员
uint256 constant PERM_MANAGE_ROLES       = 1 << 3;   // 管理角色
uint256 constant PERM_VIEW_REPORTS       = 1 << 4;   // 查看报告
uint256 constant PERM_MANAGE_COMPLIANCE  = 1 << 5;   // 管理合规
uint256 constant PERM_ADMIN              = 1 << 6;   // 超级管理员
uint256 constant PERM_SIGN_TRANSACTIONS  = 1 << 7;   // 签名交易

存储

mapping(bytes32 => Organization) private _organizations;    // orgId => Organization
mapping(bytes32 => mapping(uint256 => Role)) private _roles; // orgId => roleId => Role
mapping(bytes32 => mapping(address => uint256)) private _memberRoles; // orgId => member => roleId
mapping(bytes32 => uint256) private _roleCounter;           // orgId => next roleId

函数

函数	调用者	说明
createOrganization(bytes32 orgId, address orgDID)	DID controller	创建组织（需 DID 活跃）
createRole(bytes32 orgId, bytes32 name, uint256 permissions)	org owner / MANAGE_ROLES	创建角色
assignRole(bytes32 orgId, address member, uint256 roleId)	org owner / MANAGE_MEMBERS	分配角色
revokeRole(bytes32 orgId, address member)	org owner / MANAGE_MEMBERS	撤销角色
hasPermission(bytes32 orgId, address member, uint256 permission)	任何人 (view)	检查权限
getMemberRole(bytes32 orgId, address member)	任何人 (view)	查询成员角色
getOrganization(bytes32 orgId)	任何人 (view)	查询组织信息
getRole(bytes32 orgId, uint256 roleId)	任何人 (view)	查询角色详情
deactivateOrganization(bytes32 orgId)	org owner	停用组织

DIDRegistry 集成

• createOrganization 需验证 orgDID 在 DIDRegistry 中活跃

• Owner 必须是 orgDID 的 controller 或 delegate

• 通过 staticcall DIDRegistry.isActive() 和 DIDRegistry.resolveDID() 验证

L1 同步

• Type 10: OrgCreated → abi.encode(uint8(10), orgId, orgDID, owner)

• Type 11: RoleAssigned → abi.encode(uint8(11), orgId, member, roleId)

• Type 12: RoleRevoked → abi.encode(uint8(12), orgId, member)

---

Part 3: 选择性披露（扩展 IdentityVerifier 0x8019）

模型

选择性披露（Selective Disclosure）：用户用 ZK 证明展示凭证的特定属性，而不暴露完整数据。

例如：证明 "年龄 >= 18" 而不暴露出生日期。

新增存储

struct DisclosurePolicy {
    bytes32 credentialType;      // 关联的凭证类型
    bytes32[] requiredAttributes; // 需要验证的属性列表 (keccak256)
    uint8 circuitType;           // 使用的 ZK 电路类型
    bool active;
}

mapping(bytes32 => DisclosurePolicy) private _disclosurePolicies; // policyId => Policy
mapping(address => mapping(bytes32 => bool)) private _disclosureResults; // identity => policyId => pass

新增电路类型

在现有基础上（0=KYC, 1=Credit, 2=Enterprise）扩展：

circuitType	用途	示例
3	Age Proof	证明年龄 >= X
4	Income Proof	证明收入在范围 [A, B]
5	Region Proof	证明属于某地区集合

新增函数

函数	调用者	说明
registerDisclosurePolicy(bytes32 policyId, bytes32 credentialType, bytes32[] requiredAttributes, uint8 circuitType)	bootloader / system call	注册披露策略
verifySelectiveDisclosure(address identity, bytes32 policyId, uint256[2] pA, uint256[2][2] pB, uint256[2] pC, uint256[] publicInputs)	system call	ZK 验证选择性披露
hasValidDisclosure(address identity, bytes32 policyId)	任何人 (view)	查询披露是否已验证通过
getDisclosurePolicy(bytes32 policyId)	任何人 (view)	查询策略详情

与现有 ZK 基础设施的关系

• 复用 _circuitVerifiers 映射（已有 0/1/2，新增 3/4/5）

• 复用 _usedProofs 防重放保护

• 复用 Groth16 验证调用模式（staticcall verifyProof）

• verifySelectiveDisclosure 内部调用已有的 proof 验证逻辑，然后将结果写入 _disclosureResults

合规性钩子

verifySelectiveDisclosure 成功后自动设置对应 compliance key：

bytes32 complianceKey = keccak256(abi.encodePacked("SD_", policyId));
_compliance[identity][complianceKey] = true;

这样其他合约可以通过 checkCompliance(identity, complianceKey) 验证。

---

系统合约地址总表

地址	合约	Phase
0x8016	OracleHub	P2
0x8017	DIDRegistry	P5a + P5c (社会恢复)
0x8018	CredentialRegistry	P5a
0x8019	IdentityVerifier	P5a/b + P5c (选择性披露)
0x801A	EnterpriseIAM	P5c (新增)

---

接口变更总结

IDIDRegistry.sol 新增

// Social Recovery
function setRecovery(address[] calldata guardians, uint8 threshold, uint64 timelockDuration) external;
function initiateRecovery(address identity, address newController) external;
function approveRecovery(address identity) external;
function executeRecovery(address identity) external;
function cancelRecovery() external;
function getRecoveryConfig(address identity) external view returns (address[] memory guardians, uint8 threshold, uint64 timelockDuration);
function getRecoveryRequest(address identity) external view returns (address newController, uint64 initiatedAt, uint8 approvalCount, bool executable);

IIdentityVerifier.sol 新增

// Selective Disclosure
function registerDisclosurePolicy(bytes32 policyId, bytes32 credentialType, bytes32[] calldata requiredAttributes, uint8 circuitType) external;
function verifySelectiveDisclosure(address identity, bytes32 policyId, uint256[2] calldata pA, uint256[2][2] calldata pB, uint256[2] calldata pC, uint256[] calldata publicInputs) external returns (bool);
function hasValidDisclosure(address identity, bytes32 policyId) external view returns (bool);
function getDisclosurePolicy(bytes32 policyId) external view returns (bytes32 credentialType, bytes32[] memory requiredAttributes, uint8 circuitType, bool active);

IEnterpriseIAM.sol（新建）

interface IEnterpriseIAM {
    struct Organization { ... }
    struct Role { ... }

    function createOrganization(bytes32 orgId, address orgDID) external;
    function createRole(bytes32 orgId, bytes32 name, uint256 permissions) external;
    function assignRole(bytes32 orgId, address member, uint256 roleId) external;
    function revokeRole(bytes32 orgId, address member) external;
    function hasPermission(bytes32 orgId, address member, uint256 permission) external view returns (bool);
    function getMemberRole(bytes32 orgId, address member) external view returns (uint256);
    function getOrganization(bytes32 orgId) external view returns (address orgDID, address owner, uint256 memberCount, bool active);
    function getRole(bytes32 orgId, uint256 roleId) external view returns (bytes32 name, uint256 permissions, address admin);
    function deactivateOrganization(bytes32 orgId) external;
}

---

测试策略

每个 Part 独立的 Foundry 测试文件：

1. DIDRegistryRecovery.t.sol — 社会恢复单元测试 (~20 tests)

2. EnterpriseIAM.t.sol — 企业 IAM 单元测试 (~20 tests)

3. IdentityVerifierDisclosure.t.sol — 选择性披露单元测试 (~15 tests)

4. Phase5cE2E.t.sol — 跨合约 E2E 测试 (~10 tests)

Genesis 影响

• DIDRegistry 和 IdentityVerifier 代码变更需要重新编译系统合约

• 新增 EnterpriseIAM 需要注册到 Constants.sol + SYSTEM_CONTRACT_LIST

• 需要 genesis 重部署（与 Phase 5b 相同流程）