## 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 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 Sonoma or later, Windows 11 or later
- Provers: Ubuntu 22.04 (LTS), macOS Sonoma or later
- Validators: Ubuntu 22.04 (LTS)
- **CPU**: 64-bit architectures only
- Clients: 32-cores
- Provers: 32-cores (64-cores preferred)
- Validators: 32-cores (64-cores preferred)
- **RAM**: DDR4 or better
- Clients: 32GB 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: 300GB of disk space
- Provers: 32GB 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: 500Mbps of upload **and** download bandwidth
- Validators: 1000Mbps 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 that in order to run an Aleo Prover that is **competitive**, the machine will need more than these requirements.
### 2.2 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.
## 3. Run an Aleo Node
## 3.1 Run an Aleo Client
Start by following the instructions in the [Build Guide](#2-build-guide).
Next, to start a client node, from the `snarkOS` directory, run:
```
./run-client.sh
```
## 3.2 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)
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.md)
