Merge pull request #71 from NillionNetwork/feature/nada-by-example

Add "Nada by Example" Portal to the docs

docs/_data-types-table.mdx

@@ -0,0 +1,4 @@
+| [Secret](/nada-by-example/secret-data-type)                | [Public](/nada-by-example/public-data-type)                | [Literals](/nada-by-example/literal-data-type)        |
+| ----------------------- | ----------------------- | ----------------- |
+| `SecretInteger`         | `PublicInteger`         | `Integer`         |
+| `SecretUnsignedInteger` | `PublicUnsignedInteger` | `UnsignedInteger` |

docs/_operations-table.mdx

@@ -0,0 +1,17 @@
+
+| Operation with linked example                                                                    | Syntax                                              | Supported Types<br/> (`P: Public`, `S: Secret`)                                                           |
+| ----------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| [Addition](/nada-by-example/addition)                                                                | `x + y`                                             | `P ← P + P`,<br/> `S ← P + S`,<br/> `S ← S + P`,<br/> `S ← S + S`                                         |
+| [Subtraction](/nada-by-example/subtraction)                                                             | `x - y`                                             | `P ← P - P`,<br/> `S ← P - S`,<br/> `S ← S - P`,<br/> `S ← S - S`                                         |
+| [Multiplication](/nada-by-example/multiplication)                                                          | `x * y`                                             | `P ← P * P`,<br/> `S ← P * S`,<br/> `S ← S * P`,<br/> `S ← S * S`                                         |
+| [Power](/nada-by-example/power)                                                                   | `x ** y`                                            | `P ← P ** P`                                                                                              |
+| [Division](/nada-by-example/division)                                                                | `x / y`                                             | `P ← P / P`,<br/> `S ← P / S`,<br/> `S ← S / P`,<br/> `S ← S / S`                                         |
+| [Modulo](/nada-by-example/modulo)                                                                  | `x % y`                                             | `P ← P % P`,<br/> `S ← P % S`,<br/> `S ← S % P`,<br/> `S ← S % S`                                         |
+| [Left shift](/nada-by-example/shift-left) and [Right shift](/nada-by-example/shift-right)                                                                  | `x << y`,<br/> `x >> y`                             | `P ← P << P`,<br/> `S ← S << P`                                                                           |
+| [Probabilistic truncation](/nada-by-example/probabilistic-truncation)                                                | `x.trunc_pr(y)`                                     | `S ← S.trunc_pr(P)`                                                                                       |
+| [Comparisons](/nada-by-example/comparison)                                                             | `x < y`,<br/> `x <= y`,<br/> `x > y`,<br/> `x >= y` | `P ← P < P`,<br/> `S ← P < S`,<br/> `S ← S < P`,<br/> `S ← S < S`                                         |
+| [Ternary](/nada-by-example/if-else) _"if else"_<br/> (public condition)                             | `cond.if_else(x, y)`                                | `P ← P.if_else(P, P)`,<br/> `S ← P.if_else(P, S)`,<br/> `S ← P.if_else(S, P)`,<br/> `S ← P.if_else(S, S)` |
+| [Ternary](/nada-by-example/if-else) _"if else"_<br/> (secret condition)                             | `cond.if_else(x, y)`                                | `S ← S.if_else(P, P)`,<br/> `S ← S.if_else(P, S)`,<br/> `S ← S.if_else(S, P)`,<br/> `S ← S.if_else(S, S)` |
+| [Reveal](/nada-by-example/reveal) <br/> (convert a private<br/> value into a public value)         | `x.reveal()`                                        | `P ← S.reveal()`                                                                                          |
+| [Equality](/nada-by-example/equality)                                                                | `x == y`                                            | `S ← S == S`,<br/> `S ← S == P`,<br/> `S ← P == S`,<br/> `P ← P == P`                                     |
+| [Public Output Equality](/nada-by-example/equality) <br/> (publicly output if two secrets are equal) | `x.public_equals(y)`                                | `P ← S.public_equals(S)`                                                                                  |

docs/_python-version-info.mdx

@@ -0,0 +1,10 @@
+:::info
+
+You'll need [python3](https://www.python.org/downloads/) version 3.11 or higher with a working [pip](https://pip.pypa.io/en/stable/getting-started/) installed to import the nada_dsl dependency. Before setting up your Python virtual environment, confirm that you have python3 (version >=3.11) and pip installed
+
+```
+python3 --version
+python3 -m pip --version
+```
+
+:::

docs/nada-by-example-quickstart.md

@@ -0,0 +1,227 @@
+---
+displayed_sidebar: nadaByExampleSidebar
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import PythonVersionInfo from './\_python-version-info.mdx';
+
+# Nada by Example Local Setup Guide
+
+All examples for "Nada by Example" live in the [nada-by-example](https://github.com/NillionNetwork/nada-by-example) Github repo. Nada programs are in [`nada-by-example/src/`](https://github.com/NillionNetwork/nada-by-example/tree/main/src) and tests are in [`nada-by-example/tests`](https://github.com/NillionNetwork/nada-by-example/tree/main/tests). After you complete local repo setup following the instructions below, you can run an example from the repo locally.
+
+:::tip
+
+The [nada-by-example](https://github.com/NillionNetwork/nada-by-example) repo is a Nada project created with Nillion's [nada](/nada) tool. You can run all existing `nada` commands found in the [nada tool docs](/nada) to compile programs, get program requirements, run a program, and test a program.
+:::
+
+
+## Repo setup instructions
+
+Install Nillion, clone the nada-by-example repo, and set up a developer environment for your local nada-by-example repo.
+
+#### 1. Install Nillion globally
+
+Check to see if you have `nilup`, the Nillion installer installed
+
+```
+nilup -V
+```
+
+If you don't have nilup, install nilup
+
+```
+curl https://nilup.nilogy.xyz/install.sh | bash
+```
+
+#### 2. Use the latest version of the Nillion SDK
+
+Install and use the `latest` version of the Nillion SDK and tools.
+
+```
+nilup install latest
+nilup use latest
+```
+
+#### 3. Optionally enable nilup telemetry, providing your Ethereum wallet address
+
+```
+nilup instrumentation enable --wallet <your-eth-wallet-address>
+```
+
+#### 4. Clone the nada-by-example repo
+
+Star [nada-by-example](https://github.com/NillionNetwork/nada-by-example) on Github so you have it for future reference. Then clone the repo
+
+```
+git clone https://github.com/NillionNetwork/nada-by-example.git
+```
+
+#### 5. Create a Python virtual environment and install Nada in nada-by-example
+
+<PythonVersionInfo/>
+
+```
+cd nada-by-example
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+#### 6. Build (compile) all Nada programs in the repo
+
+```
+nada build
+```
+
+`nada build` is a [nada tool command](/nada#build-compile-a-program) that compiles programs to create one compiled binary (.nada.bin) file per program listed in the [nada-project.toml file](https://github.com/NillionNetwork/nada-by-example/blob/main/nada-project.toml) in the target/ directory.
+
+
+✅ Great work! Now that you've set up the nada-by-example repo, you can run any example.
+
+## How to run and test an example program
+
+Every Nada program example has a corresponding test file. Programs are in [`nada-by-example/src/`](https://github.com/NillionNetwork/nada-by-example/tree/main/src) and test files are in [`nada-by-example/tests`](https://github.com/NillionNetwork/nada-by-example/tree/main/tests). Running a program uses the inputs specified in the test file. Testing a program uses the inputs specified in the test file and also checks the outputs against the `expected_outputs` specified in the test file.
+
+
+Run any program with the inputs specified in the test file with [`nada run`](/nada#run-a-program)
+
+```
+nada run <test-file-name>
+```
+
+Test any program with the inputs and outputs specified in the test file with [`nada test`](/nada#test-a-program)
+
+```
+nada test <test-file-name>
+```
+
+
+### Run the addition example 
+
+Here is the Nada program and test file for the addition example. The program is [src/addition.py](https://github.com/NillionNetwork/nada-by-example/blob/main/src/addition.py) and the test file is [tests/addition_test.yaml](https://github.com/NillionNetwork/nada-by-example/blob/main/tests/addition_test.yaml)
+
+<Tabs>
+
+<TabItem value="program" label="Nada program" default>
+```python reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/src/addition.py
+```
+</TabItem>
+
+<TabItem value="test" label="Test file">
+```yaml reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/tests/addition_test.yaml
+```
+</TabItem>
+</Tabs>
+
+Run the addition program with `addition_test` test inputs:
+
+```
+nada run addition_test
+```
+
+The result of running this program is
+
+```
+(.venv) ➜  nada-by-example git:(main) nada run addition_test
+Running program 'addition' with inputs from test file addition_test
+Building ...
+Running ...
+Program ran!
+Outputs: {
+    "sum": SecretInteger(
+        NadaInt(
+            40,
+        ),
+    ),
+}
+```
+
+### Test the addition example 
+
+Here is the Nada program and test file for the addition example. The program is [src/addition.py](https://github.com/NillionNetwork/nada-by-example/blob/main/src/addition.py) and the test file is [tests/addition_test.yaml](https://github.com/NillionNetwork/nada-by-example/blob/main/tests/addition_test.yaml)
+
+<Tabs>
+
+<TabItem value="program" label="Nada program" default>
+```python reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/src/addition.py
+```
+</TabItem>
+
+<TabItem value="test" label="Test file">
+```yaml reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/tests/addition_test.yaml
+```
+</TabItem>
+</Tabs>
+
+Test the addition program with `addition_test` test inputs and expected outputs:
+
+```
+nada test addition_test
+```
+
+The result of testing this program is
+
+```
+(.venv) ➜  nada-by-example git:(main) nada test addition_test
+Running test: addition_test
+Building ...
+Running ...
+addition_test: PASS
+```
+
+Testing the addition program with `addition_test` results in a PASS because the expected_outputs `sum` output matches the run result.
+
+### Add a new test for the addition example 
+
+Use the [nada tool](/nada#generate-a-test-file) to add a new test file named "addition_test_2" for the addition example.
+
+```
+nada generate-test --test-name addition_test_2 addition
+```
+
+This results in a new test file: `/tests/addition_test_2.yaml`
+
+```
+(.venv) ➜  nada-by-example git:(main) nada generate-test --test-name addition_test_2 addition
+Generating test 'addition_test_2' for
+Building ...
+Generating test file ...
+Test generated!
+```
+
+Update the values in the test file to anything you want, for example:
+
+```yaml
+---
+program: addition
+inputs:
+  num_1:
+    SecretInteger: "100"
+  num_2:
+    SecretInteger: "10"
+expected_outputs:
+  sum:
+    SecretInteger: "110"
+
+```
+
+#### Run addition with your new test
+
+```
+nada run addition_test_2
+```
+
+#### Test addition with your new test
+
+```
+nada test addition_test_2
+```
+
+## Keep exploring examples
+
+🥳 You're all set up to run and test any example in [nada-by-example](https://github.com/NillionNetwork/nada-by-example). Keep exploring what's possible with Nada by running the rest of the programs in the repo.

docs/nada-by-example.md

@@ -0,0 +1,11 @@
+---
+displayed_sidebar: nadaByExampleSidebar
+---
+
+# Nada by Example
+
+Welcome to **Nada by Example**, an introduction to the Nada language with reference examples from the [nada-by-example](https://github.com/NillionNetwork/nada-by-example) repo. [Nada DSL](https://pypi.org/project/nada-dsl) is a Python-based language for defining MPC (Multi-Party Compute) programs on the [Nillion Network](/network). 
+
+Developers can use Nada to write programs that handle secret inputs from multiple parties (i.e., multiple users). These programs compute in a way that ensures they are “blind” to the underlying data, meaning they cannot access or view the secret inputs. This concept is known as “blind computation.”
+
+To learn more about Nada, check out the full [Nada language docs here](/nada-lang).

docs/nada-by-example/addition.md

@@ -0,0 +1,20 @@
+# Addition
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+<Tabs>
+
+<TabItem value="program" label="Nada program" default>
+```python reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/src/addition.py
+```
+</TabItem>
+
+<TabItem value="test" label="Test file">
+```yaml reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/tests/addition_test.yaml
+```
+</TabItem>
+</Tabs>

docs/nada-by-example/comparison.md

@@ -0,0 +1,75 @@
+# Comparison
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Less than `<`
+
+<Tabs>
+
+<TabItem value="program" label="Nada program" default>
+```python reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/src/comparison_lt.py
+```
+</TabItem>
+
+<TabItem value="test" label="Test file">
+```yaml reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/tests/comparison_lt_test.yaml
+```
+</TabItem>
+</Tabs>
+
+## Less than or equal to `<=`
+
+<Tabs>
+
+<TabItem value="program" label="Nada program" default>
+```python reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/src/comparison_lte.py
+```
+</TabItem>
+
+<TabItem value="test" label="Test file">
+```yaml reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/tests/comparison_lte_test.yaml
+```
+</TabItem>
+</Tabs>
+
+## Greater than `>`
+
+<Tabs>
+
+<TabItem value="program" label="Nada program" default>
+```python reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/src/comparison_gt.py
+```
+</TabItem>
+
+<TabItem value="test" label="Test file">
+```yaml reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/tests/comparison_gt_test.yaml
+```
+</TabItem>
+</Tabs>
+
+## Greater than or equal to `>=`
+
+<Tabs>
+
+<TabItem value="program" label="Nada program" default>
+```python reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/src/comparison_gte.py
+```
+</TabItem>
+
+<TabItem value="test" label="Test file">
+```yaml reference showGithubLink
+https://github.com/NillionNetwork/nada-by-example/blob/main/tests/comparison_gte_test.yaml
+```
+</TabItem>
+</Tabs>
+
+
+