Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/AleoNet/snarkOS

A Decentralized Operating System for ZK Applications
https://github.com/AleoNet/snarkOS

aleo blockchain cryptography rust zero-knowledge zksnarks

Last synced: 3 months ago
JSON representation

A Decentralized Operating System for ZK Applications

Awesome Lists containing this project

README 

        


    snarkOS






    

    

    

    

    




## Table of Contents



* [1. Overview](#1-overview)

* [2. Build Guide](#2-build-guide)

  * [2.1 Requirements](#21-requirements)

  * [2.2 Installation](#22-installation)

* [3. Run an Aleo Node](#3-run-an-aleo-node)

  * [3.1 Run an Aleo Client](#31-run-an-aleo-client)

  * [3.2 Run an Aleo Prover](#32-run-an-aleo-prover)

* [4. FAQs](#4-faqs)

* [5. Command Line Interface](#5-command-line-interface)

* [6. Development Guide](#6-development-guide)

  * [6.1 Quick Start](#61-quick-start)

  * [6.2 Operations](#62-operations)

* [7. Contributors](#7-contributors)

* [8. License](#8-license)



[comment]: <> (* [4. JSON-RPC Interface](#4-json-rpc-interface))

[comment]: <> (* [5. Additional Information](#5-additional-information))



## 1. Overview



__snarkOS__ is a decentralized operating system for zero-knowledge applications.

This code forms the backbone of [Aleo](https://aleo.org/) network,

which verifies transactions and stores the encrypted state applications in a publicly-verifiable manner.



## 2. Build Guide



### 2.1 Definitions



The following snarkOS node types exist in the Aleo network:

 - **Validator**: Validator nodes participate in consensus and must be started with an account that is bonded into the committee.

 - **Client**: Clients do not participate in consensus but maintain a ledger. They are capable of providing information about the network as well as accepting solutions and transactions and communicating them to their peers. All clients run the same software, however, for the purposes of configuration management, this document defines two types of clients:

    - Core Client: Client node connected directly to a validator node.

    - Outer Client: Client node connected only to other clients or prover nodes.

 - **Prover**: Prover nodes are dedicated to solving the Aleo puzzle. They do not participate in consensus or maintain a copy of the ledger.



### 2.2 Requirements



The following are the 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

    - Validators: Ubuntu 22.04 (LTS)

 - **CPU**: 64-bit architectures only, Latest Intel Xeon or Better

    - Clients: 24-cores (32-cores or larger preferred)

    - Validators: 64-cores (128-cores or larger preferred)

 - **RAM**: DDR4 or better

    - Clients: 128GiB of memory (192GiB or larger preferred)

    - Validators: 256GiB of memory (384GiB or larger preferred)

 - **Storage**: PCIe Gen 3 x4, PCIe Gen 4 x2 NVME SSD, or better

    - Clients: 2TB of disk space (4TB or larger preferred)

    - Validators: 4TB of disk space (6TB or larger preferred)

 - **Network**: Symmetric, commercial, always-on

    - Clients: 250Mbps of upload **and** download bandwidth

    - Validators: 500Mbps of upload **and** download bandwidth



No explicit recommendations are made for proving nodes as proving hardware may be highly variable. If interested in running Aleo Provers nodes, please refer to resources published by the Aleo community.



### 2.3 Installation



Before beginning, please ensure your machine has `Rust v1.79+` installed. Instructions to [install Rust can be found here.](https://www.rust-lang.org/tools/install)



Start by cloning this GitHub repository:

```

git clone --branch mainnet --single-branch https://github.com/AleoNet/snarkOS.git

```



Next, move into the `snarkOS` directory:

```

cd snarkOS

git checkout tags/testnet-beta

```



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

```

./build_ubuntu.sh

```



Lastly, install `snarkOS`:

```

cargo install --locked --path .

```



Please ensure ports `4130/tcp` and `3030/tcp` are open on your router and OS firewall.

### 2.4 Port Configuration



#### 2.4.1 For Core Clients



| Port     | Protocol | Allow/Deny | Source                       | Explanation                                                |

|----------|----------|------------|------------------------------|------------------------------------------------------------|

| 4130/tcp | TCP      | Allow      | All IPv4/IPv6 | TCP traffic to peers               |



#### 2.4.2 For Outer Clients



| Port     | Protocol | Allow/Deny | Source                       | Explanation                                                |

|----------|----------|------------|------------------------------|------------------------------------------------------------|

| 3030/tcp | TCP      | Allow      | All IPv4/IPv6                | REST server                                                |

| 4130/tcp | TCP      | Allow      | All IPv4/IPv6 | TCP traffic to peers                |



#### 2.4.3 For Validators



| Port     | Protocol | Allow/Deny | Source                       | Explanation                                                |

|----------|----------|------------|------------------------------|------------------------------------------------------------|

| 4130/tcp | TCP      | Allow      | All IPv4/IPv6 | TCP traffic to peers                |

| 5000/tcp | TCP      | Allow      | Trusted Validator IPs        | TCP traffic between validators for BFT communication       |

| 3000/tcp | TCP      | Allow      | Internal VPC or VPN          | Metrics dashboard, should only be open within an internal VPC or VPN |

| 3030/tcp | TCP      | Deny       | All IPv4/IPv6                | REST server. This should **always** be disabled for validators |

| 9000/tcp | TCP      | Allow      | Internal VPC or VPN          | Metrics export, should only be open within an internal VPC or VPN |

| 9090/tcp | TCP      | Allow      | Internal VPC or VPN          | Prometheus metrics, should only be open within an internal VPC or VPN |



**Note:** Ensure that your open file limit is set to 16,384 or above.

For the recommended setting run:

```

# Increase the open file limit for the current user (replace  with your username)

echo " - nofile 65536" | sudo tee -a /etc/security/limits.conf

# Increase the default system open file limit

sudo bash -c 'echo "DefaultLimitNOFILE=65536" >> /etc/systemd/system.conf'

```



## 3. Run an Aleo Node



## 3.1 Run an Aleo Client



Start by following the instructions in the [Build Guide](#2-build-guide).

The guide below provides information on running `core` and `outer` clients (as defined in Section 2.2.) Aleo community members running validators are recommended to run 1-3 `core` clients as their exclusive client peers. This will ensure network traffic from the public internet is verified prior to reaching the validator.



Any client **not** connected directly to a validator can be considered an `outer` client.



### 3.1.1 Run an Aleo Core Client



The following command is recommended when starting a client node that is connected to a validator:

`snarkos start --client --nodisplay --node 0.0.0.0:4130 --peers "validator_ip:4130,core_client_ip_1:4130,core_client_ip_2:4130,core_client_ip3:4130,outer_client_ip_1:4130,..." --verbosity 1 --norest`



To start a core client node, you can also run the following command from the `snarkOS` directory:

```

./run-core-client.sh

```



### 3.1.2 Run an Aleo Outer Client



The following command is recommended when starting a client node that is NOT connected to a validator:

`snarkos start --client --nodisplay --node 0.0.0.0:4130 --peers "core_client_ip_1:4130,core_client_ip_2:4130,core_client_ip3:4130,outer_client_ip_1:4130,..." --verbosity 1 --rest 0.0.0.0:3030`



To start an outer client node, you can also run the following command from the `snarkOS` directory:

```

./run-outer-client.sh

```



## 3.2 Run an Aleo Validator



Start by following the instructions in the [Build Guide](#2-build-guide).



The following command is recommended when starting a validator node:

`snarkos start --validator --nodisplay --bft 0.0.0.0:5000 --node 0.0.0.0:4130 --peers "validator_ip_1:4130,validator_ip_2:4130,...,core_client_ip_1:4130,core_client_ip_2:4130,..." --validators "validator_ip_1:5000,validator_ip_2:5000,..." --verbosity 1 --norest --private-key-file ~/snarkOS/privatekey`



Instead of specifying a private key file (`--private-key-file` flag), the private key can also be defined explicitly (`--private-key` flag).



To start a validator, you can also run the following command from the `snarkOS` directory:

```

./run-validator.sh

```



## 3.3 Run an Aleo Prover



Start by following the instructions in the [Build Guide](#2-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.](https://www.rust-lang.org/tools/install)

- 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 `4130/tcp` and `3030/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`, and the command is `snarkos`



### 4. How do I use the CLI to sign and verify a message?



1. Generate an account with `snarkos account new` if you haven't already

2. Sign a message with your private key using `snarkos account sign --raw -m "Message" --private-key-file=`

3. Verify your signature with `snarkos account verify --raw -m "Message" -s sign1SignatureHere -a aleo1YourAccountAddress`



Note, using the `--raw` flag with the command will sign plaintext messages as bytes rather than [Aleo](https://developer.aleo.org/aleo/language#data-types-and-values) values such as `1u8` or `100field`.



## 5. Command Line Interface



To run a node with custom settings, refer to the 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 



USAGE:

    snarkos [OPTIONS] 



OPTIONS:

    -h, --help                     Print help information

    -v, --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                   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              Specify the node's account private key

        --private-key-file    Specify the path to a file containing the node's account private key

        

        --node                         Specify the IP address and port for the node server [default: 0.0.0.0:4130]

        --connect                      Specify the IP address and port of a peer to connect to

 

        --rest                            Specify the IP address and port for the REST server [default: 0.0.0.0:3030]

        --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            Specify the verbosity of the node [options: 0, 1, 2, 3] [default: 2]

        --logfile                         Specify the path to the file where logs will be stored [default: /tmp/snarkos.log]

        

        --dev                          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 `` with a number starting from `0`):

```

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

cargo run --release -- start --nodisplay --dev  --prover

cargo run --release -- start --nodisplay --dev  --client

cargo run --release -- start --nodisplay --dev 

```



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](https://brew.sh/).

```bash

# Once Homebrew is installed, run:

brew install tmux

```



Ubuntu



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

```bash

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](https://docs.microsoft.com/en-us/windows/wsl/install).

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:

```bash

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 

```



## 7. Contributors

Thank you for helping make snarkOS better!  

[🧐 What do the emojis mean?](https://allcontributors.org/docs/en/emoji-key)



  

    

      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
πŸ’»

      Vesa-Ville
Vesa-Ville
πŸ’»

      jules
jules
πŸ’»

      Daniil
Daniil
πŸ’»

      akattis
akattis
πŸ’»

      William Cannon
William Cannon
πŸ’»

      wcannon-aleo
wcannon-aleo
πŸ’»

    

    

      Sam De Roeck
Sam De Roeck
πŸ’»

      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
πŸ’»

      Max Bruce
Max Bruce
πŸ’»

    

    

      whalelephant
Belsy
πŸ’»

      tranhoaison
Santala
πŸ’»

      web3deadline
deadline
πŸ’»

      CedricYanYuhui
CedricYanYuhui
πŸ’»

      craigjson
Craig Johnson
πŸ’»

      vbar
Vaclav Barta
πŸ’»

      Dependabot
Dependabot
πŸ’»

    

  

  

    

      

        

          Add your contributions

        

      

    

  



This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!



## 8. License



We welcome all contributions to `snarkOS`. Please refer to the [license](#7-license) for the terms of contributions.



[![License: GPL v3](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE.md)