Bitcoin Regtest

What Is Bitcoin Regtest?

Bitcoin regtest (short for "regression test") is a local, private blockchain mode built into Bitcoin Core. It creates a brand-new blockchain from scratch on your machine, following the same consensus rules as mainnet but with one critical difference: you decide when blocks are created. There is no proof-of-work mining, no network peers, and no waiting for confirmations.

Think of regtest as a personal sandbox. You control the entire network: the nodes, the blocks, the transactions, and the timing. This makes it ideal for testing Bitcoin applications in a reproducible environment. If something goes wrong, you can wipe the chain and start over in seconds.

Regtest exists alongside two other test networks: testnet (a public network with real proof-of-work mining) and signet (a public network where blocks are signed by authorized parties). Each serves a different purpose, but regtest is the go-to choice for local development and automated testing because of its speed and isolation.

How It Works

Starting a regtest node is a single command. Bitcoin Core includes regtest as a built-in network mode accessible via the -regtest flag:

# Start a regtest node
bitcoind -regtest -daemon

# Or configure it in bitcoin.conf
# regtest=1
# rpcuser=devuser
# rpcpassword=devpass

When you first launch a regtest node, Bitcoin Core generates a fresh genesis block with the hash 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206. This genesis block is unique to regtest and differs from the mainnet genesis block.

Mining Blocks on Demand

The core feature of regtest is on-demand block generation. Instead of waiting for miners to find valid blocks (which takes roughly 10 minutes on mainnet), you generate blocks instantly with a single RPC call:

# Create a wallet
bitcoin-cli -regtest createwallet "testwallet"

# Get an address to receive mining rewards
bitcoin-cli -regtest getnewaddress

# Mine 101 blocks to that address
bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)

Why 101 blocks? Bitcoin enforces a coinbase maturity rule requiring 100 confirmations before coinbase rewards become spendable. Mining 101 blocks means the reward from block 1 has exactly 100 confirmations and is now available to spend in tests.

Transaction Testing

With spendable coins, you can build and test complete transaction workflows:

# Send bitcoin to another address
bitcoin-cli -regtest sendtoaddress "bcrt1q..." 10.0

# Check unconfirmed transactions in the mempool
bitcoin-cli -regtest getrawmempool

# Mine a block to confirm the transaction
bitcoin-cli -regtest generatetoaddress 1 $(bitcoin-cli -regtest getnewaddress)

# Verify the transaction confirmed
bitcoin-cli -regtest listunspent

This cycle of send, mine, and verify runs in under a second. On mainnet, the same workflow would take at least 10 minutes for a single confirmation, and the recommended 6 confirmations would take roughly an hour.

Network Parameters

Regtest uses distinct network parameters to avoid confusion with mainnet or testnet:

All soft forks (SegWit, Taproot) are active from block height 1 on regtest, so you can test any modern Bitcoin feature immediately without waiting for activation.

Use Cases

Unit and Integration Testing

Regtest is the foundation of Bitcoin Core's own test suite. The test/functional/ directory in the Bitcoin Core repository contains hundreds of Python-based tests that spin up regtest nodes, execute transactions, and verify behavior. Any project building on Bitcoin follows the same pattern.

Typical test scenarios include: UTXO management and coin selection, multisig and PSBT signing workflows, replace-by-fee transaction handling, script validation and spending conditions, and wallet backup and recovery procedures.

CI/CD Pipelines

Because regtest has zero external dependencies, it integrates cleanly into continuous integration environments. A common pattern uses Docker to run a regtest node alongside the application under test:

# docker-compose.yml (simplified)
services:
  bitcoind:
    image: bitcoin/bitcoin:latest
    command: bitcoind -regtest -rpcallowip=0.0.0.0/0
    ports:
      - "18443:18443"

  tests:
    build: .
    depends_on:
      - bitcoind
    environment:
      - BITCOIN_RPC_URL=http://bitcoind:18443

Tests run against a fresh chain every time, ensuring deterministic results. There are no faucet rate limits, no network latency, and no reliance on public infrastructure that might be down.

Lightning Network Development

Local regtest is the standard backend for Lightning development. Developers run multiple Bitcoin nodes and Lightning nodes (LND, Core Lightning, or Eclair) on regtest to test channel operations, payment routing, and failure scenarios.

Polar simplifies this workflow significantly. It is a free, open-source desktop application that provides a visual interface for managing regtest-based Lightning networks. With Polar, you can drag and drop to create nodes, open channels, and send payments without writing a single CLI command. Under the hood, Polar manages Docker containers running Bitcoin Core in regtest mode alongside your chosen Lightning implementation.

Polar supports LND, Core Lightning, and Eclair, letting developers test interoperability across implementations. It is particularly useful for testing channel capacity management, multi-path payment routing, and force-close recovery scenarios.

Application Prototyping

Any application that interacts with Bitcoin benefits from regtest during development. Wallet developers use it to test address generation, transaction building, and fee estimation logic. Payment processors use it to verify invoice creation and settlement flows. Layer 2 protocols like Spark rely on regtest to validate on-chain anchoring and exit transactions before deploying to production.

Regtest vs Other Test Networks

Bitcoin offers three test environments, each suited to different stages of development:

Regtest is the right choice for local development and automated testing where speed and determinism matter. Testnet and signet are better suited for testing with real network conditions: peer discovery, block propagation delays, and interaction with other participants. Most projects use regtest during development and CI, then graduate to signet or testnet for pre-production validation.

Why It Matters

Regtest is the backbone of Bitcoin development infrastructure. Without it, testing a simple transaction flow would require waiting for real blocks on a public network, acquiring test coins from faucets, and dealing with network instability. Regtest eliminates all of these friction points.

For developers building on Bitcoin Layer 2 protocols, regtest is especially critical. Testing Lightning channels, HTLCs, and on-chain settlement transactions requires precise control over block timing. A force-close test, for example, needs to simulate timelock expiration by mining a specific number of blocks: something only regtest can do reliably. Projects like Spark use regtest extensively during development to test on-chain anchoring, cooperative exits, and UTXO management before deploying to live networks.

Risks and Considerations

Not a Production Substitute

Regtest cannot replicate real-world network conditions. There is no mempool congestion, no competing transactions, no reorganizations from competing miners, and no latency from block propagation. Code that works perfectly on regtest may behave differently when confronted with these conditions on mainnet.

No Peer Testing

Because regtest is local by default, it does not test peer-to-peer networking behavior. Applications that depend on peer discovery, transaction relay, or block announcement propagation need a public test network (signet or testnet) to validate those code paths.

Consensus Divergence

Regtest activates all soft forks at block height 1, which differs from mainnet where features activate at specific heights after miner signaling. If your application depends on activation timing or needs to handle pre-activation blocks, regtest will not surface those edge cases. Additionally, the halving interval of 150 blocks means regtest reaches zero-reward blocks quickly: something that will not happen on mainnet until approximately the year 2140.

State Management

Regtest state persists in the regtest subdirectory of your Bitcoin data folder. Failing to reset state between test runs can lead to flaky tests that depend on leftover transactions or block heights. Best practice is to start each test suite with a clean chain by deleting the regtest directory and restarting the node.

For a deeper look at how Bitcoin nodes work across different network modes, see the Bitcoin node implementation comparison.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.