Bitcoin Core Operations

Running Bitcoin Core

Configuration file

~/.bitcoin/bitcoin.conf (Linux/macOS) or %APPDATA%\Bitcoin\bitcoin.conf (Windows). Optional -conf= flag.

Section markers

# Top-level: applied to all networks
dbcache=4096

[main]
# Mainnet-only
prune=550

[test]
# Testnet
[signet]
# Signet
[regtest]
# Regtest

The chain=test/signet/regtest cmdline flag selects active network. Without [section], top-level options apply universally.

Key options

Initial Block Download (IBD)

Phases:

1. Header sync — fast, all headers from a single peer.
2. Block download — parallel download from multiple peers.
3. Block validation — script verify, UTXO set update.

Tips:

• Use a fast SSD; HDD adds days.
• dbcache=4096 (or higher with RAM) speeds up phase 3 dramatically.
• Bandwidth: ~600 GB. Restrict via maxuploadtarget= if metered.
• After IBD, you can shrink dbcache to 450.

Pruning vs txindex

• Pruned (550-15000 MB):
  • Fast disk usage; minimal historical access.
  • Cannot serve old blocks to peers (becomes NODE_NETWORK_LIMITED).
  • Cannot run Electrs / serve historical getrawtransaction.
• Full (no prune):
  • ~700 GB disk + growing.
  • Can serve any block to peers.
  • Required for indexers.
• txindex=1:
  • Adds ~80 GB.
  • Required for arbitrary getrawtransaction.
  • Cannot combine with prune.

For a Lightning node: full + blockfilterindex=1 is typical (no txindex needed; LDK/CLN use filter scan).

Tor configuration

proxy=127.0.0.1:9050
listenonion=1
bind=127.0.0.1

bitcoind auto-creates a Tor v3 hidden service via torcontrol (needs controlport=9051 + cookie auth or password in torrc).

debug.log

Located at ~/.bitcoin/debug.log (or ~/.bitcoin/<chain>/debug.log).

Categories: getrawtransaction, mempool, net, prune, validation, zmq. Enable verbosity:

debug=mempool
debug=validation

Or all: debug=1. Performance impact moderate.

Key patterns:

• UpdateTip: — new block.
• received block — block arrival.
• txn-already-known — duplicate broadcast.
• bad-txns-inputs-missingorspent — invalid input.
• Pre-allocating up to ... — file allocation messages.

systemd unit

[Unit]
Description=Bitcoin Core
After=network-online.target

[Service]
ExecStart=/usr/local/bin/bitcoind -daemon -conf=/etc/bitcoin/bitcoin.conf
ExecStop=/usr/local/bin/bitcoin-cli stop
Type=forking
PIDFile=/var/lib/bitcoind/bitcoind.pid
User=bitcoin
Group=bitcoin
Restart=on-failure

[Install]
WantedBy=multi-user.target

Backup considerations

• wallet.dat (legacy) or wallets/<name>/wallet.dat (descriptor).
• For descriptor wallets: backup is just the descriptors + private keys (listdescriptors true).
• Stop bitcoind before file copy or use backupwallet RPC for consistent snapshot.

Common bugs

• Setting dbcache=8000 on a system with 4 GB RAM → OOM.
• Using txindex=1 and prune=N>0 simultaneously → bitcoind exits on startup.
• Multi-wallet without explicit rpcwallet parameter → RPC fails with "Wallet file not specified".
• rpcbind=0.0.0.0 without firewall → exposes RPC to internet. Always pair with rpcallowip= or use SSH tunnel.
• Insufficient dbcache during IBD → 4x slower sync.

See also

• rpc/SKILL.md
• indexes/SKILL.md
• zmq/SKILL.md
• ../../infrastructure/node-distros/SKILL.md