Minimal Anti-Collusion Infrastructure

Please refer to the implementation spec for technical details, and
the original ethresear.ch
post for a
high-level view.

We welcome contributions to this project. Please join our
Telegram group to discuss.

Local development and testing

Requirements

You should have Node 12 installed. Use
nvm to install it.

You also need a Ubuntu/Debian Linux machine on an Intel CPU.

Get started

Install dependencies:

sudo apt-get install build-essential libgmp-dev libsodium-dev git nlohmann-json3-dev nasm g++

Clone this repository, install NodeJS dependencies, and build the source code:

git clone git@github.com:privacy-scaling-explorations/maci.git && \
cd maci && \
npm i && \
npm run bootstrap && \
npm run build

For development purposes, you can generate the proving and verifying keys for
the zk-SNARK circuits, along with their Solidity verifier contracts as such.

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Also install zkutil v0.3.2 and ensure that
the zkutil binary is in the ~/.cargo/bin/ directory. You can configure the
path to this binary via maci-config (see config/test.yaml for an example).

cargo install zkutil --version 0.3.2 &&
zkutil --help

Build the zk-SNARKs and generate their proving and verifying keys:

cd circuits
npm run buildBatchUpdateStateTreeSnark
npm run buildQuadVoteTallySnark

This should take no more than 5 minutes. We used to provide download links to
working versions of the keys and compiled circuit files, but now that we can
use snarkjs to produce them very quickly, we no longer maintain them.

Note that if you change the circuits and recompile them, you should also update
and recompile the verifier contracts in contracts/sol with their new
versions, or the tests will fail:

cd contracts
npm run compileSol

Demo

You can use the MACI command-line interface to run a demo. See:
https://github.com/appliedzkp/maci/tree/master/cli#demonstration

Local development

This repository is organised as Lerna submodules. Each submodule contains its
own unit tests.

config: project-wide configuration files. Includes config files for both
testing and production.
crypto: low-level cryptographic operations.
circuits: zk-SNARK circuits.
contracts: Solidity contracts and deployment code.
domainobjs: Classes which represent high-level domain
objects particular to this project.
core: Business logic functions for message processing, vote tallying,
and circuit input generation through MaciState, a state machine
abstraction.
cli: A command-line interface with which one can deploy and interact with
an instance of MACI.
integrationTests: Integration tests which use the command-line interface
to perform end-to-end tests.

Testing

Unit tests

The following submodules contain unit tests: core, crypto, circuits,
contracts, and domainobjs.

Except for the contracts submodule, run unit tests as such (the following
example is for crypto):

cd crypto
npm run test

For contracts and integrationTests, run the tests one by one. This prevents
incorrect nonce errors.

First, start a Ganache instance in a separate terminal:

cd contracts
npm run ganache

In another terminal, run any of the tests found in contracts/ts/__tests__/
via pattern matching, e.g.:

cd contracts
npx jest IncrementalMerkleTree

would run IncrementalMerkleTree.test.ts.

N.B. npx jest Tree would run that and IncrementalQuinTree.test.ts
in parallel, causing incorrect nonce errors.

Alternatively you can run all unit tests as follows, but you should
stop your Ganache instance first as this will start its own instance
before running the tests:

cd contracts
./scripts/runTestsInCircleCi.sh

Or run all integration tests (this also starts its own Ganache instance):

cd integrationTests
./scripts/runTestsInCircleCi.sh

You can ignore the Ganache errors which this script emits as you should already
have Ganache running in a separate terminal. Otherwise, you will have to exit
Ganache using the kill command.

brendanww/maci