Merge pull request #1350 from privacy-scaling-explorations/docs/new-v…

…ersion

docs: add doc entries for new maci version (currently being developed)

.gitignore

@@ -13,7 +13,6 @@ solc
 cli/tally.json
 **/test_tally.json
 **/tally.json
-**/subsidy.json
 integrationTests/test_tally.json
 integrationTests/artifacts/**
 deployedAddresses.json

circuits/README.md

@@ -9,7 +9,6 @@ The main circuits are:
 
 - `processMessages.circom`
 - `tallyVotes.circom`
-- (optional) `subsidy.circom`
 
 The rest of the circuits are utilities templates that are required for the main circuits to work correctly. These include utilities such as float math, conversion of private keys, and Poseidon hashing/encryption.
 

cli/package.json

@@ -30,7 +30,6 @@
     "test:ceremony": "ts-mocha --exit tests/ceremony-params/ceremonyParams.test.ts",
     "test:e2e": "ts-mocha --exit tests/e2e/e2e.test.ts",
     "test:e2e-non-qv": "ts-mocha --exit tests/e2e/e2e.nonQv.test.ts",
-    "test:e2e-subsidy": "ts-mocha --exit tests/e2e/e2e.subsidy.test.ts",
     "test:keyChange": "ts-mocha --exit tests/e2e/keyChange.test.ts",
     "test:unit": "nyc ts-mocha --exit tests/unit/*.test.ts",
     "test:airdrop": "nyc ts-mocha --exit tests/unit/airdrop.test.ts",

contracts/deploy-config-example.json

@@ -29,7 +29,6 @@
     "Poll": {
       "pollDuration": 30,
       "coordinatorPubkey": "macipk.9a59264310d95cfd8eb7083aebeba221b5c26e77427f12b7c0f50bc1cc35e621",
-      "subsidyEnabled": false,
       "useQuadraticVoting": true
     }
   }

website/.gitignore

@@ -19,6 +19,9 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-versioned_docs/version-v1.x/solidity-docs
-versioned_docs/version-v1.x/typedoc
-typedoc
+versioned_docs/version-v1.2/solidity-docs
+versioned_docs/version-v1.2/typedoc
+versioned_docs/version-v1.3_alpha/typedoc/
+versioned_docs/version-v1.3_alpha/solidity-docs/
+
+typedoc

website/src/scripts/setupSolidityDocs.ts

@@ -4,7 +4,7 @@ import path from "path";
 import { copyDirectory, insertIndexPage } from "./utils";
 
 // where to move the solidity doc files over
-const solidityDocDir = path.resolve(__dirname, "../../versioned_docs/version-v1.x/solidity-docs");
+const solidityDocDir = path.resolve(__dirname, "../../versioned_docs/version-v1.3_alpha/solidity-docs");
 // the origin folder (from the contracts package)
 const sourceDir = path.resolve(__dirname, "../../../contracts/docs");
 

website/versioned_docs/version-v1.x/cli.md → website/versioned_docs/version-v1.2/cli.md

@@ -66,7 +66,7 @@ Public key: macipk.946c756cb8588f7169d37e23a98b92051359d64321cf7372a75757b5e9d55
 Private key: macisk.08a06aef74c7f6a6f73704e30677418731bc738500f4e6c63dbfe41af8d6719c
 ```
 
-### Generate MACI keys
+### Generate MACI keys
 
 You can generate MACI keys using the following cli utility.
 

website/versioned_docs/version-v1.x/installation.md → website/versioned_docs/version-v1.2/installation.md

@@ -113,12 +113,6 @@ Edit `circuits/circom/circuits` to include the circuits you would like to compil
     "template": "TallyVotesNonQv",
     "params": [10, 1, 2],
     "pubs": ["inputHash"]
-  },
-  "SubsidyPerBatch_10-1-2_test": {
-    "file": "subsidy",
-    "template": "SubsidyPerBatch",
-    "params": [10, 1, 2],
-    "pubs": ["inputHash"]
   }
 }
 ```

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

@@ -0,0 +1,160 @@
+---
+title: MACI Security Audits
+description: Overview of MACI audit history with references to audit reports.
+sidebar_label: Security audits
+sidebar_position: 14
+---
+
+# MACI Security Audits
+
+## Full reports
+
+- Audit by PSE Audit 2024/02 [report](/audit_reports/20240223_PSE_Audit_audit_report.pdf)
+- Audit by HashCloak 2022/09 [report](/audit_reports/202220930_Hashcloak_audit_report.pdf)
+- Audit by HashCloak 2021/09 [report](/audit_reports/20210922_Hashcloak_audit_report.pdf)
+
+## PSE audit 2024
+
+In February 2024 the PSE Audit team audited the MACI codebase with a focus on the smart contracts, TypeScript core, and Circom circuits Three critical bugs were found: two within the Circom circuits and one in the smart contracts. All three of these have been fixed.
+
+Please see the [PSE Audit report](/audit_reports/20240223_PSE_Audit_audit_report.pdf) for details.
+
+## Veridise disclosure 2023
+
+In March 2023, Veridise responsibly disclosed a number of issues to the MACI team, which were identified using their new [tool](https://twitter.com/VeridiseInc/status/1630806464695791616?s=20) for catching ZK circuit bugs.
+
+Out of five issues disclosed, only three were relevant and have been since fixed by the MACI team. The other two issues were disregarded as they were present in older version of code which is not in use anymore.
+
+We would like to thank the Veridise team for their effort in keeping open source projects safe.
+
+### Issue 1
+
+**Description**
+
+In the template `QuinSelector`, if you want to confirm the input signal index is a valid integer less than 2\*\*3, you should add Num2bits(3) to check it.
+
+**Code Location**
+
+[`incrementalQuinTree.circom`](https://github.com/privacy-scaling-explorations/maci/blob/78609349aecd94186216ac8743d61b1cb81a097f/circuits/circom/trees/incrementalQuinTree.circom#L30)
+
+**Fix**
+
+[Code location](https://github.com/chaosma/maci/blob/60727d4d10406edda32ad28e53d399d41d45ed88/circuits/circom/trees/incrementalQuinTree.circom#L37)
+
+```javascript
+// Ensure that index < choices
+component lessThan = SafeLessThan(3);
+```
+
+This was fixed by adding a new Template, `SafeLesThan` which uses `Num2Bits` as further check on the signals:
+
+```javascript
+// the implicit assumption of LessThan is both inputs are at most n bits
+// so we need to add range check for both inputs
+template SafeLessThan(n) {
+    assert(n <= 252);
+    signal input in[2];
+    signal output out;
+
+    component n2b1 = Num2Bits(n);
+    n2b1.in  <== in[0];
+    component n2b2 = Num2Bits(n);
+    n2b2.in  <== in[1];
+
+    component n2b = Num2Bits(n+1);
+
+    n2b.in <== in[0]+ (1<<n) - in[1];
+
+    out <== 1-n2b.out[n];
+}
+```
+
+### Issue 2
+
+**Description**
+
+This issue is the same issue number 1, this time for the input signal index.
+
+**Code Location**
+
+[`incrementalQuinTree.circom`](https://github.com/privacy-scaling-explorations/maci/blob/78609349aecd94186216ac8743d61b1cb81a097f/circuits/circom/trees/incrementalQuinTree.circom#L64)
+
+**Fix**
+
+[PR with fix](https://github.com/privacy-scaling-explorations/maci/pull/646/files#diff-f3ad1f61e9b95b88929664b67c873325fdf70cb8569c2a96da4b0e9f02710391)
+
+As with issue number 1, a new template `SafeGreaterThan` was added:
+
+```javascript
+// N is the number of bits the input have.
+// The MSF is the sign bit.
+template SafeGreaterThan(n) {
+    signal input in[2];
+    signal output out;
+
+    component lt = SafeLessThan(n);
+
+    lt.in[0] <== in[1];
+    lt.in[1] <== in[0];
+    lt.out ==> out;
+}
+```
+
+And then used it to constrain the [`index` input signal](https://github.com/chaosma/maci/blob/2d7a3a0efd33dfc3a5f4d3f95bec3adda7abb963/circuits/circom/trees/incrementalQuinTree.circom#L115-L117):
+
+```javascript
+greaterThan[i] = SafeGreaterThan(3);
+greaterThan[i].in[0] <== i;
+greaterThan[i].in[1] <== index;
+```
+
+### Issue 3
+
+**Description**
+
+In the template `QuinGeneratePathIndices`, the constraints of the `signal n[levels + 1]` don't perform well for division and modulo counting.
+
+**Code Location**
+
+[`incrementalQuinTree.circom`](https://github.com/privacy-scaling-explorations/maci/blob/7c1b3743ea753786011289a356eaa45ba72f9ca1/circuits/circom/trees/incrementalQuinTree.circom#L228-L242)
+
+**Fix**
+
+The [updated code](https://github.com/chaosma/maci/blob/2d7a3a0efd33dfc3a5f4d3f95bec3adda7abb963/circuits/circom/trees/incrementalQuinTree.circom#L285-L290) uses the `SafeLessThen` template, as shown below:
+
+```javascript
+for (var i = 0; i < levels; i++) {
+    // Check that each output element is less than the base
+    leq[i] = SafeLessThan(3);
+    leq[i].in[0] <== out[i];
+    leq[i].in[1] <== BASE;
+    leq[i].out === 1;
+
+    // Re-compute the total sum
+    sum.nums[i] <== out[i] * (BASE ** i);
+}
+```
+
+## HashCloak audit 2022
+
+In the summer of 2022, MACI v1 was audited by HashCloak. The audit covered both the zk-SNARK circuits and the Solidity smart contracts.
+
+This audit revealed a number of high severity issues which have been remediated by the MACI development team. All issues were successfully fixed and reflected in MACI v1.1.1.
+
+Please see the [HashCloak report](/audit_reports/202220930_Hashcloak_audit_report.pdf) for details.
+
+## HashCloak audit 2021
+
+From July 5th, 2021 to August 2nd, 2021, the Ethereum Foundation’s Applied ZKPs team engaged HashCloak for an audit of the MACI protocol. The audit was conducted with 3 auditors over 15 person weeks.
+
+The following packages were in scope:
+
+- Circuits
+- Contracts
+- Core
+- Crypto
+- Domainobjs
+
+From August 18, 2021 to September 22, 2021, Hashcloak assisted the MACI team in resolving the issues.
+
+Please see the [HashCloak report](/audit_reports/20210922_Hashcloak_audit_report.pdf) for details.

website/versioned_docs/version-v1.3_alpha/ci-pipeline.md

@@ -0,0 +1,38 @@
+---
+title: CI Pipeline
+description: Introduction to how MACI's CI works
+sidebar_label: CI
+sidebar_position: 15
+---
+
+# Continuous Integration (CI) Pipeline
+
+CI (Continuous Integration) pipeline is an automated workflow to ensure that software is always in a working state. An event like opening a pull request causes a pipeline to run. The pipeline consists of an automated build process and a suite of automated tests (See [Testing](https://pse.dev/docs/testing) for more details).
+
+![cicd-maci drawio-7](https://user-images.githubusercontent.com/1610146/185962260-091cd952-5444-44f3-89e3-be64e81d4c21.png)
+
+## Pipeline Triggers
+
+### Commit to Main Branch
+
+Each commit (i.e. a merged PR) to the main branch triggers the pipeline. The pipeline creates packages that can be deployed to any environment. Packages are uploaded to an artifact repository (e.g. npm).
+
+![cicd-maci drawio-12](https://user-images.githubusercontent.com/1610146/183404579-8bcb76fe-34b6-4748-a5ae-e2e4b010bd86.png)
+
+### Pull Request (PR)
+
+When a pull request has been created (or updated), it triggers the PR pipeline. It gives the reviewer confidence that the software works as expected with the introduced code changes.
+
+![cicd-maci drawio-9](https://user-images.githubusercontent.com/1610146/183391880-d3a20f29-2708-4d72-988d-4781c0396e48.png)
+
+### Nightly
+
+Nightly build runs every midnight. It is to ensure that all required dependencies are present and to show no bugs have been introduced.
+
+![cicd-maci drawio-11](https://user-images.githubusercontent.com/1610146/183404455-cc2aaace-fe52-40f4-b5e4-3c852c5ff516.png)
+
+### Tag Push
+
+When a tag has been pushed, it triggers a release pipeline. It will draft a release note with an auto-generated changelog and publish npm package(s).
+
+![cicd-maci drawio-5](https://user-images.githubusercontent.com/1610146/185958513-51dadaf1-7f72-404b-b482-149b91edcaab.png)