Merge pull request #1228 from privacy-scaling-explorations/docs/add-p…

…urpose

Docs/add purpose

website/versioned_docs/version-v1.x/audit.md

@@ -2,7 +2,7 @@
 title: MACI Security Audits
 description: Overview of MACI audit history with references to audit reports.
 sidebar_label: Security audits
-sidebar_position: 12
+sidebar_position: 14
 ---
 
 # MACI Security Audits

website/versioned_docs/version-v1.x/ci-pipeline.md

@@ -2,7 +2,7 @@
 title: CI Pipeline
 description: Introduction to how MACI's CI works
 sidebar_label: CI
-sidebar_position: 13
+sidebar_position: 15
 ---
 
 # Continuous Integration (CI) Pipeline

website/versioned_docs/version-v1.x/circuits.md

@@ -2,7 +2,7 @@
 title: MACI Circuits
 description: Introduction to the core zk-SNARK circuits of MACI
 sidebar_label: Circuits
-sidebar_position: 7
+sidebar_position: 9
 ---
 
 # zk-SNARKS in MACI

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

@@ -2,7 +2,7 @@
 title: MACI Command-line interface (CLI)
 description: Introduction to the MACI CLI interface that allows for effective deployment and testing
 sidebar_label: Command-line interface
-sidebar_position: 5
+sidebar_position: 7
 ---
 
 # Command-line interface

website/versioned_docs/version-v1.x/contracts.md

@@ -2,7 +2,7 @@
 title: MACI Smart Contracts
 description: MACI is composed of multiple smart contracts, which together with the zk-SNARK circuits, can be used to carry out on-chain voting
 sidebar_label: Smart Contracts
-sidebar_position: 6
+sidebar_position: 8
 ---
 
 # Smart Contracts

website/versioned_docs/version-v1.x/contributing/contributing.md

@@ -2,7 +2,7 @@
 title: Contributing to MACI
 description: Instructions on how to contribute to MACI
 sidebar_label: Contributing
-sidebar_position: 19
+sidebar_position: 21
 ---
 
 # Contributing

website/versioned_docs/version-v1.x/coordinator-processing.md

@@ -2,7 +2,7 @@
 title: Coordinator local processing
 description: How does the coordinator process and tallies messages locally
 sidebar_label: Coordinator local processing
-sidebar_position: 14
+sidebar_position: 16
 ---
 
 # Coordinator local processing

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

@@ -2,7 +2,7 @@
 title: Installing MACI
 description: How to install MACI
 sidebar_label: Installation
-sidebar_position: 3
+sidebar_position: 5
 ---
 
 # Installation

website/versioned_docs/version-v1.x/integrating.md

@@ -2,7 +2,7 @@
 title: Integrating MACI
 description: How to integrate MACI into your application
 sidebar_label: Integrating
-sidebar_position: 11
+sidebar_position: 13
 ---
 
 # Integrating MACI

website/versioned_docs/version-v1.x/key-change.md

@@ -2,7 +2,7 @@
 title: MACI key change
 description: How key change messages work
 sidebar_label: Key change
-sidebar_position: 16
+sidebar_position: 18
 ---
 
 # MACI Key Change

website/versioned_docs/version-v1.x/overview.md

@@ -2,7 +2,7 @@
 title: MACI Overview
 description: High-level overview of the MACI codebase
 sidebar_label: Overview
-sidebar_position: 2
+sidebar_position: 4
 ---
 
 # MACI Overview

website/versioned_docs/version-v1.x/primitives.md

@@ -2,7 +2,7 @@
 title: MACI Primitives
 description: A short introduction of the main primitives used by MACI
 sidebar_label: Primitives
-sidebar_position: 4
+sidebar_position: 6
 ---
 
 ## MACI primitives

website/versioned_docs/version-v1.x/purpose.md

@@ -0,0 +1,62 @@
+---
+title: Why MACI Matters
+description: An overview of the purpose of MACI
+sidebar_label: Purpose
+sidebar_position: 2
+---
+
+# Why MACI Matters
+
+To understand the promise of on-chain voting and the purpose of MACI, we highly recommend reading [Vitalik's post on blockchain voting](https://vitalik.eth.limo/general/2021/05/25/voting2.html). He provides an overview of the incredible potential of e-voting and why blockchains are an excellent technology to implement e-voting solutions on top of.
+
+Below we attempt to summarize some of the points layed out in that post:
+
+## Security requirements of a voting system
+
+Any voting system requires a few crucial security properties in order to be trusted by users:
+
+- **Correct execution**: the result (tally of votes) must be correct, and the result must be guaranteed by a transparent process (so that everyone is convinced that the result is correct)
+- **Censorship resistance**: anyone eligible to vote should be able to vote, and it should not be possible to interfere with anyone's attempt to vote or to prevent anyone’s vote from being counted
+- **Privacy:** you should not be able to tell which candidate someone specific voted for, or even if they voted at all
+- **Coercion resistance:** you should not be able to prove to someone else how you voted, even if you want to
+
+## Voting systems
+
+Looking at various approaches to implement a voting system, we can see how they compare across these properties.
+
+### In-person voting systems
+
+In short, it's hard to know for sure how current voting systems operate. Governments and corporations spend lots of resources on their systems and processes in an attempt to ensure their integrity, but ultimately neither the systems nor the processes are fully auditable, so we must trust that these security properties are being enforced.
+
+|                       | In-person |
+| --------------------- | --------- |
+| Correct execution     | 🤷‍♂️        |
+| Censorship resistance | 🤷‍♂️        |
+| Privacy               | 🤷‍♂️        |
+| Collusion resistance  | 🤷‍♂️        |
+
+### Blockchain voting systems
+
+Blockchains provide two key properties: correct execution and censorship resistance. In terms of execution, the blockchain accepts inputs (transaction) from users, correctly processes them according to some pre-defined rules, and returns the correct output. No one is able to change the rules. Any user that wants to send a transaction and is willing to pay a high enough fee can send the transaction and expect to see it quickly included on-chain.
+
+By default, however, Blockchain voting applications face challenges. Ethereum, like most blockchains, is completely transparent - all transaction data is public, so there is no privacy for voters or their votes. This makes bribery very easy as a result: someone can easily show a transaction receipt that proves how they voted. In some cases, bribery can be completely automated via smart contracts to make collusion entirely trustless.
+
+|                       | In-person | Ethereum |
+| --------------------- | --------- | -------- |
+| Correct execution     | 🤷‍♂️        | ✅       |
+| Censorship resistance | 🤷‍♂️        | ✅       |
+| Privacy               | 🤷‍♂️        | ❌       |
+| Collusion resistance  | 🤷‍♂️        | ❌       |
+
+### Blockchain voting systems (with ZKPs)
+
+Enter zero-knowledge proofs (ZKPs), which when combined with blockchains like Ethereum, can enable private on-chain voting but maintain public on-chain results that are verifiable by anyone (including smart contracts). Vote tallying takes place off-chain but ZKPs are submitted and verified on-chain, which guarantees votes are counted correctly without revealing the individual votes.
+
+|                       | In-person | Ethereum | Ethereum w/ ZK |
+| --------------------- | --------- | -------- | -------------- |
+| Correct execution     | 🤷‍♂️        | ✅       | ✅             |
+| Censorship resistance | 🤷‍♂️        | ✅       | ✅             |
+| Privacy               | 🤷‍♂️        | ❌       | ✅             |
+| Collusion resistance  | 🤷‍♂️        | ❌       | ✅             |
+
+This, in essence, is why MACI exists. By combining these technologies in novel ways, we believe we can achieve all the core security properties that a voting system must have.

website/versioned_docs/version-v1.x/spec.md

@@ -2,7 +2,7 @@
 title: MACI v1.0 Specification
 description: A detailed specification meant to assist auditors in reviewing MACI version 1.0
 sidebar_label: Specification
-sidebar_position: 15
+sidebar_position: 17
 ---
 
 # MACI v1.0 Specification

website/versioned_docs/version-v1.x/testing-in-detail.md

@@ -2,7 +2,7 @@
 title: MACI Testing in Detail
 description: How MACI tests work in detail
 sidebar_label: Testing in detail
-sidebar_position: 10
+sidebar_position: 12
 ---
 
 # Testing in detail

website/versioned_docs/version-v1.x/testing.md

@@ -2,7 +2,7 @@
 title: Testing MACI
 description: An introduction on how to test MACI
 sidebar_label: Testing
-sidebar_position: 9
+sidebar_position: 11
 ---
 
 # Testing introduction

website/versioned_docs/version-v1.x/topup.md

@@ -2,7 +2,7 @@
 title: MACI Topup
 description: How the Topup feature works
 sidebar_label: Topup
-sidebar_position: 19
+sidebar_position: 22
 ---
 
 # Topup

website/versioned_docs/version-v1.x/troubleshooting.md

@@ -2,7 +2,7 @@
 title: Troubleshooting
 description: How to troubleshoot MACI's failures
 sidebar_label: Troubleshooting
-sidebar_position: 17
+sidebar_position: 19
 ---
 
 # Troubleshooting

website/versioned_docs/version-v1.x/trusted-setup.md

@@ -2,7 +2,7 @@
 title: MACI Trusted Setup
 description: Introduction to the MACI multi-party trusted setup
 sidebar_label: Trusted Setup
-sidebar_position: 8
+sidebar_position: 10
 ---
 
 # Trusted setup

website/versioned_docs/version-v1.x/versioning.md

@@ -2,7 +2,7 @@
 title: MACI versioning and release process
 description: How MACI's versioning and release process works
 sidebar_label: MACI versioning
-sidebar_position: 18
+sidebar_position: 20
 ---
 
 # MACI versioning and release process

website/versioned_docs/version-v1.x/workflow.md

@@ -2,7 +2,7 @@
 title: MACI Workflow
 description: Overview of the MACI workflow
 sidebar_label: Workflow
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 <!-- TODO: create flowcharts, similar to to Kyle's (but make light/dark mode compatible) -->