How to understand Bitcoin source code

Question

I am not a C++ pro. I read C++ as a part of my undergrad school course. I am very passionate about the future currency i.e. Bitcoin.

But I don't understand the source code structure. How to read the source code? As I already told I am have very basic knowledge of C++.

However, I can google on the way if don't understand something(functions, libraries, headers).

The actual problem I am facing is inside src/ directory. I don't understand the flow of files and directories in src/. Which is the first file that I should probably start reading. Can any one explain me all of flow of all the project in some sort of tree like structure?

~/GitHub/bitcoin/src
❯ ls                                                                   ✔ master
Makefile.am     coincontrol.h       miner.h         script
Makefile.bench.include  coins.cpp       net.cpp         secp256k1
Makefile.qt.include coins.h         net.h           serialize.h
Makefile.qttest.include compat          netbase.cpp     streams.h
Makefile.test.include   compat.h        netbase.h       support
addrman.cpp     compressor.cpp      noui.cpp        sync.cpp
addrman.h       compressor.h        noui.h          sync.h
alert.cpp       config          obj         test
alert.h         consensus       obj-test        threadsafety.h
amount.cpp      core_io.h       policy          timedata.cpp
amount.h        core_memusage.h     pow.cpp         timedata.h
arith_uint256.cpp   core_read.cpp       pow.h           tinyformat.h
arith_uint256.h     core_write.cpp      prevector.h     torcontrol.cpp
base58.cpp      crypto          primitives      torcontrol.h
base58.h        dbwrapper.cpp       protocol.cpp        txdb.cpp
bench           dbwrapper.h     protocol.h      txdb.h
bitcoin-cli-res.rc  hash.cpp        pubkey.cpp      txmempool.cpp
bitcoin-cli.cpp     hash.h          pubkey.h        txmempool.h
bitcoin-tx-res.rc   httprpc.cpp     qt          ui_interface.h
bitcoin-tx.cpp      httprpc.h       random.cpp      uint256.cpp
bitcoind-res.rc     httpserver.cpp      random.h        uint256.h
bitcoind.cpp        httpserver.h        rest.cpp        undo.h
bloom.cpp       init.cpp        reverselock.h       univalue
bloom.h         init.h          rpcblockchain.cpp   util.cpp
chain.cpp       key.cpp         rpcclient.cpp       util.h
chain.h         key.h           rpcclient.h     utilmoneystr.cpp
chainparams.cpp     keystore.cpp        rpcmining.cpp       utilmoneystr.h
chainparams.h       keystore.h      rpcmisc.cpp     utilstrencodings.cpp
chainparamsbase.cpp leveldb         rpcnet.cpp      utilstrencodings.h
chainparamsbase.h   limitedmap.h        rpcprotocol.cpp     utiltime.cpp
chainparamsseeds.h  main.cpp        rpcprotocol.h       utiltime.h
checkpoints.cpp     main.h          rpcrawtransaction.cpp   validationinterface.cpp
checkpoints.h       memusage.h      rpcserver.cpp       validationinterface.h
checkqueue.h        merkleblock.cpp     rpcserver.h     version.h
clientversion.cpp   merkleblock.h       scheduler.cpp       wallet
clientversion.h     miner.cpp       scheduler.h     zmq

Answer 1

Recently I was in a situation where I had to work on Bitcoin-core c++ code base. Being from c# background, I had the same problem which you faced. I also looked into the solutions which everyone is suggesting, still, I want to give you a more precise solution for this question:

Pre-requisites

• You need to understand the basic of c++ project structure. something like this:

root\
    lib\
        submodule1\
        submodule2\
        MakeFile.am
    src\
        component1\
            comp1.cpp
            comp1.h
        component2\
        main.cpp
        Makefile.am
    .gitmodules
    .gitignore
    Makefile.am
    configure.ac
    autogen.sh

This the very a basic project structure and it can go to a very complex one, but just to give an idea let's bear with it. I won't give you details of these files but you can always checkout out my dedicated repository for c++ boilerplate. Files like, Makefile.am, configure.ac etc. are there for Autotools or GNU Build Tools. Basically, Autotools is a set of tools, Autoconf, Automake, make utility and Libtools, used to build c++ project.

• Get the basic of Autotools

Let's start

• Download Bitcoin-core and open /src/Makefile.am.
• The Bitcoin code base is a combination of several programs like bitcoind, bitcoin-cli, bitcoin-tx and bitcoin-qt . You can see these programs mentioned in src/Makefile.am file, search for bin_PROGRAMS macro.

if BUILD_BITCOIND
  bin_PROGRAMS += bitcoind
endif
if BUILD_BITCOIN_CLI
  bin_PROGRAMS += bitcoin-cli
endif
if BUILD_BITCOIN_TX
  bin_PROGRAMS += bitcoin-tx
endif

• It is important to know which executable you want to debug? - I am giving an example of bitcoind

• Bitcoin's developers have converted modules (consensus, server, cli, wallet, common, crypto etc.) into static libraries (.a files) so that they can be shared and used across all these programs. In order to understand how these files are managed, as I said, start looking into the Makefile.am, present inside src directory. For example:

• In the bitcoin's src/Makefile.am file, we have bitcoind right? Let's search this text in that file. You will get bitcoind_SOURCES and bitcoind_LDADD macros for the source file of that program (basically the file where main() is defined) and linked static libraries (.a files) to bitcoind program respectively.

• Now let's look for one of the linked libraries, say libbitcoin_server, you will find libbitcoin_server_a_CPPFLAGS, libbitcoin_server_a_CXXFLAGS and libbitcoin_server_a_SOURCES macros. In libbitcoin_server_a_SOURCES macro, you have all .cpp and .h files defined there.

I hope these would have given you some insights to start with. Soon I will be writing a blog on this topic. Will edit this answer once done.

EDIT: here is a blog on this topic which I have written. Hope that will help.

Answer 2

I'm in my final year of college and I remember being in your exact situation 2 years ago. In my view you can adopt 2 strategies at this stage.

You need to understand the protocol first, and reading Satoshi's orginal paper, or any of the easier options is essential. It also helps a lot to understand the conceptual differences between bitcoin and other currencies like Ripple and Peercoin.

If your intention is to learn as much about the bitcoin implementation as possible, I would suggest you give up on bitcoin-core and shift to one of the python implementations. Now, there are a few quirks about the python implementations, but your learning would be much faster and you'd be in a much better position to understand the cpp code later.

If you want to stick to bitcoin-core, and are willing to tolerate a steep learning curve, there are still a few resources to sweeten it. You need to understand that it's not just cpp that you need to master to understand bitcoin core, but a lot of the GNU build system, the makes and the autoconfs and such stuff.

Now to help you understand the structure of the code in src, you could check this out.

Edit (7:7:2016):A lot of the new discussions in the bitcoin:core world, revolves around the CPP language itself. CPP itself undergoes considerable change every 4 years and there are many discussions around which CPP language features can be implemented/ incorporated into bitcoin-core. So it is required that you have a thorough understanding of CPP along with new language features that keep getting added, and their relations to the previous features.

Answer 3

I have a different approach to it. You can use this too.

1. Bitcoin uses Doxygen comments to explain the code. You can take the most recent copy of the code, build class hierarchy yourself using Doxygen, and then navigate through the various classes.

2. The next step would be to build it and run it in -regtest mode.

3. Use gdb to add breakpoints, and inspect the flow.

4. You can start with init and util files and then go through others. They have generic code, logging and files. And then get to the net.cpp, validation.cpp to find the more detailed logic.

5. In my opinion, diving into the code, getting messy is a much better approach rather than reading more. Get dirty into the code, write some of it, get errors, and understand on the way.

Answer 4

The Bitcoin-qt source code grew out of the original code written by Satochi. The latter, in my opinion, is much cleaner and easier to read. I have a new book that analyzes the Statochi's original source code at lulu.com: A Dissection of Bitcoin