Plonkathon repo setup

0xPARC · Jan 27, 2023 · 7399329 · 7399329
1 parent 4e7d282
commit 7399329
Show file tree

Hide file tree

Showing 24 changed files with 2,227 additions and 1,018 deletions.
diff --git a/README.md b/README.md
@@ -1,20 +1,32 @@
-# Py_plonk
+# PlonKathon
+**PlonKathon** is part of the program for [MIT IAP 2023] [Modern Zero Knowledge Cryptography](https://zkiap.com/). Over the course of this weekend, we will get into the weeds of the PlonK protocol through a series of exercises and extensions. This repository contains a simple python implementation of PlonK adapted from [py_plonk](https://github.com/ethereum/research/tree/master/py_plonk), and targeted to be close to compatible with the implementation at https://zkrepl.dev.
 
-Py_plonk is a simple python implementation of the PLONK protocol as described in https://eprint.iacr.org/2019/953.pdf (see also https://vitalik.ca/general/2019/09/22/plonk.html), targeted to be close to compatible with the implementation at https://zkrepl.dev. Py_plonk includes:
+### Exercises
+#### Prover
+1. Implement Round 1 of the PlonK prover
+2. Implement Round 2 of the PlonK prover
+3. Implement Round 3 of the PlonK prover
+4. Implement Round 4 of the PlonK prover
+5. Implement Round 5 of the PlonK prover
 
-* A simple programming language for describing circuits, which it can compile into the forms needed for a PLONK proof (QL, QR, QM, QO, QC, S1, S2, S3 polynomials)
-* A prover that can generate proofs for this language, given a list of variable assignments
-* A verifier that can verify these proofs
+### Extensions
+1. Add support for custom gates.
+[TurboPlonK](https://docs.zkproof.org/pages/standards/accepted-workshop3/proposal-turbo_plonk.pdf) introduced support for custom constraints, beyond the addition and multiplication gates supported here. Try to generalise this implementation to allow circuit writers to define custom constraints.
+2. Add zero-knowledge.
+The parts of PlonK that are responsible for ensuring strong privacy are left out of this implementation. See if you can identify them in the [original paper](https://eprint.iacr.org/2019/953.pdf) and add them here.
+3. Add support for lookups.
+A lookup argument allows us to prove that a certain element can be found in a public lookup table. [PlonKup](https://eprint.iacr.org/2022/086.pdf) introduces lookup arguments to PlonK. Try to understand the construction in the paper and implement it here.
 
-Full compatibility is achieved in some cases: for simple programs, py_plonk is capable of outputting verification keys that _exactly_ match https://zkrepl.dev output. See the tests in test.py for some examples.
+## Getting started
 
-This implementation is intended for educational use, and to help reproduce and verify verification keys that are generated by other software. **IT HAS NOT BEEN AUDITED AND PROBABLY HAS BUGS, DO NOT USE BY ITSELF IN PRODUCTION.**
+To get started, you'll need to have a Python version >= 3.8 and [`poetry`](https://python-poetry.org) installed: `curl -sSL https://install.python-poetry.org | python3 -`.
 
-Many features are missing. The parts of PLONK that are responsible for ensuring strong privacy are left out (they are easy to add, they would simply increase complexity and reduce the educational value of this implementation).
+Then, run `poetry install` in the root of the repository. This will install all the dependencies in a virtualenv.
 
-### Example
-
-Here is a program that lets you prove that you know two small numbers that multiply to a given number (in our example we'll use 91) without revealing what those numbers are:
+Then, to see the proof system in action, run `poetry run python test.py` from the root of the repository. This will take you through the workflow of setup, proof generation, and verification for several example programs.
+### Compiler
+#### Program
+We specify our program logic in a high-level language involving constraints and variable assignments. Here is a program that lets you prove that you know two small numbers that multiply to a given number (in our example we'll use 91) without revealing what those numbers are:
 
 ```
 n public
@@ -35,31 +47,208 @@ q <== qb012 + 8 * qb3
 n <== p * q
 ```
 
-Generating the verification key:
+Examples of valid program constraints:
+- `a === 9`
+- `b <== a * c`
+- `d <== a * c - 45 * a + 987`
+
+Examples of invalid program constraints:
+- `7 === 7` (can't assign to non-variable)
+- `a <== b * * c` (two multiplications in a row)
+- `e <== a + b * c * d` (multiplicative degree > 2)
+
+Given a `Program`, we can derive the `CommonPreprocessedInput`, which are the polynomials representing the fixed constraints of the program. The prover later uses these polynomials to construct the quotient polynomial, and to compute their evaluations at a given challenge point.
+
+```python
+@dataclass
+class CommonPreprocessedInput:
+    """Common preprocessed input"""
+
+    group_order: int
+    # q_M(X) multiplication selector polynomial
+    QM: list[Scalar]
+    # q_L(X) left selector polynomial
+    QL: list[Scalar]
+    # q_R(X) right selector polynomial
+    QR: list[Scalar]
+    # q_O(X) output selector polynomial
+    QO: list[Scalar]
+    # q_C(X) constants selector polynomial
+    QC: list[Scalar]
+    # S_σ1(X) first permutation polynomial S_σ1(X)
+    S1: list[Scalar]
+    # S_σ2(X) second permutation polynomial S_σ2(X)
+    S2: list[Scalar]
+    # S_σ3(X) third permutation polynomial S_σ3(X)
+    S3: list[Scalar]
+```
+
+#### Assembly
+Our "assembly" language consists of `AssemblyEqn`s:
 
+```python
+class AssemblyEqn:
+    """Assembly equation mapping wires to coefficients."""
+    wires: GateWires
+    coeffs: dict[Optional[str], int]
 ```
-setup = utils.Setup.from_file(SETUP_FILENAME)
-vk = make_verification_key(setup, 16, string_containing_the_above_code)
+
+where:
+```python
+@dataclass
+class GateWires:
+    """Variable names for Left, Right, and Output wires."""
+    L: Optional[str]
+    R: Optional[str]
+    O: Optional[str]
+```
+
+Examples of valid program constraints, and corresponding assembly:
+| program constraint         | assembly                                         |
+| -------------------------- | ------------------------------------------------ |
+| a === 9                    | ([None, None, 'a'], {'': 9})                     |
+| b <== a * c                | (['a', 'c', 'b'], {'a*c': 1})                    |
+| d <== a * c - 45 * a + 987 | (['a', 'c', 'd'], {'a*c': 1, 'a': -45, '': 987}) |
+
+
+### Setup
+Let $\mathbb{G}_1$ and $\mathbb{G}_2$ be two elliptic curves with a pairing $e : \mathbb{G}_1 \times \mathbb{G}_2 \rightarrow \mathbb{G}_T$. Let $p$ be the order of $\mathbb{G}_1$ and $\mathbb{G}_2$, and $G$ and $H$ be generators of $\mathbb{G}_1$ and $\mathbb{G}_2$. We will use the shorthand notation
+
+$$[x]_1 = xG \in \mathbb{G}_1 \text{ and } [x]_2 = xH \in \mathbb{G}_2$$
+
+for any $x \in \mathbb{F}_p$.
+
+The trusted setup is a preprocessing step that produces a structured reference string:
+$$\mathsf{srs} = ([1]_1, [x]_1, \cdots, [x^{d-1}]_1, [x]_2),$$
+where:
+- $x \in \mathbb{F}$ is a randomly chosen, **secret** evaluation point; and
+- $d$ is the size of the trusted setup, corresponding to the maximum degree polynomial that it can support.
+
+```python
+@dataclass
+class Setup(object):
+    #   ([1]₁, [x]₁, ..., [x^{d-1}]₁)
+    # = ( G,    xG,  ...,  x^{d-1}G ), where G is a generator of G_2
+    powers_of_x: list[G1Point]
+    # [x]₂ = xH, where H is a generator of G_2
+    X2: G2Point
 ```
 
-A setup file is in this repo. The second argument is the group order; it should be a power of two, at least 8, and at least the number of lines of code in the program.
+In this repository, we are using the pairing-friendly [BN254 curve](https://hackmd.io/@jpw/bn254), where:
+- `p = 21888242871839275222246405745257275088696311157297823662689037894645226208583`
+- $\mathbb{G}_1$ is the curve $y^2 = x^3 + 3$ over $\mathbb{F}_p$;
+- $\mathbb{G}_2$ is the twisted curve $y^2 = x^3 + 3/(9+u)$ over $\mathbb{F}_{p^2}$; and
+- $\mathbb{G}_T = {\mu}_r \subset \mathbb{F}_{p^{12}}^{\times}$.
+
+We are using an existing setup for $d = 2^{11}$, from this [ceremony](https://github.com/iden3/snarkjs/blob/master/README.md). You can find out more about trusted setup ceremonies [here](https://github.com/weijiekoh/perpetualpowersoftau).
 
-Proving:
+### Prover
+The prover creates a proof of knowledge of some satisfying witness to a program.
 
+```python
+@dataclass
+class Prover:
+    group_order: int
+    setup: Setup
+    program: Program
+    pk: CommonPreprocessedInput
 ```
-assignments = compiler.fill_variable_assignments(eqs, {
-    'pb3': 1, 'pb2': 1, 'pb1': 0, 'pb0': 1,
-    'qb3': 0, 'qb2': 1, 'qb1': 1, 'qb0': 1,
-})
-proof = prover.prove_from_witness(setup, 16, eqs, assignments)
+
+The prover progresses in five rounds, and produces a message at the end of each. After each round, the message is hashed into the `Transcript`.
+
+The `Proof` consists of all the round messages (`Message1`, `Message2`, `Message3`, `Message4`, `Message5`).
+
+#### Round 1
+```python
+def round_1(
+    self,
+    witness: dict[Optional[str], int],
+) -> Message1
+
+@dataclass
+class Message1:
+    # - [a(x)]₁ (commitment to left wire polynomial)
+    a_1: G1Point
+    # - [b(x)]₁ (commitment to right wire polynomial)
+    b_1: G1Point
+    # - [c(x)]₁ (commitment to output wire polynomial)
+    c_1: G1Point
 ```
 
-`compiler.fill_variable_assignments` is a convenience method that executes the program to fill in any variables that you do not specify yourself. In this case, you only specify the bits of the two factors (7 and 13), the program can compute all the other intermediate and final variables for you.
+#### Round 2
+```python
+def round_2(self) -> Message2
 
-`prove_from_witness` generates a proof, passing in the full set of assignments as input.
+@dataclass
+class Message2:
+    # [z(x)]₁ (commitment to permutation polynomial)
+    z_1: G1Point
+```
 
-Verifying:
+#### Round 3
+```python
+def round_3(self) -> Message3
+
+@dataclass
+class Message3:
+    # [t_lo(x)]₁ (commitment to t_lo(X), the low chunk of the quotient polynomial t(X))
+    t_lo_1: G1Point
+    # [t_mid(x)]₁ (commitment to t_mid(X), the middle chunk of the quotient polynomial t(X))
+    t_mid_1: G1Point
+    # [t_hi(x)]₁ (commitment to t_hi(X), the high chunk of the quotient polynomial t(X))
+    t_hi_1: G1Point
+```
 
+#### Round 4
+```python
+def round_4(self) -> Message4
+
+@dataclass
+class Message4:
+    # Evaluation of a(X) at evaluation challenge ζ
+    a_eval: Scalar
+    # Evaluation of b(X) at evaluation challenge ζ
+    b_eval: Scalar
+    # Evaluation of c(X) at evaluation challenge ζ
+    c_eval: Scalar
+    # Evaluation of the first permutation polynomial S_σ1(X) at evaluation challenge ζ
+    s1_eval: Scalar
+    # Evaluation of the second permutation polynomial S_σ2(X) at evaluation challenge ζ
+    s2_eval: Scalar
+    # Evaluation of the shifted permutation polynomial z(X) at the shifted evaluation challenge ζω
+    z_shifted_eval: Scalar
 ```
-assert verifier.verify_proof(setup, 16, vk, proof, [91], optimized=True)
+
+#### Round 5
+```python
+def round_5(self) -> Message5
+
+@dataclass
+class Message5:
+    # [W_ζ(X)]₁ (commitment to the opening proof polynomial)
+    W_z_1: G1Point
+    # [W_ζω(X)]₁ (commitment to the opening proof polynomial)
+    W_zw_1: G1Point
 ```
+
+### Verifier
+Given a `Setup` and a `Program`, we can generate a verification key for the program:
+
+```python
+def verification_key(self, pk: CommonPreprocessedInput) -> VerificationKey
+```
+
+The `VerificationKey` contains:
+
+| verification key element | remark                                                           |
+| ------------------------ | ---------------------------------------------------------------- |
+| $[q_M(x)]_1$             | commitment to multiplication selector polynomial                 |
+| $[q_L(x)]_1$             | commitment to left selector polynomial                           |
+| $[q_R(x)]_1$             | commitment to right selector polynomial                          |
+| $[q_O(x)]_1$             | commitment to output selector polynomial                         |
+| $[q_C(x)]_1$             | commitment to constants selector polynomial                      |
+| $[S_{\sigma1}(x)]_1$     | commitment to the first permutation polynomial $S_{\sigma1}(X)$  |
+| $[S_{\sigma2}(x)]_1$     | commitment to the second permutation polynomial $S_{\sigma2}(X)$ |
+| $[S_{\sigma3}(x)]_1$     | commitment to the third permutation polynomial $S_{\sigma3}(X)$  |
+| $[x]_2 = xH$             | (from the $\mathsf{srs}$)                                        |
+| $\omega$                 | an $n$-th root of unity, where $n$ is the program's group order.  |
diff --git a/__init__.py b/__init__.py