Proj Bitcoin 1: Setting up a Private Regtest Blockchain

What you need:


To make your own private blockchain, with a version of Bitcoin running on it. There are two test network types--the one we're using is the "Regtest" network, which is completely private and under our control. The coins we create won't be publicly traded, and they won't be worth any real money. The purpose of this project is merely to learn how blockchain technology works, not to get rich quick.


What is a Blockchain?

Bitcoin is a peer-to-peer network, with no central authority. Instead of being controlled by a government or bank, every "full node" on the network has a complete copy of the "distributed ledger", containing every transaction ever performed.

A transaction records the exchange of Bitcoin from one account to another.

In a Terminal window, execute this command to see the unspent balance owned by a user "Alice" on the real Bitcoin blockchain:

As shown below, Alice has two "unspent outputs", one worth 8,450,000 satoshis and one worth 100,000 satoshis.

A satoshi is the smallest unit of Bitcoin currency. There are 100,000,000 satoshis in a Bitcoin. So Alice has 0.0855 Bitcoins, or about $45 at the current Bitcoin price of $533 (as of 6-1-16).

Confirmations and Mining

When someone makes a purchase with Bitcoin, a transaction is created. This transaction is sent over the peer-to-peer network.

A typical transaction contains one input and two outputs, as shown in the figure below, taken from the Mastering Bitcoin online e-book.

With credit cards, a transaction is sent to the central bank, and once recorded there, the transaction is finalized.

But with Bitcoin, the transaction is not finalized until it is gathered together with others to form a "block" of transactions, and "signed" by a "Bitcoin miner". All the miners in the network race to be the first one to calculate a valid signature, and the first miner to succeed wins. The winning miner is rewarded with a prize of newly minted Bitcoins (currently 25 bitcoins per block) and also "transaction fees" included in each transaction. A new block is signed every 10 minutes, on average.

Even after a block is mined, it might be cancelled later and reversed. The current standard is to consider a transaction irrevocable after six confirmations, or six blocks. The author of "Mastering Bitcoin" explains the situation this way:


Bitcoin blocks are limited to a maximum size of 1 MB. This is a problem, because the number of transactions per Bitcoin block is increasing, as shown below.

Bitcoin is nearly at its limit: all blocks full. There is an active debate among Bitcoin enthusiasts about increasing the block size.

Private Blockchains

The discussion above is focused on the public blockchain, recording transactions that are worth real money. In this project, however, we will make our own private blockchain, using the "regtest" (regression testing) feature of the bitcoin client. Our coins won't be worth any real money.

Preparing Ubuntu

To prepare your Ubuntu machine, execute these commands:
sudo apt-get update
sudo apt-get install git build-essential -y
sudo apt-get install autoconf libboost-all-dev libssl-dev libprotobuf-dev protobuf-compiler libqt4-dev libqrencode-dev libtool -y
sudo apt-get install libdb5.1++-dev libevent-dev pkg-config -y 

Installing Berkeley Database

Execute these commands:

sha256sum db-4.8.30.NC.tar.gz 
The result should be 12edc0df75bf9abd7f82f821795bcee50f42cb2e5f76a6a281b85732798364ef, as shown below.

Execute these commands:

tar -xvf db-4.8.30.NC.tar.gz
cd db-4.8.30.NC/build_unix
mkdir -p build
../dist/configure --disable-shared --enable-cxx --with-pic --prefix=$BDB_PREFIX
make install
cd ../..

Compiling Bitcoin Core from Source

Execute these commands to clone the Bitcoin repository, and to see the versions available.
git clone

cd bitcoin

git tag
The latest version seems to be v0.9.5rc2, as shown below.

However, if you scroll up, you can see that this is just a cruel joke. Bitcoin developers apparently regard 0.10 as greater than 0.9, and the newest version was actually v0.12.1rc2 when I did it (6-1-16).

If you accidentally install the wrong version, and decide to reinstall a different one, you must execute this command first to clean out the old one: "git clean -f -x -d".

This behavior is in accordance with Semantic Versioning 2.0.0 standards.

Execute these commands to clone the latest version and see compile-time options.

git checkout v0.12.1rc2


./configure --help
There are a lot of options available, worth taking a look at, but for our purposes a default installation will be fine.

Execute these commands:

./configure --with-incompatible-bdb

The compiling takes about 10-20 minutes. It also requires at least 2 GB of RAM.

Execute these commands to install the bitcoin core software, and to check the installation location:

sudo make install

which bitcoind

which bitcoin-cli
Both items should be in /usr/local/bin, as shown below.

Creating a Configuration File

Execute these commands:
mkdir .bitcoin
nano .bitcoin/bitcoin.conf
Paste in these lines, replacing the password with something unique:
as shown below.

Press Ctrl+X, Y, Enter to save the file.

Starting the Bitcoin Daemon

Execute this command to start the Bitcoin daemon:
bitcoind -regtest -daemon
Execute this command to see listening processes:
netstat -pant
The daemon for our private "regtest" network is listening on port 18444, as shown below. The real bitcoin network listens on port 8333, and the public test network listens on port 18333.

Examining the Blockchain

Execute this command to see information about the blockchain:
bitcoin-cli -regtest getblockchaininfo
Scroll back up to see the start of the output. At this point, our blockchain contains zero blocks, as shown below.

Examining Wallet Status

Execute this command:
bitcoin-cli -regtest getinfo
Your wallet's "balance" is zero, as shown below.

Encrypting your Wallet

If someone steals your wallet, they get your Bitcoins, just like cash. To prevent that, your wallet should be encrypted.

Execute these commands to encrypt your wallet, restart the server, and see the wallet status again.

I'm using a password of P@ssw0rd -- of course, you should replace that with a strong password of your own choice when deploying blockchains with real value.

bitcoin-cli -regtest encryptwallet P@ssw0rd
bitcoind -regtest -daemon
bitcoin-cli -regtest getinfo
Now "getinfo" shows an "unlocked until" value of zero, indicating that the wallet is locked, as shown below.

Execute these commands to unlock your wallet for ten minutes (360 seconds), and see the wallet status again.

bitcoin-cli -regtest walletpassphrase P@ssw0rd 360
bitcoin-cli -regtest getinfo
Now "getinfo" shows an "unlocked until" value in Unix epoch format, as shown below.

Backing Up and Restoring your Wallet

Execute these commands to back up your wallet into a file named "wallet.backup", and see that file.
bitcoin-cli -regtest backupwallet wallet.backup
ls -l ~/wal*
You see a "wallet.backup" file, as shown below.

Execute these commands to unlock youur wallet and restore your wallet from backup:

bitcoin-cli -regtest walletpassphrase P@ssw0rd 360
bitcoin-cli -regtest importwallet wallet.backup

Dumping your Wallet into a Human-Readable File

The wallet file is binary and unreadable by humans. To put a readable text version into the file wallet.txt, and see the first 10 lines, execute these commands:
bitcoin-cli -regtest dumpwallet wallet.txt
head ~/.bitcoin/wallet.txt
You see a file header, followed by some addresses, as shown below.

Getting a New Address

You can have as many addresses as you wish. If you want to make it difficult for others to detect where your money is going, you can create a new bitcoin address for every transaction. That's what people mean when they say that bitcoin is "anonymous".

Execute this command to get a new address from the available pool of addresses (100, by default).

bitcoin-cli -regtest getnewaddress
The address appears, as shown below. It's a long random sequence of bytes. The address starts with "m" or "n" because it's on a test network. Bitcoin addresses on the real blockchain start with "1" or "3".

Mining a Block

Execute these commands to mine a block, and see information about the blockchain again:
bitcoin-cli -regtest generate 1

bitcoin-cli -regtest getblockchaininfo
Now the blockchain contains one block, as shown below.

On the real Bitcoin blockchain, the difficulty is set much higher, so mining a block requires an expensive cluster of specialized computers. But the difficulty is set very low on our test network, so mining blocks is easy.

Listing Transactions and Balance

Execute this command to view all your transactions:
bitcoin-cli -regtest listtransactions
There is one transaction, in the amount of 50 bitcoins, as shown below. This is your award for mining the first block.

Execute this command to view your balance:

bitcoin-cli -regtest getbalance
Your balance is 0, as shown below.

Why isn't your balance 50? Because the block you mined isn't "confirmed" yet. On the real Bitcoin blockchain, a block is confirmed when there have been 6 blocks after it mined, but on our testnet, confirmation takes 100 additional blocks.

Mining 100 More Blocks

Execute this command to mine 100 more blocks:
bitcoin-cli -regtest generate 100
You see 100 block hashes, as shown below.

Execute this command to see information about the blockchain:

bitcoin-cli -regtest getblockchaininfo
Now the blockchain contains 101 blocks, as shown below.

Execute this command to view your balance:

bitcoin-cli -regtest getbalance
Your balance is 50 bitcoins, as shown below.

Viewing Your Unspent Bitcoins

Execute this command to view your unspent Bitcoins:
bitcoin-cli -regtest listunspent
You see one transaction for 50 bitcoins, that's "spendable", as shown below.

Next Project

Now, proceed to Proj Bitcoin 2: Adding a Second Node to your Private Regtest Blockchain


Compile Bitcoin Core from Source on Ubuntu

Installing bitcoin in ubuntu

Bitcoin Developer Examples

List of address prefixes - Bitcoin Wiki

Example bitcoin.conf File

Mastering Bitcoin

How to test applications

Posted 6-2-16 by Sam Bowne