Operators

Node Setup

Install and run a BitSong full node on the crescendo-1 testnet from source, binary, or Docker.

This guide walks you through preparing your system, installing the bitsongd binary, and running a full node on the crescendo-1 testnet. Choose your preferred installation method below.

Prerequisites

Before installing the node, ensure your system is up to date and has the necessary dependencies installed. These instructions are tailored for Ubuntu systems.

Disable IPv6

BitSong nodes require IPv6 to be disabled to avoid connectivity issues. Add the following kernel parameters and apply them:

Terminal

echo "net.ipv6.conf.all.disable_ipv6=1" | sudo tee -a /etc/sysctl.conf
echo "net.ipv6.conf.default.disable_ipv6=1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Update your system

Start by updating your system packages to the latest versions:

Terminal

sudo apt update && sudo apt upgrade -y

Install core dependencies

Install the essential build tools and networking utilities:

Terminal

sudo apt install git build-essential ufw curl jq -y

Install Go

You need Go 1.23+ to build the node from source or run certain utilities. Install Go using the community script (adjusted for the required version):

Terminal

wget -q -O - https://git.io/vQhTU | bash -s -- --version 1.23.12

After installation, reload your shell profile to make go available in the current session:

Terminal

source $HOME/.bashrc

Install bitsongd

Build the bitsongd binary directly from the feat-hyperlane branch of the official repository.

Verify Go installation

Ensure Go is properly installed and available in your PATH:

Terminal

go version
# go version go1.23.12 linux/amd64

Clone the repository

Terminal

git clone https://github.com/bitsongofficial/go-bitsong.git
cd go-bitsong
git checkout feat-hyperlane

Build and install

Terminal

make install

This installs bitsongd to your $GOPATH/bin. Verify it works:

Terminal

bitsongd version
# 0.23.1-5-g6ef6074

Download a pre-built binary directly from GitHub.

Download the binary

Download the latest bitsongd binary for your platform from the go-bitsong releases page.

# Example for Linux amd64
wget https://github.com/bitsongofficial/go-bitsong/releases/download/<version>/bitsongd-linux-amd64
mv bitsongd-linux-amd64 bitsongd
chmod +x bitsongd

Move to your PATH

sudo mv bitsongd /usr/local/bin/

Verify installation

bitsongd version

Run bitsongd inside a Docker container without installing Go or the binary locally.

Pull the image

docker pull ghcr.io/bitsongofficial/go-bitsong:feat-hyperlane

Create a data directory

mkdir -p $(pwd)/.data

Use a shell alias

To follow the rest of this guide seamlessly, create a terminal alias:

alias bitsongd='docker run --rm -it -v $(pwd)/.data:/root/.bitsongd ghcr.io/bitsongofficial/go-bitsong:feat-hyperlane bitsongd'

Now you can use bitsongd commands as if the binary were installed natively.

Initialize the Node

Set your chain ID and node name, then initialize the configuration files:

Terminal

CHAIN_ID="crescendo-1"
MONIKER="<your-node-name>"

bitsongd init $MONIKER --chain-id $CHAIN_ID --default-denom utbtsg

Replace <your-node-name> with a unique name that identifies your node on the network explorer.

Download Genesis

Download the genesis file from the networks repository:

Terminal

curl -L https://raw.githubusercontent.com/bitsongofficial/networks/refs/heads/master/testnet/crescendo-1/genesis.json -o ~/.bitsongd/config/genesis.json

The genesis file contains the initial state of the blockchain, including genesis accounts, chain parameters, and the initial validator set.

Configure the Node

Consensus Timing

Optimize block times specifically for the testnet environment:

~/.bitsongd/config/config.toml

sed -i 's/timeout_propose = "3s"/timeout_propose = "2s"/' ~/.bitsongd/config/config.toml
sed -i 's/timeout_prevote = "1s"/timeout_prevote = "500ms"/' ~/.bitsongd/config/config.toml
sed -i 's/timeout_precommit = "1s"/timeout_precommit = "500ms"/' ~/.bitsongd/config/config.toml
sed -i 's/timeout_commit = "5s"/timeout_commit = "2s"/' ~/.bitsongd/config/config.toml

Network Settings

Enable external RPC access and Cross-Origin Resource Sharing (CORS):

~/.bitsongd/config/config.toml

sed -i 's|laddr = "tcp://127.0.0.1:26657"|laddr = "tcp://0.0.0.0:26657"|' ~/.bitsongd/config/config.toml
sed -i 's/cors_allowed_origins = \[\]/cors_allowed_origins = ["*"]/' ~/.bitsongd/config/config.toml

API Settings

Enable the REST API and set the minimum gas prices:

~/.bitsongd/config/app.toml

sed -i '/^\[api\]/,/^\[/{s/^enable = false/enable = true/}' ~/.bitsongd/config/app.toml
sed -i 's/^swagger = false/swagger = true/' ~/.bitsongd/config/app.toml
sed -i 's/^enabled-unsafe-cors = false/enabled-unsafe-cors = true/' ~/.bitsongd/config/app.toml
sed -i 's/^minimum-gas-prices = ".*"/minimum-gas-prices = "0utbtsg"/' ~/.bitsongd/config/app.toml

The minimum gas price is set to 0utbtsg for easy testing on the testnet. On mainnet, this must always be set to a non-zero value to prevent spam.

Add Seeds and Persistent Peers

Your node needs peers to discover the network. Update the persistent_peers field with addresses from the networks repository:

~/.bitsongd/config/config.toml

sed -i 's/persistent_peers = ".*"/persistent_peers = "83004624e56c4569036d47dbe1edb038d2b41e15@178.104.0.132:26656"/' ~/.bitsongd/config/config.toml

Without seed nodes or persistent peers, your node cannot discover and connect to the network. Always check the official networks repository for the latest active peer list.

Start the Node

Run the node in the foreground:

Terminal

bitsongd start

To run the node in the background and save the output to a log file:

Terminal

nohup bitsongd start > bitsongd.log 2>&1 &

For production environments, use systemd to run the node as a background service with automatic restarts.

Create the service file

Terminal

sudo tee /etc/systemd/system/bitsongd.service > /dev/null <<EOF
[Unit]
Description=BitSong Network Daemon
After=network-online.target

[Service]
User=$USER
WorkingDirectory=$HOME/.bitsongd
ExecStart=$(which bitsongd) start --home $HOME/.bitsongd
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target
EOF

Enable the service

Terminal

sudo systemctl daemon-reload
sudo systemctl enable bitsongd

Start the node

Terminal

sudo systemctl start bitsongd

Check service status

Terminal

sudo service bitsongd status

View logs

Terminal

sudo journalctl -u bitsongd -f

Run the node in a detached container:

docker run -d \
    --name crescendo-1 \
    -v $(pwd)/.data:/root/.bitsongd \
    -p 26656:26656 \
    -p 26657:26657 \
    -p 1317:1317 \
    -p 9090:9090 \
    ghcr.io/bitsongofficial/go-bitsong:feat-hyperlane \
    bitsongd start

View the live logs:

docker logs -f crescendo-1

Exposed Ports

Port	Service	Description
`26656`	P2P	Node-to-node network communication
`26657`	RPC	CometBFT RPC interface
`1317`	REST API	Cosmos SDK LCD endpoints
`9090`	gRPC	Cosmos SDK gRPC endpoints

Verify the Node

Check that your node is running and syncing with the network:

curl -s http://localhost:26657/status | jq '.result.sync_info'

Your node is fully synced and ready when the catching_up field returns false.

Manage the Node

# Stop the node (if running in background)
pkill bitsongd

# View live logs
tail -f bitsongd.log

# View live logs
sudo journalctl -u bitsongd -f

# Stop the node
sudo systemctl stop bitsongd

# Restart the node
sudo systemctl restart bitsongd

# Check status
sudo service bitsongd status

# Stop the node container
docker stop crescendo-1

# Start the node container again
docker start crescendo-1

# Remove the container (data persists in the .data/ directory)
docker rm crescendo-1

Next Steps

Once your node is fully synced, you can proceed to set up your keys and join the active validator set.

Create a Wallet

Generate or import an operator wallet to manage funds and validator transactions.

Join as a Validator

Stake your tokens, define your commission rates, and register your node on the network.

Edit this pageorReport an issue

Introduction

Overview for node operators joining the BitSong crescendo-1 testnet.

Create a Wallet

Create a BitSong wallet using the bitsongd CLI for the crescendo-1 testnet.