docs: readme and contracts

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

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