- 1. Overview
- 2. Build Guide
- 3. Run an Aleo Node
- 4. FAQs
- 5. Command Line Interface
- 6. Development Guide
- 7. Contributors
- 8. License
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.
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.
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.
Before beginning, please ensure your machine has Rust v1.79+ installed. Instructions to install Rust can be found here.
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.
| Port | Protocol | Allow/Deny | Source | Explanation |
|---|---|---|---|---|
| 4130/tcp | TCP | Allow | All IPv4/IPv6 | TCP traffic to peers |
| 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 |
| 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 <username> with your username)
echo "<username> - 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'
Start by following the instructions in the 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.
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
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
Start by following the instructions in the 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
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
- 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
snarkOSis started using./run-client.shor./run-prover.sh.
- Ensure ports
4130/tcpand3030/tcpare open on your router and OS firewall. - Ensure
snarkOSis started using./run-client.shor./run-prover.sh.
- Before running the command above (
snarkos account new) trysource ~/.bashrc - Also double-check the spelling of
snarkos. Note the directory is/snarkOS, and the command issnarkos
- Generate an account with
snarkos account newif you haven't already - Sign a message with your private key using
snarkos account sign --raw -m "Message" --private-key-file=<PRIVATE_KEY_FILE> - 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 values such as 1u8 or 100field.
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 <[email protected]>
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:4130]
--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: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 <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
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.
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.
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 tmuxUbuntu
On Ubuntu and other Debian-based systems, you can use the apt package manager:
sudo apt update
sudo apt install tmuxWindows
There are a couple of ways to use tmux on Windows:
- First, install Windows Subsystem for Linux.
- Once WSL is set up and you have a Linux distribution installed (e.g., Ubuntu), open your WSL terminal and install
tmuxas you would on a native Linux system:
sudo apt update
sudo apt install tmuxTo start a local devnet, run:
./devnet.sh
Follow the instructions in the terminal to start the devnet.
To toggle to the next node in a local devnet, run:
Ctrl+b n
To toggle to the previous node in a local devnet, run:
Ctrl+b p
To select a node in a local devnet, run:
Ctrl+b w
To select a node manually in a local devnet, run:
Ctrl+b :select-window -t {NODE_ID}
To stop a local devnet, run:
Ctrl+b :kill-session
Then, press Enter.
To clean up the node storage, run:
cargo run --release -- clean --dev <NODE_ID>
Thank you for helping make snarkOS better!
🧐 What do the emojis mean?
This project follows the all-contributors specification. Contributions of any kind are welcome!
We welcome all contributions to snarkOS. Please refer to the license for the terms of contributions.
