Set up CRISP

This page shows how to build CRISP and run it on a local chain. It is for developers who want to run the reference application or change it. At the end, the full CRISP stack runs on your computer and the client is at http://localhost:3000.

CRISP lives in its own repository, theinterfold/CRISP (opens in a new tab). It builds against one released version of the Interfold, which interfold-release.json names. You do not need a clone of the Interfold repository. Run all pnpm commands on this page from the root of the CRISP repository.

Prerequisites

Install nargo with noirup -v v1.0.0-beta.26. Other nargo versions can fail to compile the circuits. OpenVM is not necessary for local development, because the local scripts start the program server in dev mode unless CRISP_REAL_PROOFS=1.

Build and start CRISP

git clone https://github.com/theinterfold/CRISP.git
cd CRISP

cp crisp.dev.env.example crisp.dev.env

pnpm dev:setup

which interfold

pnpm dev:up

What the deployment does

scripts/crisp_deploy.sh sets PRIVATE_KEY to the first Anvil account, USE_MOCKS=true, and DEPLOY_INTERFOLD=true. Then it runs pnpm deploy:contracts --network localhost. The deployment includes these contracts:

• The Interfold contracts, with mock BFV verifiers for the DKG. With CRISP_SKIP_PROOF_AGGREGATION=false, the script sets ENABLE_ZK_VERIFICATION=true, and the deployment uses the real BFV verifiers. For these verifiers, the script extracts the circuit archive of the pinned Interfold release and sets INTERFOLD_CIRCUITS_DIR (see below).
• CRISPProgram, the two generated Noir ballot verifiers, and SelfRegistry.
• MockOpenVmReceiptVerifier (with CRISP_UNPROVED_TEST=1, which the local scripts set unless CRISP_REAL_PROOFS=1), MockVotingToken, and MockCrispDataAvailabilityVerifier. With CRISP_REAL_PROOFS=1, the deployment instead deploys the OpenVM receipt verifier for the guest that interfold program compile built. On Sepolia, CRISP_UNPROVED_TEST=1 deploys the mock verifier only with ALLOW_SEPOLIA_UNPROVED_COMPUTE=true. On any chain other than the local chain (chain ID 31337) and Sepolia, the deployment refuses CRISP_UNPROVED_TEST=1.

After the deployment, the script writes the new contract addresses into three files. You do not copy addresses by hand:

• interfold.config.yaml: the contracts of the localhost chain.
• server/.env: INTERFOLD_ADDRESS, E3_PROGRAM_ADDRESS, CIPHERNODE_REGISTRY_ADDRESS, FEE_TOKEN_ADDRESS, CRISP_VOTING_TOKEN, and the mock contract references.
• client/.env: VITE_CRISP_TOKEN.

The deployment records are in packages/crisp-contracts/deployed_contracts.json. For the addresses of the public networks, see Contract addresses.

CRISP deploys the Interfold contracts with the scripts of the published @interfold/contracts package, not with a clone of the Interfold repository. Outside the Interfold monorepo, the real BFV verifiers (ENABLE_ZK_VERIFICATION=true) read the verification key hashes of the BFV aggregation circuits from the directory that INTERFOLD_CIRCUITS_DIR names. This directory must hold the circuits of the same release as the package, in the release layout (<preset>/<committee>/default/...). scripts/crisp_deploy.sh sets the variable to circuits/interfold/release, which node scripts/interfold-release.mjs circuits writes from the release archive. When you run pnpm deploy:contracts yourself with ENABLE_ZK_VERIFICATION=true, set INTERFOLD_CIRCUITS_DIR to that directory. The deployment stops with an error when the variable is not set.

Configuration

Interfold release

interfold-release.json names the Interfold version and the SHA-256 digest of each release asset that CRISP downloads: the interfold CLI and the circuit archive. scripts/interfold-release.mjs refuses an asset when its digest does not match. The other dependencies name the same release in their own files:

• Cargo.toml and guest/Cargo.toml: the Rust crates (e3-*), as Cargo git dependencies on the release tag.
• circuits/lib/Nargo.toml and circuits/bin/*/Nargo.toml: the Noir library interfold_lib, as a Nargo git dependency on the release tag.
• package.json and packages/crisp-contracts/package.json: the npm packages @interfold/config and @interfold/contracts.

To move to another release, follow the steps in the Interfold dependency section (opens in a new tab) of the CRISP Readme.

Local profile

scripts/lib/dev_config.sh reads crisp.dev.env:

After you change crisp.dev.env, run pnpm dev:setup again, then pnpm dev:up. The ciphernodes refuse the skip setting unless the interfold binary has the test-only-skip-proof-aggregation Cargo feature. pnpm dev:setup selects that feature from the profile. With CRISP_SKIP_PROOF_AGGREGATION=false, DKG takes minutes for each committee, because the ciphernodes make recursive proofs.

interfold.config.yaml

This file configures the local ciphernodes and the program server. The excerpt shows the local chain and the first two nodes. The deployment updates the contract addresses.

chains:
  - name: localhost
    enabled: true
    rpc_url: ws://localhost:8545
    ingestion_confirmations: 0
    rpc_poll_interval_ms: 250
    data_availability:
      mode: mock_http
      rpc_url: http://127.0.0.1:4000/availability
    contracts:
      # e3_program, interfold, ciphernode_registry, bonding_registry,
      # slashing_manager, and fee_token: updated by the deployment
program:
  dev: false
nodes:
  cn1:
    quic_port: 9201
    ctrl_port: 50501
    autonetkey: true
    autopassword: true
    dashboard_port: 8080
  cn2:
    quic_port: 9202
    ctrl_port: 50502
    autonetkey: true
    autopassword: true
    peers:
      - /ip4/127.0.0.1/udp/9201/quic-v1

• The file also has mainnet and sepolia chains with enabled: false. The data-availability mode of mainnet is avail. On sepolia it is mock_http, because Avail Turing is down.
• Nodes cn3 to cn5 use QUIC ports 9203 to 9205 and control ports 50503 to 50505. Each node peers with cn1.
• scripts/lib/dev_config.sh sets E3_PROGRAM__DEV=true unless CRISP_REAL_PROOFS=1, so pnpm dev:up runs the development runner by default although the file sets program.dev: false.

For all node configuration keys, see Configuration.

Server settings

The CRISP server and the CLI read server/.env. Each value can also come from the process environment (server/src/config.rs).

The relay limits in the table apply to one server instance. All server instances use the same server key, but each instance counts only its own relays. Thus, when more than one instance relays, a slot or a round can receive the limit from each instance. To keep one limit for the server key, let one instance relay and set RELAY_MAX_INPUTS_PER_SLOT to 0 on all other instances. Move the relay to another instance only when no round is open. A ballot that a non-relaying instance receives uses the voter's wallet. Also, only the instance that receives a ballot holds its job. Thus, send all client requests to the relaying instance, for example with VITE_INTERFOLD_API. When a limit is reached, the voter's wallet sends the input.

The server records its relays in database/server in its working directory, and its limits count only these records. The server also records the time when this relay record starts. It writes that time when it starts on a database without that time, for example a new database. A round that is already open at that time uses the voter's wallet for all of its inputs, because the server cannot count the relays that occurred before. Keep this directory when you replace or move the server.

Client settings

Vite reads client/.env when the client starts or builds.

Real proofs with OpenVM

By default, the local scripts run the development runner, which makes no proof. To prove rounds with OpenVM on your machine, build the workers and set the program section of interfold.config.yaml (see Compute Provider):

program:
  dev: false
  openvm:
    prover_bin: /opt/openvm/interfold-openvm-prover
    prover_bin_cuda: /opt/openvm/interfold-openvm-prover-cuda # optional
    backend: auto # a working GPU when there is one, the CPU otherwise

Then set CRISP_REAL_PROOFS=1 in crisp.dev.env and run pnpm dev:setup again. With it, interfold program compile builds guest/ and its keys, the deployment deploys the receipt verifier for that guest, and interfold program start serves real proofs. A changed program or policy has a new receipt identity, so compile and deploy again after you change either.

Run single components

pnpm dev:up runs all services together. To run them one at a time, open a terminal for each command and run the commands in this order from the root of the CRISP repository:

# 1. Local chain
anvil --host 0.0.0.0 --chain-id 31337 --block-time 1 --mnemonic 'test test test test test test test test test test test junk'
 
# 2. Fulfill randomness requests of the mock provider in a later block
node ./scripts/anvil-randomness.mjs
 
# 3. Deploy the contracts and sync the addresses
./scripts/crisp_deploy.sh
 
# 4. Start and register the ciphernodes. The argument is the ready file.
./scripts/dev_cipher.sh ./.interfold/ready
 
# 5. Program server (port 13151)
./scripts/dev_program.sh
 
# 6. CRISP server (port 4000)
./scripts/dev_server.sh
 
# 7. Client (port 3000)
./scripts/dev_client.sh

Without step 2, the committee is not selected, because the mock randomness provider does not fulfill its own requests.

Scripts

These scripts are defined in package.json of the CRISP repository.

Run the tests

End-to-end test

pnpm test:e2e runs scripts/test_e2e.sh. The script starts scripts/dev.sh, waits for port 3000 and the .interfold/ready file, and then runs Synpress and Playwright. The test does these steps:

1. Requests a round with target/debug/cli init.
2. Connects MetaMask to the client and waits for the committee key.
3. Casts a vote and waits until CRISPProgram records it.
4. Moves the Anvil time past the input deadline.
5. Waits until the E3 stage is Complete, then checks the result on the All Polls page.

Set CRISP_E2E_DURATION_SECS to change the input window of the test (default 300 seconds). Add --ui (pnpm test:e2e --ui) to run the Synpress wallet setup without --headless. On Linux, the script runs Playwright with xvfb-run. Run pnpm report to open the Playwright report.

Compact the server database

The CRISP server keeps its database in database/server below its working directory. In the crisp-server image, the working directory is /, so the database is /database/server. sled keeps old copies of changed pages on disk until it cleans its log. To recover that space, copy the database while the server is stopped. The copy leaves out the old copies. It can still be up to about three times the size of the current data, because sled writes pages again while it builds the copy.

1. Stop the CRISP server.

2. In the server's working directory, run the server binary with compact-database. A source build puts the binary in target/release or target/debug below the root of the CRISP repository:

   server compact-database database/server database/server-compact

   With the image, give the same arguments to the image and mount the volume that holds /database:

   docker run --rm -v <volume>:/database <crisp-server image> compact-database /database/server /database/server-compact

3. Move database/server to a backup location.

4. Rename database/server-compact to database/server.

5. Start the CRISP server.

6. When the server works correctly, run sync on the host.

7. Delete the backup.

The command builds the copy in the target path with .partial added, for example database/server-compact.partial. It gives the copy the target name only when the copy is complete, matches the database, and is on the disk. The command stops without a copy when the target directory or the .partial directory exists, when the directory that holds the target does not exist, or when the source directory holds no database. It also stops when the server holds the database, when the copy does not match the database, or when the disk is full. After a failed command, delete the .partial directory before you run the command again.

The operating system can keep the moves of steps 3 and 4 in memory for some time before it writes them to the disk. The server reads from that memory, so a working server does not show that the disk holds the copy. sync makes the operating system write that data to the disk.

Upgrade from a release that keeps ballots in the round record

At its first start, the server moves the ballots out of the round records. An older release cannot read the moved ballots. Before you upgrade:

1. Stop the server and copy database/server.
2. If the disk has little free space, compact the database. The first start writes each moved ballot again before it removes the old copy. The command also works on the database of an older release.

To go back to the older release, restore the copy, but only before the new release accepts a ballot. The copy does not hold the availability jobs of later ballots, so their inputs would stay committed but unpublished. After the new release accepts ballots, fix forward. In avail mode, you can also go back when none of the availability jobs of the new release is pending: the older release reads the published ballots again from Avail. In mock mode, the server can read a ballot only from its database. The restored copy does not hold the ballots that the new release accepted, so those ballots are lost.

Common setup errors

Next steps