How to Run Nada by Example

Setup options

All examples for "Nada by Example" live in the nada-by-example Github repo. Nada programs are in nada-by-example/src/ and tests are in nada-by-example/tests. To run examples, there are 2 setup options:

1. Recommended - 1 Click Gitpod Setup
2. Local Machine Setup

1 Click Gitpod Setup

Click the button above to open the Nada by Example repo in Gitpod. Then follow the run and test an example section to learn how to run and test a Nada program.

Local Machine Setup

Complete local repo setup following the instructions below to run an example from the repo locally.

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

If you ran the install.sh script above, then it installed nilup and the latest version of the SDK for you. If you did not, then install and use the latest version of the Nillion SDK and tools by running:

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 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

info

You'll need python3 version 3.11 or higher with a working pip 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

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 that compiles programs to create one compiled binary (.nada.bin) file per program listed in the nada-project.toml file 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

tip

The nada-by-example repo is a Nada project created with Nillion's nada tool. You can run all existing nada commands found in the nada tool docs to compile programs, get program requirements, run a program, and test a program.

Every Nada program example has a corresponding test file. Programs are in nada-by-example/src/ and test files are in nada-by-example/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 <test-file-name>

Test any program with the inputs and outputs specified in the test file with nada test

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 and the test file is tests/addition_test.yaml

Nada program

src/addition.py

loading...

View on GitHub

Test file

tests/addition_test.yaml

loading...

View on GitHub

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 and the test file is tests/addition_test.yaml

Nada program

src/addition.py

loading...

View on GitHub

Test file

tests/addition_test.yaml

loading...

View on GitHub

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 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:

---
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. Keep exploring what's possible with Nada by running the rest of the programs in the repo.