diff --git a/ch03.asciidoc b/ch03.asciidoc index e4ce1591..17b774b0 100644 --- a/ch03.asciidoc +++ b/ch03.asciidoc @@ -15,7 +15,7 @@ image::images/bitcoin-choose-client.png["bitcoin choose client"] If you download an installable package, such as an EXE, DMG or PPA, you can install it the same way as any application on your operating system. For Windows, run the EXE and follow the step-by-step instructions. For Mac OS, launch the DMG and drag the Bitcoin-QT icon into your Applications folder. For Ubuntu, double-click on the PPA in your File Explorer and it will open the package manager to install the package. Once you have completed installation you should have a new application "Bitcoin-Qt" in your application list. Double-click on the icon to start the bitcoin client. -The first time you run Bitcoin Core it will start downloading the blockchain, a process that may take several days. Leave it running in the background, until it displays "Synchronized" and no longer shows "Out of sync" next to the balance. +The first time you run Bitcoin Core it will start downloading the blockchain, a process that may take several days. Leave it running in the background until it displays "Synchronized" and no longer shows "Out of sync" next to the balance. [TIP] ==== @@ -29,7 +29,7 @@ image::images/bitcoin-qt-firstload.png["bitcoin-qt first run"] ==== Bitcoin Core - Compiling the client from the source code -For developers, there is also the option to download the full source code, either as a ZIP archive or by cloning the authoritative source repository from Github. Go to https://github.com/bitcoin/bitcoin and select "Download ZIP" from the sidebar. Alternatively, use the git command line to create a local copy of the source code on your system. In the example below, we are cloning the source code from a unix-like command-line, in Linux or Mac OS: +For developers, there is also the option to download the full source code as a ZIP archive or by cloning the authoritative source repository from Github. Go to https://github.com/bitcoin/bitcoin and select "Download ZIP" from the sidebar. Alternatively, use the git command line to create a local copy of the source code on your system. In the example below, we are cloning the source code from a unix-like command-line, in Linux or Mac OS: ---- $ git clone https://github.com/bitcoin/bitcoin.git @@ -53,7 +53,7 @@ When the git cloning operation has complete, you will have a complete local copy $ cd bitcoin ---- -By default, the local copy will be synchronized with the most recent code which may be an unstable or "beta" version of bitcoin. Before compiling the code, we want to 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 used by the developers to mark specific releases of the code by version number. First, to find the available tags, we use the +git tag+ command: +By default, the local copy will be synchronized with the most recent code which may be an unstable or "beta" version of bitcoin. Before compiling the code, we want to 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 used by the developers to mark specific releases of the code by version number. First, to find the available tags, we use the +git tag+ command: ---- $ git tag @@ -84,9 +84,9 @@ $ ---- -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, using the space bar to progress to the next page. In this chapter we will build the command-line bitcoin client, also known as +bitcoind+ on Linux. Review the instructions for compiling the bitcoind command-line client on your platform by typing +more doc/build-unix.md+. Alternative instructions for Mac OSX and Windows can be found in the doc directory, as +build-os.md+ or +build-msw.md+ respectively. +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 space bar to progress to the next page. In this chapter we will build the command-line bitcoin client, also known as +bitcoind+ on Linux. Review the instructions for compiling the bitcoind command-line client on your platform by typing +more doc/build-unix.md+. Alternative instructions for Mac OSX and Windows can be found in the doc directory, as +build-os.md+ or +build-msw.md+ respectively. -Carefully review the build pre-requisited which are in the first part of the build documentation. These are libraries that must be present on your system before you can begin to compile bitcoin. If these pre-requisites are missing the build process will fail with an error. If this happens because you missed a pre-requisite, you can install it and then resume the build process from where you left off. Assuming the pre-requisites are installed, we start the build process by generating a set of build scripts using the +autogen.sh+ script. +Carefully review the build pre-requisites which are in the first part of the build documentation. These are libraries that must be present on your system before you can begin to compile bitcoin. If these pre-requisites are missing the build process will fail with an error. If this happens because you missed a pre-requisite, you can install it and then resume the build process from where you left off. Assuming the pre-requisites are installed, we start the build process by generating a set of build scripts using the +autogen.sh+ script. [TIP] ==== @@ -103,7 +103,7 @@ src/Makefile.am: installing `src/build-aux/depcomp' $ ---- -The +autogen.sh+ script creates a set of automatic configuation 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: +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: ---- $ ./configure --help @@ -140,7 +140,7 @@ Report bugs to . $ ---- -The +configure+ script allows you to enable or disable certain features of bitcoind through the use of the +--enable-FEATURE+ and +--disable-FEATURE+ flags, where +FEATURE+ is replaced by the feature name, as listed in the help output above. In this chapter, we will build the bitcoind client with all the default features, so we won't be using these flags, but you should review them to understand what optional features are part of the client. Next, we run the +configure+ script to automatically discover all the necessary libraries and create a customized build script for our system: +The +configure+ script allows you to enable or disable certain features of bitcoind through the use of the +--enable-FEATURE+ and +--disable-FEATURE+ flags, where +FEATURE+ is replaced by the feature name, as listed in the help output above. In this chapter, we will build the bitcoind client with all the default features. We won't be using the configuration flags, but you should review them to understand what optional features are part of the client. Next, we run the +configure+ script to automatically discover all the necessary libraries and create a customized build script for our system: ---- $ ./configure @@ -170,7 +170,7 @@ config.status: executing depfiles commands $ ---- -If all goes well, the +configure+ command will end by creating the customized build scripts that will allow us to compile bitcoind. If there are any missing libraries or errors, the +configure+ command will terminate with an error instead of creating the build scripts as shown above. If an error occurs, it is most likely a missing or incompatible library. Review the build documentation again and make sure you install the missing pre-requisites, then run +configure+ again and see if that fixes the error. Next, we will compile the source code, a process that can take up to an hour to complete. During the compilation process you should see output every few seconds or every few minutes, or an error if something goes wrong. The compilation process can be resumed at any time if interrupted. Type +make+ to start compiling: +If all goes well, the +configure+ command will end by creating the customized build scripts that will allow us to compile bitcoind. If there are any missing libraries or errors, the +configure+ command will terminate with an error instead of creating the build scripts as shown above. If an error occurs, it is most likely a missing or incompatible library. Review the build documentation again and make sure you install the missing pre-requisites. Then run +configure+ again and see if that fixes the error. Next, we will compile the source code, a process that can take up to an hour to complete. During the compilation process you should see output every few seconds or every few minutes, or an error if something goes wrong. The compilation process can be resumed at any time if interrupted. Type +make+ to start compiling: ---- $ make @@ -201,7 +201,7 @@ make[1]: Leaving directory `/home/ubuntu/bitcoin' $ ---- -If all goes well, bitcoind is now compiled. The final step is to install the bitcoind executable into the system path, using the +make+ command: +If all goes well, bitcoind is now compiled. The final step is to install the bitcoind executable into the system path using the +make+ command: ---- $ sudo make install @@ -239,7 +239,7 @@ It is also recommended to set alertnotify so you are notified of problems; for example: alertnotify=echo %s | mail -s "Bitcoin Alert" admin@foo.com ---- -Edit the configuration file in your preferred editor and set the parameters, replacing the password with a strong password as recommended by bitcoind. Do *not* use the password shown below. Create a file inside the +.bitcoin+ directory, so that it is named +.bitcoin/bitcoin.conf+ and enter a username and password: +Edit the configuration file in your preferred editor and set the parameters, replacing the password with a strong password as recommended by bitcoind. Do *not* use the password shown below. Create a file inside the +.bitcoin+ directory so that it is named +.bitcoin/bitcoin.conf+ and enter a username and password: ---- rpcuser=bitcoinrpc @@ -330,7 +330,7 @@ verifymessage "bitcoinaddress" "signature" "message" Commands: -daemon, getinfo -Now, run the bitcoin client. The first time you run it, it will rebuild the bitcoin blockchain. This is a multi-gigabyte file and will take on average 2 days to download in full. You can shorten the blockchain initialization time by downloading a partial copy of the blockchain using bittorrent from +http://sourceforge.net/projects/bitcoin/files/Bitcoin/blockchain/+. +Now, run the bitcoin client. The first time you run it the bitcoin blockchain will be rebuilt. This is a multi-gigabyte file and will take on average 2 days to download in full. You can shorten the blockchain initialization time by downloading a partial copy of the blockchain using bittorrent from +http://sourceforge.net/projects/bitcoin/files/Bitcoin/blockchain/+. Run bitcoind in the background with the option +-daemon+: @@ -397,7 +397,7 @@ wallet encrypted; Bitcoin server stopping, restart to run with encrypted wallet. $ ---- -We can verify the wallet has been encrypted, by running +getinfo+ again. This time you will notice a new entry +unlocked_until+ which is a counter showing how long the wallet decryption password will be stored in memory, keeping the wallet unlocked. At first this will be set to zero, meaning the wallet is locked: +We can verify the wallet has been encrypted by running +getinfo+ again. This time you will notice a new entry +unlocked_until+ which is a counter showing how long the wallet decryption password will be stored in memory, keeping the wallet unlocked. At first this will be set to zero, meaning the wallet is locked: ---- $ bitcoind getinfo @@ -544,14 +544,14 @@ $ bitcoind getbalance [TIP] ==== -If the transaction has not yet confirmed, the balance returned by getbalance will be zero. The configuration option "minconf" determines the minimum number of confirmations that are required before a transaction shows in the balance +If the transaction has not yet confirmed, the balance returned by getbalance will be zero. The configuration option "minconf" determines the minimum number of confirmations that are required before a transaction shows in the balance. ==== ==== Exploring and decoding transactions Commands: gettransaction, getrawtransaction, decoderawtransaction -We'll now explore the incoming transaction that was listed above, using the +gettransaction+. We can retrieve a transaction by its transaction hash, shown at +txid+, above with the +gettransaction+ command: +We'll now explore the incoming transaction that was listed above using the +gettransaction+ command. We can retrieve a transaction by its transaction hash, shown at +txid+, above with the +gettransaction+ command: ---- $ bitcoind gettransaction 9ca8f969bd3ef5ec2a8685660fdbf7a8bd365524c2e1fc66c309acbae2c14ae3 @@ -634,11 +634,11 @@ $ bitcoind decoderawtransaction 0100000001d717...388ac00000000 } ---- -The transaction decode shows all the compoenents of this transaction, including the transaction inputs, and outputs. In this case we see that the transaction that credited our new address with 50 milibits used one input and generated two outputs. The input to this transaction was the output from a previously confirmed transaction (shown as the vin txid starting with +d3c7+ above). The two outputs correspond to the 50 milibit credit and an output with change back to the sender. +The transaction decode shows all the compoenents of this transaction, including the transaction inputs and outputs. In this case we see that the transaction that credited our new address with 50 millibits used one input and generated two outputs. The input to this transaction was the output from a previously confirmed transaction (shown as the vin txid starting with +d3c7+ above). The two outputs correspond to the 50 millibit credit and an output with change back to the sender. -We can further explore the blockchain by examining the previous transaction referenced by its txid in this transaction, using the same commands (eg. +gettransaction+). Jumping from transaction to transaction we can follow a chain of transactions back as the coins are transmitted from owner address to owner address. +We can further explore the blockchain by examining the previous transaction referenced by its txid in this transaction using the same commands (eg. +gettransaction+). Jumping from transaction to transaction we can follow a chain of transactions back as the coins are transmitted from owner address to owner address. -Once the transaction we received has been confirmed, by inclusion in a block, the +gettransaction+ command will return additional information, showing the block hash (identifier) in which the transaction was included: +Once the transaction we received has been confirmed by inclusion in a block, the +gettransaction+ command will return additional information, showing the block hash (identifier) in which the transaction was included: ---- $ bitcoind gettransaction 9ca8f969bd3ef5ec2a8685660fdbf7a8bd365524c2e1fc66c309acbae2c14ae3 @@ -715,7 +715,7 @@ $ bitcoind getblock 000000000000000051d2e759c63a26e247f185ecb7926ed7a6624bc31c2a The block contains 367 transactions and as you see above, the 18th transaction listed (+9ca8f9...+) is the txid of the one crediting 50 millibits to our address. The +height+ entry tells us this is the 286384'th block in the blockchain. -We can also retrieve a block by its block height, using the +getblockhash+ command, which takes the block height as the parameter and returns the block hash for that block: +We can also retrieve a block by its block height using the +getblockhash+ command, which takes the block height as the parameter and returns the block hash for that block: ---- $ bitcoind getblockhash 0 @@ -752,7 +752,7 @@ The +getblock+, +getblockhash+ and +gettransaction+ commands can be used to expl Commands: listunspent, gettxout, createrawtransaction, decoderawtransaction, signrawtransaction, sendrawtransaction -Bitcoin's transactions are based on the concept of spending "outputs", which are the result of previous transactions, creating a transaction chain that transfers ownership from address to address. Our wallet has now received a transaction that assigned one such output to our address. Once this is confirmed, we can now spend that output. +Bitcoin's transactions are based on the concept of spending "outputs", which are the result of previous transactions, to create a transaction chain that transfers ownership from address to address. Our wallet has now received a transaction that assigned one such output to our address. Once this is confirmed, we can now spend that output. First, we use the +listunspent+ command to show all the unspent *confirmed* outputs in our wallet: @@ -771,7 +771,7 @@ $ bitcoind listunspent ] ---- -We see that the transaction +9ca8f9...+ created an output (with vout index 0) assigned to the address +1hvzSo...+ for the amount of 50 millibits, which at this point has received 7 confirmations. Transactions use previously created outputs as their inputs, by referring to them by the previous txid and vout index. We will now create a transaction that will spend the 0'th vout of the txid +9ca8f9...+ as its input and assign it to a new output that sends value to a new address. +We see that the transaction +9ca8f9...+ created an output (with vout index 0) assigned to the address +1hvzSo...+ for the amount of 50 millibits, which at this point has received 7 confirmations. Transactions use previously created outputs as their inputs by referring to them by the previous txid and vout index. We will now create a transaction that will spend the 0'th vout of the txid +9ca8f9...+ as its input and assign it to a new output that sends value to a new address. First, let's look at the specific output in more detail. We use the +gettxout+ to get the details of this unspent output above. Transaction outputs are always referenced by txid and vout and these are the parameters we pass to +gettxout+: @@ -867,11 +867,11 @@ $ bitcoind decoderawtransaction 0100000001e34ac1e2baac09c366fce1c2245536bda8f7db That looks correct! Our new transaction "consumes" the unspent output from our confirmed transaction and then spends it in two outputs, one for 25 millibits to our new address and one for 24.5 millibits as change back to the original address. The difference of 0.5 millibits represents the transaction fee and will be credited to the miner who finds the block that includes our transaction. -As you may notice, the transaction contains an empty +scriptSig+, because we haven't signed it yet. Without a signature, this transaction is meaningless, we haven't yet proven that we *own* the address from which the unpsent output is sourced. By signing, we remove the encumberance on the output and prove that we own this output and can spend it. We use the +signrawtransaction+ command to sign the transaction. It takes the raw transaction hex string as the parameter. +As you may notice, the transaction contains an empty +scriptSig+ because we haven't signed it yet. Without a signature, this transaction is meaningless. We haven't yet proven that we *own* the address from which the unpsent output is sourced. By signing, we remove the encumberance on the output and prove that we own this output and can spend it. We use the +signrawtransaction+ command to sign the transaction. It takes the raw transaction hex string as the parameter. [TIP] ==== -If the wallet is encrypted, you have to unlock it before you sign a transaction, as that operation requires access to the secret keys in your wallet +An encrypted wallet must be unlocked before a transaction is signed because signing requires access to the secret keys in the wallet. ==== ---- @@ -935,7 +935,7 @@ $ bitcoind decoderawtransaction 0100000001e34ac1e2baac09c366fce1c2245536bda8f7db Now, the inputs used in the transaction contain a +scriptSig+, which is a digital signature proving ownership of address +1hvz...+ and removing the encumberance on the output so that it can be spent. The signature makes this transaction verifiable by any node in the bitcoin network. -Now it's time to submit the newly created transaction to the network. We do that with the command +sendrawtransaction+ which takes the raw hex string produced by +signrawtransaction+, the same string we just decoded above: +Now it's time to submit the newly created transaction to the network. We do that with the command +sendrawtransaction+ which takes the raw hex string produced by +signrawtransaction+. This is the same string we just decoded above: ---- $ bitcoind sendrawtransaction 0100000001e34ac1e2baac09c366fce1c2245536bda8f7db0f6685862aecf53ebd69f9a89c000000006a47304402203e8a16522da80cef66bacfbc0c800c6d52c4a26d1d86a54e0a1b76d661f020c9022010397f00149f2a8fb2bc5bca52f2d7a7f87e3897a273ef54b277e4af52051a06012103c9700559f690c4a9182faa8bed88ad8a0c563777ac1d3f00fd44ea6c71dc5127ffffffff02a0252600000000001976a914d90d36e98f62968d2bc9bbd68107564a156a9bcf88ac50622500000000001976a91407bdb518fa2e6089fd810235cf1100c9c13d1fd288ac00000000 @@ -1124,7 +1124,7 @@ SpesmiloXchange home page: ===== Generating and manipulating keys with sxBitcoin Core -Generate a new private key, using the operating system's random number generator, with the +newkey+ command. We save the standard output into the file +private_key+: +Generate a new private key with the operating system's random number generator by using the +newkey+ command. We save the standard output into the file +private_key+: ---- $ sx newkey > private_key @@ -1132,7 +1132,7 @@ $ cat private_key 5Jgx3UAaXw8AcCQCi1j7uaTaqpz2fqNR9K3r4apxdYn6rTzR1PL ---- -Now, generate the public key from that private key, using the +pubkey+ command. Pass the +private_key+ file into the standard input and save the standard output of the command into a new file +public_key+: +Now, generate the public key from that private key using the +pubkey+ command. Pass the +private_key+ file into the standard input and save the standard output of the command into a new file +public_key+: ---- $ sx pubkey < private_key > public_key @@ -1140,7 +1140,7 @@ $ cat public_key 02fca46a6006a62dfdd2dbb2149359d0d97a04f430f12a7626dd409256c12be500 ---- -We can re-format the public_key as an address, using the +addr+ command. We pass the +public_key+ into standard input: +We can re-format the public_key as an address using the +addr+ command. We pass the +public_key+ into standard input: ---- $ sx addr < public_key 17re1S4Q8ZHyCP8Kw7xQad1Lr6XUzWUnkG @@ -1158,7 +1158,8 @@ $ cat seed eb68ee9f3df6bd4441a9feadec179ff1 ---- -The seed value can also be exported as a word mnemonic that is human readable and easier to store and type than a hexadecimal string, using the +mnemonic+ command: +The seed value can also be exported as a word mnemonic that is human readable and easier to store and type than a hexadecimal string + using the +mnemonic+ command: ---- $ sx mnemonic < seed > words @@ -1166,7 +1167,7 @@ $ cat words adore repeat vision worst especially veil inch woman cast recall dwell appreciate ---- -The mnemonic words can be used to reproduce the seed, using the +mnemonic+ command again: +The mnemonic words can be used to reproduce the seed using the +mnemonic+ command again: ---- $ sx mnemonic < words