diff --git a/ch03.asciidoc b/ch03.asciidoc index 8fd5f52e..75e01836 100644 --- a/ch03.asciidoc +++ b/ch03.asciidoc @@ -6,23 +6,23 @@ source_ project and the source code is available under an open (MIT) license, free to download and use for any purpose. More than just being open source, Bitcoin is developed by an open community of volunteers. At first, that community consisted of -only Satoshi Nakamoto. By 2016, bitcoin's source code had more than 400 +only Satoshi Nakamoto. By 2023, Bitcoin's source code had more than 1,000 contributors with about a dozen developers working on the code almost full-time and several dozen more on a part-time basis. Anyone can contribute to the code—including you! ((("bitcoin whitepaper")))((("Satoshi client")))((("reference implementation", see="Bitcoin Core")))((("Bitcoin Core", "reference -implementation")))When bitcoin was created by Satoshi Nakamoto, the +implementation")))When Bitcoin was created by Satoshi Nakamoto, the software was mostly completed before the whitepaper reproduced in <> was published. Satoshi wanted to make sure it worked before publishing about it. That first implementation, then simply known as "Bitcoin", has been heavily modified and improved. It has evolved into what is known as _Bitcoin Core_, to differentiate it from other implementations. Bitcoin Core is -the _reference implementation_ of the Bitcoin system, meaning that it is +the _reference implementation_ of the Bitcoin system, meaning that it provides a reference for how each part of the technology should be -implemented. Bitcoin Core implements all aspects of bitcoin, including +implemented. Bitcoin Core implements all aspects of Bitcoin, including wallets, a transaction and block validation engine, and all modern parts of Bitcoin peer-to-peer communication. @@ -38,7 +38,7 @@ image::images/mbc2_0301.png["Bitcoin Core Architecture"] ((("development environment", "setup", see="Bitcoin Core")))If you're a developer, you will want to set up a development environment with all -the tools, libraries, and support software for writing bitcoin +the tools, libraries, and support software for writing Bitcoin applications. In this highly technical chapter, we'll walk through that process step-by-step. If the material becomes too dense (and you're not actually setting up a development environment) feel free to skip to the @@ -54,7 +54,7 @@ source code can be downloaded as a archive or by cloning the authoritative source repository from GitHub. ((("Bitcoin Core downloads")))On the https://bitcoincore.org/bin/[Bitcoin Core download page], select the most recent version and download the compressed -archive of the source code, e.g., +bitcoin-0.15.0.2.tar.gz+. ((("GitHub +archive of the source code. ((("GitHub bitcoin page")))Alternatively, use the git command line to create a local copy of the source code from the https://github.com/bitcoin/bitcoin[GitHub bitcoin page]. @@ -101,7 +101,7 @@ have it already. When the git cloning operation has completed, you will have a complete local copy of the source code repository in the directory _bitcoin_. -Change to this directory by typing ++**cd bitcoin**++ at the prompt: +Change to this directory using the +cd+ command: ---- $ cd bitcoin @@ -111,7 +111,7 @@ $ cd bitcoin ((("Bitcoin Core", "compiling from source code", "version selection")))By default, the local copy will be synchronized with the -most recent code, which might be an unstable or beta version of bitcoin. +most recent code, which might be an unstable or beta version of Bitcoin. Before compiling the code, select a specific version by checking out a release _tag_. This will synchronize the local copy with a specific snapshot of the code repository identified by a keyword tag. Tags are @@ -163,12 +163,11 @@ nothing to commit, working tree clean configuration")))((("documentation")))((("build documentation", seealso="Bitcoin Core")))The source code includes documentation, which can be found in a number of files. Review the main documentation located -in _README.md_ in the _bitcoin_ directory by typing ++**more -README.md**++ at the prompt and using the spacebar to progress to the -next page. In this chapter, we will build the Bitcoin Core daemon +in _README.md_ in the _bitcoin_ directory. +In this chapter, we will build the Bitcoin Core daemon (server), also known as +bitcoind+ on Linux (a Unix-like system). Review the instructions for -compiling the +bitcoind+ command-line client on your platform by typing -++**more doc/build-unix.md**++. Alternative instructions can be found in +compiling the +bitcoind+ command-line client on your platform by reading ++doc/build-unix.md+. Alternative instructions can be found in the _doc_ directory; for example, _build-windows.md_ for Windows instructions. As of this writing, instructions are available for Android, FreeBSD, NetBSD, OpenBSD, MacOS (OSX), Unix, and Windows. @@ -197,8 +196,8 @@ The _autogen.sh_ script creates a set of automatic configuration scripts that will interrogate your system to discover the correct settings and ensure you have all the necessary libraries to compile the code. The most important of these is the +configure+ script that offers a number -of different options to customize the build process. Type -++**./configure --help**++ to see the various options: +of different options to customize the build process. Use the ++--help+ flag to see the various options: ---- $ ./configure --help @@ -278,7 +277,7 @@ complete, depending on the speed of your CPU and available memory. During the compilation process you should see output every few seconds or every few minutes, or an error if something goes wrong. If an error occurs, or the compilation process is interrupted, it can be resumed any -time by typing +make+ again. Type ++**make**++ to start compiling the +time by typing +make+ again. Type +make+ to start compiling the executable application: ---- @@ -330,7 +329,7 @@ $ which bitcoin-cli ((("Bitcoin Core", "running core nodes", id="BCnode03")))((("Bitcoin nodes", "running core nodes", id="BNcore03")))Bitcoin's peer-to-peer -network is composed of network "nodes," run mostly by volunteers and +network is composed of network "nodes," run mostly by individuals and some of the businesses that provide Bitcoin services. Those running Bitcoin nodes have a direct and authoritative view of the Bitcoin blockchain, with a local copy of all the spendable bitcoins @@ -384,25 +383,25 @@ USD computer the size of a pack of cards). Why would you want to run a node? Here are some of the most common reasons: -- If you do not want to rely on any third party to validate the +- You do not want to rely on any third party to validate the transactions you receive. - You do not want to disclose to third parties which transactions belong to your wallet. -- If you are developing bitcoin software and need to rely on a Bitcoin +- You are developing Bitcoin software and need to rely on a Bitcoin node for programmable (API) access to the network and blockchain. -- If you are building applications that must validate transactions - according to bitcoin's consensus rules. Typically, bitcoin software +- You are building applications that must validate transactions + according to Bitcoin's consensus rules. Typically, Bitcoin software companies run several nodes. -- If you want to support bitcoin. Running a node that you use to +- You want to support Bitcoin. Running a node that you use to validate the transactions you receive to your wallet makes the network more robust. If you're reading this book and interested in strong security, superior -privacy, or developing bitcoin software, you should be running your own +privacy, or developing Bitcoin software, you should be running your own node. ==== Configuring the Bitcoin Core Node @@ -487,7 +486,7 @@ this size on high-end hardware to read and write from your disk less often, or reduce the size on low-end hardware to save memory at the expense of more using your disk more frequently. -blocksonly:: Minimize your bandwidth usage you only accepting blocks of +blocksonly:: Minimize your bandwidth usage by only accepting blocks of confirmed transactions from your peers instead of relaying unconfirmed transactions. @@ -583,8 +582,8 @@ it is loading the correct settings and running as you expect. To run Bitcoin Core in the background as a process, start it with the +daemon+ option, as +bitcoind -daemon+. -To monitor the progress and runtime status of your Bitcoin node, use the -command +bitcoin-cli getblockchaininfo+: +To monitor the progress and runtime status of your Bitcoin node, start +it in daemon mode and then use the command +bitcoin-cli getblockchaininfo+: ---- $ bitcoin-cli getblockchaininfo @@ -610,8 +609,10 @@ $ bitcoin-cli getblockchaininfo ---- This shows a node with a blockchain height of 0 blocks and 83999 -headers. The node currently fetches the block headers of the best chain -and afterward continues to download the full blocks. +headers. The node first fetches the block headers from its peers in +order to find the blockchain with the most proof of work and +afterward continues to download the full blocks, validating them as it +goes. Once you are happy with the configuration options you have selected, you should add bitcoin to the startup scripts in your operating system, so @@ -623,13 +624,13 @@ startref="BCnode03")))((("", startref="BNcore03"))) === Bitcoin Core Application Programming Interface (API) -((("Bitcoin Core", "Bitcoin Core API", id="BCapi03")))The Bitcoin Core -client implements a JSON-RPC interface that can also be accessed using +((("Bitcoin Core", "Bitcoin Core API", id="BCapi03")))Bitcoin Core +implements a JSON-RPC interface that can also be accessed using the command-line helper +bitcoin-cli+. The command line allows us to experiment interactively with the capabilities that are also available programmatically via the API. ((("Bitcoin Core", "Bitcoin Core API", "RPC commands")))To start, invoke the +help+ command to see a list of -the available bitcoin RPC commands: +the available Bitcoin Core RPC commands: [[bitcoind_commands]] @@ -686,7 +687,7 @@ return to you. In the next sections we will demonstrate some very useful RPC commands and their expected output. -==== Getting Information on the Bitcoin Core Client Status +==== Getting Information on Bitcoin Core's Status ((("Bitcoin Core", "Bitcoin Core API", "status information")))Bitcoin Core provides status reports on diffent modules through the JSON-RPC @@ -734,25 +735,21 @@ $ bitcoin-cli getnetworkinfo The data is returned in JavaScript Object Notation (JSON), a format that can easily be "consumed" by all programming languages but is also quite human-readable. Among this data we see the version numbers for the -bitcoin software client and Bitcoin protocol. We see +Bitcoin Core software and Bitcoin protocol. We see the current number of connections and various information about the -Bitcoin network and the settings related to this client. +Bitcoin network and the settings related to this node. [TIP] ==== -It will take some time, perhaps more than a day, for the +bitcoind+ -client to "catch up" to the current blockchain height as it downloads -blocks from other Bitcoin clients. You can check its progress using +It will take some time, perhaps more than a day, for +bitcoind+ +to catch up to the current blockchain height as it downloads +blocks from other Bitcoin nodes. You can check its progress using +getblockchaininfo+ to see the number of known blocks. ==== [[exploring_and_decoding_transanctions]] ==== Exploring and Decoding Transactions -((("Bitcoin Core", "Bitcoin Core API", "exploring and decoding -transactions")))((("transactions", "exploring with Bitcoin Core -API")))Commands: +getrawtransaction+, +decoderawtransaction+ - In <>, ((("use cases", "buying coffee", id="alicethree")))Alice made a purchase from Bob's store. Her transaction was recorded on the blockchain. @@ -869,9 +866,6 @@ transmitted from one owner to the next. ==== Exploring Blocks -((("Bitcoin Core", "Bitcoin Core API", "exploring blocks")))((("blocks", -"exploring with Bitcoin Core API")))Commands: +getblock+, +getblockhash+ - ((("blocks", "block height")))((("blocks", "block hash")))Exploring blocks is similar to exploring transactions. However, blocks can be referenced either by the block _height_ or by the block _hash_. First, @@ -1022,7 +1016,7 @@ blockchain. Not a spectacular result, but it demonstrates the basic use of the library as a simplified interface to Bitcoin Core's JSON-RPC API. Next, let's use the +getrawtransaction+ and +decodetransaction+ calls to -retrieve the details of Alice's coffee payment. In <>, +retrieve the details of Alice's payment to Bob. In <>, we retrieve Alice's transaction and list the transaction's outputs. For each output, we show the recipient address and value. As a reminder, Alice's transaction had one output paying Bob and one output for