World ID Protocol

Note

This spec outlines a draft functionality for beta testing. Changes are expected.

1. Abstract

This spec introduces a ZK circuit (“Proof of Embedding Similarity”) which proves that a WIP-201 Flamingo Verifier matched a live capture and an RP-supplied challenge to the image committed in a user’s PoH Credential. The proof reveals no image, no Flamingo Token and no Credential.

The circuit neither extracts embeddings nor compares them. It verifies the Flamingo Token, binds its compared entries to the Credential image and the RP’s challenge, and checks the Issuer’s Credential and an Authenticator’s authorization of the result. This first iteration supports only the PoH Credential; it shall be generalized to other Credentials in the future (Future Considerations).

2. Motivation

Deepfakes make it hard to know who is on the other side of a video call or behind an online interaction in general. An RP that can capture an image of that party, the challenge, wants to know whether the image stems from a verified real human.

A WIP-201 Flamingo Verifier can be used to compare a live capture and the challenge with the face image of a user with a valid Orb Credential, and run fraud detection models on the live capture images. Its Flamingo Token alone does not answer the RP’s question:

1. No Credential. The Verifier compares any images, so the token does not show the compared image is the one in an issued (Orb) Credential.
2. No owner. It does not show that the user controls the World ID the Credential was issued to.
3. Linkable. The Credential image’s hash is the same in every token of a user, so revealing tokens would link all their proofs.

This proof closes those gaps in zero knowledge. It binds the compared image to the Issuer’s PoH Credential and the RP’s challenge, and the result to a registered Authenticator. It reveals only the challenge hash, the Flamingo configuration and the AAT values. An optional session lets the RP check that a later proof comes from the same World ID.

3. Background

This section is non-normative.

1. Personal Custody Package (PCP). At verification, the Orb packages the user’s images and stores them on the user’s device (World implements Personal Custody). The package includes hashes.json, which the Orb signs: a JSON object mapping each file name, e.g. thumbnail.png for the face thumbnail, to the lowercase hex SHA-256 of the file, plus a version. orb-core writes it as compact JSON (no insignificant whitespace) with sorted keys; constraint 3 relies on this format.
2. PoH Credential. The PoH Credential commits in claim 0 to the Orb-signed hashes.json as $H_\text{var}$ with label CLAIMS_HASH_V1. This chain lets the circuit bind the compared image to the Issuer’s Credential without hashing the image.

4. Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

1. The terms Authenticator, Issuer and Credential are as defined in the World ID Protocol. Verifier, Flamingo Token and Engine are as defined in WIP-201.
2. The Field ($F$), the Curve (BabyJubJub), the hashes ($H_t$, $H_\text{var}$) and EdDSA MUST follow WIP-100. R(d) is as defined in WIP-201.

4.1 Supported Credentials

This first iteration supports only the PoH Credential, comparing the PCP’s thumbnail.png (Background).

4.2 Constants

The following constants are re-used, but are not defined by this spec:

4.3 Flamingo Token Entry Layout

The circuit binds the Flamingo Token’s compared_entry_hash_k (WIP-201) by their index k:

1. When choosing the Flamingo configurations it offers (Proof Request), the RP MUST include only pipelines whose release manifest description places the Credential image, the live capture and the challenge at compared entries 0, 1 and 2. Another order would make the Engine treat entries in roles the circuit does not bind.
2. challenge_hash MUST be R(SHA-256(challenge)) over the exact challenge bytes. The RP MUST compute it itself from the challenge image it checked against the party it interacts with (Reference Verification).

4.4 Proof Request

An RP requesting this proof MUST include the following values in its signed proof request. Their encoding is outside this WIP.

The Authenticator builds the Flamingo request and the circuit inputs from these values. The RP then checks the proof against the same values (Reference Verification).

4.5 Circuit Inputs

All inputs not marked Public MUST remain private.

4.6 Circuit Constraints

The circuit MUST enforce the following constraints. They hold jointly; the numbering only groups them. Every inequality (<, <=) is over integers range-checked to the stated width.

1. Flamingo Token Verification

   • Enforce WIP-201 Flamingo Token Verification, yielding its signed digest and compared_entry_hash.
   • compared_entry_hash[3] == 0.

2. Challenge Binding

   • challenge_hash != 0.
   • compared_entry_hash[2] == challenge_hash.

3. Credential Image Binding

   1. hashes.json is the Credential’s.
      • MIN_HASHES_JSON_BYTES <= hashes_json_len <= MAX_HASHES_JSON_BYTES, and the chunks beyond hashes_json_len are zero.
      • claims[CLAIM_INDEX] equals $H_\text{var}$ (WIP-100 §3.3.3) with label CLAIMS_HASH_V1 over the first hashes_json_len bytes. The capacity tag binds hashes_json_len, not MAX_HASHES_JSON_BYTES; the last chunk holds only the remaining bytes, and only the $\lceil$hashes_json_len/31$\rceil$ chunks are absorbed.
      • Only the chunks around digest_offset are split into bytes; other chunks with the same commitment would be a Poseidon2 collision.
   2. Extract the image digest.
      • 18 <= digest_offset and digest_offset + 64 < hashes_json_len.
      • The 64 bytes at digest_offset are lowercase hexadecimal digits, followed by ", all within the first hashes_json_len bytes.
      • The 17 bytes before digest_offset are "thumbnail.png":", and the byte before them is { or ,.
      • The digits decode as the 32-byte big-endian digest credential_digest.
   3. Bind it to the Flamingo Token.
      • compared_entry_hash[0] == R(credential_digest).

4. World ID Authentication

   1. Select the key.
      • Range-check pk_index as 3-bit and constrain pk_index < NUM_KEYS.
      • pk = user_pk[pk_index]. Inactive slots are the identity $(0,1)$, which the signature check in step 3 rejects.
   2. Prove registration.
      • Compute offchainSignerCommitment = H_16(MERKLE_LEAF_DS; user_pk[0].x, user_pk[0].y, …, user_pk[6].x, user_pk[6].y) per WIP-100 §3.8, including inactive slots.
      • Range-check 0 < leaf_index < 2^MAX_DEPTH.
      • Recompute the root from offchainSignerCommitment at leaf_index with siblings per WIP-100 §5.3, and constrain it to equal merkle_root.
   3. Verify the authorization.
      • Compute message = H_4(DS_WIP_202_AUTH; digest, verifier_key.x, verifier_key.y), with digest and verifier_key from item 1.
      • Verify (auth_r, auth_s) by pk over message, following all requirements of WIP-100 §3.5.1.

5. Session Commitment

   • session_id * (session_id - H_3(DS_SESSION_COMMITMENT; leaf_index, session_id_r)) == 0.
   • This makes the session optional: session_id = 0 means no session, and any other value MUST be this World ID’s commitment.

6. Credential Verification

   1. Verify the Issuer’s signature.
      • Compute sub = H_3(DS_CREDENTIAL_SUB; leaf_index, cred_sub_blinding_factor).
      • Compute claims_hash, the Poseidon2 $t=16$ permutation over [claims[0], …, claims[14], 0] with output element 1.
      • Range-check cred_id as 64-bit and compute cred_id_packed = cred_id + issuer_version * 2^64.
      • Verify (cred_r, cred_s) by cred_pk over H_8(DS_CREDENTIAL_V1; issuer_schema_id, sub, cred_genesis_issued_at, cred_expires_at, claims_hash, cred_associated_data_hash, cred_id_packed).
   2. Check validity.
      • Range-check now as 32-bit and the Credential times as 64-bit.
      • now < cred_expires_at and genesis_issued_at_min <= cred_genesis_issued_at.

Steps 4.2, 5 and 6.1 MUST use the same leaf_index, which binds the Credential to the World ID whose Authenticator authorized the result.

4.7 Verification Requirements

1. Root Freshness. Verifiers MUST check that the provided public input merkle_root is valid and non-expired. Verifiers MAY check WorldIDRegistry.isValidRoot(merkle_root) on every verification or cache a valid result until the root’s actual expiration (e.g. from WorldIDRegistryV2.getRootExpiration). The configured getRootValidityWindow() is not the root’s remaining lifetime and MUST NOT, by itself, determine the cache duration. A getRootExpiration result of 0 denotes the latest root, not an unlimited cache lifetime. Cache access MUST NOT extend the expiration.
2. Proving System. Proofs of Embedding Similarity MUST use the ProveKit proving system. Verifiers MUST NOT use verification artifacts supplied by the prover.

4.8 Reference Verification

An RP accepts a proof if the following hold. It MUST check items 2–7 before verifying the proof (item 1).

1. The proof verifies according to Proving System.
2. The Flamingo Token inputs pass WIP-201 Reference Verification, with an engine_config_hash that follows Entry Layout.
3. now is within 5 minutes of the RP’s own clock.
4. The World ID and Credential are trusted:
   • merkle_root satisfies Root Freshness at verification time;
   • cred_pk is a trusted Issuer key for issuer_schema_id and issuer_version, for the PoH Credential.
5. The request matches:
   • genesis_issued_at_min is the RP’s own;
   • challenge_hash is R(SHA-256(challenge)) of a challenge image the RP checked against the party it interacts with.
6. If the RP needs this proof to concern the same World ID as another proof, session_id is nonzero and equals that proof’s session commitment.
7. AAT values. If has_aat = 1, trust_anchor_key_hash, platform, sec_level, sec_meta, authenticator_meta and min_build_version are within the RP’s own policy (WIP-106 §4), whether or not its request stated them. If has_aat = 0, the RP accepts proofs without an AAT.

5. Rationale

1. Authenticator authorization in the circuit. As in other World ID proofs, a signature by a registered Authenticator key shows the prover controls the World ID the Credential was issued to. A copy of the Credential and hashes.json alone cannot produce a proof, revoking an Authenticator stops its proofs, and even a compromised Verifier cannot authorize results for a World ID whose Authenticators it does not control.
2. Binding the compared image to the PoH Credential. The PoH Credential commits to hashes.json, which lists the SHA-256 of the face thumbnail under thumbnail.png. The circuit reads that digest at a prover-supplied offset and requires it to equal compared_entry_hash[0], so the live capture and challenge were compared with the Credential image. The offset is safe because in the compact format orb-core writes (Background) the checked pattern occurs only once.
3. Fixed entry layout in the Flamingo Token. Positions bind entries to roles without parsing the Engine release manifest in the circuit.
4. Optional session ID. An RP can check that a later proof comes from the same World ID as an earlier one, e.g. so a different person cannot take over an account. It is optional so proofs stay unlinkable by default.
5. Credential verification In-circuit credential verification allows the RP to verify that the World ID user holds a valid Orb-verified PoH credential.
6. Only the challenge hash is public. A public challenge_hash is what lets the RP verify that the proof concerns its own challenge, and with it the party it interacts with; without this check the proof is meaningless. The Credential image’s hash is constant per user and would link all their proofs, so it stays private, and so does the live capture’s.

6. Alternatives Considered

1. Comparing embeddings in the circuit. Rejected: extraction and fraud detection would still run outside, and the circuit would need fixed-point arithmetic, a fixed embedding dimension and a hash per embedding.
2. Verifying the AAT in the circuit. Rejected: verification in the Flamingo Verifier per WIP-201 saves the TAKT’s EdDSA verification and the AAT’s ES256 verification on the device, which circuits can not do efficiently yet.
3. Verifying more in the Flamingo Verifier. EdDSA verifications dominate the circuit’s cost, so moving more of them into the TEE is tempting. Rejected: World ID authentication there would reveal the leaf index, a permanent identifier, to the TEE, require the Authenticator key to leave the device, and remove the check a compromised Verifier cannot forge. Credential verification there would reveal the Credential and tie the Verifier to one Credential format, while it currently compares any images.

7. Security

1. Privacy. The proof hides the media, the Flamingo Token, the Credential and hashes.json. The AAT’s public values, engine_config_hash, challenge_hash and now are public; an uncommon combination can narrow the set of possible users.
2. No uniqueness. An Embedding Similarity Proof provides no uniqueness guarantees by design. Its use case is different. An RP that needs uniqueness MUST also request a Uniqueness Proof with the same nonzero session_id.
3. Relay and stream integrity. A proof shows the challenge image matches the Credential’s subject. It does not establish that a video stream is unmodified or prevent a relayed interaction.

8. Future Considerations

1. Other Credentials. The circuit shall be generalized to other Credentials, likely through a circuit-friendly, general format for Credentials and custody packages.

9. Backwards Compatibility

This WIP introduces a new interface; no existing contracts or functionality are affected.