Run a voting round

This page shows how to run one CRISP voting round on a local chain, from the request to the result. It is for developers who have the CRISP stack running. At the end, you have a completed E3 and a decoded tally, and you know what CRISP does at each E3 stage.

Before you start, complete Set up CRISP. pnpm dev:up must run in a terminal, and the client must be available at http://localhost:3000. Run the pnpm cli commands from the root of the CRISP repository in a second terminal.

Run the round

pnpm cli init

pnpm cli

pnpm cli check-e3-ready --e3id <id>

What happens at each stage

The Interfold contract records the stage of each E3 (E3Stage in IInterfold.sol). The CRISP server keeps its own round status and follows the chain events.

If a round receives no votes, the server does not request a computation. It logs E3 has no votes to decrypt. Setting status to Finished. and sets the status to Finished.

The server stores a round only when the program at the configured E3_PROGRAM_ADDRESS requested it. On PlaintextOutputPublished, it decodes the tally only for a stored round of that program, because each CRISPProgram deployment fixes its own ballot layout. The event changes nothing for a round that the server did not store. Any other stored round gets an empty tally and the status Finished. This applies also to a round that an earlier server release stored.

Server log messages

The CRISP server writes these messages to the pnpm dev:up terminal (server/src/server/indexer.rs and server/src/server/routes/state.rs). <id> is the E3 ID.

The ciphernode cn1 also serves the node dashboard at http://127.0.0.1:8080. See Node dashboard.

Round timing

The input window is [start, end] in the E3 request. start is the time when voting can start. end is start + E3_DURATION. The committee key alone does not open voting: publishInput reverts with E3NotAcceptingInputs before start.

Local chain

The local deployment uses the mock data-availability verifier, and availabilityFinalizationWindow is 0. The CLI sets start to the latest block time plus VOTING_START_BUFFER_SECONDS. CRISPProgram.validate does no timing checks in this mode.

The Sepolia program uses the mock verifier too, with availabilityFinalizationWindow set to 0, while Avail Turing is down. The server needs DATA_AVAILABILITY_MODE=mock and ALLOW_SEPOLIA_MOCK_DATA_AVAILABILITY=true.

Avail networks

On Ethereum mainnet, each round has three limits:

CRISPProgram.earliestVotingStart() returns the current block time plus randomnessRequestTimeout, sortitionSubmissionWindow, and dkgWindow. The CLI and the server read it for each request. In the mainnet protocol configuration, these values are 3,600 seconds, 600 seconds, and 21,600 seconds, so start is at least 25,800 seconds after the request (mainnet-protocol.config.json (opens in a new tab)). The protocol owner can change these values. For this reason, an application must read earliestVotingStart() and not keep a fixed minimum.

CRISP deployments on Avail set availabilityFinalizationWindow to 10,800 seconds (3 hours). CRISPProgram.validate rejects a request with these errors:

For this reason, E3_DURATION must be at least 14,400 seconds: 1 hour of voting and 3 hours of finalization. The server checks this sum at startup in Avail mode. A late Avail receipt is still accepted until the compute deadline of the E3. The computation waits until every committed input has its receipt.

Decode the tally

The plaintext output is a list of polynomial coefficients. The first 50 coefficients (MAX_MSG_NON_ZERO_COEFFS) carry the result. A ballot has one coefficient for each option, so the decrypted tally holds one total for each option. Coefficient o is the total weight on option o. The other coefficients are zero.

The committee decrypts each coefficient modulo the plaintext modulus t of the parameter set: 17,000,000 for insecure-64 and for secure-8192. A total is correct only while it is less than t. CRISPProgram.validate reads t from the BFV parameters of the request and sets these limits, so that each total stays less than t:

Every input counts toward the limit, including a new vote that replaces an earlier vote, and a mask. When a round has its maximum number of inputs, publishInput reverts with InputLimitReached. A mask does not need a signature from the voter, so any account can fill the limit with masks. A CONSTANT round with large credits has the smallest limit. The CLI requests CONSTANT credits of 1, so a round accepts 100,000 inputs on insecure-64 and on secure-8192.

In a census tree round, the CRISP server writes the voting power of each voter into the census leaf. For a CUSTOM round, the server reads this voting power at CRISPProgram.snapshotOf(e3Id), the timepoint that also sets the divisor. The server retries a failed read. If the read continues to fail, the server does not post the census. It tries again later, so that the census does not exclude an eligible voter. The limits hold only when the census leaf holds that voting power.

In a CUSTOM round, the weight of a voter is an integer, and the division discards the remainder. In a census tree round, a voter with less voting power than the divisor has a weight of 0. This voter can cast only an empty ballot. For example, a total supply of 1,000,000,000,000 and the secure-8192 t of 17,000,000 give a minimum divisor of 58,824. A holder with 58,823 votes then has a weight of 0.

In an ONCHAIN round, minVotingPower must be at least the divisor, or validate reverts with MinVotingPowerBelowScale. Thus each voter that can publish an input has a weight of at least 1. The default divisor increases with the total supply. A request with a fixed minVotingPower can thus revert after the supply increases.

The CUSTOM limit also relies on the token. At the snapshot, the sum of the voting power of all accounts must not be more than getPastTotalSupply(snapshot). An ERC20Votes token satisfies this condition.

Three decoders give the same result (packages/crisp-contracts/tests/tally.decoding.test.ts):

Use the SDK to decode the plaintext output yourself. plaintextOutput is the hex string of the plaintextOutput bytes of the E3, for example from the PlaintextOutputPublished event:

import { decodeTally } from '@crisp-e3/sdk'
 
// One total per option. numChoices must be an integer from 2 to MAX_VOTE_OPTIONS (10).
const [option0, option1] = decodeTally(plaintextOutput, 2)

To read the tally that the CRISP server decoded, use getRoundResult. After the round status is Finished, tally has one decimal string for each option:

import { CrispSDK } from '@crisp-e3/sdk'
 
const sdk = new CrispSDK('http://127.0.0.1:4000')
const result = await sdk.getRoundResult(1n)
console.log(result.tally)

decodeTally throws an error when numChoices is outside 2 to 10 or is not an integer. It also throws an error when the output has fewer than 50 coefficients.

Other ways to request a round

You can also request a round in these ways:

• The CRISP server has a POST /rounds/request endpoint. It requires CRON_API_KEY. When the key is empty, the endpoint is disabled.
• The cron binary calls that endpoint, then waits 24 hours, in a loop. It reads CRON_API_KEY and INTERFOLD_SERVER_URL from the process environment. A remote INTERFOLD_SERVER_URL must use HTTPS.
• CrispSDK.requestNewRound sends the same request from TypeScript.

Do not put CRON_API_KEY in a browser bundle. Use it only from protected automation.

Troubleshooting

Next steps