The Worldcoin Protocol maintains an onchain representation of a Semaphore set, with each identity in the set representing a verified human. This library provides functionality to sync the state of the onchain Merkle tree, deliver inclusion proofs for a given identity, as well as orchestrate root propagation to bridge roots to other chains, enabling the use of WorldID on other chains.
If using world-tree as a lib, documentation can be generated by running cargo doc --open. This repo also ships with binaries to sync the World Tree and deliver inclusion proof as well as propagate roots across chains. For information on how to install and run these programs, see the following sections below.
The tree-availability-service syncs the state of the World Tree, and spawns an axum server to deliver inclusion proofs for a given identity.
To install the tree-availability-service, clone this repo and run the following command.
cargo install --path .
Usage: tree-availability-service [OPTIONS] --tree-depth <TREE_DEPTH> --tree-history-size <TREE_HISTORY_SIZE> --dense-prefix-depth <DENSE_PREFIX_DEPTH> --address <ADDRESS> --creation-block <CREATION_BLOCK> --rpc-endpoint <RPC_ENDPOINT>
Options:
--tree-depth <TREE_DEPTH>
Depth of the World Tree
--tree-history-size <TREE_HISTORY_SIZE>
Quantity of recent tree changes to cache. This allows inclusion proof requests to specify a historical root
-d, --dense-prefix-depth <DENSE_PREFIX_DEPTH>
Depth of merkle tree that should be represented as a densely populated prefix. The remainder of the tree will be represented with pointer-based structures.
-a, --address <ADDRESS>
Address of the World Tree
-c, --creation-block <CREATION_BLOCK>
Creation block of the World Tree
-w, --window-size <WINDOW_SIZE>
Maximum window size when scanning blocks for TreeChanged events [default: 1000]
-r, --rpc-endpoint <RPC_ENDPOINT>
Ethereum RPC endpoint
-p, --port <PORT>
Port to expose for the tree-availability-service API [default: 8080]
--datadog
Enable datadog backend for instrumentation
-t, --throttle <THROTTLE>
Request per minute limit for rpc endpoint [default: 0]
-h, --help
Print help
tree-availability-service --tree-depth 30 -d 0 --tree-history-size 24 -a 0x78eC127A3716D447F4575E9c834d452E397EE9E1 -c 9493503 -r <RPC_ENDPOINT> -t 50
An easy way to run this service for local testing is to execute:
docker compose up -d --build
This command will build the docker image locally and start the service itself along with an anvil instance to serve as a test blockchain.
Anvil will fork from mainnet and use the real WorldId contract but with only a few identities inserted.
To test that inclusion proofs work you can execute the following curl command:
curl -X POST http://localhost:8080/inclusionProof -H "Content-Type: application/json" -d '{ "identityCommitment": "0x3017972D13A39795AD0D1C3A670D3D36A399B4435E61A510C2D57713D4F5C3DE" }'
Note: It currently takes a while for the service to startup and sync due to a number of reasons. During this time the requests will be either rejected (while anvil is starting up) or you'll receive 503 responses (while the world-tree service is syncing).