From ed234e999d5a739958e3ac2ecfe5e3e53f06c17a Mon Sep 17 00:00:00 2001 From: Hein Dauven Date: Mon, 17 Jun 2024 20:26:18 +0200 Subject: [PATCH 1/5] Update lib.rs - Remove doc imports - Update badges with correct CI and look - Update Dusk use --- .github/CODE_OF_CONDUCT.md | 2 +- src/lib.rs | 30 ++++++++---------------------- 2 files changed, 9 insertions(+), 23 deletions(-) diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 0c2569f3..134d45fc 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -70,7 +70,7 @@ behavior is threatening or harassing, report it. We are dedicated to providing an environment where participants feel welcome and safe. Reports should be directed to Emanuele Francioni , the -Project Steward(s) for Dusk Network. It is the Project Steward’s duty to +Project Steward(s) for Dusk. It is the Project Steward’s duty to receive and address reported violations of the code of conduct. They will then work with a committee consisting of representatives from the Dusk Network BV team. If for any reason you are uncomfortable reaching out to the Project Steward, please email diff --git a/src/lib.rs b/src/lib.rs index 89ed518d..14e9178a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,18 +5,16 @@ // Copyright (c) DUSK NETWORK. All rights reserved. #![doc = include_str!("../README.md")] -#![doc( - html_logo_url = "https://lh3.googleusercontent.com/SmwswGxtgIANTbDrCOn5EKcRBnVdHjmYsHYxLq2HZNXWCQ9-fZyaea-bNgdX9eR0XGSqiMFi=w128-h128-e365" -)] -#![doc(html_favicon_url = "https://dusk.network/lib/img/favicon-16x16.png")] +#![doc(html_logo_url = "https://dusk.network/favicon.svg")] +#![doc(html_favicon_url = "https://dusk.network/favicon.png")] //! //! //! -//! -//! +//! +//! //! //! -//! GitHub issues +//! GitHub issues //! //! //! GitHub @@ -31,9 +29,9 @@ //! - Zachary J. Williamson (Aztec Protocol) //! - Oana Ciobotaru //! -//! This crate contains a pure-rust implementation done by the [DuskNetwork -//! team](dusk.network) of this algorithm using as a reference implementation -//! this one done by the creators of the protocol: +//! This crate contains a pure-rust implementation done by the +//! [Dusk team](dusk.network) of this algorithm using as a reference +//! implementation this one done by the creators of the protocol: //! //! @@ -79,16 +77,4 @@ mod error; mod fft; mod proof_system; -#[doc = include_str!("../docs/notes-intro.md")] -pub mod notes { - #[doc = include_str!("../docs/notes-commitments.md")] - pub mod commitment_schemes {} - #[doc = include_str!("../docs/notes-snark.md")] - pub mod snark_construction {} - #[doc = include_str!("../docs/notes-prove-verify.md")] - pub mod prove_verify {} - #[doc = include_str!("../docs/notes-KZG10.md")] - pub mod kzg10_docs {} -} - pub mod prelude; From 3dd369dfb1ebe3c367579b8f8e73749253f6ee63 Mon Sep 17 00:00:00 2001 From: Hein Dauven Date: Mon, 17 Jun 2024 20:50:19 +0200 Subject: [PATCH 2/5] Remove docs --- docs/notes-KZG10.md | 83 -------- docs/notes-commitments.md | 140 ------------- docs/notes-intro.md | 20 -- docs/notes-prove-verify.md | 393 ------------------------------------- docs/notes-snark.md | 256 ------------------------ 5 files changed, 892 deletions(-) delete mode 100644 docs/notes-KZG10.md delete mode 100644 docs/notes-commitments.md delete mode 100644 docs/notes-intro.md delete mode 100644 docs/notes-prove-verify.md delete mode 100644 docs/notes-snark.md diff --git a/docs/notes-KZG10.md b/docs/notes-KZG10.md deleted file mode 100644 index c56025b9..00000000 --- a/docs/notes-KZG10.md +++ /dev/null @@ -1,83 +0,0 @@ -In this module we show how, and why, the KZG10 -polynomial commitment scheme has been implemented -for this PLONK implementation. - -KZG10 Commitments -================== - -PLONK can be constructed with different -commitment schemes and does not requre solely -homomorphic commitments. However, this library -implements only homomorphic commitments for two -reasons. One is their useful properties when -given encrypted values, and the second is the -requirements of the linearisation technique in -PLONK. - -PLONK makes use of the linearisation technique, -originally conceived in the SONIC [paper][sonic_paper]. -This technique requires the -the commitment scheme to be homomorphic. -The use of this lineariser in the PLONK -protocol prevents us from being able to -use merkle tree like techniques, such as -the [FRI][fri_paper] protocol. - - - -We use 'KZG10 commitments', often called 'Kate' -commitments refers to the commitments scheme -created by Kate, Zaverucha and Goldberg. -A deep explanation on how this particular commitment -scheme operates can be found [here][kzg10_paper] -in the original paper. -Aside from the compatibility wiht the chosen -linearisation technique, there are multiple -benefits of using the KZG10 commitment scheme -in the PLONK. The first is that it allow -us to have constant size commitments; the witness -of the evaluations is a single group element. -The cost of these commitments is also constant -irrespective of the number of evaluations, -so we are able to employ them with a low overhead cost. - - - - - -This commitment is used to commit to a polynomial, -from a given structured reference string (SRS), -\\(\varPhi\\), by means of a bilinear pairing group. -Where \\({\mathbb G\_{1}}\\) and \\({\mathbb G\_{2}}\\) and groups -two different pairing curves with generators \\({\mathbf g\_{1}} -\in {\mathbb G\_{1}}\\) and \\({\mathbf g\_{2}} -\in {\mathbb G\_{2}}\\). - -These commitments are homomorphic, which enables us -to perform operations on the already encrypted values -and have the evaluation be indistinguishable from the -evaluation of operations performed on the decrypted values. -In terms of Kate commitments, we are able to take two -commitment messages, \\({\mathbf m\_{1}}\\) and \\({\mathbf m\_{2}}\\), -and know there is an efficient product operation -for them both which equates to a commitment - \\({(\mathbf m\_{1}}, {\mathbf m\_{2}})\\). -For example: -\\[ -\begin{aligned} -\operatorname{Commitment}({\mathbf{m}}\_{1}) -\cdot -\operatorname{Commitment}({\mathbf{m}}\_{2}) -\equiv -{\mathbf{m}}\_{1} -\bigotimes -{\mathbf{m}}\_{2} -\end{aligned} -\\] - - - - -[sonic_paper]:https://eprint.iacr.org/2019/099.pdf -[fri_paper]:https://drops.dagstuhl.de/opus/volltexte/2018/9018/pdf/LIPIcs-ICALP-2018-14.pdf -[kzg10_paper]:https://www.iacr.org/archive/asiacrypt2010/6477178/6477178.pdf \ No newline at end of file diff --git a/docs/notes-commitments.md b/docs/notes-commitments.md deleted file mode 100644 index e346a536..00000000 --- a/docs/notes-commitments.md +++ /dev/null @@ -1,140 +0,0 @@ -This module explains the inner workings of -commitment schemes. - -Commitment schemes -=================== - -To employ a commitment scheme, is simply to select a value -from a finite set and commit to the value such that the -new 'committed' value cannot be changed. -Commitment schemes are used in cryptography, -oft in conjunction with zero knowlegde proofs to -allow a prover to commit to a polynomial, with values -represented by a short reference string. This is -then used by verifiers to confirm or deny the claims -made by the orginal committing party. With this process, -the commitment, which the committer publishes, is bound, -meaning it cannot be changed. This process is called *binding*. -Additionally, the prover is able to make this commitment -without revealing it - this is called *hiding*. After -the commitment has been made, a prover is able to -reveal the committed message to a verifier so that -the message can be compared, for consistency, with the -commitment. - - -*Generic Example* - -In a game of players P and V: - -1. \\(P\\) writes down message \\(b\\) on a piece of paper -2. \\(P\\) places the message in a box and locks it using a padlock -3. \\(P\\) gives the locked box and key to \\(V\\) - -From the above game, it can be that \\(V\\) is able to -open the box, and see the committed message. \\(P\\) is -unable to change the value after giving the -box to \\(V\\), thus the message is *binding*. As \\(V\\) -is unable to see the commitment prior to opening -the box, the commitment is also *hiding*. - -Commitment schemes are defined by a \\(P\\) time -public key *pk* generation algorithm \\(G\\). The -input is \\(1^{l}\\), where \\({\mathbb l}\\) is the security parameter -that directly relates to the length of the string. -There is an outputted *pk*, which is the public key -of the commitment scheme. In practice, the protocol -is ran like this: - -1. \\(P\\) or \\(V\\) executes \\(G\\) to return *pk*, as a string, -and sends it to the other party. -2. To make the commitment, the recieving party calculates -a random *r* from \\(({0,1})^{l}\\) and computes the commitment, -\\(C\\): - -\\[ -\begin{aligned} -\operatorname{Commitment}(b,r) -\end{aligned} -\\] - - -3. The commitment is opened, meaning \\(b\\) & \\(r\\) are revealed and -\\(V\\) checks that the commitment, \\(C\\), satisfies: -\\[ -\begin{aligned} -\operatorname{Commitment}(b,r) -\end{aligned} -\\] - -The property of having either \\(P\\) *or* \\(V\\) running the -algorithm affects the type of commitment scheme and the -satisfied requirements. With respect to the *hiding* and -*binding* properties, this commitment can be constructed -in two different ways. - -When \\(V\\) generates the public key and sends it to \\(P\\), -then the *binding* is computational and the *hiding* is -unconditional. The *computational binding* in this commitment -scheme, means the chance of being able to change the -commitment is negligible. The *unconditional hiding* -means that a commitment to b reveals no information about b. - -When \\(P\\) generates the public key and sends it to \\(V\\), then -the *binding* is unconditional and the *hiding* is computational. -The *unconditional binding* describes how \\(P\\) is unable to -change the commitment value after it has been commited to. -The *computational hiding* means the probability of \\(V\\) being -able to guess the commitment value is negligible. - - -Polynomial commitment schemes can be defined in the following way: - - - -Let \\({\mathbb G}\\) be a group of prime order *p*. -Let \\({\mathbb g}\\) and \\({\mathbb h}\\) be generators of \\({\mathbb G}\\), -such that: -\\[ -\begin{aligned} -{\mathbf{g}}, {\mathbf{h}} &\in {\mathbb G} -\end{aligned} -\\] - -Either \\({\mathbf g}\\) or \\({\mathbf h}\\) are used to produce -*pk*, which has a commitment appended to it by the committer. - -This commitment is equal to message \\({\mathbb m}\\), -where: -\\[ -\begin{aligned} -{\mathbf{m}} &\in\ {\mathbb Z\_{p}}, -\end{aligned} -\\] - -The commitment which is made once these variables are derived, is: - -\\[ -\begin{aligned} -\operatorname{Commitment}\_{pk}(b,r) = -{\mathbf{g}^{r}} -\cdot -{\mathbf{h}^{b}} -\end{aligned} -\\] - - - -The above equation is generic to using short strings, -as values, to commit to a polynomial and generate an evaluated -value. - - - - - - - - - - diff --git a/docs/notes-intro.md b/docs/notes-intro.md deleted file mode 100644 index fb606b1d..00000000 --- a/docs/notes-intro.md +++ /dev/null @@ -1,20 +0,0 @@ -This module is a self contained file which explains -how PLONK and its protocol components work in our library. - -Table of Contents -================= - -The following section explains the workings of PLONK components: -* [Commitment schemes](notes-commitments.md#commitment-schemes) -* [Proof construction components](notes-prove-verify.md#plonk-proof-construction) -* [Permutation polynomials](notes-prove-verify.md#lagrangian-polynomials) - - - -This section explains how elements of the aggregated PLONK protocol work -and some of the unique features in this library: - -* [Prover and Verify algorithms](prove_verify/index.html) -* [Unbalanced permutation arguments](unbalanced_perm_args/index.html) -* [KZG10 commitment scheme](kzg10_docs/index.html) - diff --git a/docs/notes-prove-verify.md b/docs/notes-prove-verify.md deleted file mode 100644 index 98c588ae..00000000 --- a/docs/notes-prove-verify.md +++ /dev/null @@ -1,393 +0,0 @@ -This module contains the notes on -how the prover algorithm is -constructed for PLONK. - -PLONK proof construction -======================== - -Following on from the generic -SNARK construction, -here we will give the set up -of a PLONK proof and show -which steps need to be satisfied -to utilize the protocol. - -First we will explain the -derivation and simplification -of the arithmetic circuits. - -PLONK uses both gate constraints -and copy constraints, to collect -like expressions. Using the same -example of: - -\\[ -\begin{aligned} -\mathbf{W}\_L -\cdot -\mathbf{W}\_R = -\mathbf{W}\_O, -\end{aligned} -\\] - -We can express multiples of the -same wires in or out of the same -gate, with the above equation. - -Thus we have 'ith' gates, so the -index from left or right across -the circuit is mitigated for -wires which are equal. - -For example, in the two equations: - -\\[ -\begin{aligned} -\mathbf{A}\_{1} -\circ -X -\cdot -\mathbf{B}\_{1} -\circ -X^2 -= \mathbf{C}\_{1} -\end{aligned} -\\] -and -\\[ -\begin{aligned} -\mathbf{A}\_{2} -\circ -X^2 -\cdot -\mathbf{B}\_{2} -\circ -X -= \mathbf{C}\_{2} -\end{aligned} -\\] - -We can state the equalities that: -\\[ -\begin{aligned} -\mathbf{A}\_{1} = \mathbf{B}\_{2} \\\\ -&\\\\ -\mathbf{B}\_{1} = \mathbf{A}\_{2} \\\\ -\end{aligned} -\\] - -These are examples of constraints -collected in PLONK. Which is done -the same for addition gates, except -the gate constrain satisfies: - -\\[ -\begin{aligned} -\mathbf{W}\_L + \mathbf{W}\_R = \mathbf{W}\_O -\end{aligned} -\\] - -PLONK also uses 'copy -constraints', which are used to -associate wires, which have -equality, from the entire circuit. -These constraints are checked -with a permutation argument. -In essence, this checks that -wires are not repeated by using -randomness given by the verifier. - -This process is better explained in -within the permutation section of -the notes. - -After the constraints -are made, they are formatted into a -system of numerical equations, -which in PLONK are reduced to a -small amount of polynomial -equations which are capable of -representing the constraints. -PLONK allows us to combine the -two gate equations by describing -their relationship relative to -the role in the circuit. -PLONK also has constants, which -are denoted as 'Q'. These -values will change for each -programme. The shape of -the circuit is defined by -these values. When they are -combined with the gate -equations, we get the -polynomial equation for -a reduced form as: - -\\[ -\\\\ \mathbf{L} = left -\\\\ \mathbf{R} = right -\\\\ \mathbf{O} = output -\\\\ \mathbf{M} = multiplication -\\\\ \mathbf{C} = constants -\\] - -\\[ -\mathbf{Q}\_L \cdot \mathbb{a}\_i + -\mathbf{Q}\_R \cdot \mathbb{b}\_i + -\mathbf{Q}\_0 \cdot \mathbb{c}\_i + -\mathbf{Q}\_M \cdot \mathbb{a}\_i\mathbb{b}\_i + -\mathbf{Q}\_C = 0 -\\] -This can be used for both -addition and multiplication -gates, where their values -can be provided by the user -depending on the circuit -composition. -For an addition gate, -we derive it as follows: - -\\[ -\begin{aligned} -\mathbf{Q}\_L = 1, -\mathbf{Q}\_R = 1, -\mathbf{Q}\_0 = -1, -\mathbf{Q}\_M = 0, -\mathbf{Q}\_C = 1 -\end{aligned} -\\] - -Which results in: -\\[ -\mathbb{a}\_{i} + -\mathbb{b}\_{i} - -\mathbb{c}\_{i} = 0 -\\] - -For a multiplication gate, -we derive it as follows: - -\\[ -\begin{aligned} -\mathbf{Q}\_L = 0, -\mathbf{Q}\_R = 0, -\mathbf{Q}\_0 = -1, -\mathbf{Q}\_M = 1, -\mathbf{Q}\_C = 0 -\end{aligned} -\\] - - -Which results in: -\\[ -\mathbb{a}\_{i} -\cdot -\mathbb{b}\_{i} - -\mathbb{c}\_{i} = 0 -\\] - -With this format, there is -a specific method used to -convert all the equations -into polynomial form. -Basically, in order to -bundle -these together, PLONK can -take sets of equations and -turn them into one single -equation over polynomials. -This is called the evaluation -form. We are then able to -use Lagrangian interpolation -to convert to coefficient form. -The only thing this interpolation -is doing, -is allowing us to evaluate a -functions over specific points, -for 'x' values, where the target -polynomial is equal to '1' or -'0'. - -With these specific bases, we -can derive the relation between -all sets of equations into one -single polynomial equation, -where we have a vector of inputs -to each gate type: -\\[ -\begin{aligned} -\mathbf{Q}\_L(x) \cdot a(x) + -\mathbf{Q}\_R(x) \cdot b(x) + -\mathbf{Q}\_0(x) \cdot c(x) + -\mathbf{Q}\_M(x) \cdot a(x)b(x) + -\mathbf{Q}\_C(x) = -0 -\end{aligned} -\\] - -The utility for this in PLONK, -as a univeral SNARK, is that -any operation or relationship -that holds with the inputted -vectors, will also hold over -the polynomial. - -In order to check this in PLONK, -a 'vanishing polynomial' is -introduced. Which is just a -polynomial equal to zero for -all the points we evaluate at. -So this means that the vectors -will be divisible by this vanishing -polynomial, if the expression we -check does indeed hold. - -To summarise what the PLONK -proof must satisfy: - -The generation of copy and -gate constraints where the -former are representative -of permuted wires. Generate -all of the polynomials to -be checked against the -vanishing polynomials. -Take all of the wire values -and convert them into three -polynomials, \\({\mathbf A}(z)\\), -\\({\mathbf B}(z)\\), -\\({\mathbf C}(z)\\). -Check the polynomials at -some random \\({\mathbf Z\_z}\\), by making -commitments and checking -the evaluation form. -Then commit all evalution -polynomials forms for the -verfier. - - - - - - - - - -Lagrangian polynomials -====================== - -The use of polynomials in the -PLONK proving scheme refers -to specific evaluation domains, -named Lagrangian polynomials, -based on interpolation of two -functions of particular group -elements. The following section -gives a more comprehensive -understanding to the way in -which these polynomials are -formed, given certain inputs. - - -Langrangian polynomials are -introduced as a means of -constructing continous -functions -from discrete data. With alternative -polynomial constructions, discrete -data sets can be approximated; -Langrangian polynomials, -however, -form a solution that fits data exactly. -This is achieved through *interpolation*, -which finds a linear combination of 'n' -inputted functions with respect to a -given data set which imposes 'n' -constraints and computes -an exact fitting solution. - -Linear Algebra dictates that the interpolation polynomial ought -to be formed from the system \\({\mathbf A}(x)\\) = -\\({\mathbf b}\\), -where \\({\mathbf b}\_i\\) = -\\({\mathbf y}\_i\\), i = 0,...,n -and the entries of -\\({\mathbf A}(x)\\) -are defined by \\({\mathbf a}\_{ij}\\) = -\\({\mathbf P}(x\_{i})\\), -and \\(i,j \in 0,....,n,\\) -Additionally, the used points for the -interpolation are -\\(x\_{0},x\_{1}...,x\_{n}\\), -from which the data points -\\(y\_{0},y\_{1}...,y\_{n}\\), are obtained, -and -\\({\mathbf P}\_j(x\_i) = x^{j}\\). -Where \\(i \in 0,1,...,n\\). The basis -\\(1,x,...,x^{n}\\) -of the space of polynomials, degree n+1 is called the *monomial -basis*, and the corresponding matrix A is called the *Vandermode -matrix* for the points \\(x\_{0},x\_{1}...,x\_{n}\\). - -*Langrangian interpolation*, however, has the matrix A, as the identity -matrix. -This stems from writing the interpolating polynomial as: - -\\[ -\begin{aligned} -\mathbf{p}\_n(x) = \sum_{j=0}^{n} y_i\mathbb{L}\_n,j(x) -\end{aligned} -\\] - - - - - The polynomials \\({\mathbb L}\_n\\) and - \\(j(x)\\) = 0,...,n are interpolations - of the points \\(x\_{0},x\_{1}...,x\_{n}\\). They are commonly called the -*Lagrangian polynomials*. -They are wriiten in the form: - -\\[ -\begin{aligned} -\mathbb{L}\_n,j(x) = -\prod_{m=0}^{k} -\frac{(x-x\_{m})} -{(x\_{j}-x\_{m})} -\end{aligned} -\\] - - the unique solution polynomial of degree 'n' that satisfies this -\\[ -\begin{aligned} -\mathbf{P}\_n(x\_j) -\end{aligned} -\\] - -where -\\[ -\begin{aligned} -i,j = \mathbb{f}(x\_j), \mathbb{j} = 0,1,...1,n -\end{aligned} -\\] - - This polynomial, \\({\mathbf P}\_n(x\_j)\\) - is called the *interpolating - polynomial* of \\(\mathbb{f}(x)\\). - - To understand these as an expanded product argument, it can be written as - - Given a set of k + 1 data points - -[data points](https://wikimedia.org/api/rest_v1/media/math/render/svg/5e4f064b4751bb32d87cc829aca1b2b2f38d4a6d) - -where no two -[x_j](https://wikimedia.org/api/rest_v1/media/math/render/svg/5db47cb3d2f9496205a17a6856c91c1d3d363ccd) are the same, -the interpolation polynomial in the Lagrange form is a linear combination - -[Lagrange polynomial](https://wikimedia.org/api/rest_v1/media/math/render/svg/d07f3378ff7718c345e5d3d4a57d3053190226a0) - -of Lagrange basis polynomials. -[Basis Polynomial](https://wikimedia.org/api/rest_v1/media/math/render/svg/6e2c3a2ab16a8723c0446de6a30da839198fb04b) - - diff --git a/docs/notes-snark.md b/docs/notes-snark.md deleted file mode 100644 index e4d4d82d..00000000 --- a/docs/notes-snark.md +++ /dev/null @@ -1,256 +0,0 @@ -This module contains the methodology of how -zk-SNARKS are constructed. - -SNARKs -===== -These notes will -show an abstraction on the construction -of SNARKs by showing the mathematical -steps involved. - -ZK-SNARK stands for Zero-Knowledge -Succinct Non-Interactive ARgument of -Knowledge. Implementing a SNARK -protocol allows us to prove that a -presented statement is true without -revealing anything other than the -statement itself. - -The type of SNARK we will focus on -will be one with a pre-processing -stage. This means that the inputs -to our SNARK system is an output -of a program. We will also show -how SNARKs satisfy the fundamental -properties of zero knowledge. Namely: -Completeness, Soundess and Zero -Knowledge. Completeness means that the -verifier is convinced that the claims -from the prover are true. Soundness -means that if the information is -false, then the prover cannot -convince the verifier otherwise. -Zero knowledge means that the -proof should reveal nothing -other than the statement or -claim itself. - -To construct their proofs, SNARKS -convert an arithmetic circuit into -an algebraic expression of polynomials. -The arithmetic circuit here, is a mapping, -performed by a system of -wires and gates, where the outputs -are inputs which have passed through -the circuit. The input for this is -standardly assumed to be a computer -program and those used in the zero -knowledge fields tend to have a large -number of operations. - -For SNARK circuits, the prover will -select gates, -e.g. - -*Multiplication gates* which are represented -with two input wires to the gate, -and one product wire, such that: - - -\\({\mathbb W\_{L}}\\) \\(\cdot\\) \\({\mathbb W\_{R}}\\) = \\({\mathbb W\_{O}}\\), - -Where: - -* \\({\mathbb W\_{L}}\\) is representative of the left input wire to the gate\ -* \\({\mathbb W\_{R}}\\) is representative of the right input wire to the gate -* \\({\mathbb W\_{O}}\\) is representative of the output wire of the gate - -The variables rely upon another -set of contraints when inside -the circuit. These are the gate -constants: \\({\mathbb a\_{L}}\\), \\({\mathbb a\_{R}}\\), \\({\mathbb a\_{O}}\\), - -Where: - -* \\({\mathbb a\_{L}}\\) is the left input to the gate -* \\({\mathbb a\_{R}}\\) is the right input to the gate -* \\({\mathbb a\_{O}}\\) is the output of the gate - -The wires values can be seen as -the weights to each of the inputs. - -They are constrained as: - -\\[ -\begin{aligned} -\mathbf{{W}}\_{L} \cdot \mathbf{a}\_{L} + -\mathbf{{W}}\_{R} \cdot \mathbf{a}\_{R} - -\mathbf{{W}}\_{O} \cdot \mathbf{a}\_{O} = -0 -\end{aligned} -\\] - -When a program is chosen, the operations -are expressed in terms of circuits, like -the one above. - -Many programmes and their computations -have a large range of operations, -so the number of these gates they -need to construct can be very -large. Therefore, we use a -technique called a 'Quadratic -Arithmetic Programme' (QAP) -, to bundle the constraints -together. For example, -many wires may be of the same -value and rather than -computing them differently -for each programme, they can -be collected together and -the constraint can be -checked at varying values. -This step involves checks for -the values at specified -indices. Additionally, the -index values that are being -checked at are not numbers, -but are instead polynomials. -This polynomial is computed -by the QAP from the input -vectors. This QAP is intended -to give the prover the necessary -'tools' to derive these polynomials -for a proof, from a given -arithmetic circuit. - -Following on from the example -above, we can show a QAP being -constructed from an 'n' number -of multiplication gates. The -inputs to the gates will be -a vector of polynomials, all -evaluated for indice value at -some polynomial of their reduced -form, \\({\mathbf Z\_p}\\), - -Let the left input polynomial be: - -\\[ -\begin{aligned} -\vec{A} = (A\_{i}(z))\_{i=0}^{n}\\\\ -\end{aligned} -\\] - -Let the right input polynomial be: - -\\\[ -\begin{aligned} -\vec{B} = (B\_{i}(z))\_{i=0}^{n}\\\\ -\end{aligned} -\\] - -Let the outputs polynomial be: - -\\[ -\begin{aligned} -\vec{C} = (C\_{i}(z))\_{i=0}^{n}\\\\ -\end{aligned} -\\] - -The coefficients of these -polynomials are inside -some [finite field][finite_field] -, which also contains the -polynomial \\({\mathbf Z\_z}\\). -As a result, it can be checked -that the \\({\mathbf Z\_z}\\) divides -the multiplication gates -polynomial. - - -This is done by first constructing the full polynomial: - -\\[ -\begin{aligned} -\mathbf{P}(z) = -\mathbf{A}(z) * -\mathbf{B}(z) - -\mathbf{C}(z) -\end{aligned} -\\] -When the above equation is -constructed by the prover, -the verifier can check claims -by checking the divisibility -of \\({\mathbf P}(z)\\) by - \\({\mathbf Z\_z}\\). This -\\({\mathbf Z\_z}\\) polynomial is -often referred to as the -'target polynomial'. The -added benefit of having this -checked in polynomial form, -is that even with large -polynomials, the identity -between the two will hold -at most points if the identity -holds between the polynomials. -Which means that the check between -the two can be performed at -randomly chosen points to -verify the proof. - -In order to turn a given QAP -into a zk-SNARK, a prover must -rely upon a third party. Which -is more commonly known as 'a -trusted set up'. The trusted -set up constructs the polynomial -\\({\mathbf Z\_z}\\). The prover then -commits the vector values along -with their secret input, known as -the *witness*, to the equation -\\({\mathbf P}(z)\\) = -\\({\mathbf A}(z)\\) * -\\({\mathbf B}(z)\\) - -\\({\mathbf C}(z)\\) - -Then, the prover completes the -divisibility check between \\({\mathbf P}(z)\\) -and \\({\mathbf Z\_z}\\). This way, the -verifier can be sure that the -prover knows the *witness* value. - -The inner workings of the SNARK -also contain a 'bilinear pairing', -which is referring to the fields -which are used throughout the -protocol. However, in detail -explanations of these are out -of scope for these docs, more -information on the role pairing -cryptography has within SNARK -construction can be found [here][pairings]. - - - - - - - - - - -[finite_field]: https://web.stanford.edu/class/ee392d/Chap7.pdf -[pairings]:https://eprint.iacr.org/2016/260.pdf - - - - - - - - - - - From aab1bc2b3055ba6d0d724e40f05ea6382856de97 Mon Sep 17 00:00:00 2001 From: Hein Dauven Date: Mon, 17 Jun 2024 20:52:49 +0200 Subject: [PATCH 3/5] Remove code of conduct, falls back to org CoC --- .github/CODE_OF_CONDUCT.md | 92 -------------------------------------- 1 file changed, 92 deletions(-) delete mode 100644 .github/CODE_OF_CONDUCT.md diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md deleted file mode 100644 index 134d45fc..00000000 --- a/.github/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,92 +0,0 @@ -# Code of Conduct - -## Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of -experience, education, socio-economic status, nationality, personal appearance, -race, religion, or sexual identity and orientation. - -## Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, or to ban temporarily or permanently any -contributor for other behaviors that they deem inappropriate, threatening, -offensive, or harmful. - -## Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -This Code of Conduct also applies outside the project spaces when the Project -Steward has a reasonable belief that an individual's behavior may have a -negative impact on the project or its community. - -## Conflict Resolution - -We do not believe that all conflict is bad; healthy debate and disagreement -often yield positive results. However, it is never okay to be disrespectful or -to engage in behavior that violates the project’s code of conduct. - -If you see someone violating the code of conduct, you are encouraged to address -the behavior directly with those involved. Many issues can be resolved quickly -and easily, and this gives people more control over the outcome of their -dispute. If you are unable to resolve the matter for any reason, or if the -behavior is threatening or harassing, report it. We are dedicated to providing -an environment where participants feel welcome and safe. - -Reports should be directed to Emanuele Francioni , the -Project Steward(s) for Dusk. It is the Project Steward’s duty to -receive and address reported violations of the code of conduct. They will then -work with a committee consisting of representatives from the Dusk Network BV team. If for any reason you -are uncomfortable reaching out to the Project Steward, please email -help@dusk.network. - -We will investigate every complaint, but you may not receive a direct response. -We will use our discretion in determining when and how to follow up on reported -incidents, which may range from not taking action to permanent expulsion from -the project and project-sponsored spaces. We will notify the accused of the -report and provide them an opportunity to discuss it before any action is taken. -The identity of the reporter will be omitted from the details of the report -supplied to the accused. In potentially harmful situations, such as ongoing -harassment or threats to anyone's safety, we may take action without notice. - -## Attribution - -This Code of Conduct is adapted from the Contributor Covenant, version 1.4, -available at -https://www.contributor-covenant.org/version/1/4/code-of-conduct.html From 80979dd982d7041441f472ece1c99f2d4aedc536 Mon Sep 17 00:00:00 2001 From: Hein Dauven Date: Mon, 17 Jun 2024 21:08:20 +0200 Subject: [PATCH 4/5] Fix LaTeX in docs and move katex header --- .cargo/config.toml | 2 +- Cargo.toml | 2 +- Makefile | 4 ++-- docs/katex-header.html => katex-header.html | 8 +++++++- 4 files changed, 11 insertions(+), 5 deletions(-) rename docs/katex-header.html => katex-header.html (77%) diff --git a/.cargo/config.toml b/.cargo/config.toml index 69931cee..45715570 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -1,4 +1,4 @@ [build] # Flags needed to render LaTeX in documentation # With this, `cargo docs` must be run with the `--no-deps` flag -rustdocflags = "--html-in-header ./docs/katex-header.html" +rustdocflags = "--html-in-header ./katex-header.html" diff --git a/Cargo.toml b/Cargo.toml index 79b7adb0..aee1399e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -138,4 +138,4 @@ name = "select_point" required-features = ["alloc"] [package.metadata.docs.rs] -rustdoc-args = [ "--html-in-header", "./docs/katex-header.html" ] +rustdoc-args = [ "--html-in-header", "./katex-header.html" ] diff --git a/Makefile b/Makefile index b6328ef0..d91258cf 100644 --- a/Makefile +++ b/Makefile @@ -2,12 +2,12 @@ help: ## Display this help screen @grep -h -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}' doc: ## Generate documentation - @cargo rustdoc --lib -- --html-in-header docs/katex-header.html -D warnings + @cargo rustdoc --lib -- --html-in-header katex-header.html -D warnings doc-internal: ## Generate documentation with private items @cargo rustdoc --lib -- --document-private-items -D warnings doc-local: ## Open local documentation - @RUSTDOCFLAGS="--html-in-header docs/katex-header.html" cargo doc --no-deps --open + @RUSTDOCFLAGS="--html-in-header katex-header.html" cargo doc --no-deps --open .PHONY: help doc doc-internal doc-local diff --git a/docs/katex-header.html b/katex-header.html similarity index 77% rename from docs/katex-header.html rename to katex-header.html index 4a840d38..a2ff28ae 100644 --- a/docs/katex-header.html +++ b/katex-header.html @@ -13,7 +13,13 @@ macros: { "\\lo": "\\text{lo}", "\\hi": "\\text{hi}" - } + }, + delimiters: [ + { left: "$$", right: "$$", display: true }, + { left: "\\(", right: "\\)", display: false }, + { left: "$", right: "$", display: false }, + { left: "\\[", right: "\\]", display: true } + ] }); }); From 22fdd63769c8ec28d66e4778d00b43a57b9e2f0f Mon Sep 17 00:00:00 2001 From: Hein Dauven Date: Mon, 17 Jun 2024 21:23:59 +0200 Subject: [PATCH 5/5] Update README and CHANGELOG - Remove notes doc reference - Mention issue 819 in the changelog --- CHANGELOG.md | 5 +++++ README.md | 55 ++++++++++++++++++++-------------------------------- src/lib.rs | 2 +- 3 files changed, 27 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5133da75..60b2f2e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- Remove docs [#819] + ## [0.19.2] - 2024-03-27 ### Added @@ -581,6 +585,7 @@ is necessary since `rkyv/validation` was required as a bound. - Proof system module. +[#819]: https://github.com/dusk-network/plonk/issues/819 [#818]: https://github.com/dusk-network/plonk/issues/818 [#815]: https://github.com/dusk-network/plonk/issues/815 [#813]: https://github.com/dusk-network/plonk/issues/813 diff --git a/README.md b/README.md index 9b2a13a2..9c946cfd 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,57 @@ # PLONK ![Build Status](https://github.com/dusk-network/plonk/workflows/Continuous%20integration/badge.svg) [![Repository](https://img.shields.io/badge/github-plonk-blueviolet?logo=github)](https://github.com/dusk-network/plonk) -[![Documentation](https://img.shields.io/badge/docs-plonk-blue?logo=rust)](https://docs.rs/plonk/) +[![Documentation](https://img.shields.io/badge/docs-plonk-blue?logo=rust)](https://docs.rs/dusk-plonk/latest/) +_This is a pure Rust implementation of the PLONK proving system over BLS12-381._ -_This is a pure Rust implementation of the PLONK proving system over BLS12-381_ +This library contains a modular implementation of KZG10 as the default polynomial commitment scheme. - -This library contains a modularised implementation of KZG10 as the default -polynomial commitment scheme. - -**DISCLAIMER**: This library is currently unstable and still needs to go through -an exhaustive security analysis. Use at your own risk. +**DISCLAIMER**: This library is currently unstable and still needs to undergo an exhaustive security analysis. Use at your own risk. ## Usage -Check the 'examples' directory for the usage. +To see how to use this library, check the 'examples' directory. ## Features -This crate includes a variety of features which will briefly be explained below: -- `alloc`: Enables the usage of an allocator and with it the capability of performing `Proof` constructions and - verifications. Without this feature it **IS NOT** possible to prove or verify anything. - Its absence only makes `dusk-plonk` export certain fixed-size data structures such as `Proof` which can be useful in no_std environments where we don't have allocators either. -- `std`: Enables `std` usage as well as `rayon` parallelization in some proving and verifying ops. - It also uses the `std` versions of the elliptic curve deps, which utilizes the `parallel` feature - from `dusk-bls12-381`. By default, this is the feature that comes enabled with the crate. -- `debug`: Enables the runtime debugger backend. Will output [CDF](https://crates.io/crates/dusk-cdf) files to the path defined in the `CDF_OUTPUT` environment variable. If used, the binary must be compiled with `debug = true`. For more info, check the [cargo book](https://doc.rust-lang.org/cargo/reference/profiles.html#debug). - __The recommended method is to derive the std output, and the std error, and then place them in text file - which can be used to efficiently analyse the gates.__ +This crate includes a variety of features which are briefly explained below: +- `alloc`: Enables the usage of an allocator, allowing for `Proof` constructions and verifications. Without this feature it **IS NOT** possible to prove or verify anything. + Its absence only makes `dusk-plonk` export certain fixed-size data structures such as `Proof`, which can be useful in no_std environments where we don't have allocators available. +- `std`: Enables `std` usage as well as `rayon` parallelization in some proving and verifying operations. + It also uses the `std` versions of the elliptic curve dependencies, utilizing the `parallel` feature + from `dusk-bls12-381`. This feature is enabled by default. +- `debug`: Enables the runtime debugger backend, outputting [CDF](https://crates.io/crates/dusk-cdf) files to the path defined in the `CDF_OUTPUT` environment variable. When used, the binary must be compiled with `debug = true`. For more info, check the [cargo book](https://doc.rust-lang.org/cargo/reference/profiles.html#debug). + __It is recommended to derive the std output and std error and then place them in a text file for efficient gate analysis.__ ## Documentation -There are two main types of documentation in this repository: - -- **Crate documentation**. This provides info about all of the functions that the library provides, as well - as the documentation regarding the data structures that it exports. To check this, please feel free to go to - the [documentation page](https://docs.rs/dusk-plonk/) or run `make doc` or `make doc-internal`. - -- **Notes**. This is a specific subset of documentation which explains the key mathematical concepts - of PLONK and how they work with mathematical demonstrations. To check it, run `make doc` and open the resulting docs, - which will be located under `/target` with your browser. +The crate documentation provides information about all the functions that the library provides, as well +as the documentation regarding the data structures that it exports. To check this, visit the [documentation page](https://docs.rs/dusk-plonk/) or run `make doc` or `make doc-internal`. ## Performance Benchmarks taken on `Apple M1`, for a circuit-size of `2^16` constraints: - Proving time: `7.871s` -- Verification time: `7.643ms` **(This time will not vary depending on the circuit-size.)** +- Verification time: `7.643ms` **(This time does not vary depending on the circuit-size.)** For more results, please run `cargo bench` to get a full report of benchmarks in respect of constraint numbers. ## Acknowledgements -- Reference implementation AztecProtocol/Barretenberg -- FFT Module and KZG10 Module were taken and modified from zexe/zcash and scipr-lab, respectively. +- Reference implementation by Aztec Protocol/Barretenberg. +- FFT Module and KZG10 Module were adapted from ZEXE/Zcash and SCIPR Lab, respectively. ## Licensing -This code is licensed under Mozilla Public License Version 2.0 (MPL-2.0). Please see [LICENSE](https://github.com/dusk-network/plonk/blob/master/LICENSE) for further info. +This code is licensed under the Mozilla Public License Version 2.0 (MPL-2.0). Please see [LICENSE](https://github.com/dusk-network/plonk/blob/master/LICENSE) for more information. ## About -Implementation designed by the [dusk](https://dusk.network) team. +This implementation is designed by the [Dusk](https://dusk.network) team. ## Contributing -- If you want to contribute to this repository/project please, check [CONTRIBUTING.md](https://github.com/dusk-network/plonk/blob/master/CONTRIBUTING.md) +- If you want to contribute to this repository/project, please check our [CONTRIBUTING.md](https://github.com/dusk-network/plonk/blob/master/CONTRIBUTING.md). - If you want to report a bug or request a new feature addition, please open an issue on this repository. diff --git a/src/lib.rs b/src/lib.rs index 14e9178a..11878e0d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -33,7 +33,7 @@ //! [Dusk team](dusk.network) of this algorithm using as a reference //! implementation this one done by the creators of the protocol: //! -//! +//! // Bitshift/Bitwise ops are allowed to gain performance. #![allow(clippy::suspicious_arithmetic_impl)]