Skip to content

regtest.md

Latest commit

 

History

History
130 lines (82 loc) · 5.15 KB

regtest.md

File metadata and controls

130 lines (82 loc) · 5.15 KB
Raw

Bitcoin regtest: instant, private testing

Testnet only. Everything here runs on a throwaway local chain. No real coins, no real network, nothing worth anything.

This walkthrough pairs with the site guide at https://testnethub.com/regtest. Read that for the concepts; run this for the commands.

What regtest is

Regression test mode (regtest) is a private Bitcoin network that lives entirely on your own machine. It is the fastest way to test wallet code, transaction building, and node RPC without waiting on anyone.

Three things make it different from public testnet:

  • Private and local. Your node is the whole network. Nobody else connects, and your chain resets whenever you want.
  • You mine on demand. There is no proof-of-work race. You create blocks with a single command, the instant you need them.
  • Instant confirmations. A transaction confirms the moment you mine a block, so a full send-and-confirm cycle takes seconds instead of minutes.

The trade-off: because it is your own isolated chain, a regtest coin means nothing anywhere else, and no faucet or block explorer knows about it.

Start the node

Launch bitcoind in regtest mode as a background daemon:

bitcoind -regtest -daemon

Every command below talks to that daemon with the -regtest flag. Check it is up:

bitcoin-cli -regtest getblockchaininfo

You should see "chain": "regtest" and a block count of 0 on a fresh chain.

Create a wallet and an address

Newer versions of Bitcoin Core do not load a wallet automatically, so create one first:

bitcoin-cli -regtest createwallet "test"

Then generate an address to receive coins:

bitcoin-cli -regtest getnewaddress

That prints an address such as bcrt1q.... The bcrt prefix is the giveaway that you are on regtest. Save it in a shell variable so the next commands can reuse it:

ADDR=$(bitcoin-cli -regtest getnewaddress)
echo "$ADDR"

Mine blocks and the 100-block maturity rule

On regtest you produce blocks yourself with generatetoaddress. The address you pass receives the block reward (the coinbase output).

Here is the catch that trips people up: a coinbase output cannot be spent until 100 more blocks are mined on top of it. This is the coinbase maturity rule, and it is the same on mainnet. It exists so that a reorg cannot leave someone spending a reward that no longer exists.

So mining one block gives you a reward you cannot touch yet. To get spendable coins you mine 101 blocks: the first block's reward matures once 100 blocks sit on top of it.

bitcoin-cli -regtest generatetoaddress 101 "$ADDR"

That returns the list of block hashes it created and finishes in well under a second.

Check the balance

Now the first reward has matured, so the wallet shows a spendable balance:

bitcoin-cli -regtest getbalance

You should see 50.00000000. Only the first block's reward is mature; blocks 2 through 101 are still locked behind their own 100-block windows, which is exactly what the maturity rule predicts.

Send a transaction and confirm it

Make a second address to send to. In real life this belongs to someone else; on regtest one wallet playing both sides is fine for testing:

DEST=$(bitcoin-cli -regtest getnewaddress)
bitcoin-cli -regtest sendtoaddress "$DEST" 10

sendtoaddress returns the transaction id. At this point the transaction sits in your mempool, unconfirmed. Confirm it by mining a single block:

bitcoin-cli -regtest generatetoaddress 1 "$ADDR"

Look up the transaction to confirm it landed in a block:

bitcoin-cli -regtest gettransaction <txid>

The confirmations field is now 1. That is the whole loop: build, broadcast, mine, confirm, in seconds.

Shut down and reset

Stop the daemon cleanly:

bitcoin-cli -regtest stop

Your regtest chain data sits under the regtest/ subfolder of your Bitcoin data directory. Delete that folder to wipe the chain and start from block 0 again. Because none of it is shared, throwing it away costs nothing.

When to prefer regtest over public testnet

Reach for regtest when you want speed and control:

  • Writing or debugging code that builds, signs, and sends transactions.
  • Testing confirmation logic, since you decide exactly when a block appears.
  • Reproducing an edge case on demand, including reorgs and specific block heights.
  • Running automated tests in CI, where waiting on a public network is a non-starter.
  • Working offline or keeping your testing private.

Reach for public testnet (such as testnet4) when you need realism:

  • Checking that your app talks to real peers, faucets, and block explorers.
  • Testing fee estimation and mempool behavior under genuine network conditions.
  • Sharing a transaction or address with someone else so both sides see the same chain.
  • Any final check before mainnet, where you want conditions as close to real as testnet allows.

A common workflow uses both: build and iterate fast on regtest, then run a final pass on public testnet before going live. For the public-network recipes, see the rest of testnet-examples and the TestnetHub guides.