/snarkOS

A Decentralized Operating System for ZK Applications

Primary LanguageRustApache License 2.0Apache-2.0

snarkOS

Table of Contents

1. Overview

snarkOS is a decentralized operating system for zero-knowledge applications. This code forms the backbone of Aleo network, which verifies transactions and stores the encrypted state applications in a publicly-verifiable manner.

2. Build Guide

2.1 Requirements

The following are minimum requirements to run an Aleo node:

  • OS: 64-bit architectures only, latest up-to-date for security
    • Clients: Ubuntu 22.04 (LTS), macOS Ventura or later, Windows 11 or later
    • Provers: Ubuntu 22.04 (LTS), macOS Ventura or later
    • Validators: Ubuntu 22.04 (LTS)
  • CPU: 64-bit architectures only
    • Clients: 16-cores
    • Provers: 32-cores (64-cores preferred)
    • Validators: 32-cores (64-cores preferred)
  • RAM: DDR4 or better
    • Clients: 16GB of memory
    • Provers: 32GB of memory (64GB or larger preferred)
    • Validators: 64GB of memory (128GB or larger preferred)
  • Storage: PCIe Gen 3 x4, PCIe Gen 4 x2 NVME SSD, or better
    • Clients: 64GB of disk space
    • Provers: 128GB of disk space
    • Validators: 2TB of disk space (4TB or larger preferred)
  • Network: Symmetric, commercial, always-on
    • Clients: 100Mbps of upload and download bandwidth
    • Provers: 250Mbps of upload and download bandwidth
    • Validators: 500Mbps of upload and download bandwidth
  • GPU:
    • Clients: Not required at this time
    • Provers: CUDA-enabled GPU (optional)
    • Validators: Not required at this time

Please note to run an Aleo Prover that is competitive, the machine will require more than these requirements.

2.2 Installation

Before beginning, please ensure your machine has Rust v1.66+ installed. Instructions to install Rust can be found here.

Start by cloning this Github repository:

git clone https://github.com/AleoHQ/snarkOS.git --depth 1

Next, move into the snarkOS directory:

cd snarkOS

[For Ubuntu users] A helper script to install dependencies is available. From the snarkOS directory, run:

./build_ubuntu.sh

Lastly, install snarkOS:

cargo install --path .

Please ensure ports 4133/tcp and 3033/tcp are open on your router and OS firewall.

3. Run an Aleo Node

3a. Run an Aleo Client

Start by following the instructions in the Build Guide.

Next, to start a client node, from the snarkOS directory, run:

./run-client.sh

3b. Run an Aleo Prover

Start by following the instructions in the Build Guide.

Next, generate an Aleo account address:

snarkos account new

This will output a new Aleo account in the terminal.

Please remember to save the account private key and view key. The following is an example output:

 Attention - Remember to store this account private key and view key.

  Private Key  APrivateKey1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  <-- Save Me And Use In The Next Step
     View Key  AViewKey1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  <-- Save Me
      Address  aleo1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  <-- Save Me

Next, to start a proving node, from the snarkOS directory, run:

./run-prover.sh

When prompted, enter your Aleo private key:

Enter the Aleo Prover account private key:
APrivateKey1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. FAQs

1. My node is unable to compile.

  • Ensure your machine has Rust v1.66+ installed. Instructions to install Rust can be found here.
  • If large errors appear during compilation, try running cargo clean.
  • Ensure snarkOS is started using ./run-client.sh or ./run-prover.sh.

2. My node is unable to connect to peers on the network.

  • Ensure ports 4133/tcp and 3033/tcp are open on your router and OS firewall.
  • Ensure snarkOS is started using ./run-client.sh or ./run-prover.sh.

3. I can't generate a new address

  • Before running the command above (snarkos account new) try source ~/.bashrc
  • Also double-check the spelling of snarkos. Note the directory is /snarkOS, the command is snarkos

5. Command Line Interface

To run a node with custom settings, refer to the full list of options and flags available in the snarkOS CLI.

The full list of CLI flags and options can be viewed with snarkos --help:

snarkOS 
The Aleo Team <hello@aleo.org>

USAGE:
    snarkos [OPTIONS] <SUBCOMMAND>

OPTIONS:
    -h, --help                     Print help information
    -v, --verbosity <VERBOSITY>    Specify the verbosity [options: 0, 1, 2, 3] [default: 2]

SUBCOMMANDS:
    account    Commands to manage Aleo accounts
    clean      Cleans the snarkOS node storage
    help       Print this message or the help of the given subcommand(s)
    start      Starts the snarkOS node
    update     Update snarkOS

The following are the options for the snarkos start command:

USAGE:
    snarkos start [OPTIONS]

OPTIONS:
        --network <NETWORK_ID>                  Specify the network ID of this node [default: 3]
        
        --validator                             Specify this node as a validator
        --prover                                Specify this node as a prover
        --client                                Specify this node as a client
        
        --private-key <PRIVATE_KEY>             Specify the node's account private key
        --private-key-file <PRIVATE_KEY_FILE>   Specify the path to a file containing the node's account private key
        
        --node <IP:PORT>                        Specify the IP address and port for the node server [default: 0.0.0.0:4133]
        --connect <IP:PORT>                     Specify the IP address and port of a peer to connect to
 
        --rest <REST>                           Specify the IP address and port for the REST server [default: 0.0.0.0:3033]
        --norest                                If the flag is set, the node will not initialize the REST server
        
        --nodisplay                             If the flag is set, the node will not render the display
        --verbosity <VERBOSITY_LEVEL>           Specify the verbosity of the node [options: 0, 1, 2, 3] [default: 2]
        --logfile <PATH>                        Specify the path to the file where logs will be stored [default: /tmp/snarkos.log]
        
        --dev <NODE_ID>                         Enables development mode, specify a unique ID for this node

6. Development Guide

6.1 Quick Start

In the first terminal, start the first validator by running:

cargo run --release -- start --nodisplay --dev 0 --validator

In the second terminal, start the second validator by running:

cargo run --release -- start --nodisplay --dev 1 --validator

In the third terminal, start the third validator by running:

cargo run --release -- start --nodisplay --dev 2 --validator

In the fourth terminal, start the fourth validator by running:

cargo run --release -- start --nodisplay --dev 3 --validator

From here, this procedure can be used to further start up provers and clients.

6.2 Operations

It is important to initialize the nodes starting from 0 and incrementing by 1 for each new node.

The following is a list of options to initialize a node (replace <NODE_ID> with a number starting from 0):

cargo run --release -- start --nodisplay --dev <NODE_ID> --validator
cargo run --release -- start --nodisplay --dev <NODE_ID> --prover
cargo run --release -- start --nodisplay --dev <NODE_ID> --client
cargo run --release -- start --nodisplay --dev <NODE_ID>

When no node type is specified, the node will default to --client.

6.3 Local Devnet

6.3.1 Install tmux

To run a local devnet with the script, start by installing tmux.

macOS

To install tmux on macOS, you can use the Homebrew package manager. If you haven't installed Homebrew yet, you can find instructions at their website.

# Once Homebrew is installed, run:
brew install tmux
Ubuntu

On Ubuntu and other Debian-based systems, you can use the apt package manager:

sudo apt update
sudo apt install tmux
Windows

There are a couple of ways to use tmux on Windows:

Using Windows Subsystem for Linux (WSL)

  1. First, install Windows Subsystem for Linux.
  2. Once WSL is set up and you have a Linux distribution installed (e.g., Ubuntu), open your WSL terminal and install tmux as you would on a native Linux system:
sudo apt update
sudo apt install tmux

6.3.2 Start a Local Devnet

To start a local devnet, run:

./devnet.sh

Follow the instructions in the terminal to start the devnet.

6.3.3 View a Local Devnet

Switch Nodes (forward)

To toggle to the next node in a local devnet, run:

Ctrl+b n

Switch Nodes (backwards)

To toggle to the previous node in a local devnet, run:

Ctrl+b p

Select a Node (choose-tree)

To select a node in a local devnet, run:

Ctrl+b w

Select a Node (manually)

To select a node manually in a local devnet, run:

Ctrl+b :select-window -t {NODE_ID}

6.3.4 Stop a Local Devnet

To stop a local devnet, run:

Ctrl+b :kill-session

Then, press Enter.

Clean Up

To clean up the node storage, run:

cargo run --release -- clean --dev <NODE_ID>

7. Contributors

Thank you for helping make snarkOS better!
🧐 What do the emojis mean?

Howard Wu
Howard Wu

πŸ’» 🚧 πŸ€” πŸ‘€
Raymond Chu
Raymond Chu

πŸ’» 🚧 πŸ€” πŸ‘€
ljedrz
ljedrz

πŸ’» 🚧 πŸ€” πŸ‘€
Niklas Long
Niklas Long

πŸ’» 🚧 πŸ€” πŸ‘€
Collin Chin
Collin Chin

πŸ’» πŸ“– πŸ‘€
Mike Turner
Mike Turner

πŸ’» πŸ“– πŸ‘€
Georgios Konstantopoulos
Georgios Konstantopoulos

πŸ’»
Kobi Gurkan
Kobi Gurkan

πŸ’»
jules
jules

πŸ’»
Max Bruce
Max Bruce

πŸ’»
Daniil
Daniil

πŸ’»
akattis
akattis

πŸ’»
William Cannon
William Cannon

πŸ’»
Sam De Roeck
Sam De Roeck

πŸ’»
wcannon-aleo
wcannon-aleo

πŸ’»
soft2dev
soft2dev

πŸ’»
Ali Mousa
Ali Mousa

πŸ’»
pyk
pyk

πŸ’»
Belsy
Belsy

πŸ’»
apruden2008
apruden2008

πŸ’»
Fabiano Prestes
Fabiano Prestes

πŸ’»
Haruka
Haruka

πŸ’»
e4m7he6g
e4m7he6g

πŸ’»
GregΓ³rio Granado MagalhΓ£es
GregΓ³rio Granado MagalhΓ£es

πŸ’»
Evgeny Garanin
Evgeny Garanin

πŸ’»
Macro Hoober
Macro Hoober

πŸ’»
code-pangolin
code-pangolin

πŸ’»
kaola526
kaola526

πŸ’»
clarenous
clarenous

πŸ’»
Kostyan
Kostyan

πŸ’»
Austin Abell
Austin Abell

πŸ’»
Youssef El Housni
Youssef El Housni

πŸ’»
ghostant-1017
ghostant-1017

πŸ’»
Miguel Gargallo
Miguel Gargallo

πŸ’»
Chines Wang
Chines Wang

πŸ’»
Ayush Goswami
Ayush Goswami

πŸ’»
Tim - o2Stake
Tim - o2Stake

πŸ’»
liu-sen
liu-sen

πŸ’»
Palamar
Palamar

πŸ’»
swift-mx
swift-mx

πŸ’»
Caesar Wang
Caesar Wang

πŸ’»
Paul IP
Paul IP

πŸ’»
Philip Glazman
Philip Glazman

πŸ’»
Ruslan Nigmatulin
Ruslan Nigmatulin

πŸ’»
François Garillot
François Garillot

πŸ’»
aolcr
aolcr

πŸ’»
Maciej ZwoliΕ„ski
Maciej ZwoliΕ„ski

πŸ’»
Nacho Avecilla
Nacho Avecilla

πŸ’»
Dependabot
Dependabot

πŸ’»
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!

8. License

We welcome all contributions to snarkOS. Please refer to the license for the terms of contributions.

License: GPL v3