changes on the structure and beginning of SHA256 example

zokrates_book/src/SUMMARY.md

@@ -1,6 +1,14 @@
 # Summary
 
 - [Introduction](./introduction.md)
-- [Grammar](./grammar.md)
-- [CLI](./cli.md)
-- [Verification](./verification.md)
+
+- [Getting Started](./gettingstarted.md)
+- [Proofing a Hash Pre-Image](./sha256example.md)
+
+- [ZoKrates Programming Concepts](./concepts.md)
+
+- [ZoKrates Reference](reference/index.md)
+    - [Grammar](reference/grammar.md)
+    - [CLI](reference/cli.md)
+    - [Gadgets](reference/gadgets.md)
+    - [Verification](reference/verification.md)

zokrates_book/src/concepts.md

@@ -0,0 +1,13 @@
+# ZoKrates Programming Concepts
+
+## Variables
+
+## Types
+
+## Comments 
+
+## Functions
+
+## Control Flow
+
+## Gadgets

zokrates_book/src/gettingstarted.md

@@ -0,0 +1,47 @@
+# Getting Started
+
+## Installation
+
+Using Docker is currently the recommended way to get started with Zokrates.
+
+```bash
+docker run -ti zokrates/zokrates /bin/bash
+```
+
+Now you should be dropped into a shell and can find the `zokrates` executable in the following folder `ZoKrates/target/release`.
+
+Alternatively you can build the container yourself with the following commands:
+
+```bash
+git clone https://github.com/JacobEberhardt/ZoKrates
+cd ZoKrates
+docker build -t zokrates .
+docker run -ti zokrates /bin/bash
+cd ZoKrates/target/release
+```
+
+Alternatively, you can build Cargo from [source](https://github.com/JacobEberhardt/ZoKrates/).
+
+## First Steps with ZoKrates
+
+First, create the text-file `add.code` and implement your program:
+
+```zokrates
+def main(field a, field b, field c) -> (field):
+  return a + b + c
+```
+
+The keyword `field` declares the type of the parameters used as elements of the underlying finite field.
+
+Then run the different phases of the protocol:
+
+```bash
+./zokrates compile -i 'add.code'
+./zokrates setup
+./zokrates compute-witness -a 1 2 3
+./zokrates generate-proof
+./zokrates export-verifier
+```
+
+The CLI commands are explained in more detail in this [section
+](reference/cli.html) of the doc.

zokrates_book/src/introduction.md

@@ -1,13 +1,22 @@
 # Introduction
 
-Welcome to the ZoKrates documentation, here's some ZoKrates code:
+Zokrates is a toolbox for zkSNARKs on Ethereum.
 
-```zokrates
-def main() -> (field):
-	return 42
-```
 
-And here is some invalid ZoKrates code:
-```zokrates
-🦓
-```
+## Background on zkSNARKs
+
+ Zero-knowledge proofs (ZKPs) are a family of probabilistic protocols, first described by [Goldwasser, Micali and Rackoff](http://people.csail.mit.edu/silvio/Selected%20Scientific%20Papers/Proof%20Systems/The_Knowledge_Complexity_Of_Interactive_Proof_Systems.pdf) in 1985.
+ 
+On particular family of ZKPs is described as zero-knowledge **S**uccinct **N**on-interactive **AR**guments of **K**nowledge, a.k.a. zk-SNARKs. zk-SNARKs are the most widely used zero-knowledge protocols, with the anonymous cryptocurrency Zcash and the smart-contract platform Ethereum among the notable early adopters. 
+
+For further details we refer the reader to some introductory material provided by the community: [[1]](https://z.cash/technology/zksnarks/),[[2]](https://medium.com/@VitalikButerin/zk-snarks-under-the-hood-b33151a013f6), [[3]](https://blog.decentriq.ch/zk-snarks-primer-part-one/).
+
+## Motivation
+
+Ethereum runs computations on all nodes of the network, resulting in high costs, limits in complexity, and low privacy. zkSNARKs have been enabling to only verify computations on-chain for a fraction of the cost of running them, but are hard to grasp and work with.
+
+Zokrates bridges this gap. It helps you create off-chain programs and link them to the Ethereum blockchain, expanding the possibilities for your dApp.
+
+## License
+
+ZoKrates, all the source code, is released under the GNU Lesser General Public License v3.

zokrates_book/src/programmingconcepts.md

@@ -0,0 +1,10 @@
+#ZoKrates Programming Concepts
+
+## Variables
+
+## Data Types
+
+## Functions
+
+## Control Flow
+

zokrates_book/src/reference/cli.md

@@ -1,21 +1,26 @@
-# CLI
+# Command Line Tool
 
 Zokrates provides a command line interface.
 You can see an overview of the available subcommands by running
 
-```
+```sh
 ./zokrates
 ```
-## compile
-```
+
+## `compile`
+
+```sh
 ./zokrates compile -i /path/to/add.code
 ```
-Compile a `.code` file.
+
+Compiles a `.code` file into  ZoKrates internal representation of arithmetic circuits. Use the `--gadgets` flag if libsnark gadgets are being used in your code (e.g. SHA256 hashing). 
+
 Creates a compiled `.code` file at `./out.code`.
 
-## compute-witness
-```
-./zokrates compute-witness -a 1 2
+## `compute-witness`
+
+```sh
+./zokrates compute-witness -a 1 2 3
 ```
 
 Computes a witness for the compiled program found at `./out.code` and arguments to the program.
@@ -23,33 +28,38 @@ A witness is a valid assignment of the variables, which include the results of t
 
 Creates a witness file at `./witness`
 
-## setup
-```
+## `setup`
+
+```sh
 ./zokrates setup
 ```
 
 Generates a trusted setup for the compiled program found at `./out.code`.
 
 Creates a proving key and a verifying key at `./proving.key` and `./verifying.key`.
+These keys are derived from a source of randomness, commonly referred to as “toxic waste”. Anyone having access to the source of randomness can produce fake proofs that will be accepted by a verifier following the protocol.
 
-## export-verifier
-```
+## `export-verifier`
+
+```sh
 ./zokrates export-verifier
 ```
 
-Using the verifying key at `./verifying.key`, generates a Solidity contract enabling to verify proofs for computations of the compiled program at `./out.code`.
+Using the verifying key at `./verifying.key`, generates a Solidity contract which contains the generated verification key and a public function to verify a solution to the compiled program at `./out.code`.
 
-Creates a verifier contract at `./verifier.sol`
+Creates a verifier contract at `./verifier.sol`.
 
-## generate-proof
-```
+## `generate-proof`
+
+```sh
 ./zokrates generate-proof
 ```
 
 Using the proving key at `./proving.key`, generates a proof for a computation of the compiled program `./out.code` resulting in `./witness`.
 
 Returns the proof, for example:
-```
+
+```k
 A = 0x45582d7906c967b1fd1cac0aad3efefa526e4cd888b8ecb5907b46c2eb1f781, 0x8158089a63a6aafa4afc3bbfd5ebf392e5ef61d0c5faf2e2445c9112450f29c
 A_p = 0x5e4fe0bfa79a571b8918138ee5d7b3d0ad394c9bb8f7d2e1549f7e3c3bab7e9, 0x1708b5ba3d138e433406c792f679ae6902fc9f7c6131305a9a5f826dbe2d71fb
 B = [0x34f5c5b7518597452e55a69bf9171a63837a98a1c1c1870b610b2cfe79c4573, 0x18e56afd179d67960db838a8fdb128eb78d5dd2c1ffcd564f9d0dada928ed71f], [0xf160ea8d2dc33b564a45c0998309b4bf5a050cc8f6288793b7401b37d1eb1a2, 0x23ade8ba2c64300b5ff90e18641516407054a21179829252fd87f1bd61a3be34]
@@ -62,7 +72,8 @@ K = 0x1868436121f271e9fbf78a8f75bb4077e2d4f208891793fd5b468afc3b05c0e4, 0x1021c3
 
 Passed to the verifier contract, this proof can be checked.
 For example, using `web3`, a call would look like the following:
-```
+
+```k
 Verifier.at(<verifier contract address>).verifyTx(A, A_p, B, B_p, C, C_p, H, K, [...publicInputs, ...outputs])
 ```
 

zokrates_book/src/reference/gadgets.md

@@ -0,0 +1,3 @@
+# Gadgets
+
+//TODO: add description of all gadgets available + SHA256 comparison

zokrates_book/src/reference/index.md

@@ -0,0 +1,9 @@
+# ZoKrates Reference
+
+The reference covers the details of various areas of Cargo.
+
+- [ZoKrates Reference](index.md)
+    - [Grammar](grammar.md)
+    - [CLI](cli.md)
+    - [Gadgets](gadgets.md)
+    - [Verification](verification.md)

zokrates_book/src/reference/verification.md

@@ -1,9 +1,10 @@
 # Verification
+
 Passed to the verifier contract, this proof can be checked.
 For example, using `web3`, a call would look like the following:
+
 ```
 Verifier.at(<verifier contract address>).verifyTx(A, A_p, B, B_p, C, C_p, H, K, [...publicInputs, ...outputs])
 ```
 
-Where `A, ..., K` are defined as above (adding brackets and quotes: `A = ["0x123", "0x345"]`), `publicInputs` are the public inputs supplied to witness generation and `outputs` are the results of the computation.
-
+Where `A, ..., K` are defined as above (adding brackets and quotes: `A = ["0x123", "0x345"]`), `publicInputs` are the public inputs supplied to witness generation and `outputs` are the results of the computation.