Satoshi's Original Bitcoin Client - An Operational View
Preface
---------
I thought my client was taking too long to download the block chain and it
did not appear to operate smoothly. I thought I could do something to decrease
the block download time. So I downloaded the code and dug in. Ultimately,
I failed to find the silver bullet to eliminate the long download delays
(big suprise!). But I did manage to penetrate the C++ code and figure
out how things worked for the most part.
So, I decided to write down my understanding of the code from an operational
perspective, to spare those who are not fluent in C++ from having to wade
through the code, which is quite dense and bit of a chore to pick apart,
when they really just want to know "how it works".
My focus was initially on the block download process, but I decided to
go ahead and cover all the major operational aspects I could (before losing
interest
. I do think I found some areas for improvement, but that is not
the point of these articles. I will try to make it clear when I am stating
the facts versus when I am writing commentary.
I intend these articles to go into the Wiki at some point but I also
thought it would be useful to open topics in the forum in order to
allow for review in case I made a mistake or missed something big,
and for reference.
Overview
------------
This series of articles will focus on how the Satoshi bitcoin client
program operates, and less so on the protocol details and the rules
for processing blocks and transactions.
Satoshi's bitcoin client is a C++ program, so be sure to look for code in
both the .cpp and the .h header files. Also, the program is multithreaded.
This leads to some complexity and the use of certain code patterns to deal
with concurrency that may be unfamiliar to many programmers. Also, the
code is aggresive in the use of C++ constructs, so it will help to be
fluent with map, multmap, set, string, vector, iostream, and templates.
For information on how the bitcoin protocol works, see:
The original Satoshi whitepaper:
http://bitcoin.org/bitcoin.pdf The articles on the bitcoin.it Wiki:
https://en.bitcoin.it/wiki/Category:Technical With special mention of the protocol specification:
https://en.bitcoin.it/wiki/Protocol_specification And the protocol rules:
https://en.bitcoin.it/wiki/Protocol_rules-- Operations --
The client is oriented around several major operations, including:
Initialization and Startup
Upon startup, the client performs various initilization routines
including starting multiple threads to handle concurrent operations.
Node Discovery
The client uses various techniques find out about other bitcoin
nodes that may exist.
Node Connectivity
The client initiates and maintains connections to other nodes.
Sockets and Messages
The client processes messages from other nodes and sends
messages to other nodes using socket connections.
Block Exchange
Nodes advertise their inventory of blocks to each other and
exchange blocks to build block chains.
Transaction Exchange
Nodes exchange and relay transactions with each other.
The client associates transactions with bitcoin addresses in the
local wallet.
Wallet Services
The client can create transactions using the local wallet.
The client associates transactions with bitcoin addresses in the
local wallet. The client provides a service for managing
the local wallet.
RPC Interface
The client offers an JSON-RPC interface over HTTP over sockets
to perform various operational functions and to manage the local
wallet.
User Interface
The user interface code is scheduled to be superseded by bitcoin-qt.
Therefore, it is not covered in further detail.
See their individual articles for more detail on each of these operations.
-- fClient Mode --
It is worth noting that there is code in the client to allow it to
operate in a mode where it only downloads block headers.
The implementation is intended to be used as a lightweight client mode which
can operate without verifying and storing all blocks and transactions.
This is controlled by the fClient variable in the code which is currently
hard coded to false. This is currently not considered to be finished code.
This mode is known as fClient mode and the phrase Simplified Payment
Verification (or SPV) mode has also been used to describe a lightweight
client approach.
-- Main Thread Level Functions --
init.cpp:
main()
ExitTimeout
Shutdown
net.cpp:
StartNode
ThreadGetMyExternalIP
ThreadMapPort
ThreadSocketHandler
ThreadOpenConnections
ThreadMessageHandler
rpc.cpp:
ThreadRPCServer
irc.cpp:
ThreadIRCSeed
db.cpp:
ThreadFlushWalletDB
ui.cpp:
ThreadDelayedRepaint
SendingDialogStartTransfer
-- Significant Classes By File --
net.cpp/.h:
CNode: handes one socket connection
CInv
CAddress
CMessageHeader
CRequestTracker
main.cpp/.h:
CDiskTxPos
CInPoint
COutPoint
CTxIn
CTxOut
CTransaction
CMerkleTx
CTxIndex
CBlock
CBlockIndex
CDiskBlockIndex
CBlockLocator
CAlert : CUnsignedAlert
wallet.cpp/.h
CWallet : CKeyStore
CReserveKey
CWalletTx : CMerkleTx
CWalletKey
CAccount
CAccountingEntry
db.cpp/.h:
CTxDB
CKeyPool
CWalletDB
bignum.h
CBigNum
util.h
CCriticalSection: used for thread contention
--
Search on "Satoshi Client Operation" for more articles in this series.
Transaction Exchange :
https://bitcointalk.org/index.php?topic=41730.0Block Exchange :
https://bitcointalk.org/index.php?topic=41729.0Sockets and Messages :
https://bitcointalk.org/index.php?topic=41727.0Node Connectivity :
https://bitcointalk.org/index.php?topic=41726.0Node Discovery :
https://bitcointalk.org/index.php?topic=41722.0Initialization and Thread Startup :
https://bitcointalk.org/index.php?topic=41719.0
