diff --git a/.gitignore b/.gitignore index c088ded7..ba5f4354 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,13 @@ coverage/ docs/* !docs/CNAME !docs/index.html - +!docs/verification.md +!docs/contribution.md +!docs/contribute0.png +!docs/contribute1.png +!docs/auth0.png +!docs/auth1.png +!docs/clean.png +!docs/logout.png *.env diff --git a/docs/auth0.png b/docs/auth0.png new file mode 100644 index 00000000..3159e39a Binary files /dev/null and b/docs/auth0.png differ diff --git a/docs/auth1.png b/docs/auth1.png new file mode 100644 index 00000000..78c63b7e Binary files /dev/null and b/docs/auth1.png differ diff --git a/docs/clean.png b/docs/clean.png new file mode 100644 index 00000000..662e8fa1 Binary files /dev/null and b/docs/clean.png differ diff --git a/docs/contribute0.png b/docs/contribute0.png new file mode 100644 index 00000000..b367f43b Binary files /dev/null and b/docs/contribute0.png differ diff --git a/docs/contribute1.png b/docs/contribute1.png new file mode 100644 index 00000000..0f534ca1 Binary files /dev/null and b/docs/contribute1.png differ diff --git a/docs/contribution.md b/docs/contribution.md new file mode 100644 index 00000000..741d366e --- /dev/null +++ b/docs/contribution.md @@ -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 + +## 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. + +auth0.png + +Open the link in your browser and log in your GitHub with your authentication code. + +auth1.png + +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). + diff --git a/docs/logout.png b/docs/logout.png new file mode 100644 index 00000000..f2c1c59e Binary files /dev/null and b/docs/logout.png differ diff --git a/docs/verification.md b/docs/verification.md new file mode 100644 index 00000000..80dfc71e --- /dev/null +++ b/docs/verification.md @@ -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 +