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 installing the bitsongd binary and running a full node on the Crescendo-1 testnet. Choose your preferred installation method below.

Install bitsongd

Build the bitsongd binary from the feat-hyperlane branch.

Install Go

You need Go 1.22+. Verify your installation:

go version

Clone the repository

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

Build and install

make install

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

bitsongd version

Download a pre-built binary 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

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 an 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:

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

bitsongd init $MONIKER \
    --chain-id $CHAIN_ID \
    --default-denom ubtsg

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

Download Genesis

Download the genesis file from the networks repository:

curl -L https://raw.githubusercontent.com/bitsongofficial/networks/main/crescendo-1/genesis.json \
    -o ~/.bitsongd/config/genesis.json

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

Configure the Node

Consensus Timing

Optimize block times for the testnet:

~/.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 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 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 = "0ubtsg"/' ~/.bitsongd/config/app.toml

The minimum gas price is set to 0ubtsg for easy testing. On mainnet this should always be set to a non-zero value.

Add Seeds / Persistent Peers

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

sed -i 's/persistent_peers = ".*"/persistent_peers = "<peer-addresses>"/' ~/.bitsongd/config/config.toml

Without seed nodes or persistent peers, your node cannot discover and connect to the network. Check the networks repo for the latest peer list.

Start the Node

bitsongd start

To run in the background:

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

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 logs:

docker logs -f crescendo-1

Exposed Ports

Port	Service
`26656`	P2P — node-to-node communication
`26657`	RPC — CometBFT RPC
`1317`	REST API — Cosmos SDK LCD
`9090`	gRPC — Cosmos SDK gRPC

Verify the Node

Check that your node is running and syncing:

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

Your node is fully synced when catching_up is false.

Manage the Node

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

# View logs
tail -f bitsongd.log

# Stop the node
docker stop crescendo-1

# Start it again
docker start crescendo-1

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

Next Steps

Once your node is synced, create a wallet and then join as a validator.

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.