# zkparty MPC Participant Guide

**All of this code is highly experimental and has not been audited. Use at your own risk.**

Thanks for helping to participate in zkSNARK trusted setup ceremonies! This guide will walk you through how to participate.

If you are a participant, you'll first need to obtain the trusted setup client Docker image. This Docker image will allow you to participate in any trusted setup ceremony as long as the project is using our AZTEC-based coordinator server, so you only need to get the image once! (unless breaking changes are introduced to the coordinator server API).

In this guide:
- **Register for a ceremony**: How to join an upcoming or ongoing MPC ceremony.
- **Participating in a ceremony (no frills)**: The easiest way to run the client software and contribute to MPC.
- **Participating in a ceremony (manual / extra security)**: For advanced users who want to be especially careful about the integrity of their ceremony contribution. Read this if you want to control the computation / toxic waste generation process.
- **Attestations**: Send a signed attestation or message regarding your participation.
- **Verifying ceremony integrity**: Verify that all steps of an MPC ceremony have been performed properly.
- **Notes on participant ordering**: When your client needs to be online and running.

## Register for a ceremony
You'll need to know the admin address and coordinator server URL of the ceremony you'd like to join. This should be provided to you by the ceremony coordinator; in the future, we will have a listing on zkparty.io.

You can register for a ceremony by sending (at least) 1 Wei to the admin address of the ceremony. Ceremonies may specify a maximum number of participants, and inclusion in the participant set is first-come-first-serve. You can submit registration at any point, even after the ceremony has begun.

Alternatively, to bypass the first-come-first serve mechanism, ceremonies can also manually add a "whitelist" of participants. If a ceremony coordinator tells you that they have whitelisted your address, you don't need to do anything manually to register.

## Participating in a ceremony (no frills)

Once you've registered for a ceremony and know the IP address of the coordinator server, 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.

### 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 on participating with manual / extra security.

### Participating

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

docker run -ti -e API_URL=<ceremony url>/api -e PRIVATE_KEY=<0x...> bgu33/zkparty:latest

Note that to participate in the ceremony, you need two parameters passed as environment variables:
- API_URL: This is the URL that the coordinator server exposes the ceremony API from. Your client uploads to and downloads from this coordinator server. You'll need to get this URL from the ceremony coordinator.
- PRIVATE_KEY: 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 the duration of the ceremony, or at least so long as you have not completed your part of the ceremony.

### Spectating
You can enter a bogus private key to track the progress of a ceremony in your terminal in spectator mode, without contributing. In the future, you'll also be able to track the progress of ceremonies on a webapp hub that we're in the process of putting together.

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=<ceremony url>/api -e PRIVATE_KEY=<0x...> bgu33/zkparty:latest

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

### Building
The no-frills mode pulls a docker image of an MPC client from Dockerhub. However, 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. If you'd like to participant manually and anonymously, see the "Participating anonymously" subsection of this section.*

To run the client in OFFLINE mode:

cd setup-mpc-client
API_URL=<ceremony url> 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=<ceremony url> 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=<ceremony url> PARAMS_PATH=</path/to/params> PRIVATE_KEY=<0x...> ./sign_and_upload.sh

Signs and uploads the parameters you generated.

### Participating manually AND anonymously
If you'd like to make a manual contribution anonymously, you unfortunately can't just join with your own burner address via the "send 1 Wei" method; you need to be a whitelisted (Tier 0 or Tier 1) participant to contribute anonymously. Therefore we have whitelisted 50 anonymous private keys. Instructions on using these keys can be found [here](https://hackmd.io/QKzT41VJTJai_FpF8B003w).

## Attestations
We are in the process of putting together a webapp which participants will be able to submit signed messages and attestions to.

## 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 <server url>/api/data/initial_params`.

You can download the parameters after the contribution of any participant by making an HTTP request to `GET <server url>/api/data/<eth address>/0`. You can download the signature of a participant's parameter set with `GET <server url>/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.