World ID Starter Kit (Smart Contracts)

Easiest way to get started with World ID on-chain. This repository contains the minimum requirements to build web3 dApps with World ID, allowing you to easily add sybil-resistance and uniqueness features to your dApp.

This repository contains the smart contract code, and is built with the Foundry toolkit. We also have a Hardhat version in the world-id-starter-hardhat repository.

🏃 Getting started

Start with the verifyAndExecute function on the Contract.sol file, which contains the basic World ID verification logic. You can rename this function as you choose (for example, we use claim on our airdrop example).

Setting your Action ID

The action ID (also called "external nullifier") makes sure that the proof your contract receives was generated for it (more on Action IDs). A sensible default is to use the address of your contract (which will always be unique), but feel free to update if you have a unique use-case. You should be changing the abi.encodePacked(address(this)).hashToField() line, updating the parameters inside the encodePacked call.

Note Make sure you're passing the correct Action ID when initializing the JS widget! The generated proof will be invalid otherwise.

Setting your signal

The signal adds an additional layer of protection to the World ID Proof, it makes sure that the input provided to the contract is the one the person who generated the proof intended (more on signals). By default this contract expects an address (receiver), but you can update it to be any arbitrary string.

To update the signal, you should change the input on the abi.encodePacked(input).hashToField() line. You should provide the exact same string when initializing the JS widget, to make sure the proof includes them.

Note The hashToField part is really important, as validation will fail otherwise even with the right parameters. Make sure to include it!

About nullifiers

Nullifiers are what enforces uniqueness in World ID. You can generate multiple proofs for a given signal and action ID, but they will all have the same nullifier. Note how, in the verifyAndExecute function we first check if the given nullifier has already been used (and revert if so), then mark it as used after the proof is verified.

If your use-case doesn't require uniqueness, you can use them as "anonymous identifiers", linking users between different signals (for example, allowing them to change which address they've verified in a social network). To do this, update the nullifierHashes mapping to point to some sort of identifier instead of a boolean. See this project as an example.

🗝 Usage instructions

1. End users will need a verified identity, which can be obtained through our Simulator (see docs for more info). In production, this would be obtained by verifying with an orb.

2. Use the JS widget to prompt the user with verification (make sure you're providing the correct signal and action ID). Upon acceptance, you'll get a merkle_root, nullifier_hash and proof.

3. The ZKP (attribute proof) is a uint256[8] array and your smart contract expects it that way. For easier handling, the JS widget will return the proof encoded. Unpack your proof before sending it to your smart contract.

import { defaultAbiCoder as abi } from "@ethers/utils";
const unpackedProof = abi.decode(["uint256[8]"], proof)[0];
// You can now pass your unpackedProof to your smart contract

4. Use the obtained parameters, along with any inputs your contract needs (which should be included in the signal), to call your smart contract!

🚀 Deployment

1. If you've added any parameters to your constructor or renamed the contract, you should update the scripts/deploy.js script accordingly.
2. Run cp .env.example .env to create your environment file, and add a RPC_URL for the network you want to deploy (we currently only support the Polygon Mumbai Testnet) and a PRIVATE_KEY for the deployer wallet.
3. Run make deploy to deploy your contract.

🧑‍💻 Development & testing

1. Install Foundry.

   curl -L https://foundry.paradigm.xyz | bash
   foundryup # run on a new terminal window; installs latest version
   

2. Install Node.js v16 or above (required for tests). We recommend nvm if you use multiple node versions.
3. Install dependencies & build smart contracts

   make
   

Warning Make sure you've run make instead of using Foundry directly! We need to build some of WorldID's dependencies in a specific way, and tests will fail otherwise.

Running test suite

This repository includes automated tests, which you can use to make sure your contract is working as expected before deploying it. Of course, any modifications you've made to the Contract.sol file will need to be reflected on the tests as well to make them work.

If you've changed the type of the external nullifier, or the signal, you should look over the src/test/helpers/InteractsWithWorldID.sol and src/test/scripts/generate-proof.js to update them as well.

Once you've done this, you can run the tests,

make test

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 align="center" of a person's iris to verify they are a unique and alive human. 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.

Getting started with World ID

Regardless of how you landed here, the easiest way to get started with World ID is through the the Dev Portal.

World ID Demos

Want to see World ID in action? We have a bunch of Examples.

📄 Documentation

We have comprehensive docs for World ID at https://id.worldcoin.org/docs.

🗣 Feedback

World ID is in Beta, help us improve! Please share feedback on your experience. You can find us on Discord, look for the #world-id channel. You can also open an issue or a PR directly on this repo.