refactor

Author: mhchia

docs/architecture.md

@@ -4,51 +4,49 @@ sidebar_position: 2
 
 # Architecture
 
-We use a client-server architecture, where there are 3 parties running all the time while data providers and consumers serve clients, i.e. data providers can go offline after providing their data and data consumers can go offline after querying the results.
+We use a client-server architecture where data providers and consumers delegate MPC computations to three long-running computation parties. This setup balances user experience and data security, allowing participants to submit data without staying online during computation while ensuring privacy through non-colluding servers.
 
-The core components are:
+## Components
 
-- **Coordination Server**: provides API for data providers and consumers to interact with, and coordinates computation sessions between computation parties.
-  - Verifies TLSNotary proof and prevents Sybil attacks.
-  - Implements rate-limiting to prevent DoS attacks.
-- **Computation Parties**:
-  - Store secret-shared data received from data providers.
-  - Perform MPC computations defined in DSL
+- **Coordination Server**: Coordinates communication between data providers, data consumers, and computation parties.
+  - Implements basic congestion control, rate-limiting, and sybil prevention to maintain system robustness.
+  - Does not access or store plaintext data.
+- **Computation Parties (3 servers)**:
+  - Store encrypted data received from data providers.
+  - Perform statistical operations defined in MPC   while verifying the data matches TLSNotary proof.
   - Return results to data consumers.
   - Each party operates independently to ensure security.
-- **TLSNotary Server**: data providers prove their data using it.
-  - Modified from the original TLSNotary server so the proved data is a commitment instead of plaintext. Later in MPC program, we verify the commitment matches the data provider's data.
+- **TLSNotary Server**: Data providers use it to generate proofs confirming their data is authenticated from verified websites.
 - **(Optional) Client API**:
-  - It's essentially a data consumer, but it's a REST API service that periodically polls computation parties for results and caches them
-  - Provides a simple interface for end users to query statistical results without interacting with the coordination server (and thus triggering MPC computations)
+  - Acts as a data consumer by periodically polling computation parties for results and caches them.
+  - Offers a simple REST API for end users to query statistical results without directly interacting with the Coordination Server, preventing unnecessary MPC computations.
 
-## Workflow
+## System Workflow
 
 ### Data Proving and Sharing
 
 ![share-data](./share-data.png)
 
-1. Data providers prove their balance using the Notary Server and obtain a TLSNotary proof.
-2. Data providers submit the TLSNotary proof to the Coordination Server, signaling their intent to share data.
-3. The Coordination Server instructs computation parties to initiate an MPC session on designated ports and wait for data providers to connect.
-4. Data providers run a client to secret-share their balance with the computation parties.
-   - Computation parties verify if the secret-shared balance matches the one in the TLSNotary proof. If not, they reject the data provider.
+1. **Proof Generation**: Data providers use the TLSNotary Server to prove data authenticity.
+2. **Submission**: Data providers submit the TLSNotary proof to the Coordination Server, signaling their intent to share data. The Coordination Server instructs computation parties to initiate an MPC session on designated ports and wait for incoming data.
+3. **Data Sharing**: Data providers use a client to secret-share their data with the computation parties.
+   - Computation parties verify the secret-shared data against the TLSNotary proof. Invalid submissions are rejected. Otherwise, store the secret-shared data.
 
 ### Query Computation
 
 ![query-computation](./query-result.png)
 
-1. Data consumers submit a query to the Coordination Server, requesting aggregated statistics.
-2. The Coordination Server instructs computation parties to perform MPC on the shared data.
-3. Data consumers retrieve the statistical results from the computation parties through the client interface.
+1. **Query Submission**: Data consumers send a query to the Coordination Server to request aggregated statistics.
+2. **Computation Trigger**: The Coordination Server instructs computation parties to perform MPC on all submitted encrypted data.
+3. **Result Retrieval**: Data consumers obtain the statistical results from computation parties through the client interface.
 
 ## Security Considerations
 
-- Coordination Server:
+- **Coordination Server**:
   - Centralized to streamline coordination but does not access or store plaintext data.
   - Rate-limiting and participant verification reduce the risk of Sybil attacks and DoS.
     - In Binance case, we expose a field "uid" in the TLSNotary proof, which is a unique identifier for each data provider. This way we prevent Sybil attacks by checking if the uid is unique.
-- Notary Server:
+- **Notary Server**:
   - Participants trust the Notary Server to generate a correct proof.
-  - By default, we use a local notary whose private keys are exposed, so it's possible for people to forge it. Running a remote notary server can mitigate this risk.
-- Computation Parties: Computation parties must be operated by non-colluding entities to prevent reconstruction of participants' balances.
+  - By default, we use a local notary whose private keys are exposed, so it's possible for people to forge it. A trusted party running a remote notary server can mitigate this risk.
+- **Computation Parties**: Computation parties must be operated by non-colluding entities to prevent reconstruction of participants' balances.

docs/devcon-demo.png

@@ -0,0 +1,20 @@
+---
+sidebar_position: 3
+---
+
+# Examples
+
+We have two examples to demonstrate different use cases, each maintained in a separate branch of the repository.
+
+## 1. Simple Example
+
+- **Branch:** [`simple`](https://github.com/ZKStats/mpc-demo-infra/tree/simple)
+
+Three participants prove and share their followers count on [page 0](https://jernkunpittaya.github.io/followers-page/party_0.html), [page 1](https://jernkunpittaya.github.io/followers-page/party_1.html), and [page 2](https://jernkunpittaya.github.io/followers-page/party_2.html), respectively. We then derive the statistics of all participants using MPC.
+
+## 2. Binance ETH Balance Example
+- **Branch:** [`main`](https://github.com/ZKStats/mpc-demo-infra/tree/main)
+
+This example was built for our [Devcon 2024 demo](https://pse-team.notion.site/MPCStats-Devcon-Demo-Report-3055bb69afd24d60bf8ee8d4fa5f774c). Participants can prove and share their Binance ETH balance in their spot account using the Binance API. We then derive the mean, median, max, and gini index of the balances of all participants, without revealing their individual balances.
+
+![devcon-demo](./devcon-demo.png)