---

name: bitcoin-testing-regtest description: | Regtest mode: instant block generation, deterministic fork, multi-node setup, generatetoaddress, fallbackfee config. USE WHEN: building Bitcoin tests, simulating network conditions, scaffolding integration tests. allowed-tools: Read, Grep, Glob

regtest

Bitcoin's "regression test" mode. Local-only chain, instant block generation, no PoW difficulty. The default for Bitcoin testing.

Setup

bitcoind -regtest -daemon -fallbackfee=0.00001
bitcoin-cli -regtest createwallet test
bitcoin-cli -regtest -rpcwallet=test getnewaddress
# bcrt1q...

# Mine 101 blocks (subsidy matures after 100)
bitcoin-cli -regtest -rpcwallet=test generatetoaddress 101 <addr>

# Now wallet has 50 BTC mature
bitcoin-cli -regtest -rpcwallet=test getbalance

-fallbackfee is required because the empty regtest mempool has no fee estimates.

Multi-node setup

# Node 1
bitcoind -regtest -datadir=/tmp/n1 -port=18444 -rpcport=18443 -daemon

# Node 2
bitcoind -regtest -datadir=/tmp/n2 -port=18445 -rpcport=18446 \
  -connect=127.0.0.1:18444 -daemon

# Node 3
bitcoind -regtest -datadir=/tmp/n3 -port=18447 -rpcport=18448 \
  -connect=127.0.0.1:18444 -daemon

Useful commands

# Mine blocks (deterministic; instant)
bitcoin-cli -regtest generatetoaddress 1 <addr>

# Reset chain (start fresh)
rm -rf ~/.bitcoin/regtest
bitcoind -regtest -daemon

# Specific block at specific time
bitcoin-cli -regtest setmocktime <unix_ts>
bitcoin-cli -regtest generatetoaddress 1 <addr>

Address prefixes

• P2PKH: m... or n....
• P2SH: 2....
• Bech32: bcrt1q....
• Bech32m: bcrt1p....

Use cases

• Unit tests that need a real bitcoind.
• Integration tests for wallet / Lightning logic.
• Demos / tutorials with deterministic state.
• Reproducing bugs with controlled chain history.

Common bugs

• Forgetting -fallbackfee → sendtoaddress errors.
• Forgetting to mine 100+ blocks before spending coinbase → "input immature".
• Mixing regtest output with mainnet RPC by accident → use distinct -datadir and explicit -regtest arg.

See also

• signet/SKILL.md
• testnet/SKILL.md
• polar/SKILL.md
• nigiri/SKILL.md
• ../core/operations/SKILL.md