Skip to main content

JavaScript Developer Quickstart

Start building on Nillion. The quickstart walks you through

  1. Installing the Nillion SDK
  2. Setting up a developer environment
  3. Running nillion-devnet, a local Nillion network
  4. Writing your first Nada program, tiny_secret_addition.py
  5. Connecting to the network with the NillionClient to store programs, store secrets, and compute on programs with stored secrets.

Install the Nillion SDK tools​

  1. Install nilup the Nillion SDK tool installer and version manager. Binaries are available for Linux and macOS platforms

    For the security-conscious, please download the install.sh script, so that you can inspect how it works, before piping it to bash.

    curl https://nilup.nilogy.xyz/install.sh | bash

    Confirm global nilup tool installation

    nilup -V

  2. Use nilup to install the latest version of the Nillion SDK.

    nilup install latest
    nilup use latest
    nilup init

    Optionally enable nilup telemetry, providing your Ethereum wallet address. We collect this data to understand how the software is used, and to better assist you in case of issues.In doing this, you consent to the collection of telemetry data by the Nillion Network. While we will not collect any personal information, we still recommend using a new wallet address that cannot be linked to your identity by any third party. For more information, check out our privacy policy.

    nilup instrumentation enable --wallet <your-eth-wallet-address>

    Confirm global Nillion tool installation

    nillion -V

Clone the Scaffold-Nillion JavaScript starter repo​

The Scaffold-Nillion Starter Repo repo has everything you need to start building. Clone the repo:

git clone https://github.com/NillionNetwork/scaffold-nillion.git

Install repo dependencies​

Before you use Scaffold-Nillion, you need to install the following:

  • Node (>= v18.17)

    • Check version with 
      node -v

  • python3 version 3.11 or higher with a working pip installed

    • Confirm that you have python3 (version >=3.11) and pip installed: 
      python3 --version
      python3 -m pip --version

  • Yarn (v1 or v2+)

    • Check version with 
      yarn -v

  • Git

  • anvil tool from foundry, which can be installed with:

    # install Foundryup, the Foundry toolchain installer
    curl -L https://foundry.paradigm.xyz | bash

    # after installation, use the foundryup commmand to install the binaries including Anvil
    foundryup

  • pidof

  • grep

Install MetaMask Flask and to store a Nillion user key in MetaMask Snaps​

  1. Install the MetaMask Flask browser extension that will let you work with experimental snaps.
  2. Create a new test wallet in MetaMask Flask
  3. Temporarily disable any other wallet browser extensions (Classic MetaMask, Rainbow Wallet, etc.) while using MetaMask Flask
  4. Visit the Nillion Key Management UI to generate a user key and store it in MetaMask Snaps - this saves your user key within MetaMask so it can be used by other Nillion web apps

Run the starter​

1. Enter the scaffold-nillion folder​

cd scaffold-nillion
yarn install

2. Run a local ethereum network in the first terminal:​

yarn chain

This command starts a local Ethereum network using Hardhat. The network runs on your local machine and can be used for testing and development.

3. Open a second terminal and deploy the test ethereum contract:​

yarn deploy

This command deploys a test smart contract to the local network.

4. Open a third terminal to run the Nillion devnet:​

This bootstraps nillion-devnet, a local network of nodes and adds cluster info to your NextJS app .env file

yarn nillion-devnet

5. Open another terminal to create and activate a python virtual environment for Nada program development​

cd packages/nillion && bash create-venv.sh && source .venv/bin/activate

The nada tool was used to initiate a project inside of packages/nillion/next-project-programs. Create a new Nada program tiny_secret_addition.py in next-project-programs/src

cd next-project-programs
touch src/tiny_secret_addition.py

Write a Nada program​

The Nillion Network uses Nada, our MPC language, to define MPC programs. The first implementation of Nada is a Python DSL (Domain Specific Language), called Nada. Let's write a tiny Nada program that adds two secret numbers. Here's the code for the finished program we'll write line by line:

programs/tiny_secret_addition_complete.py
loading...

Open the file and import nada_dsl

from nada_dsl import *

Create a function called nada_main() that will contain the code you want to run

from nada_dsl import *
def nada_main():

Add a party​

In Nada you have to declare the parties involved in the computation through the Party type. A Party is defined with a name.

info

Here's an example of a Party

Party(name="Steph")

Create party1, a Party named "Party1"

from nada_dsl import *
def nada_main():

    party1 = Party(name="Party1")

Learn about inputs​

Nada programs have inputs. An Input is defined with a name and a party, which is the Party providing the input.

info

Here's an example of an Input:

Input(name="numberOfDogs", party=Party(name="Steph"))

Nada program inputs are typed. There are a few categories of types

Secrecy level

  • Public: visible to all nodes
  • Secret: secret values to be handled by the computing nodes as shares or particles

Scalar

  • Integer
  • String

These categories are combined into types like SecretInteger, which are used to type an Input. See all types

info

Here's an example of a SecretInteger Input provided by Steph

steph = Party(name="Steph")
stephs_secret_int = SecretInteger(Input(name="numberOfDogs", party=steph))

Create 2 secret integers inputs​

  • my_int1, a SecretInteger named "my_int1" owned by Party1
  • my_int2, a SecretInteger named "my_int2" owned by Party1
from nada_dsl import *

def nada_main():
    party1 = Party(name="Party1")
    my_int1 = SecretInteger(Input(name="my_int1", party=party1))
    my_int2 = SecretInteger(Input(name="my_int2", party=party1))

Add the integers by creating a new variable called new_int and setting it equal to my_int1 + my_int2

from nada_dsl import *

def nada_main():
    party1 = Party(name="Party1")
    my_int1 = SecretInteger(Input(name="my_int1", party=party1))
    my_int2 = SecretInteger(Input(name="my_int2", party=party1))

    new_int = my_int1 + my_int2

Finally, Nada programs return an output. The Output type is used to declare a named output that will be revealed to a concrete Party. The Output has a name and a party as parameters.

Return the output​

Nada programs return an array of outputs.

info

Here's an example of an output. The output is named total_score, its value is score_int, and it can be read by the party named Steph.

Output(score_int, "total_score", Party(name="Steph"))

Complete your Nada program by adding a final line that returns an array with one output. The output is named "my_output", its value is new_int, and it can be ready by party1.

Resulting Nada program​

programs/tiny_secret_addition_complete.py
loading...

🎉 You just wrote your first Nada program! Next, let's compile the program.

Compile the Nada program​

Add the program path, name, and a prime size to your nada-project.toml file

[[programs]]
path = "src/tiny_secret_addition.py"
name = "tiny_secret_addition"
prime_size = 128

Run the build command from the next-project-programs folder to build all programs added to the nada-project.toml file, creating nada.bin files for each Nada program.

nada build

Copy the tiny_secret_addition.nada.bin program binary file into nextjs public programs folder for eventual use in your web app.

cp target/tiny_secret_addition.nada.bin ../../nextjs/public/programs

Copy the tiny_secret_addition.py program file into nextjs public programs folder for eventual use in your web app.

cp src/tiny_secret_addition.py ../../nextjs/public/programs

Now the NextJs app has the Nada program and binaries in the nextjs/public/programs folder, where the program can be stored using the JavaScript Client.

Spin up the NextJs Web App​

Open one more terminal to start your NextJS web app from the root directory, scaffold-nillion

yarn start

Open your app on: http://localhost:3000

  • Visit the Nillion Blind Computation page to try out the Blind Computation Demo: http://localhost:3000/nillion-compute
  • Edit the code for this page in packages/nextjs/app/nillion-compute/page.tsx to set the programName to "tiny_secret_addition". Now the page will store and compute with the tiny_secret_addition.py program you wrote. 
    const [programName] = useState<string>('tiny_secret_addition');

Complete the TODOs in the Hello World page to hook up a working Nillion store and retrieve example​

  • Visit the Nillion Hello World page: http://localhost:3000/nillion-hello-world
  • Notice that the buttons and functionality for this page are not hooked up yet.
  • Edit the code for this page in packages/nextjs/app/nillion-hello-world/page.tsx to complete each of the 🎯 TODOs to get the page working
  • Need a hint on how to get something working? Take a look at the completed packages/nextjs/app/nillion-hello-world-complete/page.tsx page
tip

Open the Nillion JavaScript Client Reference doc in another tab to search for available classes while completing the 🎯 TODOs.

Keep exploring​

You've successfully written your first single party Nada program, stored the program on the network, stored secrets on the network, and run compute against secrets. Keep exploring by