Merge upstream commits

.github/workflows/ci.yml

@@ -8,12 +8,10 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        # We don't need to test across multiple platforms yet
-        # os: [ubuntu-latest, windows-latest, macOS-latest]
-        os: [ubuntu-latest]
+        os: [ubuntu-latest, windows-latest, macOS-latest]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: actions-rs/toolchain@v1
         with:
           override: false
@@ -33,7 +31,7 @@ jobs:
           - wasm32-wasi
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: actions-rs/toolchain@v1
         with:
           override: false
@@ -50,7 +48,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: actions-rs/toolchain@v1
         with:
           override: false
@@ -66,7 +64,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       # Use stable for this to ensure that cargo-tarpaulin can be built.
       - uses: actions-rs/toolchain@v1
         with:
@@ -82,16 +80,14 @@ jobs:
           command: tarpaulin
           args: --all-features --timeout 600 --out Xml
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v1
-        with:
-          token: ${{secrets.CODECOV_TOKEN}}
+        uses: codecov/codecov-action@v3.1.0
 
   doc-links:
     name: Intra-doc links
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: actions-rs/toolchain@v1
         with:
           override: false
@@ -113,7 +109,7 @@ jobs:
     timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: actions-rs/toolchain@v1
         with:
           override: false

.github/workflows/lints-stable.yml

@@ -5,19 +5,19 @@ on: pull_request
 
 jobs:
   clippy:
-    name: Clippy (1.51.0)
+    name: Clippy (1.56.1)
     timeout-minutes: 30
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: actions-rs/toolchain@v1
         with:
           components: clippy
           override: false
       - name: Run clippy
         uses: actions-rs/clippy-check@v1
         with:
-          name: Clippy (1.51.0)
+          name: Clippy (1.56.1)
           token: ${{ secrets.GITHUB_TOKEN }}
           args: --all-features --all-targets -- -D warnings

.gitignore

@@ -3,3 +3,4 @@
 Cargo.lock
 .vscode
 **/*.html
+.DS_Store

COPYING.md

@@ -0,0 +1,16 @@
+# License
+
+Licensed under either of
+
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+# Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the Apache-2.0
+license, shall be dual licensed as above, without any additional terms or
+conditions.
+

README.md

@@ -1,12 +1,10 @@
 # halo2 [![Crates.io](https://img.shields.io/crates/v/halo2.svg)](https://crates.io/crates/halo2) #
 
-**IMPORTANT**: This library is in beta, and should not be used in production software.
-
 ## [Documentation](https://docs.rs/halo2)
 
 ## Minimum Supported Rust Version
 
-Requires Rust **1.51** or higher.
+Requires Rust **1.56.1** or higher.
 
 Minimum supported Rust version can be changed in the future, but it will be done with a
 minor version bump.
@@ -18,14 +16,17 @@ The `RAYON_NUM_THREADS` environment variable can be used to set the number of th
 
 ## License
 
-Copyright 2020-2021 The Electric Coin Company.
+Licensed under either of
+
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
 
-You may use this package under the Bootstrap Open Source Licence, version 1.0,
-or at your option, any later version. See the file [`COPYING`](COPYING) for
-more details, and [`LICENSE-BOSL`](LICENSE-BOSL) for the terms of the Bootstrap
-Open Source Licence, version 1.0.
+### Contribution
 
-The purpose of the BOSL is to allow commercial improvements to the package
-while ensuring that all improvements are open source. See
-[here](https://electriccoin.co/blog/introducing-tgppl-a-radically-new-type-of-open-source-license/)
-for why the BOSL exists.
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the Apache-2.0
+license, shall be dual licensed as above, without any additional terms or
+conditions.

book/macros.txt

@@ -20,6 +20,7 @@
 # Circuit constraint helper methods
 
 \BoolCheck:{\texttt{bool\_check}({#1})}
+\Ternary:{\texttt{ternary}({{#1}, {#2}, {#3}})}
 \RangeCheck:{\texttt{range\_check}({#1, #2})}
 \ShortLookupRangeCheck:{\texttt{short\_lookup\_range\_check}({#1})}
 
@@ -51,7 +52,7 @@
 \bottom:{\perp}
 \alg:{#1_\textnormal{alg}}
 \zero:{\mathcal{O}}
-\dlrel:{\mathsf{dl-rel}}
+\dlrel:{\textsf{dl-rel}}
 \game:{\mathsf{G}}
 \innerprod:{\langle{#1},{#2}\rangle}
 \dlgame:{\mathsf{G}^\dlrel_{\group,n}}
@@ -61,4 +62,15 @@
 \halo:{\textsf{Halo}}
 \lo:{\textnormal{lo}}
 \hi:{\textnormal{hi}}
-\protocol:{\halo}
+\protocol:{\halo}
+\extractwitness:{\textnormal{ExtractWitness}}
+\pfail:{p_\textnormal{fail}}
+\repr:\{\kern-0.1em {#1} \kern-0.1em\}^{#2}
+\rep:{\repr{#1}{}}
+\repv:{\repr{#1}{\mathbf{#2}}_{#3}}
+\dlreladv:{\mathcal{H}}
+\mr:{\mathcal{M}^{#1}_{#2}({#3})}
+\mv:{\mr{\mathbf{#1}}{#2}{#3}}
+\m:{\mr{#1}{}{#2}}
+\z:{\mathcal{Z}_{#1}({#2}, {#3})}
+\trprefix:{{#1}|_{#2}}

book/src/IDENTIFIERS.json

@@ -0,0 +1,25 @@
+{
+    "decompose-combined-lookup": "design/gadgets/decomposition.html#combined-lookup-expression",
+    "decompose-short-lookup": "design/gadgets/decomposition.html#short-range-check",
+    "decompose-short-range": "design/gadgets/decomposition.html#short-range-decomposition",
+    "ecc-complete-addition": "design/gadgets/ecc/addition.html#complete-addition-constraints",
+    "ecc-incomplete-addition": "design/gadgets/ecc/addition.html#incomplete-addition-constraints",
+    "ecc-fixed-mul-base-canonicity": "design/gadgets/ecc/fixed-base-scalar-mul.html#base-field-element",
+    "ecc-fixed-mul-coordinates": "design/gadgets/ecc/fixed-base-scalar-mul.html#constrain-coordinates",
+    "ecc-fixed-mul-full-word": "design/gadgets/ecc/fixed-base-scalar-mul.html#full-width-scalar",
+    "ecc-fixed-mul-load-base": "design/gadgets/ecc/fixed-base-scalar-mul.html#load-fixed-base",
+    "ecc-fixed-mul-short-msb": "design/gadgets/ecc/fixed-base-scalar-mul.html#constrain-short-signed-msb",
+    "ecc-fixed-mul-short-conditional-neg": "design/gadgets/ecc/fixed-base-scalar-mul.html#constrain-short-signed-conditional-neg",
+    "ecc-var-mul-complete-gate": "design/gadgets/ecc/var-base-scalar-mul.html#complete-gate",
+    "ecc-var-mul-incomplete-first-row": "design/gadgets/ecc/var-base-scalar-mul.html#incomplete-first-row-gate",
+    "ecc-var-mul-incomplete-last-row": "design/gadgets/ecc/var-base-scalar-mul.html#incomplete-last-row-gate",
+    "ecc-var-mul-incomplete-main-loop": "design/gadgets/ecc/var-base-scalar-mul.html#incomplete-main-loop-gate",
+    "ecc-var-mul-lsb-gate": "design/gadgets/ecc/var-base-scalar-mul.html#lsb-gate",
+    "ecc-var-mul-overflow": "design/gadgets/ecc/var-base-scalar-mul.html#overflow-check-constraints",
+    "ecc-var-mul-witness-scalar": "design/gadgets/ecc/var-base-scalar-mul.html#witness-scalar",
+    "ecc-witness-point": "design/gadgets/ecc/witnessing-points.html#points-including-the-identity",
+    "ecc-witness-non-identity-point": "design/gadgets/ecc/witnessing-points.html#non-identity-points",
+    "sinsemilla-constraints": "design/gadgets/sinsemilla.html#optimized-sinsemilla-gate",
+    "sinsemilla-merkle-crh-bit-lengths": "design/gadgets/sinsemilla/merkle-crh.html#bit-length-constraints",
+    "sinsemilla-merkle-crh-decomposition": "design/gadgets/sinsemilla/merkle-crh.html#decomposition-constraints"
+}

book/src/SUMMARY.md

@@ -25,8 +25,10 @@
   - [Implementation](design/implementation.md)
     - [Proofs](design/implementation/proofs.md)
     - [Fields](design/implementation/fields.md)
+    - [Selector combining](design/implementation/selector-combining.md)
   - [Gadgets](design/gadgets.md)
     - [Elliptic curve cryptography](design/gadgets/ecc.md)
+      - [Witnessing points](design/gadgets/ecc/witnessing-points.md)
       - [Incomplete and complete addition](design/gadgets/ecc/addition.md)
       - [Fixed-base scalar multiplication](design/gadgets/ecc/fixed-base-scalar-mul.md)
       - [Variable-base scalar multiplication](design/gadgets/ecc/var-base-scalar-mul.md)

book/src/background/curves.md

@@ -155,10 +155,10 @@ when adding two distinct points.
 ### Point addition
 We now add two points with distinct $x$-coordinates, $P = (x_0, y_0)$ and $Q = (x_1, y_1),$
 where $x_0 \neq x_1,$ to obtain $R = P + Q = (x_2, y_2).$ The line $\overline{PQ}$ has slope
-$$\lambda = frac{y_1 - y_0}{x_1 - x_0} \implies y - y_0 = \lambda \cdot (x - x_0).$$
+$$\lambda = \frac{y_1 - y_0}{x_1 - x_0} \implies y - y_0 = \lambda \cdot (x - x_0).$$
 
 Using the expression for $\overline{PQ}$, we compute $y$-coordinate $-y_2$ of $-R$ as:
-$$-y_2 - y_0 = \lambda \cdot (x_2 - x_0) \implies \boxed{y_2 = (x_0 - x_2) - y_0}.$$
+$$-y_2 - y_0 = \lambda \cdot (x_2 - x_0) \implies \boxed{y_2 =\lambda (x_0 - x_2) - y_0}.$$
 
 Plugging the expression for $\overline{PQ}$ into the curve equation $y^2 = x^3 + b$ yields
 $$
@@ -193,7 +193,7 @@ Important notes:
 Imagine that $\mathbb{F}_p$ has a primitive cube root of unity, or in other words that
 $3 | p - 1$ and so an element $\zeta_p$ generates a $3$-order multiplicative subgroup.
 Notice that a point $(x, y)$ on our example elliptic curve $y^2 = x^3 + b$ has two cousin
-points: $(\zeta_p x, \zeta_p^2 x)$, because the computation $x^3$ effectively kills the
+points: $(\zeta_p x,y), (\zeta_p^2 x,y)$, because the computation $x^3$ effectively kills the
 $\zeta$ component of the $x$-coordinate. Applying the map $(x, y) \mapsto (\zeta_p x, y)$
 is an application of an endomorphism over the curve. The exact mechanics involved are
 complicated, but when the curve has a prime $q$ number of points (and thus a prime

book/src/background/fields.md

@@ -248,7 +248,7 @@ odd, and so half of all elements are squares.
 In order to compute the square root, we can first raise the element
 $a = \alpha^i \cdot  \beta^j$ to the power $t$ to "kill" the $t$-order component, giving
 
-$$a^t = \alpha^{it \pmod 2^k} \cdot \beta^{jt \pmod t} = \alpha^{it \pmod 2^k}$$
+$$a^t = \alpha^{it \pmod {2^k}} \cdot \beta^{jt \pmod t} = \alpha^{it \pmod {2^k}}$$
 
 and then raise this result to the power $t^{-1} \pmod{2^k}$ to undo the effect of the
 original exponentiation on the $2^k$-order component:

book/src/background/groups.md

@@ -36,14 +36,14 @@ Assuming the discrete log assumption holds, Pedersen commitments are also perfec
 and computationally binding:
 
 * **hiding**: the adversary chooses messages $m_0, m_1.$ The committer commits to one of
-  these messages $c = \text{Commit}(m_b;r), b \in \{0,1\}.$ Given $c,$ the probability of
+  these messages $c = \text{Commit}(m_b,r), b \in \{0,1\}.$ Given $c,$ the probability of
   the adversary guessing the correct $b$ is no more than $\frac{1}{2}$.
 * **binding**: the adversary cannot pick two different messages $m_0 \neq m_1,$ and
   randomness $r_0, r_1,$ such that $\text{Commit}(m_0,r_0) = \text{Commit}(m_1,r_1).$
 
 ### Vector Pedersen commitment
 We can use a variant of the Pedersen commitment scheme to commit to multiple messages at
-once, $\mathbf{m} = (m_1, \cdots, m_n)$. This time, we'll have to sample a corresponding
+once, $\mathbf{m} = (m_0, \cdots, m_{n-1})$. This time, we'll have to sample a corresponding
 number of random public generators $\mathbf{G} = (G_0, \cdots, G_{n-1}),$ along with a
 single random generator $H$ as before (for use in hiding). Then, our commitment scheme is:
 
@@ -57,10 +57,10 @@ $$
 
 > TODO: is this positionally binding?
 
-## Diffie--Hellman
+## Diffie–Hellman
 
-An example of a protocol that uses cryptographic groups is Diffie--Hellman key agreement
-[[DH1976]]. The Diffie--Hellman protocol is a method for two users, Alice and Bob, to
+An example of a protocol that uses cryptographic groups is Diffie–Hellman key agreement
+[[DH1976]]. The Diffie–Hellman protocol is a method for two users, Alice and Bob, to
 generate a shared private key. It proceeds as follows:
 
 1. Alice and Bob publicly agree on two prime numbers, $p$ and $G,$ where $p$ is large and
@@ -83,7 +83,7 @@ $g, p, A = [a]G,$ and $B = [b]G$: in other words, they would need to either get
 discrete logarithm $a$ from $A = [a]G$ or $b$ from $B = [b]G,$ which we assume to be
 computationally infeasible in $\mathbb{F}_p^\times.$
 
-More generally, protocols that use similar ideas to Diffie--Hellman are used throughout
+More generally, protocols that use similar ideas to Diffie–Hellman are used throughout
 cryptography. One way of instantiating a cryptographic group is as an
 [elliptic curve](curves.md). Before we go into detail on elliptic curves, we'll describe
 some algorithms that can be used for any group.

book/src/background/pc-ipa.md

@@ -53,7 +53,7 @@ $\mathbf{b}^{(k)} := \mathbf{b}.$ In each round $j = k, k-1, \cdots, 1$:
 $$
 \begin{aligned}
 L_j &= \langle\mathbf{a_{lo}^{(j)}}, \mathbf{G_{hi}^{(j)}}\rangle + [l_j]H + [\langle\mathbf{a_{lo}^{(j)}}, \mathbf{b_{hi}^{(j)}}\rangle] U\\
-R_j &= \langle\mathbf{a_{hi}^{(j)}}, \mathbf{G_{lo}^{(j)}}\rangle + [l_j]H + [\langle\mathbf{a_{hi}^{(j)}}, \mathbf{b_{lo}^{(j)}}\rangle] U\\
+R_j &= \langle\mathbf{a_{hi}^{(j)}}, \mathbf{G_{lo}^{(j)}}\rangle + [r_j]H + [\langle\mathbf{a_{hi}^{(j)}}, \mathbf{b_{lo}^{(j)}}\rangle] U\\
 \end{aligned}
 $$
 

book/src/background/polynomials.md

@@ -178,7 +178,7 @@ most points." Formally, it can be written as follows:
 
 > Let $p(x_1, x_2, \cdots, x_n)$ be a nonzero polynomial of $n$ variables with degree $d$.
 > Let $S$ be a finite set of numbers with at least $d$ elements in it. If we choose random
-> $\alpha_1, \alpha_1, \cdots, \alpha_n$ from $S$,
+> $\alpha_1, \alpha_2, \cdots, \alpha_n$ from $S$,
 > $$\text{Pr}[p(\alpha_1, \alpha_2, \cdots, \alpha_n) = 0] \leq \frac{d}{|S|}.$$
 
 In the familiar univariate case $p(X)$, this reduces to saying that a nonzero polynomial
@@ -279,7 +279,7 @@ we can reconstruct its coefficient form in the Lagrange basis:
 
 $$A(X) = \sum_{i = 0}^{n-1} A(x_i)\mathcal{L_i}(X), $$
 
-where $X \in \{x_0, x_1,\cdots, x_{1-n}\}.$
+where $X \in \{x_0, x_1,\cdots, x_{n-1}\}.$
 
 ## References
 [^master-thm]: [Dasgupta, S., Papadimitriou, C. H., & Vazirani, U. V. (2008). "Algorithms" (ch. 2). New York: McGraw-Hill Higher Education.](https://people.eecs.berkeley.edu/~vazirani/algorithms/chap2.pdf)

book/src/background/recursion.md

@@ -14,7 +14,7 @@ polynomial with degree $2^k - 1.$
 
 |  |  | 
 | -------- | -------- | 
-| <img src="https://i.imgur.com/vMXKFDV.png" width=1900> | Since $G$ is a commitment, it can be checked in an inner product argument. The verifier circuit witnesses $G$ and brings $G, u_1, \cdots, u_k$ out as public inputs to the proof $\pi.$ The next verifier instance checks $\pi$ using the inner product argument; this includes checking that $G = \text{Commit}(g(X, u_1, \cdots, u_k))$ evaluates at some random point to the expected value for the given challenges $u_1, \cdots, u_k.$ Recall from the [previous section](#Polynomial-commitment-using-inner-product-argument) that this check only requires $\log d$ work. <br><br> At the end of checking $\pi$ and $G,$ the circuit is left with a new $G',$ along with the $u_1', \cdots, u_k'$ challenges sampled for the check. To fully accept $\pi$ as valid, we should perform a linear-time computation of $G' = \langle\mathbf{G}, \mathbf{s}'\rangle$. Once again, we delay this computation by witnessing $G'$ and bringing $G, u_1, \cdots, u_k$ out as public inputs to the proof $\pi.$ <br><br> This goes on from one proof instance to the next, until we are satisfied with the size of our batch of proofs. We finally perform a single linear-time computation, thus deciding the validity of the whole batch.   |
+| <img src="https://i.imgur.com/vMXKFDV.png" width=1900> | Since $G$ is a commitment, it can be checked in an inner product argument. The verifier circuit witnesses $G$ and brings $G, u_1, \cdots, u_k$ out as public inputs to the proof $\pi.$ The next verifier instance checks $\pi$ using the inner product argument; this includes checking that $G = \text{Commit}(g(X, u_1, \cdots, u_k))$ evaluates at some random point to the expected value for the given challenges $u_1, \cdots, u_k.$ Recall from the [previous section](#Polynomial-commitment-using-inner-product-argument) that this check only requires $\log d$ work. <br><br> At the end of checking $\pi$ and $G,$ the circuit is left with a new $G',$ along with the $u_1', \cdots, u_k'$ challenges sampled for the check. To fully accept $\pi$ as valid, we should perform a linear-time computation of $G' = \langle\mathbf{G}, \mathbf{s}'\rangle$. Once again, we delay this computation by witnessing $G'$ and bringing $G', u_1', \cdots, u_k'$ out as public inputs to the proof $\pi'.$ <br><br> This goes on from one proof instance to the next, until we are satisfied with the size of our batch of proofs. We finally perform a single linear-time computation, thus deciding the validity of the whole batch.   |
 
 We recall from the section [Cycles of curves](curves.md#cycles-of-curves) that we can
 instantiate this protocol over a two-cycle, where a proof produced by one curve is