diff --git a/ch03.asciidoc b/ch03.asciidoc index 1b3a7c7f..beeeb569 100644 --- a/ch03.asciidoc +++ b/ch03.asciidoc @@ -1,227 +1,207 @@ [[ch03_bitcoin_client]] -== The Bitcoin Client +== Bitcoin Development Environment -=== Bitcoin Core: The Reference Implementation - -((("bitcoin client", id="ix_ch03-asciidoc0", range="startofrange")))((("bitcoin client","Bitcoin Core", id="ix_ch03-asciidoc1", range="startofrange")))((("Bitcoin Core client", id="ix_ch03-asciidoc2", range="startofrange")))((("Satoshi client", see="Bitcoin Core client")))You can download the reference client _Bitcoin Core_, also known as the "Satoshi client," from bitcoin.org. The reference client implements all aspects of the bitcoin system, including wallets, a transaction verification engine with a full copy of the entire transaction ledger (blockchain), and a full network node in the peer-to-peer bitcoin network. +If you're a developer, you will want to setup a development environment with all the tools, libraries and support software for writing bitcoin applications. If you're not a developer, you might want to skip this chapter entirely. -On((("bitcoin.org","Bitcoin Core, downloading"))) http://bitcoin.org/en/choose-your-wallet[Bitcoin's Choose Your Wallet page], select Bitcoin Core to download the reference client. Depending on your operating system, you will download an executable installer. For Windows, this is either a ZIP archive or an .exe executable. For Mac OS it is a .dmg disk image. Linux versions include a PPA package for Ubuntu or a tar.gz archive. The bitcoin.org page that lists recommended bitcoin clients is shown in <>. +=== Bitcoin Core: The Reference Implementation -[[bitcoin-choose-client]] -.Choosing a bitcoin client at bitcoin.org -image::images/msbt_0301.png["bitcoin choose client"] +Bitcoin is an _open source_ project and the source code is available under an open (MIT) license, free to download and use for any purpose. Open source means more than simply free to use. It also means that bitcoin is developed by an open community of volunteers. At first, that community consisted of only Satoshi Nakamoto. By 2016, bitcoin's source code has more than 340 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! -==== Running Bitcoin Core for the First Time +((("bitcoin client", id="ix_ch03-asciidoc0", range="startofrange")))((("bitcoin client","Bitcoin Core", id="ix_ch03-asciidoc1", range="startofrange")))((("Bitcoin Core client", id="ix_ch03-asciidoc2", range="startofrange")))((("Satoshi client", see="Bitcoin Core client"))) +When bitcoin was created by Satoshi Nakamoto, the software was actually completed before the white paper <>. Satoshi wanted to make sure it worked before writing about it. That first implementation, then simply known as "Bitcoin" or "Satoshi client", has been heavily modified and improved. It has evolved into what is known as _Bitcoin Core_, to differentiate it from other compatible implementations. Bitcoin Core is the _reference implementation_ of the bitcoin system, meaning that it is the authoritative reference on how each part of the technology should be implemented. Bitcoin Core implements all aspects of bitcoin, including wallets, a transaction and block validation engine, and a full network node in the peer-to-peer bitcoin network. -((("Bitcoin Core client","running")))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 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 called Bitcoin-Qt in your application list. Double-click the icon to start the bitcoin client. +[WARNING] +==== +Even though Bitcoin Core includes a reference implementation of a wallet, this is not intended to be used as a production wallet for users or for applications. Application developers are advised to build wallets using modern standards such as BIP39 and BIP32 (see <> and <>). +==== -The first time you run Bitcoin Core it will start downloading the blockchain, a process that might take several days (see <>). Leave it running in the background until it displays "Synchronized" and no longer shows "out of sync" next to the balance. +[[compiling_core]] +=== Compiling Bitcoin Core from the Source Code -[[bitcoin-qt-firstload]] -.Bitcoin Core screen during the blockchain initialization -image::images/msbt_0302.png["bitcoin-qt first run"] +((("Bitcoin Core client","compiling from source code", id="ix_ch03-asciidoc3", range="startofrange")))((("bitcoind client", see="Bitcoin Core client")))Bitcoin Core's source code can be downloaded as a ZIP archive or by cloning the authoritative source repository from GitHub. ((("Bitcoin Core client","source code, downloading")))((("GitHub, downloading Bitcoin Core from"))) On the https://github.com/bitcoin/bitcoin[GitHub bitcoin page], select Download ZIP from the sidebar. Alternatively, use the git command line to create a local copy of the source code on your system. [TIP] ==== -((("Bitcoin Core client","disk space requirement for")))((("blockchains","synchronizing for Bitcoin Core")))((("disk space requirement for Bitcoin Core")))Bitcoin Core keeps a full copy of the transaction ledger (blockchain), with every transaction that has ever occurred on the bitcoin network since its inception in 2009. This dataset is several gigabytes in size (approximately 16 GB in late 2013) and is downloaded incrementally over several days. The client will not be able to process transactions or update account balances until the full blockchain dataset is downloaded. During that time, the client will display "out of sync" next to the account balances and show "Synchronizing" in the footer. Make sure you have enough disk space, bandwidth, and time to complete the initial synchronization. +In many of the examples in this chapter we will be using the operating system's command-line interface (also known as a "shell"), accessed via a "terminal" application. The shell will display a prompt; you type a command; and the shell responds with some text and a new prompt for your next command. The prompt may look different on your system, but in the examples below it is denoted by a +$+ symbol. In the examples when you see text after a +$+ symbol, don't type the +$+ symbol but type the command immediately following it, then press enter to execute the command. In the examples, the lines below each command are the operating system's responses to that command. When you see the next +$+ prefix, you'll know it's a new command and you should repeat the process. ==== - - - -==== Compiling Bitcoin Core from the Source Code - -((("Bitcoin Core client","compiling from source code", id="ix_ch03-asciidoc3", range="startofrange")))((("bitcoind client", see="Bitcoin Core client")))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. ((("Bitcoin Core client","source code, downloading")))((("GitHub, downloading Bitcoin Core from"))) On the https://github.com/bitcoin/bitcoin[GitHub bitcoin page], 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 following example, we are cloning the source code from a Unix-like command line, in Linux or Mac OS: +In this example, we are using the +git+ command to create a local copy ("clone") of the source code. ---- $ git clone https://github.com/bitcoin/bitcoin.git Cloning into 'bitcoin'... -remote: Counting objects: 31864, done. -remote: Compressing objects: 100% (12007/12007), done. -remote: Total 31864 (delta 24480), reused 26530 (delta 19621) -Receiving objects: 100% (31864/31864), 18.47 MiB | 119 KiB/s, done. -Resolving deltas: 100% (24480/24480), done. +remote: Counting objects: 66193, done. +remote: Total 66193 (delta 0), reused 0 (delta 0), pack-reused 66193 +Receiving objects: 100% (66193/66193), 63.39 MiB | 574.00 KiB/s, done. +Resolving deltas: 100% (48395/48395), done. +Checking connectivity... done. $ ---- [TIP] ==== -The instructions and resulting output might vary from version to version. Follow the documentation that comes with the code even if it differs from the instructions you see here, and don't be surprised if the output displayed on your screen is slightly different from the examples here. +Git is the most widely used distributed version control system, an essential part of any software developer's toolkit. You may need to install the +git+ command, or a graphical user interface for git, on your operating system if you do not 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: - ---- $ cd bitcoin ---- - + +==== Selecting a Bitcoin Core Release By default, the local copy will be synchronized with the 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 tags"))) 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 v0.1.5 v0.1.6test1 -v0.2.0 -v0.2.10 -v0.2.11 -v0.2.12 +v0.10.0 +... +v0.11.2 +v0.11.2rc1 +v0.12.0rc1 +v0.12.0rc2 +... +---- -[... many more tags ...] +The list of tags shows all the released versions of bitcoin. By convention,((("release candidates"))) _release candidates_, which are intended for testing, have the suffix "rc". Stable releases that can be run on production systems have no suffix. From the preceding list, select the highest version release, which at this writing was v0.11.2. To synchronize the local code with this version, use the +git checkout+ command: -v0.8.4rc2 -v0.8.5 -v0.8.6 -v0.8.6rc1 -v0.9.0rc1 +---- +$ git checkout v0.11.2 +HEAD is now at 7e27892... Merge pull request #6975 ---- -The list of tags shows all the released versions of bitcoin. By convention,((("release candidates"))) _release candidates_, which are intended for testing, have the suffix "rc". Stable releases that can be run on production systems have no suffix. From the preceding list, select the highest version release, which at this writing was v0.9.0rc1. To synchronize the local code with this version, use the +git checkout+ command: +You can confirm you have the desired version "checked out" by issuing the +git status+ command: ---- -$ git checkout v0.9.0rc1 -Note: checking out 'v0.9.0rc1'. - -HEAD is now at 15ec451... Merge pull request #3605 -$ +$ git status +HEAD detached at v0.11.2 +nothing to commit, working directory clean ---- +==== Configuring the Bitcoin Core Build -((("Bitcoin Core client","documentation")))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 OS X and Windows can be found in the _doc_ directory, as _build-osx.md_ or _build-msw.md_, respectively. +((("Bitcoin Core client","documentation")))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 OS X and Windows can be found in the _doc_ directory, as _build-osx.md_ or _build-msw.md_, respectively. Carefully review the build prerequisites, 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 prerequisites are missing, the build process will fail with an error. If this happens because you missed a prerequisite, you can install it and then resume the build process from where you left off. Assuming the prerequisites are installed, you start the build process by generating a set of build scripts using the _autogen.sh_ script. -[TIP] +[NOTE] ==== The Bitcoin Core build process was changed to use the autogen/configure/make system starting with version 0.9. Older versions use a simple Makefile and work slightly differently from the following example. Follow the instructions for the version you want to compile. The autogen/configure/make introduced in 0.9 is likely to be the build system used for all future versions of the code and is the system demonstrated in the following examples. ==== ---- -$ ./autogen.sh -configure.ac:12: installing `src/build-aux/config.guess' -configure.ac:12: installing `src/build-aux/config.sub' -configure.ac:37: installing `src/build-aux/install-sh' -configure.ac:37: installing `src/build-aux/missing' -src/Makefile.am: installing `src/build-aux/depcomp' -$ +$ ./autogen.sh +... +glibtoolize: copying file 'build-aux/m4/libtool.m4' +glibtoolize: copying file 'build-aux/m4/ltoptions.m4' +glibtoolize: copying file 'build-aux/m4/ltsugar.m4' +glibtoolize: copying file 'build-aux/m4/ltversion.m4' +... +configure.ac:10: installing 'build-aux/compile' +configure.ac:5: installing 'build-aux/config.guess' +configure.ac:5: installing 'build-aux/config.sub' +configure.ac:9: installing 'build-aux/install-sh' +configure.ac:9: installing 'build-aux/missing' +Makefile.am: installing 'build-aux/depcomp' +... ---- ((("autogen.sh script")))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"))) +configure+ script that offers a number of different options to customize the build process. Type +./configure --help+ to see the various options: ---- $ ./configure --help - -`configure' configures Bitcoin Core 0.9.0 to adapt to many kinds of systems. +`configure' configures Bitcoin Core 0.11.2 to adapt to many kinds of systems. Usage: ./configure [OPTION]... [VAR=VALUE]... -To assign environment variables (e.g., CC, CFLAGS...), specify them as -VAR=VALUE. See below for descriptions of some of the useful variables. - -Defaults for the options are specified in brackets. - -Configuration: - -h, --help display this help and exit - --help=short display options specific to this package - --help=recursive display the short help of all the included packages - -V, --version display version information and exit - -[... many more options and variables are displayed below ...] - +... Optional Features: --disable-option-checking ignore unrecognized --enable/--with options --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) --enable-FEATURE[=ARG] include FEATURE [ARG=yes] -[... more options ...] + --enable-wallet enable wallet (default is yes) -Use these variables to override the choices made by `configure' or to help -it to find libraries and programs with nonstandard names/locations. + --with-gui[=no|qt4|qt5|auto] +... +---- -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. 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. If you are in an academic setting, computer lab restrictions may require you to install applications in your home directory (e.g. using --prefix=$HOME). -$ ----- +[TIP] +==== +Here are some useful options that override the default behavior of the configure script: + +--prefix=$HOME:: This overrides the default installation location (which is +/usr/local/+) for the resulting executable. Use $HOME to put everything in your home directory, or a different path. + +--disable-wallet:: This is used to disable the reference wallet implementation. + +--with-incompatible-bdb:: If you are building a wallet, allow the use of an incompatible version of the Berkeley DB library. -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. 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, run the +configure+ script to automatically discover all the necessary libraries and create a customized build script for your system: +--with-gui=no:: Don't build the graphical user interface, which requires the Qt library. This builds server and command-line bitcoin only. +==== + +Next, run the +configure+ script to automatically discover all the necessary libraries and create a customized build script for your system: ---- -$ ./configure +$ ./configure checking build system type... x86_64-unknown-linux-gnu checking host system type... x86_64-unknown-linux-gnu checking for a BSD-compatible install... /usr/bin/install -c checking whether build environment is sane... yes checking for a thread-safe mkdir -p... /bin/mkdir -p -checking for gawk... no -checking for mawk... mawk +checking for gawk... gawk checking whether make sets $(MAKE)... yes - -[... many more system features are tested ...] - -configure: creating ./config.status -config.status: creating Makefile -config.status: creating src/Makefile -config.status: creating src/test/Makefile -config.status: creating src/qt/Makefile -config.status: creating src/qt/test/Makefile -config.status: creating share/setup.nsi -config.status: creating share/qt/Info.plist -config.status: creating qa/pull-tester/run-bitcoind-for-test.sh -config.status: creating qa/pull-tester/build-tests.sh -config.status: creating src/bitcoin-config.h -config.status: executing depfiles commands +... +[many pages of configuration tests follow] +... $ ---- -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. If an error occurs, it is most likely because of a missing or incompatible library. Review the build documentation again and make sure you install the missing prerequisites. Then run +configure+ again and see if that fixes the error. Next, you 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. If an error occurs, it is most likely because of a missing or incompatible library. Review the build documentation again and make sure you install the missing prerequisites. Then run +configure+ again and see if that fixes the error. + +==== Building the Bitcoin Core Executables + +Next, you will compile the source code, a process that can take up to an hour to 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 executable application: ---- $ make Making all in src -make[1]: Entering directory `/home/ubuntu/bitcoin/src' -make all-recursive -make[2]: Entering directory `/home/ubuntu/bitcoin/src' -Making all in . -make[3]: Entering directory `/home/ubuntu/bitcoin/src' - CXX addrman.o - CXX alert.o - CXX rpcserver.o - CXX bloom.o - CXX chainparams.o + CXX crypto/libbitcoinconsensus_la-hmac_sha512.lo + CXX crypto/libbitcoinconsensus_la-ripemd160.lo + CXX crypto/libbitcoinconsensus_la-sha1.lo + CXX crypto/libbitcoinconsensus_la-sha256.lo + CXX crypto/libbitcoinconsensus_la-sha512.lo + CXX libbitcoinconsensus_la-hash.lo + CXX primitives/libbitcoinconsensus_la-transaction.lo + CXX libbitcoinconsensus_la-pubkey.lo + CXX script/libbitcoinconsensus_la-bitcoinconsensus.lo + CXX script/libbitcoinconsensus_la-interpreter.lo [... many more compilation messages follow ...] - CXX test_bitcoin-wallet_tests.o - CXX test_bitcoin-rpc_wallet_tests.o - CXXLD test_bitcoin -make[4]: Leaving directory `/home/ubuntu/bitcoin/src/test' -make[3]: Leaving directory `/home/ubuntu/bitcoin/src/test' -make[2]: Leaving directory `/home/ubuntu/bitcoin/src' -make[1]: Leaving directory `/home/ubuntu/bitcoin/src' -make[1]: Entering directory `/home/ubuntu/bitcoin' -make[1]: Nothing to be done for `all-am'. -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, Bitcoin Core is now compiled. The final step is to install the various executables on your system using the +sudo make install+ command. You may be prompted for your user password, because this step requires administrative privileges: ---- $ sudo make install +Password: Making install in src -Making install in . - /bin/mkdir -p '/usr/local/bin' - /usr/bin/install -c bitcoind bitcoin-cli '/usr/local/bin' -Making install in test -make install-am - /bin/mkdir -p '/usr/local/bin' - /usr/bin/install -c test_bitcoin '/usr/local/bin' + ../build-aux/install-sh -c -d '/usr/local/lib' +libtool: install: /usr/bin/install -c bitcoind /usr/local/bin/bitcoind +libtool: install: /usr/bin/install -c bitcoin-cli /usr/local/bin/bitcoin-cli +libtool: install: /usr/bin/install -c bitcoin-tx /usr/local/bin/bitcoin-tx +... $ ---- -You can confirm that bitcoin is correctly installed by asking the system for the path of the two executables, as follows: +The default installation of bitcoind puts it in _/usr/local/bin_. You can confirm that Bitcoin Core is correctly installed by asking the system for the path of the executables, as follows: -[source,bash] ---- $ which bitcoind /usr/local/bin/bitcoind @@ -230,7 +210,36 @@ $ which bitcoin-cli /usr/local/bin/bitcoin-cli ---- -The default installation of bitcoind puts it in _/usr/local/bin_. When you first run bitcoind, it will remind you to create a configuration file with a strong password for the JSON-RPC interface. Run bitcoind by typing +bitcoind+ into the terminal: +=== Running a Bitcoin Core Node + +Bitcoin's peer-to-peer network is composed of network "nodes", run mostly by volunteers and some of the businesses that build bitcoin applications. Those running bitcoin nodes have a direct and authoritative view of the bitcoin blockchain, with a local copy of all the transactions, independently validated by their own system. By running a node, you don't have to rely on any third party to validate a transaction. Moreover, by running a bitcoin node you contribute to the bitcoin network by making it more robust. + +Running a node, however, requires a permanently connected system with enough resources to process all bitcoin transactions. Depending on whether you choose to index all transactions and keep a full copy of the blockchain, you may also need a lot of disk space and RAM. In early 2016, a full-index node needs 2GB of RAM and 80GB of disk space. Bitcoin nodes also transmit and receive bitcoin transactions and blocks, consuming Internet bandwidth. If your Internet connection is limited, has a low data cap, or is metered (charged by the gigabit), you should probably not run a bitcoin node on it, or run it in a way that constrains its bandwidth (see <>). + +[TIP] +==== +((("Bitcoin Core","runtime requirement for")))((("runtime requirements for Bitcoin Core")))Bitcoin Core keeps a full copy of the blockchain by default, with every transaction that has ever occurred on the bitcoin network since its inception in 2009. This dataset is several gigabytes in size and is downloaded incrementally over several hours or days, depending on the speed of your CPU and Internet connection. Bitcoin Core will not be able to process transactions or update account balances until the full blockchain dataset is downloaded. Make sure you have enough disk space, bandwidth, and time to complete the initial synchronization. You can configure Bitcoin Core to reduce the size of the blockchain by discarding old blocks (see <>) but it will still download the entire dataset before discarding data. +==== + +Despite these resource requirements, thousands of volunteers run bitcoin nodes. Some are running on systems as simple as a Raspberry Pi (a $35 USD computer the size of a pack of cards). Many volunteers also run bitcoin nodes on rented servers, usually some variant of Linux. A _Virtual Private Server_ (VPS) or _Cloud Computing_ server instance can be used to run a bitcoin node. Such servers can be rented for $12 to $18 USD per month from a variety of providers. + +Why would you want to run a node? Here are some of the most common reasons for running a node: + +* If 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 companies run several nodes. + +* If you want to support bitcoin. Running a node makes the network more robust and able to serve more wallets, more users and more transactions. + +* If you do not want to rely on any third party for processing your own transactions or validating transactions. + +If you're reading this book and interested in developing bitcoin software, you should be running your own node. + +==== Running Bitcoin Core for the First Time + +When you first run bitcoind, it will remind you to create a configuration file with a strong password for the JSON-RPC interface. This password controls access to the Application Programming Interface (API) offered by Bitcoin Core. + +Run bitcoind by typing +bitcoind+ into the terminal: ---- $ bitcoind @@ -246,363 +255,249 @@ 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 here. Create a file inside the _.bitcoin_ directory so that it is named _.bitcoin/bitcoin.conf_ and enter a username and password: +==== Configuring the Bitcoin Core Node + +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 in the book. Create a file inside the +.bitcoin+ directory (under your user's home directory) so that it is named +.bitcoin/bitcoin.conf+ and provide a username and password: [source,ini] ---- rpcuser=bitcoinrpc -rpcpassword=2XA4DuKNCbtZXsBQRRNDEwEY2nM6M4H9Tx5dFjoAVVbK +rpcpassword=CHANGE_THIS ---- -While you're editing this configuration file, you might want to set a few other options, such as +txindex+ (see <>). For a full listing of the available options, type +bitcoind --help+. - -Now, run the Bitcoin Core client. The first time you run it, it will rebuild the bitcoin blockchain by downloading all the blocks. This is a multigigabyte file and will take an average of two days to download in full. You can shorten the((("blockchains","downloading with bittorrent clients"))) blockchain initialization time by downloading a partial copy of the blockchain using a BitTorrent client from http://bit.ly/1qkLNyh[SourceForge]. +While you're editing this configuration file, you might want to set a few other options. In addition to the +rpcuser+ and +rpcpassword+ options, Bitcoin Core offers dozens of configuration options that modify the behavior of the network node, the storage of the blockchain and many other aspects of its operation. -Run bitcoind in the background with the option +-daemon+:(((range="endofrange", startref="ix_ch03-asciidoc3"))) +To see a listing of these options, run +bitcoind --help+: ---- -$ bitcoind -daemon + bitcoind --help +Bitcoin Core Daemon version v0.11.2 -Bitcoin version v0.9.0rc1-beta (2014-01-31 09:30:15 +0100) -Using OpenSSL version OpenSSL 1.0.1c 10 May 2012 -Default data directory /home/bitcoin/.bitcoin -Using data directory /bitcoin/ -Using at most 4 connections (1024 file descriptors available) -init message: Verifying wallet... -dbenv.open LogDir=/bitcoin/database ErrorFile=/bitcoin/db.log -Bound to [::]:8333 -Bound to 0.0.0.0:8333 -init message: Loading block index... -Opening LevelDB in /bitcoin/blocks/index -Opened LevelDB successfully -Opening LevelDB in /bitcoin/chainstate -Opened LevelDB successfully - -[... more startup messages ...] +Usage: + bitcoind [options] Start Bitcoin Core Daemon ----- +Options: -=== Using Bitcoin Core's JSON-RPC API from the Command Line + -? + This help message -((("Bitcoin Core client","JSON-RPC API for", id="ix_ch03-asciidoc5", range="startofrange")))((("Bitcoin Core client","using from command line", id="ix_ch03-asciidoc6", range="startofrange")))((("bitcoin-cli command line helper", id="ix_ch03-asciidoc7", range="startofrange")))The Bitcoin Core client 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. To start, invoke the +help+ command to see a list of the available bitcoin RPC commands: + -alerts + Receive and display P2P network alerts (default: 1) -[[bitcoind_commands]] + -alertnotify= + Execute command when a relevant alert is received or we see a really + long fork (%s in cmd is replaced by message) +... +[many more options] +... + -rpcsslciphers= + Acceptable ciphers (default: + TLSv1.2+HIGH:TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!3DES:@STRENGTH) ---- -$ bitcoin-cli help -addmultisigaddress nrequired ["key",...] ( "account" ) -addnode "node" "add|remove|onetry" -backupwallet "destination" -createmultisig nrequired ["key",...] -createrawtransaction [{"txid":"id","vout":n},...] {"address":amount,...} -decoderawtransaction "hexstring" -decodescript "hex" -dumpprivkey "bitcoinaddress" -dumpwallet "filename" -getaccount "bitcoinaddress" -getaccountaddress "account" -getaddednodeinfo dns ( "node" ) -getaddressesbyaccount "account" -getbalance ( "account" minconf ) -getbestblockhash -getblock "hash" ( verbose ) -getblockchaininfo -getblockcount -getblockhash index -getblocktemplate ( "jsonrequestobject" ) -getconnectioncount -getdifficulty -getgenerate -gethashespersec -getinfo -getmininginfo -getnettotals -getnetworkhashps ( blocks height ) -getnetworkinfo -getnewaddress ( "account" ) -getpeerinfo -getrawchangeaddress -getrawmempool ( verbose ) -getrawtransaction "txid" ( verbose ) -getreceivedbyaccount "account" ( minconf ) -getreceivedbyaddress "bitcoinaddress" ( minconf ) -gettransaction "txid" -gettxout "txid" n ( includemempool ) -gettxoutsetinfo -getunconfirmedbalance -getwalletinfo -getwork ( "data" ) -help ( "command" ) -importprivkey "bitcoinprivkey" ( "label" rescan ) -importwallet "filename" -keypoolrefill ( newsize ) -listaccounts ( minconf ) -listaddressgroupings -listlockunspent -listreceivedbyaccount ( minconf includeempty ) -listreceivedbyaddress ( minconf includeempty ) -listsinceblock ( "blockhash" target-confirmations ) -listtransactions ( "account" count from ) -listunspent ( minconf maxconf ["address",...] ) -lockunspent unlock [{"txid":"txid","vout":n},...] -move "fromaccount" "toaccount" amount ( minconf "comment" ) -ping -sendfrom "fromaccount" "tobitcoinaddress" amount ( minconf "comment" "comment-to" ) -sendmany "fromaccount" {"address":amount,...} ( minconf "comment" ) -sendrawtransaction "hexstring" ( allowhighfees ) -sendtoaddress "bitcoinaddress" amount ( "comment" "comment-to" ) -setaccount "bitcoinaddress" "account" -setgenerate generate ( genproclimit ) -settxfee amount -signmessage "bitcoinaddress" "message" -signrawtransaction "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] ["privatekey1",...] sighashtype ) -stop -submitblock "hexdata" ( "jsonparametersobject" ) -validateaddress "bitcoinaddress" -verifychain ( checklevel numblocks ) -verifymessage "bitcoinaddress" "signature" "message" -walletlock -walletpassphrase "passphrase" timeout -walletpassphrasechange "oldpassphrase" "newpassphrase" ----- - + +Here are some of the most important options that can set in the configuration file, or as command-line parameters to bitcoind: -==== Getting Information on the Bitcoin Core Client Status +alertnotify:: Run a specified command or script to send emergency alerts to the owner of this node, usually by sending email. -Commands: +getinfo+ +conf:: An alternative location for the configuration file. This only makes sense as a command-line parameter to bitcoind, as it can't be inside the configuration file it refers to. -((("Bitcoin Core client","client status, getting")))((("bitcoin-cli command line helper","getinfo command")))((("client status, getting")))((("getinfo command (bitcoin-cli)")))Bitcoin's +getinfo+ RPC command displays basic information about the status of the bitcoin network node, the wallet, and the blockchain database. Use +bitcoin-cli+ to run it: +datadir:: Select the directory and filesystem to put all the blockchain data. By default this is the +.bitcoin+ subdirectory of your home directory. Make sure this filesystem has several gigabytes free space. -[source,bash] ----- -$ bitcoin-cli getinfo ----- -[source,json] ----- -{ - "version" : 90000, - "protocolversion" : 70002, - "walletversion" : 60000, - "balance" : 0.00000000, - "blocks" : 286216, - "timeoffset" : -72, - "connections" : 4, - "proxy" : "", - "difficulty" : 2621404453.06461525, - "testnet" : false, - "keypoololdest" : 1374553827, - "keypoolsize" : 101, - "paytxfee" : 0.00000000, - "errors" : "" -} ----- +prune:: Reduce the disk space requirements to this many megabytes, by deleting old blocks. Use this on a resource-constrained node that can't fit the full blockchain. -The data is returned in((("JavaScript Object Notation (JSON)"))) 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 (90000), protocol (70002), and wallet (60000). We see the current balance contained in the wallet, which is zero. We see the current block height, showing us how many blocks are known to this client (286216). We also see various statistics about the bitcoin network and the settings related to this client. We will explore these settings in more detail in the rest of this chapter. +txindex:: Maintain an index of all transactions. This means a complete copy of the blockchain and allows you to programmatically retrieve any transaction by ID. -[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 +getinfo+ to see the number of known blocks. -==== +maxconnections:: Set the maximum number of nodes from which to accept connections. Reducing this from the default will reduce your bandwidth consumption. Use if you have a data cap or pay by the gigabyte. -==== Wallet Setup and Encryption +minrelaytxfee:: Increase the minimum acceptable transaction fee. Use this on memory-constrained nodes to reduce the size of the in-memory transaction pool. -Commands: +encryptwallet+, +walletpassphrase+ +Here's how you might combine the above options: -((("bitcoin-cli command line helper","wallet setup with")))((("bitcoin-cli command line helper","walletpassphrase command")))((("encryptwallet command (bitcoin-cli)")))((("walletpassphrase command (bitcoin-cli)")))((("wallets","setup from command line")))Before you proceed with creating keys and other commands, you should first encrypt the wallet with a password. For this example, you will use the +encryptwallet+ command with the password "foo". Obviously, replace "foo" with a strong and complex password! +A fully-indexed node, running as an API back-end for a bitcoin application: +[[full_index_node]] +.Sample configuration of a full-index node +==== ---- -$ bitcoin-cli encryptwallet foo -wallet encrypted; Bitcoin server stopping, restart to run with encrypted wallet. The keypool has been flushed, you need to make a new backup. -$ +alertnotify=myemailscript.sh "Alert: %s" +datadir=/lotsofspace/bitcoin +txindex=1 +rpcuser=bitcoinrpc +rpcpassword=CHANGE_THIS ---- +==== -You can verify the wallet has been encrypted by running +getinfo+ again. This time you will notice a new entry called +unlocked_until+. This 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: +A resource-constrained node running on a smaller server: -[source,bash] ----- -$ bitcoin-cli getinfo +[[constrained_resources]] +.Sample configuration of a resource-constrained system +==== ---- -[source,json] +alertnotify=myemailscript.sh "Alert: %s" +maxconnections=15 +prune=5000 +minrelaytxfee=0.0001 +rpcuser=bitcoinrpc +rpcpassword=CHANGE_THIS ---- -{ - "version" : 90000, +==== -#[... other information...] +Now, run the Bitcoin Core client. The first time you run it, it will reconstruct a complete local copy of the bitcoin blockchain by downloading all the blocks. + +To test your configuration, run Bitcoin Core with the option +printtoconsole+ to run in the foreground with output to the console:(((range="endofrange", startref="ix_ch03-asciidoc3"))) - "unlocked_until" : 0, - "errors" : "" -} -$ ---- +$ bitcoind -printtoconsole -To unlock the wallet, issue the +walletpassphrase+ command, which takes two parameters—the password and a number of seconds until the wallet is locked again automatically (a time counter): +Bitcoin version v0.11.20.0 +Using OpenSSL version OpenSSL 1.0.2e 3 Dec 2015 +Startup time: 2015-01-02 19:56:17 +Using data directory /tmp/bitcoin +Using config file /tmp/bitcoin/bitcoin.conf +Using at most 125 connections (275 file descriptors available) +Using 2 threads for script verification +scheduler thread start +HTTP: creating work queue of depth 16 +No rpcpassword set - using random cookie authentication +Generated RPC authentication cookie /tmp/bitcoin/.cookie +HTTP: starting 4 worker threads +Bound to [::]:8333 +Bound to 0.0.0.0:8333 +Cache configuration: +* Using 2.0MiB for block index database +* Using 32.5MiB for chain state database +* Using 65.5MiB for in-memory UTXO set +init message: Loading block index... +Opening LevelDB in /tmp/bitcoin/blocks/index +Opened LevelDB successfully ----- -$ bitcoin-cli walletpassphrase foo 360 -$ +[... more startup messages ...] ---- -You can confirm the wallet is unlocked and see the timeout by running +getinfo+ again: +You can hit +CTRL+C+ to interrupt the process once you are satisfied that it is loading the correct settings and running as you expect it. -[source,bash] +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 getinfo+: ---- $ bitcoin-cli getinfo ---- [source,json] ---- { - "version" : 90000, - -#[... other information ...] - - "unlocked_until" : 1392580909, + "version" : 110200, + "protocolversion" : 70002, + "blocks" : 396328, + "timeoffset" : 0, + "connections" : 15, + "proxy" : "", + "difficulty" : 120033340651.23696899, + "testnet" : false, + "relayfee" : 0.00010000, "errors" : "" } ---- -==== Wallet Backup, Plain-text Dump, and Restore - -Commands: +backupwallet+, +importwallet+, +dumpwallet+ - -((("backups","of wallets")))((("backupwallet command (bitcoin-cli)")))((("bitcoin-cli command line helper","backupwallet command")))((("bitcoin-cli command line helper","dumpwallet command")))((("bitcoin-cli command line helper","importwallet command")))((("dumpwallet command (bitcoin-cli)")))((("importwallet command (bitcoin-cli)")))((("wallets","backing up")))((("wallets","dumping into plain text")))((("wallets","restoring")))Next, we will practice creating a wallet backup file and then restoring the wallet from the backup file. Use the +backupwallet+ command to back up, providing the filename as the parameter. Here we back up the wallet to the file _wallet.backup_: +This shows a node running Bitcoin Core version 0.11.2, with a blockchain height of 396328 blocks and 15 active network connections. +Once you are happy with the configuration options you have selected, you should add bitcoin to the startup scripts in your operating system, so that it runs continuously and restarts when the operating system restarts. You will find a number of example startup scripts for various operating systems in bitcoin's source directory under +contrib/init+ and a +README.md+ file showing which system uses which script. ----- -$ bitcoin-cli backupwallet wallet.backup -$ ----- +=== Bitcoin Core Application Programming Interface (API) -Now, to restore the backup file, use the +importwallet+ command. If your wallet is locked, you will need to unlock it first (see +walletpassphrase+ in the preceding section) in order to import the backup file: +((("Bitcoin Core client","JSON-RPC API for", id="ix_ch03-asciidoc5", range="startofrange")))((("Bitcoin Core client","using from command line", id="ix_ch03-asciidoc6", range="startofrange")))((("bitcoin-cli command line helper", id="ix_ch03-asciidoc7", range="startofrange")))The Bitcoin Core client 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. To start, invoke the +help+ command to see a list of the available bitcoin RPC commands: +[[bitcoind_commands]] ---- -$ bitcoin-cli importwallet wallet.backup -$ ----- +$ bitcoin-cli help +addmultisigaddress nrequired ["key",...] ( "account" ) +addnode "node" "add|remove|onetry" +backupwallet "destination" +createmultisig nrequired ["key",...] +createrawtransaction [{"txid":"id","vout":n},...] {"address":amount,...} +decoderawtransaction "hexstring" -The +dumpwallet+ command can be used to dump the wallet into a text file that is human-readable: +... +verifymessage "bitcoinaddress" "signature" "message" +walletlock +walletpassphrase "passphrase" timeout +walletpassphrasechange "oldpassphrase" "newpassphrase" ---- -$ bitcoin-cli dumpwallet wallet.txt -$ more wallet.txt -# Wallet dump created by Bitcoin v0.9.0rc1-beta (2014-01-31 09:30:15 +0100) -# * Created on 2014-02- 8dT20:34:55Z -# * Best block at time of backup was 286234 (0000000000000000f74f0bc9d3c186267bc45c7b91c49a0386538ac24c0d3a44), -# mined on 2014-02- 8dT20:24:01Z -KzTg2wn6Z8s7ai5NA9MVX4vstHRsqP26QKJCzLg4JvFrp6mMaGB9 2013-07- 4dT04:30:27Z change=1 # addr=16pJ6XkwSQv5ma5FSXMRPaXEYrENCEg47F -Kz3dVz7R6mUpXzdZy4gJEVZxXJwA15f198eVui4CUivXotzLBDKY 2013-07- 4dT04:30:27Z change=1 # addr=17oJds8kaN8LP8kuAkWTco6ZM7BGXFC3gk -[... many more keys ...] +Each of these commands may take a number of parameters. To get additional help, a detailed description and information on the parameters, add the command name after help. For example, to see help on the +getblockhash+ RPC command: -$ ---- +$ bitcoin-cli help getblockhash +getblockhash index -==== Wallet Addresses and Receiving Transactions - -Commands: getnewaddress, getreceivedbyaddress, listtransactions, getaddressesbyaccount, getbalance +Returns hash of block in best-block-chain at index provided. -((("addresses", id="ix_ch03-asciidoc9", range="startofrange")))((("bitcoin-cli command line helper","getaddressesbyaccount command", id="ix_ch03-asciidoc10", range="startofrange")))((("bitcoin-cli command line helper","getbalance command", id="ix_ch03-asciidoc11", range="startofrange")))((("bitcoin-cli command line helper","getnewaddress command", id="ix_ch03-asciidoc12", range="startofrange")))((("bitcoin-cli command line helper","getreceivedbyaddress command", id="ix_ch03-asciidoc13", range="startofrange")))((("bitcoin-cli command line helper","listtransactions command", id="ix_ch03-asciidoc14", range="startofrange")))((("getaddressesbyaccount command (bitcoin-cli)", id="ix_ch03-asciidoc15", range="startofrange")))((("getbalance command (bitcoin-cli)", id="ix_ch03-asciidoc16", range="startofrange")))((("getnewaddress command (bitcoin-cli)", id="ix_ch03-asciidoc17", range="startofrange")))((("getreceivedbyaddress command (bitcoin-cli)", id="ix_ch03-asciidoc18", range="startofrange")))((("listtransactions command (bitcoin-cli)", id="ix_ch03-asciidoc19", range="startofrange")))((("transactions","wallets, receiving", id="ix_ch03-asciidoc20", range="startofrange")))((("wallets","addresses of", id="ix_ch03-asciidoc21", range="startofrange")))((("wallets","receiving transactions", id="ix_ch03-asciidoc22", range="startofrange")))The bitcoin reference client maintains a pool of addresses, the size of which is displayed by +keypoolsize+ when you use the command +getinfo+. These addresses are generated automatically and can then be used as public receiving addresses or change addresses. To get one of these addresses, use the +getnewaddress+ command: +Arguments: +1. index (numeric, required) The block index +Result: +"hash" (string) The block hash ----- -$ bitcoin-cli getnewaddress -1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL +Examples: +> bitcoin-cli getblockhash 1000 +> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockhash", "params": [1000] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/ ---- -Now, we can use this address to send a small amount of bitcoin to our bitcoind wallet from an external wallet (assuming you have some bitcoin in an exchange, web wallet, or other bitcoind wallet held elsewhere). For this example, we will send 50 millibits (0.050 bitcoin) to the preceding address. - -We can now query the bitcoind client for the amount received by this address, and specify how many confirmations are required before an amount is counted in that balance. For this example, we will specify zero confirmations. A few seconds after sending the bitcoin from another wallet, we will see it reflected in the wallet. We use +getreceivedbyaddress+ with the address and the number of confirmations set to zero (0): - +At the end of the help information you will see two examples of the RPC command, using the +bitcoin-cli+ helper or the HTTP client +curl+. These examples demonstrate how you might call the command. Copy the first example and see the result: ---- -$ bitcoin-cli getreceivedbyaddress 1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL 0 -0.05000000 +$ bitcoin-cli getblockhash 1000 +00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09 ---- -If we omit the zero from the end of this command, we will only see the amounts that have at least +minconf+ confirmations, where +minconf+ is the setting for the minimum number of confirmations before a transaction is listed in the balance. The +minconf+ setting is specified in the bitcoind configuration file. Because the transaction sending this bitcoin was only sent in the last few seconds, it has still not confirmed and therefore we will see it list a zero balance: +The result is a block hash, which is described in more detail in the following chapters. But for now, this command should return the same result on your system, demonstrating that your Bitcoin Core node is running, is accepting commands and has information about block 1000 to return to you. +In the next sections we will demonstrate some very useful RPC commands and their expected output. ----- -$ bitcoin-cli getreceivedbyaddress 1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL -0.00000000 ----- +==== Getting Information on the Bitcoin Core Client Status -The transactions received by the entire wallet can also be displayed using the +listtransactions+ command: +Command: +getinfo+ +((("Bitcoin Core client","client status, getting")))((("bitcoin-cli command line helper","getinfo command")))((("client status, getting")))((("getinfo command (bitcoin-cli)")))Bitcoin's +getinfo+ RPC command displays basic information about the status of the bitcoin network node, the wallet, and the blockchain database. Use +bitcoin-cli+ to run it: ---- -$ bitcoin-cli listtransactions +$ bitcoin-cli getinfo ---- [source,json] ---- -[ - { - "account" : "", - "address" : "1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL", - "category" : "receive", - "amount" : 0.05000000, - "confirmations" : 0, - "txid" : "9ca8f969bd3ef5ec2a8685660fdbf7a8bd365524c2e1fc66c309acbae2c14ae3", - "time" : 1392660908, - "timereceived" : 1392660908 - } -] - ----- - -We can list all addresses in the entire wallet using the +getaddressesbyaccount+ command: - +{ + "version" : 110200, + "protocolversion" : 70002, + "blocks" : 396367, + "timeoffset" : 0, + "connections" : 15, + "proxy" : "", + "difficulty" : 120033340651.23696899, + "testnet" : false, + "relayfee" : 0.00010000, + "errors" : "" +} ----- -$ bitcoin-cli getaddressesbyaccount "" ----- -[source,json] ----- -[ - "1LQoTPYy1TyERbNV4zZbhEmgyfAipC6eqL", - "17vrg8uwMQUibkvS2ECRX4zpcVJ78iFaZS", - "1FvRHWhHBBZA8cGRRsGiAeqEzUmjJkJQWR", - "1NVJK3JsL41BF1KyxrUyJW5XHjunjfp2jz", - "14MZqqzCxjc99M5ipsQSRfieT7qPZcM7Df", - "1BhrGvtKFjTAhGdPGbrEwP3xvFjkJBuFCa", - "15nem8CX91XtQE8B1Hdv97jE8X44H3DQMT", - "1Q3q6taTsUiv3mMemEuQQJ9sGLEGaSjo81", - "1HoSiTg8sb16oE6SrmazQEwcGEv8obv9ns", - "13fE8BGhBvnoy68yZKuWJ2hheYKovSDjqM", - "1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL", - "1KHUmVfCJteJ21LmRXHSpPoe23rXKifAb2", - "1LqJZz1D9yHxG4cLkdujnqG5jNNGmPeAMD" -] ---- -Finally, the command +getbalance+ will show the total balance of the wallet, adding up all transactions confirmed with at least +minconf+ confirmations: - - ----- -$ bitcoin-cli getbalance -0.05000000 ----- +The data is returned in((("JavaScript Object Notation (JSON)"))) 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 (110200 and bitcoin protocol (70002). We see the current block height, showing us how many blocks are known to this client (396367). We also see various statistics about the bitcoin network and the settings related to this client. [TIP] ==== -((("getbalance command (bitcoin-cli)","unconfirmed transactions and")))((("unconfirmed transactions","getbalance command and")))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.(((range="endofrange", startref="ix_ch03-asciidoc22")))(((range="endofrange", startref="ix_ch03-asciidoc21")))(((range="endofrange", startref="ix_ch03-asciidoc20")))(((range="endofrange", startref="ix_ch03-asciidoc19")))(((range="endofrange", startref="ix_ch03-asciidoc18")))(((range="endofrange", startref="ix_ch03-asciidoc17")))(((range="endofrange", startref="ix_ch03-asciidoc16")))(((range="endofrange", startref="ix_ch03-asciidoc15")))(((range="endofrange", startref="ix_ch03-asciidoc14")))(((range="endofrange", startref="ix_ch03-asciidoc13")))(((range="endofrange", startref="ix_ch03-asciidoc12")))(((range="endofrange", startref="ix_ch03-asciidoc11")))(((range="endofrange", startref="ix_ch03-asciidoc10")))(((range="endofrange", startref="ix_ch03-asciidoc9"))) +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 +getinfo+ to see the number of known blocks. ==== - ==== Exploring and Decoding Transactions Commands: +gettransaction+, +getrawtransaction+, +decoderawtransaction+ -((("bitcoin-cli command line helper","decoderawtransaction command", id="ix_ch03-asciidoc23", range="startofrange")))((("bitcoin-cli command line helper","getrawtransaction command", id="ix_ch03-asciidoc24", range="startofrange")))((("bitcoin-cli command line helper","gettransaction command", id="ix_ch03-asciidoc25", range="startofrange")))((("decoderawtransaction command (bitcoin-cli)", id="ix_ch03-asciidoc26", range="startofrange")))((("getrawtransaction command (bitcoin-cli)", id="ix_ch03-asciidoc27", range="startofrange")))((("gettransaction command (bitcoin-cli)", id="ix_ch03-asciidoc28", range="startofrange")))((("transactions","decoding", id="ix_ch03-asciidoc29", range="startofrange")))((("transactions","exploring", id="ix_ch03-asciidoc30", range="startofrange")))We'll now explore the incoming transaction that was listed previously using the +gettransaction+ command. We can retrieve a transaction by its transaction hash, shown at +txid+ earlier, with the +gettransaction+ command: +((("bitcoin-cli command line helper","decoderawtransaction command", id="ix_ch03-asciidoc23", range="startofrange")))((("bitcoin-cli command line helper","getrawtransaction command", id="ix_ch03-asciidoc24", range="startofrange")))((("bitcoin-cli command line helper","gettransaction command", id="ix_ch03-asciidoc25", range="startofrange")))((("decoderawtransaction command (bitcoin-cli)", id="ix_ch03-asciidoc26", range="startofrange")))((("getrawtransaction command (bitcoin-cli)", id="ix_ch03-asciidoc27", range="startofrange")))((("gettransaction command (bitcoin-cli)", id="ix_ch03-asciidoc28", range="startofrange")))((("transactions","decoding", id="ix_ch03-asciidoc29", range="startofrange")))((("transactions","exploring", id="ix_ch03-asciidoc30", range="startofrange"))) - -++++ -
-$ bitcoin-cli gettransaction 9ca8f969bd3ef5ec2a8685660fdbf7a8bd365524c2e1fc66↵
-c309acbae2c14ae3
-
-
-++++ +---- +$ bitcoin-cli gettransaction 9ca8f969bd3ef5ec2a8685660fdbf7a8bd365524c2e1fc66� +---- [source,json] ---- { @@ -718,9 +613,9 @@ b2ac1bd193dfba2014104793ac8a58ea751f9710e39aad2e296cc14daa44fa59248be58ede65e&#x ++++ -The transaction decode shows all the components 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+). The two outputs correspond to the 50 millibit credit and an output with change back to the sender. +The transaction decode shows all the components 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+). 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 (e.g., +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 (e.g., +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: @@ -757,12 +652,12 @@ c309acbae2c14ae3 ++++ -Here, we see the new information in the entries +blockhash+ (the hash of the block in which the transaction was included), and +blockindex+ with value 18 (indicating that our transaction was the 18th transaction in that block). +Here, we see the new information in the entries +blockhash+ (the hash of the block in which the transaction was included), and +blockindex+ with value 18 (indicating that our transaction was the 18th transaction in that block). [[txindex]] .Transaction Database Index and txindex Option **** -((("transaction database index")))By default, Bitcoin Core builds a database containing _only_ the transactions related to the user's wallet. If you want to be able to access _any_ transaction with commands like +gettransaction+, you need to configure Bitcoin Core to build a complete transaction index, which can be achieved with the((("txindex option (Bitcoin Core)"))) +txindex+ option. Set +txindex=1+ in the Bitcoin Core configuration file (usually found in your home directory under _.bitcoin/bitcoin.conf_). Once you change this parameter, you need to restart bitcoind and wait for it to rebuild the index.(((range="endofrange", startref="ix_ch03-asciidoc30")))(((range="endofrange", startref="ix_ch03-asciidoc29")))(((range="endofrange", startref="ix_ch03-asciidoc28")))(((range="endofrange", startref="ix_ch03-asciidoc27")))(((range="endofrange", startref="ix_ch03-asciidoc26")))(((range="endofrange", startref="ix_ch03-asciidoc25")))(((range="endofrange", startref="ix_ch03-asciidoc24")))(((range="endofrange", startref="ix_ch03-asciidoc23"))) +((("transaction database index")))By default, Bitcoin Core builds a database containing _only_ the transactions related to the user's wallet. If you want to be able to access _any_ transaction with commands like +gettransaction+, you need to configure Bitcoin Core to build a complete transaction index, which can be achieved with the((("txindex option (Bitcoin Core)"))) +txindex+ option. Set +txindex=1+ in the Bitcoin Core configuration file (usually found in your home directory under _.bitcoin/bitcoin.conf_). Once you change this parameter, you need to restart bitcoind and wait for it to rebuild the index.(((range="endofrange", startref="ix_ch03-asciidoc30")))(((range="endofrange", startref="ix_ch03-asciidoc29")))(((range="endofrange", startref="ix_ch03-asciidoc28")))(((range="endofrange", startref="ix_ch03-asciidoc27")))(((range="endofrange", startref="ix_ch03-asciidoc26")))(((range="endofrange", startref="ix_ch03-asciidoc25")))(((range="endofrange", startref="ix_ch03-asciidoc24")))(((range="endofrange", startref="ix_ch03-asciidoc23"))) **** ==== Exploring Blocks @@ -829,7 +724,7 @@ d829a92eb6" ++++ -The block contains 367 transactions and as you can see, 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 286384th block in the blockchain. +The block contains 367 transactions and as you can see, 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 286384th 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: @@ -878,348 +773,13 @@ bf18eb6048" ++++ -The +getblock+, +getblockhash+, and +gettransaction+ commands can be used to explore the blockchain database, programmatically. - - -==== Creating, Signing, and Submitting Transactions Based on pass:[Unspent Outputs] +The +getblock+, +getblockhash+, and +gettransaction+ commands can be used to explore the blockchain database, programmatically. -Commands: +listunspent+, +gettxout+, +createrawtransaction+, +decoderawtransaction+, +signrawtransaction+, +sendrawtransaction+ - -((("bitcoin-cli command line helper","createrawtransaction command", id="ix_ch03-asciidoc31", range="startofrange")))((("bitcoin-cli command line helper","decoderawtransaction command", id="ix_ch03-asciidoc32", range="startofrange")))((("bitcoin-cli command line helper","gettxout command", id="ix_ch03-asciidoc33", range="startofrange")))((("bitcoin-cli command line helper","listunspent command", id="ix_ch03-asciidoc34", range="startofrange")))((("bitcoin-cli command line helper","sendrawtransaction command", id="ix_ch03-asciidoc35", range="startofrange")))((("bitcoin-cli command line helper","signrawtransaction command", id="ix_ch03-asciidoc36", range="startofrange")))((("createrawtransaction command (bitcoin-cli)", id="ix_ch03-asciidoc37", range="startofrange")))((("decoderawtransaction command (bitcoin-cli)", id="ix_ch03-asciidoc38", range="startofrange")))((("gettxout command (bitcoin-cli)", id="ix_ch03-asciidoc39", range="startofrange")))((("listunspent command (bitcoin-cli)", id="ix_ch03-asciidoc40", range="startofrange")))((("sendrawtransaction command (bitcoin-cli)", id="ix_ch03-asciidoc41", range="startofrange")))((("signrawtransaction command (bitcoin-cli)", id="ix_ch03-asciidoc42", range="startofrange")))((("transactions","creating from the command line", id="ix_ch03-asciidoc43", range="startofrange")))((("transactions","signing from the command line", id="ix_ch03-asciidoc44", range="startofrange")))((("transactions","submitting from the command line", id="ix_ch03-asciidoc45", range="startofrange")))((("unspent transaction output (UTXO)", id="ix_ch03-asciidoc46", range="startofrange")))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 spend that output. - -First, we use the +listunspent+ command to show all the unspent _confirmed_ outputs in our wallet: - - ----- -$ bitcoin-cli listunspent ----- - - -++++ -
-[
-    {
-        "txid" : "9ca8f969bd3ef5ec2a8685660fdbf7a8bd365524c2e1fc66c309acbae2c↵
-14ae3",
-        "vout" : 0,
-        "address" : "1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL",
-        "account" : "",
-        "scriptPubKey" : "76a91407bdb518fa2e6089fd810235cf1100c9c13d1fd288ac",
-        "amount" : 0.05000000,
-        "confirmations" : 7
-    }
-]
-
-++++ - -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 seven 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 0th 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 +gettxout+ to get the details of this unspent output. Transaction outputs are always referenced by txid and vout, and these are the parameters we pass to +gettxout+: - - -++++ -
-$ bitcoin-cli gettxout 9ca8f969bd3ef5ec2a8685660fdbf7a8bd365524c2e1fc66c309ac↵
-bae2c14ae3 0
-
-++++ - - -++++ -
-{
-    "bestblock" : "0000000000000001405ce69bd4ceebcdfdb537749cebe89d371eb37e13↵
-899fd9",
-    "confirmations" : 7,
-    "value" : 0.05000000,
-    "scriptPubKey" : {
-        "asm" : "OP_DUP OP_HASH160 07bdb518fa2e6089fd810235cf1100c9c13d1fd2
-         OP_EQUALVERIFY OP_CHECKSIG",
-        "hex" : "76a91407bdb518fa2e6089fd810235cf1100c9c13d1fd288ac",
-        "reqSigs" : 1,
-        "type" : "pubkeyhash",
-        "addresses" : [
-            "1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL"
-        ]
-    },
-    "version" : 1,
-    "coinbase" : false
-}
-
-++++ - -What we see here is the output that assigned 50 millibits to our address +1hvz...+. To spend this output we will create a new transaction. First, let's make an address to which we will send the money: - - ----- -$ bitcoin-cli getnewaddress -1LnfTndy3qzXGN19Jwscj1T8LR3MVe3JDb ----- - -We will send 25 millibits to the new address +1LnfTn...+ we just created in our wallet. In our new transaction, we will spend the 50 millibit output and send 25 millibits to this new address. Because we have to spend the _whole_ output from the previous transaction, we must also generate some change. We will generate change back to the +1hvz...+ address, sending the change back to the address from which the value originated. Finally, we will also have to pay a fee for this transaction. To pay the fee, we will reduce the change output by 0.5 millibits, and return 24.5 millibits in change. The difference between the sum of the new outputs (25 mBTC + 24.5 mBTC = 49.5 mBTC) and the input (50 mBTC) will be collected as a transaction fee by the miners. - -We use +createrawtransaction+ to create this transaction. As parameters to +createrawtransaction+ we provide the transaction input (the 50 millibit unspent output from our confirmed transaction) and the two transaction outputs (money sent to the new address and change sent back to the previous address): - -++++ -
-$ bitcoin-cli createrawtransaction '[{"txid" : "9ca8f969bd3ef5ec2a8685660fdbf↵
-$ bitcoin-cli createrawtransaction '[{"txid" : "9ca8f969bd3ef5ec2a8685660fdbf↵
-7a8bd365524c2e1fc66c309acbae2c14ae3", "vout" : 0}]' '{"1LnfTndy3qzXGN19Jwscj1↵
-T8LR3MVe3JDb": 0.025, "1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL": 0.0245}'
-
-0100000001e34ac1e2baac09c366fce1c2245536bda8f7db0f6685862aecf53ebd69f9a89c000↵
-0000000ffffffff02a0252600000000001976a914d90d36e98f62968d2bc9bbd68107564a156a↵
-9bcf88ac50622500000000001976a91407bdb518fa2e6089fd810235cf1100c9c13d1fd288ac0↵
-0000000
-
-++++ - -The +createrawtransaction+ command produces a raw hex string that encodes the transaction details we supplied. Let's confirm everything is correct by decoding this raw string using the +decoderawtransaction+ command: - -++++ -
-$ bitcoin-cli decoderawtransaction 0100000001e34ac1e2baac09c366fce1c2245536bd↵
-a8f7db0f6685862aecf53ebd69f9a89c0000000000ffffffff02a0252600000000001976a914d↵
-90d36e98f62968d2bc9bbd68107564a156a9bcf88ac50622500000000001976a91407bdb518fa↵
-2e6089fd810235cf1100c9c13d1fd288ac00000000
-
-++++ - - -++++ -
-{
-    "txid" : "0793299cb26246a8d24e468ec285a9520a1c30fcb5b6125a102e3fc05d4f3cb↵
-a",
-    "version" : 1,
-    "locktime" : 0,
-    "vin" : [
-        {
-            "txid" : "9ca8f969bd3ef5ec2a8685660fdbf7a8bd365524c2e1fc66c309acb↵
-ae2c14ae3",
-            "vout" : 0,
-            "scriptSig" : {
-                "asm" : "",
-                "hex" : ""
-            },
-            "sequence" : 4294967295
-        }
-    ],
-    "vout" : [
-        {
-            "value" : 0.02500000,
-            "n" : 0,
-            "scriptPubKey" : {
-                "asm" : "OP_DUP OP_HASH160 d90d36e98f62968d2bc9bbd68107564a15↵
-6a9bcf OP_EQUALVERIFY OP_CHECKSIG",
-                "hex" : "76a914d90d36e98f62968d2bc9bbd68107564a156a9bcf88ac",
-                "reqSigs" : 1,
-                "type" : "pubkeyhash",
-                "addresses" : [
-                    "1LnfTndy3qzXGN19Jwscj1T8LR3MVe3JDb"
-                ]
-            }
-        },
-        {
-            "value" : 0.02450000,
-            "n" : 1,
-            "scriptPubKey" : {
-                "asm" : "OP_DUP OP_HASH160 07bdb518fa2e6089fd810235cf1100c9c1↵
-3d1fd2 OP_EQUALVERIFY OP_CHECKSIG",
-                "hex" : "76a91407bdb518fa2e6089fd810235cf1100c9c13d1fd288ac",
-                "reqSigs" : 1,
-                "type" : "pubkeyhash",
-                "addresses" : [
-                    "1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL"
-                ]
-            }
-        }
-    ]
-}
-
-++++ - -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 might 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 unspent output is sourced. By signing, we remove the lock 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] -==== -((("wallets","signing transactions with")))An encrypted wallet must be unlocked before a transaction is signed because signing requires access to the secret keys in the wallet. -==== - -++++ -
-$ bitcoin-cli walletpassphrase foo 360
-$ bitcoin-cli signrawtransaction 0100000001e34ac1e2baac09c366fce1c2245536bda8↵
-f7db0f6685862aecf53ebd69f9a89c0000000000ffffffff02a0252600000000001976a914d90↵
-d36e98f62968d2bc9bbd68107564a156a9bcf88ac50622500000000001976a91407bdb518fa2e↵
-6089fd810235cf1100c9c13d1fd288ac00000000
-
-++++ - - -++++ -
-{
-    "hex" : "0100000001e34ac1e2baac09c366fce1c2245536bda8f7db0f6685862aecf53e↵
-bd69f9a89c000000006a47304402203e8a16522da80cef66bacfbc0c800c6d52c4a26d1d86a54↵
-e0a1b76d661f020c9022010397f00149f2a8fb2bc5bca52f2d7a7f87e3897a273ef54b277e4af↵
-52051a06012103c9700559f690c4a9182faa8bed88ad8a0c563777ac1d3f00fd44ea6c71dc512↵
-7ffffffff02a0252600000000001976a914d90d36e98f62968d2bc9bbd68107564a156a9bcf88↵
-ac50622500000000001976a91407bdb518fa2e6089fd810235cf1100c9c13d1fd288ac00000000",
-    "complete" : true
-}
-
-++++ - -The +signrawtransaction+ command returns another hex-encoded raw transaction. We decode it to see what changed, with +decoderawtransaction+: - - -++++ -
-$ bitcoin-cli decoderawtransaction 0100000001e34ac1e2baac09c366fce1c2245536bda↵
-8f7db0f6685862aecf53ebd69f9a89c000000006a47304402203e8a16522da80cef66bacfbc0c↵
-800c6d52c4a26d1d86a54e0a1b76d661f020c9022010397f00149f2a8fb2bc5bca52f2d7a7f87↵
-e3897a273ef54b277e4af52051a06012103c9700559f690c4a9182faa8bed88ad8a0c563777ac↵
-1d3f00fd44ea6c71dc5127ffffffff02a0252600000000001976a914d90d36e98f62968d2bc9b↵
-bd68107564a156a9bcf88ac50622500000000001976a91407bdb518fa2e6089fd810235cf1100↵
-c9c13d1fd288ac00000000
-
-++++ - - -++++ -
-{
-    "txid" : "ae74538baa914f3799081ba78429d5d84f36a0127438e9f721dff584ac17b34↵
-6",
-    "version" : 1,
-    "locktime" : 0,
-    "vin" : [
-        {
-            "txid" : "9ca8f969bd3ef5ec2a8685660fdbf7a8bd365524c2e1fc66c309acb↵
-ae2c14ae3",
-            "vout" : 0,
-            "scriptSig" : {
-                "asm" : "304402203e8a16522da80cef66bacfbc0c800c6d52c4a26d1d86↵
-a54e0a1b76d661f020c9022010397f00149f2a8fb2bc5bca52f2d7a7f87e3897a273ef54b277e↵
-4af52051a0601 03c9700559f690c4a9182faa8bed88ad8a0c563777ac1d3f00fd44ea6c71dc5↵
-127",
-                "hex" : "47304402203e8a16522da80cef66bacfbc0c800c6d52c4a26d1d↵
-86a54e0a1b76d661f020c9022010397f00149f2a8fb2bc5bca52f2d7a7f87e3897a273ef54b27↵
-7e4af52051a06012103c9700559f690c4a9182faa8bed88ad8a0c563777ac1d3f00fd44ea6c71↵
-dc5127"
-            },
-            "sequence" : 4294967295
-        }
-    ],
-    "vout" : [
-        {
-            "value" : 0.02500000,
-            "n" : 0,
-            "scriptPubKey" : {
-                "asm" : "OP_DUP OP_HASH160 d90d36e98f62968d2bc9bbd68107564a15↵
-6a9bcf OP_EQUALVERIFY OP_CHECKSIG",
-                "hex" : "76a914d90d36e98f62968d2bc9bbd68107564a156a9bcf88ac",
-                "reqSigs" : 1,
-                "type" : "pubkeyhash",
-                "addresses" : [
-                    "1LnfTndy3qzXGN19Jwscj1T8LR3MVe3JDb"
-                ]
-            }
-        },
-        {
-            "value" : 0.02450000,
-            "n" : 1,
-            "scriptPubKey" : {
-                "asm" : "OP_DUP OP_HASH160 07bdb518fa2e6089fd810235cf1100c9c1↵
-3d1fd2 OP_EQUALVERIFY OP_CHECKSIG",
-                "hex" : "76a91407bdb518fa2e6089fd810235cf1100c9c13d1fd288ac",
-                "reqSigs" : 1,
-                "type" : "pubkeyhash",
-                "addresses" : [
-                    "1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL"
-                ]
-            }
-        }
-    ]
-}
-
-++++ - -Now, the inputs used in the transaction contain a +scriptSig+, which is a digital signature proving ownership of address +1hvz...+ and removing the lock 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+. This is the same string we just decoded: - -++++ -
-$ bitcoin-cli sendrawtransaction 0100000001e34ac1e2baac09c366fce1c2245536bda8↵
-f7db0f6685862aecf53ebd69f9a89c000000006a47304402203e8a16522da80cef66bacfbc0c8↵
-00c6d52c4a26d1d86a54e0a1b76d661f020c9022010397f00149f2a8fb2bc5bca52f2d7a7f87e↵
-3897a273ef54b277e4af52051a06012103c9700559f690c4a9182faa8bed88ad8a0c563777ac1↵
-d3f00fd44ea6c71dc5127ffffffff02a0252600000000001976a914d90d36e98f62968d2bc9bb↵
-d68107564a156a9bcf88ac50622500000000001976a91407bdb518fa2e6089fd810235cf1100c↵
-9c13d1fd288ac00000000ae74538baa914f3799081ba78429d5d84f36a0127438e9f721dff584↵
-ac17b346
-
-++++ - -The command +sendrawtransaction+ returns a _transaction hash (txid)_ as it submits the transaction on the network. We can now query that transaction ID with +gettransaction+: - -++++ -
-$ bitcoin-cli gettransaction ae74538baa914f3799081ba78429d5d84f36a0127438e9f7↵
-21dff584ac17b346
-
-++++ - -[source,json] ----- -{ - "amount" : 0.00000000, - "fee" : -0.00050000, - "confirmations" : 0, - "txid" : "ae74538baa914f3799081ba78429d5d84f36a0127438e9f721dff584ac17b346", - "time" : 1392666702, - "timereceived" : 1392666702, - "details" : [ - { - "account" : "", - "address" : "1LnfTndy3qzXGN19Jwscj1T8LR3MVe3JDb", - "category" : "send", - "amount" : -0.02500000, - "fee" : -0.00050000 - }, - { - "account" : "", - "address" : "1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL", - "category" : "send", - "amount" : -0.02450000, - "fee" : -0.00050000 - }, - { - "account" : "", - "address" : "1LnfTndy3qzXGN19Jwscj1T8LR3MVe3JDb", - "category" : "receive", - "amount" : 0.02500000 - }, - { - "account" : "", - "address" : "1hvzSofGwT8cjb8JU7nBsCSfEVQX5u9CL", - "category" : "receive", - "amount" : 0.02450000 - } - ] -} ----- - -As before, we can also examine this in more detail using the +getrawtransaction+ and +decodetransaction+ commands. These commands will return the exact same hex string that we produced and decoded previously just before we sent it on the network.(((range="endofrange", startref="ix_ch03-asciidoc46")))(((range="endofrange", startref="ix_ch03-asciidoc45")))(((range="endofrange", startref="ix_ch03-asciidoc44")))(((range="endofrange", startref="ix_ch03-asciidoc43")))(((range="endofrange", startref="ix_ch03-asciidoc42")))(((range="endofrange", startref="ix_ch03-asciidoc41")))(((range="endofrange", startref="ix_ch03-asciidoc40")))(((range="endofrange", startref="ix_ch03-asciidoc39")))(((range="endofrange", startref="ix_ch03-asciidoc38")))(((range="endofrange", startref="ix_ch03-asciidoc37")))(((range="endofrange", startref="ix_ch03-asciidoc36")))(((range="endofrange", startref="ix_ch03-asciidoc35")))(((range="endofrange", startref="ix_ch03-asciidoc34")))(((range="endofrange", startref="ix_ch03-asciidoc33")))(((range="endofrange", startref="ix_ch03-asciidoc32")))(((range="endofrange", startref="ix_ch03-asciidoc31")))(((range="endofrange", startref="ix_ch03-asciidoc7")))(((range="endofrange", startref="ix_ch03-asciidoc6")))(((range="endofrange", startref="ix_ch03-asciidoc5")))(((range="endofrange", startref="ix_ch03-asciidoc2")))(((range="endofrange", startref="ix_ch03-asciidoc1"))) [[alt_libraries]] === Alternative Clients, Libraries, and Toolkits -((("clients, alternative", id="ix_ch03-asciidoc47", range="startofrange")))((("libraries, alternative", id="ix_ch03-asciidoc48", range="startofrange")))((("toolkits, alternative", id="ix_ch03-asciidoc49", range="startofrange")))Beyond the reference client (bitcoind), other clients and libraries can be used to interact with the bitcoin network and data structures. These are implemented in a variety of programming languages, offering programmers native interfaces in their own language. +((("clients, alternative", id="ix_ch03-asciidoc47", range="startofrange")))((("libraries, alternative", id="ix_ch03-asciidoc48", range="startofrange")))((("toolkits, alternative", id="ix_ch03-asciidoc49", range="startofrange")))Beyond the reference client (bitcoind), other clients and libraries can be used to interact with the bitcoin network and data structures. These are implemented in a variety of programming languages, offering programmers native interfaces in their own language. Alternative implementations include: @@ -1233,7 +793,7 @@ https://github.com/jgarzik/picocoin[picocoin]:: ((("picocoin")))A C implementati https://github.com/vbuterin/pybitcointools[pybitcointools]:: ((("pybitcointools library")))A Python bitcoin library https://github.com/richardkiss/pycoin[pycoin]:: ((("pycoin library")))Another Python bitcoin library -Many more libraries exist in a variety of other programming languages and more are created all the time. +Many more libraries exist in a variety of other programming languages and more are created all the time. [[libbitcoin]] ==== Libbitcoin and Bitcoin Explorer @@ -1266,7 +826,7 @@ The Bitcoin Explorer installer installs both bx and the libbitcoin library, so i ==== pycoin -((("libraries, alternative","pycoin library")))((("pycoin library")))((("Python","pycoin library")))The Python library http://github.com/richardkiss/pycoin[_pycoin_], originally written and maintained by((("Kiss, Richard"))) Richard Kiss, is a Python-based library that supports manipulation of bitcoin keys and transactions, even supporting the scripting language enough to properly deal with nonstandard transactions. +((("libraries, alternative","pycoin library")))((("pycoin library")))((("Python","pycoin library")))The Python library http://github.com/richardkiss/pycoin[_pycoin_], originally written and maintained by((("Kiss, Richard"))) Richard Kiss, is a Python-based library that supports manipulation of bitcoin keys and transactions, even supporting the scripting language enough to properly deal with nonstandard transactions. The pycoin library supports both Python 2 (2.7.x) and Python 3 (after 3.3), and comes with some handy command-line utilities, ku and tx. To install pycoin 0.42 under Python 3 in a virtual environment (venv), use the following: @@ -1278,10 +838,10 @@ $ pip install pycoin==0.42 Downloading/unpacking pycoin==0.42 Downloading pycoin-0.42.tar.gz (66kB): 66kB downloaded Running setup.py (path:/tmp/pycoin/build/pycoin/setup.py) egg_info for package pycoin - + Installing collected packages: pycoin Running setup.py install for pycoin - + Installing tx script to /tmp/pycoin/bin Installing cache_tx script to /tmp/pycoin/bin Installing bu script to /tmp/pycoin/bin @@ -1330,7 +890,7 @@ $ go get -u -v github.com/conformal/btcd/... ===== Controlling btcd -((("btcd","controlling")))btcd has a number of configuration options, which you can view by running: +((("btcd","controlling")))btcd has a number of configuration options, which you can view by running: [source,bash] ---- @@ -1362,10 +922,9 @@ $ btcd -u myuser -P SomeDecentp4ssw0rd $ btcctl -u myuser -P SomeDecentp4ssw0rd ---- -For a list of available options, run the following: (((range="endofrange", startref="ix_ch03-asciidoc49")))(((range="endofrange", startref="ix_ch03-asciidoc48")))(((range="endofrange", startref="ix_ch03-asciidoc47")))(((range="endofrange", startref="ix_ch03-asciidoc0"))) +For a list of available options, run the following: (((range="endofrange", startref="ix_ch03-asciidoc49")))(((range="endofrange", startref="ix_ch03-asciidoc48")))(((range="endofrange", startref="ix_ch03-asciidoc47")))(((range="endofrange", startref="ix_ch03-asciidoc0"))) ---- $ btcctl --help ---- -