CRISP
CRISP Setup

Getting Started with CRISP

This guide will walk you through the steps to set up and run CRISP locally. CRISP is a complete example of an E3 Program, built with a modern Hardhat-based architecture that includes smart contracts, frontend applications, and secure computation components.

The setup includes the following:

  • CRISP contracts: Smart contracts located in the contracts/ directory
  • Applications: Frontend, server, and computation programs in the apps/ directory
  • Ciphernodes: Distributed nodes managed through the Enclave CLI
  • Development environment: Hardhat + Foundry hybrid setup

Prerequisites

Before getting started, ensure you have installed:

Install Node

You can install Node following the official documentation (opens in a new tab) or using a Node Version Manager (e.g., nvm (opens in a new tab)).

Install Pnpm

You can install Pnpm following the official documentation (opens in a new tab).

Install Metamask

You can add Metamask as extension to your browser following the official documentation (opens in a new tab).

Install Rust and Foundry

You need to install Rust and Foundry first. After installation, restart your terminal.

# Install Rust
curl https://sh.rustup.rs -sSf | sh
 
# Install Foundry
curl -L https://foundry.paradigm.xyz | bash

Install RISC Zero Toolchain

Next, install rzup for the cargo-risczero toolchain.

# Install rzup
curl -L https://risczero.com/install | bash
 
# Install RISC Zero toolchain
rzup install cargo-risczero

Verify the installation was successful by running:

cargo risczero --version

At this point, you should have all the tools required to develop and deploy an application with RISC Zero (opens in a new tab).

Environment

You need to setup your environment variables for client/ and server/. Just copy and paste the .env.default as .env and overwrite with your values the following variables (you can leave the others initialized with the default values).

Client

VITE_E3_PROGRAM_ADDRESS=0x322813Fd9A801c5507c9de605d63CEA4f2CE6c44 # Default E3 program address from anvil
VITE_SEMAPHORE_ADDRESS=0x9A9f2CCfdE556A7E9Ff0848998Aa4a0CFD8863AE

Server

ENCLAVE_ADDRESS="0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512"
CIPHERNODE_REGISTRY_ADDRESS="0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9"
NAIVE_REGISTRY_FILTER_ADDRESS="0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9"
E3_PROGRAM_ADDRESS="0x322813Fd9A801c5507c9de605d63CEA4f2CE6c44" # CRISPProgram Contract Address

These address will be displayed after successfully running the pnpm dev:up command in a log that will look like the following:

[DEPLOY] Script ran successfully.
[DEPLOY]
[DEPLOY] == Logs ==
[DEPLOY]   Deploying on ChainID 31337
[DEPLOY]   Using config profile: custom
[DEPLOY]   Using MockRISC0Verifier
[DEPLOY]   Deployed MockRISC0Verifier to 0x0B306BF915C4d645ff596e518fAf3F9669b97016
[DEPLOY]   Enclave Address:  0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
[DEPLOY]   Verifier Address:  0x0B306BF915C4d645ff596e518fAf3F9669b97016
[DEPLOY]   Deployed SemaphoreNoirVerifier to 0x959922bE3CAee4b8Cd9a407cc3ac1C251C2007B1
[DEPLOY]   Deployed Semaphore to 0x9A9f2CCfdE556A7E9Ff0848998Aa4a0CFD8863AE
[DEPLOY]   Deployed CRISPCheckerFactory to 0x68B1D87F95878fE05B998F19b66F4baba5De1aed
[DEPLOY]   Deployed CRISPPolicyFactory to 0x3Aa5ebB10DC797CAC828524e59A333d0A371443c
[DEPLOY]   Using CRISPInputValidator
[DEPLOY]   Deployed InputValidator to:  0xc6e7DF5E7b4f2A278906862b61205850344D4e7d
[DEPLOY]   Deployed CRISPInputValidatorFactory to 0x59b670e9fA9D0A427751Af201D676719a970857b
[DEPLOY]   Deployed HonkVerifier to 0x4ed7c70F96B99c776995fB64377f0d4aB3B0e1C1
[DEPLOY]   Deployed CRISPProgram to 0x322813Fd9A801c5507c9de605d63CEA4f2CE6c44
[DEPLOY]   Enabled E3 Program on Enclave

If you find any inconsistency with the addresses on the environment, you must update them and run the script again (they must match).

Quick Start

The fastest way to get CRISP running is using the scripts provided in the scripts/ directory:

# Install dependencies
pnpm install
 
# Setup and build the development environment
pnpm dev:setup
 
# Start all services (Anvil, Ciphernodes, Applications)
pnpm dev:up
 
# Clean up all artifacts and generated output (e.g., builds)
# This must be run from enclave root (do cd ../../ if you are inside examples/CRISP)
pnpm clean

This will start all CRISP components:

  • Anvil (local blockchain)
  • Deploy all contracts
  • Compile all ZK circuits
  • Ciphernodes network
  • CRISP applications (server, client)
# Build the development containers
pnpm dev:setup
 
# Start all services
pnpm dev:up
 
# Rebuild containers
pnpm dev:build
 
# Invoke the Server CLI
pnpm cli

Once everything is running, you can:

  1. Navigate http://localhost:3000 for the client interface
  2. Add the Anvil private key to your wallet: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
  3. Press Connect Wallet button and complete the association with your MetaMask account
  4. Switch to Anvil local network (this will be handled automatically by the app. You just need to press on the connected account on the frontend and select the network. Then, complete the configuration on MetaMask pop-up).
  5. Open a new terminal, run pnpm cli and start a new E3 Round.
  6. Refresh and interact with the round following the Client interface.

Manual Start

If you prefer to set up CRISP manually or want to understand each component:

Setting Up the project

  1. Navigate to the root directory:

    cd examples/CRISP

  2. Install dependencies:

    pnpm install

Setting Up the Web App

To set up the CRISP dApp in your local environment, follow these steps:

  1. Navigate to the client directory:

    cd examples/CRISP/client

  2. Start the development server:

    pnpm dev

Setting Up the CRISP Server

Setting up the CRISP server involves several components, but this guide will walk you through each step.

Step 1: Start a Local Testnet with Anvil

anvil

Keep Anvil running in the terminal, and open a new terminal for the next steps.

Step 2: Setting Up the Ciphernodes

  1. Clone the Enclave Repo (opens in a new tab):

    git clone https://github.com/gnosisguild/enclave.git

  2. Navigate to the enclave-contracts directory:

    cd enclave/packages/enclave-contracts

  3. Install dependencies:

    pnpm install

  4. Delete any previous local deployment (if any):

    rm -rf deployments/localhost/

  5. Deploy the contracts on the local testnet:

    pnpm deploy:mocks --network localhost

After deployment, you will see the addresses for the following contracts:

  • Enclave
  • Ciphernode Registry
  • Naive Registry Filter
  • Mock Input Validator
  • Mock E3 Program
  • Mock Decryption Verifier
  • Mock Compute Provider

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

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.

Faster Proving w/ Bonsai

The following steps are optional. You can config Bonsai (opens in a new tab) for faster proving.

  • Set up environment variables by creating a .cargo directory and config.toml file:

    mkdir .cargo && cd .cargo && touch config.toml

  • Add the following configuration to config.toml:

    Note: This requires having access to a Bonsai API Key. To request an API key complete the form here (opens in a new tab).

    [env]
BONSAI_API_KEY="your_api_key"
BONSAI_API_URL="your_api_url"

  1. In the risc0/script directory, update the config.toml with the deployed contract addresses. The following configuration is based on default deployment addresses using local Anvil node:

    [profile.custom]
chainId = 31337
riscZeroVerifierAddress = "0x0000000000000000000000000000000000000000"
enclaveAddress = "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512"
inputValidatorAddress = "0xa513E6E4b8f2a923D98304ec87F64353C4D5C853"

  2. Export the ETH_WALLET_PRIVATE_KEY environment variable (Anvil's default private key):

    export ETH_WALLET_PRIVATE_KEY="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"

  3. Deploy the contracts:

    forge script --rpc-url http://localhost:8545 --broadcast script/Deploy.s.sol

Note down the CRISPProgram contract Address, which will be used as the E3 Program Address.

Step 4: Set up Environment Variables

Create a .env file in the server directory with the following:

# Private key for the enclave server
PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
ENCLAVE_SERVER_URL=http://0.0.0.0:4000
HTTP_RPC_URL=http://127.0.0.1:8545
PROGRAM_SERVER_URL=http://127.0.0.1:13151
WS_RPC_URL=ws://127.0.0.1:8545
CHAIN_ID=31337
 
# Cron-job API key to trigger new rounds
CRON_API_KEY=1234567890
 
# Based on Default Anvil Deployments (Only for testing)
ENCLAVE_ADDRESS="0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512"
CIPHERNODE_REGISTRY_ADDRESS="0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9"
NAIVE_REGISTRY_FILTER_ADDRESS="0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9"
E3_PROGRAM_ADDRESS="0x322813Fd9A801c5507c9de605d63CEA4f2CE6c44" # CRISPProgram Contract Address
 
# E3 Config
E3_WINDOW_SIZE=40
E3_THRESHOLD_MIN=1
E3_THRESHOLD_MAX=2
E3_DURATION=160
 
# E3 Compute Provider Config
E3_COMPUTE_PROVIDER_NAME="RISC0"
E3_COMPUTE_PROVIDER_PARALLEL=false
E3_COMPUTE_PROVIDER_BATCH_SIZE=4 # Must be a power of 2

Running Ciphernodes

To run three ciphernodes, use the following command inside the CRISP directory:

./scripts/dev_cipher.sh

This script will start the ciphernodes, add the ciphernodes to the registry on chain.

Running the CRISP Server

To run the CRISP Server, open a new terminal and navigate to the server directory. Then, execute the following command:

cargo run --bin server

Interacting with CRISP via CLI

Open a new terminal and navigate to the server directory. Then, execute the following command:

cargo run --bin cli

Once the CLI client is running, you can interact with the CRISP voting protocol by following these steps:

  1. Select CRISP: Voting Protocol (ETH) from the menu.

  2. To initiate a new CRISP round, choose the option Initialize new CRISP round.

Ensure all services are running correctly and that components are communicating as expected before starting a new CRISP round.

Next Steps

Once you have completed the setup, you can proceed to Running an E3 Program to learn how to interact with CRISP and run voting rounds.

IntroductionRunning an E3 Program