self-xyz

核心用法

Self Protocol 集成技能提供了一套完整的零知识身份验证方案，支持三种集成模式：链下验证（Web应用/API）、链上验证（Celo智能合约）和深度链接（移动端优先）。开发者通过 @selfxyz/qrcode 和 @selfxyz/core 两个官方包，可在 Next.js 等现代前端框架中快速实现二维码扫描验证流程。用户通过 Self 移动应用扫描护照或身份证的 NFC 芯片，生成零知识证明并分享至应用，全程不暴露原始个人数据。

前端使用 SelfAppBuilder 配置验证参数（如最低年龄、国籍披露等），通过 SelfQRcodeWrapper 组件渲染二维码；后端使用 SelfBackendVerifier 进行证明验证，支持自定义配置存储。链上场景则继承 SelfVerificationRoot 合约，利用 Celo 网络的 Hub V2 合约完成去信任化验证。

显著优点

1. 隐私优先架构：采用零知识证明技术，用户可证明年龄、国籍、人性等属性而无需透露具体护照号码、姓名等敏感信息，从根本上解决传统 KYC 的数据泄露风险。

2. 多场景覆盖：一套方案同时支持链下快速集成（适合 Web2 应用）、链上无许可验证（适合 DeFi 和 DAO 治理）以及移动端深度链接，灵活性极高。

3. 真实身份锚定：基于政府签发的护照和身份证 NFC 芯片数据，提供比传统钱包签名更强的 Sybil 抵抗能力，有效防止女巫攻击。

4. 合规友好：内置 OFAC 筛查、年龄验证、国籍检查等常见合规需求，支持 3 位 ISO 国家代码配置，满足全球监管要求。

5. 开发体验完善：提供 mock 护照测试模式（开发环境）、详细的错误代码说明、配置匹配检查清单，大幅降低集成调试成本。

潜在缺点与局限性

1. 硬件依赖限制：用户必须持有带 NFC 芯片的护照或身份证，且需安装 Self 移动应用，这在部分发展中国家或老年用户群体中渗透率有限。

2. 网络生态绑定：链上验证目前主要支持 Celo 网络，若项目基于 Ethereum、Polygon 等其他 L1/L2，需额外桥接或等待多链支持。

3. 配置严格性：前端 disclosures 与后端/合约验证配置必须完全匹配，包括年龄阈值、国家列表、OFAC 设置等，任何不匹配都会导致静默失败，调试难度较高。

4. 国家代码限制：排除列表最多支持 40 个国家，对于需要复杂地理围栏的场景可能不足。

5. 版本兼容性：要求 @selfxyz/core >= 1.1.0-beta.1，早期版本可能存在 API 差异，升级时需注意破坏性变更。

适合的目标群体

• Web3 项目方：需要隐私保护型 KYC 的 DeFi 协议、空投项目、DAO 治理平台
• 金融科技开发者：构建年龄验证、国籍合规检查的金融应用
• 企业合规团队：寻求 GDPR/CCPA 友好的身份验证方案，避免存储用户原始身份数据
• Celo 生态开发者：利用原生集成的链上验证能力构建去中心化应用
• 隐私技术研究者：探索零知识证明在真实世界身份场景的应用落地

使用风险

1. 环境配置风险：开发测试时若误将 mockPassport: true 或 celo-staging 配置部署至生产环境，会导致验证逻辑被绕过。文档虽明确区分环境，但人为失误仍可能发生。

2. 合约地址验证：文档提供的 Hub V2 合约地址需通过官方渠道二次确认，若地址被篡改或网络升级，可能导致资金或验证逻辑风险。

3. 依赖项更新：@selfxyz 包处于活跃开发期（存在 beta 版本），未来 API 可能调整，需关注官方更新日志避免兼容性问题。

4. 性能与可用性：零知识证明生成依赖用户设备计算能力和网络连接，低端设备或弱网环境下体验可能下降；后端验证涉及密码学运算，高并发场景需评估服务器负载。

5. 法律合规边界：虽然技术实现隐私保护，但具体应用场景（如年龄验证、国籍限制）仍需符合当地法律法规，技术方案不能替代法律合规审查。