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 architecture that includes smart contracts, zero-knowledge circuits, frontend applications, and secure computation components.

Prerequisites

Before getting started, ensure you have installed:

Quick Start

The simplest way to run CRISP is:

# Install dependencies and build everything
pnpm dev:setup
 
# Start all services (Hardhat, contracts, ciphernodes, program server, coordination server, and UI)
pnpm dev:up

dev:up runs scripts/dev.sh, which:

  1. Starts the Hardhat node in packages/crisp-contracts
  2. Deploys all contracts (Enclave, CRISPProgram, verifiers, registries) via scripts/crisp_deploy.sh
  3. Starts ciphernodes using enclave.config.yaml via scripts/dev_cipher.sh
  4. Launches the program server via scripts/dev_program.sh
  5. Starts the coordination server (Rust) via scripts/dev_server.sh on port 4000
  6. Starts the React client via scripts/dev_client.sh on port 3000

All services run concurrently and will automatically restart if needed.

Additional Commands

# Recompile Noir circuits and generate verifiers
pnpm compile:circuits
 
# Open the interactive CLI to start voting rounds
pnpm cli
 
# Run end-to-end tests
pnpm test:e2e

Deployed Contract Addresses

The contract addresses are automatically configured in enclave.config.yaml and the server .env file. After running pnpm dev:up, the deployment logs will show the deployed contract addresses, which are also saved in packages/crisp-contracts/deployed_contracts.json.

Using the Application

Once everything is running, you can:

  1. Navigate http://localhost:3000 for the client interface
  2. Add the Hardhat private key to your wallet: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
  3. Press Connect Wallet button and complete the association with your MetaMask account
  4. Switch to Hardhat 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.

Configuration

Ciphernode Configuration

The enclave.config.yaml file in the CRISP root directory configures the ciphernode network. By default, it runs in development mode with fake proofs for fast local development:

program:
  dev: true # Uses fake zkVM proofs (fast for development)

Boundless Configuration

For production-grade zero-knowledge proofs with Boundless (opens in a new tab), update enclave.config.yaml:

program:
  dev: false # Disable dev mode to use real proofs
  risc0:
    risc0_dev_mode: 0 # 0 = production (Boundless), 1 = dev mode
    boundless:
      rpc_url: 'https://sepolia.infura.io/v3/YOUR_KEY' # RPC endpoint
      private_key: 'YOUR_PRIVATE_KEY' # Wallet with funds for proving
      pinata_jwt: 'YOUR_PINATA_JWT' # Required for uploading programs to IPFS
      program_url: 'https://gateway.pinata.cloud/ipfs/YOUR_CID' # Pre-uploaded program URL
      onchain: true # true = onchain requests, false = offchain

Note: For production proving with Boundless, you need:

  • An RPC endpoint (e.g., Infura, Alchemy) with funds
  • A private key with sufficient ETH/tokens for proof generation
  • A Pinata JWT for uploading programs to IPFS (get one at pinata.cloud (opens in a new tab))
  • Pre-uploaded program URL to avoid uploading the ~40MB program at runtime

Uploading Your Program to IPFS

When you make changes to the guest program in program/, you need to upload it to IPFS to get a program URL:

  1. First, configure your Pinata JWT in enclave.config.yaml (as shown above)

  2. Build and upload your program:

    # This compiles the guest program and uploads it to IPFS via Pinata
enclave program upload

  3. The command will output an IPFS hash like QmXxx.... Update your enclave.config.yaml with the full URL:

    program_url: 'https://gateway.pinata.cloud/ipfs/QmXxx...'

Important: Every time you modify the guest program code in program/, you must rebuild and re-upload it to IPFS, then update the program_url in your configuration. This ensures Boundless uses your latest program version.

Environment Variables

The pnpm dev:setup command automatically creates .env files for the server and client from the .env.example templates. The server's .env file is automatically populated with contract addresses after deployment.

Running Individual Components

While pnpm dev:up runs everything together, you can also run components separately:

# Start only the Hardhat node
cd packages/crisp-contracts && pnpm hardhat node
 
# Start only the ciphernodes (requires Hardhat running)
./scripts/dev_cipher.sh
 
# Start only the program server (requires ciphernodes)
./scripts/dev_program.sh
 
# Start only the coordination server (requires program server)
./scripts/dev_server.sh
 
# Start only the client (requires coordination server)
./scripts/dev_client.sh
 
# Run the CLI (requires all services)
pnpm cli

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