Skip to content

Run a Bitcoin Gold (BTG) full node

A full node validates every block and transaction against Bitcoin Gold (BTG)'s consensus rules, supports the network by relaying blocks, and gives you a trustless view of the chain. This course takes you from a fresh Ubuntu 22.04 / 24.04 install to a hardened, monitored, systemd-managed Bitcoin Gold (BTG) full node.

This walkthrough is written for bgoldd v0.17.3 and matches the configuration running at bitcoingold.services.

Who this is for

You should be comfortable with:

  • Basic Linux command line (cd, apt, systemctl, cat, nano).
  • Opening firewall ports and reading a config file.
  • The concept of "trustless validation" — you don't need to trust any third party to tell you your balance is correct.

If you prefer to install from a prebuilt binary instead of compiling, see Building from source for the compile path; everything below works the same.

What you'll build

By the end of this course you will have:

  • A compiled bgoldd binary at /usr/local/bin/bgoldd.
  • A dedicated bitcoingold system user running the daemon.
  • A bitcoingold.conf that binds RPC to localhost only and exposes P2P on 8338.
  • A systemd unit (btgd.service) that auto-restarts on failure.
  • A ufw rule allowing inbound P2P, blocking RPC from the network.
  • A logrotate policy keeping debug.log under control.
  • Verification commands that cross-check your chain tip against the public explorer.

Requirements

Resource Minimum Recommended (mainnet sync in <24 h)
OS Ubuntu 22.04 LTS Ubuntu 22.04 / 24.04 LTS
CPU 2 cores 4+ cores
RAM 4 GB 8 GB
Disk 200 GB SSD 500 GB SSD (txindex grows quickly)
Bandwidth 5 TB/month 10 TB/month (sustained relay)
Time (initial sync) 1–3 days 12–24 hours with dbcache=2000

1. Install build dependencies

sudo apt update
sudo apt install -y build-essential libtool autotools-dev automake \
  pkg-config libssl-dev libevent-dev bsdmainutils libboost-all-dev \
  libminiupnpc-dev libzmq3-dev libdb-dev libdb++-dev

If you also want the GUI wallet:

sudo apt install -y libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools

2. Clone the source

cd /usr/local/src
sudo git clone https://github.com/BTCGPU/BTCGPU.git
sudo chown -R "$USER:$USER" BTCGPU
cd BTCGPU
git log --oneline -1   # note the commit for later reference

3. Build

The full build (no GUI) takes ~10–25 minutes on a 4-core machine.

./autogen.sh
./configure --without-gui --with-incompatible-bips
make -j"$(nproc)"

Common configure flags

  • --with-gui — build the Qt5 wallet (bitcoin-qt).
  • --disable-wallet — node only, no wallet.dat, smaller attack surface.
  • --with-incompatible-bips — enable BIPs that Bitcoin Gold (BTG) adopted but BTC has not.
  • --prefix=/usr/local — install location (default).

If make fails on libdb (Berkeley DB), install libdb++-dev and re-run ./configure.

4. Install

sudo make install
which bgoldd
bgoldd --version

You should see something like Bitcoin Gold Core version v0.17.3.

5. Create the data directory and system user

sudo useradd --system --home /var/lib/bitcoingold --shell /usr/sbin/nologin bitcoingold
sudo mkdir -p /var/lib/bitcoingold/.bitcoingold
sudo chown -R bitcoingold:bitcoingold /var/lib/bitcoingold

Why /var/lib/bitcoingold?

Putting the data directory under /var/lib follows the Filesystem Hierarchy Standard. It's where other daemons (PostgreSQL, MariaDB) keep their data, so backups and monitoring tools know to look.

6. Write bitcoingold.conf

This config is what runs in production at bitcoingold.services. The values are explained inline.

sudo tee /var/lib/bitcoingold/.bitcoingold/bitcoingold.conf > /dev/null <<'EOF'
# Bitcoin Gold full node
# ------------------------------
# server=1            : accept RPC commands
# txindex=1           : maintain a full transaction index (required for explorers)
# listen=1            : accept inbound P2P connections
# port=8338           : Bitcoin Gold (BTG) P2P port (NOT 8333 — that's Bitcoin)
# discover=1          : discover own IP via upnp (only if behind NAT)
# uacomment=...       : identifies this node in the peers list
server=1
txindex=1
listen=1
port=8338
discover=1
uacomment=bitcoingold.services

# Data directory (default, but explicit is better)
datadir=/var/lib/bitcoingold/.bitcoingold/

# Logging: print to console for systemd journal, plus a real logfile
printtoconsole=1
debuglogfile=/var/log/bitcoingold.log

# RPC: bind to localhost only — never expose RPC to the network
rpcbind=127.0.0.1
rpcallowip=127.0.0.1
rpcport=8332

# Replace these with strong random values:
#   tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32 ; echo
rpcuser=CHANGE_ME
rpcpassword=CHANGE_ME_LONG_RANDOM

# Bitcoin BIP-61 peer messaging is opt-in for Bitcoin Gold (BTG); disable to reduce log noise
enablebip61=0

# IPv4 only, no Tor (turn back on if you run a hidden service)
onlynet=ipv4
listenonion=0

# We don't need this node to be a DNS seed source
dnsseed=0

# ZMQ: Blockbook consumes hashblock events on 127.0.0.1:38335
zmqpubhashblock=tcp://127.0.0.1:38335

# Connection limits: 500 inbound, 20 outbound (10 full + 10 block-relay)
maxconnections=500
maxoutbound=20
maxuploadtarget=0    # no upload cap (saturate the link; helps the network)

# Database cache in MB. 2000 is a sweet spot for 8 GB RAM nodes.
dbcache=2000

# Run as a node only; we use ElectrumG/Blockbook for the wallet side
disablewallet=1
EOF

sudo chown bitcoingold:bitcoingold /var/lib/bitcoingold/.bitcoingold/bitcoingold.conf
sudo chmod 600 /var/lib/bitcoingold/.bitcoingold/bitcoingold.conf

Lock the config file down

chmod 600 is mandatory: the file contains your RPC password in plaintext. Any user who can read it can drain the wallet.

7. Create the systemd unit

sudo tee /etc/systemd/system/btgd.service > /dev/null <<'EOF'
[Unit]
Description=Bitcoin Gold Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
User=bitcoingold
Group=bitcoingold
ExecStart=/usr/local/bin/bgoldd -daemon -conf=/var/lib/bitcoingold/.bitcoingold/bitcoingold.conf
ExecStop=/usr/local/bin/bgold-cli -conf=/var/lib/bitcoingold/.bitcoingold/bitcoingold.conf stop
Restart=on-failure
RestartSec=30
TimeoutStartSec=infinity
TimeoutStopSec=600

# --- hardening (matches production at bitcoingold.services) ---
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
ReadWritePaths=/var/lib/bitcoingold/.bitcoingold

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now btgd.service

8. Firewall

Allow inbound P2P from anywhere (so the node can serve the network), keep RPC on localhost only.

sudo ufw allow 8338/tcp comment "Bitcoin Gold (BTG) P2P"
sudo ufw status verbose

If you also run an Electrum server, Blockbook, or web dashboard on the same host, add the appropriate ports then.

Do not open 8332 to the network

Port 8332 is RPC. The rpcallowip line above restricts it to localhost, but a belt-and-braces ufw rule keeps you safe if you ever relax rpcallowip for a moment.

9. Wait for initial sync

The first sync is the slow part. On a 500 GB SSD with dbcache=2000 it typically takes 12–24 hours. Watch progress:

sudo -u bitcoingold bgold-cli -conf=/var/lib/bitcoingold/.bitcoingold/bitcoingold.conf getblockchaininfo | jq '{headers, blocks, verificationprogress, size_on_disk}'

verificationprogress should approach 0.9999…. The chain is fully synced when blocks == headers.

While it syncs, you can use the time to set up a DNS seeder role or run Blockbook on top.

10. Verification

Once sync is complete, cross-check your view against the public network.

# Peers — should grow to ~20+ outbound + 100+ inbound
bgold-cli getnetworkinfo | jq '{connections: .connections, networks: [.networks[] | {name, reachable}]}'

# Tip block hash and height
bgold-cli getbestblockhash
bgold-cli getblockcount

# Compare against the public explorer
curl -s https://explorer.bitcoingold.services/api/v2/btg/info | jq '.data | {blocks, bestblockhash}'

# Sanity: get a block from your local node and check its hash
HASH=$(bgold-cli getblockhash 800000)
bgold-cli getblock "$HASH" | jq '{hash, confirmations, height, txcount: (.tx | length)}'

If getbestblockhash matches the explorer's bestblockhash for the same height, your node is in full consensus with the network.

11. Log rotation

debug.log can grow to several GB over months. Keep it under control with logrotate.

sudo tee /etc/logrotate.d/bitcoingold > /dev/null <<'EOF'
/var/log/bitcoingold.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
    sharedscripts
    postrotate
        # bgoldd reopens the log on SIGHUP; some setups need this:
        # pkill -HUP -f bgoldd
    endscript
}
EOF

12. Maintenance

Snapshots / backups

The blockchain and wallet.dat are the only things worth backing up. The chainstate is rebuildable from blocks, so skip it.

# Snapshot a full node (run as bitcoingold)
sudo -u bitcoingold tar -cf /backup/btg-blocks-$(date +%F).tar \
    -C /var/lib/bitcoingold/.bitcoingold blocks indexes chainstate wallet.dat

Restarting safely

sudo systemctl restart btgd.service
sudo journalctl -u btgd.service -f

bgoldd writes a clean shutdown marker to debug.log. Always restart via systemctl, never kill -9 — a hard kill can corrupt the in-memory coins cache.

Upgrading

  1. sudo systemctl stop btgd.service
  2. cd /usr/local/src/BTCGPU && sudo git pull && sudo make install
  3. sudo systemctl start btgd.service
  4. tail -f /var/log/bitcoingold.log — confirm a clean startup.

Read the release notes before upgrading

Major version bumps (0.15 → 0.17) can change bitcoingold.conf defaults and deprecate RPCs. Always read the corresponding Release-Notes-vX.Y.Z.md from the wiki first.

Troubleshooting

Daemon won't start: "Unable to bind to 0.0.0.0:8338"

Another process is on the port, or you forgot sudo.

sudo ss -lntp | grep 8338

Daemon won't start: "Cannot obtain a lock on data directory"

Another bgoldd is already running, or a previous instance didn't clean up.

ps -ef | grep bgoldd
# If stale:
sudo rm /var/lib/bitcoingold/.bitcoingold/.lock

"RPC: connection refused" when using bgold-cli

You're probably running bgold-cli as root or as a different user than the daemon. Use sudo -u bitcoingold bgold-cli ... or add the same rpcuser/rpcpassword to ~/.bitcoingold/bitcoingold.conf for your local user.

"Pruning is not compatible with -txindex"

You can't have both. To enable txindex=1, leave pruning off (the default).

Chain stuck for hours at the same height

Check the DNS seeds you have configured. If you have dnsseed=0 and no -addnode entries, and your network is blocking outbound UDP/53, you may have 0 peers. Allow outbound DNS:

sudo ufw allow out 53

Out of disk space

The chain is currently ~165 GB. Add 100 GB headroom for txindex growth.

df -h /var/lib/bitcoingold
du -sh /var/lib/bitcoingold/.bitcoingold/{blocks,chainstate,indexes}

What to do next