docs(website): update troubleshooting

website/src/scripts/setupTypedoc.ts

@@ -25,9 +25,12 @@ function updateMdFiles(file: string, sidebarInfo: string) {
   fs.writeFileSync(file, `${sidebarInfo}\n${writtenContent}`);
 }
 
-// read all dir in typedoc/ -> rename README.md as index.md -> remove upper navigations
-const directories = fs.readdirSync(TYPEDOC_DIR);
-directories.forEach((dir) => {
+/**
+ * A function that parses a sub-directory of typedoc/,
+ * defines label for it and updates the markdown files.
+ * @param dir - the sub-directory being processed
+ */
+function parseAndRenameDirectory(dir: string) {
   const dirname = path.resolve(TYPEDOC_DIR, dir);
   const label = fitFormat(dir);
 
@@ -63,25 +66,37 @@ directories.forEach((dir) => {
       }
     });
   }
-});
-
-// insert index page
-insertIndexPage(TYPEDOC_DIR, { title: "Typedoc", label: "Typedoc" });
-
-// find the target moving directory
-const versionFile = path.resolve(__dirname, "../../versions.json");
-let versionDir = "";
-try {
-  const versionContent = fs.readFileSync(versionFile, "utf8");
-  if (versionContent) {
-    const versionContentJson = JSON.parse(versionContent) as string[];
-    versionDir = path.resolve(__dirname, `../../versioned_docs/version-${versionContentJson[0]}/typedoc`);
+}
+
+/**
+ * A function that parses a sub-directory of typedoc/,
+ * defines label for it and updates the markdown files.
+ * @return target directory path for typedocs
+ */
+function defineTargetDirectory() {
+  const versionFile = path.resolve(__dirname, "../../versions.json");
+
+  if (fs.existsSync(versionFile)) {
+    const versionContent = fs.readFileSync(versionFile, "utf8");
+    if (versionContent) {
+      const versionContentJson = JSON.parse(versionContent) as string[];
+      return path.resolve(__dirname, `../../versioned_docs/version-${versionContentJson[0]}/typedoc`);
+    }
   }
-} catch (e) {
-  versionDir = path.resolve(__dirname, "../../docs/typedoc");
+
+  return path.resolve(__dirname, "../../docs/typedoc");
 }
 
-// move the typedoc/ directory to target directory
-copyDirectory(TYPEDOC_DIR, versionDir);
+if (fs.existsSync(TYPEDOC_DIR)) {
+  const directories = fs.readdirSync(TYPEDOC_DIR, "utf8");
+  directories.forEach((dir) => {
+    parseAndRenameDirectory(dir);
+  });
+
+  insertIndexPage(TYPEDOC_DIR, { title: "Typedoc", label: "Typedoc" });
 
-fs.rmSync(TYPEDOC_DIR, { recursive: true, force: true });
+  const versionDir = defineTargetDirectory();
+  copyDirectory(TYPEDOC_DIR, versionDir);
+
+  fs.rmSync(TYPEDOC_DIR, { recursive: true, force: true });
+}

website/versioned_docs/version-v1.3_alpha/troubleshooting.md

@@ -49,3 +49,113 @@ You can generate the missing `.dat` files using the following command:
 ```bash
 pnpm build:circuits-c
 ```
+
+## contracts: `prove` command failure
+
+### Case `Commitment mismatch`
+
+If your log looks like the following, that's because you have already run the `prove` command. You can access the `cli` and attempt again by executing the `genProofs` command.
+
+```
+Error: commitment mismatch
+    at Prover.validateCommitment (/home/user/Documents/maci/contracts/tasks/helpers/Prover.ts:458:13)
+    at Prover.proveTally (/home/user/Documents/maci/contracts/tasks/helpers/Prover.ts:390:12)
+    at processTicksAndRejections (node:internal/process/task_queues:95:5)
+    at async SimpleTaskDefinition.action (/home/user/Documents/maci/contracts/tasks/runner/prove.ts:235:7)
+    at async Environment._runTaskDefinition (/home/user/Documents/maci/node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/hardhat/src/internal/core/runtime-environment.ts:359:14)
+    at async Environment.run (/home/user/Documents/maci/node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/hardhat/src/internal/core/runtime-environment.ts:192:14)
+    at async main (/home/user/Documents/maci/node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/hardhat/src/internal/cli/cli.ts:323:7)
+ ELIFECYCLE  Command failed with exit code 1.
+ ELIFECYCLE  Command failed with exit code 1.
+```
+
+This is because commitments are generated using random salts, thus will differ at each `genProofs` run.
+
+In [core/Poll.ts](/docs/typedoc/core/classes/Poll):
+
+```
+let newSbSalt = genRandomSalt();
+while (this.sbSalts[this.currentMessageBatchIndex!] === newSbSalt) {
+  newSbSalt = genRandomSalt();
+}
+```
+
+## General Failure
+
+### Case `AssertionError`
+
+This could happen when you run `prove` in the `contracts` package, or run `genProofs` in the `cli` package. If your log looks like following, there are two possible reasons:
+
+1. Your MACI keypair for coordinator is generated wrongly, please generate a new pair and run the whole process again.
+2. The provided private key is unmatched to the public key which deployed the poll, you will need to input the correct private key.
+
+```
+An unexpected error occurred:
+
+AssertionError [ERR_ASSERTION]: false == true
+    at genMaciStateFromContract (/home/user/Documents/maci/contracts/ts/genMaciState.ts:156:9)
+    at processTicksAndRejections (node:internal/process/task_queues:95:5)
+    at async SimpleTaskDefinition.action (/home/user/Documents/maci/contracts/tasks/runner/prove.ts:127:25)
+    at async Environment._runTaskDefinition (/home/user/Documents/maci/node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/hardhat/src/internal/core/runtime-environment.ts:359:14)
+    at async Environment.run (/home/user/Documents/maci/node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/hardhat/src/internal/core/runtime-environment.ts:192:14)
+    at async main (/home/user/Documents/maci/node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/hardhat/src/internal/cli/cli.ts:323:7) {
+  generatedMessage: true,
+  code: 'ERR_ASSERTION',
+  actual: false,
+  expected: true,
+  operator: '=='
+}
+```
+
+### Cannot filter non-indexed parameters
+
+If you encountered the following error log:
+
+```
+TypeError: cannot filter non-indexed parameters; must be null (argument="contract._messageRoot", value=4658669366154318429589992378027343879410506110087584229116806667655891474709, code=INVALID_ARGUMENT, version=6.11.1)
+    at makeError (/home/user/Documents/maci/node_modules/.pnpm/[email protected]/node_modules/ethers/src.ts/utils/errors.ts:687:21)
+    at assert (/home/user/Documents/maci/node_modules/.pnpm/[email protected]/node_modules/ethers/src.ts/utils/errors.ts:715:25)
+    at assertArgument (/home/user/Documents/maci/node_modules/.pnpm/[email protected]/node_modules/ethers/src.ts/utils/errors.ts:727:5)
+    at /home/user/Documents/maci/node_modules/.pnpm/[email protected]/node_modules/ethers/src.ts/abi/interface.ts:1047:31
+    at Array.forEach (<anonymous>)
+    at Interface.encodeFilterTopics (/home/user/Documents/maci/node_modules/.pnpm/[email protected]/node_modules/ethers/src.ts/abi/interface.ts:1042:16)
+    at /home/user/Documents/maci/node_modules/.pnpm/[email protected]/node_modules/ethers/src.ts/contract/contract.ts:108:39
+    at processTicksAndRejections (node:internal/process/task_queues:95:5)
+    at async getSubInfo (/home/user/Documents/maci/node_modules/.pnpm/[email protected]/node_modules/ethers/src.ts/contract/contract.ts:502:18)
+    at async Proxy.queryFilter (/home/user/Documents/maci/node_modules/.pnpm/[email protected]/node_modules/ethers/src.ts/contract/contract.ts:938:38) {
+  code: 'INVALID_ARGUMENT',
+  argument: 'contract._messageRoot',
+  value: 4658669366154318429589992378027343879410506110087584229116806667655891474709n,
+  shortMessage: 'cannot filter non-indexed parameters; must be null'
+}
+```
+
+This could happen during running `genProofs` in `cli` package, or running `prove` in `contracts` package.
+Be aware that we updated several parameters to `indexed`:
+
+```javascript
+event MergeMaciStateAqSubRoots(uint256 indexed _numSrQueueOps);
+event MergeMaciStateAq(uint256 indexed _stateRoot, uint256 indexed _numSignups);
+event MergeMessageAqSubRoots(uint256 indexed _numSrQueueOps);
+event MergeMessageAq(uint256 indexed _messageRoot);
+```
+
+Please remember to pull the latest MACI repo updates(`git fetch origin && git pull origin dev`) and run `build` in the `contracts` package.
+
+### Verifier contract found the proof invalid
+
+If your log looks like the following, that's because the zkey and wasm files added to the [`VkRegistry` contract](/docs/contracts#vkregistry) are different from what you use to run the **prove** command. Check if you're using the correct zkey and wasm files.
+
+```
+Error: The verifier contract found the proof invalid.
+    at Prover.proveMessageProcessing (/home/user/Documents/maci/contracts/tasks/helpers/Prover.ts:215:15)
+    at processTicksAndRejections (node:internal/process/task_queues:95:5)
+    at async SimpleTaskDefinition.action (/home/user/Documents/maci/contracts/tasks/runner/prove.ts:185:7)
+    at async Environment._runTaskDefinition (/home/user/Documents/maci/node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/hardhat/src/internal/core/runtime-environment.ts:359:14)
+    at async Environment.run (/home/user/Documents/maci/node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/hardhat/src/internal/core/runtime-environment.ts:192:14)
+    at async main (/home/user/Documents/maci/node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/hardhat/src/internal/cli/cli.ts:323:7)
+```
+
+### The on-chain verification of total spent voice credits failed
+
+If you ran the `verify` command and got this error, please ensure consistency in your use of quadratic voting throughout interactions with MACI, including poll deployment, proof generation, and verification.