name: self-xyz description: “集成Self协议（self.xyz）——一种隐私优先的身份验证协议，使用零知识证明验证护照和身份证件。当用户提到Self协议、Self身份、self.xyz、护照验证、零知识身份验证、SelfAppBuilder、SelfBackendVerifier、SelfVerificationRoot，或希望添加保护隐私的KYC、年龄验证、国籍检查、OFAC筛查、或使用真实身份文档进行女巫攻击抵抗时使用。涵盖前端二维码集成、后端证明验证以及在Celo链上的智能合约验证。”

Self协议集成

Self允许用户使用零知识证明从护照/身份证件中证明身份属性（年龄、国籍、人类身份）——不暴露任何个人数据。用户在Self移动应用中扫描其文档的NFC芯片，并与您的应用共享一个zk证明。

快速开始（Next.js 链下）

1. 安装

npm install @selfxyz/qrcode @selfxyz/core

2. 前端 — 二维码组件

"use client";
import { SelfQRcodeWrapper, SelfAppBuilder } from "@selfxyz/qrcode";

export default function VerifyIdentity({ userId }: { userId: string }) {
  const selfApp = new SelfAppBuilder({
    appName: "我的应用",
    scope: "my-app-scope",
    endpoint: "https://yourapp.com/api/verify",
    endpointType: "https",
    userId,
    userIdType: "hex",
    disclosures: {
      minimumAge: 18,
    },
  }).build();

  return (
    <SelfQRcodeWrapper
      selfApp={selfApp}
      onSuccess={() => console.log("验证成功")}
      type="websocket"
      darkMode={false}
    />
  );
}

3. 后端 — 验证端点

// 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",                    // 必须与前端scope匹配
    "https://yourapp.com/api/verify",  // 必须与前端endpoint匹配
    true,                              // true = 接受模拟护照（仅开发）
    null,                              // allowedIds (null = 全部)
    new DefaultConfigStore({           // 必须与前端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 URL	`"https"` 或 `"https-staging"`
链上 (合约)	DeFi、代币门控、空投	合约地址（小写）	`"celo"` 或 `"celo-staging"`
深度链接	移动端优先流程	您的API URL	`"https"`

链下：实现最快。证明发送到您的后端，在服务器端验证。
链上：证明由Celo智能合约验证。继承 SelfVerificationRoot。用于无需信任/无需许可的场景。
深度链接：针对移动用户——直接打开Self应用而非扫描二维码。参见 references/frontend.md。

关键注意事项

配置匹配是强制性的 — 前端 disclosures 必须与后端/合约验证配置 完全一致。年龄阈值、国家列表或OFAC设置不匹配会导致静默失败。
合约地址必须小写 — 前端 endpoint 中使用非校验和格式。使用 .toLowerCase()。
国家代码为ISO 3字母 — 例如 "USA"、"IRN"、"PRK"。排除列表最多40个国家。
模拟护照 = 仅限测试网 — 在后端设置 mockPassport: true / 使用 "celo-staging" endpoint类型。真实护照需要主网。创建模拟护照：打开Self应用，点击护照按钮 5次。模拟测试需要禁用OFAC。
版本要求 — @selfxyz/core >= 1.1.0-beta.1。
证明ID — 1 = 护照，2 = 生物识别身份证。必须通过 allowedIds 映射明确允许。
Scope唯一性 — 链上，scope与合约地址进行Poseidon哈希，防止跨合约证明重放。
Endpoint必须可公开访问 — Self应用直接将证明发送到您的endpoint。本地开发请使用ngrok。
常见错误：ScopeMismatch = scope/地址不匹配或非小写地址。Invalid 'to' Address = 错误的 endpointType（celo vs https）。InvalidIdentityCommitmentRoot = 测试网上使用真实护照（请使用主网）。Invalid Config ID = 主网上使用模拟护照（请使用测试网）。

已部署合约（Celo）

网络	地址
主网 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 模式