Update HW requirements, node start commands, and node shell scripts

README.md

@@ -38,37 +38,40 @@ which verifies transactions and stores the encrypted state applications in a pub
 
 ## 2. Build Guide
 
-### 2.1 Requirements
+### 2.1 Definitions
 
-The following are **minimum** requirements to run an Aleo node:
+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
-    - 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)
+ - **CPU**: 64-bit architectures only, Latest Intel Xeon or Better
+    - Clients, core: 32-cores (24 minimum)
+    - Clients, outer: 32-cores (16 minimum)
+    - Validators: 64-cores (or better)
  - **RAM**: DDR4 or better
-    - Clients: 16GB of memory
-    - Provers: 32GB of memory (64GB or larger preferred)
-    - Validators: 64GB of memory (128GB or larger preferred)
+    - Clients, core: 192GB of memory (128 minimum)
+    - Clients, outer: 128GB of memory (64 minimum)
+    - Validators: 384GB of memory (256 minimum)
  - **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)
+    - Clients, core: 4TB of disk space (2 minimum)
+    - Clients, outer: 2TB of disk space (1 minimum)
+    - Validators: 6TB of disk space (4 minimum)
  - **Network**: Symmetric, commercial, always-on
-    - Clients: 100Mbps of upload **and** download bandwidth
-    - Provers: 250Mbps of upload **and** download bandwidth
+    - Clients: 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 that in order to run an Aleo Prover that is **competitive**, the machine will need more than these requirements.
+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.2 Installation
+### 2.3 Installation
 
 Before beginning, please ensure your machine has `Rust v1.66+` installed. Instructions to [install Rust can be found here.](https://www.rust-lang.org/tools/install)
 
@@ -93,19 +96,76 @@ 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 |
 
 ## 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 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 “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).
 
-Next, to start a client node, from the `snarkOS` directory, run:
+To start a validator, you can also run the following command from the `snarkOS` directory:
 ```
-./run-client.sh
+./run-validator.sh
 ```
 
-## 3.2 Run an Aleo Prover
+## 3.3 Run an Aleo Prover
 
 Start by following the instructions in the [Build Guide](#2-build-guide).
 

run-core-client.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# USAGE examples: 
+  # CLI with env vars: PEERS=“validator_ip:4130,core_client_ip_1:4130,core_client_ip_2:4130,core_client_ip_3:4130,outer_client_ip_1:4130,... ./run-core-client.sh
+  # CLI with prompts for vars:  ./run-core-client.sh
+
+# If the env var PEERS is not set, prompt for it
+if [ -z "${PEERS}" ]
+then
+  read -r -p "Enter the peers (comma-separated) (e.g., “validator_ip:4130,core_client_ip_1:4130,core_client_ip_2:4130,core_client_ip_3:4130,outer_client_ip_1:4130,...): "
+  PEERS=$REPLY
+fi
+
+if [ "${PEERS}" == "" ]
+then
+  echo "Missing peers."
+  exit 1
+fi
+
+COMMAND='cargo run --release -- start --nodisplay --client --node 0.0.0.0:4130 --peers ${PEERS} --verbosity 1 --norest'
+
+for word in $*;
+do
+  COMMAND="${COMMAND} ${word}"
+done
+
+function exit_node()
+{
+    echo "Exiting..."
+    kill $!
+    exit
+}
+
+trap exit_node SIGINT
+
+echo "Checking for updates..."
+git stash
+rm Cargo.lock
+STATUS=$(git pull)
+
+if [ "$STATUS" != "Already up to date." ]; then
+  echo "Updated code found, cleaning the project"
+  cargo clean
+fi
+
+echo "Running an Aleo Core Client node..."
+$COMMAND &
+wait

run-outer-client.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# USAGE examples: 
+  # CLI with env vars: PEERS=core_client_ip_1:4130,core_client_ip_2:4130,core_client_ip_3:4130,outer_client_ip_1:4130,... ./run-outer-client.sh
+  # CLI with prompts for vars:  ./run-outer-client.sh
+
+# If the env var PEERS is not set, prompt for it
+if [ -z "${PEERS}" ]
+then
+  read -r -p "Enter the peers (comma-separated) (e.g., core_client_ip_1:4130,core_client_ip_2:4130,core_client_ip_3:4130,outer_client_ip_1:4130,...): "
+  PEERS=$REPLY
+fi
+
+if [ "${PEERS}" == "" ]
+then
+  echo "Missing peers."
+  exit 1
+fi
+
+COMMAND='cargo run --release -- start --nodisplay --client --node 0.0.0.0:4130 --peers ${PEERS} --verbosity 1 --rest 0.0.0.0:3030'
+
+for word in $*;
+do
+  COMMAND="${COMMAND} ${word}"
+done
+
+function exit_node()
+{
+    echo "Exiting..."
+    kill $!
+    exit
+}
+
+trap exit_node SIGINT
+
+echo "Checking for updates..."
+git stash
+rm Cargo.lock
+STATUS=$(git pull)
+
+if [ "$STATUS" != "Already up to date." ]; then
+  echo "Updated code found, cleaning the project"
+  cargo clean
+fi
+
+echo "Running an Aleo Outer Client node..."
+$COMMAND &
+wait

run-prover.sh

@@ -32,20 +32,15 @@ function exit_node()
 
 trap exit_node SIGINT
 
-echo "Running an Aleo Prover node..."
-$COMMAND &
-
-while :
-do
-  echo "Checking for updates..."
-  git stash
-  STATUS=$(git pull)
+echo "Checking for updates..."
+git stash
+STATUS=$(git pull)
 
-  if [ "$STATUS" != "Already up to date." ]; then
-    echo "Updated code found, rebuilding and relaunching prover"
-    cargo clean
-    kill -INT $!; sleep 2; $COMMAND &
-  fi
+if [ "$STATUS" != "Already up to date." ]; then
+  echo "Updated code found, cleaning the project"
+  cargo clean
+fi
 
-  sleep 1800;
-done
+echo "Running an Aleo Prover node..."
+$COMMAND &
+wait

run-validator.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # USAGE examples:
-  # CLI with env vars: VALIDATOR_PRIVATE_KEY=APrivateKey1...  ./run-validator.sh
+  # CLI with env vars: VALIDATOR_PRIVATE_KEY=APrivateKey1... PEERS=core_client_ip_1:4130,core_client_ip_2:4130,... VALIDATORS=validator_ip_1:5000,validator_ip_2:5000,... ./run-validator.sh
   # CLI with prompts for vars:  ./run-validator.sh
 
 # If the env var VALIDATOR_PRIVATE_KEY is not set, prompt for it
@@ -16,7 +16,33 @@ then
   exit
 fi
 
-COMMAND="cargo run --release -- start --nodisplay --validator --private-key ${VALIDATOR_PRIVATE_KEY}"
+# If the env var PEERS is not set, prompt for it
+if [ -z "${PEERS}" ]
+then
+  read -r -p "Enter the peers (comma-separated) (e.g., core_client_ip_1:4130,core_client_ip_2:4130,...): "
+  PEERS=$REPLY
+fi
+
+if [ "${PEERS}" == "" ]
+then
+  echo "Missing peers."
+  exit 1
+fi
+
+# If the env var VALIDATORS is not set, prompt for it
+if [ -z "${VALIDATORS}" ]
+then
+  read -r -p "Enter the validators (comma-separated) (e.g., validator_ip_1:5000,validator_ip_2:5000,...): "
+  VALIDATORS=$REPLY
+fi
+
+if [ "${VALIDATORS}" == "" ]
+then
+  echo "Missing validators."
+  exit 1
+fi
+
+COMMAND="cargo run --release -- start --nodisplay --validator --bft 0.0.0.0:5000 --node 0.0.0.0:4130 --peers ${PEERS} --validators ${VALIDATORS} --norest --private-key ${VALIDATOR_PRIVATE_KEY}"
 
 for word in $*;
 do
@@ -32,21 +58,16 @@ function exit_node()
 
 trap exit_node SIGINT
 
+echo "Checking for updates..."
+git stash
+rm Cargo.lock
+STATUS=$(git pull)
+
+if [ "$STATUS" != "Already up to date." ]; then
+  echo "Updated code found, cleaning the project"
+  cargo clean
+fi
+
 echo "Running an Aleo Validator node..."
 $COMMAND &
-
-while :
-do
-  echo "Checking for updates..."
-  git stash
-  rm Cargo.lock
-  STATUS=$(git pull)
-
-  if [ "$STATUS" != "Already up to date." ]; then
-    echo "Updated code found, rebuilding and relaunching validator"
-    cargo clean
-    kill -INT $!; sleep 2; $COMMAND &
-  fi
-
-  sleep 1800;
-done
+wait