From 498a8665217ba0f67a70b95dcd1eb5f487fb994e Mon Sep 17 00:00:00 2001 From: schaeff Date: Fri, 17 Jul 2020 12:25:05 +0200 Subject: [PATCH] update docs --- zokrates_book/src/SUMMARY.md | 1 + zokrates_book/src/concepts/control_flow.md | 25 +++--- zokrates_book/src/concepts/imports.md | 7 +- zokrates_book/src/concepts/operators.md | 96 ++++------------------ zokrates_book/src/concepts/stdlib.md | 30 ++++--- zokrates_book/src/concepts/types.md | 8 +- zokrates_book/src/reference/cli.md | 1 + zokrates_cli/examples/book/add.zok | 6 -- zokrates_cli/examples/book/and.zok | 5 -- zokrates_cli/examples/book/assert.zok | 3 + zokrates_cli/examples/book/div.zok | 2 - zokrates_cli/examples/book/equal.zok | 2 - zokrates_cli/examples/book/for.zok | 4 +- zokrates_cli/examples/book/gtl.zok | 7 -- zokrates_cli/examples/book/hashexample.zok | 2 +- zokrates_cli/examples/book/mul.zok | 2 - zokrates_cli/examples/book/or.zok | 4 - zokrates_cli/examples/book/pow.zok | 2 - zokrates_cli/examples/book/sub.zok | 7 -- zokrates_cli/examples/book/xor.zok | 4 - 20 files changed, 65 insertions(+), 153 deletions(-) delete mode 100644 zokrates_cli/examples/book/add.zok delete mode 100644 zokrates_cli/examples/book/and.zok create mode 100644 zokrates_cli/examples/book/assert.zok delete mode 100644 zokrates_cli/examples/book/div.zok delete mode 100644 zokrates_cli/examples/book/equal.zok delete mode 100644 zokrates_cli/examples/book/gtl.zok delete mode 100644 zokrates_cli/examples/book/mul.zok delete mode 100644 zokrates_cli/examples/book/or.zok delete mode 100644 zokrates_cli/examples/book/pow.zok delete mode 100644 zokrates_cli/examples/book/sub.zok delete mode 100644 zokrates_cli/examples/book/xor.zok diff --git a/zokrates_book/src/SUMMARY.md b/zokrates_book/src/SUMMARY.md index db737980..e12073a0 100644 --- a/zokrates_book/src/SUMMARY.md +++ b/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) diff --git a/zokrates_book/src/concepts/control_flow.md b/zokrates_book/src/concepts/control_flow.md index b799a249..c83961bf 100644 --- a/zokrates_book/src/concepts/control_flow.md +++ b/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. -For-loops define their own scope. \ No newline at end of file +The bounds have to be constant at compile-time, therefore they cannot depend on execution inputs. + +### 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. diff --git a/zokrates_book/src/concepts/imports.md b/zokrates_book/src/concepts/imports.md index e78c810c..3f6995fa 100644 --- a/zokrates_book/src/concepts/imports.md +++ b/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: -```zokrates -from "../mycode" import foo -``` - -Also, imports further up the file-system are supported: +Imports up the file-system tree are supported: ```zokrates from "../../../mycode" import foo ``` diff --git a/zokrates_book/src/concepts/operators.md b/zokrates_book/src/concepts/operators.md index 38765d5a..6153893c 100644 --- a/zokrates_book/src/concepts/operators.md +++ b/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 | +|------------------------------|--------------------------------------------------------------|------------------------------------|---------| +| **
| Power | Left | (1) | +| *
/
| Multiplication
Division
| Left
Left | | +| +
-
| Addition
Subtraction
| Left
Left | | +| <<
>>
| Left shift
Right shift
| Left
Left | (2) | +| & | Bitwise AND | Left
Left | | +| \| | Bitwise OR | Left
Left | | +| ^ | Bitwise XOR | Left
Left | | +| >=

>
<=
< | Greater or equal
Greater
Lower or equal
Lower | Left
Left
Left
Left | (3) | +| !=
==
| Not Equal
Equal
| Left
Left | | +| && | Boolean AND | Left | | +| \|\| | Boolean OR | Left | | -#### Or -```zokrates -{{#include ../../../zokrates_cli/examples/book/or.zok}} -``` -#### Xor - -```zokrates -{{#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 | **
| Power | Left | -| 2 | *
/
| Multiplication
Division
| Left
Left | -| 3 | +
-
| Addition
Subtraction
| Left
Left | -| 4 | >=
>
<=
< | gte
gt
lte
lt | Left
Left
Left
Left| -| 5 | ==
!=
| Equal
Not Equal
| Left
Left | -| 6 | && | And | Left | -| 7 | XOR(a,b) - import from stdlib | Xor | Left | -| 8 | \|\| | Or | Left | \ No newline at end of file +1. The exponent must be a compile-time constant +2. The right operand must be a compile time constant +3. Both operands are be asserted to be strictly lower than the biggest power of 2 lower than `p/2` \ No newline at end of file diff --git a/zokrates_book/src/concepts/stdlib.md b/zokrates_book/src/concepts/stdlib.md index 29c78930..a0e8cd4a 100644 --- a/zokrates_book/src/concepts/stdlib.md +++ b/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. -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. +A function that takes 2 `u32[8]` arrays as inputs and returns their sha256 compression function as a `u32[8]`. +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" +``` diff --git a/zokrates_book/src/concepts/types.md b/zokrates_book/src/concepts/types.md index 9ad99b90..31c5f002 100644 --- a/zokrates_book/src/concepts/types.md +++ b/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: diff --git a/zokrates_book/src/reference/cli.md b/zokrates_book/src/reference/cli.md index 96572d0e..31298601 100644 --- a/zokrates_book/src/reference/cli.md +++ b/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` diff --git a/zokrates_cli/examples/book/add.zok b/zokrates_cli/examples/book/add.zok deleted file mode 100644 index 8321dc10..00000000 --- a/zokrates_cli/examples/book/add.zok +++ /dev/null @@ -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 \ No newline at end of file diff --git a/zokrates_cli/examples/book/and.zok b/zokrates_cli/examples/book/and.zok deleted file mode 100644 index e63da463..00000000 --- a/zokrates_cli/examples/book/and.zok +++ /dev/null @@ -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 \ No newline at end of file diff --git a/zokrates_cli/examples/book/assert.zok b/zokrates_cli/examples/book/assert.zok new file mode 100644 index 00000000..c4277fed --- /dev/null +++ b/zokrates_cli/examples/book/assert.zok @@ -0,0 +1,3 @@ +def main() -> (): + assert(1 == 2) + return \ No newline at end of file diff --git a/zokrates_cli/examples/book/div.zok b/zokrates_cli/examples/book/div.zok deleted file mode 100644 index 6a223445..00000000 --- a/zokrates_cli/examples/book/div.zok +++ /dev/null @@ -1,2 +0,0 @@ -def main(field a, field b, field c) -> (field): - return a / b / c \ No newline at end of file diff --git a/zokrates_cli/examples/book/equal.zok b/zokrates_cli/examples/book/equal.zok deleted file mode 100644 index 9037d5e2..00000000 --- a/zokrates_cli/examples/book/equal.zok +++ /dev/null @@ -1,2 +0,0 @@ -def main(field a, field b) -> (bool): - return a == b \ No newline at end of file diff --git a/zokrates_cli/examples/book/for.zok b/zokrates_cli/examples/book/for.zok index b8f66e91..e774b78f 100644 --- a/zokrates_cli/examples/book/for.zok +++ 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 \ No newline at end of file diff --git a/zokrates_cli/examples/book/gtl.zok b/zokrates_cli/examples/book/gtl.zok deleted file mode 100644 index ac835b0b..00000000 --- a/zokrates_cli/examples/book/gtl.zok +++ /dev/null @@ -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 \ No newline at end of file diff --git a/zokrates_cli/examples/book/hashexample.zok b/zokrates_cli/examples/book/hashexample.zok index 24f1e824..510f45e2 100644 --- a/zokrates_cli/examples/book/hashexample.zok +++ b/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]) diff --git a/zokrates_cli/examples/book/mul.zok b/zokrates_cli/examples/book/mul.zok deleted file mode 100644 index 0651e7d2..00000000 --- a/zokrates_cli/examples/book/mul.zok +++ /dev/null @@ -1,2 +0,0 @@ -def main(field a, field b, field c) -> (field): - return a * b * c \ No newline at end of file diff --git a/zokrates_cli/examples/book/or.zok b/zokrates_cli/examples/book/or.zok deleted file mode 100644 index 80860190..00000000 --- a/zokrates_cli/examples/book/or.zok +++ /dev/null @@ -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 \ No newline at end of file diff --git a/zokrates_cli/examples/book/pow.zok b/zokrates_cli/examples/book/pow.zok deleted file mode 100644 index d5f400ab..00000000 --- a/zokrates_cli/examples/book/pow.zok +++ /dev/null @@ -1,2 +0,0 @@ -def main() -> (field): - return 5**5 \ No newline at end of file diff --git a/zokrates_cli/examples/book/sub.zok b/zokrates_cli/examples/book/sub.zok deleted file mode 100644 index bc891f8b..00000000 --- a/zokrates_cli/examples/book/sub.zok +++ /dev/null @@ -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 \ No newline at end of file diff --git a/zokrates_cli/examples/book/xor.zok b/zokrates_cli/examples/book/xor.zok deleted file mode 100644 index 91e53edf..00000000 --- a/zokrates_cli/examples/book/xor.zok +++ /dev/null @@ -1,4 +0,0 @@ -import "utils/binary/xor" as XOR - -def main(field a, field b) -> (field): - return XOR(a, b) \ No newline at end of file