@maci-protocol/website 0.0.0-ci.da13fbb → 0.0.0-ci.de6bbd5

package/docusaurus.config.ts

@@ -204,9 +204,15 @@ async function getConfig(): Promise<Config> {
         phpLoader: "matomo.php",
         jsLoader: "matomo.js",
       },
+      mermaid: {
+        theme: { light: "neutral", dark: "forest" },
+      },
     } satisfies Preset.ThemeConfig,
+    markdown: {
+      mermaid: true,
+    },
+    themes: ["@docusaurus/theme-mermaid"],
   };
-
   return config;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maci-protocol/website",
-  "version": "0.0.0-ci.da13fbb",
+  "version": "0.0.0-ci.de6bbd5",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -25,7 +25,8 @@
     "@docusaurus/preset-classic": "^3.8.1",
     "@docusaurus/theme-classic": "^3.8.1",
     "@docusaurus/theme-common": "^3.8.1",
-    "@easyops-cn/docusaurus-search-local": "^0.51.0",
+    "@docusaurus/theme-mermaid": "^3.8.1",
+    "@easyops-cn/docusaurus-search-local": "^0.52.1",
     "@mdx-js/react": "^3.1.0",
     "clsx": "^2.1.1",
     "docusaurus-plugin-image-zoom": "^3.0.1",
@@ -41,7 +42,7 @@
     "@docusaurus/module-type-aliases": "^3.8.1",
     "@docusaurus/tsconfig": "^3.8.1",
     "@docusaurus/types": "^3.8.1",
-    "@types/node": "^22.15.17",
+    "@types/node": "^24.0.13",
     "@types/react": "^19.1.8",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3"
@@ -61,5 +62,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "d5c6bf10c4097b1d21e4f3c3e40df127a222696b"
+  "gitHead": "b1ed6c9c3a7dc3ca3081242d67438b96779c285a"
 }

package/versioned_docs/version-v0.x/introduction.md

@@ -41,9 +41,7 @@ Refer to the [Glossary](#glossary) for definitions of terms.
 3. The signup period ends after a fixed amount of time. From that point onwards, users may no longer invoke `signUp()` in this contract.
 
 4. Each user votes. To do this, they:
-
    - Sign their command using the key which they had signed up with and then use a random (ephemeral) key as well as the coordinator's public key to generate a shared key (via ECDH) encrypt it.
-
      - If they are bribed, the user should sign it using an old public key which has already been replaced with a new one.
 
      - Otherwise, the user should use the most current public key they have registered.
@@ -53,9 +51,7 @@ Refer to the [Glossary](#glossary) for definitions of terms.
 5. The coordinator processes all the commands after the voting period ends.
 
 6. For each batch of commands, they perform the following steps:
-
    - Generate a new state root which is the result of:
-
      - For each valid command, in reverse order, update the state leaf accordingly
 
      - Ignore all invalid commands

package/versioned_docs/version-v3.x/guides/sdk.md

@@ -0,0 +1,121 @@
+---
+title: MACI SDK
+description: How to use the MACI SDK
+sidebar_label: MACI SDK
+sidebar_position: 6
+---
+
+In this guide we will be looking at how to use the MACI SDK to interact with the MACI protocol.
+
+## Installation
+
+```bash
+npm install @maci-protocol/sdk
+```
+
+## Browser compatibility
+
+As the SDK imports functions from the `@maci-protocol/contracts` package which uses hardhat, certain functionality is not browser compatible.
+However, all it takes to use browser compatible functions is to import from `@maci-protocol/sdk/browser`.
+
+As an example, we can import the `signUp` function from the `@maci-protocol/sdk/browser` package.
+
+```typescript
+import { signUp } from "@maci-protocol/sdk/browser";
+```
+
+Let's take a look at an example of how to use the `joinPoll` function to register a user to a poll.
+
+### JoinPoll
+
+This step is required to register a user to a specific poll for which they want to vote. In short, it requires the user to generate a zk-SNARK proof that they know the private key to a public key registered to the MACI contract (proving they passed the initial gatekeeping requirements). This forces them to join with the same MACI key to each poll, greatly increasing the value of the key. Should they have been allowed to join with a throwaway key, they could simply sell their key for polls they do not care about.
+
+**How does the flow look like?**
+
+1. Reconstruct the MACI state tree by pulling all public keys from the MACI contract (events from RPC or from Subgraph)
+2. Generate a merkle tree inclusion proof for the user's public key
+3. Generate a zk-SNARK proof that the user knows the private key to the public key in the merkle tree inclusion proof
+4. Call the `joinPoll` function on the Poll smart contract
+
+**How to use the SDK for this?**
+
+> This example is browser specific, as it uses the `@maci-protocol/sdk/browser` package and WASM for witness generation
+
+Option 1: Use the `joinPoll` function from the `@maci-protocol/sdk/browser` package.
+
+1. Download the `pollJoining` zk artifacts using [downloadPollJoiningArtifactsBrowser](https://github.com/privacy-scaling-explorations/maci/blob/dev/packages/sdk/ts/proof/download.ts#L46)
+
+```typescript
+import { downloadPollJoiningArtifactsBrowser } from "@maci-protocol/sdk/browser";
+
+const artifacts = await downloadPollJoiningArtifactsBrowser({
+  testing: true,
+  stateTreeDepth: 10,
+});
+```
+
+2. Use the `joinPoll` function to join the poll
+
+```typescript
+import { joinPoll } from "@maci-protocol/sdk/browser";
+
+const joinedPollData = await joinPoll({
+  maciAddress: PUBLIC_MACI_ADDRESS,
+  privateKey: maciKeypair.privateKey.serialize(),
+  signer,
+  pollId,
+  inclusionProof,
+  pollJoiningZkey: artifacts.zKey as unknown as string,
+  pollWasm: artifacts.wasm as unknown as string,
+  sgDataArg: DEFAULT_SG_DATA,
+  ivcpDataArg: DEFAULT_IVCP_DATA,
+  blocksPerBatch: 1000,
+});
+```
+
+This is not really efficient, as we are using the user RPC to fetch events, which can be quite slow and prone to errors. A better approach is to use a Subgraph to fetch the events.
+
+Option 2: Fetch the MACI keys using a subgraph and reconstruct the state tree locally.
+
+1. Deploy the subgraph - instructions [here](/guides/subgraph)
+2. Fetch the MACI keys
+
+```typescript
+import { MaciSubgraph } from "@maci-protocol/sdk/browser";
+
+const subgraph = new MaciSubgraph("https://api.studio.thegraph.com/query/x/maci/version/latest");
+
+const keys = await subgraph.getKeys();
+```
+
+3. Generate the merkle tree
+
+```typescript
+import { generateSignUpTreeFromKeys } from "@maci-protocol/sdk/browser";
+
+const signUpTree = generateSignUpTreeFromKeys(keys);
+```
+
+4. Generate the inclusion proof - you will need to know the index of the user's public key in the merkle tree
+
+```typescript
+const inclusionProof = signUpTree.generateProof(publicKeyIndex);
+```
+
+5. Generate the zk-SNARK proof and join the poll
+
+```typescript
+import { joinPoll } from "@maci-protocol/sdk/browser";
+
+const joinedPollData = await joinPoll({
+  maciAddress: PUBLIC_MACI_ADDRESS,
+  privateKey: maciKeypair.privateKey.serialize(),
+  signer,
+  pollId,
+  inclusionProof,
+  pollJoiningZkey: artifacts.zKey as unknown as string,
+  pollWasm: artifacts.wasm as unknown as string,
+  sgDataArg: DEFAULT_SG_DATA,
+  ivcpDataArg: DEFAULT_IVCP_DATA,
+});
+```

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

@@ -19,7 +19,7 @@ The MACI smart contracts handle the on-chain aspects - both the functionality an
 
 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.
+Contracts are released through the [`@maci-protocol/contracts`](https://www.npmjs.com/package/@maci-protocol/contracts) NPM package.
 
 [Learn more about MACI contracts](/docs/technical-references/smart-contracts/)
 
@@ -29,12 +29,12 @@ The TypeScript libraries manage the business logic between the smart contracts a
 
 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)
+- [`@maci-protocol/cli`](https://www.npmjs.com/package/@maci-protocol/cli)
+- [`@maci-protocol/core`](https://www.npmjs.com/package/@maci-protocol/core)
+- [`@maci-protocol/crypto`](https://www.npmjs.com/package/@maci-protocol/crypto)
+- [`@maci-protocol/domainobjs`](https://www.npmjs.com/package/@maci-protocol/domainobjs)
+- [`@maci-protocol/integrationtests`](https://www.npmjs.com/package/@maci-protocol/integrationtests)
+- [`@maci-protocol/sdk`](https://www.npmjs.com/package/@maci-protocol/sdk)
 
 ## Circuits
 
@@ -43,6 +43,6 @@ MACI has multiple circuits that ensure all off-chain computation is completed co
 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.
+The MACI circuits are released through the [`@maci-protocol/circuits`](https://www.npmjs.com/package/@maci-protocol/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/processMessages.md

@@ -18,7 +18,67 @@ The pre-requisites for this circuit are:
 
 This circuit requires the coordinator's private key, hence a proof for this circuit can only be generated by the coordinator. The private key is needed in order to generate the ECDH shared key used to decrypt the messages.
 
-![ProcessMessages](/img/circuits/processMessages_2_0.svg)
+```mermaid
+flowchart LR
+        parameters(["MessageProcessorQv - Parameters"])
+        parameters --> stateTreeDepth["stateTreeDepth"]
+        parameters --> batchSize["batchSize"]
+        parameters --> voteOptionTreeDepth["voteOptionTreeDepth"]
+
+        stateTreeDepth & batchSize & voteOptionTreeDepth --> publicInputs["Public inputs"]
+
+        subgraph publicInputs
+            direction LR
+            totalSignups ~~~ index
+            batchEndIndex ~~~ currentSbCommitment
+            newSbCommitment ~~~ outputBatchHash
+            actualStateTreeDepth ~~~ coordinatorPublicKeyHash
+            voteOptions
+        end
+
+        publicInputs --> privateInputs
+
+        subgraph privateInputs
+            direction LR
+            inputBatchHash ~~~ messages
+            coordinatorPrivateKey ~~~ encryptionPublicKeys
+            currentStateRoot ~~~ currentStateLeaves
+            currentStateLeavesPathElements ~~~ currentSbSalt
+            newSbSalt ~~~ currentBallotRoot
+            currentBallots ~~~ currentBallotsPathElements
+            currentVoteWeights ~~~ currentVoteWeightsPathElements
+        end
+
+        privateInputs --> step1["1 - Verify currentSbCommitment"]
+        step1 --> step1B["hash(currentStateRoot, currentBallotRoot, currentSbSalt)"]
+
+        privateInputs --> step2["2 – Check voteOptions upper-bound"]
+        step2 --> step2B["voteOptions <= 5 ** voteOptionTreeDepth"]
+
+        privateInputs --> step3["3 – Ensure totalSignups within capacity"]
+        step3 --> step3B["totalSignups <= 2 ** stateTreeDepth"]
+
+        privateInputs --> step4["4 – Hash each message + pub-key"]
+        step4 --> step4B["MessageHasher template loop"]
+
+        privateInputs --> step5["5 – Build and verify chainHash"]
+        step5 --> step5B["PoseidonHasher template loop + Mux1"]
+
+        privateInputs --> step6["6 – Derive & verify coordinator pubKey"]
+        step6 --> step6B["PrivateToPublicKey -> derivedPublicKeyHash == coordinatorPublicKeyHash"]
+
+        privateInputs --> step7["7 – Decrypt each message to a command using MessageToCommand"]
+        step7 --> step7B["MessageToCommand template loop"]
+
+        privateInputs --> step8["8 – Process messages in reverse order"]
+        step8 --> step8B["SingleMessageProcessorQv template loop"]
+
+        privateInputs --> step9["9 – Compute newSbCommitment"]
+        step9 --> step9B["hash(stateRoot, ballotRoot, newSbSalt)"]
+
+        privateInputs --> step10["10 – Verify provided newSbCommitment"]
+        step10 --> step10B["equality with computed commitment"]
+```
 
 :::info
 A version working with non quadratic voting (non-qv) is also [available](https://github.com/privacy-scaling-explorations/maci/blob/dev/circuits/circom/coordinator/non-qv/MessageProcessor.circom). This version is called `MessageProcessorNonQV` and is to be used when the Poll is not using the quadratic voting feature. Note that by default MACI works with quadratic voting.