WorldID Semaphore Contracts

These are the underlying contracts that power World ID. If you're looking to integrate with World ID, you should use the Foundry or Hardhat starter kits.

This repository contains the underlying contracts that make World ID work, powered by the Semaphore library. These contracts are responsible for performing identity operations on chain, and attestation of identities for the purposes of semaphore proofs. Check out user-flows.md for more information on how these contracts relate to the rest of the World ID system.

About World ID

World ID is a protocol that lets you prove a human is doing an action only once without revealing any personal data. Stop bots, stop abuse.

World ID uses a device called the Orb which takes a picture of a person's iris to verify they are a unique and alive human. The protocol only requires a hash-equivalent (i.e. irreversible) of the iris to be stored (which happens on a blockchain). The protocol uses Zero-knowledge proofs so no traceable information is ever public.

World ID is meant for on-chain web3 apps, traditional Cloud applications, and even IRL verifications. Go to the World ID app to get started.

Privileged Actions and Trust

The WorldID Identity Manager uses a bifurcated notion of privilege in production. This operates as follows:

• Owner: The owner is responsible for administrating the contract. In production, the contract's owner will be a multi-signature wallet.
• Identity Operator: The identity operator is responsible for performing identity operations using the contract. In production, the contract's identity operator will be a wallet associated with OpenZeppelin Relay, ensuring that identities are submitted on-chain reliably and in order.

All other contracts use a simple notion of an "owner", that will be held by a multi-signature wallet in production.

What follows below is a table of privileged operations in the WorldID Identity Manager contract, and which of the owner and identity operator has the permission to perform these actions.

Operation	Privileges	Description
acceptOwnership	New Owner	Accepts the transfer of ownership.
disableStateBridge	Owner	Turns off the state bridge.
enableStateBridge	Owner	Turns on the state bridge.
registerIdentities	Identity Operator	Registers new identity commitments into the World ID system.
deleteIdentities	Identity Operator	Registers new identity commitments into the World ID system.
setIdentityOperator	Owner	Sets the address that has permission to act as the Identity Operator.
setRegisterIdentitiesVerifierLookupTable	Owner	Sets the table of verifiers used to verify proofs that correspond to identity insertions.
setDeleteIdentitiesVerifierLookupTable	Owner	Sets the table of verifiers used to verify proofs that correspond to identity insertions.
setRootHistoryExpiry	Owner	Sets the amount of time it takes for a non-current tree root to expire.
setSemaphoreVerifier	Owner	Sets the contract used to verify semaphore proofs.
setStateBridge	Owner	Sets the address of the state bridge. The state bridge is the contract responsible for sending identity tree updates to other chains.
transferOwnership	Owner	Transfers ownership from the current owner to a new owner using a two-step process.
upgradeTo	Owner	Upgrades the implementation of the identity manager to a new version.
upgradeToAndCall	Owner	Upgrades the implementation of the identity manager to a new version and executes a function call while doing so.

While there have been some discussions pertaining to the implementation of timelocks for sensitive actions, many of these actions are required for administrating the contracts in conjunction with external services (such as the signup sequencer). To this end, timelocks would cause problems due to delays that could risk desynchronisation between the contract and external services.

Development

This repository uses the Foundry smart contract toolkit. You can download the Foundry installer by running curl -L https://foundry.paradigm.xyz | bash, and then install the latest version by running foundryup on a new terminal window (additional instructions are available on the Foundry repo).

We provide a docker image running anvil internally which has all the contracts predeployed. This approach is the easiest way to get started interacting with the smart contracts.

Simply run

> docker run -p 8545:8545 ghcr.io/worldcoin/world-id-contracts

This docker image starts an anvil instance with contracts deployed at:

WorldIDRouter: 0x59b670e9fA9D0A427751Af201D676719a970857b
WorldIDIdentityManager: 0x68B1D87F95878fE05B998F19b66F4baba5De1aed

All the contracts are deployed using the default anvil wallet 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266, with the private key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80. This is also the default owner account for all contracts.

Testing

Tests can be run with forge test.

Deployment

contract-deployer

In order to deploy world-id-contracts you need to download contract-deployer, build it and do the following:

1. Download the repo

git clone https://github.com/worldcoin/contract-deployer.git
cd contract-deployer
git submodule update --init --recursive

2. Setup your environment variables (link)

3. Setup deployment config file (link)

4. Deploy

Note

You need to have the rust toolchain installed in order to deploy the contracts. link

Run:

cargo run --release

forge script (new)

A Deploy.s.sol deployment script is provided for easy deployment.

To deploy the entire stack (router, orb WorldID, phone WorldID, all the verifiers, etc.) run

> export PRIVATE_KEY=<YOUR_PRIVATE_KEY>
> export ETHERSCAN_API_KEY=<YOUR_ETHERSCAN_API_KEY>
> forge script script/Deploy.s.sol --broadcast --rpc-url <YOUR_RPC_URL> --verify