@maci-protocol/website 0.0.0-ci.2653bc0

package/versioned_docs/version-v3.x/technical-references/smart-contracts/MACI.md

@@ -0,0 +1,160 @@
+---
+title: MACI Smart Contract
+description: MACI main smart contract
+sidebar_label: MACI
+sidebar_position: 1
+---
+
+:::info
+Code location: [MACI.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/MACI.sol)
+:::
+
+`MACI.sol` is the core contract of the project, as it provides the base layer for user signups and Polls to be created.
+
+The constructor shown below accepts several arguments:
+
+- `PollFactory` address
+- `MessageProcessorFactory` address
+- `TallyFactory` address
+- `IBasePolicy` address
+- `InitialVoiceCreditProxy` address
+- The depth of the state tree
+
+```solidity
+constructor(
+  IPollFactory _pollFactory,
+  IMessageProcessorFactory _messageProcessorFactory,
+  ITallyFactory _tallyFactory,
+  IBasePolicy _signUpPolicy,
+  uint8 _stateTreeDepth,
+  uint256[5] memory _emptyBallotRoots
+) payable {
+  // initialize and insert the blank leaf
+  InternalLeanIMT._insert(leanIMTData, PAD_KEY_HASH);
+  stateRootsOnSignUp.push(PAD_KEY_HASH);
+
+  pollFactory = _pollFactory;
+  messageProcessorFactory = _messageProcessorFactory;
+  tallyFactory = _tallyFactory;
+  signUpPolicy = _signUpPolicy;
+  stateTreeDepth = _stateTreeDepth;
+  maxSignups = uint256(STATE_TREE_ARITY) ** uint256(_stateTreeDepth);
+  emptyBallotRoots = _emptyBallotRoots;
+
+  // Verify linked poseidon libraries
+  if (hash2([uint256(1), uint256(1)]) == 0) revert PoseidonHashLibrariesNotLinked();
+}
+```
+
+Upon deployment, the contract will initialize the state tree, and insert the blank leaf hash.
+
+After this, all of the parameters will be stored to state, and then the contract will perform a simple sanity check to ensure that the Poseidon hash libraries were linked successfully.
+
+## SignUp
+
+Next, we have the `signUp` function, which allows users to `signUp`, as long as they pass the conditions set in the `signUpPolicy` contract. This contract can use any mean necessary to gatekeep access to MACI's polls. For instance, only wallets with a specific ERC721 token can be allowed to sign up.
+
+This function does the following:
+
+- checks that the maximum number of signups has not been reached. Given a tree depth of 10, this will be $2 ** 10 - 1$.
+- checks that the provided public key is a valid baby-jubjub point
+- registers the user using the sign up policy contract. It is important that whichever policy is used, this reverts if a user tries to sign up twice or the conditions are not met (i.e returning false is not enough)
+- hashes the public key and inserts it into the state tree.
+
+```ts
+function signUp(PubKey memory _pubKey, bytes memory _signUpPolicyData) public virtual {
+  // ensure we do not have more signups than what the circuits support
+  if (leanIMTData.size >= maxSignups) revert TooManySignups();
+
+  // ensure that the public key is on the baby jubjub curve
+  if (!CurveBabyJubJub.isOnCurve(_pubKey.x, _pubKey.y)) {
+    revert InvalidPubKey();
+  }
+
+  // Register the user via the sign-up policy. This function should
+  // throw if the user has already registered or if ineligible to do so.
+  signUpPolicy.register(msg.sender, _signUpPolicyData);
+
+  // Hash the public key and insert it into the tree.
+  uint256 pubKeyHash = hashLeftRight(_pubKey.x, _pubKey.y);
+  uint256 stateRoot = InternalLeanIMT._insert(leanIMTData, pubKeyHash);
+
+  // Store the current state tree root in the array
+  stateRootsOnSignUp.push(stateRoot);
+
+  emit SignUp(leanIMTData.size - 1, block.timestamp, _pubKey.x, _pubKey.y);
+}
+```
+
+## DeployPoll
+
+Once everything has been setup, polls can be deployed using the `deployPoll` function. Polls can be deployed concurrently, as each deployment has its own separate set of contracts and state.
+
+```ts
+function deployPoll(DeployPollArgs calldata args) public virtual returns (PollContracts memory) {
+  // cache the poll to a local variable so we can increment it
+  uint256 pollId = nextPollId;
+
+  // Increment the poll ID for the next poll
+  // 2 ** 256 polls available
+  unchecked {
+    nextPollId++;
+  }
+
+  // check coordinator key is a valid point on the curve
+  if (!CurveBabyJubJub.isOnCurve(args.coordinatorPubKey.x, args.coordinatorPubKey.y)) {
+    revert InvalidPubKey();
+  }
+
+  ExtContracts memory extContracts = ExtContracts({
+    maci: IMACI(address(this)),
+    verifier: IVerifier(args.verifier),
+    vkRegistry: IVkRegistry(args.vkRegistry),
+    policy: IsignUpPolicy(args.policy),
+    initialVoiceCreditProxy: IInitialVoiceCreditProxy(args.initialVoiceCreditProxy)
+  });
+
+  IPollFactory.DeployPollArgs memory deployPollArgs = IPollFactory.DeployPollArgs({
+    startDate: args.startDate,
+    endDate: args.endDate,
+    treeDepths: args.treeDepths,
+    messageBatchSize: args.messageBatchSize,
+    coordinatorPubKey: args.coordinatorPubKey,
+    extContracts: extContracts,
+    emptyBallotRoot: emptyBallotRoots[args.treeDepths.voteOptionTreeDepth - 1],
+    pollId: pollId,
+    relayers: args.relayers,
+    voteOptions: args.voteOptions
+  });
+
+  address p = pollFactory.deploy(deployPollArgs);
+  address mp = messageProcessorFactory.deploy(args.verifier, args.vkRegistry, p, msg.sender, args.mode);
+  address tally = tallyFactory.deploy(args.verifier, args.vkRegistry, p, mp, msg.sender, args.mode);
+
+  // store the addresses in a struct so they can be returned
+  PollContracts memory pollAddr = PollContracts({ poll: p, messageProcessor: mp, tally: tally });
+
+  polls[pollId] = pollAddr;
+
+  emit DeployPoll(pollId, args.coordinatorPubKey.x, args.coordinatorPubKey.y, args.mode);
+
+  return pollAddr;
+}
+```
+
+Polls require the following information:
+
+- `duration`: the duration of the poll
+- `treeDepths`: the depth of the state tree, message tree, and vote option tree
+- `coordinatorPubKey`: the public key of the poll's coordinator
+- `verifier`: the address of the zk-SNARK verifier contract
+- `vkRegistry`: the address of the vk registry contract
+- `mode`: the mode of the poll, to set whether it supports quadratic voting or non quadratic voting
+- `signUpPolicy`: the address of the sign up policy contract
+- `initialVoiceCreditProxy`: the address of the initial voice credit proxy contract
+- `relayers`: the addresses of the relayers for the poll (if offchain voting is enabled)
+- `voteOptions`: the number of vote options for the poll
+
+:::info
+Please be advised that the number of signups in the MACI contract (number of leaves in the merkle tree holding MACI's state) considers the initial zero leaf as one signup. For this reason, when accounting for the real users signed up to MACI, you should subtract one from the value returned from the `numSignUps` function.
+:::

package/versioned_docs/version-v3.x/technical-references/smart-contracts/MessageProcessor.md

@@ -0,0 +1,13 @@
+---
+title: MessageProcessor Smart Contract
+description: MessageProcessor smart contract
+sidebar_label: MessageProcessor
+sidebar_position: 4
+---
+
+:::info
+Code location: [MessageProcessor.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/MessageProcessor.sol)
+:::
+
+This contract is used to prepare parameters for the zk-SNARK circuits as well as for verifying proofs. It should be deployed alongside a `Poll`.
+It will process messages in batches, and after all batches have been processed, the `sbCommitment` can then be used for the `Tally` contract verification steps.

package/versioned_docs/version-v3.x/technical-references/smart-contracts/Params.md

@@ -0,0 +1,33 @@
+---
+title: Params Smart Contract
+description: Params smart contract
+sidebar_label: Params
+sidebar_position: 9
+---
+
+:::info
+Code location: [Params.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/utils/Params.sol)
+:::
+
+A contract holding three structs:
+
+```ts
+/// @notice A struct holding the depths of the merkle trees
+struct TreeDepths {
+  uint8 intStateTreeDepth;
+  uint8 voteOptionTreeDepth;
+}
+
+/// @notice A struct holding the external contracts
+/// that are to be passed to a Poll contract on
+/// deployment
+struct ExtContracts {
+  IMACI maci;
+  IVerifier verifier;
+  IVkRegistry vkRegistry;
+  IBasePolicy policy;
+  IInitialVoiceCreditProxy initialVoiceCreditProxy;
+}
+```
+
+Struct parameters are used to avoid stack too deep errors in the other contracts.

package/versioned_docs/version-v3.x/technical-references/smart-contracts/Policies.md

@@ -0,0 +1,39 @@
+---
+title: Policies Smart Contract
+description: Policies smart contract
+sidebar_label: Policies
+sidebar_position: 6
+---
+
+:::info
+Code location: [Policies](https://github.com/privacy-scaling-explorations/excubiae/tree/main/packages/contracts/contracts/extensions)
+:::
+
+MACI is composed of multiple smart contracts, which together with the zk-SNARK circuits, can be used to carry out on-chain voting. Start with an [overview of our smart contracts here](/docs/technical-references/smart-contracts/MACI).
+
+MACI uses a "policy" contract from Excubiae, which is used to configure and enforce the eligibility criteria of voters who can participate in MACI polls. In other words, it is a way to whitelist signups to the system. Operators of MACI can use the policy contract to configure signup eligibility and to protect against sybil attacks in their polls.
+
+The MACI repository comes with several out-of-the-box options:
+
+- `FreeForAllPolicy` - This allows anyone to signup on MACI.
+- `SignUpTokenPolicy` - This restricts signups only to holders of a specific ERC721 token.
+- `EASPolicy` - This restricts signups only to users who have received an attestation of a specific schema from a trusted attester.
+- `HatsPolicy` - This allows gatekeeping signups to only users who have a specific [Hat](https://www.hatsprotocol.xyz/).
+- `GitcoinPassportPolicy` - This allows gatekeeping signups to only users who have a specific [Gitcoin Passport](https://passport.gitcoin.co/) score.
+- `ZupassPolicy` - This allows gatekeeping signups only to users who have a valid [Zupass PCD ticket](https://github.com/proofcarryingdata/zupass).
+- `SemaphorePolicy` - This allows gatekeeping signups only to users who can prove they are part of a [Semaphore](https://semaphore.pse.dev/) group.
+
+You can find all of the latest policy contracts here:
+https://github.com/privacy-scaling-explorations/excubiae/tree/main/packages/contracts/contracts/extensions
+
+Developers are also welcome to implement a custom policy contract as long as it conforms to the `BasePolicy` - an abstract contract to inherit from with function signature:
+
+```ts
+abstract contract BasePolicy {
+    function enforce(address subject, bytes calldata evidence) external override onlyTarget {}
+}
+```
+
+Whenever a user signs up (via the `MACI.signUp` function), this triggers the MACI contract to call the `BasePolicy.enforce` function. Please note that this function should throw if the user is not eligible to sign up, rather than returning true or false.
+
+If you'd like to create a policy contract for your project, or if there's specific policy functionality you'd like to see MACI support, we'd be happy to help! Please [create a GitHub issue](https://github.com/privacy-scaling-explorations/maci/issues/new/choose).

package/versioned_docs/version-v3.x/technical-references/smart-contracts/Poll.md

@@ -0,0 +1,170 @@
+---
+title: Poll Smart Contract
+description: MACI Poll Contract
+sidebar_label: Poll
+sidebar_position: 2
+---
+
+:::info
+Code location: [Poll.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/Poll.sol)
+:::
+
+This contract allows users to submit their votes.
+
+The main functions of the contract are as follows:
+
+- `publishMessage` - This function allows anyone to publish a message, and it accepts the message object as well as an ephemeral public key. This key together with the coordinator public key will be used to generate a shared ECDH key that will encrypt the message.
+  Before saving the message, the function will check that the voting deadline has not passed, as well as the max number of messages was not reached.
+- `publisMessageBatch` - This function allows to submit a batch of messages, and it accepts an array of messages with their corresponding public keys used in the encryption step. It will call the `publishMessage` function for each message in the array.
+- `joinPoll` - This function allows a user to join a poll. It will check if the voter is allowed to join the poll based on the sign up policy, as well as allocate voice credits based on the voice credit proxy.
+
+## JoinPoll
+
+The `joinPoll` function looks as follows:
+
+```ts
+  /// @inheritdoc IPoll
+  function joinPoll(
+    uint256 _nullifier,
+    PubKey calldata _pubKey,
+    uint256 _stateRootIndex,
+    uint256[8] calldata _proof,
+    bytes memory _signUpPolicyData,
+    bytes memory _initialVoiceCreditProxyData
+  ) external virtual isWithinVotingDeadline {
+    // Whether the user has already joined
+    if (pollNullifiers[_nullifier]) {
+      revert UserAlreadyJoined();
+    }
+
+    // Set nullifier for user's private key
+    pollNullifiers[_nullifier] = true;
+
+    // Verify user's proof
+    if (!verifyJoiningPollProof(_nullifier, _stateRootIndex, _pubKey, _proof)) {
+      revert InvalidPollProof();
+    }
+
+    // Check if the user is eligible to join the poll
+    extContracts.policy.enforce(msg.sender, _signUpPolicyData);
+
+    // Get the user's voice credit balance.
+    uint256 voiceCreditBalance = extContracts.initialVoiceCreditProxy.getVoiceCredits(
+      msg.sender,
+      _initialVoiceCreditProxyData
+    );
+
+    // Store user in the pollStateTree
+    uint256 stateLeaf = hashStateLeaf(StateLeaf(_pubKey, voiceCreditBalance, block.timestamp));
+
+    uint256 stateRoot = InternalLazyIMT._insert(pollStateTree, stateLeaf);
+
+    // Store the current state tree root in the array
+    pollStateRootsOnJoin.push(stateRoot);
+
+    uint256 pollStateIndex = pollStateTree.numberOfLeaves - 1;
+    emit PollJoined(_pubKey.x, _pubKey.y, voiceCreditBalance, block.timestamp, _nullifier, pollStateIndex);
+  }
+```
+
+## PublishMessage
+
+The `publishMessage` function looks as follows:
+
+```ts
+function publishMessage(Message calldata _message, PubKey calldata _encPubKey) public virtual isOpenForVoting {
+  // check if the public key is on the curve
+  if (!CurveBabyJubJub.isOnCurve(_encPubKey.x, _encPubKey.y)) {
+    revert InvalidPubKey();
+  }
+
+  // cannot realistically overflow
+  unchecked {
+    numMessages++;
+  }
+
+  // compute current message hash
+  uint256 messageHash = hashMessageAndEncPubKey(_message, _encPubKey);
+
+  // update current message chain hash
+  updateChainHash(messageHash);
+
+  emit PublishMessage(_message, _encPubKey);
+}
+```
+
+The `publishMessageBatch` function looks as follows:
+
+```ts
+function publishMessageBatch(Message[] calldata _messages, PubKey[] calldata _encPubKeys) public virtual {
+  if (_messages.length != _encPubKeys.length) {
+    revert InvalidBatchLength();
+  }
+
+  uint256 len = _messages.length;
+  for (uint256 i = 0; i < len; ) {
+    // an event will be published by this function already
+    publishMessage(_messages[i], _encPubKeys[i]);
+
+    unchecked {
+      i++;
+    }
+  }
+}
+```
+
+## MergeState
+
+After a Poll's voting period ends, the coordinator's job is to store the main state root, as well as some more information on the Poll contract using `mergeState`:
+
+```ts
+function mergeState() public isAfterVotingDeadline {
+  // This function can only be called once per Poll after the voting
+  // deadline
+  if (stateMerged) revert StateAlreadyMerged();
+
+  // set merged to true so it cannot be called again
+  stateMerged = true;
+
+  uint256 _mergedStateRoot = InternalLazyIMT._root(pollStateTree);
+  mergedStateRoot = _mergedStateRoot;
+
+  // Set currentSbCommitment
+  uint256[3] memory sb;
+  sb[0] = _mergedStateRoot;
+  sb[1] = emptyBallotRoot;
+  sb[2] = uint256(0);
+
+  currentSbCommitment = hash3(sb);
+
+  // get number of joined users and cache in a var for later use
+  uint256 _numSignups = pollStateTree.numberOfLeaves;
+  numSignups = _numSignups;
+
+  // dynamically determine the actual depth of the state tree
+  uint8 depth = 1;
+  while (uint40(1 << depth) < _numSignups) {
+    depth++;
+  }
+
+  actualStateTreeDepth = depth;
+
+  emit MergeState(mergedStateRoot, numSignups);
+}
+```
+
+The function will store the state root from the MACI contract, create a commitment by hashing this merkle root, an empty ballot root stored in the `emptyBallotRoot` variable, and a zero as salt. The commitment will be stored in the `currentSbCommitment` variable. Finally, it will store the total number of signups, and calculate the actual depth of the state tree. This information will be used when processing messages and tally to ensure proof validity.
+
+The `emptyBallotRoot` value is used to store the empty ballot root for the configured vote option tree depth. For instance, if the vote option tree depth is 5, a build script will generate the following values (this assumes that the state tree depth is 10):
+
+```javascript
+emptyBallotRoots[0] = uint256(16015576667038038422103932363190100635991292382181099511410843174865570503661);
+emptyBallotRoots[1] = uint256(166510078825589460025300915201657086611944528317298994959376081297530246971);
+emptyBallotRoots[2] = uint256(10057734083972610459557695472359628128485394923403014377687504571662791937025);
+emptyBallotRoots[3] = uint256(4904828619307091008204672239231377290495002626534171783829482835985709082773);
+emptyBallotRoots[4] = uint256(18694062287284245784028624966421731916526814537891066525886866373016385890569);
+```
+
+:::info
+Please be advised that the number of signups in this case includes the zero leaf. For this reason, when accounting for the real users signed up to the Poll, you should subtract one from the value stored in the Poll contract.
+:::

package/versioned_docs/version-v3.x/technical-references/smart-contracts/PollFactory.md

@@ -0,0 +1,33 @@
+---
+title: Poll Factory Smart Contract
+description: Poll Factory smart contract
+sidebar_label: PollFactory
+sidebar_position: 3
+---
+
+:::info
+Code location: [PollFactory.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/PollFactory.sol)
+:::
+
+`PollFactory` is a smart contract that is used to deploy new Polls. This is used by MACI inside the `deployPoll` function.
+
+```ts
+/// @inheritdoc IPollFactory
+function deploy(DeployPollArgs calldata _args) public virtual returns (address pollAddr) {
+  // deploy the poll
+  Poll poll = new Poll(
+    _args.startDate,
+    _args.endDate,
+    _args.treeDepths,
+    _args.messageBatchSize,
+    _args.coordinatorPubKey,
+    _args.extContracts,
+    _args.emptyBallotRoot,
+    _args.pollId,
+    _args.relayers,
+    _args.voteOptions
+  );
+
+  pollAddr = address(poll);
+}
+```

package/versioned_docs/version-v3.x/technical-references/smart-contracts/Tally.md

@@ -0,0 +1,43 @@
+---
+title: Tally Smart Contract
+description: Tally smart contract
+sidebar_label: Tally
+sidebar_position: 5
+---
+
+:::info
+Code location: [Tally.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/Tally.sol)
+:::
+
+The `Tally` contract is used by the coordinator to submit commitments to the tally results via the `tallyVotes` function. This is done in batches and the final commitment can be used by the users to verify the validity of the results.
+
+This contract should be deployed alongside a `Poll`, with the the constructor accepting the following parameters:
+
+```ts
+  constructor(
+    address _verifier,
+    address _vkRegistry,
+    address _poll,
+    address _mp,
+    address _tallyOwner,
+    Mode _mode
+  ) payable {
+    verifier = IVerifier(_verifier);
+    vkRegistry = IVkRegistry(_vkRegistry);
+    poll = IPoll(_poll);
+    messageProcessor = IMessageProcessor(_mp);
+    mode = _mode;
+  }
+```
+
+- `verifier` - The address of the verifier contract
+- `vkRegistry` - The address of the vkRegistry contract
+- `poll` - The address of the poll contract
+- `messageProcessor` - The address of the messageProcessor contract
+- `mode` - The mode of the tally contract - depending on this, the commitments will be processed differently, and it must equal the Poll mode (quadratic vs non quadratic voting)
+
+Users can use the verification functions to verify the Tally results. These are as follows:
+
+- `verifySpentVoiceCredits` - Verifies the spent voice credits
+- `verifyPerVOSpentVoiceCredits` - Verifies the spent voice credits per vote option
+- `verifyTallyResult` - Verifies the tally result

package/versioned_docs/version-v3.x/technical-references/smart-contracts/VkRegistry.md

@@ -0,0 +1,62 @@
+---
+title: VkRegistry Smart Contract
+description: VkRegistry smart contract
+sidebar_label: VkRegistry
+sidebar_position: 8
+---
+
+:::info
+Code location: [VkRegistry.sol](https://github.com/privacy-scaling-explorations/maci/blob/dev/contracts/contracts/VkRegistry.sol)
+:::
+
+The VkRegistry is a contract that holds the verifying keys for the zk-SNARK circuits. It holds four different sets of keys:
+
+- `processVks` - The keys for the processMessages circuit
+- `tallyVks` - The keys for the tallyVotes circuit
+- `pollJoiningVk` - The key for the poll joining circuit
+- `pollJoinedVk` - The key for the poll joined circuit
+
+Each circuit will have a signature which is its compile-time constants represented as a uint256.
+
+Please note that each Verifying Key should be set with the corresponding mode. Available modes are quadratic voting and non quadratic voting.
+
+The contract owner can set them using the `setVerifyingKeysBatch` function:
+
+```ts
+function setVerifyingKeysBatch(
+  uint256 _stateTreeDepth,
+  uint256 _intStateTreeDepth,
+  uint256 _voteOptionTreeDepth,
+  uint8 _messageBatchSize,
+  Mode[] calldata _modes,
+  VerifyingKey calldata _pollJoiningVk,
+  VerifyingKey calldata _pollJoinedVk,
+  VerifyingKey[] calldata _processVks,
+  VerifyingKey[] calldata _tallyVks
+) public onlyOwner {
+  if (_modes.length != _processVks.length || _modes.length != _tallyVks.length) {
+    revert InvalidKeysParams();
+  }
+
+  uint256 length = _modes.length;
+
+  setPollJoiningVkKey(_stateTreeDepth, _pollJoiningVk);
+  setPollJoinedVkKey(_stateTreeDepth, _pollJoinedVk);
+
+  for (uint256 index = 0; index < length; ) {
+    setVerifyingKeys(
+      _stateTreeDepth,
+      _intStateTreeDepth,
+      _voteOptionTreeDepth,
+      _messageBatchSize,
+      _modes[index],
+      _processVks[index],
+      _tallyVks[index]
+    );
+
+    unchecked {
+      index++;
+    }
+  }
+}
+```

package/versioned_docs/version-v3.x/technical-references/smart-contracts/VoiceCreditProxy.md

@@ -0,0 +1,18 @@
+---
+title: Voice Credits Proxy Smart Contract
+description: Voice Credits Proxy smart contract
+sidebar_label: VoiceCreditsProxy
+sidebar_position: 7
+---
+
+:::info
+Code location: [InitialVoiceCreditProxy](https://github.com/privacy-scaling-explorations/maci/tree/dev/contracts/contracts/initialVoiceCreditProxy)
+:::
+
+The VoiceCreditProxy contract is used to assign voice credits to users. Whichever implementation should the MACI deployers use, this must implement a view function that returns the balance for a user, such as the one below:
+
+```javascript
+function getVoiceCredits(address _user, bytes memory _data) public virtual view returns (uint256) {}
+```
+
+The repository comes with a simple implementation called `ConstantInitialVoiceCreditProxy` which assigns a fixed amount of voice credits to each user.

package/versioned_docs/version-v3.x/technical-references/smart-contracts/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Smart Contracts",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "MACI is composed of multiple smart contracts, which together with the zk-SNARK circuits, can be used to carry out on-chain voting. The main contracts are presented and explained below. Please also find autogenerated solidity documentation with solidity-docs."
+  }
+}

package/versioned_docs/version-v3.x/technical-references/technical-references.md

@@ -0,0 +1,48 @@
+---
+title: MACI Codebase
+description: High-level overview of the MACI codebase
+sidebar_label: Technical References
+sidebar_position: 1
+---
+
+# MACI Overview
+
+The MACI codebase consists of three subsystems in different programming languages:
+
+1. Solidity smart contracts
+2. TypeScript libraries
+3. Circom circuits
+
+## Smart contracts
+
+The MACI smart contracts handle the on-chain aspects - both the functionality and the storage - of the voting system. They provide the functionality to deploy polls, register voters, and accept votes. They also store and manage the on-chain data from transactions, such as the encrypted votes of a poll. Finally, they verify proofs of the zk-SNARK circuits, so that everyone can validate the voting results.
+
+The MACI smart contracts are written in [Solidity](https://soliditylang.org/).
+
+Contracts are released through the [`@maci-contracts`](https://www.npmjs.com/package/maci-contracts) NPM package.
+
+[Learn more about MACI contracts](/docs/technical-references/smart-contracts/)
+
+## TypeScript libraries
+
+The TypeScript libraries manage the business logic between the smart contracts and the circuit code. They provide a variety of functionality, such as encryption tools, utilities, and a CLI for interacting with MACI (for actions like signing up, voting, tallying votes & generating proofs).
+
+The MACI [TypeScript](https://www.typescriptlang.org/) libraries are released through the following NPM packages:
+
+- [`@maci-cli`](https://www.npmjs.com/package/maci-cli)
+- [`@maci-core`](https://www.npmjs.com/package/maci-core)
+- [`@maci-crypto`](https://www.npmjs.com/package/maci-crypto)
+- [`@maci-domainobjs`](https://www.npmjs.com/package/maci-domainobjs)
+- [`@maci-integrationtests`](https://www.npmjs.com/package/maci-integrationtests)
+- [`@maci-sdk`](https://www.npmjs.com/package/maci-sdk)
+
+## Circuits
+
+MACI has multiple circuits that ensure all off-chain computation is completed correctly. The circuits are used to generate zero-knowledge proofs (zk-SNARKs) that the votes were counted correctly. Specifically, they enforce that message processing and vote tallying were correctly executed by the coordinator. The proofs can then be verified through a verifier smart contract on-chain.
+
+The circuits for these zero-knowledge proofs are written
+in [Circom](https://iden3.io/circom).
+
+The MACI circuits are released through the [`@maci-circuits`](https://www.npmjs.com/package/maci-circuits) NPM package.
+
+[Learn more about MACI circuits](/docs/technical-references/zk-snark-circuits/)

package/versioned_docs/version-v3.x/technical-references/zk-snark-circuits/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "zk-SNARK Circuits",
+  "position": 3
+}