Skip to content

Commit

Permalink
docs(documentation): added guides and improved overall docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Crisgarner committed Oct 11, 2024
1 parent 038c9a2 commit 89371de
Show file tree
Hide file tree
Showing 68 changed files with 596 additions and 815 deletions.
3 changes: 3 additions & 0 deletions apps/website/docusaurus.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,9 @@ async function getConfig(): Promise<Config> {
blogPosts: Array.isArray(blogPosts) ? blogPosts : [],
},
themeConfig: {
prism: {
additionalLanguages: ["bash"],
},
image: "img/maci-card.png",
navbar: {
title: "MACI",
Expand Down
2 changes: 1 addition & 1 deletion apps/website/src/scripts/setupSolidityDocs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { copyDirectory, generateToC, insertIndexPage } from "./utils";
// where to move the solidity doc files over
const solidityDocDir = path.resolve(
__dirname,
"../../versioned_docs/version-v2.x/developers-references/smart-contracts/solidity-docs",
"../../versioned_docs/version-v2.x/technical-references/smart-contracts/solidity-docs",
);
// the origin folder (from the contracts package)
const sourceDir = path.resolve(__dirname, "../../../packages/contracts/docs");
Expand Down
4 changes: 2 additions & 2 deletions apps/website/src/scripts/setupTypedoc.ts
Original file line number Diff line number Diff line change
Expand Up @@ -82,12 +82,12 @@ function defineTargetDirectory() {
const versionContentJson = JSON.parse(versionContent) as string[];
return path.resolve(
__dirname,
`../../versioned_docs/version-${versionContentJson[0]}/developers-references/typescript-code/typedoc`,
`../../versioned_docs/version-${versionContentJson[0]}/technical-references/typescript-code/typedoc`,
);
}
}

return path.resolve(__dirname, "../../docs/developers-references/typescript-code/typedoc");
return path.resolve(__dirname, "../../docs/technical-references/typescript-code/typedoc");
}

if (fs.existsSync(TYPEDOC_DIR)) {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,4 @@
{
"label": "Contributing",
"position": 10,
"link": {
"type": "generated-index",
"description": "MACI's contribution guidelines."
}
"position": 10
}
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: MACI Project Ideas
description: Community-sourced ideas of projects you could build with MACI
sidebar_label: MACI Project ideas
sidebar_position: 1
sidebar_position: 3
---

# Build on MACI
Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,4 @@
{
"label": "Core Concepts",
"position": 3,
"link": {
"type": "generated-index",
"description": "Understand MACI's core concepts."
}
"position": 5
}
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Hashing and Encryption
description: A short introduction of the main primitives used by MACI
sidebar_label: Hashing and Encryption
sidebar_position: 2
sidebar_position: 3
---

### Hash Functions
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: MACI Keys
description: A short introduction of MACI's keys
sidebar_label: Maci Keys
sidebar_position: 1
sidebar_position: 2
---

## Elliptic Curves
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ MACI uses different types of merkle trees to store and manage data. On chain, a

## Accumulator queue

This contract holds [messages](/docs/developers-references/smart-contracts/Poll#publishmessage) sent by users. When a leaf is inserted into the `AccQueue`, the merkle root is not updated yet, instead the leaf is updated or the root of a subtree is re-computed. The smart contract exposes three functions:
This contract holds [messages](/docs/technical-references/smart-contracts/Poll#publishmessage) sent by users. When a leaf is inserted into the `AccQueue`, the merkle root is not updated yet, instead the leaf is updated or the root of a subtree is re-computed. The smart contract exposes three functions:

- `enqueue(leaf)`: Enqueues a leaf into a subtree
four out of five times it is invoked, an enqueue operation may or may not require the contract to perform a hash function. When it does, only up to $t_d$ required number of hashes need to be computed
Expand All @@ -20,4 +20,4 @@ This contract holds [messages](/docs/developers-references/smart-contracts/Poll#

## LazyIMT

A LazyIMT is a Merkle tree that is updated lazily. It is used to [store the state leaves](/docs/developers-references/smart-contracts/MACI#signup) of the users. The "lazy" tree performs the minimum number of hashes necessary to insert elements in a tree. This means if there is only a left element the parent hash is not calculated until a corresponding right element exists, to avoid having an intermediate hash that will change in the future. This tree is designed for roots that are infrequently accessed onchain.
A LazyIMT is a Merkle tree that is updated lazily. It is used to [store the state leaves](/docs/technical-references/smart-contracts/MACI#signup) of the users. The "lazy" tree performs the minimum number of hashes necessary to insert elements in a tree. This means if there is only a left element the parent hash is not calculated until a corresponding right element exists, to avoid having an intermediate hash that will change in the future. This tree is designed for roots that are infrequently accessed onchain.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: MACI Workflow
description: Overview of the MACI workflow
sidebar_label: Workflow
sidebar_position: 4
sidebar_position: 1
---

<!-- TODO: create flowcharts, similar to Kyle's (but make light/dark mode compatible) -->
Expand Down Expand Up @@ -69,11 +69,11 @@ See our [smart contract docs](/docs/category/smart-contracts) or our [contract s

### MACI.sol

The MACI contract is responsible for registering user signups by recording the initial public key for each user (via the [`signUp` function](/docs/developers-references/smart-contracts/solidity-docs/MACI#signup-1)). To conduct a voting round, the coordinator can deploy a Poll via MACI (with the [`deployPoll` function](/docs/developers-references/smart-contracts/solidity-docs/MACI#deploypoll)).
The MACI contract is responsible for registering user signups by recording the initial public key for each user (via the [`signUp` function](/docs/technical-references/smart-contracts/solidity-docs/MACI#signup-1)). To conduct a voting round, the coordinator can deploy a Poll via MACI (with the [`deployPoll` function](/docs/technical-references/smart-contracts/solidity-docs/MACI#deploypoll)).

### Poll.sol

The Poll contract is where users submit their votes (via the [`publishMessage` function](/docs/developers-references/smart-contracts/solidity-docs/Poll#publishmessage)). One MACI contract can be used for multiple Poll contracts. In other words, a user that signed up to the MACI contract can vote on multiple issues, with each issue represented by a distinct Poll contract.
The Poll contract is where users submit their votes (via the [`publishMessage` function](/docs/technical-references/smart-contracts/solidity-docs/Poll#publishmessage)). One MACI contract can be used for multiple Poll contracts. In other words, a user that signed up to the MACI contract can vote on multiple issues, with each issue represented by a distinct Poll contract.

### MessageProcessor.sol and Tally.sol

Expand Down Expand Up @@ -120,13 +120,13 @@ At this point, the coordinator must process all the messages, tally the results,

Once the voting period has completed for a specific poll, the coordinator will use the `MessageProcessor` contract to first prove that they have correctly decrypted each message and applied them to correctly create an updated state tree. This state tree keeps an account of all the valid votes that should be counted. So, when processing the messages, the coordinator will not keep messages that are later overridden by a newer message inside the state tree. For example, if a user votes for option A, but then later sends a new message to vote for option B, the coordinator will only count the vote for option B.

The coordinator must process messages in batches so that proving on chain does not exceed the data limit. The coordinator then creates a zk-SNARK proving their state tree correctly contains only the valid messages. Once the proof is ready, the coordinator calls [`MessageProcessor.processMessages()`](/docs/developers-references/smart-contracts/solidity-docs/MessageProcessor#processmessages), providing a hash of the state tree and the zk-SNARK proof as an input parameters.
The coordinator must process messages in batches so that proving on chain does not exceed the data limit. The coordinator then creates a zk-SNARK proving their state tree correctly contains only the valid messages. Once the proof is ready, the coordinator calls [`MessageProcessor.processMessages()`](/docs/technical-references/smart-contracts/solidity-docs/MessageProcessor#processmessages), providing a hash of the state tree and the zk-SNARK proof as an input parameters.

The `MessageProcessor` contract will send the proof to a separate verifier contract. The verifier contract is specifically built to read MACI zk-SNARK proofs and tell if they are valid or not. So, if the verifier contract returns true, then everyone can see on-chain that the coordinator correctly processed that batch of messages. The coordinator repeats this process until all messages have been processed.

#### Tally Results

Finally, once all messages have been processed, the coordinator tallies the votes of the valid messages (off-chain). The coordinator creates a zk-SNARK proving that the valid messages in the state tree (proved in Process Messages step) contain votes that sum to the given tally result. Then, they call [`Tally.tallyVotes()`](/docs/developers-references/smart-contracts/solidity-docs/Tally#tallyvotes) with a hash of the correct tally results and the zk-SNARK proof. Similarly to the processMessages function, the `tallyVotes` function will send the proof to a verifier contract to ensure that it is valid.
Finally, once all messages have been processed, the coordinator tallies the votes of the valid messages (off-chain). The coordinator creates a zk-SNARK proving that the valid messages in the state tree (proved in Process Messages step) contain votes that sum to the given tally result. Then, they call [`Tally.tallyVotes()`](/docs/technical-references/smart-contracts/solidity-docs/Tally#tallyvotes) with a hash of the correct tally results and the zk-SNARK proof. Similarly to the processMessages function, the `tallyVotes` function will send the proof to a verifier contract to ensure that it is valid.

<!-- "hash of the correct tally results" - so are the final results actually put on chain? or just a hash?? -->

Expand Down

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

Loading

0 comments on commit 89371de

Please sign in to comment.