The code analysis of Bitcoin - Part I

Why?

I am a big fan of Bitcoin. I am eager to find some articles which can go through every underlying technical detail, so I searched the internet but resulted in no luck. There are so many sorts of "Bitcoin for dummies" articles and books, apparently, they are not what I'm searching for. The book "Mastering Bitcoin", which is written by Andreas M. Antonopoulos, is one of the best books talking about Bitcoin, IMHO. But it is still not enough for me.
I can't find any Bitcoin code analysis articles on the internet, so I decided to clone the code and read it myself - thank god it is an open source project!. I will record what I've learned along with my study. Hope these series of articles can help, if you are doing like what I was.

First off, go to GitHub and grab the code:

  ># git clone https://github.com/bitcoin/bitcoin.git

Then let's take a look at the files/directories structure, try to figure out what "submodules" it has and then dive into each one to understand the details. Finally, connect every part together, then I believe we will be Bitcoin masters.

Where to start?

The answer is, always begin with the /bitcoin/README.md file. After reading it very carefully, I strongly recommend going through other documents reside in the /bitcoin/doc folder.

Build & run

Follow the instructions in /bitcoin/doc/README.md. It's pretty easy to build the code in Linux (especially in Ubuntu) system. Then try to run with

  ># bitcoind -printtoconsole

Ensure everything works. After that, we have set up the environment for ourselves to understand the code. We are aiming to read the code, why we need to build it? Because the best way to understand what a piece of code does is to experiment it.

Bitcoin versions

In order to keep us always on the same page, let's switch the code base to version 0.15.

  ># cd /bitcoin/
  ># git checkout 0.15

(When I'm writing this article, the newest Bitcoin version is 0.15.1).

Files & directories
Let's take a look at the files and directories in the code base:

All source codes are in the "src" folder. So open it and here is what we're having:

A glance at what is in the folders:

• bench - The code to do benchmarking.
• compat - The code to make it compatible with different building environment (OS, compiler...).
• config - Initially it is empty. All configurations will be generated during building and a file named "bitcoin-config.h" will be put here.
• consensus - The code to make Bitcoin nodes reaching consensus, including implementations of merkle trees and transactions verification.
• crypto - The code to handle all cryptography related operations, including SHA256, AES, RIPEMD160(the method to generate bitcoin's 160-bit address) and so on.
• leveldb - The key/value database. Bitcoin uses leveldb to store blocks info locally.
• obj - The folder to store compiled objects.
• obj-test - The folder to store compiled objects of test cases.
• policy - Policies used by the wallet.
• primitives - The definition of blocks and transactions.
• qt - The UI part using QT library.
• rpc - The implementation of remote process call interfaces.
• script - The Bitcoin script language handler.
• secp256k1 - A 3rd party optimized C library for EC operations on curve secp256k1.
• support - Some supporting/helper functions.
• test - The unit test cases of each module.
• univalue - A 3rd party universal value object and JSON library.
• wallet - The bitcoin wallet implementation.
• zmq - Zeromq (http://zeromq.org/). The 3rd party distributed messaging queue implementation.

All other files in "src" folder, can be considered as the main parts of Bitcoin. I listed some important files, and we will look into the code in them as we go.

• addrdb.cpp - Read/write peers info.
• base58.cpp - Bitcoin's base58 encoding/decoding.
• bloom.cpp - The bloom filters implementation.
• bitcoin-cli.cpp - The command line interface tool.
• bitcoin-tx.cpp - The bitcoin trasaction tool.
• bitcoind.cpp - The main entry of the program.
• chain.cpp - The blockchain implementation.
• txdb.cpp - The transactions.
• txmempool.cpp - The transactions pool in memeory.
• validation.cpp - The verification on blocks.

Debugging info

After compiled and installed bitcoind, use

  ># bitcoind -printtoconsole -debug

to start the bitcoind program with debugging info, and print logs to console. With debugging info turned on, many details will be revealed at runtime.

Select a text editor

I personally recommend using Sublime and SourceInsight (A Windows software, unfortunately, it has no Linux version). These text editors can build indexes through all over the code so you can jump to class and function definitions, variable and method reference very quickly. If you have your own preferable, make sure it can build indexes of the code. (Tips: in sublime, use CRTL+K, CRTL+1 to fold the code. It's very useful to outline methods in one big source file)

Next

Basically, we have everything set up for our further study now. Next, let's go into each submodule and find out what is behind the scene.