Skip to main content

Protocol Overview

How it works

The following diagram outlines the technical flow for a World ID transaction. Find more details on each component in the Components section.

World ID Flowchart

When a user executes a World ID transaction they assert and prove two things:

  1. They are a human.
  2. They are performing a specific action (see below) only once.

What are actions?

An action is something that a single human can perform only once. For example: receive an airdrop, vote on a specific issue, fund a specific project, create an account with a particular service. A project may request verification for multiple actions, but it's important to consider that Proof of uniqueness will be scoped to each action. More on actions can be found in the Glossary.

Proof of personhood

The protocol relies on a Semaphore instance and zero-knowledge proofs, which allow a user to prove their membership to a set (in this case the set of verified identities) without revealing who they are. The Orb performs multiple real-time checks to ensure the person in front is a human that has not been seen before. Advanced details found on Proof of personhood.

Picture of a Worldcoin orb

Proof of uniqueness

Given that we don't know anything about the person who's proving their membership to the set, a critical piece of the protocol is making sure a person can only prove their membership in a particular context only once. For instance, if you're doing an airdrop, you want to make sure a single person can only claim the airdrop once. We do this through actions. A user can only submit a proof for an action once. To define each action, we use action IDs which is an arbitrary string that the verifying party crafts and provides. A single user will always output the same nullifier hash for the same action ID.

When an existing proof for an action ID and the same identity is found, proof of uniqueness fails

Example: Alice is an end user who has verified at a Worldcoin orb. MeshaApp is a dapp with a new token that wants to airdrop a piece but only once per person.

  • MeshaApp asks Alice to verify with World ID and provides action ID meshaApp-airdrop.
  • Alice generates a ZKP in their Worldcoin app using the action ID: meshaApp-airdrop => nullifier_hash_1.
  • MeshaApp can verify the proof comes from an identity belonging to the set of verified identities and can store nullifier_hash_1 in the list of claimed airdrops. Note in particular, MeshaApp has no way of associating nullifier_hash_1 to any particular identity.
  • If Alice ever generates another ZKP at any point in time for the same action ID meshaApp-airdrop, the generated nullifier hash will always be nullifier_hash_1, and therefore MeshaApp can decline any additional airdrop requests for claimed hashes.
  • If Bob (another end user), generates a ZKP with their identity for action ID meshaApp-airdrop, the result will be nullifier_hash_2 (different from Alice's nullifier hash).
  • If Alice generates a ZKP for another action ID (e.g. meshaApp-airdrop-2), the generated nullifier hash will be different from the very first one => nullifier_hash_3.

Components

ComponentOwnerDescription
The OrbWorldcoin (OSS in 2022)Responsible for verifying personhood by obtaining biometric data and submitting verified identities for the protocol.
Worldcoin appWorldcoin (OSS in 2022)Non-custodial wallet that stores the private information from the World ID identity. Generates ZKPs for World ID claims.
JS packageWorldcoin (OSS)Integrate with your dapp to easily interact with World ID and request and receive proofs from the Worldcoin app.
Client appDeveloper (You)Any dapp that has an action that wishes to protect behind World ID. The client app loads the JS package to use World ID.
Smart contractDeveloper (You)Main execution point of World ID. The smart contract verifies submitted ZKPs, ensures uniqueness of ZKPs and then executes whatever action. Can be forked from any of our Example apps.
Client walletEnd userAny ETH-enabled wallet. Executes the transaction the smart contract dictates, providing the ZKP details as well as any other needed parameters.
SequencerWorldcoin (optional)Centralized server that helps batch multiple proof submissions to reduce gas cost.
World ID BackendWorldcoin (optional)Simple service that stores information on Verified Actions.