docs: clarify circuits parameters (privacy-scaling-explorations#1575)

mabsattar · Jun 18, 2024 · 00829f4 · 00829f4
1 parent 813da20
commit 00829f4
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 0 deletions.
diff --git a/...sioned_docs/version-v2.0_alpha/developers-references/zk-snark-circuits/setup.md b/...sioned_docs/version-v2.0_alpha/developers-references/zk-snark-circuits/setup.md
@@ -30,6 +30,22 @@ pnpm circom:build $CIRCUIT_NAME
 
 > Please note that the name should match one of the circuit names inside the `circom.json` file.
 
+### Parameters
+
+MACI's circuits are parameterized, and thus can be configured to support different number of users, messages (votes), and vote options. Please ensure you understand what each of these parameter means and correctly configure them when building circuits from scratch, and when deploying the smart contracts.
+
+- **STATE_TREE_DEPTH** = how many users the system supports
+- **MESSAGE_TREE_DEPTH** = how many messages (votes) the system supports
+- **VOTE_OPTIONS_TREE_DEPTH** = how many vote options the system supports
+- **MESSAGE_BATCH_TREE_DEPTH** = how many messages in a batch can the circuit process
+- **INT_STATE_TREE_DEPTH** = how many ballots can be processed per batch when tallying the results
+
+For instance, given a binary tree for signups, if you set `STATE_TREE_DEPTH` to 2, the system will support 4 users, as 2 \*\* 2 = 4.
+
+For messages, we use a quinary (five leaves) merkle tree, so if you set `MESSAGE_TREE_DEPTH` to 2, the system will support 32 messages, as 5 \*\* 2 = 32.
+
+Please refer to the individual circuit documentation for more details on the inner working of each circuit and where parameters fit.
+
 ### Generating zKeys
 
 Run from the root directory to save to the `cli/zkeys` folder:

diff --git a/website/versioned_docs/version-v2.0_alpha/quick-start/deployment.md b/website/versioned_docs/version-v2.0_alpha/quick-start/deployment.md
@@ -16,6 +16,14 @@ We recommend to use the hardhat tasks inside the `maci-contracts` folder, due to
 
 ## Deployment Steps
 
+:::info
+Before deploying the contracts, please ensure that you have compiled the project using the correct state tree depth argument. This defines the maximum number of users that the system supports, and by default the parameter is set to 10 (to support 2 \*\* 10 users) for testing purposes. For production use, you might need to change this parameter to a different value. For more information about the parameters please refer to the [circuits page](/docs/developers-references/zk-snark-circuits/setup#Parameters).
+
+To re-compile with a different state tree depth parameter please run:
+
+`export STATE_TREE_DEPTH=$ENTER_VALUE_HERE && pnpm build`
+:::
+
 In order, these are the steps for a full MACI deployment:
 
 1. Deploy crypto (Hasher, Poseidon)

diff --git a/website/versioned_docs/version-v2.0_alpha/quick-start/installation.md b/website/versioned_docs/version-v2.0_alpha/quick-start/installation.md
@@ -68,6 +68,14 @@ pnpm i && \
 pnpm run build
 ```
 
+:::info
+Depending on the number of signups you would like to support, you will be required to re-compile the contracts with a different STATE_TREE_DEPTH parameter. This is by default 10 and can be used for testing purposes. For more information about the parameters please refer to the [circuits page](/docs/developers-references/zk-snark-circuits/setup#Parameters).
+
+To re-compile with a different state tree depth parameter please run:
+
+`export STATE_TREE_DEPTH=$ENTER_VALUE_HERE && pnpm build`
+:::
+
 #### On Intel chips (no ARM64)
 
 Install dependencies: