forked from privacy-scaling-explorations/p0tion
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #5 from ethstorage/es-doc
Add user guide documentation for contribution and verification
- Loading branch information
Showing
9 changed files
with
231 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,149 @@ | ||
# EthStorage Trusted Setup Ceremony | ||
|
||
In essence, a trusted setup ceremony is about creating a number that nobody knows and nobody can figure out. | ||
Each of us will contribute a portion of the number and then forget what we contributed. Thus, | ||
no malicious actor can figure out what the number we created is without knowing what each person contributed — | ||
and all of us (or at least most of us, or at least one of us) forgot what we contributed. | ||
This prevents anyone from knowing or figuring out the number. | ||
|
||
This document will walk you through contributing to the EthStorage trusted setup ceremony. You can reach out to us on Discord. | ||
|
||
Contribution will be open till <to be default> | ||
|
||
## Background | ||
### What is a Trusted Setup Ceremony? | ||
To generate and verify proofs securely, a cryptographic event must be run where a group of people collaborate to create | ||
a set of cryptographic parameters needed to kick-off zkSNARKs-based systems. The goal is to ensure that no one can | ||
influence or manipulate the parameter creation process. The idea is to share the burden of the setup among many | ||
participants; thus each produces only a fragment of the information needed to generate the ceremony parameter, | ||
the so-called toxic waste. As the name could suggest, this information must be thrown away by the participants, | ||
and it only takes at least one of them to successfully forget the toxic waste to ensure the security of the ceremony | ||
because an attacker needs all fragments in order to break the system; that’s why these events are called MPC Trusted | ||
Setup Ceremonies. | ||
|
||
### How does a Trusted Setup work? | ||
Any Trusted Setup ceremony is organized in two subsequent steps: the Phase 1, is universally reusable in any point of | ||
contribution as input for any zkSNARKs Phase 2. Briefly, the goal of the Phase 1 is to securely generate zk-SNARK | ||
parameters for circuits of up to a huge amount of constraints while the Phase 2, is a circuit-specific ceremony that | ||
must be done for each individual application circuit. Luckily, both phases have a similar workflow. Both assume that | ||
there is at least one coordinator and multiple participants taking turns in (generally) sequential rounds. The | ||
coordinator generates and publishes a challenge file, which the first participant downloads, generates some entropy | ||
(the so-called toxic waste). Then, the participant runs a computation to produce a new challenge file, which is made | ||
available for coordinator verification. If the contribution has been verified as correct, the next participant will | ||
repeat the process starting from this latest contribution, otherwise is going to recompute the work taking the | ||
position of the previous participant. The process is repeated indefinitely until the coordinator decides to end | ||
the ceremony or a predetermined end date is reached. Ultimately, the ceremony results in the extraction of a key | ||
for the specific circuit being used. | ||
|
||
|
||
## Requirements | ||
|
||
1. **A computer**: | ||
|
||
A computer with 8GB or above Space and Ram is recommended. Ideally Mac or Linux, Windows via | ||
[WSL](https://learn.microsoft.com/en-us/windows/wsl/install) is Ok. | ||
|
||
2. **A strong internet connection**: | ||
|
||
The most common cause of failures is an inability to upload your contribution to the ceremony before the timeout | ||
period expires. Please run the ceremony with a strong internet connection, and your upload and download bandwidths | ||
should be at least 25 Mbps each (preferably 50+ Mbps each). Using a wired (ethernet) connection rather than a | ||
wireless (WiFi) connection is also recommended. | ||
|
||
3. **A GitHub Account**: | ||
|
||
A GitHub account must be a month old with at least one follower, five followings and two repos. | ||
|
||
4. **Node Version Manager (NVM)** | ||
|
||
Running the CLI app to contribute to the ceremony requires node version 16.20 or above. | ||
We’ll install nvm to change node versions by downloading a shell script using the following command in the terminal: | ||
```bash | ||
curl -sL https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.0/install.sh -o install_nvm.sh | ||
sh install_nvm.sh | ||
export NVM_DIR="$HOME/.nvm" | ||
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" | ||
``` | ||
|
||
5. **Install node v18** | ||
|
||
Before contribution, let’s install and switch to node v18 which the ceremony relies on. | ||
```bash | ||
nvm install 18 | ||
nvm use 18 | ||
``` | ||
|
||
## Contributing to the Ceremony | ||
|
||
1. **Create a temporary directory** | ||
```bash | ||
mkdir ~/phase2cli | ||
cd ~/phase2cli | ||
``` | ||
|
||
2. **Install phase2cli** | ||
|
||
```bash | ||
npm install -g @ethstorage-io/phase2cli | ||
``` | ||
|
||
3. **Authenticate with GitHub** | ||
|
||
If your GitHub meets the requirements, you will be eligible for this next step using the following command | ||
```bash | ||
phase2cli auth | ||
``` | ||
You will be provided [a link](https://github.com/login/device) and your authentication code as following. | ||
|
||
<img alt="auth0.png" src="auth0.png" width="100%"/> | ||
|
||
Open the link in your browser and log in your GitHub with your authentication code. | ||
|
||
<img alt="auth1.png" src="auth1.png" width=40%/> | ||
|
||
4. **Contribute** | ||
|
||
```bash | ||
phase2cli contribute | ||
``` | ||
|
||
Run the command and select the circom you want to contribute (for this ceremony, please select _EthStorage circom_); | ||
You can see the circom description after one ceremony is selected. | ||
![contribute0.png](contribute0.png) | ||
|
||
Once your contribution is complete, you’ll be invited to share a message on Twitter/X — please do so, or on whatever social media platform(s) you prefer! | ||
![contribute1.png](contribute1.png) | ||
|
||
|
||
5. **Cleanup** | ||
|
||
After successful contribution you can clear up this file and GitHub authorizations. Use these commands | ||
```bash | ||
phase2cli clean | ||
phase2cli logout | ||
``` | ||
![clean.png](clean.png) | ||
![logout.png](logout.png) | ||
|
||
## Note | ||
**Make sure your computer does not go to sleep**: When your turn in the queue comes, your computer needs to be awake | ||
and connected to the internet. If you’re going to leave your contribution running and step away from the computer, | ||
be sure you don’t have your computer set to automatically sleep. | ||
|
||
|
||
## Frequently Encountered Errors | ||
**Error: Your contribution took longer than the estimated time**: | ||
|
||
If you meet the following error: | ||
"Your contribution took longer than the estimated time and you were removed as current contributor. You should wait for | ||
a timeout to expire before you can rejoin for contribution." This means that your contribution uses twice times | ||
contributions average used. Recommend using better machines (hardware and network) to provide contribution. | ||
|
||
**If you disconnect**: While in the queue, you can re-join by running the npx phase2cli contribute command again. | ||
|
||
**Authentication errors**: phase2cli authentication can get rejected if you initially failed the GitHub account requirements. | ||
Please make sure your GitHub account meets our requirement and reset authentication. | ||
|
||
**Cannot rejoin after timeout**: If you encounter problems and your contribution window times out, you won’t be able to | ||
rejoin the queue immediately. Rejoin again in a few hours (and talk to us if it still doesn’t work). | ||
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,74 @@ | ||
# Verifying Trusted Setup Ceremony | ||
|
||
A trusted setup ceremony is a fundamental process in ensuring the integrity and security of certain cryptographic systems. | ||
By generating a unique and unpredictable “number” collectively, with contributions from multiple parties, | ||
we create a foundation of trust that prevents malicious actors from compromising the system. | ||
|
||
Verifying the security of our ceremony is paramount. However, it's important to note that it's a more technical process than contributing. | ||
We invite everyone to confirm the security of our ceremony for themselves, and so are publishing this guide to help you do so. | ||
|
||
|
||
## Overview | ||
There are multiple steps to verifying the security of a trusted setup ceremony. We provide the required list in a way | ||
that malicious projects pretend to run rituals while secretly retaining backdoors. | ||
To ensure that anyone can verify the integrity of our trusted setup ceremony, we have outlined a robust guide for | ||
verifying the results. Here’s an overview of the key steps involved: | ||
|
||
- Verifying the circuit we are securing does not include security holes; | ||
- Verifying the transcript matches the circuit; | ||
- Verifying contributors' attestations match the transcript; | ||
|
||
## Verifying the Circuit | ||
Confirming the integrity and security of the [EthStorage blob poseidon circuit](https://github.com/ethstorage/zk-decoder/blob/main/circom/circuits/blob_poseidon_2.circom) | ||
by reviewing our circom code, which is open-source and available on Github. | ||
|
||
## Verifying the Transcript Matches the Circuit | ||
Our ceremony transcript is included in the zkey published on ceremony.ethstorage.io in the "Download ZKey" tab of the | ||
[EthStorage Circom page](https://ceremony.ethstorage.io/projects/EthStorage%20circom). You can verify it matches the | ||
circuit using Circom and snarkjs: | ||
|
||
- Install [Circom](https://docs.circom.io/getting-started/installation/) and [snarkjs](https://github.com/iden3/snarkjs). | ||
- Clone circom code https://github.com/ethstorage/zk-decoder. | ||
- Download the Powers of Tau (ptau) file we used for our ceremony; we used the Hermez rollup with 2^20 powers of tau, | ||
which is linked in [the snarkjs readme](https://github.com/privacy-scaling-explorations/perpetualpowersoftau?tab=readme-ov-file#prepared-phase-2-files) | ||
or available directly [here](https://pse-trusted-setup-ppot.s3.eu-central-1.amazonaws.com/pot28_0080/ppot_0080_20.ptau). | ||
- Generate the `r1cs` file from the `circom` source files, by running `circom blob_poseidon_2.circom --r1cs` in the | ||
directory `zk-decoder/circom/circuits` (need to run `npm install` for the first time). The SHA-256 hash of this file | ||
(i.e. as computed by `sha256sum blob_poseidon_2.r1cs`) is `ba17a94a5edcc1d0b0ad10990e0aea4894f080ce571b0db79fb1c3a9c4a74a0d` | ||
- Use snarkjs to verify that the transcript matches this circuit and powers of tau, by running | ||
`snarkjs zkey verify blob_poseidon_2.r1cs ppot_0080_20.ptau blob_poseidon_2_final.zkey`. `blob_poseidon_2_final.zkey` can be downloaded | ||
[here](https://ethstorage-circom-ph2-ceremony.s3.us-west-2.amazonaws.com/circuits/blob_poseidon_2/contributions/blob_poseidon_2_final.zkey). | ||
You should see a list of contribution hashes (attestations) followed by the message snarkJS: `ZKey Ok!`. | ||
|
||
Note: If you meet issue "[ERROR] snarkJS: DOMException [QuotaExceededError]: The requested length exceeds 65,536 bytes" | ||
when you run `snarkjs zkey verify ...` command, please update your snarkjs to latest version and rerun it again. | ||
|
||
## Verifying Contributor Attestations Match the Transcript | ||
|
||
Each contributor authorized our ceremony to publish an attestation to their GitHub account. (In a Gist entitled | ||
"`ethstorage-circom_attestation.log`") These attestations match the attestations published in the transcript. | ||
This proves which GitHub user made each contribution to the ceremony. You can verify attestations by looking them | ||
up both in the transcript and on GitHub: | ||
|
||
In the transcript (generated by snarkjs in the previous step), you will see that each contribution is preceded | ||
by the phrase contribution `#[number] [username]-[number]`. That username is the GitHub username. | ||
|
||
On GitHub, you can run a search to find an attestation Gist on gist.github.com. For example, if the username is | ||
`somecontributor`, then you could search for filename:`"ethstorage-circom_attestation.log" user:somecontributor`. | ||
|
||
To verify an attestation, confirm that the hash in the attestation in the transcript matches the hash in the | ||
GitHub Gist for that same user. | ||
|
||
**Important Note**: Contributors can remove their attestations from GitHub at any time. They can also edit their | ||
attestations (although in this case the edit history will be visible). Only the original version of the attestation | ||
can be valid; an edited version cannot be a valid attestation. Note that if any malicious contributors were | ||
able to participate in the ceremony, it does not damage the security of the ceremony, but it does mean that they | ||
can pretend to have a bad attestation by editing or deleting their Gist. Therefore, a contribution with no attestation | ||
provides no security to the ceremony. | ||
|
||
Please exercise good judgment about whether a missing or edited attestation represents: | ||
|
||
- A malicious contributor | ||
- Someone just cleaning up old Gists | ||
- A problem in the ceremony | ||
|