Skip to main content

Install safrochaind

This page walks you through every step of getting a working safrochaind binary on a fresh machine. Pick the tab that matches your OS and copy the blocks straight into a terminal.

Prerequisites​

ToolMainnetTestnet
Go1.25.81.23.9
safrochain-node tagv0.2.2release/v0.1.0
makeanyany
gitanyany
C toolchainbuild-essential (Linux) or Xcode CLI tools (macOS)same
OSLinux x86_64 / arm64, macOS (Intel or Apple Silicon)same
Pick the right network

Mainnet and testnet do not share a Go toolchain. Mainnet (safrochain-1) requires Go 1.25.8 and tag v0.2.2. Testnet (safro-testnet-1) requires Go 1.23.9 and tag release/v0.1.0. Mixing them produces a binary that will fail to start with Apphash mismatch or refuse to build.

1 · Install build tools​

sudo apt update
sudo apt install -y build-essential git curl jq make pkg-config libssl-dev wget

2 · Install Go and build safrochaind​

Pick one of the two flows below. Do not run both on the same machine unless you understand how to manage multiple Go toolchains side-by-side.

2.a — Install Go 1.25.8 for mainnet​

# =============================================================================
# Mainnet — Go 1.25.8 install (Ubuntu / Debian)
# Required for: safrochain-1, safrochain-node tag v0.2.2
# =============================================================================

# Update package lists and install dependencies
sudo apt update
sudo apt install -y git make jq build-essential wget curl

# Download and install Go 1.25.8
wget https://go.dev/dl/go1.25.8.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.8.linux-amd64.tar.gz
rm go1.25.8.linux-amd64.tar.gz

# Configure Go environment
export PATH=$PATH:/usr/local/go/bin
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
mkdir -p $GOPATH

# Persist environment variables
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> $HOME/.bashrc
source $HOME/.bashrc

# Verify Go installation
if go version | grep -q "go1.25.8"; then
    echo "Go 1.25.8 installed successfully."
else
    echo "Error: Go 1.25.8 not installed. Check installation steps."
    exit 1
fi

You should see go version go1.25.8 linux/amd64 (or darwin/arm64).

2.b — Build safrochaind for mainnet (tag v0.2.2)​

# =============================================================================
# Mainnet — clone, checkout v0.2.2, build
# Chain ID: safrochain-1
# =============================================================================
git clone https://github.com/Safrochain-Org/safrochain-node ~/safrochain-node
cd ~/safrochain-node
git fetch --tags

# IMPORTANT: mainnet uses tag v0.2.2 (NOT v0.2.0, NOT release/v0.1.0)
git checkout v0.2.2

make install

After make install, you should see the install complete banner (same layout as Join mainnet). For v0.2.2 the key lines match:

│   ●  safrochaind   v0.2.2
│   ●  Cosmos SDK    v0.50.14
│   ●  CometBFT      v0.38.21
│   ●  Go runtime    go1.25.8 darwin/arm64
│   ●  Build tags    netgo,ledger

On Linux AMD64, Go runtime is typically go1.25.8 linux/amd64.

Verify the binary:

safrochaind version
safrochaind version --long | grep -E '^version:|^cosmos_sdk_version:|^go:|^build_tags:|^commit:'

make install puts the binary in $GOBIN (defaults to ~/go/bin). If safrochaind is not on your $PATH, run:

which safrochaind || echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc
source ~/.bashrc

(macOS users: replace ~/.bashrc with ~/.zshrc.)

4 · Initialise a home directory​

safrochaind init my-moniker \
  --chain-id safro-testnet-1 \
  --home ~/.safrochain

This creates ~/.safrochain/{config,data} with:

  • config/genesis.json: placeholder, replaced below.
  • config/config.toml: CometBFT settings.
  • config/app.toml: Cosmos SDK module settings.
  • config/client.toml: CLI defaults (safrochaind config …).
  • config/priv_validator_key.json: consensus key (treat as a secret).
  • config/node_key.json: node ID for P2P.
  • data/: empty, populated as the chain syncs.

5 · Replace the placeholder genesis​

For testnet:

curl -fsSL https://raw.githubusercontent.com/Safrochain-Org/safrochain-node/main/networks/safro-testnet-1/genesis.json \
  -o ~/.safrochain/config/genesis.json

For mainnet (post-launch):

curl -fsSL https://raw.githubusercontent.com/Safrochain-Org/safrochain-node/main/networks/safrochain-1/genesis.json \
  -o ~/.safrochain/config/genesis.json

Verify the SHA-256 against the value published on Mainnet endpoints / Testnet endpoints:

shasum -a 256 ~/.safrochain/config/genesis.json

6 · Configure CLI defaults​

safrochaind config chain-id        safro-testnet-1
safrochaind config node            https://rpc.testnet.safrochain.com:443
safrochaind config keyring-backend file
safrochaind config broadcast-mode  sync
safrochaind config output          json

7 · Start the node​

Public seeds for testnet and mainnet are listed on Networks → Mainnet endpoints and Networks → Testnet endpoints. Configure them in ~/.safrochain/config/config.toml (the seeds field), then:

safrochaind start

You should see Started node and a stream of Committed state lines as the node catches up.

8 · Run as a systemd service (Linux)​

For 24/7 operation, copy this unit to /etc/systemd/system/safrochaind.service:

[Unit]
Description=Safrochain Node
After=network-online.target

[Service]
User=%u
ExecStart=%h/go/bin/safrochaind start --home %h/.safrochain
Restart=on-failure
RestartSec=5
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable --now safrochaind
sudo journalctl -u safrochaind -f

On macOS, run safrochaind start in a tmux/screen session, or wrap it in a launchd plist.

9 · Upgrading to a new release​

cd ~/safrochain-node
git fetch --tags
git checkout v<next-release>          # mainnet: e.g. v0.2.2, then v0.3.0, ...
make install
sudo systemctl restart safrochaind   # Linux only
safrochaind version

For coordinated chain upgrades use cosmovisor so the binary swap happens at the upgrade height. See Upgrades.

Common issues​

SymptomFix
make install fails building cosmwasm-vminstall clang (apt install clang / brew install llvm) and retry
safrochaind: command not foundadd ~/go/bin (or $(go env GOPATH)/bin on macOS) to $PATH
starts then exits with chain id mismatchwrong genesis: redownload the matching one
starts but stuck at height 0seeds not reachable: recheck the public seeds list on the Networks page
dial tcp ... i/o timeout on macOScheck pf/firewall and that you're not on a corporate VPN that blocks port 26656
Last updated on