Safrochain Testnet Node Setup Guide

This guide provides a comprehensive, step-by-step process for setting up a Safrochain testnet node in local mode and configuring a validator. Designed for beginners and advanced users alike, it includes copy-paste commands with detailed explanations for Linux (Ubuntu) and macOS. By the end, you'll have a fully synchronized node on the Safrochain testnet, a funded validator wallet, and a configured validator ready for staking.

📋 Prerequisites

Before starting, ensure you have the following:

System Requirements:

Operating System: Linux (Ubuntu 20.04 or later recommended) or macOS (10.15 or later)

Minimum: 2GB RAM, 20GB free disk space

Recommended: 4GB RAM, 50GB SSD for production

Internet: Stable connection for cloning repositories, downloading the genesis file, and syncing the blockchain

Permissions: Root/admin access (sudo on Linux/macOS) for installing packages and configuring firewalls

Testnet Configuration:

Chain ID: safro-testnet-1

Main Node: 2242a526e7841e7e8a551aabc4614e6cd612e7fb@88.99.211.113:26656

Genesis File: https://genesis.safrochain.com/testnet/genesis.json

Faucet: https://faucet.safrochain.com (provides 25,000,000 usaf per request)

Testnet Denomination: Uses usaf as the base unit for transactions

Home Directory: Node configuration and data stored in $HOME_NODE (default: $HOME/.safrochain)

Note: This guide assumes you are joining an existing testnet and do not need to create initial accounts or modify the genesis file. Commands are provided for manual execution to ensure clarity and control.

🚀 Setup Steps

Follow these steps to set up your Safrochain testnet node and validator. Each step includes commands, explanations, verification checks, and troubleshooting tips for a smooth setup process.

Step 1: Install Dependencies

Purpose: Installs Go 1.23.9, git, make, and jq (for JSON parsing), and configures the Go environment required to build and run the Safrochain node.

Prerequisites: Administrative privileges (sudo on Linux/macOS).

Linux (Ubuntu)

macOS

Notes:

Linux: Installs Go 1.23.9 via the official tarball. For other architectures (e.g., ARM), visit https://go.dev/dl/.

macOS: Requires Xcode Command Line Tools and Homebrew (brew install homebrew). If using Bash, replace .zshrc with .bashrc.

GOPATH is set to $HOME/go for building the Safrochain binary. jq is used for JSON validation in later steps.

Verification: Run go version to confirm go1.23.x. If incorrect, remove existing Go (sudo rm -rf /usr/local/go) and retry.

Verification:

Check Go version:

Expected Output: go version go1.23.9 ...

Check jq installation:

Expected Output: jq-1.6 or similar

Troubleshooting:

Wrong Go version: Run sudo rm -rf /usr/local/go and repeat the installation.

Command not found: Verify sudo privileges and internet connectivity (ping google.com).

Step 2: Clone Repository and Build Binary

Purpose: Clones the Safrochain node repository, builds the safrochaind binary, and adds it to the system PATH.

Prerequisites: git and Go 1.23 installed (Step 1).

Linux (Ubuntu)

macOS

Notes:

The safrochaind binary is installed in ~/go/bin.

Linux: PATH changes are saved to .bashrc.

macOS: Uses .zshrc. For Bash, replace with .bashrc. For other shells (e.g., Fish), add export PATH=$PATH:$HOME/go/bin to the shell's config (e.g., ~/.config/fish/config.fish).

Verification: Run safrochaind version to confirm the binary is accessible.

Verification:

Check binary existence:

Expected Output: /home/<user>/go/bin/safrochaind

Check binary version:

Expected Output: A version number (e.g., v1.0.0)

Troubleshooting:

safrochaind not found: Verify ~/go/bin is in PATH (echo $PATH) and re-run source $HOME/.bashrc (Linux) or source $HOME/.zshrc (macOS).

make install fails: Check for errors in safrochain-node/app.go or run go mod tidy in the repository directory.

Step 3: Initialize the Node

Purpose: Initializes the node with a unique moniker and creates the configuration directory $HOME_NODE.

Prerequisites: safrochaind binary built (Step 2).

Linux (Ubuntu)

macOS

Notes:

The moniker is your node's public name (e.g., my-node).

The --chain-id safro-testnet-1 matches the testnet's identifier.

Creates $HOME_NODE/config/ with default files: app.toml, config.toml, client.toml, genesis.json, node_key.json, priv_validator_key.json.

$HOME_NODE is set to $HOME/.safrochain and persisted for future sessions.

Verification:

Check configuration directory:

Expected Output: app.toml client.toml config.toml genesis.json node_key.json priv_validator_key.json

Verify $HOME_NODE:

Expected Output: /home/<user>/.safrochain

Troubleshooting:

Directory not created: Ensure safrochaind is installed (which safrochaind) and you have write permissions (ls -ld $HOME).

Initialization error: Check disk space (df -h) or re-run the command.

Step 4: Configure Genesis File

Purpose: Downloads the official testnet genesis.json and places it in $HOME_NODE/config/.

Prerequisites: Internet access and $HOME_NODE/config/ created (Step 3).

Notes:

Uses curl -L to follow redirects and download the genesis file.

Overwrites any existing genesis.json in $HOME_NODE/config/.

To inspect the file:

Verification:

Check file existence:

Expected Output: $HOME_NODE/config/genesis.json

Validate JSON:

Expected Output: JSON content without errors

Troubleshooting:

Download fails: Verify the URL in a browser or test internet connectivity (ping google.com). Try the alternative URL: https://raw.githubusercontent.com/Safrochain-Org/genesis/refs/heads/main/genesis-testnet.json.

Step 5: Configure Node Settings

Purpose: Configures app.toml, config.toml, and client.toml with testnet-specific settings, including gas prices, ports, and the main node as a seed peer.

Prerequisites: Node initialized (Step 3).

All Configs files

Node Configuration Notes

Gas prices: Set to 0.001usaf for the testnet denomination.

Seeds: Configures the main node 2242a526e7841e7e8a551aabc4614e6cd612e7fb@88.99.211.113:26656 for syncing.

External IP: Defaults to 127.0.0.1 for local operation. For public nodes, provide your server's external IP.

Enables API (1317), gRPC (9090), and P2P (26656) ports.

Uses the $MONIKER variable from Step 3.

🔧 Automatic Configuration of `config.toml`

To automatically update the seeds, persistent_peers, and pex values in config.toml, use the command below that matches your OS:

Linux

macOS

✅ Verification

Check if configuration files exist:

Expected Output:

app.toml  client.toml  config.toml  genesis.json  node_key.json  priv_validator_key.json

Verify that the seed peer is correctly set:

Expected Output:

seeds = "2242a526e7841e7e8a551aabc4614e6cd612e7fb@88.99.211.113:26656"

🛠️ Troubleshooting

Files not created: Check if $HOME_NODE is set (echo $HOME_NODE) and that the user has write permissions (ls -ld $HOME_NODE).

Incorrect moniker: Re-run the config.toml creation step with the correct $MONIKER.

Step 6: Open Required Ports

Purpose: Configures the firewall to allow ports 26656 (P2P), 26657 (RPC), 1317 (API), and 9090 (gRPC) for node communication.

Prerequisites: Firewall tools installed (ufw for Linux, macOS firewall).

Linux (Ubuntu)

macOS

Notes:

Linux: Uses ufw for simple firewall management. Verify with sudo ufw status.

macOS: pfctl changes are temporary; for persistence, modify /etc/pf.conf or use the GUI firewall settings.

For cloud providers (e.g., AWS, GCP), ensure these ports are open in your security group settings.

Verification:

Check firewall status (Linux):

Expected Output: Lists 26656, 26657, 1317, 9090 as allowed; 26658, 6060 as denied.

Test port accessibility:

Expected Output: Connection to localhost 26656 port [tcp/*] succeeded!

Troubleshooting:

Ports not open: Re-run ufw commands or check for conflicting rules (sudo ufw status).

Cloud provider issues: Verify security group rules in your cloud provider's console.

Step 7: Start the Node

Purpose: Starts the node, connects to the main node for syncing, and logs output for monitoring.

Prerequisites: Configuration files and genesis file set up (Steps 4–5).

Choose 1 or 2

safrochaind start

systemd service (Linux only)

Notes:

Resets node state to ensure a clean start.

Direct launch: Runs in the background with logs saved to $HOME_NODE/safrochaind.log.

Systemd service: Recommended for production (Linux only); auto-restarts on failure.

macOS users should use the direct launch method or a similar service manager like launchd.

Verification:

Check logs (direct launch):

Expected Output: Node activity logs, including block syncing.

Check status (systemd):

Expected Output: Shows active (running) status.

Check sync status:

Expected Output: JSON with catching_up: false when synced.

Troubleshooting:

Node not starting: Check logs (tail $HOME_NODE/safrochaind.log or journalctl -u safrochaind -f).

Validator set empty:

Verify genesis file:

Redownload genesis file:

Reset state:

🔍 Monitoring Tools

Monitor your node and validator with these commands:

Node Status:

Expected Output: JSON with node details, including sync status.

Sync Info:

Expected Output: JSON with catching_up: false when synced.

Validator Info:

Expected Output: Details of your validator.

Logs:

For systemd

Expected Output: Real-time node activity logs.

🛑 Stopping the Node

Direct Launch:

Systemd Service (Linux only):

🔄 Updating the Node

To update the node to a new version:

Notes:

Check the Safrochain GitHub releases for the latest version tag.

Ensure the node is stopped before updating.

📚 Resources

Official Repository: Safrochain GitHub

Testnet Explorer: Safrochain Explorer

Community: Safrochain Community (Discord, Telegram)

📝 Notes

Monitor disk space (df -h) and logs regularly to ensure node health.

For production, consider using a dedicated server with higher specs and a robust backup strategy.

Install a Node

Safrochain Testnet Node Setup Guide#

📋 Prerequisites#

🚀 Setup Steps#

Step 1: Install Dependencies#

Step 2: Clone Repository and Build Binary#

Step 3: Initialize the Node#

Step 4: Configure Genesis File#

Step 5: Configure Node Settings#

Node Configuration Notes#

🔧 Automatic Configuration of config.toml#

✅ Verification#

🛠️ Troubleshooting#

Step 6: Open Required Ports#

Step 7: Start the Node#

🔍 Monitoring Tools#

🛑 Stopping the Node#

🔄 Updating the Node#

📚 Resources#

📝 Notes#

Safrochain Testnet Node Setup Guide

📋 Prerequisites

🚀 Setup Steps

Step 1: Install Dependencies

Step 2: Clone Repository and Build Binary

Step 3: Initialize the Node

Step 4: Configure Genesis File

Step 5: Configure Node Settings

Node Configuration Notes

🔧 Automatic Configuration of `config.toml`

✅ Verification

🛠️ Troubleshooting

Step 6: Open Required Ports

Step 7: Start the Node

🔍 Monitoring Tools

🛑 Stopping the Node

🔄 Updating the Node

📚 Resources

📝 Notes