📦 Self zkID verification — 零知识身份验证
v1.0.0集成 Self.xyz 零知识身份协议，在前端扫码、后端验证、Celo 链上三步完成护照/身份证隐私 KYC，无需泄露明文即可完成年龄、国籍、OFAC 筛查与女巫抵抗。
by 详细分析 ▾
运行时依赖
版本
- 首次发布 self-xyz 技能，集成 Self.xyz 隐私优先身份协议。 - 支持零知识证明验证护照/身份证，全程无个人数据明文暴露。 - 提供链下（后端/API）与链上（智能合约）快速接入指南，含前端扫码与后端验证示例。 - 文档涵盖链下、链上、深度链接等集成模式并列出常见坑点。 - 列出 Celo 网络已部署合约地址，附详细配置与高级用法链接。
安装命令
点击复制技能文档
# Self Protocol 集成 Self 让用户通过零知识证明，从护照/身份证中证明身份属性（年龄、国籍、人性），无需暴露任何个人数据。用户在 Self 手机 App 中扫描证件 NFC 芯片后，向你的应用提交 zk 证明。 ## 快速入门（Next.js 链下验证） ### 1. 安装 ``bash npm install @selfxyz/qrcode @selfxyz/core ` ### 2. 前端 — 二维码组件 `tsx "use client"; import { SelfQRcodeWrapper, SelfAppBuilder } from "@selfxyz/qrcode"; export default function VerifyIdentity({ userId }: { userId: string }) { const selfApp = new SelfAppBuilder({ appName: "My App", scope: "my-app-scope", endpoint: "https://yourapp.com/api/verify", endpointType: "https", userId, userIdType: "hex", disclosures: { minimumAge: 18, }, }).build(); return ( console.log("Verified")} type="websocket" darkMode={false} /> ); } ` ### 3. 后端 — 验证接口 `ts // app/api/verify/route.ts import { SelfBackendVerifier, DefaultConfigStore } from "@selfxyz/core"; export async function POST(req: Request) { const { proof, publicSignals } = await req.json(); const verifier = new SelfBackendVerifier( "my-app-scope", // must match frontend scope "https://yourapp.com/api/verify", // must match frontend endpoint true, // true = accept mock passports (dev only) null, // allowedIds (null = all) new DefaultConfigStore({ // must match frontend disclosures minimumAge: 18, }) ); const result = await verifier.verify(proof, publicSignals); return Response.json({ verified: result.isValid, nationality: result.credentialSubject?.nationality, }); } ` ## 集成模式 | 模式 | 适用场景 | endpoint | endpointType | |---------|------------|------------|----------------| | 链下（后端） | Web 应用、API、大多数场景 | 你的 API 地址 | "https" 或 "https-staging" | | 链上（合约） | DeFi、代币门禁、空投 | 合约地址（小写） | "celo" 或 "celo-staging" | | 深度链接 | 移动端优先流程 | 你的 API 地址 | "https" | - 链下：实现最快。证明发到后端，服务器端验证。 - 链上：由 Celo 智能合约验证。继承 SelfVerificationRoot。适用于无需信任/无需许可场景。 - 深度链接：针对移动端用户 —— 直接打开 Self 应用而非扫码。详见 references/frontend.md。 ## 关键陷阱 1. 配置必须严格一致 —— 前端 disclosures 必须与后端/合约的验证配置完全一致。年龄阈值、国家列表或 OFAC 设置不一致会导致静默失败。 2. 合约地址必须小写 —— 前端 endpoint 使用非校验和格式。请用 .toLowerCase()。 3. 国家代码为 ISO 三字母 —— 如 "USA"、"IRN"、"PRK"。排除列表最多 40 国。 4. Mock 护照仅用于测试网 —— 后端设置 mockPassport: true / 使用 "celo-staging" 端点类型。真实护照需主网。创建 mock 护照：打开 Self 应用，连续点击 Passport 按钮 5 次。Mock 测试需关闭 OFAC。 5. 版本要求 —— @selfxyz/core >= 1.1.0-beta.1。 6. 证件 ID —— 1 = 护照，2 = 生物识别身份证。需通过 allowedIds 显式允许。 7. Scope 唯一性 —— 链上时，scope 与合约地址一起进行 Poseidon 哈希，防止跨合约证明重放。 8. 端点必须公网可达 —— Self 应用直接向你的端点发证明。本地开发可用 ngrok。 9. 常见错误： ScopeMismatch = scope/地址不匹配或地址未小写。 Invalid 'to' Address = endpointType 错误（celo vs https）。 InvalidIdentityCommitmentRoot = 主网使用真实护照（请用主网）。 Invalid Config ID = 主网使用 mock 护照（请用测试网）。 ## 已部署合约（Celo） | 网络 | 地址 | |---------|---------| | Mainnet Hub V2 | 0xe57F4773bd9c9d8b6Cd70431117d353298B9f5BF | | Sepolia Hub V2 | 0x16ECBA51e18a4a7e61fdC417f0d47AFEeDfbed74 | | Sepolia Staging Hub V2 | 0x68c931C9a534D37aa78094877F46fE46a49F1A51 | ## 参考资料 如需深入集成细节，请加载： - references/frontend.md —— SelfAppBuilder 完整配置、SelfQRcodeWrapper 属性、使用 getUniversalLink 的深链、披露选项 - references/backend.md —— SelfBackendVerifier 构造函数详解、DefaultConfigStore 与 InMemoryConfigStore 区别、验证结果结构、动态配置 - references/contracts.md —— SelfVerificationRoot 继承模式、Hub V2 交互、setVerificationConfigV2、customVerificationHook、getConfigId、userDefinedData` 用法