From 4cdd6c1e42aeaf2b2f48b825298ca311e23a345c Mon Sep 17 00:00:00 2001 From: ctrlc03 <93448202+ctrlc03@users.noreply.github.com> Date: Thu, 11 Sep 2025 12:05:22 +0100 Subject: [PATCH] refactor: readme and contracts --- examples/CRISP/Readme.md | 62 ++++--- examples/CRISP/contracts/README.md | 30 ++-- examples/CRISP/deployment-guide.md | 261 ----------------------------- 3 files changed, 41 insertions(+), 312 deletions(-) delete mode 100644 examples/CRISP/deployment-guide.md diff --git a/examples/CRISP/Readme.md b/examples/CRISP/Readme.md index 3301731c19..8d096fd420 100644 --- a/examples/CRISP/Readme.md +++ b/examples/CRISP/Readme.md @@ -12,28 +12,29 @@ CRISP ├── wasm-crypto ├── contracts - Contracts for the CRISP protocol ├── docker-compose.yaml -└── scripts - └── tasks - Scripts for tasks to be run inside the docker container +└── scripts - Scripts for the CRISP protocol, including setup and testing ``` -## Docker Development +## Development -There is a Dockerfile for easy local development which has all the tools you need preinstalled. To start the development environment, run the following command: +To start the development environment, run the following commands: ```sh -pnpm dev:setup # build the devcontainer +pnpm dev:setup # build the project pnpm dev:up # run the services ``` +The two commands above will start everything you need to run the CRISP protocol. You can then interact with it using the web application at `http://localhost:3000`. Please ensure you follow the prerequisites installation for running the protocol locally. + ## Prerequisites for running without Docker Before getting started, make sure you have the following tools installed: - **Rust** -- **RISC Zero toolchain** +- **RISC Zero toolchain** (not needed for development only) - **Foundry** and **Anvil** (for local testnet) - **Node.js** (for client-side dependencies) -- **Yarn** (as Node package manager) +- **Pnpm** (as Node package manager) ## Dependencies @@ -77,14 +78,12 @@ cargo risczero --version At this point, you should have all the tools required to develop and deploy an application with [RISC Zero](https://www.risczero.com). -## Setting Up the Web App +## Setting Up the project -To set up the CRISP dApp in your local environment, follow these steps: - -1. Navigate to the `client` directory: +1. Navigate to the root directory: ```sh - cd examples/CRISP/client + cd examples/CRISP ``` 2. Install dependencies: @@ -93,7 +92,16 @@ To set up the CRISP dApp in your local environment, follow these steps: pnpm install ``` -3. Start the development server: +## Setting Up the Web App + +To set up the CRISP dApp in your local environment, follow these steps: + +1. Navigate to the `client` directory: + + ```sh + cd examples/CRISP/client + ``` +2. Start the development server: ```sh pnpm dev @@ -155,9 +163,11 @@ After deployment, you will see the addresses for the following contracts: Note down the first four addresses as they will be needed to configure `risc0`, `local_testnet` and the `server`. -### Step 3: Deploy the RISC Zero Contracts +### Step 3: Deploy the RISC Zero Contracts -1. Navigate to the `CRISP/packages/risc0` directory. +> Please note that this step is optional for development only. You can run the program server in dev mode which does not use Risc0. + +1. Navigate to the `CRISP/lib/risc0-ethereum` directory. --- @@ -241,27 +251,13 @@ E3_COMPUTE_PROVIDER_BATCH_SIZE=4 # Must be a power of 2 ## Running Ciphernodes -Please make sure that your scripts are run from the `enclave` root directory - this is mandatory to set the environment variables correctly. Depending on your operating system, you may need to give additional execution permissions to each script (using `sudo chmod +x script_name.sh`). The following commands assume that `enclave' and `CRISP' share the same parent folder. - -Navigate to the root of the `enclave` repository. To run 3 Ciphernodes, use the provided `run_ciphernodes.sh` script. +To run three ciphernodes, use the following command inside the CRISP directory: ```sh -./../CRISP/packages/local_testnet/run_ciphernodes.sh +./scripts/dev_ciphernodes.sh ``` -After starting the ciphernodes, a new directory `enclave_data` will be created under `CRISP/packages/local_testnet`. This is where all your ciphernodes configs, data and aggregator live. If you need to rebuild your ciphernodes, we suggest you delete this directory (e.g. `rm -rf CRISP/packages/local_testnet/enclave_data`). - -Open a new terminal. Navigate to the root of the `enclave` repository and run the aggregator using the `run_aggregator.sh` script: - -```sh -./../CRISP/packages/local_testnet/run_aggregator.sh -``` - -Once the aggregator is running, you can add the Ciphernodes to the registry. Open a new terminal. Navigate to the root of the `enclave` repository and run the following script `add_ciphernodes.sh`: - -```sh -./../CRISP/packages/local_testnet/add_ciphernodes.sh -``` +This script will start the ciphernodes, add the ciphernodes to the registry on chain. ## Running the CRISP Server @@ -285,8 +281,6 @@ Once the CLI client is running, you can interact with the CRISP voting protocol 2. To initiate a new CRISP round, choose the option `Initialize new CRISP round`. -3. To vote in a CRISP round, choose the option `Participate in an E3 round`. - Ensure all services are running correctly and that components are communicating as expected before starting a new CRISP round. ## Contributing diff --git a/examples/CRISP/contracts/README.md b/examples/CRISP/contracts/README.md index 43d7eec1c0..df0d0838ee 100644 --- a/examples/CRISP/contracts/README.md +++ b/examples/CRISP/contracts/README.md @@ -1,26 +1,22 @@ # Solidity Contracts -This directory contains the Solidity contracts for an application with [RISC Zero] on Ethereum. -The example contract included within the template is [`EvenNumber.sol`](./EvenNumber.sol). -It holds a number, guaranteed to be even. - -The Solidity libraries for RISC Zero can be found at [github.com/risc0/risc0-ethereum]. +This directory contains the Solidity contracts for CRISP - Coercion-Resistant Impartial Selection Protocol. Contracts are built and tested with [forge], which is part of the [Foundry] toolkit. Tests are defined in the `tests` directory in the root of this template. -## Generated Contracts +## CRISP Program + +This is the main logic of CRISP - an enclave program for secure voting. + +It exposes two main functions: + +* `validate` - that is called when a new E3 instance is requested on Enclave (`Enclave.request`). +* `verify` - that is called when the ciphertext output is published on Enclave (`Enclave.publishCiphertextOutput`). This function ensures that the ciphertext output is valid. CRISP uses Risc0 as the compute provider for running the FHE program, thus the proof will be a Risc0 proof. + +## Input validator -As part of the build process, this template generates the `ImageID.sol` and `Elf.sol` contracts. -Running `cargo build --locked` will generate these contracts with up to date references to your guest code. +The input validator contract is used to validate the input data that is submitted to the E3 instance. It is called by the Enclave contract when a new input is published (`Enclave.publishInput`). In CRISP, the data providers (the ones submitting the inputs) are the voters, and the input submitted is the vote itself. -- `ImageID.sol`: contains the [Image IDs][image-id] for the guests implemented in the [methods] directory. -- `Elf.sol`: contains the path of the guest binaries implemented in the [methods] directory. - This contract is saved in the `tests` directory in the root of this template. +The validator will validate the input data by checking whether the gating conditions are satisifed (this uses Semaphore by default), and that the ciphertext is constructed correctly, using [Greco](https://github.com/gnosisguild/enclave/tree/main/packages/circuits/crates/libs/greco) ([link to paper(https://eprint.iacr.org/2024/594)]). -[Foundry]: https://getfoundry.sh/ -[RISC Zero]: https://risczero.com -[forge]: https://github.com/foundry-rs/foundry#forge -[github.com/risc0/risc0-ethereum]: https://github.com/risc0/risc0-ethereum/tree/main/contracts -[image-id]: https://dev.risczero.com/terminology#image-id -[methods]: ../methods/README.md diff --git a/examples/CRISP/deployment-guide.md b/examples/CRISP/deployment-guide.md deleted file mode 100644 index 772ba57c52..0000000000 --- a/examples/CRISP/deployment-guide.md +++ /dev/null @@ -1,261 +0,0 @@ -# RISC Zero Ethereum Deployment Guide - -Welcome to the [RISC Zero] Ethereum Deployment guide! - -Once you've written your [contracts] and your [methods], and [tested] your program, you're ready to deploy your contract. - -You can either: - -- [Deploy your project to a local network] -- [Deploy to a testnet] -- [Deploy to Ethereum Mainnet] - -## Deploy your project on a local network - -You can deploy your contracts and run an end-to-end test or demo as follows: - -1. Start a local testnet with `anvil` by running: - - ```bash - anvil - ``` - - Once anvil is started, keep it running in the terminal, and switch to a new terminal. - -2. Set your environment variables: - > ***Note:*** *This requires having access to a Bonsai API Key. To request an API key [complete the form here](https://bonsai.xyz/apply).* - > Alternatively you can generate your proofs locally, assuming you have a machine with an x86 architecture and [Docker] installed. In this case do not export Bonsai related env variables. - - ```bash - # Anvil sets up a number of default wallets, and this private key is one of them. - export ETH_WALLET_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 - export ETH_WALLET_ADDRESS=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 - export BONSAI_API_KEY="YOUR_API_KEY" # see form linked in the previous section - export BONSAI_API_URL="BONSAI_API_URL" # provided with your api key - ``` - -3. Build your project: - - ```bash - cargo build --locked - ``` - -4. Deploy your contract by running: - - ```bash - FOUNDRY_PROFILE=local USE_MOCK_VERIFIER=true forge script --rpc-url http://localhost:8545 --broadcast deploy/Deploy.s.sol - ``` - - This command should output something similar to: - - ```bash - ... - == Logs == - You are deploying on ChainID 31337 - Deployed RiscZeroGroth16Verifier to 0x5FbDB2315678afecb367f032d93F642f64180aa3 - Deployed EvenNumber to 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512 - ... - ``` - - Save the `EvenNumber` contract address to an env variable: - - ```bash - export EVEN_NUMBER_ADDRESS=#COPY EVEN NUMBER ADDRESS FROM DEPLOY LOGS - ``` - - > You can also use the following command to set the contract address if you have [`jq`][jq] installed: - > - > ```bash - > export EVEN_NUMBER_ADDRESS=$(jq -re '.transactions[] | select(.contractName == "EvenNumber") | .contractAddress' ./broadcast/Deploy.s.sol/31337/run-latest.json) - > ``` - -### Interact with your local deployment - -1. Query the state: - - ```bash - cast call --rpc-url http://localhost:8545 ${EVEN_NUMBER_ADDRESS:?} 'get()(uint256)' - ``` - -2. Publish a new state - - ```bash - cargo run --bin publisher -- \ - --chain-id=31337 \ - --rpc-url=http://localhost:8545 \ - --contract=${EVEN_NUMBER_ADDRESS:?} \ - --input=12345678 - ``` - -3. Query the state again to see the change: - - ```bash - cast call --rpc-url http://localhost:8545 ${EVEN_NUMBER_ADDRESS:?} 'get()(uint256)' - ``` - -## Deploy your project on Sepolia testnet - -You can deploy your contracts on the `Sepolia` testnet and run an end-to-end test or demo as follows: - -1. Get access to Bonsai and an Ethereum node running on Sepolia testnet (in this example, we will be using [Alchemy](https://www.alchemy.com/) as our Ethereum node provider) and export the following environment variables: - > ***Note:*** *This requires having access to a Bonsai API Key. To request an API key [complete the form here](https://bonsai.xyz/apply).* - > Alternatively you can generate your proofs locally, assuming you have a machine with an x86 architecture and [Docker] installed. In this case do not export Bonsai related env variables. - - ```bash - export BONSAI_API_KEY="YOUR_API_KEY" # see form linked in the previous section - export BONSAI_API_URL="BONSAI_API_URL" # provided with your api key - export ALCHEMY_API_KEY="YOUR_ALCHEMY_API_KEY" # the API_KEY provided with an alchemy account - export ETH_WALLET_PRIVATE_KEY="YOUR_WALLET_PRIVATE_KEY" # the private hex-encoded key of your Sepolia testnet wallet - ``` - -2. Build your project: - - ```bash - cargo build --locked - ``` - -3. Deploy your contract by running: - - ```bash - FOUNDRY_PROFILE=sepolia forge script deploy/Deploy.s.sol --rpc-url https://eth-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY:?} --broadcast - ``` - - This command uses the `sepolia` profile defined in the [config][config] file, and should output something similar to: - - ```bash - ... - == Logs == - You are deploying on ChainID 11155111 - Deploying using config profile: sepolia - Using IRiscZeroVerifier contract deployed at 0x925d8331ddc0a1F0d96E68CF073DFE1d92b69187 - Deployed EvenNumber to 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512 - ... - ``` - - Save the `EvenNumber` contract address to an env variable: - - ```bash - export EVEN_NUMBER_ADDRESS=#COPY EVEN NUMBER ADDRESS FROM DEPLOY LOGS - ``` - - > You can also use the following command to set the contract address if you have [`jq`][jq] installed: - > - > ```bash - > export EVEN_NUMBER_ADDRESS=$(jq -re '.transactions[] | select(.contractName == "EvenNumber") | .contractAddress' ./broadcast/Deploy.s.sol/11155111/run-latest.json) - > ``` - -### Interact with your Sepolia testnet deployment - -1. Query the state: - - ```bash - cast call --rpc-url https://eth-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY:?} ${EVEN_NUMBER_ADDRESS:?} 'get()(uint256)' - ``` - -2. Publish a new state - - ```bash - cargo run --bin publisher -- \ - --chain-id=11155111 \ - --rpc-url=https://eth-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY:?} \ - --contract=${EVEN_NUMBER_ADDRESS:?} \ - --input=12345678 - ``` - -3. Query the state again to see the change: - - ```bash - cast call --rpc-url https://eth-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY:?} ${EVEN_NUMBER_ADDRESS:?} 'get()(uint256)' - ``` - -## Deploy your project on Ethereum mainnet - -You can deploy your contract on Ethereum Mainnet as follows: - -1. Get access to Bonsai and an Ethereum node running on Mainnet (in this example, we will be using [Alchemy](https://www.alchemy.com/) as our Ethereum node provider) and export the following environment variables: - > ***Note:*** *This requires having access to a Bonsai API Key. To request an API key [complete the form here](https://bonsai.xyz/apply).* - > Alternatively you can generate your proofs locally, assuming you have a machine with an x86 architecture and [Docker] installed. In this case do not export Bonsai related env variables. - - ```bash - export BONSAI_API_KEY="YOUR_API_KEY" # see form linked in the previous section - export BONSAI_API_URL="BONSAI_API_URL" # provided with your api key - export ALCHEMY_API_KEY="YOUR_ALCHEMY_API_KEY" # the API_KEY provided with an alchemy account - export ETH_WALLET_ADDRESS="YOUR_WALLET_ADDRESS" # the account address you want to use for deployment - ``` - -2. Build your project: - - ```bash - cargo build --locked - ``` - -3. Deploy your contract by running: - - You'll need to pass options to forge script to connect to your deployer wallet. See the [Foundry documentation][forge-script-wallet-docs]. - The example command below configures Forge to use a Ledger hardware wallet. - - ```bash - forge script deploy/Deploy.s.sol --rpc-url https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY:?} --broadcast --ledger - ``` - - This command uses the `mainnet` profile defined in the [config][config] file, and should output something similar to: - - ```bash - ... - == Logs == - You are deploying on ChainID 1 - Deploying using config profile: mainnet - Using IRiscZeroVerifier contract deployed at 0x8EaB2D97Dfce405A1692a21b3ff3A172d593D319 - Deployed EvenNumber to 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512 - ... - ``` - - Save the `EvenNumber` contract address to an env variable: - - ```bash - export EVEN_NUMBER_ADDRESS=#COPY EVEN NUMBER ADDRESS FROM DEPLOY LOGS - ``` - - > You can also use the following command to set the contract address if you have [`jq`][jq] installed: - > - > ```bash - > export EVEN_NUMBER_ADDRESS=$(jq -re '.transactions[] | select(.contractName == "EvenNumber") | .contractAddress' ./broadcast/Deploy.s.sol/1/run-latest.json) - > ``` - -### Interact with your Ethereum Mainnet deployment - -1. Query the state: - - ```bash - cast call --rpc-url https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY:?} ${EVEN_NUMBER_ADDRESS:?} 'get()(uint256)' - ``` - -2. Publish a new state - - > NOTE: Currently only a local wallet, provided by the `ETH_WALLET_PRIVATE_KEY` env var is implemented in the example publisher app. - > Please see https://github.com/risc0/risc0-foundry-template/issues/121 for more details. - - ```bash - cargo run --bin publisher -- \ - --chain-id=1 \ - --rpc-url=https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY:?} \ - --contract=${EVEN_NUMBER_ADDRESS:?} \ - --input=12345678 - ``` - -3. Query the state again to see the change: - - ```bash - cast call --rpc-url https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY:?} ${EVEN_NUMBER_ADDRESS:?} 'get()(uint256)' - ``` - -[Deploy to Ethereum Mainnet]: #deploy-your-project-on-ethereum-mainnet -[Deploy your project to a local network]: #deploy-your-project-on-a-local-network -[RISC Zero]: https://www.risczero.com/ -[Docker]: https://docs.docker.com/engine/install/ -[contracts]: ./contracts/ -[jq]: https://jqlang.github.io/jq/ -[methods]: ./methods/ -[tested]: ./README.md#run-the-tests -[config]: ./deploy/config.toml -[forge-script-wallet-docs]: https://book.getfoundry.sh/reference/forge/forge-script#wallet-options---raw