# Semaphore Phase 2 Multi-Party Trusted Setup Participant Guide

*Adapted from Brian Gu's [zkparty MPC Participant Guide](https://hackmd.io/AFqIQYGCQDmNCXNVmA54-Q?both).*

Thanks for helping to participate in Semaphore's phase 2 trusted setup ceremony. This ceremony will produce the proving and verifying keys for the [Semaphore zero-knowledge signalling gadget](https://github.com/appliedzkp/semaphore), which enables privacy-preserving distributed applications on Ethereum. Read more about this ceremony [here](https://github.com/appliedzkp/semaphore-phase2-setup/).

This guide will walk you through how to do so.

We are grateful to [Aztec Protocol](https://www.aztecprotocol.com/) as this ceremony would not be possible without their open-source [Ignition ceremony](https://www.aztecprotocol.com/ignition/) software, which we have modified.

## What you need

1. An Ethereum private key (**not** stored in a hardware wallet)
2. Docker on a command line
3. An Internet connection
4. About 10-30 minutes of free time

## Register for the ceremony

The coordinator of the ceremony requires your Ethereum address (**not an address from a key stored in a hardware wallet**) to add you to the queue.

There are five ways to register for the ceremony.

First, if you have already signed up for the ceremony via a Google form which Wei Jie sent to you, you are already registered. You will be a Tier 1 participant.

Second, if you had signed up for the [Aztec Ignition](https://ignition.aztecprotocol.com/) ceremony in late 2019, you can just use the same private key which you had had used for Ignition for this ceremony. If your Ethereum address is in [this JSON file](https://ignition.aztecprotocol.com/api/state) (use Ctrl-F to locate it), you can use it. You will be a Tier 2 participant.

Third, you can send at least 1 mainnet wei (`0.000000000000000001` ETH) to the admin address of the ceremony, which is `0xdB689954DD60745aC50987c94e5a669153D44389`. Doing so will register the address which you used to send the ETH. You will be a Tier 3 participant.

Fourth, you can select a random private key from [this list](https://hackmd.io/QKzT41VJTJai_FpF8B003w) of 50 keys on a first-come-first-serve basis. You should use this method if you prefer to be anonymous. You will be a Tier 3 participant.

Lastly, you can reach out to Wei Jie (@weijiek) on Telegram who can add you to the list manually. This may take a while due to time constraints.

## Participating in a ceremony (no-frills mode)

Follow these instructions to get and run the MPC client. Your MPC client will automatically connect to the coordinator server and make a contribution when its turn arrives.

The following instructions work best on Linux or MacOS. For Microsoft Windows, use [these instructions instead](#Windows-Instructions).

### Getting the client
First, make sure you have Docker installed.

Next, pull our pre-built client image from Dockerhub:

docker pull bgu33/zkparty

If you'd like to build a Docker image from source yourself, see the section below on participating with manual / extra security.

### Participating

Once you've downloaded or built the client image, you can join and participate in a ceremony by running this command:

docker run -ti -e API_URL=http://phase2.semaphore.appliedzkp.org:8081/api -e PRIVATE_KEY=0x... bgu33/zkparty:latest

Replace `0x...` with the private key of the Ethereum account you used to register for the ceremony. Obviously, keep this private!

That's it! Leave the client running on a machine with a stable Internet connection for about 15-20 minutes, or at least so long as you have not completed your part of the ceremony

Note that the UI may appear to do nothing while the server validates your contribution. Don't worry, just wait a few minutes and the server will respond.


Remember to clear your terminal history:

history -c

Bash users should also inspect and edit `~/.bash_history` to ensure that they remove their private key from their history file.

### Spectating

Assuming that you have pulled the Dockerhub repository, you can spectate by running the following command with a private key that does NOT correspond to a registered address in the ceremony. (It's the same command as above.)

docker run -ti -e API_URL=http://phase2.semaphore.appliedzkp.org:8081/api -e PRIVATE_KEY=0x1234000000000000000000000000000000000000000000000000000000000000 bgu33/zkparty:latest


.

### Removing the Docker container (and image)

First, find the name of the Docker container you just ran running:

docker container ls -a | grep bgu33/zkparty

CONTAINER ID    IMAGE                   ....    NAMES
160994b1f676    bgu33/zkparty:latest    ....    busy_vaughan

Delete the container:

docker rm <container name, e.g. busy_vaughan>

## Windows Instructions

1. Visit and download https://github.com/docker/toolbox/releases
2. Once downloaded and installed, go to your Start Menu > Programs > Docker > Docker Quickstart Terminal.
3. The quickstart terminal may take 5 minutes or more depending on your computer's speed. Once it is finished you will see a picture of an ASCII whale with the words docker is configured to use the default machine with IP `xxx.xxx.xxx.xxx`.
4. Continue to type the commands in the [Participating in the ceremony (no-frills mode) section](#Participating-in-a-ceremony-no-frills-mode).

Removing containers:

1. When your part of the ceremony is complete you will see a line at the top of the CLI screen indicating such. You can close out of the CLI window.
2. Open the Docker Quickstart Terminal again.
3. Type `docker container ls -a | grep bgu33/zkparty`
4. For every docker container that you have running using the zkparty container type `docker stop <CONTAINER_NAME>` (example: `docker stop keen_torvalds`). Do this command for every container you need to remove.
5. Type `docker rm <CONTAINER_NAME>` for each container you want to remove.
6. Once you remove all of your containers run the command `docker container ls -a | grep bgu33/zkparty` to verify that you do not have any containers existing that ran the ceremony.

## Participating in a ceremony (manual / extra security)

### Building

If you'd like to build the Docker image yourself from [source](https://github.com/briangu33/Setup), follow the instructions here.

First, make sure you have [Docker](https://www.docker.com/products/docker-desktop) installed.

To get started, you need to build the image from the Setup repository. Clone the repository:

git clone https://github.com/briangu33/Setup
cd Setup
git submodule update --init

Next, run the `./build-client.sh` script in the root directory. This builds the necessary Docker images. You need to have about 5GB of space available.

The client image that is built is tagged as `setup-mpc-client:latest`. Note that this script will also build two other intermediate images, `setup-tools:latest` and `setup-mpc-common:latest`. You can ignore these.

### Participating
The no-frills contribution mode downloads the latest parameter set from the server and automatically makes a contribution with OS entropy. However, if you'd like to have a little more control over how you contribute to the ceremony, you can contribute in OFFLINE (manual) mode. You'll still have to run an empty / "OFFLINE mode" client that signals to the server that you're indeed online and ready to contribute (else the server will skip over you - see "Notes"), but the actual work of generating the contribution can be done by yourself. *You must be a tier 0 or tier 1 whitelisted participant to run in manual mode. Please contact Wei Jie (@weijie) on Telegram if you would like to do so so that he can add you to the whitelist.*

To run the client in OFFLINE mode:

cd setup-mpc-client
API_URL=http://phase2.semaphore.appliedzkp.org:8081 PRIVATE_KEY=0x... COMPUTE_OFFLINE=1 ./run-client.sh

This above command starts an "empty" client that tells the server not to skip over your turn.

If you're running your client in this mode, the following is your responsibility to do manually:
- Grab the most recent parameter set, from the last completed participant
- Run contribution binaries to contribute your entropy to the parameter set
- Upload your new parameter set to the server

Note that download, computation, and upload can be run from ANY machine, completely independent of the empty client you are running. The only constraint is that your upload must be signed with the private key you've registered for the ceremony with.

We have provided scripts for all three of these operations in `setup-mpc-client-bash`. Here's how to use them:

#### Download

cd setup-mpc-client-bash
API_URL=http://phase2.semaphore.appliedzkp.org:8081 PREV_ADDRESS=0x... ./download.sh

Note that you'll need to refer to the interface of your empty client to get the address of the most recent validated ceremony participant, `PREV_ADDRESS`. This writes to a file `params.params` in your current directory.

#### Contribute

contribute <in_params_filename> <entropy_str> <out_params_filename> <optional 1000>

The `contribute` program is compiled from Kobi Gurkan's MPC contribution [Rust library](https://github.com/kobigurk/phase2-bn254/tree/master/phase2). The last parameter is optional; put `1000` as the fourth argument if you'd like to print progress reports on the computation to terminal.

**This is the trusted step.** Security-minded participants may want to perform this step on an air-gapped computer with an exotic source of entropy.

#### Upload

API_URL=http://phase2.semaphore.appliedzkp.org:8081 PARAMS_PATH=/path/to/params PRIVATE_KEY=0x... ./sign_and_upload.sh

Signs and uploads the parameters you generated.

## Verifying ceremony integrity
A number of tools are available to help you trustlessly verify ceremony integrity. Your ceremony coordinator should publish publically their `circuit.json` file and the `initial_params` of the ceremony. Initial ceremony parameters are available at `GET phase2.semaphore.appliedzkp.org:8081/api/data/initial_params`.

You can download the parameters after the contribution of any participant by making an HTTP request to `GET phase2.semaphore.appliedzkp.org:8081/api/data/<eth address>/0`. You can download the signature of a participant's parameter set with `GET phase2.semaphore.appliedzkp.org/api/signature/<eth address>/0`. Verify the signatures with `web3x` or your preferred Ethereum library.

You can verify that a contribution was performed properly with the `verify_contribution` binary provided by [Kobi's library](https://github.com/kobigurk/phase2-bn254/tree/master/phase2). More detailed instructions coming soon.

## Notes on participant ordering
Technically, you don't have to start running your client until it's your turn to contribute, but online participants are prioritized by the ceremony protocol in general (i.e. if it would be your turn but you're offline, the ceremony will swap in the next currently online person and push you back a slot in the contribution queue). You can exit the ceremony once you've finished your part without penalty.

If disconnect midway through your turn, the server will time you out after a timeout period.

If you are computing offline and upload a malformed or otherwise invalid contribution, the server will just ignore it. You can upload a proper contribution any time before your timeout period is up without penalty.