[Book] Examples (#85)

* - Added custom arguments to basic
- Added comments to test basic test program
- Created a cript to generate documentation based on comments + test_files folder structure
- A bit of cleanup in test data generation scripts + support for arguments

This resolves issue #32

docs/pages/example.md

@@ -0,0 +1,220 @@
+---
+title: Examples
+---
+
+## Table of content:
+
+| Name | Description | Src   | Args  | Memory | Trace | Private Input | Public Input | Proof | Prover config | Prover Params |
+| :--- | :---        | :---: | :---: | :---:  | :---: | :---:         | :---:        | :---: | :---:         | :---:         |
+| [Basic](#basic-arrow_up) | Linear function calculation | [link]() |  [link](/./e2e_test/Cairo/basic_args.json)  | [link](/./test_files/basic/memory.b) | [link](/./test_files/basic/trace.b) | [link](/./test_files/basic/private_input.json) | [link](/./test_files/basic/public_input.json) | [link](/./test_files/basic/proof.json) | [link](/./test_files/cpu_air_prover_config.json) | [link](/./test_files/cpu_air_params.json) |
+| [Hash poseidon](#hash-poseidon-arrow_up) | Calculate Poseidon hash | [link]() |  :x:  | [link](/./test_files/hash_poseidon/memory.b) | [link](/./test_files/hash_poseidon/trace.b) | [link](/./test_files/hash_poseidon/private_input.json) | [link](/./test_files/hash_poseidon/public_input.json) | [link](/./test_files/hash_poseidon/proof.json) | [link](/./test_files/cpu_air_prover_config.json) | [link](/./test_files/hash_poseidon_cpu_air_params.json) |
+| [Fibonacci](#fibonacci-arrow_up) | Fibonacci number calculation | [link]() |  [link](/./e2e_test/Cairo/fibonacci_args.json)  | [link](/./test_files/fibonacci/memory.b) | [link](/./test_files/fibonacci/trace.b) | [link](/./test_files/fibonacci/private_input.json) | [link](/./test_files/fibonacci/public_input.json) | [link](/./test_files/fibonacci/proof.json) | [link](/./test_files/cpu_air_prover_config.json) | [link](/./test_files/cpu_air_params.json) |
+| [Ecdsa](#ecdsa-arrow_up) | ECDSA signature verification using STARK-curve | [link]() |  [link](/./e2e_test/Cairo/ecdsa_args.json)  | [link](/./test_files/ecdsa/memory.b) | [link](/./test_files/ecdsa/trace.b) | [link](/./test_files/ecdsa/private_input.json) | [link](/./test_files/ecdsa/public_input.json) | [link](/./test_files/ecdsa/proof.json) | [link](/./test_files/cpu_air_prover_config.json) | [link](/./test_files/ecdsa_cpu_air_params.json) |
+| [Hash pedersen](#hash-pedersen-arrow_up) | Calculate Pedersen hash | [link]() |  :x:  | [link](/./test_files/hash_pedersen/memory.b) | [link](/./test_files/hash_pedersen/trace.b) | [link](/./test_files/hash_pedersen/private_input.json) | [link](/./test_files/hash_pedersen/public_input.json) | [link](/./test_files/hash_pedersen/proof.json) | [link](/./test_files/cpu_air_prover_config.json) | [link](/./test_files/hash_pedersen_cpu_air_params.json) |
+
+
+
+## Basic [:arrow_up:](#table-of-content)
+
+([src](/))
+([input arguments](//./e2e_test/Cairo/basic_args.json))
+
+This program calculates value of a basic linear function using equation:
+
+    y = a*x + b
+
+where:
+
+    a = 12345678901234567890
+    b = 98765432109876543210
+
+
+**Outputs Format**: 
+
+    [ y ] as Array<felt252>
+
+**Memory Layout**: 
+
+    basic
+
+**Arguments Format**: ([arguments file](/./e2e_test/Cairo/basic_args.json))
+
+    [ x ] as Array<felt252>
+
+**Execution traces**:
+
+[Memory File](/./test_files/basic/memory.b)
+
+[Trace File](/./test_files/basic/trace.b)
+
+[Private Input](/./test_files/basic/private_input.json)
+
+[Public Input](/./test_files/basic/public_input.json)
+
+[Proof](/./test_files/basic/proof.json)
+
+[Prover Config](/./test_files/cpu_air_prover_config.json)
+
+[Prover Params](/./test_files/cpu_air_params.json)
+
+
+## Hash poseidon [:arrow_up:](#table-of-content)
+
+([src](/))
+([input arguments](/None))
+
+This program calculates Poseidon hash of the struct. For the struct definition see below.
+
+    StructForHash { first: 0, second: 1, third: (1, 2), last: false };
+
+
+
+**Outputs Format**: 
+
+    [ hashValue ] as Array<felt252>
+
+**Memory Layout**: 
+
+    recursive_with_poseidon
+
+**Arguments Format**: ([arguments file](None))
+
+    None
+
+**Execution traces**:
+
+[Memory File](/./test_files/hash_poseidon/memory.b)
+
+[Trace File](/./test_files/hash_poseidon/trace.b)
+
+[Private Input](/./test_files/hash_poseidon/private_input.json)
+
+[Public Input](/./test_files/hash_poseidon/public_input.json)
+
+[Proof](/./test_files/hash_poseidon/proof.json)
+
+[Prover Config](/./test_files/cpu_air_prover_config.json)
+
+[Prover Params](/./test_files/hash_poseidon_cpu_air_params.json)
+
+
+## Fibonacci [:arrow_up:](#table-of-content)
+
+([src](/))
+([input arguments](//./e2e_test/Cairo/fibonacci_args.json))
+
+This program calculates Nth Fibonacci number using recursion.
+
+
+**Outputs Format**: 
+
+    [ nth_number ] as Array<felt252>
+
+**Memory Layout**: 
+
+    small
+
+**Arguments Format**: ([arguments file](/./e2e_test/Cairo/fibonacci_args.json))
+
+    [ n ] as Array<felt252>
+
+**Execution traces**:
+
+[Memory File](/./test_files/fibonacci/memory.b)
+
+[Trace File](/./test_files/fibonacci/trace.b)
+
+[Private Input](/./test_files/fibonacci/private_input.json)
+
+[Public Input](/./test_files/fibonacci/public_input.json)
+
+[Proof](/./test_files/fibonacci/proof.json)
+
+[Prover Config](/./test_files/cpu_air_prover_config.json)
+
+[Prover Params](/./test_files/cpu_air_params.json)
+
+
+## Ecdsa [:arrow_up:](#table-of-content)
+
+([src](/))
+([input arguments](//./e2e_test/Cairo/ecdsa_args.json))
+
+This program calculates and checks the ECDSA signature using the STARK-curve.
+IMPORTANT: It's not safe! Some important checks are omitted. 
+Check `check_ecdsa_signature`` function comment.
+Returns 1 if the signature is correct, 0 otherwise.
+
+
+**Outputs Format**: 
+
+    [ 0 or 1 ] as Array<felt252>
+
+**Memory Layout**: 
+
+    all_cairo
+
+**Arguments Format**: ([arguments file](/./e2e_test/Cairo/ecdsa_args.json))
+
+    [hash, public_key, r, s] as Array<felt252>
+
+**Execution traces**:
+
+[Memory File](/./test_files/ecdsa/memory.b)
+
+[Trace File](/./test_files/ecdsa/trace.b)
+
+[Private Input](/./test_files/ecdsa/private_input.json)
+
+[Public Input](/./test_files/ecdsa/public_input.json)
+
+[Proof](/./test_files/ecdsa/proof.json)
+
+[Prover Config](/./test_files/cpu_air_prover_config.json)
+
+[Prover Params](/./test_files/ecdsa_cpu_air_params.json)
+
+
+## Hash pedersen [:arrow_up:](#table-of-content)
+
+([src](/))
+([input arguments](/None))
+
+This program calculates Pedersen hash of the struct. For the struct definition see below.
+
+    StructForHash { first: 0, second: 1, third: (1, 2), last: false };
+
+
+
+**Outputs Format**: 
+
+    [ hashValue ] as Array<felt252>
+
+**Memory Layout**: 
+
+    recursive_large_output
+
+**Arguments Format**: ([arguments file](None))
+
+    None
+
+**Execution traces**:
+
+[Memory File](/./test_files/hash_pedersen/memory.b)
+
+[Trace File](/./test_files/hash_pedersen/trace.b)
+
+[Private Input](/./test_files/hash_pedersen/private_input.json)
+
+[Public Input](/./test_files/hash_pedersen/public_input.json)
+
+[Proof](/./test_files/hash_pedersen/proof.json)
+
+[Prover Config](/./test_files/cpu_air_prover_config.json)
+
+[Prover Params](/./test_files/hash_pedersen_cpu_air_params.json)
+
+
+
+
+

e2e_test/Cairo/basic.cairo

@@ -1,18 +1,38 @@
-// layout - small
-// can't check modulus application because it is not implemented!
-// only range check is used
+//! Linear function calculation
+//!
+//! This program calculates value of a basic linear function using equation:
+//!
+//!     y = a*x + b
+//!
+//! where:
+//!
+//!     a = 12345678901234567890
+//!     b = 98765432109876543210
+//!
+//! Input arguments:
+//!
+//!     [ x ] as Array<felt252>
+//!    
+//! Output values: 
+//!
+//!     [ y ] as Array<felt252>
+//!
+//! Memory layout:
+//!
+//!     basic
+//!
+
 
 use core::felt252;
 
-fn main() -> Array<felt252> {
+fn main(input: Array<felt252>) -> Array<felt252> {
+    assert!(input.len() > 0, "x argument must be specified");
+
+    let x = *input.at(0);
     let a = 12345678901234567890;
     let b = 98765432109876543210;
 
     let mut result = array![];
-    if (a * b) == 1219326311370217952237463801111263526900 {
-        result.append(1);
-    } else {
-        result.append(0);
-    }
+    result.append(x * a + b);
     result
 }

e2e_test/Cairo/basic_args.json

@@ -0,0 +1 @@
+[10]

e2e_test/Cairo/bitwise.cairo

@@ -1,5 +1,6 @@
 // layout - small
 // can't check & is not implemented for felt252
+// does not compile
 
 use core::felt252;
 

e2e_test/Cairo/ecdsa.cairo

@@ -1,21 +1,42 @@
-// layout - all_cairo
+//! ECDSA signature verification using STARK-curve
+//!
+//! This program calculates and checks the ECDSA signature using the STARK-curve.
+//! IMPORTANT: It's not safe! Some important checks are omitted. 
+//! Check `check_ecdsa_signature`` function comment.
+//! Returns 1 if the signature is correct, 0 otherwise.
+//!
+//! Input arguments:
+//!
+//!     [hash, public_key, r, s] as Array<felt252>
+//!    
+//! Output values: 
+//!
+//!    [ 0 or 1 ] as Array<felt252>
+//!
+//! Memory layout:
+//!
+//!     all_cairo
+//!
 
 use core::felt252;
 use core::pedersen::PedersenTrait;
 use core::hash::{HashStateTrait, HashStateExTrait};
 use core::ecdsa::check_ecdsa_signature;
 
-fn main() -> Array<felt252> {
-    let message_hash = 0x503f4bea29baee10b22a7f10bdc82dda071c977c1f25b8f3973d34e6b03b2c;
-    let public_key = 0x7b7454acbe7845da996377f85eb0892044d75ae95d04d3325a391951f35d2ec;
-    let signature_r = 0xbe96d72eb4f94078192c2e84d5230cde2a70f4b45c8797e2c907acff5060bb;
-    let signature_s = 0x677ae6bba6daf00d2631fab14c8acf24be6579f9d9e98f67aa7f2770e57a1f5;
+
+fn main(args: Array<felt252>) -> Array<felt252> {
+    assert!(args.len() == 4, "Expected 4 arguments: hash, public_key, r, s");
+
+    let hash = *args.at(0);
+    let public_key = *args.at(1);
+    let r = *args.at(2);
+    let s = *args.at(3);
 
     let mut result = array![];
-    if check_ecdsa_signature(message_hash, public_key, signature_r, signature_s) {
-        result.append(1);
+    if check_ecdsa_signature(hash, public_key, r, s) {
+        result.append(1);    
     } else {
-        result.append(0);
+        result.append(0);    
     }
     result
 }

e2e_test/Cairo/ecdsa_args.json

@@ -0,0 +1,6 @@
+[
+    141784621858361645174009804296757185726381639603648306606182704733930666796
+    3490001189944926769628658346285649224182856084131963744896357527096042836716
+    336742005567258698661916498343089167447076063081786685068305785816009957563
+    2925335700420068477532893136360799683220922576143466479208174349948949078517
+]

e2e_test/Cairo/fibonacci.cairo

@@ -1,7 +1,27 @@
+//! Fibonacci number calculation
+//!
+//! This program calculates Nth Fibonacci number using recursion.
+//!
+//! Input arguments:
+//!
+//!     [ n ] as Array<felt252>
+//!    
+//! Output values: 
+//!
+//!     [ nth_number ] as Array<felt252>
+//!
+//! Memory layout:
+//!
+//!     small
+//!
+
+
 use core::felt252;
 
-fn main() -> Array<felt252> {
-    let n = 10;
+fn main(args: Array<felt252>) -> Array<felt252> {
+    assert!(args.len() > 0, "Expected n as argument");
+
+    let n = *args.at(0);
     let mut result = array![];
     result.append(fib(1, 1, n));
     result