Running a Node

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:

Platform	Path
Linux	~/.bitcoin/
macOS	~/Library/Application Support/BTX/
Windows	%LOCALAPPDATA%\Bitcoin\

Key contents inside the data directory:

Path	Description
blocks/	Raw block data (blkNNNNN.dat, 128 MiB each) and block index (LevelDB)
chainstate/	UTXO set (LevelDB)
wallets/	Wallet databases (SQLite or BDB)
btx.conf	User configuration file (not created automatically)
debug.log	Debug and general log output
mempool.dat	Mempool dump on shutdown
peers.dat	Peer address database
.cookie	Session RPC authentication cookie
onion_v3_private_key	Tor v3 onion service key (when -listenonion is active)
i2p_private_key	I2P address key (when -i2psam is set)

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)

Item	Path
Binary	/usr/bin/btxd
Configuration	/etc/btx/btx.conf
Data directory	/var/lib/btxd
PID file	/run/btxd/btxd.pid

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.

Network	Key flag	Notes
Tor	-proxy=127.0.0.1:9050	Tor v3 onion services only. Automatic onion service creation when Tor control socket is available.
I2P	-i2psam=127.0.0.1:7656	Requires an I2P router with SAM v3.1 bridge enabled (i2pd or Java I2P).
CJDNS	-cjdnsreachable	Encrypted IPv6 mesh. Peers use fc00::/8 addresses.

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:

Category	Description
net	P2P network messages
rpc	RPC call details
mempool	Mempool activity
tor	Tor integration details
i2p	I2P integration details
validation	Block and transaction validation
walletdb	Wallet database operations

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