update docs

zokrates_book/src/SUMMARY.md

@@ -7,6 +7,7 @@
 - [Programming Concepts](./concepts.md)
 	- [Variables](./concepts/variables.md)
 	- [Types](./concepts/types.md)
+	- [Operators](./concepts/operators.md)
 	- [Functions](./concepts/functions.md)
 	- [Control flow](./concepts/control_flow.md)
 	- [Imports](./concepts/imports.md)

zokrates_book/src/concepts/control_flow.md

@@ -1,10 +1,10 @@
 ## Control Flow
 
-ZoKrates provide a single thread of execution with two control flow constructs.
+ZoKrates provides a single thread of execution with a few flow constructs.
 
 ### Function calls
 
-Function calls can help make programs clearer and more modular. However, using function calls is not always zero-cost, so deep call chains should be avoided.
+Function calls help make programs clear and modular.
 
 Arguments are passed by value.
 
@@ -12,18 +12,14 @@ Arguments are passed by value.
 {{#include ../../../zokrates_cli/examples/book/side_effects.zok}}
 ```
 
-### If expressions
+### If-expressions
 
-An if-expression allows you to branch your code depending on a condition.
+An if-expression allows you to branch your code depending on a boolean condition.
 
 ```zokrates
 {{#include ../../../zokrates_cli/examples/book/if_else.zok}}
 ```
 
-The condition supports `<`, `<=`, `>`, `>=`, `==`, which can be combined with the boolean operators `&&`, `||` and `!`.
-
->When it comes to inequality checks, there is a caveat: when executing `a < b`, both `a` and `b` will be asserted to be strictly lower than the biggest power of 2 lower than `p/2`. This means that `a` and `b` are both asserted to be between `0` and `2**252 - 1`. The same applies to other inequality checks.
-
 ### For loops
 
 For loops are available with the following syntax:
@@ -32,5 +28,14 @@ For loops are available with the following syntax:
 {{#include ../../../zokrates_cli/examples/book/for.zok}}
 ```
 
-The bounds have to be known at compile-time, so only constants are allowed.
+The bounds have to be constant at compile-time, therefore they cannot depend on execution inputs.
-For-loops define their own scope.
+
+### Assertions
+
+Any boolean can be asserted to be true using the `assert` function.
+
+```zokrates
+{{#include ../../../zokrates_cli/examples/book/assert.zok}}
+```
+
+If any assertion fails, execution stops as no valid proof could be generated from it.

zokrates_book/src/concepts/imports.md

@@ -53,12 +53,7 @@ You can import a resource in the same folder directly, like this:
 from "./mycode" import foo
 ```
 
-There also is a handy syntax to import from the parent directory:
+Imports up the file-system tree are supported:
-```zokrates
-from "../mycode" import foo
-```
-
-Also, imports further up the file-system are supported:
 ```zokrates
 from "../../../mycode" import foo
 ```

zokrates_book/src/concepts/operators.md

@@ -1,85 +1,23 @@
 ## Operators
 
-The ZoKrates programming language constists of different operands that can be used on variables
+The following table lists the precedence and associativity of all available operators. Operators are listed top to bottom, in ascending precedence.
 
-### Available Operators
+| Operator                     | Description                                                  | Associativity                      | Remarks |
+|------------------------------|--------------------------------------------------------------|------------------------------------|---------|
+| ** <br>                      | Power                                                        | Left                               | (1)     |
+| * <br> /<br>                 | Multiplication <br>  Division <br>                           | Left <br> Left                     |         |
+| + <br> - <br>                | Addition <br>  Subtraction <br>                              | Left <br> Left                     |         |
+| << <br> >> <br>              | Left shift <br>  Right shift <br>                            | Left <br> Left                     | (2)     |
+| &                            | Bitwise AND                                                  | Left <br> Left                     |         |
+| \|                           | Bitwise OR                                                   | Left <br> Left                     |         |
+| ^                            | Bitwise XOR                                                  | Left <br> Left                     |         |
+| >= <br><br> > <br> <= <br> < | Greater or equal <br> Greater <br> Lower or equal <br> Lower | Left <br> Left <br> Left <br> Left | (3)     |
+| != <br> == <br>              | Not Equal <br> Equal  <br>                                   | Left <br> Left                     |         |
+| &&                           | Boolean AND                                                  | Left                               |         |
+| \|\|                         | Boolean OR                                                   | Left                               |         |
 
-#### Or
 
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/or.zok}}
-```
 
-#### Xor
+1. The exponent must be a compile-time constant
-
+2. The right operand must be a compile time constant
-```zokrates
+3. Both operands are be asserted to be strictly lower than the biggest power of 2 lower than `p/2`
-{{#include ../../../zokrates_cli/examples/book/xor.zok}}
-```
-
-#### And
-
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/and.zok}}
-```
-
-#### Equal
-
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/equal.zok}}
-```
-
-#### Not Equal
-
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/not_equal.zok}}
-```
-
-#### Greater/Lower
-
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/gtl.zok}}
-```
-
-#### Add
-
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/add.zok}}
-```
-
-#### Subtract
-
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/subtract.zok}}
-```
-
-#### Multiply
-
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/mul.zok}}
-```
-
-#### Divide
-
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/div.zok}}
-```
-
-#### Power
-
-```zokrates
-{{#include ../../../zokrates_cli/examples/book/pow.zok}}
-```
-
-### Operator Precedence
-The following table lists the precedence and associativity of all available operators. Operators are listed top to bottom, in descending precedence.
-
-| Precedence | Operator                               | Description                        | Associativity                     |
-|------------|----------------------------------------|------------------------------------|-----------------------------------|
-| 1          | ** <br>                                | Power                              | Left                              |
-| 2          | * <br> /<br>                           | Multiplication <br>  Division <br> | Left <br> Left                    |
-| 3          | + <br> - <br>                          | Addition <br>  Subtraction <br>    | Left <br> Left                    |
-| 4          | >= <br> > <br> <= <br> <               | gte <br> gt <br> lte <br> lt       | Left <br> Left <br> Left <br> Left|
-| 5          | == <br> != <br>                        | Equal <br> Not Equal  <br>         | Left <br> Left                    |
-| 6          | &&                                     | And                                | Left                              |
-| 7          | XOR(a,b) - import from stdlib          | Xor                                | Left                              |
-| 8          | \|\|                                   | Or                                 | Left                              |

zokrates_book/src/concepts/stdlib.md

@@ -1,6 +1,6 @@
 ## Standard library
 
-ZoKrates comes with a number of reusable components which are defined at `./stdlib/` in the ZoKrates root repository. In order to import the standard library as described in the [imports](./imports.html) section the `$ZOKRATES_HOME` environment variable needs to be set to the `stdlib` folder.  The standard library is solely based on the ZoKrates DSL and can be easily extended.
+ZoKrates comes with a number of reusable components which are defined at `./stdlib/` in the ZoKrates root repository. In order to import the standard library as described in the [imports](./imports.html) section the `$ZOKRATES_HOME` environment variable needs to be set to the `stdlib` folder.
 
 The following section highlights a subset of available imports:
 
@@ -12,7 +12,7 @@ The following section highlights a subset of available imports:
 import "hashes/sha256/512Padded.zok"
 ```
 
-A function that takes 2 `bool[256]` arrays as inputs and returns their sha256 compression function as an array of 256 booleans.
+A function that takes 2 `u32[8]` arrays as inputs and returns their sha256 compression function as a `u32[8]`.
 
 #### sha256compression
 
@@ -20,8 +20,8 @@ A function that takes 2 `bool[256]` arrays as inputs and returns their sha256 co
 import "hashes/sha256/512bit.zok"
 ```
 
-A function that takes 2 `bool[256]` arrays as inputs and returns their sha256 compression function as an array of 256 booleans.
+A function that takes 2 `u32[8]` arrays as inputs and returns their sha256 compression function as a `u32[8]`.
-The difference with `sha256` is that no padding is added at the end of the message, which makes it more efficient but also less compatible with Solidity.
+The difference with `512Padded` is that no padding is added at the end of the message, which makes it more efficient but also less compatible with Solidity.
 
 There also is support for 2-round (1024-bit input) and 3-round (1536-bit input) variants, using  `hashes/1024bit.zok` and `hashes/1536bit.zok` respectively.
 
@@ -58,10 +58,10 @@ Verifies an EdDSA Signature. Checks the correctness of a given EdDSA Signature `
 #### pack128
 
 ```zokrates
-import "utils/pack/pack128"
+import "utils/pack/u32/pack128"
 ```
 
-Packs 128 booleans as one field element.
+Packs a `u32[4]` as one field element.
 
 #### unpack128
 
@@ -69,21 +69,29 @@ Packs 128 booleans as one field element.
 import "utils/pack/unpack128"
 ```
 
-Unpacks a field element to 128 booleans.
+Unpacks a field element to a `u32[4]`, throwing if it doesn't fit.
 
 #### pack256
 
 ```zokrates
-import "utils/pack/pack256"
+import "utils/pack/u32/pack256"
 ```
 
-Packs 256 booleans as one. Overflows can occur.
+Packs a `u32[8]` as one field element. Overflows can occur.
 
 #### nonStrictUnpack256
 
 ```zokrates
-import "utils/pack/nonStrictUnpack256"
+import "utils/pack/u32/nonStrictUnpack256"
 ```
 
-Unpacks a field element into 256 booleans. Uniqueness of the output is not guaranteed.
+Unpacks a field element to a `u32[4]`. Uniqueness of the output is not guaranteed.
+
+### Casts
+
+Different helpers to convert between types.
+
+```zokrates
+import "utils/casts/bool_128_to_u32_4"
+```
 

zokrates_book/src/concepts/types.md

@@ -18,11 +18,11 @@ While `field` values mostly behave like unsigned integers, one should keep in mi
 
 ### `bool`
 
-ZoKrates has limited support for booleans, to the extent that they can only be used as the condition in `if ... else ... endif` expressions.
+Booleans are available in ZoKrates. When a boolean is used as a parameter of the main function, the program is constrained to only accept `0` or `1` for that parameter. A boolean can be asserted to be true using an `assert(bool)` statement.
 
-You can use them for equality and inequality checks between `field` values.
+### `u8/u16/u32`
 
-Note that while equality checks are cheap, inequality checks should be used wisely as they are orders of magnitude more expensive.
+Unsigned integers enable implementing programs which rely bit strings, such as hash functions.
 
 ## Complex Types
 
@@ -47,7 +47,7 @@ Initialization always needs to happen in the same statement as a declaration, un
 For initialization, a list of comma-separated values is provided within brackets `[]`.
 
 ZoKrates offers a special shorthand syntax to initialize an array with a constant value:
-`[value;repetitions]`
+`[value; repetitions]`
 
 
 The following code provides examples for declaration and initialization:

zokrates_book/src/reference/cli.md

@@ -63,6 +63,7 @@ Creates a proving key and a verification key at `./proving.key` and `./verificat
 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.
 
 The [proving scheme](proving_schemes.md) and curve can be chosen with the `proving-scheme` and `curve` flags.
+The backend can be chosen with the `backend` flag.
 
 ## `export-verifier`
 

zokrates_cli/examples/book/add.zok

@@ -1,6 +0,0 @@
-// only using add, no need to flatten
-def main(field a) -> (field):
-  field b = a + 5
-  field c = a + b + a + 4
-  field d = a + c + a + b
-  return b + c + d

zokrates_cli/examples/book/and.zok

@@ -1,5 +0,0 @@
-// example using if-then-else-fi with &&
-
-def main(field a, field b) -> (field):
-    field y = if a + 2 == 3 && a * 2 == 2 then 1 else 0 fi
-    return y

zokrates_cli/examples/book/assert.zok

@@ -0,0 +1,3 @@
+def main() -> ():
+	assert(1 == 2)
+	return

zokrates_cli/examples/book/div.zok

@@ -1,2 +0,0 @@
-def main(field a, field b, field c) -> (field):
-  return a / b / c

zokrates_cli/examples/book/equal.zok

@@ -1,2 +0,0 @@
-def main(field a, field b) -> (bool):
-  return a == b

zokrates_cli/examples/book/for.zok

@@ -1,6 +1,8 @@
 def main() -> (field):
     field res = 0
     for field i in 0..4 do
-        res = res + i
+    	for field j in i..5 do
+        	res = res + i
+        endfor
     endfor
     return res

zokrates_cli/examples/book/gtl.zok

@@ -1,7 +0,0 @@
-def main() -> (bool):
-    field a = if 10 > 9 then 1 else 0 fi
-    field b = if 10 >= 9 then 1 else 0 fi
-    field c = if 10 <= 10 then 1 else 0 fi
-    field d = if 10 < 9 then 1 else 0 fi
-    
-    return a == b && c == d

zokrates_cli/examples/book/hashexample.zok

@@ -1,4 +1,4 @@
-import "hashes/sha256/512bitPacked" as sha256packed
+from "hashes/sha256/512bitPacked" import main
 
 def main(private field a, private field b, private field c, private field d) -> (field[2]):
 	field[2] h = sha256packed([a, b, c, d])

zokrates_cli/examples/book/mul.zok

@@ -1,2 +0,0 @@
-def main(field a, field b, field c) -> (field):
-  return a * b * c

zokrates_cli/examples/book/or.zok

@@ -1,4 +0,0 @@
-// example using if-then-else-fi with ||
-def main(field a, field b) -> (field):
-    field y = if a + 2 == 4 || b * 2 == 2 then 1 else 0 fi
-    return y

zokrates_cli/examples/book/pow.zok

@@ -1,2 +0,0 @@
-def main() -> (field):
-  return 5**5

zokrates_cli/examples/book/sub.zok

@@ -1,7 +0,0 @@
-// only using sub, no need to flatten
-def main(field a) -> (field):
-  field b = a + 100
-  field c = b + a + b
-  field d = b - a - 3 - a
-  field e = d + 3 - a
-  return d + c + e

zokrates_cli/examples/book/xor.zok

@@ -1,4 +0,0 @@
-import "utils/binary/xor" as XOR
-
-def main(field a, field b) -> (field):
-    return XOR(a, b)