Running a Node

git clone https://github.com/btxchain/btx.git
cd btx
git checkout v0.33.2
git verify-tag v0.33.2

This guide covers starting btxd, the data directory layout, systemd service configuration, pruning, privacy networks, ZMQ notifications, and debugging.

Starting btxd

The daemon binary is btxd and the CLI client is btx-cli. After building, both live in build-btx/bin/.

Mainnet

btxd -daemon
btx-cli -getinfo

Default RPC port is 19334, P2P port is 19335. No manual configuration is required; the daemon uses a cookie file for RPC authentication by default.

Testnet

btxd -testnet -daemon

Data is stored in a testnet3/ subdirectory of the data directory.

Regtest

btxd -regtest -daemon

Regtest uses fSkipMatMulValidation=true by default, which skips the expensive MatMul proof-of-work check and allows instant block generation for testing.

Custom data directory

btxd -datadir=/path/to/data -daemon

Data directory structure

Default data directory locations:

Key contents inside the data directory:

Chain-specific data (testnet, regtest) is stored in a subdirectory of the data directory, for example testnet3/ or regtest/. The btx.conf file is shared across all chains.

Systemd service setup

BTX ships sample service files in contrib/init/. To install on a systemd-based Linux distribution:

1. Create a service user:

   sudo useradd -r -m -s /usr/sbin/nologin btx

2. Copy the service file:

   sudo cp contrib/init/bitcoind.service /usr/lib/systemd/system/btxd.service

   Edit the file to set ExecStart=/usr/bin/btxd and update the User= and Group= to btx.

3. Reload and enable:

   sudo systemctl daemon-reload
   sudo systemctl enable btxd
   sudo systemctl start btxd

4. Check status:

   sudo systemctl status btxd
   journalctl -u btxd -f

The systemd unit automatically creates and sets permissions on the data and PID directories. Auto-respawn is configured by default.

Standard Linux paths (systemd)

Pruning and disk usage

Pruning discards old block data while keeping the UTXO set and block index. This significantly reduces disk usage at the cost of being unable to serve historical blocks to other nodes.

btxd -prune=10000   # keep approximately 10 GB of block data

The minimum prune target is 550 MiB. A pruned node still validates every block during initial sync but discards block data after verification. The full UTXO set, chain state, and wallet data are retained.

Approximate full-chain storage requirements depend on chain height and transaction volume. BTX blocks can be up to 24 MB serialized / 24 MWU weight, though typical blocks are much smaller.

Tor / I2P / CJDNS support

BTX Node supports three privacy overlay networks for peer-to-peer connections. These can be used individually or combined.

Use -onlynet=onion, -onlynet=i2p, or -onlynet=cjdns to restrict outbound connections to a specific network. Multiple -onlynet flags can be combined. See the Network page for detailed configuration.

ZMQ notifications

BTX Node can publish real-time block and transaction events over ZeroMQ PUB sockets. Build with -DWITH_ZMQ=ON to enable.

btxd \
  -zmqpubhashblock=tcp://127.0.0.1:28332 \
  -zmqpubhashtx=tcp://127.0.0.1:28332 \
  -zmqpubrawtx=tcp://127.0.0.1:28333

Available notification topics:

• hashblock / rawblock — chain tip updates
• hashtx / rawtx — all transactions (mempool and block)
• hashwallettx / rawwallettx — wallet transactions only
• sequence — ordered mempool and chain events

ZMQ sockets are self-connecting and self-healing. No authentication is performed; restrict access with firewalling. See the Network page for full topic details.

Logging and debugging

The primary log file is debug.log in the data directory. Control its location with -debuglogfile=/path/to/file.

Enable category logging

btxd -debug=net -debug=rpc -debug=mempool

Common debug categories:

To enable all debug categories (verbose):

btxd -debug=1

Runtime log control

You can toggle logging categories at runtime without restarting:

btx-cli logging '["net","mempool"]' '[]'

Shrink log

Use -shrinkdebugfile to truncate debug.log on startup, keeping only the most recent entries.

RPC information

btx-cli -getinfo           # quick node summary
btx-cli getblockchaininfo  # chain state details
btx-cli getnetworkinfo     # network and protocol info
btx-cli getmempoolinfo     # mempool statistics