Build Your Own Bitcoin Main-net

During my initial research period at UAB, I began developing a replica of the real Bitcoin mainnet. While this might sound unusual—especially given the existence of testnet and regtest networks—there’s a clear motivation behind it.

Our research team needed a controlled environment to analyse wallet fingerprints for a further study on address clustering. Since many wallets offer limited or no support for testnet or regtest, we created a full-featured, isolated mainnet that behaves like the real Bitcoin network while remaining entirely under our control.

The implemented network is built directly from the original Bitcoin Core source code, but it operates in complete isolation from Bitcoin’s public mainnet.

Why build your own mainnet?

Creating a private Bitcoin mainnet replica opens the door to capabilities that are otherwise impossible or impractical to achieve.

Benefits

• Total control over the chain
  • Execute tests in a “distributed‑nature” environment without relying on real distributed infrastructure.
  • Perform large‑scale transaction testing.
• Easy deployment, since every node runs inside a Docker container.
• Compatible with software and hardware that only operate in mainnet environments.
• Zero‑cost transactions, enabling unlimited experimentation.

Requirements

To ensure that the chain works exactly as expected, two constraints must be respected:

• SegWit and Taproot must be enabled from the genesis block.
  Their activation heights influence transaction validity; using these features before their expected height would cause nodes to reject the blocks.
• The network must remain fully isolated from the internet to prevent accidental synchronization with the real Bitcoin blockchain.

Architecture

We define the network with three critical node types:

• Full Node: Ensures consensus on the chain.
• Router Node: Manages peer connectivity.
• Miner Node: Mines a block whenever a transaction is sent into the network.

Each node is built into a custom Ubuntu-based Docker image containing Bitcoin Core 24.0.1, resulting in an image size of approximately 5.11 GB.
The associated Dockerfile clones Bitcoin Core, applies some modifications, compiles it, and configures the node for execution.

Modified Bitcoin Core files

The two required modifications are:

• chainparams.cpp — SegWit and Taproot are activated at genesis.
• mining.cpp — Removes initial block validation checks to allow mining even when the node is not synchronized.

An entrypoint script ensures the service starts with minimal permissions and only launches Docker if the bitcoind daemon is healthy.

Configuring bitcoin.conf

The bitcoin.conf file defines how each Bitcoin node behaves within the replica network.

To achieve the expected behavior, you should configure at least:

• rpcallowip — Restrict RPC access to the Docker network or a specific IP.
• paytxfee — Set a static fee (e.g., 0.0001) since fee estimation will fail on an empty chain.
• minimumchainwork = 0 — As the network starts fully fresh.
• txindex = 1 — Optional, but useful for exploring transactions.

💭 You can experiment with bitcoin.conf settings here :)

Network setup

Each node is deployed inside a Docker network, ensuring full isolation from external peers.
Connections between nodes rely on addnode, linking all peers through the router node.

You can connect external software wallets using RPC, but only from allowed endpoints.

Mining

Mining can be done through simple scripts. Given the network’s difficulty of 1, block discovery is almost instantaneous.

Although a basic Python mining script is available in the repository, we replaced it with a compact little ASIC miner for more realistic testing.

Add-ons

Just like in the real Bitcoin network, additional services can be integrated.

Faucet

We implemented a lightweight server running to distribute free coins for testing.

Block Explorer

A local Dockerized deployment of Mempool Space provides full visibility into blocks and transactions.

Installation guide

Alright, the real fun begins now. How do we build it and actually use it? You’ve got a detailed guide over on the GitHub README, but let me break it down for you here.

Prerequisites

You’ll need Docker (v20.10 or higher recommended) installed on your system.

Method 1: Download the image from GitHub Container Registry

You can directly pull the pre-built Docker image and run the setup script without building the image from source following these steps:

# Pull the image from the GitHub Container Registry
docker pull ghcr.io/dmenec/mainnet_testbed:1.0

# Clone the repository
git clone https://github.com/Dmenec/BTC-Labnet.git
cd BTC-Labnet

# Run the script to set up Docker containers
./start.sh

Method 2: Build from source

Follow these steps to build the image from source:

# Clone the repository
git clone https://github.com/Dmenec/BTC-Labnet.git
cd BTC-Labnet

# Run the script to set up Docker containers
./start.sh

After execution, three interconnected Bitcoin nodes (bc-node1, bc-node2, and bc-node3) will be created.

Setup process details

Building a customized Docker image for Bitcoin Core

First, modify Bitcoin Core to adjust the code and enable SegWit and Taproot. Then, create a Dockerfile using your own configuration to build your custom Bitcoin Core image. Finally, build the Docker image by running:

docker build -t bitcoin .

Setting up the Docker network

Create a Docker bridge network to isolate your Bitcoin nodes:

docker network create -d bridge bitcoin_network

Running Bitcoin nodes

Start your Bitcoin node with the following command:

docker run -it -d --network bitcoin_network --name bc-node1 -p 8333:8333 -p 8332:8332 bitcoin -printtoconsole -txindex=1 -reindex

As you can see, installing it isn’t too complicated. While the build does compile Bitcoin Core, so it might take a few minutes, once it’s done… you’ll have all the power to do whatever you want with your Bitcoin blockchain clone!