Add cargo spec infra and some sample speccing.

Makefile

@@ -0,0 +1,22 @@
+.PHONY: spec-build spec-watch
+
+OUT_MD_FILE := ./spec/specification.md
+OUT_HTML_FILE := ./spec/specification.html
+OUT_TEX_FILE := ./spec/specification.tex
+OUT_PDF_FILE := ./spec/specification.pdf
+OUT_SPEC_DIRECTORY := ./spec/
+
+# builds the specification once
+spec-build:
+	cargo spec build --output-file $(OUT_MD_FILE)
+	pandoc $(OUT_MD_FILE) --to=latex --standalone  --output $(OUT_TEX_FILE)
+	pandoc $(OUT_TEX_FILE) --to=pdf --standalone  --output $(OUT_PDF_FILE)
+# this gives lots of error and does not compile corretly
+# pdftex -shell-escape -output-directory $(OUT_SPEC_DIRECTORY)  \\nonstopmode\\input specification.tex 
+
+# watches specification-related files and rebuilds them on the fly
+spec-watch:
+	cargo spec watch --output-file $(OUT_MD_FILE)
+
+spec-build-html:
+	cargo spec build --output-format respec --output-file $(OUT_HTML_FILE)

README.md

@@ -17,4 +17,12 @@
 * Refactor common/piop.rs to have types shared between prover nad verifier
 * Add zk
 * Batch verification
-* Batch proving
+* Batch proving
+
+## Building the Specification document
+
+The specification is built by means of [Cargo spec](https://crates.io/crates/cargo-spec) crate. To build the specification document, oneneed pandoc and latex. With requirement installed, on can simply invoke:
+```
+$ make spec-build
+```
+and get the specification in `./spec/specification.pdf`

Specification.toml

@@ -0,0 +1,20 @@
+[metadata]
+name = "Ring Proof"
+description = "zk proof of knowledge of blindinng factor of a Pedersen commitment"
+authors = ["Alistair, Davide, Jeff, Syed, Sergey"]
+
+[config]
+template = "specification_template.md"
+
+[sections]
+# Plonk Prover
+plonk-prover = "common/src/prover.rs"
+
+# Plonk Verifier
+plonk-verifier = "common/src/verifier.rs"
+
+# Ring Prover
+ring-prover = "ring/src/ring_prover.rs"
+
+## Ring Verifier
+ring-verifier = "ring/src/ring_verifier.rs"

common/src/verifier.rs

@@ -30,6 +30,16 @@ impl<F: PrimeField, CS: PCS<F>, T: Transcript<F, CS>> PlonkVerifier<F, CS, T> {
         }
     }
 
+    //~ #### Plonk.Verify\
+    //~ **Inputs**:\
+    //~   - $Piop$: an object of Piop type\
+    //~   - $Proof$: a proof tuple as defined in ???\
+    //~   - $Challenges: ([\alpha_1,...,\alpha_n, \zeta, [\nu_1,..,nu_n])$ A Plonk Verifier challenge defined in ???\
+    //~   - $H$: R Random oracle\
+    //~ **Output**:\
+    //~   - A boolean value indicating if the $Proof$ represents a correct proof\
+    //~
+    //~ *****  
     pub fn verify<Piop, Commitments, Evaluations, R: Rng>(
         &self,
         piop: Piop,
@@ -42,10 +52,14 @@ impl<F: PrimeField, CS: PCS<F>, T: Transcript<F, CS>> PlonkVerifier<F, CS, T> {
             Commitments: ColumnsCommited<F, CS::C>,
             Evaluations: ColumnsEvaluated<F>,
     {
+        //~ $C \leftarrow EvaluateConsttrain(Poip)$  
+        //~ $E \leftarrow \sum_i^n \alpha[i] * C[i]$  
+        //~ $D \leftarrow DomainEvaluated(Piop)$  
         let eval: F = piop.evaluate_constraints_main().iter().zip(challenges.alphas.iter()).map(|(c, alpha)| *alpha * c).sum();
         let zeta = challenges.zeta;
         let domain_evaluated = piop.domain_evaluated();
 
+        //~ $q_{zeta} \leftarrow \frac{D}{\Omega(C + Proof.x)}$  
         let q_zeta = domain_evaluated.divide_by_vanishing_poly_in_zeta(eval + proof.lin_at_zeta_omega);
 
         let mut columns = [
@@ -64,8 +78,12 @@ impl<F: PrimeField, CS: PCS<F>, T: Transcript<F, CS>> PlonkVerifier<F, CS, T> {
         let lin_comm = CS::C::combine(&challenges.alphas[..3], &lin_pices);
 
         let zeta_omega = zeta * domain_evaluated.omega();
-
+
+        //~ **return** $BatchVerify()$  
         CS::batch_verify(&self.pcs_vk, vec![cl, lin_comm], vec![challenges.zeta, zeta_omega], vec![agg_y, proof.lin_at_zeta_omega], vec![proof.agg_at_zeta_proof, proof.lin_at_zeta_omega_proof], rng)
+        //~      
+        //~ *****    
+
     }
 
     pub fn restore_challenges<Commitments, Evaluations>(
@@ -98,6 +116,13 @@ impl<F: PrimeField, CS: PCS<F>, T: Transcript<F, CS>> PlonkVerifier<F, CS, T> {
     }
 }
 
+
+//~ ### Challenge  
+//~
+//~ **Definition**: *Plonk verifier challange* is defined as triple:
+//~ $$([\alpha_1,...,\alpha_n, \zeta, [\nu_1,..,nu_n])$$
+//~ where \alpha_i, zeta and nu_i are all elements of Plonk Scalar Field.
+//~
 pub struct Challenges<F: Field> {
     pub alphas: Vec<F>,
     pub zeta: F,

spec/specification.md

@@ -0,0 +1,46 @@
+# Ring Proof
+
+for a vector commitment to a list of public keys, and a Pedersen commitment to one of the secret keys,
+  implements a zk proof of knowledge of the blinding factor for the Pedersen commitment, and the position of the
+  corresponding public key in the list.
+
+### Preliminaries 
+
+### Plonk Prover
+
+
+### Plonk Verifier
+
+#### Plonk.Verify\
+**Inputs**:\
+  - $Piop$: an object of Piop type\
+  - $Proof$: a proof tuple as defined in ???\
+  - $Challenges: ([\alpha_1,...,\alpha_n, \zeta, [\nu_1,..,nu_n])$ A Plonk Verifier challenge defined in ???\
+  - $H$: R Random oracle\
+**Output**:\
+  - A boolean value indicating if the $Proof$ represents a correct proof\
+
+*****  
+$C \leftarrow EvaluateConsttrain(Poip)$  
+$E \leftarrow \sum_i^n \alpha[i] * C[i]$  
+$D \leftarrow DomainEvaluated(Piop)$  
+$q_zeta \leftarrow \frac{D}{\Omega(C + Proof.x)}$  
+**return** $BatchVerify()$  
+
+*****    
+### Challenge  
+
+**Definition**: *Plonk verifier challange* is defined as triple:
+$$([\alpha_1,...,\alpha_n, \zeta, [\nu_1,..,nu_n])$$
+where \alpha_i, zeta and nu_i are all elements of Plonk Scalar Field.
+
+
+
+### Ring Prover
+
+
+
+### Ring Verifier
+
+
+

specification_template.md

@@ -0,0 +1,23 @@
+# Ring Proof
+
+for a vector commitment to a list of public keys, and a Pedersen commitment to one of the secret keys,
+  implements a zk proof of knowledge of the blinding factor for the Pedersen commitment, and the position of the
+  corresponding public key in the list.
+
+### Preliminaries 
+
+### Plonk Prover
+{sections.plonk-prover}
+
+### Plonk Verifier
+
+{sections.plonk-verifier}
+
+### Ring Prover
+
+{sections.ring-prover}
+
+### Ring Verifier
+
+{sections.ring-verifier}
+