World ID 智能合约全景指南：从以太坊到 Layer2，30 分钟掌握全流程

关键词：World ID 智能合约、身份管理器、状态桥、Orb 凭证、零知识证明、抗 Sybil、World ID Router、Merkle 树验证

World ID 是一套建立在零知识证明（ZKP）技术之上的链上身份协议，由一组可组合的智能合约构成，覆盖以太坊主网、Optimism、Polygon 与 Base 测试网等多链环境。了解这些合约的组合方式、调用方法与安全注意事项，对开发者（尤其是构建抗 Sybil 攻击 的 dApp 的开发者）至关重要。

本文将用「组件地图＋交互流程＋代码示例＋问答答疑」的形式，一次性把 World ID 合约讲透。

1. 合约总览：四张底牌看清全局结构

链	身份根最终性	World ID 合约类型	Merkle 根到达时间
Ethereum 主网	原生	身份管理器	约 60 分钟
Optimism	桥接	Bridged World ID	约 5 分钟
Polygon	桥接	Bridged World ID	约 40 分钟
Base（测试网）	桥接	Bridged World ID	约 5 分钟

World ID 的核心合约共 4 类，按角色区分：

WorldIdIdentityManager（以太坊专署身份管理器）
StateBridge（OpStateBridge / PolygonStateBridge）
Bridged World ID（OpWorldId / PolygonWorldId）
WorldIdRouter（开发者唯一需要直接交互的聚合路由器）

2. Identity Manager：根生于以太坊的首脑

部署位置：仅 Ethereum 主网（Sepolia 测试网用于调试）。
核心职责：
1. 运行 Semaphore 实例管理身份树（Merkle Tree）。
2. 接收来自 Worldcoin 签约 sequencer 的添加或删除身份事件。
3. 发布最新 Merkle 根到 StateBridge，触发跨链同步。

开发者日常不会直接调用 WorldIdIdentityManager，除非你是在自建 sequencer。

3. State Bridge：把证明的「信任根」传向 Layer2

每一个 Layer2 都会各自拥有：

一条 State Bridge 合约（部署在 以太坊）；
一条 Bridged World ID 合约（部署在 目标链）。

State Bridge 周期性地向 Bridged World ID「广播」最新 Merkle 根。
Layer1 → Layer2 延迟主要由官方 relayer 与 L2 出块速度决定：Optimism≈5分钟，Polygon≈40分钟。

👉 想了解如何无许可部署自定义链的 State Bridge？点击这里解锁跨链扩展路线。

4. Bridged World ID：Layer2 证明验证的执行场

Bridged 合约在功能上与主网合约几乎镜像：

核心接口：verifyProof，使用与以太坊同一份参数规范。
依赖：必须正确接收来自 State Bridge 的 Merkle 根，否则调用将回滚。
无需额外许可：开发者可自由分叉并部署到自家链，实现「私有层」World ID 身份体系。

5. World ID Router：开发者唯一直接对话的合约

“一句话总结：把它当成惟一被关心的合约地址即可。”

自动路由：Router 根据 groupId 判断你是想在以太坊还是 Optimism 验证——不是所有链都开同样的分组。
当前绑定：仅 Orb 凭证 开放上链，故必须传递 groupId = 1。
代理升级无忧：上层合约逻辑升级无需改动 dApp，Router 会代理到最新实现。

verifyProof 公开函数 6 元组参数一次讲清

字段名	类型	说明
`root`	uint256	当前验证的 Merkle 根
`groupId`	uint256	只能是 `1`（Orb）
`signalHash`	uint256	`keccak256(用户信号)` 结果
`nullifierHash`	uint256	证明一次性标识符的哈希
`externalNullifierHash`	uint256	`keccak256(app_id + action)`
`proof`	uint256[8]	来自 IDKit 的零知识证明体

示例调用（Hardhat）：

// 伪代码演示
WorldIdRouter(worldIdRouter).verifyProof(
    root,
    1,
    keccak256("welcome-chat"),
    nullifierHash,
    keccak256(abi.encodePacked(appId, action)),
    proof
);

6. 实战：抗 Sybil 认证的 3 行核心代码

零知识只提供「匿名唯一性」，要让协议 真正抗 Sybil 还需要额外步骤：

记录每一次验证通过后的 nullifierHash。
下次验证前先查重，保证同一地址/身份只能执行一次。

极简示例：

contract SimpleSybilResistant {
    mapping(uint256 => bool) public usedNullifier;

    function claimReward(
        uint256 root,
        uint256 nullifierHash,
        uint256[8] calldata proof
    ) external {
        require(!usedNullifier[nullifierHash], "Already claimed");
        worldIdRouter.verifyProof(root, 1, signalHash, nullifierHash, externalNullifierHash, proof);
        usedNullifier[nullifierHash] = true;
        // 发放奖励...
    }
}

👉 想知道如何把这套逻辑快速集成到前端？一键查看完整示例模版。

7. 常见问答（FAQ）

Q1：如何把 World ID 接入自己主网的 dApp？
A：

npm 安装 @worldcoin/idkit；
用 IDKit 组件获取 root、proof、nullifierHash；
在合约调用 WorldIdRouter.verifyProof(...)；
按上述 nullifier 记重即可。

Q2：State Bridge 能否经典形式再推送到自己私有区块链？
A：可。你只需要：

fork OpStateBridge.sol（或其他）→ 修改 dispatchRoot() 逻辑，把根发送到新链；
fork OpWorldId.sol → 继续作为验证者；
最终部署到新 L2，并替换 Router 的路由表。

Q3：World ID Router 升级会自动影响正在运行的 dApp 吗？
A：不会。Router 经 UUPS 或 Proxy Pattern 部署，升级逻辑后的地址不变，业务端无需变地址。

Q4：Orb 凭证何时会允许更多 groupId？
A：官方计划 2025 Q4 开放 Phone / Orb Mixed Mode；对开发者来说只需等待 Router 更新即可。

Q5：Base 仅测试网，主网上线时间表？
A：目前官方未公布 Base 主网集成时间，可按需在 Sepolia 与 Optimism Sepolia 先验证。

8. 结语：链上身份，从单点钥匙到分布式信任根

World ID 把「物理独特性」转化为「可验证的匿名唯一性」，同时将最重的 身份管理器 留在最安全的以太坊主网， 验证与交互 下沉到速度快、费用低的 Layer2。开发者只需对着 WorldIdRouter 打一行 verifyProof，就完成了跨链、零知识、抗 Sybil 的闭环。

只用 5 分钟部署 World ID，你将拥有最具竞争力的链上身份基础设施。现在就开始动手吧！