This submodule assists with handling key business logic functions and processes.
One may conceive of MACI as a state machine with 1) data and 2) functions which transform said data. This makes it easier to reason about the system, write tests, and implement functionality. It also allows us to implement the smart contracts in discrete components which are easy to test.
To this end, this submodule exposes a MaciState class and a Poll class.
Developers should instantiate objects from these classes to test MACI. For
instance, MACI.test.ts creates a
MaciState object and every time it interacts with the MACI smart contract, it
mirrors said interaction on the MaciState and Poll. As such, the developer
can then use their helper functions like maciState.signUp(),
poll.publishMessage, poll.processMessages(), and poll.tallyVotes() to
step through the various stages of the MACI flow.
Accepts a user's public key and creates a new state leaf and ballot leaf.
In testing, whenever a test suite submits a signUp() transaction, it should
call maciState.signUp() as well, so that the off-chain representation of MACI
is kept up to date.
In production, genMaciStateFromContract() in
genMaciState.ts uses this function when it
scans a MACI contract's event log for signups, so as to bring its MaciState
instance up to date.
Creates a new Poll. This should be done whenever the MACI contract's
deployPoll() function is called.
A function that deep-copies an object.
stateTree is a quinary Merkle tree, chosen over a binary tree due to the gas and circuit constraints associated with the Poseidon hash function (details here). Each leaf in this tree represents a participant's public key, their voice credit balance and the block timestamp at which they signed up. The tree features a configurable depth and an arity of five, with insertions starting at index 1. The zeroth leaf is reserved as a security measure against denial-of-service attacks.
A Poll is an off-chain representation of a Poll. In testing, Poll instances
should mirror their on-chain counterparts.
Publishes a message by updating the message tree and message accumulation queue.
Processes a batch of messages and returns the inputs to the processMessages
circuit which can be used to prove correct execution.
Tallies a batch of votes and returns the inputs to the tallyVotes
circuit which can be used to prove correct execution.
Deep-copies and returns this object.
messageTree is also a quinary Merkle tree. Each message in this tree represents an encrypted command, such as a user casting a vote in a poll or changing their public key.
For more details about testing please refer to the tests documentation.
ts/: The home for our core classes,MaciStateandPollts/utls/: Contains supporting utilitiests/__tests__/: A dedicated test suite directory