diff options
Diffstat (limited to 'doc')
82 files changed, 5363 insertions, 954 deletions
diff --git a/doc/Doxyfile b/doc/Doxyfile index e0339e652e..428fba98e1 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -34,7 +34,7 @@ PROJECT_NAME = Bitcoin # This could be handy for archiving the generated documentation or # if some version control system is used. -PROJECT_NUMBER = 0.9.99 +PROJECT_NUMBER = 0.12.99 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer diff --git a/doc/README.md b/doc/README.md index d5d61738e8..c30f29452b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,37 +1,28 @@ -Bitcoin 0.9.99 BETA +Bitcoin Core 0.12.99 ===================== -Copyright (c) 2009-2014 Bitcoin Developers - - Setup --------------------- -[Bitcoin Core](http://bitcoin.org/en/download) is the original Bitcoin client and it builds the backbone of the network. However, it downloads and stores the entire history of Bitcoin transactions (which is currently several GBs); depending on the speed of your computer and network connection, the synchronization process can take anywhere from a few hours to a day or more. Thankfully you only have to do this once. If you would like the process to go faster you can [download the blockchain directly](bootstrap.md). +[Bitcoin Core](http://bitcoin.org/en/download) is the original Bitcoin client and it builds the backbone of the network. However, it downloads and stores the entire history of Bitcoin transactions (which is currently several GBs); depending on the speed of your computer and network connection, the synchronization process can take anywhere from a few hours to a day or more. Running --------------------- -The following are some helpful notes on how to run Bitcoin on your native platform. +The following are some helpful notes on how to run Bitcoin on your native platform. ### Unix -You need the Qt4 run-time libraries to run Bitcoin-Qt. On Debian or Ubuntu: - - sudo apt-get install libqtgui4 - Unpack the files into a directory and run: -- bin/32/bitcoin-qt (GUI, 32-bit) or bin/32/bitcoind (headless, 32-bit) -- bin/64/bitcoin-qt (GUI, 64-bit) or bin/64/bitcoind (headless, 64-bit) - - +- `bin/bitcoin-qt` (GUI) or +- `bin/bitcoind` (headless) ### Windows Unpack the files into a directory, and then run bitcoin-qt.exe. -### OSX +### OS X -Drag Bitcoin-Qt to your applications folder, and then run Bitcoin-Qt. +Drag Bitcoin-Core to your applications folder, and then run Bitcoin-Core. ### Need Help? @@ -44,24 +35,34 @@ Building --------------------- The following are developer notes on how to build Bitcoin on your native platform. They are not complete guides, but include notes on the necessary libraries, compile flags, etc. -- [OSX Build Notes](build-osx.md) +- [OS X Build Notes](build-osx.md) - [Unix Build Notes](build-unix.md) +- [Windows Build Notes](build-windows.md) +- [OpenBSD Build Notes](build-openbsd.md) +- [Gitian Building Guide](gitian-building.md) Development --------------------- -The Bitcoin repo's [root README](https://github.com/bitcoin/bitcoin/blob/master/README.md) contains relevant information on the development process and automated testing. +The Bitcoin repo's [root README](/README.md) contains relevant information on the development process and automated testing. -- [Coding Guidelines](coding.md) +- [Developer Notes](developer-notes.md) - [Multiwallet Qt Development](multiwallet-qt.md) - [Release Notes](release-notes.md) - [Release Process](release-process.md) - [Source Code Documentation (External Link)](https://dev.visucore.com/bitcoin/doxygen/) - [Translation Process](translation_process.md) +- [Translation Strings Policy](translation_strings_policy.md) - [Unit Tests](unit-tests.md) +- [Unauthenticated REST Interface](REST-interface.md) +- [Shared Libraries](shared-libraries.md) +- [BIPS](bips.md) +- [Dnsseed Policy](dnsseed-policy.md) +- [Benchmarking](benchmarking.md) ### Resources * Discuss on the [BitcoinTalk](https://bitcointalk.org/) forums, in the [Development & Technical Discussion board](https://bitcointalk.org/index.php?board=6.0). -* Discuss on [#bitcoin-dev](http://webchat.freenode.net/?channels=bitcoin) on Freenode. If you don't have an IRC client use [webchat here](http://webchat.freenode.net/?channels=bitcoin-dev). +* Discuss project-specific development on #bitcoin-core-dev on Freenode. If you don't have an IRC client use [webchat here](http://webchat.freenode.net/?channels=bitcoin-core-dev). +* Discuss general Bitcoin development on #bitcoin-dev on Freenode. If you don't have an IRC client use [webchat here](http://webchat.freenode.net/?channels=bitcoin-dev). ### Miscellaneous - [Assets Attribution](assets-attribution.md) @@ -71,6 +72,6 @@ The Bitcoin repo's [root README](https://github.com/bitcoin/bitcoin/blob/master/ License --------------------- -Distributed under the [MIT/X11 software license](http://www.opensource.org/licenses/mit-license.php). +Distributed under the [MIT software license](http://www.opensource.org/licenses/mit-license.php). This product includes software developed by the OpenSSL Project for use in the [OpenSSL Toolkit](https://www.openssl.org/). This product includes cryptographic software written by Eric Young ([eay@cryptsoft.com](mailto:eay@cryptsoft.com)), and UPnP software written by Thomas Bernard. diff --git a/doc/README_osx.txt b/doc/README_osx.md index d56234f7d9..aed3cd97e1 100644 --- a/doc/README_osx.txt +++ b/doc/README_osx.md @@ -1,21 +1,19 @@ -Deterministic OSX Dmg Notes. +Deterministic OS X Dmg Notes. -Working OSX DMG's are created in Linux by combining a recent clang, -the Apple's binutils (ld, ar, etc), and DMG authoring tools. +Working OS X DMGs are created in Linux by combining a recent clang, +the Apple binutils (ld, ar, etc) and DMG authoring tools. Apple uses clang extensively for development and has upstreamed the necessary functionality so that a vanilla clang can take advantage. It supports the use of -F, -target, -mmacosx-version-min, and --sysroot, which are all necessary -when building for OSX. A pre-compiled version of 3.2 is used because it was not -available in the Precise repositories at the time this work was started. In the -future, it can be switched to use system packages instead. +when building for OS X. Apple's version of binutils (called cctools) contains lots of functionality missing in the FSF's binutils. In addition to extra linker options for frameworks and sysroots, several other tools are needed as well such as install_name_tool, lipo, and nmedit. These do not build under linux, so they have been patched to do so. The work here was used as a starting point: -https://github.com/mingwandroid/toolchain4 +[mingwandroid/toolchain4](https://github.com/mingwandroid/toolchain4). In order to build a working toolchain, the following source packages are needed from Apple: cctools, dyld, and ld64. @@ -29,17 +27,21 @@ originally done in toolchain4. To complicate things further, all builds must target an Apple SDK. These SDKs are free to download, but not redistributable. -To obtain it, register for a developer account, then download xcode4630916281a.dmg: -https://developer.apple.com/downloads/download.action?path=Developer_Tools/xcode_4.6.3/xcode4630916281a.dmg +To obtain it, register for a developer account, then download the [Xcode 7.3.1 dmg](https://developer.apple.com/devcenter/download.action?path=/Developer_Tools/Xcode_7.3.1/Xcode_7.3.1.dmg). + This file is several gigabytes in size, but only a single directory inside is -needed: Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk +needed: +``` +Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk +``` Unfortunately, the usual linux tools (7zip, hpmount, loopback mount) are incapable of opening this file. -To create a tarball suitable for gitian input, mount the dmg in OSX, then create it with: - $ tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.7.sdk.tar.gz MacOSX10.7.sdk - +To create a tarball suitable for Gitian input, mount the dmg in OS X, then create it with: +``` + $ tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.11.sdk.tar.gz MacOSX10.11.sdk +``` -The gitian descriptors build 2 sets of files: Linux tools, then Apple binaries +The Gitian descriptors build 2 sets of files: Linux tools, then Apple binaries which are created using these tools. The build process has been designed to avoid including the SDK's files in Gitian's outputs. All interim tarballs are fully deterministic and may be freely redistributed. @@ -47,36 +49,34 @@ fully deterministic and may be freely redistributed. genisoimage is used to create the initial DMG. It is not deterministic as-is, so it has been patched. A system genisoimage will work fine, but it will not be deterministic because the file-order will change between invocations. -The patch can be seen here: -https://raw.githubusercontent.com/theuni/osx-cross-depends/master/patches/cdrtools/genisoimage.diff +The patch can be seen here: [theuni/osx-cross-depends](https://raw.githubusercontent.com/theuni/osx-cross-depends/master/patches/cdrtools/genisoimage.diff). No effort was made to fix this cleanly, so it likely leaks memory badly. But it's only used for a single invocation, so that's no real concern. genisoimage cannot compress DMGs, so afterwards, the 'dmg' tool from the libdmg-hfsplus project is used to compress it. There are several bugs in this tool and its maintainer has seemingly abandoned the project. It has been forked -and is available (with fixes) here: https://github.com/theuni/libdmg-hfsplus . +and is available (with fixes) here: [theuni/libdmg-hfsplus](https://github.com/theuni/libdmg-hfsplus). -The 'dmg' tool has the ability to create DMG's from scratch as well, but this +The 'dmg' tool has the ability to create DMGs from scratch as well, but this functionality is broken. Only the compression feature is currently used. Ideally, the creation could be fixed and genisoimage would no longer be necessary. Background images and other features can be added to DMG files by inserting a -.DS_Store before creation. The easiest way to create this file is to build a -DMG without one, move it to a device running OSX, customize the layout, then -grab the .DS_Store file for later use. That is the approach taken here. +.DS_Store before creation. This is generated by the script +contrib/macdeploy/custom_dsstore.py. -As of OSX Mavericks (10.9), using an Apple-blessed key to sign binaries is a +As of OS X Mavericks (10.9), using an Apple-blessed key to sign binaries is a requirement in order to satisfy the new Gatekeeper requirements. Because this private key cannot be shared, we'll have to be a bit creative in order for the build process to remain somewhat deterministic. Here's how it works: -- Builders use gitian to create an unsigned release. This outputs an unsigned +- Builders use Gitian to create an unsigned release. This outputs an unsigned dmg which users may choose to bless and run. It also outputs an unsigned app structure in the form of a tarball, which also contains all of the tools that have been previously (deterministically) built in order to create a final dmg. - The Apple keyholder uses this unsigned app to create a detached signature, - using the script that is also included there. -- Builders feed the unsigned app + detached signature back into gitian. It + using the script that is also included there. Detached signatures are available from this [repository](https://github.com/bitcoin-core/bitcoin-detached-sigs). +- Builders feed the unsigned app + detached signature back into Gitian. It uses the pre-built tools to recombine the pieces into a deterministic dmg. diff --git a/doc/README_windows.txt b/doc/README_windows.txt index 368f2b45e1..2d1c4503c9 100644 --- a/doc/README_windows.txt +++ b/doc/README_windows.txt @@ -1,13 +1,5 @@ -Bitcoin 0.9.99 BETA
-
-Copyright (c) 2009-2014 Bitcoin Core Developers
-
-Distributed under the MIT/X11 software license, see the accompanying
-file COPYING or http://www.opensource.org/licenses/mit-license.php.
-This product includes software developed by the OpenSSL Project for use in
-the OpenSSL Toolkit (https://www.openssl.org/). This product includes
-cryptographic software written by Eric Young (eay@cryptsoft.com).
-
+Bitcoin Core 0.12.99
+=====================
Intro
-----
diff --git a/doc/REST-interface.md b/doc/REST-interface.md index 0af650b4e8..bf669235e3 100644 --- a/doc/REST-interface.md +++ b/doc/REST-interface.md @@ -5,23 +5,92 @@ The REST API can be enabled with the `-rest` option. Supported API ------------- -`GET /rest/tx/TX-HASH.{bin|hex|json}` -Given a transaction hash, -Returns a transaction, in binary, hex-encoded binary or JSON formats. +####Transactions +`GET /rest/tx/<TX-HASH>.<bin|hex|json>` -`GET /rest/block/BLOCK-HASH.{bin|hex|json}` -`GET /rest/block/notxdetails/BLOCK-HASH.{bin|hex|json}` +Given a transaction hash: returns a transaction in binary, hex-encoded binary, or JSON formats. -Given a block hash, -Returns a block, in binary, hex-encoded binary or JSON formats. +For full TX query capability, one must enable the transaction index via "txindex=1" command line / configuration option. + +####Blocks +`GET /rest/block/<BLOCK-HASH>.<bin|hex|json>` +`GET /rest/block/notxdetails/<BLOCK-HASH>.<bin|hex|json>` + +Given a block hash: returns a block, in binary, hex-encoded binary or JSON formats. The HTTP request and response are both handled entirely in-memory, thus making maximum memory usage at least 2.66MB (1 MB max block, plus hex encoding) per request. With the /notxdetails/ option JSON response will only contain the transaction hash instead of the complete transaction details. The option only affects the JSON response. -For full TX query capability, one must enable the transaction index via "txindex=1" command line / configuration option. +####Blockheaders +`GET /rest/headers/<COUNT>/<BLOCK-HASH>.<bin|hex|json>` + +Given a block hash: returns <COUNT> amount of blockheaders in upward direction. + +####Chaininfos +`GET /rest/chaininfo.json` + +Returns various state info regarding block chain processing. +Only supports JSON as output format. +* chain : (string) current network name as defined in BIP70 (main, test, regtest) +* blocks : (numeric) the current number of blocks processed in the server +* headers : (numeric) the current number of headers we have validated +* bestblockhash : (string) the hash of the currently best block +* difficulty : (numeric) the current difficulty +* verificationprogress : (numeric) estimate of verification progress [0..1] +* chainwork : (string) total amount of work in active chain, in hexadecimal +* pruned : (boolean) if the blocks are subject to pruning +* pruneheight : (numeric) heighest block available +* softforks : (array) status of softforks in progress + +####Query UTXO set +`GET /rest/getutxos/<checkmempool>/<txid>-<n>/<txid>-<n>/.../<txid>-<n>.<bin|hex|json>` + +The getutxo command allows querying of the UTXO set given a set of outpoints. +See BIP64 for input and output serialisation: +https://github.com/bitcoin/bips/blob/master/bip-0064.mediawiki + +Example: +``` +$ curl localhost:18332/rest/getutxos/checkmempool/b2cdfd7b89def827ff8af7cd9bff7627ff72e5e8b0f71210f92ea7a4000c5d75-0.json 2>/dev/null | json_pp +{ + "chaintipHash" : "00000000fb01a7f3745a717f8caebee056c484e6e0bfe4a9591c235bb70506fb", + "chainHeight" : 325347, + "utxos" : [ + { + "scriptPubKey" : { + "addresses" : [ + "mi7as51dvLJsizWnTMurtRmrP8hG2m1XvD" + ], + "type" : "pubkeyhash", + "hex" : "76a9141c7cebb529b86a04c683dfa87be49de35bcf589e88ac", + "reqSigs" : 1, + "asm" : "OP_DUP OP_HASH160 1c7cebb529b86a04c683dfa87be49de35bcf589e OP_EQUALVERIFY OP_CHECKSIG" + }, + "value" : 8.8687, + "height" : 2147483647, + "txvers" : 1 + } + ], + "bitmap" : "1" +} +``` + +####Memory pool +`GET /rest/mempool/info.json` + +Returns various information about the TX mempool. +Only supports JSON as output format. +* size : (numeric) the number of transactions in the TX mempool +* bytes : (numeric) size of the TX mempool in bytes +* usage : (numeric) total TX mempool memory usage + +`GET /rest/mempool/contents.json` + +Returns transactions in the TX mempool. +Only supports JSON as output format. Risks ------------- -Running a webbrowser on the same node with a REST enabled bitcoind can be a risk. Accessing prepared XSS websites could read out tx/block data of your node by placing links like `<script src="http://127.0.0.1:1234/tx/json/1234567890">` which might break the nodes privacy.
\ No newline at end of file +Running a web browser on the same node with a REST enabled bitcoind can be a risk. Accessing prepared XSS websites could read out tx/block data of your node by placing links like `<script src="http://127.0.0.1:8332/rest/tx/1234567890.json">` which might break the nodes privacy. diff --git a/doc/assets-attribution.md b/doc/assets-attribution.md index cd864f254d..2dd930d6a4 100644 --- a/doc/assets-attribution.md +++ b/doc/assets-attribution.md @@ -1,103 +1 @@ -The following is a list of assets used in the bitcoin source and their proper attribution. - -[Wladimir van der Laan](https://github.com/laanwj) ------------------------ -#### Info -* License: MIT - -### Assets Used - src/qt/res/icons/clock*.png, src/qt/res/icons/tx*.png, - src/qt/res/src/clock_green.svg, src/qt/res/src/clock1.svg, - src/qt/res/src/clock2.svg, src/qt/res/src/clock3.svg, - src/qt/res/src/clock4.svg, src/qt/res/src/clock5.svg, - src/qt/res/src/inout.svg, src/qt/res/src/questionmark.svg - -[David Vignoni](http://www.icon-king.com) ------------------------ - -### Info -* Icon Pack: NUVOLA ICON THEME for KDE 3.x -* Designer: David Vignoni (david@icon-king.com) -* License: LGPL -* Site: [http://www.icon-king.com/projects/nuvola](http://www.icon-king.com/projects/nuvola) - -### Assets Used - src/qt/res/icons/address-book.png, src/qt/res/icons/export.png, - src/qt/res/icons/history.png, src/qt/res/icons/key.png, - src/qt/res/icons/lock_*.png, src/qt/res/icons/overview.png, - src/qt/res/icons/receive.png, src/qt/res/icons/send.png, - src/qt/res/icons/synced.png, src/qt/res/icons/filesave.png - -schollidesign ------------------------ - -### Info -* Icon Pack: Human-O2 -* Designer: schollidesign -* License: GNU/GPL -* Site: [http://findicons.com/icon/93743/blocks_gnome_netstatus_0](http://findicons.com/icon/93743/blocks_gnome_netstatus_0) - -### Assets Used - src/qt/res/icons/connect*.png - -md2k7 ------------------------ - -### Info -* Designer: md2k7 -* License: You are free to do with these icons as you wish, including selling, copying, modifying etc. -* License: MIT -* Site: [https://bitcointalk.org/index.php?topic=15276.0](https://bitcointalk.org/index.php?topic=15276.0) - -### Assets Used - src/qt/res/icons/transaction*.png - -[Everaldo.com](http://www.everaldo.com) ------------------------ - -### Info -* Icon Pack: Crystal SVG -* Designer: [http://www.everaldo.com](http://www.everaldo.com) -* License: LGPL - -### Assets Used - src/qt/res/icons/configure.png, src/qt/res/icons/quit.png, - src/qt/res/icons/editcopy.png, src/qt/res/icons/editpaste.png, - src/qt/res/icons/add.png, src/qt/res/icons/edit.png, - src/qt/res/icons/remove.png (edited) - -Everaldo (Everaldo Coelho) ------------------------ - -### Info -* Icon Pack: Kids -* Designer: Everaldo (Everaldo Coelho) -* License: GNU/GPL -* Site: [http://findicons.com/icon/17102/reload?id=17102](http://findicons.com/icon/17102/reload?id=17102) - -### Assets Used - scripts/img/reload.xcf (modified), src/qt/res/movies/*.png - -[Vignoni David](http://techbase.kde.org/Projects/Oxygen) ------------------------ - -### Info -* Designer: Vignoni David -* License: Oxygen icon theme is dual licensed. You may copy it under the Creative Common Attribution-ShareAlike 3.0 License or the GNU Library General Public License. -* Site: [http://techbase.kde.org/Projects/Oxygen](http://techbase.kde.org/Projects/Oxygen) - -### Assets Used - src/qt/res/icons/debugwindow.png - -Jonas Schnelli ------------------------ - -### Info -* Designer: Jonas Schnelli (based on the original bitcoin logo from Bitboy) -* License: MIT - -### Assets Used - src/qt/res/icons/bitcoin.icns, src/qt/res/src/bitcoin.svg, - src/qt/res/src/bitcoin.ico, src/qt/res/src/bitcoin.png, - src/qt/res/src/bitcoin_testnet.png, docs/bitcoin_logo_doxygen.png, - src/qt/res/images/splash.png, src/qt/res/images/splash_testnet.png +The list of assets used in the bitcoin source and their attribution can now be found in [contrib/debian/copyright](../contrib/debian/copyright). diff --git a/doc/benchmarking.md b/doc/benchmarking.md new file mode 100644 index 0000000000..0ba75afcda --- /dev/null +++ b/doc/benchmarking.md @@ -0,0 +1,30 @@ +Benchmarking +============ + +Bitcoin Core has an internal benchmarking framework, with benchmarks +for cryptographic algorithms such as SHA1, SHA256, SHA512 and RIPEMD160. As well as the rolling bloom filter. + +After compiling bitcoin-core, the benchmarks can be run with: +`src/bench/bench_bitcoin` + +The output will look similar to: +``` +#Benchmark,count,min,max,average +RIPEMD160,448,0.001245033173334,0.002638196945190,0.002461894814457 +RollingBloom-refresh,1,0.000635000000000,0.000635000000000,0.000635000000000 +RollingBloom-refresh,1,0.000108000000000,0.000108000000000,0.000108000000000 +RollingBloom-refresh,1,0.000107000000000,0.000107000000000,0.000107000000000 +RollingBloom-refresh,1,0.000204000000000,0.000204000000000,0.000204000000000 +SHA1,640,0.000909024336207,0.001938136418660,0.001843086257577 +SHA256,256,0.002209486499909,0.008500099182129,0.004300644621253 +SHA512,384,0.001319904176016,0.002813005447388,0.002615700786312 +Sleep100ms,10,0.205592155456543,0.210056066513062,0.104166316986084 +Trig,67108864,0.000000014997003,0.000000015448112,0.000000015188842 +``` + +More benchmarks are needed for, in no particular order: +- Script Validation +- CCoinDBView caching +- Coins database +- Memory pool +- Wallet coin selection diff --git a/doc/bips.md b/doc/bips.md new file mode 100644 index 0000000000..039d5114fd --- /dev/null +++ b/doc/bips.md @@ -0,0 +1,29 @@ +BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.13.0**): + +* [`BIP 9`](https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki): The changes allowing multiple soft-forks to be deployed in parallel have been implemented since **v0.12.1** ([PR #7575](https://github.com/bitcoin/bitcoin/pull/7575)) +* [`BIP 11`](https://github.com/bitcoin/bips/blob/master/bip-0011.mediawiki): Multisig outputs are standard since **v0.6.0** ([PR #669](https://github.com/bitcoin/bitcoin/pull/669)). +* [`BIP 13`](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki): The address format for P2SH addresses has been implemented since **v0.6.0** ([PR #669](https://github.com/bitcoin/bitcoin/pull/669)). +* [`BIP 14`](https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki): The subversion string is being used as User Agent since **v0.6.0** ([PR #669](https://github.com/bitcoin/bitcoin/pull/669)). +* [`BIP 16`](https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki): The pay-to-script-hash evaluation rules have been implemented since **v0.6.0**, and took effect on *April 1st 2012* ([PR #748](https://github.com/bitcoin/bitcoin/pull/748)). +* [`BIP 21`](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki): The URI format for Bitcoin payments has been implemented since **v0.6.0** ([PR #176](https://github.com/bitcoin/bitcoin/pull/176)). +* [`BIP 22`](https://github.com/bitcoin/bips/blob/master/bip-0022.mediawiki): The 'getblocktemplate' (GBT) RPC protocol for mining has been implemented since **v0.7.0** ([PR #936](https://github.com/bitcoin/bitcoin/pull/936)). +* [`BIP 23`](https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki): Some extensions to GBT have been implemented since **v0.10.0rc1**, including longpolling and block proposals ([PR #1816](https://github.com/bitcoin/bitcoin/pull/1816)). +* [`BIP 30`](https://github.com/bitcoin/bips/blob/master/bip-0030.mediawiki): The evaluation rules to forbid creating new transactions with the same txid as previous not-fully-spent transactions were implemented since **v0.6.0**, and the rule took effect on *March 15th 2012* ([PR #915](https://github.com/bitcoin/bitcoin/pull/915)). +* [`BIP 31`](https://github.com/bitcoin/bips/blob/master/bip-0031.mediawiki): The 'pong' protocol message (and the protocol version bump to 60001) has been implemented since **v0.6.1** ([PR #1081](https://github.com/bitcoin/bitcoin/pull/1081)). +* [`BIP 32`](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki): Hierarchical Deterministic Wallets has been implemented since **v0.13.0** ([PR #8035](https://github.com/bitcoin/bitcoin/pull/8035)). +* [`BIP 34`](https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki): The rule that requires blocks to contain their height (number) in the coinbase input, and the introduction of version 2 blocks has been implemented since **v0.7.0**. The rule took effect for version 2 blocks as of *block 224413* (March 5th 2013), and version 1 blocks are no longer allowed since *block 227931* (March 25th 2013) ([PR #1526](https://github.com/bitcoin/bitcoin/pull/1526)). +* [`BIP 35`](https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki): The 'mempool' protocol message (and the protocol version bump to 60002) has been implemented since **v0.7.0** ([PR #1641](https://github.com/bitcoin/bitcoin/pull/1641)). +* [`BIP 37`](https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki): The bloom filtering for transaction relaying, partial merkle trees for blocks, and the protocol version bump to 70001 (enabling low-bandwidth SPV clients) has been implemented since **v0.8.0** ([PR #1795](https://github.com/bitcoin/bitcoin/pull/1795)). +* [`BIP 42`](https://github.com/bitcoin/bips/blob/master/bip-0042.mediawiki): The bug that would have caused the subsidy schedule to resume after block 13440000 was fixed in **v0.9.2** ([PR #3842](https://github.com/bitcoin/bitcoin/pull/3842)). +* [`BIP 61`](https://github.com/bitcoin/bips/blob/master/bip-0061.mediawiki): The 'reject' protocol message (and the protocol version bump to 70002) was added in **v0.9.0** ([PR #3185](https://github.com/bitcoin/bitcoin/pull/3185)). +* [`BIP 65`](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki): The CHECKLOCKTIMEVERIFY softfork was merged in **v0.12.0** ([PR #6351](https://github.com/bitcoin/bitcoin/pull/6351)), and backported to **v0.11.2** and **v0.10.4**. Mempool-only CLTV was added in [PR #6124](https://github.com/bitcoin/bitcoin/pull/6124). +* [`BIP 66`](https://github.com/bitcoin/bips/blob/master/bip-0066.mediawiki): The strict DER rules and associated version 3 blocks have been implemented since **v0.10.0** ([PR #5713](https://github.com/bitcoin/bitcoin/pull/5713)). +* [`BIP 68`](https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki): Sequence locks have been implemented as of **v0.12.1** ([PR #7184](https://github.com/bitcoin/bitcoin/pull/7184)), and have been activated since *block 419328*. +* [`BIP 70`](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki) [`71`](https://github.com/bitcoin/bips/blob/master/bip-0071.mediawiki) [`72`](https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki): Payment Protocol support has been available in Bitcoin Core GUI since **v0.9.0** ([PR #5216](https://github.com/bitcoin/bitcoin/pull/5216)). +* [`BIP 111`](https://github.com/bitcoin/bips/blob/master/bip-0111.mediawiki): `NODE_BLOOM` service bit added, and enforced for all peer versions as of **v0.13.0** ([PR #6579](https://github.com/bitcoin/bitcoin/pull/6579) and [PR #6641](https://github.com/bitcoin/bitcoin/pull/6641)). +* [`BIP 112`](https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki): The CHECKSEQUENCEVERIFY opcode has been implemented since **v0.12.1** ([PR #7524](https://github.com/bitcoin/bitcoin/pull/7524)) and has been activated since *block 419328*. +* [`BIP 113`](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki): Median time past lock-time calculations have been implemented since **v0.12.1** ([PR #6566](https://github.com/bitcoin/bitcoin/pull/6566)) and have been activated since *block 419328*. +* [`BIP 125`](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki): Opt-in full replace-by-fee signaling honoured in mempool and mining as of **v0.12.0** ([PR 6871](https://github.com/bitcoin/bitcoin/pull/6871)). +* [`BIP 130`](https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki): direct headers announcement is negotiated with peer versions `>=70012` as of **v0.12.0** ([PR 6494](https://github.com/bitcoin/bitcoin/pull/6494)). +* [`BIP 133`](https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki): feefilter messages are respected and sent for peer versions `>=70013` as of **v0.13.0** ([PR 7542](https://github.com/bitcoin/bitcoin/pull/7542)). +* [`BIP 152`](https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki): Compact block transfer and related optimizations are used as of **v0.13.0** ([PR 8068](https://github.com/bitcoin/bitcoin/pull/8068)). diff --git a/doc/bootstrap.md b/doc/bootstrap.md deleted file mode 100644 index b84fd24b11..0000000000 --- a/doc/bootstrap.md +++ /dev/null @@ -1,56 +0,0 @@ -### Bootstrap the Blockchain Synchronization - -Normally the Bitcoin client will download the transaction and network information, called the blockchain, from the network by syncing with the other clients. This process can take quite some time as the [Bitcoin blockchain](https://blockchain.info/charts/blocks-size) is growing bigger and bigger for each day. Luckily there is a safe and fast way to speed up this process. We'll show you how to bootstrap your blockchain to bring your client up to speed in just a few simple steps. - -### Requirements - -- A fresh install of the Bitcoin client software. - -### Download the blockchain via BitTorrent - -Jeff Garzik, Bitcoin Core developer, offers an [torrent file](https://bitcointalk.org/index.php?topic=145386.0) for bootstrapping purposes that is updated often. BitTorrent is a protocol that speeds up the downloading of large files by using the other clients in the network. Examples of free and safe open source clients are [Deluge](http://deluge-torrent.org/) or [qBittorrent](http://www.qbittorrent.org/). A guide to installing and configuring the torrent clients can be found [here](http://dev.deluge-torrent.org/wiki/UserGuide) for Deluge and [here](http://qbforums.shiki.hu/) for qBittorrent. A further in-depth tutorial on BitTorrent can be found [here](http://www.howtogeek.com/howto/31846/bittorrent-for-beginners-how-get-started-downloading-torrents/). - -With the client installed we'll proceed to download the blockchain torrent file. Use the following magnet link: - - magnet:?xt=urn:btih:2d4e6c1f96c5d5fb260dff92aea4e600227f1aea&dn=bootstrap.dat&tr=udp://tracker.openbittorrent.com:80&tr=udp://tracker.publicbt.com:80&tr=udp://tracker.ccc.de:80&tr=udp://tracker.istole.it:80 - - or go to [Jeff Garzik's topic](https://bitcointalk.org/index.php?topic=145386.0) for a signed magnet link. Alternatively you can use the [.torrent file](http://sourceforge.net/projects/bitcoin/files/Bitcoin/blockchain/bootstrap.dat.torrent/download) found on SourceForge. - - - -The download page should look like this, with a countdown to the download. If it does not work click the direct download link. - -The torrent client installed will recognize the download of the torrent file. Save the bootstrap.dat file to the folder you use for downloads. The image below shows the torrent download in qBittorrent, with current speed and ETA highlighted. - - - -### Importing the blockchain -Exit the Bitcoin client software if you have it running. Be sure not to have an actively used wallet in use. We are going to copy the download of the blockchain to the Bitcoin client data directory. You should run the client software at least once so it can generate the data directory. Copy the downloaded bootstrap.dat file into the Bitcoin data folder. - -**For Windows users:** -Open explorer, and type into the address bar: - - %APPDATA%\Bitcoin - -This will open up the data folder. It should look like the image below. Copy over the bootstrap.dat from your download folder to this directory. - - -**For OSX users:** -Open Finder by pressing Press [shift] + [cmd] + [g] and enter: - - ~/Library/Application Support/Bitcoin/ - -**For Linux users:** -The directory is hidden in your User folder. Go to: - - ~/.bitcoin/ - -### Importing the blockchain -Now start the Bitcoin client software. It should show "Importing blocks from disk" like the image below. - - -Wait until the import finishes. The client will download the last days not covered by the import. Congratulations you have successfully imported the blockchain! - -### Is this safe? - -Yes, the above method is safe. The download contains only raw blockchain data and the client verifies this on import. Do not download the blockchain from unofficial sources, especially if they provide `*.rev` and `*.sst` files. These files are not verified and can contain malicious edits. diff --git a/doc/build-openbsd.md b/doc/build-openbsd.md new file mode 100644 index 0000000000..d923301467 --- /dev/null +++ b/doc/build-openbsd.md @@ -0,0 +1,162 @@ +OpenBSD build guide +====================== +(updated for OpenBSD 5.7) + +This guide describes how to build bitcoind and command-line utilities on OpenBSD. + +As OpenBSD is most common as a server OS, we will not bother with the GUI. + +Preparation +------------- + +Run the following as root to install the base dependencies for building: + +```bash +pkg_add gmake libtool libevent +pkg_add autoconf # (select highest version, e.g. 2.69) +pkg_add automake # (select highest version, e.g. 1.15) +pkg_add python # (select version 2.7.x, not 3.x) +ln -sf /usr/local/bin/python2.7 /usr/local/bin/python2 +``` + +The default C++ compiler that comes with OpenBSD 5.7 is g++ 4.2. This version is old (from 2007), and is not able to compile the current version of Bitcoin Core. It is possible to patch it up to compile, but with the planned transition to C++11 this is a losing battle. So here we will be installing a newer compiler. + +GCC +------- + +You can install a newer version of gcc with: + +```bash +pkg_add g++ # (select newest 4.x version, e.g. 4.9.2) +``` + +This compiler will not overwrite the system compiler, it will be installed as `egcc` and `eg++` in `/usr/local/bin`. + +### Building boost + +Do not use `pkg_add boost`! The boost version installed thus is compiled using the `g++` compiler not `eg++`, which will result in a conflict between `/usr/local/lib/libestdc++.so.XX.0` and `/usr/lib/libstdc++.so.XX.0`, resulting in a test crash: + + test_bitcoin:/usr/lib/libstdc++.so.57.0: /usr/local/lib/libestdc++.so.17.0 : WARNING: symbol(_ZN11__gnu_debug17_S_debug_me ssagesE) size mismatch, relink your program + ... + Segmentation fault (core dumped) + +This makes it necessary to build boost, or at least the parts used by Bitcoin Core, manually: + +``` +# Pick some path to install boost to, here we create a directory within the bitcoin directory +BITCOIN_ROOT=$(pwd) +BOOST_PREFIX="${BITCOIN_ROOT}/boost" +mkdir -p $BOOST_PREFIX + +# Fetch the source and verify that it is not tampered with +wget http://heanet.dl.sourceforge.net/project/boost/boost/1.59.0/boost_1_59_0.tar.bz2 +echo '727a932322d94287b62abb1bd2d41723eec4356a7728909e38adb65ca25241ca boost_1_59_0.tar.bz2' | sha256 -c +# MUST output: (SHA256) boost_1_59_0.tar.bz2: OK +tar -xjf boost_1_59_0.tar.bz2 + +# Boost 1.59 needs two small patches for OpenBSD +cd boost_1_59_0 +# Also here: https://gist.githubusercontent.com/laanwj/bf359281dc319b8ff2e1/raw/92250de8404b97bb99d72ab898f4a8cb35ae1ea3/patch-boost_test_impl_execution_monitor_ipp.patch +patch -p0 < /usr/ports/devel/boost/patches/patch-boost_test_impl_execution_monitor_ipp +# https://github.com/boostorg/filesystem/commit/90517e459681790a091566dce27ca3acabf9a70c +sed 's/__OPEN_BSD__/__OpenBSD__/g' < libs/filesystem/src/path.cpp > libs/filesystem/src/path.cpp.tmp +mv libs/filesystem/src/path.cpp.tmp libs/filesystem/src/path.cpp + +# Build w/ minimum configuration necessary for bitcoin +echo 'using gcc : : eg++ : <cxxflags>"-fvisibility=hidden -fPIC" <linkflags>"" <archiver>"ar" <striper>"strip" <ranlib>"ranlib" <rc>"" : ;' > user-config.jam +config_opts="runtime-link=shared threadapi=pthread threading=multi link=static variant=release --layout=tagged --build-type=complete --user-config=user-config.jam -sNO_BZIP2=1" +./bootstrap.sh --without-icu --with-libraries=chrono,filesystem,program_options,system,thread,test +./b2 -d2 -j2 -d1 ${config_opts} --prefix=${BOOST_PREFIX} stage +./b2 -d0 -j4 ${config_opts} --prefix=${BOOST_PREFIX} install +``` + +### Building BerkeleyDB + +BerkeleyDB is only necessary for the wallet functionality. To skip this, pass `--disable-wallet` to `./configure`. + +See "Berkeley DB" in [build_unix.md](build_unix.md) for instructions on how to build BerkeleyDB 4.8. +You cannot use the BerkeleyDB library from ports, for the same reason as boost above (g++/libstd++ incompatibility). + +```bash +# Pick some path to install BDB to, here we create a directory within the bitcoin directory +BITCOIN_ROOT=$(pwd) +BDB_PREFIX="${BITCOIN_ROOT}/db4" +mkdir -p $BDB_PREFIX + +# Fetch the source and verify that it is not tampered with +wget 'http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz' +echo '12edc0df75bf9abd7f82f821795bcee50f42cb2e5f76a6a281b85732798364ef db-4.8.30.NC.tar.gz' | sha256 -c +# MUST output: (SHA256) db-4.8.30.NC.tar.gz: OK +tar -xzf db-4.8.30.NC.tar.gz + +# Build the library and install to specified prefix +cd db-4.8.30.NC/build_unix/ +# Note: Do a static build so that it can be embedded into the executable, instead of having to find a .so at runtime +../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX CC=egcc CXX=eg++ CPP=ecpp +make install +``` + +### Building Bitcoin Core + +**Important**: use `gmake`, not `make`. The non-GNU `make` will exit with a horrible error. + +Preparation: +```bash +export AUTOCONF_VERSION=2.69 # replace this with the autoconf version that you installed +export AUTOMAKE_VERSION=1.15 # replace this with the automake version that you installed +./autogen.sh +``` +Make sure `BDB_PREFIX` and `BOOST_PREFIX` are set to the appropriate paths from the above steps. + +To configure with wallet: +```bash +./configure --with-gui=no --with-boost=$BOOST_PREFIX \ + CC=egcc CXX=eg++ CPP=ecpp \ + LDFLAGS="-L${BDB_PREFIX}/lib/" CPPFLAGS="-I${BDB_PREFIX}/include/" +``` + +To configure without wallet: +```bash +./configure --disable-wallet --with-gui=no --with-boost=$BOOST_PREFIX \ + CC=egcc CXX=eg++ CPP=ecpp +``` + +Build and run the tests: +```bash +gmake +gmake check +``` + +Clang (not currently working) +------------------------------ + +Using a newer g++ results in linking the new code to a new libstdc++. +Libraries built with the old g++, will still import the old library. +This gives conflicts, necessitating rebuild of all C++ dependencies of the application. + +With clang this can - at least theoretically - be avoided because it uses the +base system's libstdc++. + +```bash +pkg_add llvm boost +``` + +```bash +./configure --disable-wallet --with-gui=no CC=clang CXX=clang++ +gmake +``` + +However, this does not appear to work. Compilation succeeds, but link fails +with many 'local symbol discarded' errors: + + local symbol 150: discarded in section `.text._ZN10tinyformat6detail14FormatIterator6finishEv' from libbitcoin_util.a(libbitcoin_util_a-random.o) + local symbol 151: discarded in section `.text._ZN10tinyformat6detail14FormatIterator21streamStateFromFormatERSoRjPKcii' from libbitcoin_util.a(libbitcoin_util_a-random.o) + local symbol 152: discarded in section `.text._ZN10tinyformat6detail12convertToIntIA13_cLb0EE6invokeERA13_Kc' from libbitcoin_util.a(libbitcoin_util_a-random.o) + +According to similar reported errors this is a binutils (ld) issue in 2.15, the +version installed by OpenBSD 5.7: + +- http://openbsd-archive.7691.n7.nabble.com/UPDATE-cppcheck-1-65-td248900.html +- https://llvm.org/bugs/show_bug.cgi?id=9758 + +There is no known workaround for this. diff --git a/doc/build-osx.md b/doc/build-osx.md index c41820f2b1..c9eb4225ab 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,144 +1,95 @@ Mac OS X Build Instructions and Notes ==================================== -This guide will show you how to build bitcoind(headless client) for OSX. - -Notes ------ - -* Tested on OS X 10.7 through 10.10 on 64-bit Intel processors only. - -* All of the commands should be executed in a Terminal application. The -built-in one is located in `/Applications/Utilities`. +The commands in this guide should be executed in a Terminal application. +The built-in one is located in `/Applications/Utilities/Terminal.app`. Preparation ----------- +Install the OS X command line tools: -You need to install XCode with all the options checked so that the compiler -and everything is available in /usr not just /Developer. XCode should be -available on your OS X installation media, but if not, you can get the -current version from https://developer.apple.com/xcode/. If you install -Xcode 4.3 or later, you'll need to install its command line tools. This can -be done in `Xcode > Preferences > Downloads > Components` and generally must -be re-done or updated every time Xcode is updated. - -There's also an assumption that you already have `git` installed. If -not, it's the path of least resistance to install [Github for Mac](https://mac.github.com/) -(OS X 10.7+) or -[Git for OS X](https://code.google.com/p/git-osx-installer/). It is also -available via Homebrew. +`xcode-select --install` -You will also need to install [Homebrew](http://brew.sh) in order to install library -dependencies. +When the popup appears, click `Install`. -The installation of the actual dependencies is covered in the Instructions -sections below. +Then install [Homebrew](http://brew.sh). -Instructions: Homebrew +Dependencies ---------------------- -#### Install dependencies using Homebrew + brew install automake berkeley-db4 libtool boost --c++11 miniupnpc openssl pkg-config protobuf --c++11 qt5 libevent - brew install autoconf automake libtool boost miniupnpc openssl pkg-config protobuf qt +NOTE: Building with Qt4 is still supported, however, could result in a broken UI. Building with Qt5 is recommended. -#### Installing berkeley-db4 using Homebrew - -The homebrew package for berkeley-db4 has been broken for some time. It will install without Java though. - -Running this command takes you into brew's interactive mode, which allows you to configure, make, and install by hand: -``` -$ brew install https://raw.github.com/mxcl/homebrew/master/Library/Formula/berkeley-db4.rb -–without-java -``` - -The rest of these commands are run inside brew interactive mode: -``` -/private/tmp/berkeley-db4-UGpd0O/db-4.8.30 $ cd .. -/private/tmp/berkeley-db4-UGpd0O $ db-4.8.30/dist/configure --prefix=/usr/local/Cellar/berkeley-db4/4.8.30 --mandir=/usr/local/Cellar/berkeley-db4/4.8.30/share/man --enable-cxx -/private/tmp/berkeley-db4-UGpd0O $ make -/private/tmp/berkeley-db4-UGpd0O $ make install -/private/tmp/berkeley-db4-UGpd0O $ exit -``` - -After exiting, you'll get a warning that the install is keg-only, which means it wasn't symlinked to `/usr/local`. You don't need it to link it to build bitcoin, but if you want to, here's how: - - $ brew link --force berkeley-db4 +Build Bitcoin Core +------------------------ +1. Clone the bitcoin source code and cd into `bitcoin` -### Building `bitcoind` + git clone https://github.com/bitcoin/bitcoin + cd bitcoin -1. Clone the github tree to get the source code and go into the directory. +2. Build bitcoin-core: - git clone https://github.com/bitcoin/bitcoin.git - cd bitcoin + Configure and build the headless bitcoin binaries as well as the GUI (if Qt is found). -2. Build bitcoind: + You can disable the GUI build by passing `--without-gui` to configure. ./autogen.sh ./configure make -3. It is also a good idea to build and run the unit tests: +3. It is recommended to build and run the unit tests: make check -4. (Optional) You can also install bitcoind to your path: +4. You can also create a .dmg that contains the .app bundle (optional): - make install + make deploy -Use Qt Creator as IDE ------------------------- -You can use Qt Creator as IDE, for debugging and for manipulating forms, etc. -Download Qt Creator from http://www.qt.io/download/. Download the "community edition" and only install Qt Creator (uncheck the rest during the installation process). +Running +------- -1. Make sure you installed everything through homebrew mentioned above -2. Do a proper ./configure --with-gui=qt5 --enable-debug -3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project -4. Enter "bitcoin-qt" as project name, enter src/qt as location -5. Leave the file selection as it is -6. Confirm the "summary page" -7. In the "Projects" tab select "Manage Kits..." -8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler -9. Select LLDB as debugger (you might need to set the path to your installtion) -10. Start debugging with Qt Creator +Bitcoin Core is now available at `./src/bitcoind` -Creating a release build ------------------------- -You can ignore this section if you are building `bitcoind` for your own use. +Before running, it's recommended you create an RPC configuration file. -bitcoind/bitcoin-cli binaries are not included in the Bitcoin-Qt.app bundle. + echo -e "rpcuser=bitcoinrpc\nrpcpassword=$(xxd -l 16 -p /dev/urandom)" > "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" -If you are building `bitcoind` or `Bitcoin-Qt` for others, your build machine should be set up -as follows for maximum compatibility: + chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" -All dependencies should be compiled with these flags: +The first time you run bitcoind, it will start downloading the blockchain. This process could take several hours. - -mmacosx-version-min=10.7 - -arch x86_64 - -isysroot $(xcode-select --print-path)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk +You can monitor the download process by looking at the debug.log file: -Once dependencies are compiled, see release-process.md for how the Bitcoin-Qt.app -bundle is packaged and signed to create the .dmg disk image that is distributed. + tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log -Running +Other commands: ------- -It's now available at `./bitcoind`, provided that you are still in the `src` -directory. We have to first create the RPC configuration file, though. - -Run `./bitcoind` to get the filename where it should be put, or just try these -commands: + ./src/bitcoind -daemon # Starts the bitcoin daemon. + ./src/bitcoin-cli --help # Outputs a list of command-line options. + ./src/bitcoin-cli help # Outputs a list of RPC commands when the daemon is running. - echo -e "rpcuser=bitcoinrpc\nrpcpassword=$(xxd -l 16 -p /dev/urandom)" > "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" - chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" +Using Qt Creator as IDE +------------------------ +You can use Qt Creator as an IDE, for bitcoin development. +Download and install the community edition of [Qt Creator](https://www.qt.io/download/). +Uncheck everything except Qt Creator during the installation process. -The next time you run it, it will start downloading the blockchain, but it won't -output anything while it's doing this. This process may take several hours; -you can monitor its process by looking at the debug.log file, like this: +1. Make sure you installed everything through Homebrew mentioned above +2. Do a proper ./configure --enable-debug +3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project +4. Enter "bitcoin-qt" as project name, enter src/qt as location +5. Leave the file selection as it is +6. Confirm the "summary page" +7. In the "Projects" tab select "Manage Kits..." +8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler +9. Select LLDB as debugger (you might need to set the path to your installation) +10. Start debugging with Qt Creator - tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log +Notes +----- -Other commands: -------- +* Tested on OS X 10.7 through 10.11 on 64-bit Intel processors only. - ./bitcoind -daemon # to start the bitcoin daemon. - ./bitcoin-cli --help # for a list of command-line options. - ./bitcoin-cli help # When the daemon is running, to get a list of RPC commands +* Building with downloaded Qt binaries is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714) diff --git a/doc/build-unix.md b/doc/build-unix.md index 8ddee3b757..bd89978cc2 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -1,15 +1,17 @@ UNIX BUILD NOTES ==================== -Some notes on how to build Bitcoin in Unix. +Some notes on how to build Bitcoin Core in Unix. + +(for OpenBSD specific instructions, see [build-openbsd.md](build-openbsd.md)) Note --------------------- Always use absolute paths to configure and compile bitcoin and the dependencies, -for example, when specifying the the path of the dependency: +for example, when specifying the path of the dependency: ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX -Here BDB_PREFIX must absolute path - it is defined using $(pwd) which ensures +Here BDB_PREFIX must be an absolute path - it is defined using $(pwd) which ensures the usage of the absolute path. To Build @@ -31,8 +33,9 @@ These dependencies are required: Library | Purpose | Description ------------|------------------|---------------------- - libssl | SSL Support | Secure communications - libboost | Boost | C++ Library + libssl | Crypto | Random Number Generation, Elliptic Curve Cryptography + libboost | Utility | Library for threading, data structures, etc + libevent | Networking | OS independent asynchronous networking Optional dependencies: @@ -43,69 +46,76 @@ Optional dependencies: qt | GUI | GUI toolkit (only needed when GUI enabled) protobuf | Payments in GUI | Data interchange format used for payment protocol (only needed when GUI enabled) libqrencode | QR codes in GUI | Optional for generating QR codes (only needed when GUI enabled) + univalue | Utility | JSON parsing and encoding (bundled version will be used unless --with-system-univalue passed to configure) + libzmq3 | ZMQ notification | Optional, allows generating ZMQ notifications (requires ZMQ version >= 4.x) For the versions used in the release, see [release-process.md](release-process.md) under *Fetch and build inputs*. -System requirements +Memory Requirements -------------------- -C++ compilers are memory-hungry. It is recommended to have at least 1 GB of -memory available when compiling Bitcoin Core. With 512MB of memory or less -compilation will take much longer due to swap thrashing. +C++ compilers are memory-hungry. It is recommended to have at least 1.5 GB of +memory available when compiling Bitcoin Core. On systems with less, gcc can be +tuned to conserve memory with additional CXXFLAGS: + + + ./configure CXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768" Dependency Build Instructions: Ubuntu & Debian ---------------------------------------------- Build requirements: - sudo apt-get install build-essential libtool autotools-dev autoconf pkg-config libssl-dev - -for Ubuntu 12.04 and later or Debian 7 and later libboost-all-dev has to be installed: + sudo apt-get install build-essential libtool autotools-dev automake pkg-config libssl-dev libevent-dev bsdmainutils - sudo apt-get install libboost-all-dev +Options when installing required Boost library files: - db4.8 packages are available [here](https://launchpad.net/~bitcoin/+archive/bitcoin). - You can add the repository using the following command: +1. On at least Ubuntu 14.04+ and Debian 7+ there are generic names for the +individual boost development packages, so the following can be used to only +install necessary parts of boost: - sudo add-apt-repository ppa:bitcoin/bitcoin - sudo apt-get update + sudo apt-get install libboost-system-dev libboost-filesystem-dev libboost-chrono-dev libboost-program-options-dev libboost-test-dev libboost-thread-dev - Ubuntu 12.04 and later have packages for libdb5.1-dev and libdb5.1++-dev, - but using these will break binary wallet compatibility, and is not recommended. +2. If that doesn't work, you can install all boost development packages with: -for Debian 7 (Wheezy) and later: - The oldstable repository contains db4.8 packages. - Add the following line to /etc/apt/sources.list, - replacing [mirror] with any official debian mirror. + sudo apt-get install libboost-all-dev - deb http://[mirror]/debian/ oldstable main +BerkeleyDB is required for the wallet. db4.8 packages are available [here](https://launchpad.net/~bitcoin/+archive/bitcoin). +You can add the repository and install using the following commands: -To enable the change run + sudo add-apt-repository ppa:bitcoin/bitcoin + sudo apt-get update + sudo apt-get install libdb4.8-dev libdb4.8++-dev - sudo apt-get update +Ubuntu and Debian have their own libdb-dev and libdb++-dev packages, but these will install +BerkeleyDB 5.1 or later, which break binary wallet compatibility with the distributed executables which +are based on BerkeleyDB 4.8. If you do not care about wallet compatibility, +pass `--with-incompatible-bdb` to configure. -for other Debian & Ubuntu (with ppa): - - sudo apt-get install libdb4.8-dev libdb4.8++-dev +See the section "Disable-wallet mode" to build Bitcoin Core without wallet. Optional: - sudo apt-get install libminiupnpc-dev (see --with-miniupnpc and --enable-upnp-default) + sudo apt-get install libminiupnpc-dev (see --with-miniupnpc and --enable-upnp-default) + +ZMQ dependencies: + + sudo apt-get install libzmq3-dev (provides ZMQ API 4.x) Dependencies for the GUI: Ubuntu & Debian ----------------------------------------- If you want to build Bitcoin-Qt, make sure that the required packages for Qt development -are installed. Either Qt 4 or Qt 5 are necessary to build the GUI. -If both Qt 4 and Qt 5 are installed, Qt 4 will be used. Pass `--with-gui=qt5` to configure to choose Qt5. +are installed. Either Qt 5 or Qt 4 are necessary to build the GUI. +If both Qt 4 and Qt 5 are installed, Qt 5 will be used. Pass `--with-gui=qt4` to configure to choose Qt4. To build without GUI pass `--without-gui`. -To build with Qt 4 you need the following: +To build with Qt 5 (recommended) you need the following: - sudo apt-get install libqt4-dev libprotobuf-dev protobuf-compiler + sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler -For Qt 5 you need the following: +Alternatively, to build with Qt 4 you need the following: - sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler + sudo apt-get install libqt4-dev libprotobuf-dev protobuf-compiler libqrencode (optional) can be installed with: @@ -114,6 +124,24 @@ libqrencode (optional) can be installed with: Once these are installed, they will be found by configure and a bitcoin-qt executable will be built by default. +Dependency Build Instructions: Fedora +------------------------------------- +Build requirements: + + sudo dnf install gcc-c++ libtool make autoconf automake openssl-devel libevent-devel boost-devel libdb4-devel libdb4-cxx-devel + +Optional: + + sudo dnf install miniupnpc-devel + +To build with Qt 5 (recommended) you need the following: + + sudo dnf install qt5-qttools-devel qt5-qtbase-devel protobuf-devel + +libqrencode (optional) can be installed with: + + sudo dnf install qrencode-devel + Notes ----- The release is built with GCC and then "strip bitcoind" to strip the debug @@ -131,14 +159,6 @@ turned off by default. See the configure options for upnp behavior desired: --disable-upnp-default (the default) UPnP support turned off by default at runtime --enable-upnp-default UPnP support turned on by default at runtime -To build: - - tar -xzvf miniupnpc-1.6.tar.gz - cd miniupnpc-1.6 - make - sudo su - make install - Berkeley DB ----------- @@ -159,13 +179,14 @@ tar -xzvf db-4.8.30.NC.tar.gz # Build the library and install to our prefix cd db-4.8.30.NC/build_unix/ -# Note: Do a static build so that it can be embedded into the exectuable, instead of having to find a .so at runtime +# Note: Do a static build so that it can be embedded into the executable, instead of having to find a .so at runtime ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX make install # Configure Bitcoin Core to use our own-built instance of BDB cd $BITCOIN_ROOT -./configure (other args...) LDFLAGS="-L${BDB_PREFIX}/lib/" CPPFLAGS="-I${BDB_PREFIX}/include/" +./autogen.sh +./configure LDFLAGS="-L${BDB_PREFIX}/lib/" CPPFLAGS="-I${BDB_PREFIX}/include/" # (other args...) ``` **Note**: You only need Berkeley DB if the wallet is enabled (see the section *Disable-Wallet mode* below). @@ -195,12 +216,12 @@ Hardening enables the following features: * Position Independent Executable Build position independent code to take advantage of Address Space Layout Randomization - offered by some kernels. An attacker who is able to cause execution of code at an arbitrary - memory location is thwarted if he doesn't know where anything useful is located. + offered by some kernels. Attackers who can cause execution of code at an arbitrary memory + location are thwarted if they don't know where anything useful is located. The stack and heap are randomly located by default but this allows the code section to be randomly located as well. - On an Amd64 processor where a library was not compiled with -fPIC, this will cause an error + On an AMD64 processor where a library was not compiled with -fPIC, this will cause an error such as: "relocation R_X86_64_32 against `......' can not be used when making a shared object;" To test that you have built PIE executable, install scanelf, part of paxutils, and use: @@ -208,6 +229,7 @@ Hardening enables the following features: scanelf -e ./bitcoin The output should contain: + TYPE ET_DYN @@ -239,3 +261,49 @@ In this case there is no dependency on Berkeley DB 4.8. Mining is also possible in disable-wallet mode, but only using the `getblocktemplate` RPC call not `getwork`. +Additional Configure Flags +-------------------------- +A list of additional configure flags can be displayed with: + + ./configure --help + + +Setup and Build Example: Arch Linux +----------------------------------- +This example lists the steps necessary to setup and build a command line only, non-wallet distribution of the latest changes on Arch Linux: + + pacman -S git base-devel boost libevent python + git clone https://github.com/bitcoin/bitcoin.git + cd bitcoin/ + ./autogen.sh + ./configure --disable-wallet --without-gui --without-miniupnpc + make check + +Note: +Enabling wallet support requires either compiling against a Berkeley DB newer than 4.8 (package `db`) using `--with-incompatible-bdb`, +or building and depending on a local version of Berkeley DB 4.8. The readily available Arch Linux packages are currently built using +`--with-incompatible-bdb` according to the [PKGBUILD](https://projects.archlinux.org/svntogit/community.git/tree/bitcoin/trunk/PKGBUILD). +As mentioned above, when maintaining portability of the wallet between the standard Bitcoin Core distributions and independently built +node software is desired, Berkeley DB 4.8 must be used. + + +ARM Cross-compilation +------------------- +These steps can be performed on, for example, an Ubuntu VM. The depends system +will also work on other Linux distributions, however the commands for +installing the toolchain will be different. + +First install the toolchain: + + sudo apt-get install g++-arm-linux-gnueabihf + +To build executables for ARM: + + cd depends + make HOST=arm-linux-gnueabihf NO_QT=1 + cd .. + ./configure --prefix=$PWD/depends/arm-linux-gnueabihf --enable-glibc-back-compat --enable-reduce-exports LDFLAGS=-static-libstdc++ + make + + +For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. diff --git a/doc/build-windows.md b/doc/build-windows.md new file mode 100644 index 0000000000..2b9233d1e1 --- /dev/null +++ b/doc/build-windows.md @@ -0,0 +1,40 @@ +WINDOWS BUILD NOTES +==================== + +Some notes on how to build Bitcoin Core for Windows. + +Most developers use cross-compilation from Ubuntu to build executables for +Windows. This is also used to build the release binaries. + +Building on Windows itself is possible (for example using msys / mingw-w64), +but no one documented the steps to do this. If you are doing this, please contribute them. + +Cross-compilation +------------------- + +These steps can be performed on, for example, an Ubuntu VM. The depends system +will also work on other Linux distributions, however the commands for +installing the toolchain will be different. + +First install the toolchains: + + sudo apt-get install g++-mingw-w64-i686 mingw-w64-i686-dev g++-mingw-w64-x86-64 mingw-w64-x86-64-dev + +To build executables for Windows 32-bit: + + cd depends + make HOST=i686-w64-mingw32 -j4 + cd .. + ./configure --prefix=`pwd`/depends/i686-w64-mingw32 + make + +To build executables for Windows 64-bit: + + cd depends + make HOST=x86_64-w64-mingw32 -j4 + cd .. + ./configure --prefix=`pwd`/depends/x86_64-w64-mingw32 + make + +For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. + diff --git a/doc/coding.md b/doc/coding.md deleted file mode 100644 index 43294dbe4c..0000000000 --- a/doc/coding.md +++ /dev/null @@ -1,138 +0,0 @@ -Coding -==================== - -Various coding styles have been used during the history of the codebase, -and the result is not very consistent. However, we're now trying to converge to -a single style, so please use it in new code. Old code will be converted -gradually. -- Basic rules specified in src/.clang-format. Use a recent clang-format-3.5 to format automatically. - - Braces on new lines for namespaces, classes, functions, methods. - - Braces on the same line for everything else. - - 4 space indentation (no tabs) for every block except namespaces. - - No indentation for public/protected/private or for namespaces. - - No extra spaces inside parenthesis; don't do ( this ) - - No space after function names; one space after if, for and while. - -Block style example: -```c++ -namespace foo -{ -class Class -{ - bool Function(char* psz, int n) - { - // Comment summarising what this section of code does - for (int i = 0; i < n; i++) { - // When something fails, return early - if (!Something()) - return false; - ... - } - - // Success return is usually at the end - return true; - } -} -} -``` - -Doxygen comments ------------------ - -To facilitate the generation of documentation, use doxygen-compatible comment blocks for functions, methods and fields. - -For example, to describe a function use: -```c++ -/** - * ... text ... - * @param[in] arg1 A description - * @param[in] arg2 Another argument description - * @pre Precondition for function... - */ -bool function(int arg1, const char *arg2) -``` -A complete list of `@xxx` commands can be found at http://www.stack.nl/~dimitri/doxygen/manual/commands.html. -As Doxygen recognizes the comments by the delimiters (`/**` and `*/` in this case), you don't -*need* to provide any commands for a comment to be valid, just a description text is fine. - -To describe a class use the same construct above the class definition: -```c++ -/** - * Alerts are for notifying old versions if they become too obsolete and - * need to upgrade. The message is displayed in the status bar. - * @see GetWarnings() - */ -class CAlert -{ -``` - -To describe a member or variable use: -```c++ -int var; //!< Detailed description after the member -``` - -Also OK: -```c++ -/// -/// ... text ... -/// -bool function2(int arg1, const char *arg2) -``` - -Not OK (used plenty in the current source, but not picked up): -```c++ -// -// ... text ... -// -``` - -A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html, -but if possible use one of the above styles. - -Locking/mutex usage notes -------------------------- - -The code is multi-threaded, and uses mutexes and the -LOCK/TRY_LOCK macros to protect data structures. - -Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main -and then cs_wallet, while thread 2 locks them in the opposite order: -result, deadlock as each waits for the other to release its lock) are -a problem. Compile with -DDEBUG_LOCKORDER to get lock order -inconsistencies reported in the debug.log file. - -Re-architecting the core code so there are better-defined interfaces -between the various components is a goal, with any necessary locking -done by the components (e.g. see the self-contained CKeyStore class -and its cs_KeyStore lock for example). - -Threads -------- - -- ThreadScriptCheck : Verifies block scripts. - -- ThreadImport : Loads blocks from blk*.dat files or bootstrap.dat. - -- StartNode : Starts other threads. - -- ThreadDNSAddressSeed : Loads addresses of peers from the DNS. - -- ThreadMapPort : Universal plug-and-play startup/shutdown - -- ThreadSocketHandler : Sends/Receives data from peers on port 8333. - -- ThreadOpenAddedConnections : Opens network connections to added nodes. - -- ThreadOpenConnections : Initiates new connections to peers. - -- ThreadMessageHandler : Higher-level message handling (sending and receiving). - -- DumpAddresses : Dumps IP addresses of nodes to peers.dat. - -- ThreadFlushWalletDB : Close the wallet.dat file if it hasn't been used in 500ms. - -- ThreadRPCServer : Remote procedure call handler, listens on port 8332 for connections and services them. - -- BitcoinMiner : Generates bitcoins (if wallet is enabled). - -- Shutdown : Does an orderly shutdown of everything. diff --git a/doc/developer-notes.md b/doc/developer-notes.md new file mode 100644 index 0000000000..95c46b05fe --- /dev/null +++ b/doc/developer-notes.md @@ -0,0 +1,430 @@ +Developer Notes +=============== + +Various coding styles have been used during the history of the codebase, +and the result is not very consistent. However, we're now trying to converge to +a single style, so please use it in new code. Old code will be converted +gradually. +- Basic rules specified in [src/.clang-format](/src/.clang-format). + Use a recent clang-format to format automatically using one of the [dev scripts] + (/contrib/devtools/README.md#clang-formatpy). + - Braces on new lines for namespaces, classes, functions, methods. + - Braces on the same line for everything else. + - 4 space indentation (no tabs) for every block except namespaces. + - No indentation for public/protected/private or for namespaces. + - No extra spaces inside parenthesis; don't do ( this ) + - No space after function names; one space after if, for and while. + +Block style example: +```c++ +namespace foo +{ +class Class +{ + bool Function(char* psz, int n) + { + // Comment summarising what this section of code does + for (int i = 0; i < n; i++) { + // When something fails, return early + if (!Something()) + return false; + ... + } + + // Success return is usually at the end + return true; + } +} +} +``` + +Doxygen comments +----------------- + +To facilitate the generation of documentation, use doxygen-compatible comment blocks for functions, methods and fields. + +For example, to describe a function use: +```c++ +/** + * ... text ... + * @param[in] arg1 A description + * @param[in] arg2 Another argument description + * @pre Precondition for function... + */ +bool function(int arg1, const char *arg2) +``` +A complete list of `@xxx` commands can be found at http://www.stack.nl/~dimitri/doxygen/manual/commands.html. +As Doxygen recognizes the comments by the delimiters (`/**` and `*/` in this case), you don't +*need* to provide any commands for a comment to be valid; just a description text is fine. + +To describe a class use the same construct above the class definition: +```c++ +/** + * Alerts are for notifying old versions if they become too obsolete and + * need to upgrade. The message is displayed in the status bar. + * @see GetWarnings() + */ +class CAlert +{ +``` + +To describe a member or variable use: +```c++ +int var; //!< Detailed description after the member +``` + +or +```cpp +//! Description before the member +int var; +``` + +Also OK: +```c++ +/// +/// ... text ... +/// +bool function2(int arg1, const char *arg2) +``` + +Not OK (used plenty in the current source, but not picked up): +```c++ +// +// ... text ... +// +``` + +A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html, +but if possible use one of the above styles. + +Development tips and tricks +--------------------------- + +**compiling for debugging** + +Run configure with the --enable-debug option, then make. Or run configure with +CXXFLAGS="-g -ggdb -O0" or whatever debug flags you need. + +**debug.log** + +If the code is behaving strangely, take a look in the debug.log file in the data directory; +error and debugging messages are written there. + +The -debug=... command-line option controls debugging; running with just -debug or -debug=1 will turn +on all categories (and give you a very large debug.log file). + +The Qt code routes qDebug() output to debug.log under category "qt": run with -debug=qt +to see it. + +**testnet and regtest modes** + +Run with the -testnet option to run with "play bitcoins" on the test network, if you +are testing multi-machine code that needs to operate across the internet. + +If you are testing something that can run on one machine, run with the -regtest option. +In regression test mode, blocks can be created on-demand; see qa/rpc-tests/ for tests +that run in -regtest mode. + +**DEBUG_LOCKORDER** + +Bitcoin Core is a multithreaded application, and deadlocks or other multithreading bugs +can be very difficult to track down. Compiling with -DDEBUG_LOCKORDER (configure +CXXFLAGS="-DDEBUG_LOCKORDER -g") inserts run-time checks to keep track of which locks +are held, and adds warnings to the debug.log file if inconsistencies are detected. + +Locking/mutex usage notes +------------------------- + +The code is multi-threaded, and uses mutexes and the +LOCK/TRY_LOCK macros to protect data structures. + +Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main +and then cs_wallet, while thread 2 locks them in the opposite order: +result, deadlock as each waits for the other to release its lock) are +a problem. Compile with -DDEBUG_LOCKORDER to get lock order +inconsistencies reported in the debug.log file. + +Re-architecting the core code so there are better-defined interfaces +between the various components is a goal, with any necessary locking +done by the components (e.g. see the self-contained CKeyStore class +and its cs_KeyStore lock for example). + +Threads +------- + +- ThreadScriptCheck : Verifies block scripts. + +- ThreadImport : Loads blocks from blk*.dat files or bootstrap.dat. + +- StartNode : Starts other threads. + +- ThreadDNSAddressSeed : Loads addresses of peers from the DNS. + +- ThreadMapPort : Universal plug-and-play startup/shutdown + +- ThreadSocketHandler : Sends/Receives data from peers on port 8333. + +- ThreadOpenAddedConnections : Opens network connections to added nodes. + +- ThreadOpenConnections : Initiates new connections to peers. + +- ThreadMessageHandler : Higher-level message handling (sending and receiving). + +- DumpAddresses : Dumps IP addresses of nodes to peers.dat. + +- ThreadFlushWalletDB : Close the wallet.dat file if it hasn't been used in 500ms. + +- ThreadRPCServer : Remote procedure call handler, listens on port 8332 for connections and services them. + +- BitcoinMiner : Generates bitcoins (if wallet is enabled). + +- Shutdown : Does an orderly shutdown of everything. + +Ignoring IDE/editor files +-------------------------- + +In closed-source environments in which everyone uses the same IDE it is common +to add temporary files it produces to the project-wide `.gitignore` file. + +However, in open source software such as Bitcoin Core, where everyone uses +their own editors/IDE/tools, it is less common. Only you know what files your +editor produces and this may change from version to version. The canonical way +to do this is thus to create your local gitignore. Add this to `~/.gitconfig`: + +``` +[core] + excludesfile = /home/.../.gitignore_global +``` + +(alternatively, type the command `git config --global core.excludesfile ~/.gitignore_global` +on a terminal) + +Then put your favourite tool's temporary filenames in that file, e.g. +``` +# NetBeans +nbproject/ +``` + +Another option is to create a per-repository excludes file `.git/info/exclude`. +These are not committed but apply only to one repository. + +If a set of tools is used by the build system or scripts the repository (for +example, lcov) it is perfectly acceptable to add its files to `.gitignore` +and commit them. + +Development guidelines +============================ + +A few non-style-related recommendations for developers, as well as points to +pay attention to for reviewers of Bitcoin Core code. + +General Bitcoin Core +---------------------- + +- New features should be exposed on RPC first, then can be made available in the GUI + + - *Rationale*: RPC allows for better automatic testing. The test suite for + the GUI is very limited + +- Make sure pull requests pass Travis CI before merging + + - *Rationale*: Makes sure that they pass thorough testing, and that the tester will keep passing + on the master branch. Otherwise all new pull requests will start failing the tests, resulting in + confusion and mayhem + + - *Explanation*: If the test suite is to be updated for a change, this has to + be done first + +Wallet +------- + +- Make sure that no crashes happen with run-time option `-disablewallet`. + + - *Rationale*: In RPC code that conditionally uses the wallet (such as + `validateaddress`) it is easy to forget that global pointer `pwalletMain` + can be NULL. See `qa/rpc-tests/disablewallet.py` for functional tests + exercising the API with `-disablewallet` + +- Include `db_cxx.h` (BerkeleyDB header) only when `ENABLE_WALLET` is set + + - *Rationale*: Otherwise compilation of the disable-wallet build will fail in environments without BerkeleyDB + +General C++ +------------- + +- Assertions should not have side-effects + + - *Rationale*: Even though the source code is set to to refuse to compile + with assertions disabled, having side-effects in assertions is unexpected and + makes the code harder to understand + +- If you use the `.h`, you must link the `.cpp` + + - *Rationale*: Include files define the interface for the code in implementation files. Including one but + not linking the other is confusing. Please avoid that. Moving functions from + the `.h` to the `.cpp` should not result in build errors + +- Use the RAII (Resource Acquisition Is Initialization) paradigm where possible. For example by using + `unique_ptr` for allocations in a function. + + - *Rationale*: This avoids memory and resource leaks, and ensures exception safety + +C++ data structures +-------------------- + +- Never use the `std::map []` syntax when reading from a map, but instead use `.find()` + + - *Rationale*: `[]` does an insert (of the default element) if the item doesn't + exist in the map yet. This has resulted in memory leaks in the past, as well as + race conditions (expecting read-read behavior). Using `[]` is fine for *writing* to a map + +- Do not compare an iterator from one data structure with an iterator of + another data structure (even if of the same type) + + - *Rationale*: Behavior is undefined. In C++ parlor this means "may reformat + the universe", in practice this has resulted in at least one hard-to-debug crash bug + +- Watch out for out-of-bounds vector access. `&vch[vch.size()]` is illegal, + including `&vch[0]` for an empty vector. Use `vch.data()` and `vch.data() + + vch.size()` instead. + +- Vector bounds checking is only enabled in debug mode. Do not rely on it + +- Make sure that constructors initialize all fields. If this is skipped for a + good reason (i.e., optimization on the critical path), add an explicit + comment about this + + - *Rationale*: Ensure determinism by avoiding accidental use of uninitialized + values. Also, static analyzers balk about this. + +- Use explicitly signed or unsigned `char`s, or even better `uint8_t` and + `int8_t`. Do not use bare `char` unless it is to pass to a third-party API. + This type can be signed or unsigned depending on the architecture, which can + lead to interoperability problems or dangerous conditions such as + out-of-bounds array accesses + +- Prefer explicit constructions over implicit ones that rely on 'magical' C++ behavior + + - *Rationale*: Easier to understand what is happening, thus easier to spot mistakes, even for those + that are not language lawyers + +Strings and formatting +------------------------ + +- Be careful of `LogPrint` versus `LogPrintf`. `LogPrint` takes a `category` argument, `LogPrintf` does not. + + - *Rationale*: Confusion of these can result in runtime exceptions due to + formatting mismatch, and it is easy to get wrong because of subtly similar naming + +- Use `std::string`, avoid C string manipulation functions + + - *Rationale*: C++ string handling is marginally safer, less scope for + buffer overflows and surprises with `\0` characters. Also some C string manipulations + tend to act differently depending on platform, or even the user locale + +- Use `ParseInt32`, `ParseInt64`, `ParseUInt32`, `ParseUInt64`, `ParseDouble` from `utilstrencodings.h` for number parsing + + - *Rationale*: These functions do overflow checking, and avoid pesky locale issues + +- For `strprintf`, `LogPrint`, `LogPrintf` formatting characters don't need size specifiers + + - *Rationale*: Bitcoin Core uses tinyformat, which is type safe. Leave them out to avoid confusion + +Threads and synchronization +---------------------------- + +- Build and run tests with `-DDEBUG_LOCKORDER` to verify that no potential + deadlocks are introduced. As of 0.12, this is defined by default when + configuring with `--enable-debug` + +- When using `LOCK`/`TRY_LOCK` be aware that the lock exists in the context of + the current scope, so surround the statement and the code that needs the lock + with braces + + OK: + +```c++ +{ + TRY_LOCK(cs_vNodes, lockNodes); + ... +} +``` + + Wrong: + +```c++ +TRY_LOCK(cs_vNodes, lockNodes); +{ + ... +} +``` + +Source code organization +-------------------------- + +- Implementation code should go into the `.cpp` file and not the `.h`, unless necessary due to template usage or + when performance due to inlining is critical + + - *Rationale*: Shorter and simpler header files are easier to read, and reduce compile time + +- Don't import anything into the global namespace (`using namespace ...`). Use + fully specified types such as `std::string`. + + - *Rationale*: Avoids symbol conflicts + +GUI +----- + +- Do not display or manipulate dialogs in model code (classes `*Model`) + + - *Rationale*: Model classes pass through events and data from the core, they + should not interact with the user. That's where View classes come in. The converse also + holds: try to not directly access core data structures from Views. + +Git and github tips +--------------------- + +- For resolving merge/rebase conflicts, it can be useful to enable diff3 style using + `git config merge.conflictstyle diff3`. Instead of + + <<< + yours + === + theirs + >>> + + you will see + + <<< + yours + ||| + original + === + theirs + >>> + + This may make it much clearer what caused the conflict. In this style, you can often just look + at what changed between *original* and *theirs*, and mechanically apply that to *yours* (or the other way around). + +- When reviewing patches which change indentation in C++ files, use `git diff -w` and `git show -w`. This makes + the diff algorithm ignore whitespace changes. This feature is also available on github.com, by adding `?w=1` + at the end of any URL which shows a diff. + +- When reviewing patches that change symbol names in many places, use `git diff --word-diff`. This will instead + of showing the patch as deleted/added *lines*, show deleted/added *words*. + +- When reviewing patches that move code around, try using + `git diff --patience commit~:old/file.cpp commit:new/file/name.cpp`, and ignoring everything except the + moved body of code which should show up as neither `+` or `-` lines. In case it was not a pure move, this may + even work when combined with the `-w` or `--word-diff` options described above. + +- When looking at other's pull requests, it may make sense to add the following section to your `.git/config` + file: + + [remote "upstream-pull"] + fetch = +refs/pull/*:refs/remotes/upstream-pull/* + url = git@github.com:bitcoin/bitcoin.git + + This will add an `upstream-pull` remote to your git repository, which can be fetched using `git fetch --all` + or `git fetch upstream-pull`. Afterwards, you can use `upstream-pull/NUMBER/head` in arguments to `git show`, + `git checkout` and anywhere a commit id would be acceptable to see the changes from pull request NUMBER. diff --git a/doc/dnsseed-policy.md b/doc/dnsseed-policy.md index 66a1757ac5..55a5c28258 100644 --- a/doc/dnsseed-policy.md +++ b/doc/dnsseed-policy.md @@ -7,19 +7,17 @@ As such, DNS seeds must be run by entities which have some minimum level of trust within the Bitcoin community. Other implementations of Bitcoin software may also use the same -seeds and may be more exposed. In light of this exposure this -document establishes some basic expectations for the expectations -for the operation of dnsseeds. +seeds and may be more exposed. In light of this exposure, this +document establishes some basic expectations for operating dnsseeds. -0. A DNS seed operating organization or person is expected -to follow good host security practices and maintain control of -their serving infrastructure and not sell or transfer control of their -DNS seed. Any hosting services contracted by the operator are -equally expected to uphold these expectations. +0. A DNS seed operating organization or person is expected to follow good +host security practices, maintain control of applicable infrastructure, +and not sell or transfer control of the DNS seed. Any hosting services +contracted by the operator are equally expected to uphold these expectations. 1. The DNS seed results must consist exclusively of fairly selected and functioning Bitcoin nodes from the public network to the best of the -operators understanding and capability. +operator's understanding and capability. 2. For the avoidance of doubt, the results may be randomized but must not single-out any group of hosts to receive different results unless due to an @@ -29,7 +27,7 @@ urgent technical necessity and disclosed. 4. Any logging of DNS queries should be only that which is necessary for the operation of the service or urgent health of the Bitcoin -network and must not be retained longer than necessary or disclosed +network and must not be retained longer than necessary nor disclosed to any third party. 5. Information gathered as a result of the operators node-spidering @@ -45,7 +43,8 @@ related to the DNS seed operation. If these expectations cannot be satisfied the operator should discontinue providing services and contact the active Bitcoin -Core development team as well as posting on bitcoin-development. +Core development team as well as posting on +[bitcoin-dev](https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev). Behavior outside of these expectations may be reasonable in some situations but should be discussed in public in advance. diff --git a/doc/files.md b/doc/files.md index 80195535bb..f7eca57dcb 100644 --- a/doc/files.md +++ b/doc/files.md @@ -1,12 +1,19 @@ -Used in 0.8.0 ---------------------- -* wallet.dat: personal wallet (BDB) with keys and transactions -* peers.dat: peer IP address database (custom format); since 0.7.0 + +* banlist.dat: stores the IPs/Subnets of banned nodes +* bitcoin.conf: contains configuration settings for bitcoind or bitcoin-qt +* bitcoind.pid: stores the process id of bitcoind while running * blocks/blk000??.dat: block data (custom, 128 MiB per file); since 0.8.0 * blocks/rev000??.dat; block undo data (custom); since 0.8.0 (format changed since pre-0.8) * blocks/index/*; block index (LevelDB); since 0.8.0 * chainstate/*; block chain state database (LevelDB); since 0.8.0 * database/*: BDB database environment; only used for wallet since 0.8.0 +* db.log: wallet database log file +* debug.log: contains debug information and general logging generated by bitcoind or bitcoin-qt +* fee_estimates.dat: stores statistics used to estimate minimum transaction fees and priorities required for confirmation; since 0.10.0 +* peers.dat: peer IP address database (custom format); since 0.7.0 +* wallet.dat: personal wallet (BDB) with keys and transactions +* .cookie: session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0 +* onion_private_key: cached Tor hidden service private key for `-listenonion`: since 0.12.0 Only used in pre-0.8.0 --------------------- diff --git a/doc/gitian-building.md b/doc/gitian-building.md index b356a5d88d..7796a5fc9c 100644 --- a/doc/gitian-building.md +++ b/doc/gitian-building.md @@ -1,11 +1,11 @@ Gitian building ================ -*Setup instructions for a gitian build of Bitcoin using a Debian VM or physical system.* +*Setup instructions for a Gitian build of Bitcoin Core using a Debian VM or physical system.* Gitian is the deterministic build process that is used to build the Bitcoin Core executables. It provides a way to be reasonably sure that the -executables are really built from source on GitHub. It also makes sure that +executables are really built from the source on GitHub. It also makes sure that the same, tested dependencies are used and statically built into the executable. Multiple developers build the source code by following a specific descriptor @@ -13,8 +13,8 @@ Multiple developers build the source code by following a specific descriptor These results are compared and only if they match, the build is accepted and uploaded to bitcoin.org. -More independent gitian builders are needed, which is why I wrote this -guide. It is preferred to follow these steps yourself instead of using someone else's +More independent Gitian builders are needed, which is why this guide exists. +It is preferred you follow these steps yourself instead of using someone else's VM image to avoid 'contaminating' the build. Table of Contents @@ -22,11 +22,11 @@ Table of Contents - [Create a new VirtualBox VM](#create-a-new-virtualbox-vm) - [Connecting to the VM](#connecting-to-the-vm) -- [Setting up Debian for gitian building](#setting-up-debian-for-gitian-building) -- [Installing gitian](#installing-gitian) -- [Setting up gitian images](#setting-up-gitian-images) +- [Setting up Debian for Gitian building](#setting-up-debian-for-gitian-building) +- [Installing Gitian](#installing-gitian) +- [Setting up the Gitian image](#setting-up-the-gitian-image) - [Getting and building the inputs](#getting-and-building-the-inputs) -- [Building Bitcoin](#building-bitcoin) +- [Building Bitcoin Core](#building-bitcoin-core) - [Building an alternative repository](#building-an-alternative-repository) - [Signing externally](#signing-externally) - [Uploading signatures](#uploading-signatures) @@ -39,55 +39,48 @@ This guide explains how to set up the environment, and how to start the builds. Debian Linux was chosen as the host distribution because it has a lightweight install (in contrast to Ubuntu) and is readily available. Any kind of virtualization can be used, for example: -- [VirtualBox](https://www.virtualbox.org/), covered by this guide +- [VirtualBox](https://www.virtualbox.org/) (covered by this guide) - [KVM](http://www.linux-kvm.org/page/Main_Page) - [LXC](https://linuxcontainers.org/), see also [Gitian host docker container](https://github.com/gdm85/tenku/tree/master/docker/gitian-bitcoin-host/README.md). -You can also install on actual hardware instead of using virtualization. +You can also install Gitian on actual hardware instead of using virtualization. Create a new VirtualBox VM --------------------------- -In the VirtualBox GUI click "Create" and choose the following parameters in the wizard: +In the VirtualBox GUI click "New" and choose the following parameters in the wizard: - + -- Type: Linux, Debian (64 bit) +- Type: Linux, Debian (64-bit)  -- Memory Size: at least 1024MB, anything lower will really slow the build down +- Memory Size: at least 1024MB, anything less will really slow down the build. - + -- Hard Drive: Create a virtual hard drive now - - +- Hard Disk: Create a virtual hard disk now -- Hard Drive file type: Use the default, VDI (VirtualBox Disk Image) + - - -- Storage on Physical hard drive: Dynamically Allocated - - +- Hard Disk file type: Use the default, VDI (VirtualBox Disk Image) -- Disk size: at least 40GB; as low as 20GB *may* be possible, but better to err on the safe side -- Push the `Create` button + -Get the [Debian 7.4 net installer](http://ftp.at.debian.org/debian-jigdo/current/amd64/iso-cd/debian-7.4.0-amd64-netinst.iso) (a more recent minor version should also work, see also [Debian Network installation](https://www.debian.org/CD/netinst/)). -This DVD image can be validated using a SHA256 hashing tool, for example on -Unixy OSes by entering the following in a terminal: +- Storage on physical hard disk: Dynamically Allocated - echo "b712a141bc60269db217d3b3e456179bd6b181645f90e4aac9c42ed63de492e9 debian-7.4.0-amd64-netinst.iso" | sha256sum -c - # (must return OK) + + +- File location and size: at least 40GB; as low as 20GB *may* be possible, but better to err on the safe side +- Click `Create` -After creating the VM, we need to configure it. +After creating the VM, we need to configure it. -- Click the `Settings` button, then go to the `Network` tab. Adapter 1 should be attacked to `NAT`. +- Click the `Settings` button, then go to the `Network` tab. Adapter 1 should be attached to `NAT`.  -- Click `Advanced`, then `Port Forwarding`. We want to set up a port through where we can reach the VM to get files in and out. +- Click `Advanced`, then `Port Forwarding`. We want to set up a port through which we can reach the VM to get files in and out. - Create a new rule by clicking the plus icon.  @@ -102,6 +95,13 @@ After creating the VM, we need to configure it. - Click `Ok` twice to save. +Get the [Debian 8.x net installer](http://cdimage.debian.org/debian-cd/8.5.0/amd64/iso-cd/debian-8.5.0-amd64-netinst.iso) (a more recent minor version should also work, see also [Debian Network installation](https://www.debian.org/CD/netinst/)). +This DVD image can be validated using a SHA256 hashing tool, for example on +Unixy OSes by entering the following in a terminal: + + echo "ad4e8c27c561ad8248d5ebc1d36eb172f884057bfeb2c22ead823f59fa8c3dff debian-8.5.0-amd64-netinst.iso" | sha256sum -c + # (must return OK) + Then start the VM. On the first launch you will be asked for a CD or DVD image. Choose the downloaded iso.  @@ -109,14 +109,15 @@ Then start the VM. On the first launch you will be asked for a CD or DVD image. Installing Debian ------------------ -In this section it will be explained how to install Debian on the newly created VM. +This section will explain how to install Debian on the newly created VM. -- Choose the non-graphical installer. We do not need the graphical environment, it will only increase installation time and disk usage. +- Choose the non-graphical installer. We do not need the graphical environment; it will only increase installation time and disk usage.  -**Note**: Navigation in the Debian installer: To keep a setting at the default -and proceed, just press `Enter`. To select a different button, press `Tab`. +**Note**: Navigating in the Debian installer: +To keep a setting at the default and proceed, just press `Enter`. +To select a different button, press `Tab`. - Choose locale and keyboard settings (doesn't matter, you can just go with the defaults or select your own information) @@ -125,99 +126,128 @@ and proceed, just press `Enter`. To select a different button, press `Tab`.  - The VM will detect network settings using DHCP, this should all proceed automatically -- Configure the network: - - System name `debian`. +- Configure the network: + - Hostname `debian`. - Leave domain name empty.  -- Choose a root password and enter it twice (remember it for later) +- Choose a root password and enter it twice (remember it for later)  -- Name the new user `debian` (the full name doesn't matter, you can leave it empty) +- Name the new user `debian` (the full name doesn't matter, you can leave it empty) +- Set the account username as `debian`   -- Choose a user password and enter it twice (remember it for later) +- Choose a user password and enter it twice (remember it for later)  -- The installer will set up the clock using a time server, this process should be automatic +- The installer will set up the clock using a time server; this process should be automatic - Set up the clock: choose a time zone (depends on the locale settings that you picked earlier; specifics don't matter)  - Disk setup - - Partitioning method: Guided - Use the entire disk - + - Partitioning method: Guided - Use the entire disk +  - - Select disk to partition: SCSI1 (0,0,0) + - Select disk to partition: SCSI1 (0,0,0)  - - Partitioning scheme: All files in one partition - - + - Partition Disks -> *All files in one partition* + + - Finish partitioning and write changes to disk -> *Yes* (`Tab`, `Enter` to select the `Yes` button) - +  - The base system will be installed, this will take a minute or so -- Choose a mirror (any will do) +- Choose a mirror (any will do)  -- Enter proxy information (unless you are on an intranet, you can leave this empty) +- Enter proxy information (unless you are on an intranet, leave this empty)  - Wait a bit while 'Select and install software' runs - Participate in popularity contest -> *No* -- Choose software to install. We need just the base system. +- Choose software to install. We need just the base system. +- Make sure only 'SSH server' and 'Standard System Utilities' are checked +- Uncheck 'Debian Desktop Environment' and 'Print Server'  -- Make sure only 'SSH server' and 'Standard System Utilities' are checked -- Uncheck 'Debian Desktop Environment' and 'Print Server' +- Install the GRUB boot loader to the master boot record? -> Yes  -- Install the GRUB boot loader to the master boot record? -> Yes +- Device for boot loader installation -> ata-VBOX_HARDDISK - + - Installation Complete -> *Continue* - After installation, the VM will reboot and you will have a working Debian VM. Congratulations! + + + +After Installation +------------------- +The next step in the guide involves logging in as root via SSH. +SSH login for root users is disabled by default, so we'll enable that now. + +Login to the VM using username `root` and the root password you chose earlier. +You'll be presented with a screen similar to this. + + + +Type: + +``` +sed -i 's/^PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config +``` +and press enter. Then, +``` +/etc/init.d/ssh restart +``` +and enter to restart SSH. Logout by typing 'logout' and pressing 'enter'. + Connecting to the VM ---------------------- After the VM has booted you can connect to it using SSH, and files can be copied from and to the VM using a SFTP utility. Connect to `localhost`, port `22222` (or the port configured when installing the VM). -On Windows you can use putty[1] and WinSCP[2]. +On Windows you can use [putty](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) and [WinSCP](http://winscp.net/eng/index.php). -For example to connect as `root` from a Linux command prompt use +For example, to connect as `root` from a Linux command prompt use $ ssh root@localhost -p 22222 The authenticity of host '[localhost]:22222 ([127.0.0.1]:22222)' can't be established. - ECDSA key fingerprint is 8e:71:f9:5b:62:46:de:44:01:da:fb:5f:34:b5:f2:18. + RSA key fingerprint is ae:f5:c8:9f:17:c6:c7:1b:c2:1b:12:31:1d:bb:d0:c7. Are you sure you want to continue connecting (yes/no)? yes - Warning: Permanently added '[localhost]:22222' (ECDSA) to the list of known hosts. + Warning: Permanently added '[localhost]:22222' (RSA) to the list of known hosts. root@localhost's password: (enter root password configured during install) - Linux debian 3.2.0-4-amd64 #1 SMP Debian 3.2.54-2 x86_64 + + The programs included with the Debian GNU/Linux system are free software; + the exact distribution terms for each program are described in the + individual files in /usr/share/doc/*/copyright. + + Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent + permitted by applicable law. root@debian:~# Replace `root` with `debian` to log in as user. -[1] http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html -[2] http://winscp.net/eng/index.php - -Setting up Debian for gitian building +Setting up Debian for Gitian building -------------------------------------- In this section we will be setting up the Debian installation for Gitian building. @@ -226,25 +256,23 @@ First we need to log in as `root` to set up dependencies and make sure that our user can use the sudo command. Type/paste the following in the terminal: ```bash -apt-get install git ruby sudo apt-cacher-ng qemu-utils debootstrap lxc python-cheetah parted kpartx bridge-utils +apt-get install git ruby sudo apt-cacher-ng qemu-utils debootstrap lxc python-cheetah parted kpartx bridge-utils make ubuntu-archive-keyring curl adduser debian sudo ``` -When you get a colorful screen with a question about the 'LXC directory', just -go with the default (`/var/lib/lxc`). - Then set up LXC and the rest with the following, which is a complex jumble of settings and workarounds: ```bash -# the version of lxc-start in Debian 7.4 needs to run as root, so make sure -# that the build script can exectute it without providing a password +# the version of lxc-start in Debian needs to run as root, so make sure +# that the build script can execute it without providing a password echo "%sudo ALL=NOPASSWD: /usr/bin/lxc-start" > /etc/sudoers.d/gitian-lxc -# add cgroup for LXC -echo "cgroup /sys/fs/cgroup cgroup defaults 0 0" >> /etc/fstab +echo "%sudo ALL=NOPASSWD: /usr/bin/lxc-execute" >> /etc/sudoers.d/gitian-lxc # make /etc/rc.local script that sets up bridge between guest and host echo '#!/bin/sh -e' > /etc/rc.local echo 'brctl addbr br0' >> /etc/rc.local echo 'ifconfig br0 10.0.3.2/24 up' >> /etc/rc.local +echo 'iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE' >> /etc/rc.local +echo 'echo 1 > /proc/sys/net/ipv4/ip_forward' >> /etc/rc.local echo 'exit 0' >> /etc/rc.local # make sure that USE_LXC is always set when logging in as debian, # and configure LXC IP addresses @@ -255,9 +283,9 @@ reboot ``` At the end the VM is rebooted to make sure that the changes take effect. The steps in this -section need only to be performed once. +section only need to be performed once. -Installing gitian +Installing Gitian ------------------ Re-login as the user `debian` that was created during installation. @@ -266,65 +294,62 @@ The rest of the steps in this guide will be performed as that user. There is no `python-vm-builder` package in Debian, so we need to install it from source ourselves, ```bash -wget http://archive.ubuntu.com/ubuntu/pool/universe/v/vm-builder/vm-builder_0.12.4+bzr489.orig.tar.gz -echo "ec12e0070a007989561bfee5862c89a32c301992dd2771c4d5078ef1b3014f03 vm-builder_0.12.4+bzr489.orig.tar.gz" | sha256sum -c +wget http://archive.ubuntu.com/ubuntu/pool/universe/v/vm-builder/vm-builder_0.12.4+bzr494.orig.tar.gz +echo "76cbf8c52c391160b2641e7120dbade5afded713afaa6032f733a261f13e6a8e vm-builder_0.12.4+bzr494.orig.tar.gz" | sha256sum -c # (verification -- must return OK) -tar -zxvf vm-builder_0.12.4+bzr489.orig.tar.gz -cd vm-builder-0.12.4+bzr489 +tar -zxvf vm-builder_0.12.4+bzr494.orig.tar.gz +cd vm-builder-0.12.4+bzr494 sudo python setup.py install cd .. ``` **Note**: When sudo asks for a password, enter the password for the user *debian* not for *root*. -Clone the git repositories for bitcoin and gitian and then checkout the bitcoin version that you want to build. +Clone the git repositories for bitcoin and Gitian. ```bash git clone https://github.com/devrandom/gitian-builder.git git clone https://github.com/bitcoin/bitcoin -cd bitcoin -git checkout v${VERSION} -cd .. +git clone https://github.com/bitcoin-core/gitian.sigs.git ``` -Setting up gitian images +Setting up the Gitian image ------------------------- -Gitian needs virtual images of the operating system to build in. -Currently this is Ubuntu Precise for both x86 architectures. -These images will be copied and used every time that a build is started to +Gitian needs a virtual image of the operating system to build in. +Currently this is Ubuntu Trusty x86_64. +This image will be copied and used every time that a build is started to make sure that the build is deterministic. -Creating the images will take a while, but only has to be done once. +Creating the image will take a while, but only has to be done once. Execute the following as user `debian`: ```bash cd gitian-builder -bin/make-base-vm --lxc --arch i386 --suite precise -bin/make-base-vm --lxc --arch amd64 --suite precise +bin/make-base-vm --lxc --arch amd64 --suite trusty ``` -There will be a lot of warnings printed during build of the images. These can be ignored. +There will be a lot of warnings printed during the build of the image. These can be ignored. **Note**: When sudo asks for a password, enter the password for the user *debian* not for *root*. Getting and building the inputs -------------------------------- -In [doc/release-process.md](release-process.md) in the bitcoin repository under 'Fetch and build inputs'. -you will find a list of `wget` commands that can be executed to get the dependencies. +Follow the instructions in [doc/release-process.md](release-process.md#fetch-and-build-inputs-first-time-or-when-dependency-versions-change) +in the bitcoin repository under 'Fetch and build inputs' to install sources which require +manual intervention. Also optionally follow the next step: 'Seed the Gitian sources cache +and offline git repositories' which will fetch the remaining files required for building +offline. -I needed to add `--no-check-certificate` to the OpenSSL wget line to make it work. -Likely this is because the ca-certificates in Debian 7.4 is fairly old. This does not create a -security issue as the gitian descriptors check the integrity of the input archives and refuse to work -if any one is corrupted. +Building Bitcoin Core +---------------- -After downloading the archives, execute the `gbuild` commands to build the dependencies. -This can take a long time, but only has to be done when the dependencies change, for example -to upgrade the used version. +To build Bitcoin Core (for Linux, OS X and Windows) just follow the steps under 'perform +Gitian builds' in [doc/release-process.md](release-process.md#perform-gitian-builds) in the bitcoin repository. -**Note**: Do not forget to copy the result from `build/out` to `inputs` after every gbuild command! This will save -you a lot of time. +This may take some time as it will build all the dependencies needed for each descriptor. +These dependencies will be cached after a successful build to avoid rebuilding them when possible. At any time you can check the package installation and build progress with @@ -333,22 +358,16 @@ tail -f var/install.log tail -f var/build.log ``` -Building Bitcoin ----------------- - -To build Bitcoin (for Linux, OSX and Windows) just follow the steps under 'perform -gitian builds' in [doc/release-process.md](release-process.md) in the bitcoin repository. - Output from `gbuild` will look something like Initialized empty Git repository in /home/debian/gitian-builder/inputs/bitcoin/.git/ - remote: Reusing existing pack: 35606, done. - remote: Total 35606 (delta 0), reused 0 (delta 0) - Receiving objects: 100% (35606/35606), 26.52 MiB | 4.28 MiB/s, done. - Resolving deltas: 100% (25724/25724), done. + remote: Counting objects: 57959, done. + remote: Total 57959 (delta 0), reused 0 (delta 0), pack-reused 57958 + Receiving objects: 100% (57959/57959), 53.76 MiB | 484.00 KiB/s, done. + Resolving deltas: 100% (41590/41590), done. From https://github.com/bitcoin/bitcoin ... (new tags, new branch etc) - --- Building for precise i386 --- + --- Building for trusty amd64 --- Stopping target if it is up Making a new image copy stdin: is not a tty @@ -363,14 +382,11 @@ Output from `gbuild` will look something like lxc-start: Connection refused - inotify event with no name (mask 32768) Running build script (log in var/build.log) -As when building the dependencies, the progress of package installation and building -can be inspected in `var/install.log` and `var/build.log`. - Building an alternative repository ----------------------------------- If you want to do a test build of a pull on GitHub it can be useful to point -the gitian builder at an alternative repository, using the same descriptors +the Gitian builder at an alternative repository, using the same descriptors and inputs. For example: @@ -382,10 +398,61 @@ COMMIT=2014_03_windows_unicode_path ./bin/gbuild --commit bitcoin=${COMMIT} --url bitcoin=${URL} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml ``` +Building fully offline +----------------------- + +For building fully offline including attaching signatures to unsigned builds, the detached-sigs repository +and the bitcoin git repository with the desired tag must both be available locally, and then gbuild must be +told where to find them. It also requires an apt-cacher-ng which is fully-populated but set to offline mode, or +manually disabling gitian-builder's use of apt-get to update the VM build environment. + +To configure apt-cacher-ng as an offline cacher, you will need to first populate its cache with the relevant +files. You must additionally patch target-bin/bootstrap-fixup to set its apt sources to something other than +plain archive.ubuntu.com: us.archive.ubuntu.com works. + +So, if you use LXC: + +```bash +export PATH="$PATH":/path/to/gitian-builder/libexec +export USE_LXC=1 +cd /path/to/gitian-builder +./libexec/make-clean-vm --suite trusty --arch amd64 + +LXC_ARCH=amd64 LXC_SUITE=trusty on-target -u root apt-get update +LXC_ARCH=amd64 LXC_SUITE=trusty on-target -u root \ + -e DEBIAN_FRONTEND=noninteractive apt-get --no-install-recommends -y install \ + $( sed -ne '/^packages:/,/[^-] .*/ {/^- .*/{s/"//g;s/- //;p}}' ../bitcoin/contrib/gitian-descriptors/*|sort|uniq ) +LXC_ARCH=amd64 LXC_SUITE=trusty on-target -u root apt-get -q -y purge grub +LXC_ARCH=amd64 LXC_SUITE=trusty on-target -u root -e DEBIAN_FRONTEND=noninteractive apt-get -y dist-upgrade +``` + +And then set offline mode for apt-cacher-ng: + +``` +/etc/apt-cacher-ng/acng.conf +[...] +Offlinemode: 1 +[...] + +service apt-cacher-ng restart +``` + +Then when building, override the remote URLs that gbuild would otherwise pull from the Gitian descriptors:: +```bash + +cd /some/root/path/ +git clone https://github.com/bitcoin-core/bitcoin-detached-sigs.git + +BTCPATH=/some/root/path/bitcoin +SIGPATH=/some/root/path/bitcoin-detached-sigs + +./bin/gbuild --url bitcoin=${BTCPATH},signature=${SIGPATH} ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml +``` + Signing externally ------------------- -If you want to do the PGP signing on another device that's also possible; just define `SIGNER` as mentioned +If you want to do the PGP signing on another device, that's also possible; just define `SIGNER` as mentioned and follow the steps in the build process as normal. gpg: skipped "laanwj": secret key not available @@ -394,17 +461,17 @@ When you execute `gsign` you will get an error from GPG, which can be ignored. C in `gitian.sigs` to your signing machine and do ```bash - gpg --detach-sign ${VERSION}-linux/${SIGNER}/bitcoin-build.assert - gpg --detach-sign ${VERSION}-win/${SIGNER}/bitcoin-build.assert - gpg --detach-sign ${VERSION}-osx/${SIGNER}/bitcoin-build.assert + gpg --detach-sign ${VERSION}-linux/${SIGNER}/bitcoin-linux-build.assert + gpg --detach-sign ${VERSION}-win/${SIGNER}/bitcoin-win-build.assert + gpg --detach-sign ${VERSION}-osx-unsigned/${SIGNER}/bitcoin-osx-build.assert ``` This will create the `.sig` files that can be committed together with the `.assert` files to assert your -gitian build. +Gitian build. Uploading signatures --------------------- After building and signing you can push your signatures (both the `.assert` and `.assert.sig` files) to the -[bitcoin/gitian.sigs](https://github.com/bitcoin/gitian.sigs/) repository, or if that's not possible create a pull -request. You can also mail the files to me (laanwj@gmail.com) and I'll commit them. +[bitcoin-core/gitian.sigs](https://github.com/bitcoin-core/gitian.sigs/) repository, or if that's not possible create a pull +request. You can also mail the files to Wladimir (laanwj@gmail.com) and he will commit them. diff --git a/doc/gitian-building/all_files_in_one_partition.png b/doc/gitian-building/all_files_in_one_partition.png Binary files differnew file mode 100644 index 0000000000..8cbb0d8adc --- /dev/null +++ b/doc/gitian-building/all_files_in_one_partition.png diff --git a/doc/gitian-building/create_new_vm.png b/doc/gitian-building/create_new_vm.png Binary files differnew file mode 100644 index 0000000000..dd22428e17 --- /dev/null +++ b/doc/gitian-building/create_new_vm.png diff --git a/doc/gitian-building/create_vm_file_location_size.png b/doc/gitian-building/create_vm_file_location_size.png Binary files differindex 14aef5abae..5f77206b6f 100644 --- a/doc/gitian-building/create_vm_file_location_size.png +++ b/doc/gitian-building/create_vm_file_location_size.png diff --git a/doc/gitian-building/create_vm_hard_disk.png b/doc/gitian-building/create_vm_hard_disk.png Binary files differnew file mode 100644 index 0000000000..8e29816fab --- /dev/null +++ b/doc/gitian-building/create_vm_hard_disk.png diff --git a/doc/gitian-building/create_vm_hard_disk_file_type.png b/doc/gitian-building/create_vm_hard_disk_file_type.png Binary files differnew file mode 100644 index 0000000000..a157211cf5 --- /dev/null +++ b/doc/gitian-building/create_vm_hard_disk_file_type.png diff --git a/doc/gitian-building/create_vm_hard_drive.png b/doc/gitian-building/create_vm_hard_drive.png Binary files differdeleted file mode 100644 index a1706e14fd..0000000000 --- a/doc/gitian-building/create_vm_hard_drive.png +++ /dev/null diff --git a/doc/gitian-building/create_vm_hard_drive_file_type.png b/doc/gitian-building/create_vm_hard_drive_file_type.png Binary files differdeleted file mode 100644 index 251b8ee3e2..0000000000 --- a/doc/gitian-building/create_vm_hard_drive_file_type.png +++ /dev/null diff --git a/doc/gitian-building/create_vm_memsize.png b/doc/gitian-building/create_vm_memsize.png Binary files differindex 33717867a5..5abfee5337 100644 --- a/doc/gitian-building/create_vm_memsize.png +++ b/doc/gitian-building/create_vm_memsize.png diff --git a/doc/gitian-building/create_vm_page1.png b/doc/gitian-building/create_vm_page1.png Binary files differdeleted file mode 100644 index edaebc6223..0000000000 --- a/doc/gitian-building/create_vm_page1.png +++ /dev/null diff --git a/doc/gitian-building/create_vm_storage_physical_hard_disk.png b/doc/gitian-building/create_vm_storage_physical_hard_disk.png Binary files differnew file mode 100644 index 0000000000..cee16a6c63 --- /dev/null +++ b/doc/gitian-building/create_vm_storage_physical_hard_disk.png diff --git a/doc/gitian-building/create_vm_storage_physical_hard_drive.png b/doc/gitian-building/create_vm_storage_physical_hard_drive.png Binary files differdeleted file mode 100644 index 987efaa40c..0000000000 --- a/doc/gitian-building/create_vm_storage_physical_hard_drive.png +++ /dev/null diff --git a/doc/gitian-building/debian_install_10_configure_clock.png b/doc/gitian-building/debian_install_10_configure_clock.png Binary files differindex 467c79018e..7cda038ae4 100644 --- a/doc/gitian-building/debian_install_10_configure_clock.png +++ b/doc/gitian-building/debian_install_10_configure_clock.png diff --git a/doc/gitian-building/debian_install_11_partition_disks.png b/doc/gitian-building/debian_install_11_partition_disks.png Binary files differindex 18110734df..2a648c517f 100644 --- a/doc/gitian-building/debian_install_11_partition_disks.png +++ b/doc/gitian-building/debian_install_11_partition_disks.png diff --git a/doc/gitian-building/debian_install_12_choose_disk.png b/doc/gitian-building/debian_install_12_choose_disk.png Binary files differindex a00d4abf17..0f3acc498e 100644 --- a/doc/gitian-building/debian_install_12_choose_disk.png +++ b/doc/gitian-building/debian_install_12_choose_disk.png diff --git a/doc/gitian-building/debian_install_13_partition_scheme.png b/doc/gitian-building/debian_install_13_partition_scheme.png Binary files differdeleted file mode 100644 index 2f80f19b63..0000000000 --- a/doc/gitian-building/debian_install_13_partition_scheme.png +++ /dev/null diff --git a/doc/gitian-building/debian_install_14_finish.png b/doc/gitian-building/debian_install_14_finish.png Binary files differindex 411d457e95..c8ef0b37ad 100644 --- a/doc/gitian-building/debian_install_14_finish.png +++ b/doc/gitian-building/debian_install_14_finish.png diff --git a/doc/gitian-building/debian_install_15_write_changes.png b/doc/gitian-building/debian_install_15_write_changes.png Binary files differindex f26093982c..d8de00dec6 100644 --- a/doc/gitian-building/debian_install_15_write_changes.png +++ b/doc/gitian-building/debian_install_15_write_changes.png diff --git a/doc/gitian-building/debian_install_16_choose_a_mirror.png b/doc/gitian-building/debian_install_16_choose_a_mirror.png Binary files differindex d2c2e9523b..0bd985b38c 100644 --- a/doc/gitian-building/debian_install_16_choose_a_mirror.png +++ b/doc/gitian-building/debian_install_16_choose_a_mirror.png diff --git a/doc/gitian-building/debian_install_17_choose_a_mirror2.png b/doc/gitian-building/debian_install_17_choose_a_mirror2.png Binary files differdeleted file mode 100644 index cef2db0781..0000000000 --- a/doc/gitian-building/debian_install_17_choose_a_mirror2.png +++ /dev/null diff --git a/doc/gitian-building/debian_install_18_proxy_settings.png b/doc/gitian-building/debian_install_18_proxy_settings.png Binary files differindex 24ba25c109..2c19919f64 100644 --- a/doc/gitian-building/debian_install_18_proxy_settings.png +++ b/doc/gitian-building/debian_install_18_proxy_settings.png diff --git a/doc/gitian-building/debian_install_19_software_selection.png b/doc/gitian-building/debian_install_19_software_selection.png Binary files differindex d462757aff..5430456b14 100644 --- a/doc/gitian-building/debian_install_19_software_selection.png +++ b/doc/gitian-building/debian_install_19_software_selection.png diff --git a/doc/gitian-building/debian_install_1_boot_menu.png b/doc/gitian-building/debian_install_1_boot_menu.png Binary files differindex 27fd849b4f..216502e1c6 100644 --- a/doc/gitian-building/debian_install_1_boot_menu.png +++ b/doc/gitian-building/debian_install_1_boot_menu.png diff --git a/doc/gitian-building/debian_install_20_install_grub.png b/doc/gitian-building/debian_install_20_install_grub.png Binary files differindex de4f9be0c9..d853c15871 100644 --- a/doc/gitian-building/debian_install_20_install_grub.png +++ b/doc/gitian-building/debian_install_20_install_grub.png diff --git a/doc/gitian-building/debian_install_21_install_grub_bootloader.png b/doc/gitian-building/debian_install_21_install_grub_bootloader.png Binary files differnew file mode 100644 index 0000000000..493ab806a6 --- /dev/null +++ b/doc/gitian-building/debian_install_21_install_grub_bootloader.png diff --git a/doc/gitian-building/debian_install_21_finish_installation.png b/doc/gitian-building/debian_install_22_finish_installation.png Binary files differindex b967c3550d..7c4445585b 100644 --- a/doc/gitian-building/debian_install_21_finish_installation.png +++ b/doc/gitian-building/debian_install_22_finish_installation.png diff --git a/doc/gitian-building/debian_install_2_select_a_language.png b/doc/gitian-building/debian_install_2_select_a_language.png Binary files differindex 1c9e0bcfc1..0228ae2c01 100644 --- a/doc/gitian-building/debian_install_2_select_a_language.png +++ b/doc/gitian-building/debian_install_2_select_a_language.png diff --git a/doc/gitian-building/debian_install_3_select_location.png b/doc/gitian-building/debian_install_3_select_location.png Binary files differindex 005c395656..7b18fba975 100644 --- a/doc/gitian-building/debian_install_3_select_location.png +++ b/doc/gitian-building/debian_install_3_select_location.png diff --git a/doc/gitian-building/debian_install_4_configure_keyboard.png b/doc/gitian-building/debian_install_4_configure_keyboard.png Binary files differindex 580c8af7c5..8e46117de4 100644 --- a/doc/gitian-building/debian_install_4_configure_keyboard.png +++ b/doc/gitian-building/debian_install_4_configure_keyboard.png diff --git a/doc/gitian-building/debian_install_5_configure_the_network.png b/doc/gitian-building/debian_install_5_configure_the_network.png Binary files differindex a7fdffc66b..8e3720f243 100644 --- a/doc/gitian-building/debian_install_5_configure_the_network.png +++ b/doc/gitian-building/debian_install_5_configure_the_network.png diff --git a/doc/gitian-building/debian_install_6a_set_up_root_password.png b/doc/gitian-building/debian_install_6a_set_up_root_password.png Binary files differindex 31bd210f38..dcade11967 100644 --- a/doc/gitian-building/debian_install_6a_set_up_root_password.png +++ b/doc/gitian-building/debian_install_6a_set_up_root_password.png diff --git a/doc/gitian-building/debian_install_7_set_up_user_fullname.png b/doc/gitian-building/debian_install_7_set_up_user_fullname.png Binary files differindex bffc6ccd7a..6763c6e08a 100644 --- a/doc/gitian-building/debian_install_7_set_up_user_fullname.png +++ b/doc/gitian-building/debian_install_7_set_up_user_fullname.png diff --git a/doc/gitian-building/debian_install_8_set_up_username.png b/doc/gitian-building/debian_install_8_set_up_username.png Binary files differindex 9e2750ad4e..bb04de96d2 100644 --- a/doc/gitian-building/debian_install_8_set_up_username.png +++ b/doc/gitian-building/debian_install_8_set_up_username.png diff --git a/doc/gitian-building/debian_install_9_user_password.png b/doc/gitian-building/debian_install_9_user_password.png Binary files differindex a26d30cba5..981f1181d7 100644 --- a/doc/gitian-building/debian_install_9_user_password.png +++ b/doc/gitian-building/debian_install_9_user_password.png diff --git a/doc/gitian-building/debian_root_login.png b/doc/gitian-building/debian_root_login.png Binary files differnew file mode 100644 index 0000000000..14cdd5ba5b --- /dev/null +++ b/doc/gitian-building/debian_root_login.png diff --git a/doc/gitian-building/network_settings.png b/doc/gitian-building/network_settings.png Binary files differindex 1d9b6428a7..9e714fd154 100644 --- a/doc/gitian-building/network_settings.png +++ b/doc/gitian-building/network_settings.png diff --git a/doc/gitian-building/port_forwarding_rules.png b/doc/gitian-building/port_forwarding_rules.png Binary files differindex e45c9efffc..9e1fa2af20 100644 --- a/doc/gitian-building/port_forwarding_rules.png +++ b/doc/gitian-building/port_forwarding_rules.png diff --git a/doc/gitian-building/select_startup_disk.png b/doc/gitian-building/select_startup_disk.png Binary files differindex 729b368fd1..59bc093e2c 100644 --- a/doc/gitian-building/select_startup_disk.png +++ b/doc/gitian-building/select_startup_disk.png diff --git a/doc/img/bootstrap1.png b/doc/img/bootstrap1.png Binary files differdeleted file mode 100644 index 075930791b..0000000000 --- a/doc/img/bootstrap1.png +++ /dev/null diff --git a/doc/img/bootstrap2.png b/doc/img/bootstrap2.png Binary files differdeleted file mode 100644 index 6461f81810..0000000000 --- a/doc/img/bootstrap2.png +++ /dev/null diff --git a/doc/img/bootstrap4.png b/doc/img/bootstrap4.png Binary files differdeleted file mode 100644 index ad69737922..0000000000 --- a/doc/img/bootstrap4.png +++ /dev/null diff --git a/doc/img/bootstrap5.png b/doc/img/bootstrap5.png Binary files differdeleted file mode 100644 index d8d9baaf37..0000000000 --- a/doc/img/bootstrap5.png +++ /dev/null diff --git a/doc/init.md b/doc/init.md index 1f0559d806..e3db5b05ef 100644 --- a/doc/init.md +++ b/doc/init.md @@ -8,12 +8,14 @@ can be found in the contrib/init folder. contrib/init/bitcoind.openrc: OpenRC compatible SysV style init script contrib/init/bitcoind.openrcconf: OpenRC conf.d file contrib/init/bitcoind.conf: Upstart service configuration file + contrib/init/bitcoind.init: CentOS compatible SysV style init script 1. Service User --------------------------------- -All three startup configurations assume the existence of a "bitcoin" user +All three Linux startup configurations assume the existence of a "bitcoin" user and group. They must be created before attempting to use these scripts. +The OS X configuration assumes bitcoind will be set up for the current user. 2. Configuration --------------------------------- @@ -28,27 +30,34 @@ file, however it is recommended that a strong and secure password be used as this password is security critical to securing the wallet should the wallet be enabled. -If bitcoind is run with "-daemon" flag, and no rpcpassword is set, it will -print a randomly generated suitable password to stderr. You can also -generate one from the shell yourself like this: +If bitcoind is run with the "-server" flag (set by default), and no rpcpassword is set, +it will use a special cookie file for authentication. The cookie is generated with random +content when the daemon starts, and deleted when it exits. Read access to this file +controls who can access it through RPC. -bash -c 'tr -dc a-zA-Z0-9 < /dev/urandom | head -c32 && echo' +By default the cookie is stored in the data directory, but it's location can be overridden +with the option '-rpccookiefile'. -Once you have a password in hand, set rpcpassword= in /etc/bitcoin/bitcoin.conf +This allows for running bitcoind without having to do any manual configuration. -For an example configuration file that describes the configuration settings, -see contrib/debian/examples/bitcoin.conf. +`conf`, `pid`, and `wallet` accept relative paths which are interpreted as +relative to the data directory. `wallet` *only* supports relative paths. + +For an example configuration file that describes the configuration settings, +see `contrib/debian/examples/bitcoin.conf`. 3. Paths --------------------------------- +3a) Linux + All three configurations assume several paths that might need to be adjusted. -Binary: /usr/bin/bitcoind -Configuration file: /etc/bitcoin/bitcoin.conf -Data directory: /var/lib/bitcoind -PID file: /var/run/bitcoind/bitcoind.pid (OpenRC and Upstart) - /var/lib/bitcoind/bitcoind.pid (systemd) +Binary: `/usr/bin/bitcoind` +Configuration file: `/etc/bitcoin/bitcoin.conf` +Data directory: `/var/lib/bitcoind` +PID file: `/var/run/bitcoind/bitcoind.pid` (OpenRC and Upstart) or `/var/lib/bitcoind/bitcoind.pid` (systemd) +Lock file: `/var/lock/subsys/bitcoind` (CentOS) The configuration file, PID directory (if applicable) and data directory should all be owned by the bitcoin user and group. It is advised for security @@ -56,37 +65,61 @@ reasons to make the configuration file and data directory only readable by the bitcoin user and group. Access to bitcoin-cli and other bitcoind rpc clients can then be controlled by group membership. +3b) Mac OS X + +Binary: `/usr/local/bin/bitcoind` +Configuration file: `~/Library/Application Support/Bitcoin/bitcoin.conf` +Data directory: `~/Library/Application Support/Bitcoin` +Lock file: `~/Library/Application Support/Bitcoin/.lock` + 4. Installing Service Configuration ----------------------------------- 4a) systemd -Installing this .service file consists on just copying it to +Installing this .service file consists of just copying it to /usr/lib/systemd/system directory, followed by the command -"systemctl daemon-reload" in order to update running systemd configuration. +`systemctl daemon-reload` in order to update running systemd configuration. -To test, run "systemctl start bitcoind" and to enable for system startup run -"systemctl enable bitcoind" +To test, run `systemctl start bitcoind` and to enable for system startup run +`systemctl enable bitcoind` 4b) OpenRC Rename bitcoind.openrc to bitcoind and drop it in /etc/init.d. Double check ownership and permissions and make it executable. Test it with -"/etc/init.d/bitcoind start" and configure it to run on startup with -"rc-update add bitcoind" +`/etc/init.d/bitcoind start` and configure it to run on startup with +`rc-update add bitcoind` 4c) Upstart (for Debian/Ubuntu based distributions) -Drop bitcoind.conf in /etc/init. Test by running "service bitcoind start" +Drop bitcoind.conf in /etc/init. Test by running `service bitcoind start` it will automatically start on reboot. NOTE: This script is incompatible with CentOS 5 and Amazon Linux 2014 as they -use old versions of Upstart and do not supply the start-stop-daemon uitility. +use old versions of Upstart and do not supply the start-stop-daemon utility. + +4d) CentOS + +Copy bitcoind.init to /etc/init.d/bitcoind. Test by running `service bitcoind start`. + +Using this script, you can adjust the path and flags to the bitcoind program by +setting the BITCOIND and FLAGS environment variables in the file +/etc/sysconfig/bitcoind. You can also use the DAEMONOPTS environment variable here. + +4e) Mac OS X + +Copy org.bitcoin.bitcoind.plist into ~/Library/LaunchAgents. Load the launch agent by +running `launchctl load ~/Library/LaunchAgents/org.bitcoin.bitcoind.plist`. + +This Launch Agent will cause bitcoind to start whenever the user logs in. + +NOTE: This approach is intended for those wanting to run bitcoind as the current user. +You will need to modify org.bitcoin.bitcoind.plist if you intend to use it as a +Launch Daemon with a dedicated bitcoin user. 5. Auto-respawn ----------------------------------- Auto respawning is currently only configured for Upstart and systemd. Reasonable defaults have been chosen but YMMV. - - diff --git a/doc/reduce-traffic.md b/doc/reduce-traffic.md new file mode 100644 index 0000000000..2d86588eb2 --- /dev/null +++ b/doc/reduce-traffic.md @@ -0,0 +1,38 @@ +Reduce Traffic +============== + +Some node operators need to deal with bandwidth caps imposed by their ISPs. + +By default, bitcoin-core allows up to 125 connections to different peers, 8 of +which are outbound. You can therefore, have at most 117 inbound connections. + +The default settings can result in relatively significant traffic consumption. + +Ways to reduce traffic: + +## 1. Use `-maxuploadtarget=<MiB per day>` + +A major component of the traffic is caused by serving historic blocks to other nodes +during the initial blocks download phase (syncing up a new node). +This option can be specified in MiB per day and is turned off by default. +This is *not* a hard limit; only a threshold to minimize the outbound +traffic. When the limit is about to be reached, the uploaded data is cut by no +longer serving historic blocks (blocks older than one week). +Keep in mind that new nodes require other nodes that are willing to serve +historic blocks. **The recommended minimum is 144 blocks per day (max. 144MB +per day)** + +Whitelisted peers will never be disconnected, although their traffic counts for +calculating the target. + +## 2. Disable "listening" (`-listen=0`) + +Disabling listening will result in fewer nodes connected (remember the maximum of 8 +outbound peers). Fewer nodes will result in less traffic usage as you are relaying +blocks and transactions to fewer nodes. + +## 3. Reduce maximum connections (`-maxconnections=<num>`) + +Reducing the maximum connected nodes to a minimum could be desirable if traffic +limits are tiny. Keep in mind that bitcoin's trustless model works best if you are +connected to a handful of nodes. diff --git a/doc/release-notes.md b/doc/release-notes.md index f804e8c11b..3d2baaaaea 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -1,126 +1,207 @@ (note: this is a temporary file, to be added-to by anybody, and moved to release-notes at release time) -Block file backwards-compatibility warning -=========================================== +Bitcoin Core version *version* is now available from: -Because release 0.10.0 makes use of headers-first synchronization and parallel -block download, the block files and databases are not backwards-compatible -with older versions of Bitcoin Core: + <https://bitcoin.org/bin/bitcoin-core-*version*/> -* Blocks will be stored on disk out of order (in the order they are -received, really), which makes it incompatible with some tools or -other programs. Reindexing using earlier versions will also not work -anymore as a result of this. +This is a new major version release, including new features, various bugfixes +and performance improvements, as well as updated translations. -* The block index database will now hold headers for which no block is -stored on disk, which earlier versions won't support. +Please report bugs using the issue tracker at github: -If you want to be able to downgrade smoothly, make a backup of your entire data -directory. Without this your node will need start syncing (or importing from -bootstrap.dat) anew afterwards. + <https://github.com/bitcoin/bitcoin/issues> -This does not affect wallet forward or backward compatibility. +To receive security and update notifications, please subscribe to: -Transaction fee changes -======================= + <https://bitcoincore.org/en/list/announcements/join/> -This release automatically estimates how high a transaction fee (or how -high a priority) transactions require to be confirmed quickly. The default -settings will create transactions that confirm quickly; see the new -'txconfirmtarget' setting to control the tradeoff between fees and -confirmation times. +Compatibility +============== -Prior releases used hard-coded fees (and priorities), and would -sometimes create transactions that took a very long time to confirm. +Microsoft ended support for Windows XP on [April 8th, 2014](https://www.microsoft.com/en-us/WindowsForBusiness/end-of-xp-support), +an OS initially released in 2001. This means that not even critical security +updates will be released anymore. Without security updates, using a bitcoin +wallet on a XP machine is irresponsible at least. -Statistics used to estimate fees and priorities are saved in the -data directory in the `fee_estimates.dat` file just before -program shutdown, and are read in at startup. +In addition to that, with 0.12.x there have been varied reports of Bitcoin Core +randomly crashing on Windows XP. It is [not clear](https://github.com/bitcoin/bitcoin/issues/7681#issuecomment-217439891) +what the source of these crashes is, but it is likely that upstream +libraries such as Qt are no longer being tested on XP. -New Command Line Options ---------------------------- +We do not have time nor resources to provide support for an OS that is +end-of-life. From 0.13.0 on, Windows XP is no longer supported. Users are +suggested to upgrade to a newer verion of Windows, or install an alternative OS +that is supported. -- `-txconfirmtarget=n` : create transactions that have enough fees (or priority) -so they are likely to confirm within n blocks (default: 1). This setting -is over-ridden by the -paytxfee option. +No attempt is made to prevent installing or running the software on Windows XP, +you can still do so at your own risk, but do not expect it to work: do not +report issues about Windows XP to the issue tracker. -New RPC methods ----------------- +Notable changes +=============== -- `estimatefee nblocks` : Returns approximate fee-per-1,000-bytes needed for -a transaction to be confirmed within nblocks. Returns -1 if not enough -transactions have been observed to compute a good estimate. +Database cache memory increased +-------------------------------- -- `estimatepriority nblocks` : Returns approximate priority needed for -a zero-fee transaction to confirm within nblocks. Returns -1 if not -enough free transactions have been observed to compute a good -estimate. +As a result of growth of the UTXO set, performance with the prior default +database cache of 100 MiB has suffered. +For this reason the default was changed to 300 MiB in this release. -RPC access control changes -========================================== +For nodes on low-memory systems, the database cache can be changed back to +100 MiB (or to another value) by either: -Subnet matching for the purpose of access control is now done -by matching the binary network address, instead of with string wildcard matching. -For the user this means that `-rpcallowip` takes a subnet specification, which can be +- Adding `dbcache=100` in bitcoin.conf +- Changing it in the GUI under `Options → Size of database cache` -- a single IP address (e.g. `1.2.3.4` or `fe80::0012:3456:789a:bcde`) -- a network/CIDR (e.g. `1.2.3.0/24` or `fe80::0000/64`) -- a network/netmask (e.g. `1.2.3.4/255.255.255.0` or `fe80::0012:3456:789a:bcde/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff`) +Note that the database cache setting has the most performance impact +during initial sync of a node, and when catching up after downtime. -An arbitrary number of `-rpcallow` arguments can be given. An incoming connection will be accepted if its origin address -matches one of them. +bitcoin-cli: arguments privacy +-------------------------------- +The RPC command line client gained a new argument, `-stdin` +to read extra arguments from standard input, one per line until EOF/Ctrl-D. For example: -| 0.9.x and before | 0.10.x | -|--------------------------------------------|---------------------------------------| -| `-rpcallowip=192.168.1.1` | `-rpcallowip=192.168.1.1` (unchanged) | -| `-rpcallowip=192.168.1.*` | `-rpcallowip=192.168.1.0/24` | -| `-rpcallowip=192.168.*` | `-rpcallowip=192.168.0.0/16` | -| `-rpcallowip=*` (dangerous!) | `-rpcallowip=::/0` | - -Using wildcards will result in the rule being rejected with the following error in debug.log: - - Error: Invalid -rpcallowip subnet specification: *. Valid are a single IP (e.g. 1.2.3.4), a network/netmask (e.g. 1.2.3.4/255.255.255.0) or a network/CIDR (e.g. 1.2.3.4/24). - -RPC Server "Warm-Up" Mode -========================= - -The RPC server is started earlier now, before most of the expensive -intialisations like loading the block index. It is available now almost -immediately after starting the process. However, until all initialisations -are done, it always returns an immediate error with code -28 to all calls. - -This new behaviour can be useful for clients to know that a server is already -started and will be available soon (for instance, so that they do not -have to start it themselves). - -Improved signing security -========================= - -For 0.10 the security of signing against unusual attacks has been -improved by making the signatures constant time and deterministic. - -This change is a result of switching signing to use libsecp256k1 -instead of OpenSSL. Libsecp256k1 is a cryptographic library -optimized for the curve Bitcoin uses which was created by Bitcoin -Core developer Pieter Wuille. - -There exist attacks[1] against most ECC implementations where an -attacker on shared virtual machine hardware could extract a private -key if they could cause a target to sign using the same key hundreds -of times. While using shared hosts and reusing keys are inadvisable -for other reasons, it's a better practice to avoid the exposure. - -OpenSSL has code in their source repository for derandomization -and reduction in timing leaks, and we've eagerly wanted to use -it for a long time but this functionality has still not made its -way into a released version of OpenSSL. Libsecp256k1 achieves -significantly stronger protection: As far as we're aware this is -the only deployed implementation of constant time signing for -the curve Bitcoin uses and we have reason to believe that -libsecp256k1 is better tested and more thoroughly reviewed -than the implementation in OpenSSL. - -[1] https://eprint.iacr.org/2014/161.pdf + $ echo -e "mysecretcode\n120" | src/bitcoin-cli -stdin walletpassphrase + +It is recommended to use this for sensitive information such as wallet +passphrases, as command-line arguments can usually be read from the process +table by any user on the system. + +RPC low-level changes +---------------------- + +- `gettxoutsetinfo` UTXO hash (`hash_serialized`) has changed. There was a divergence between + 32-bit and 64-bit platforms, and the txids were missing in the hashed data. This has been + fixed, but this means that the output will be different than from previous versions. + +- Full UTF-8 support in the RPC API. Non-ASCII characters in, for example, + wallet labels have always been malformed because they weren't taken into account + properly in JSON RPC processing. This is no longer the case. This also affects + the GUI debug console. + +C++11 and Python 3 +------------------- + +Various code modernizations have been done. The Bitcoin Core code base has +started using C++11. This means that a C++11-capable compiler is now needed for +building. Effectively this means GCC 4.7 or higher, or Clang 3.3 or higher. + +When cross-compiling for a target that doesn't have C++11 libraries, configure with +`./configure --enable-glibc-back-compat ... LDFLAGS=-static-libstdc++`. + +For running the functional tests in `qa/rpc-tests`, Python3.4 or higher is now +required. + +Linux ARM builds +------------------ + +Due to popular request, Linux ARM builds have been added to the uploaded +executables. + +The following extra files can be found in the download directory or torrent: + +- `bitcoin-${VERSION}-arm-linux-gnueabihf.tar.gz`: Linux binaries for the most + common 32-bit ARM architecture. +- `bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz`: Linux binaries for the most + common 64-bit ARM architecture. + +ARM builds are still experimental. If you have problems on a certain device or +Linux distribution combination please report them on the bug tracker, it may be +possible to resolve them. + +Note that Android is not considered ARM Linux in this context. The executables +are not expected to work out of the box on Android. + +0.13.0 Change log +================= + +Detailed release notes follow. This overview includes changes that affect +behavior, not code moves, refactors and string updates. For convenience in locating +the code changes and accompanying discussion, both the pull request and +git merge commit are mentioned. + +### RPC and REST + +Asm script outputs replacements for OP_NOP2 and OP_NOP3 +------------------------------------------------------- + +OP_NOP2 has been renamed to OP_CHECKLOCKTIMEVERIFY by [BIP +65](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki) + +OP_NOP3 has been renamed to OP_CHECKSEQUENCEVERIFY by [BIP +112](https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki) + +The following outputs are affected by this change: +- RPC `getrawtransaction` (in verbose mode) +- RPC `decoderawtransaction` +- RPC `decodescript` +- REST `/rest/tx/` (JSON format) +- REST `/rest/block/` (JSON format when including extended tx details) +- `bitcoin-tx -json` + +New mempool information RPC calls +--------------------------------- + +RPC calls have been added to output detailed statistics for individual mempool +entries, as well as to calculate the in-mempool ancestors or descendants of a +transaction: see `getmempoolentry`, `getmempoolancestors`, `getmempooldescendants`. + +### ZMQ + +Each ZMQ notification now contains an up-counting sequence number that allows +listeners to detect lost notifications. +The sequence number is always the last element in a multi-part ZMQ notification and +therefore backward compatible. +Each message type has its own counter. +(https://github.com/bitcoin/bitcoin/pull/7762) + +### Configuration and command-line options + +### Block and transaction handling + +### P2P protocol and network code + +The p2p alert system has been removed in #7692 and the 'alert' message is no longer supported. + + +Fee filtering of invs (BIP 133) +------------------------------------ + +The optional new p2p message "feefilter" is implemented and the protocol +version is bumped to 70013. Upon receiving a feefilter message from a peer, +a node will not send invs for any transactions which do not meet the filter +feerate. [BIP 133](https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki) + +### Validation + +### Build system + +### Wallet + +Hierarchical Deterministic Key Generation +----------------------------------------- +Newly created wallets will use hierarchical deterministic key generation +according to BIP32 (keypath m/0'/0'/k'). +Existing wallets will still use traditional key generation. + +Backups of HD wallets, regardless of when they have been created, can +therefore be used to re-generate all possible private keys, even the +ones which haven't already been generated during the time of the backup. + +HD key generation for new wallets can be disabled by `-usehd=0`. Keep in +mind that this flag only has affect on newly created wallets. +You can't disable HD key generation once you have created a HD wallet. + +There is no distinction between internal (change) and external keys. + +[Pull request](https://github.com/bitcoin/bitcoin/pull/8035/files), [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) + +### GUI + +### Tests + +### Miscellaneous + diff --git a/doc/release-notes/release-notes-0.10.0.md b/doc/release-notes/release-notes-0.10.0.md new file mode 100644 index 0000000000..986b8832ec --- /dev/null +++ b/doc/release-notes/release-notes-0.10.0.md @@ -0,0 +1,762 @@ +Bitcoin Core version 0.10.0 is now available from: + + https://bitcoin.org/bin/0.10.0/ + +This is a new major version release, bringing both new features and +bug fixes. + +Please report bugs using the issue tracker at github: + + https://github.com/bitcoin/bitcoin/issues + +Upgrading and downgrading +========================= + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Downgrading warning +--------------------- + +Because release 0.10.0 makes use of headers-first synchronization and parallel +block download (see further), the block files and databases are not +backwards-compatible with older versions of Bitcoin Core or other software: + +* Blocks will be stored on disk out of order (in the order they are +received, really), which makes it incompatible with some tools or +other programs. Reindexing using earlier versions will also not work +anymore as a result of this. + +* The block index database will now hold headers for which no block is +stored on disk, which earlier versions won't support. + +If you want to be able to downgrade smoothly, make a backup of your entire data +directory. Without this your node will need start syncing (or importing from +bootstrap.dat) anew afterwards. It is possible that the data from a completely +synchronised 0.10 node may be usable in older versions as-is, but this is not +supported and may break as soon as the older version attempts to reindex. + +This does not affect wallet forward or backward compatibility. + + +Notable changes +=============== + +Faster synchronization +---------------------- + +Bitcoin Core now uses 'headers-first synchronization'. This means that we first +ask peers for block headers (a total of 27 megabytes, as of December 2014) and +validate those. In a second stage, when the headers have been discovered, we +download the blocks. However, as we already know about the whole chain in +advance, the blocks can be downloaded in parallel from all available peers. + +In practice, this means a much faster and more robust synchronization. On +recent hardware with a decent network link, it can be as little as 3 hours +for an initial full synchronization. You may notice a slower progress in the +very first few minutes, when headers are still being fetched and verified, but +it should gain speed afterwards. + +A few RPCs were added/updated as a result of this: +- `getblockchaininfo` now returns the number of validated headers in addition to +the number of validated blocks. +- `getpeerinfo` lists both the number of blocks and headers we know we have in +common with each peer. While synchronizing, the heights of the blocks that we +have requested from peers (but haven't received yet) are also listed as +'inflight'. +- A new RPC `getchaintips` lists all known branches of the block chain, +including those we only have headers for. + +Transaction fee changes +----------------------- + +This release automatically estimates how high a transaction fee (or how +high a priority) transactions require to be confirmed quickly. The default +settings will create transactions that confirm quickly; see the new +'txconfirmtarget' setting to control the tradeoff between fees and +confirmation times. Fees are added by default unless the 'sendfreetransactions' +setting is enabled. + +Prior releases used hard-coded fees (and priorities), and would +sometimes create transactions that took a very long time to confirm. + +Statistics used to estimate fees and priorities are saved in the +data directory in the `fee_estimates.dat` file just before +program shutdown, and are read in at startup. + +New command line options for transaction fee changes: +- `-txconfirmtarget=n` : create transactions that have enough fees (or priority) +so they are likely to begin confirmation within n blocks (default: 1). This setting +is over-ridden by the -paytxfee option. +- `-sendfreetransactions` : Send transactions as zero-fee transactions if possible +(default: 0) + +New RPC commands for fee estimation: +- `estimatefee nblocks` : Returns approximate fee-per-1,000-bytes needed for +a transaction to begin confirmation within nblocks. Returns -1 if not enough +transactions have been observed to compute a good estimate. +- `estimatepriority nblocks` : Returns approximate priority needed for +a zero-fee transaction to begin confirmation within nblocks. Returns -1 if not +enough free transactions have been observed to compute a good +estimate. + +RPC access control changes +-------------------------- + +Subnet matching for the purpose of access control is now done +by matching the binary network address, instead of with string wildcard matching. +For the user this means that `-rpcallowip` takes a subnet specification, which can be + +- a single IP address (e.g. `1.2.3.4` or `fe80::0012:3456:789a:bcde`) +- a network/CIDR (e.g. `1.2.3.0/24` or `fe80::0000/64`) +- a network/netmask (e.g. `1.2.3.4/255.255.255.0` or `fe80::0012:3456:789a:bcde/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff`) + +An arbitrary number of `-rpcallow` arguments can be given. An incoming connection will be accepted if its origin address +matches one of them. + +For example: + +| 0.9.x and before | 0.10.x | +|--------------------------------------------|---------------------------------------| +| `-rpcallowip=192.168.1.1` | `-rpcallowip=192.168.1.1` (unchanged) | +| `-rpcallowip=192.168.1.*` | `-rpcallowip=192.168.1.0/24` | +| `-rpcallowip=192.168.*` | `-rpcallowip=192.168.0.0/16` | +| `-rpcallowip=*` (dangerous!) | `-rpcallowip=::/0` (still dangerous!) | + +Using wildcards will result in the rule being rejected with the following error in debug.log: + + Error: Invalid -rpcallowip subnet specification: *. Valid are a single IP (e.g. 1.2.3.4), a network/netmask (e.g. 1.2.3.4/255.255.255.0) or a network/CIDR (e.g. 1.2.3.4/24). + + +REST interface +-------------- + +A new HTTP API is exposed when running with the `-rest` flag, which allows +unauthenticated access to public node data. + +It is served on the same port as RPC, but does not need a password, and uses +plain HTTP instead of JSON-RPC. + +Assuming a local RPC server running on port 8332, it is possible to request: +- Blocks: http://localhost:8332/rest/block/*HASH*.*EXT* +- Blocks without transactions: http://localhost:8332/rest/block/notxdetails/*HASH*.*EXT* +- Transactions (requires `-txindex`): http://localhost:8332/rest/tx/*HASH*.*EXT* + +In every case, *EXT* can be `bin` (for raw binary data), `hex` (for hex-encoded +binary) or `json`. + +For more details, see the `doc/REST-interface.md` document in the repository. + +RPC Server "Warm-Up" Mode +------------------------- + +The RPC server is started earlier now, before most of the expensive +intialisations like loading the block index. It is available now almost +immediately after starting the process. However, until all initialisations +are done, it always returns an immediate error with code -28 to all calls. + +This new behaviour can be useful for clients to know that a server is already +started and will be available soon (for instance, so that they do not +have to start it themselves). + +Improved signing security +------------------------- + +For 0.10 the security of signing against unusual attacks has been +improved by making the signatures constant time and deterministic. + +This change is a result of switching signing to use libsecp256k1 +instead of OpenSSL. Libsecp256k1 is a cryptographic library +optimized for the curve Bitcoin uses which was created by Bitcoin +Core developer Pieter Wuille. + +There exist attacks[1] against most ECC implementations where an +attacker on shared virtual machine hardware could extract a private +key if they could cause a target to sign using the same key hundreds +of times. While using shared hosts and reusing keys are inadvisable +for other reasons, it's a better practice to avoid the exposure. + +OpenSSL has code in their source repository for derandomization +and reduction in timing leaks that we've eagerly wanted to use for a +long time, but this functionality has still not made its +way into a released version of OpenSSL. Libsecp256k1 achieves +significantly stronger protection: As far as we're aware this is +the only deployed implementation of constant time signing for +the curve Bitcoin uses and we have reason to believe that +libsecp256k1 is better tested and more thoroughly reviewed +than the implementation in OpenSSL. + +[1] https://eprint.iacr.org/2014/161.pdf + +Watch-only wallet support +------------------------- + +The wallet can now track transactions to and from wallets for which you know +all addresses (or scripts), even without the private keys. + +This can be used to track payments without needing the private keys online on a +possibly vulnerable system. In addition, it can help for (manual) construction +of multisig transactions where you are only one of the signers. + +One new RPC, `importaddress`, is added which functions similarly to +`importprivkey`, but instead takes an address or script (in hexadecimal) as +argument. After using it, outputs credited to this address or script are +considered to be received, and transactions consuming these outputs will be +considered to be sent. + +The following RPCs have optional support for watch-only: +`getbalance`, `listreceivedbyaddress`, `listreceivedbyaccount`, +`listtransactions`, `listaccounts`, `listsinceblock`, `gettransaction`. See the +RPC documentation for those methods for more information. + +Compared to using `getrawtransaction`, this mechanism does not require +`-txindex`, scales better, integrates better with the wallet, and is compatible +with future block chain pruning functionality. It does mean that all relevant +addresses need to added to the wallet before the payment, though. + +Consensus library +----------------- + +Starting from 0.10.0, the Bitcoin Core distribution includes a consensus library. + +The purpose of this library is to make the verification functionality that is +critical to Bitcoin's consensus available to other applications, e.g. to language +bindings such as [python-bitcoinlib](https://pypi.python.org/pypi/python-bitcoinlib) or +alternative node implementations. + +This library is called `libbitcoinconsensus.so` (or, `.dll` for Windows). +Its interface is defined in the C header [bitcoinconsensus.h](https://github.com/bitcoin/bitcoin/blob/0.10/src/script/bitcoinconsensus.h). + +In its initial version the API includes two functions: + +- `bitcoinconsensus_verify_script` verifies a script. It returns whether the indicated input of the provided serialized transaction +correctly spends the passed scriptPubKey under additional constraints indicated by flags +- `bitcoinconsensus_version` returns the API version, currently at an experimental `0` + +The functionality is planned to be extended to e.g. UTXO management in upcoming releases, but the interface +for existing methods should remain stable. + +Standard script rules relaxed for P2SH addresses +------------------------------------------------ + +The IsStandard() rules have been almost completely removed for P2SH +redemption scripts, allowing applications to make use of any valid +script type, such as "n-of-m OR y", hash-locked oracle addresses, etc. +While the Bitcoin protocol has always supported these types of script, +actually using them on mainnet has been previously inconvenient as +standard Bitcoin Core nodes wouldn't relay them to miners, nor would +most miners include them in blocks they mined. + +bitcoin-tx +---------- + +It has been observed that many of the RPC functions offered by bitcoind are +"pure functions", and operate independently of the bitcoind wallet. This +included many of the RPC "raw transaction" API functions, such as +createrawtransaction. + +bitcoin-tx is a newly introduced command line utility designed to enable easy +manipulation of bitcoin transactions. A summary of its operation may be +obtained via "bitcoin-tx --help" Transactions may be created or signed in a +manner similar to the RPC raw tx API. Transactions may be updated, deleting +inputs or outputs, or appending new inputs and outputs. Custom scripts may be +easily composed using a simple text notation, borrowed from the bitcoin test +suite. + +This tool may be used for experimenting with new transaction types, signing +multi-party transactions, and many other uses. Long term, the goal is to +deprecate and remove "pure function" RPC API calls, as those do not require a +server round-trip to execute. + +Other utilities "bitcoin-key" and "bitcoin-script" have been proposed, making +key and script operations easily accessible via command line. + +Mining and relay policy enhancements +------------------------------------ + +Bitcoin Core's block templates are now for version 3 blocks only, and any mining +software relying on its `getblocktemplate` must be updated in parallel to use +libblkmaker either version 0.4.2 or any version from 0.5.1 onward. +If you are solo mining, this will affect you the moment you upgrade Bitcoin +Core, which must be done prior to BIP66 achieving its 951/1001 status. +If you are mining with the stratum mining protocol: this does not affect you. +If you are mining with the getblocktemplate protocol to a pool: this will affect +you at the pool operator's discretion, which must be no later than BIP66 +achieving its 951/1001 status. + +The `prioritisetransaction` RPC method has been added to enable miners to +manipulate the priority of transactions on an individual basis. + +Bitcoin Core now supports BIP 22 long polling, so mining software can be +notified immediately of new templates rather than having to poll periodically. + +Support for BIP 23 block proposals is now available in Bitcoin Core's +`getblocktemplate` method. This enables miners to check the basic validity of +their next block before expending work on it, reducing risks of accidental +hardforks or mining invalid blocks. + +Two new options to control mining policy: +- `-datacarrier=0/1` : Relay and mine "data carrier" (OP_RETURN) transactions +if this is 1. +- `-datacarriersize=n` : Maximum size, in bytes, we consider acceptable for +"data carrier" outputs. + +The relay policy has changed to more properly implement the desired behavior of not +relaying free (or very low fee) transactions unless they have a priority above the +AllowFreeThreshold(), in which case they are relayed subject to the rate limiter. + +BIP 66: strict DER encoding for signatures +------------------------------------------ + +Bitcoin Core 0.10 implements BIP 66, which introduces block version 3, and a new +consensus rule, which prohibits non-DER signatures. Such transactions have been +non-standard since Bitcoin v0.8.0 (released in February 2013), but were +technically still permitted inside blocks. + +This change breaks the dependency on OpenSSL's signature parsing, and is +required if implementations would want to remove all of OpenSSL from the +consensus code. + +The same miner-voting mechanism as in BIP 34 is used: when 751 out of a +sequence of 1001 blocks have version number 3 or higher, the new consensus +rule becomes active for those blocks. When 951 out of a sequence of 1001 +blocks have version number 3 or higher, it becomes mandatory for all blocks. + +Backward compatibility with current mining software is NOT provided, thus miners +should read the first paragraph of "Mining and relay policy enhancements" above. + +0.10.0 Change log +================= + +Detailed release notes follow. This overview includes changes that affect external +behavior, not code moves, refactors or string updates. + +RPC: +- `f923c07` Support IPv6 lookup in bitcoin-cli even when IPv6 only bound on localhost +- `b641c9c` Fix addnode "onetry": Connect with OpenNetworkConnection +- `171ca77` estimatefee / estimatepriority RPC methods +- `b750cf1` Remove cli functionality from bitcoind +- `f6984e8` Add "chain" to getmininginfo, improve help in getblockchaininfo +- `99ddc6c` Add nLocalServices info to RPC getinfo +- `cf0c47b` Remove getwork() RPC call +- `2a72d45` prioritisetransaction <txid> <priority delta> <priority tx fee> +- `e44fea5` Add an option `-datacarrier` to allow users to disable relaying/mining data carrier transactions +- `2ec5a3d` Prevent easy RPC memory exhaustion attack +- `d4640d7` Added argument to getbalance to include watchonly addresses and fixed errors in balance calculation +- `83f3543` Added argument to listaccounts to include watchonly addresses +- `952877e` Showing 'involvesWatchonly' property for transactions returned by 'listtransactions' and 'listsinceblock'. It is only appended when the transaction involves a watchonly address +- `d7d5d23` Added argument to listtransactions and listsinceblock to include watchonly addresses +- `f87ba3d` added includeWatchonly argument to 'gettransaction' because it affects balance calculation +- `0fa2f88` added includedWatchonly argument to listreceivedbyaddress/...account +- `6c37f7f` `getrawchangeaddress`: fail when keypool exhausted and wallet locked +- `ff6a7af` getblocktemplate: longpolling support +- `c4a321f` Add peerid to getpeerinfo to allow correlation with the logs +- `1b4568c` Add vout to ListTransactions output +- `b33bd7a` Implement "getchaintips" RPC command to monitor blockchain forks +- `733177e` Remove size limit in RPC client, keep it in server +- `6b5b7cb` Categorize rpc help overview +- `6f2c26a` Closely track mempool byte total. Add "getmempoolinfo" RPC +- `aa82795` Add detailed network info to getnetworkinfo RPC +- `01094bd` Don't reveal whether password is <20 or >20 characters in RPC +- `57153d4` rpc: Compute number of confirmations of a block from block height +- `ff36cbe` getnetworkinfo: export local node's client sub-version string +- `d14d7de` SanitizeString: allow '(' and ')' +- `31d6390` Fixed setaccount accepting foreign address +- `b5ec5fe` update getnetworkinfo help with subversion +- `ad6e601` RPC additions after headers-first +- `33dfbf5` rpc: Fix leveldb iterator leak, and flush before `gettxoutsetinfo` +- `2aa6329` Enable customising node policy for datacarrier data size with a -datacarriersize option +- `f877aaa` submitblock: Use a temporary CValidationState to determine accurately the outcome of ProcessBlock +- `e69a587` submitblock: Support for returning specific rejection reasons +- `af82884` Add "warmup mode" for RPC server +- `e2655e0` Add unauthenticated HTTP REST interface to public blockchain data +- `683dc40` Disable SSLv3 (in favor of TLS) for the RPC client and server +- `44b4c0d` signrawtransaction: validate private key +- `9765a50` Implement BIP 23 Block Proposal +- `f9de17e` Add warning comment to getinfo + +Command-line options: +- `ee21912` Use netmasks instead of wildcards for IP address matching +- `deb3572` Add `-rpcbind` option to allow binding RPC port on a specific interface +- `96b733e` Add `-version` option to get just the version +- `1569353` Add `-stopafterblockimport` option +- `77cbd46` Let -zapwallettxes recover transaction meta data +- `1c750db` remove -tor compatibility code (only allow -onion) +- `4aaa017` rework help messages for fee-related options +- `4278b1d` Clarify error message when invalid -rpcallowip +- `6b407e4` -datadir is now allowed in config files +- `bdd5b58` Add option `-sysperms` to disable 077 umask (create new files with system default umask) +- `cbe39a3` Add "bitcoin-tx" command line utility and supporting modules +- `dbca89b` Trigger -alertnotify if network is upgrading without you +- `ad96e7c` Make -reindex cope with out-of-order blocks +- `16d5194` Skip reindexed blocks individually +- `ec01243` --tracerpc option for regression tests +- `f654f00` Change -genproclimit default to 1 +- `3c77714` Make -proxy set all network types, avoiding a connect leak +- `57be955` Remove -printblock, -printblocktree, and -printblockindex +- `ad3d208` remove -maxorphanblocks config parameter since it is no longer functional + +Block and transaction handling: +- `7a0e84d` ProcessGetData(): abort if a block file is missing from disk +- `8c93bf4` LoadBlockIndexDB(): Require block db reindex if any `blk*.dat` files are missing +- `77339e5` Get rid of the static chainMostWork (optimization) +- `4e0eed8` Allow ActivateBestChain to release its lock on cs_main +- `18e7216` Push cs_mains down in ProcessBlock +- `fa126ef` Avoid undefined behavior using CFlatData in CScript serialization +- `7f3b4e9` Relax IsStandard rules for pay-to-script-hash transactions +- `c9a0918` Add a skiplist to the CBlockIndex structure +- `bc42503` Use unordered_map for CCoinsViewCache with salted hash (optimization) +- `d4d3fbd` Do not flush the cache after every block outside of IBD (optimization) +- `ad08d0b` Bugfix: make CCoinsViewMemPool support pruned entries in underlying cache +- `5734d4d` Only remove actualy failed blocks from setBlockIndexValid +- `d70bc52` Rework block processing benchmark code +- `714a3e6` Only keep setBlockIndexValid entries that are possible improvements +- `ea100c7` Reduce maximum coinscache size during verification (reduce memory usage) +- `4fad8e6` Reject transactions with excessive numbers of sigops +- `b0875eb` Allow BatchWrite to destroy its input, reducing copying (optimization) +- `92bb6f2` Bypass reloading blocks from disk (optimization) +- `2e28031` Perform CVerifyDB on pcoinsdbview instead of pcoinsTip (reduce memory usage) +- `ab15b2e` Avoid copying undo data (optimization) +- `341735e` Headers-first synchronization +- `afc32c5` Fix rebuild-chainstate feature and improve its performance +- `e11b2ce` Fix large reorgs +- `ed6d1a2` Keep information about all block files in memory +- `a48f2d6` Abstract context-dependent block checking from acceptance +- `7e615f5` Fixed mempool sync after sending a transaction +- `51ce901` Improve chainstate/blockindex disk writing policy +- `a206950` Introduce separate flushing modes +- `9ec75c5` Add a locking mechanism to IsInitialBlockDownload to ensure it never goes from false to true +- `868d041` Remove coinbase-dependant transactions during reorg +- `723d12c` Remove txn which are invalidated by coinbase maturity during reorg +- `0cb8763` Check against MANDATORY flags prior to accepting to mempool +- `8446262` Reject headers that build on an invalid parent +- `008138c` Bugfix: only track UTXO modification after lookup + +P2P protocol and network code: +- `f80cffa` Do not trigger a DoS ban if SCRIPT_VERIFY_NULLDUMMY fails +- `c30329a` Add testnet DNS seed of Alex Kotenko +- `45a4baf` Add testnet DNS seed of Andreas Schildbach +- `f1920e8` Ping automatically every 2 minutes (unconditionally) +- `806fd19` Allocate receive buffers in on the fly +- `6ecf3ed` Display unknown commands received +- `aa81564` Track peers' available blocks +- `caf6150` Use async name resolving to improve net thread responsiveness +- `9f4da19` Use pong receive time rather than processing time +- `0127a9b` remove SOCKS4 support from core and GUI, use SOCKS5 +- `40f5cb8` Send rejects and apply DoS scoring for errors in direct block validation +- `dc942e6` Introduce whitelisted peers +- `c994d2e` prevent SOCKET leak in BindListenPort() +- `a60120e` Add built-in seeds for .onion +- `60dc8e4` Allow -onlynet=onion to be used +- `3a56de7` addrman: Do not propagate obviously poor addresses onto the network +- `6050ab6` netbase: Make SOCKS5 negotiation interruptible +- `604ee2a` Remove tx from AlreadyAskedFor list once we receive it, not when we process it +- `efad808` Avoid reject message feedback loops +- `71697f9` Separate protocol versioning from clientversion +- `20a5f61` Don't relay alerts to peers before version negotiation +- `b4ee0bd` Introduce preferred download peers +- `845c86d` Do not use third party services for IP detection +- `12a49ca` Limit the number of new addressses to accumulate +- `35e408f` Regard connection failures as attempt for addrman +- `a3a7317` Introduce 10 minute block download timeout +- `3022e7d` Require sufficent priority for relay of free transactions +- `58fda4d` Update seed IPs, based on bitcoin.sipa.be crawler data +- `18021d0` Remove bitnodes.io from dnsseeds. + +Validation: +- `6fd7ef2` Also switch the (unused) verification code to low-s instead of even-s +- `584a358` Do merkle root and txid duplicates check simultaneously +- `217a5c9` When transaction outputs exceed inputs, show the offending amounts so as to aid debugging +- `f74fc9b` Print input index when signature validation fails, to aid debugging +- `6fd59ee` script.h: set_vch() should shift a >32 bit value +- `d752ba8` Add SCRIPT_VERIFY_SIGPUSHONLY (BIP62 rule 2) (test only) +- `698c6ab` Add SCRIPT_VERIFY_MINIMALDATA (BIP62 rules 3 and 4) (test only) +- `ab9edbd` script: create sane error return codes for script validation and remove logging +- `219a147` script: check ScriptError values in script tests +- `0391423` Discourage NOPs reserved for soft-fork upgrades +- `98b135f` Make STRICTENC invalid pubkeys fail the script rather than the opcode +- `307f7d4` Report script evaluation failures in log and reject messages +- `ace39db` consensus: guard against openssl's new strict DER checks +- `12b7c44` Improve robustness of DER recoding code +- `76ce5c8` fail immediately on an empty signature + +Build system: +- `f25e3ad` Fix build in OS X 10.9 +- `65e8ba4` build: Switch to non-recursive make +- `460b32d` build: fix broken boost chrono check on some platforms +- `9ce0774` build: Fix windows configure when using --with-qt-libdir +- `ea96475` build: Add mention of --disable-wallet to bdb48 error messages +- `1dec09b` depends: add shared dependency builder +- `c101c76` build: Add --with-utils (bitcoin-cli and bitcoin-tx, default=yes). Help string consistency tweaks. Target sanity check fix +- `e432a5f` build: add option for reducing exports (v2) +- `6134b43` Fixing condition 'sabotaging' MSVC build +- `af0bd5e` osx: fix signing to make Gatekeeper happy (again) +- `a7d1f03` build: fix dynamic boost check when --with-boost= is used +- `d5fd094` build: fix qt test build when libprotobuf is in a non-standard path +- `2cf5f16` Add libbitcoinconsensus library +- `914868a` build: add a deterministic dmg signer +- `2d375fe` depends: bump openssl to 1.0.1k +- `b7a4ecc` Build: Only check for boost when building code that requires it + +Wallet: +- `b33d1f5` Use fee/priority estimates in wallet CreateTransaction +- `4b7b1bb` Sanity checks for estimates +- `c898846` Add support for watch-only addresses +- `d5087d1` Use script matching rather than destination matching for watch-only +- `d88af56` Fee fixes +- `a35b55b` Dont run full check every time we decrypt wallet +- `3a7c348` Fix make_change to not create half-satoshis +- `f606bb9` fix a possible memory leak in CWalletDB::Recover +- `870da77` fix possible memory leaks in CWallet::EncryptWallet +- `ccca27a` Watch-only fixes +- `9b1627d` [Wallet] Reduce minTxFee for transaction creation to 1000 satoshis +- `a53fd41` Deterministic signing +- `15ad0b5` Apply AreSane() checks to the fees from the network +- `11855c1` Enforce minRelayTxFee on wallet created tx and add a maxtxfee option + +GUI: +- `c21c74b` osx: Fix missing dock menu with qt5 +- `b90711c` Fix Transaction details shows wrong To: +- `516053c` Make links in 'About Bitcoin Core' clickable +- `bdc83e8` Ensure payment request network matches client network +- `65f78a1` Add GUI view of peer information +- `06a91d9` VerifyDB progress reporting +- `fe6bff2` Add BerkeleyDB version info to RPCConsole +- `b917555` PeerTableModel: Fix potential deadlock. #4296 +- `dff0e3b` Improve rpc console history behavior +- `95a9383` Remove CENT-fee-rule from coin control completely +- `56b07d2` Allow setting listen via GUI +- `d95ba75` Log messages with type>QtDebugMsg as non-debug +- `8969828` New status bar Unit Display Control and related changes +- `674c070` seed OpenSSL PNRG with Windows event data +- `509f926` Payment request parsing on startup now only changes network if a valid network name is specified +- `acd432b` Prevent balloon-spam after rescan +- `7007402` Implement SI-style (thin space) thoudands separator +- `91cce17` Use fixed-point arithmetic in amount spinbox +- `bdba2dd` Remove an obscure option no-one cares about +- `bd0aa10` Replace the temporary file hack currently used to change Bitcoin-Qt's dock icon (OS X) with a buffer-based solution +- `94e1b9e` Re-work overviewpage UI +- `8bfdc9a` Better looking trayicon +- `b197bf3` disable tray interactions when client model set to 0 +- `1c5f0af` Add column Watch-only to transactions list +- `21f139b` Fix tablet crash. closes #4854 +- `e84843c` Broken addresses on command line no longer trigger testnet +- `a49f11d` Change splash screen to normal window +- `1f9be98` Disable App Nap on OSX 10.9+ +- `27c3e91` Add proxy to options overridden if necessary +- `4bd1185` Allow "emergency" shutdown during startup +- `d52f072` Don't show wallet options in the preferences menu when running with -disablewallet +- `6093aa1` Qt: QProgressBar CPU-Issue workaround +- `0ed9675` [Wallet] Add global boolean whether to send free transactions (default=true) +- `ed3e5e4` [Wallet] Add global boolean whether to pay at least the custom fee (default=true) +- `e7876b2` [Wallet] Prevent user from paying a non-sense fee +- `c1c9d5b` Add Smartfee to GUI +- `e0a25c5` Make askpassphrase dialog behave more sanely +- `94b362d` On close of splashscreen interrupt verifyDB +- `b790d13` English translation update +- `8543b0d` Correct tooltip on address book page + +Tests: +- `b41e594` Fix script test handling of empty scripts +- `d3a33fc` Test CHECKMULTISIG with m == 0 and n == 0 +- `29c1749` Let tx (in)valid tests use any SCRIPT_VERIFY flag +- `6380180` Add rejection of non-null CHECKMULTISIG dummy values +- `21bf3d2` Add tests for BoostAsioToCNetAddr +- `b5ad5e7` Add Python test for -rpcbind and -rpcallowip +- `9ec0306` Add CODESEPARATOR/FindAndDelete() tests +- `75ebced` Added many rpc wallet tests +- `0193fb8` Allow multiple regression tests to run at once +- `92a6220` Hook up sanity checks +- `3820e01` Extend and move all crypto tests to crypto_tests.cpp +- `3f9a019` added list/get received by address/ account tests +- `a90689f` Remove timing-based signature cache unit test +- `236982c` Add skiplist unit tests +- `f4b00be` Add CChain::GetLocator() unit test +- `b45a6e8` Add test for getblocktemplate longpolling +- `cdf305e` Set -discover=0 in regtest framework +- `ed02282` additional test for OP_SIZE in script_valid.json +- `0072d98` script tests: BOOLAND, BOOLOR decode to integer +- `833ff16` script tests: values that overflow to 0 are true +- `4cac5db` script tests: value with trailing 0x00 is true +- `89101c6` script test: test case for 5-byte bools +- `d2d9dc0` script tests: add tests for CHECKMULTISIG limits +- `d789386` Add "it works" test for bitcoin-tx +- `df4d61e` Add bitcoin-tx tests +- `aa41ac2` Test IsPushOnly() with invalid push +- `6022b5d` Make `script_{valid,invalid}.json` validation flags configurable +- `8138cbe` Add automatic script test generation, and actual checksig tests +- `ed27e53` Add coins_tests with a large randomized CCoinViewCache test +- `9df9cf5` Make SCRIPT_VERIFY_STRICTENC compatible with BIP62 +- `dcb9846` Extend getchaintips RPC test +- `554147a` Ensure MINIMALDATA invalid tests can only fail one way +- `dfeec18` Test every numeric-accepting opcode for correct handling of the numeric minimal encoding rule +- `2b62e17` Clearly separate PUSHDATA and numeric argument MINIMALDATA tests +- `16d78bd` Add valid invert of invalid every numeric opcode tests +- `f635269` tests: enable alertnotify test for Windows +- `7a41614` tests: allow rpc-tests to get filenames for bitcoind and bitcoin-cli from the environment +- `5122ea7` tests: fix forknotify.py on windows +- `fa7f8cd` tests: remove old pull-tester scripts +- `7667850` tests: replace the old (unused since Travis) tests with new rpc test scripts +- `f4e0aef` Do signature-s negation inside the tests +- `1837987` Optimize -regtest setgenerate block generation +- `2db4c8a` Fix node ranges in the test framework +- `a8b2ce5` regression test only setmocktime RPC call +- `daf03e7` RPC tests: create initial chain with specific timestamps +- `8656dbb` Port/fix txnmall.sh regression test +- `ca81587` Test the exact order of CHECKMULTISIG sig/pubkey evaluation +- `7357893` Prioritize and display -testsafemode status in UI +- `f321d6b` Add key generation/verification to ECC sanity check +- `132ea9b` miner_tests: Disable checkpoints so they don't fail the subsidy-change test +- `bc6cb41` QA RPC tests: Add tests block block proposals +- `f67a9ce` Use deterministically generated script tests +- `11d7a7d` [RPC] add rpc-test for http keep-alive (persistent connections) +- `34318d7` RPC-test based on invalidateblock for mempool coinbase spends +- `76ec867` Use actually valid transactions for script tests +- `c8589bf` Add actual signature tests +- `e2677d7` Fix smartfees test for change to relay policy +- `263b65e` tests: run sanity checks in tests too + +Miscellaneous: +- `122549f` Fix incorrect checkpoint data for testnet3 +- `5bd02cf` Log used config file to debug.log on startup +- `68ba85f` Updated Debian example bitcoin.conf with config from wiki + removed some cruft and updated comments +- `e5ee8f0` Remove -beta suffix +- `38405ac` Add comment regarding experimental-use service bits +- `be873f6` Issue warning if collecting RandSeed data failed +- `8ae973c` Allocate more space if necessary in RandSeedAddPerfMon +- `675bcd5` Correct comment for 15-of-15 p2sh script size +- `fda3fed` libsecp256k1 integration +- `2e36866` Show nodeid instead of addresses in log (for anonymity) unless otherwise requested +- `cd01a5e` Enable paranoid corruption checks in LevelDB >= 1.16 +- `9365937` Add comment about never updating nTimeOffset past 199 samples +- `403c1bf` contrib: remove getwork-based pyminer (as getwork API call has been removed) +- `0c3e101` contrib: Added systemd .service file in order to help distributions integrate bitcoind +- `0a0878d` doc: Add new DNSseed policy +- `2887bff` Update coding style and add .clang-format +- `5cbda4f` Changed LevelDB cursors to use scoped pointers to ensure destruction when going out of scope +- `b4a72a7` contrib/linearize: split output files based on new-timestamp-year or max-file-size +- `e982b57` Use explicit fflush() instead of setvbuf() +- `234bfbf` contrib: Add init scripts and docs for Upstart and OpenRC +- `01c2807` Add warning about the merkle-tree algorithm duplicate txid flaw +- `d6712db` Also create pid file in non-daemon mode +- `772ab0e` contrib: use batched JSON-RPC in linarize-hashes (optimization) +- `7ab4358` Update bash-completion for v0.10 +- `6e6a36c` contrib: show pull # in prompt for github-merge script +- `5b9f842` Upgrade leveldb to 1.18, make chainstate databases compatible between ARM and x86 (issue #2293) +- `4e7c219` Catch UTXO set read errors and shutdown +- `867c600` Catch LevelDB errors during flush +- `06ca065` Fix CScriptID(const CScript& in) in empty script case + +Credits +======= + +Thanks to everyone who contributed to this release: + +- 21E14 +- Adam Weiss +- Aitor Pazos +- Alexander Jeng +- Alex Morcos +- Alon Muroch +- Andreas Schildbach +- Andrew Poelstra +- Andy Alness +- Ashley Holman +- Benedict Chan +- Ben Holden-Crowther +- Bryan Bishop +- BtcDrak +- Christian von Roques +- Clinton Christian +- Cory Fields +- Cozz Lovan +- daniel +- Daniel Kraft +- David Hill +- Derek701 +- dexX7 +- dllud +- Dominyk Tiller +- Doug +- elichai +- elkingtowa +- ENikS +- Eric Shaw +- Federico Bond +- Francis GASCHET +- Gavin Andresen +- Giuseppe Mazzotta +- Glenn Willen +- Gregory Maxwell +- gubatron +- HarryWu +- himynameismartin +- Huang Le +- Ian Carroll +- imharrywu +- Jameson Lopp +- Janusz Lenar +- JaSK +- Jeff Garzik +- JL2035 +- Johnathan Corgan +- Jonas Schnelli +- jtimon +- Julian Haight +- Kamil Domanski +- kazcw +- kevin +- kiwigb +- Kosta Zertsekel +- LongShao007 +- Luke Dashjr +- Mark Friedenbach +- Mathy Vanvoorden +- Matt Corallo +- Matthew Bogosian +- Micha +- Michael Ford +- Mike Hearn +- mrbandrews +- mruddy +- ntrgn +- Otto Allmendinger +- paveljanik +- Pavel Vasin +- Peter Todd +- phantomcircuit +- Philip Kaufmann +- Pieter Wuille +- pryds +- randy-waterhouse +- R E Broadley +- Rose Toomey +- Ross Nicoll +- Roy Badami +- Ruben Dario Ponticelli +- Rune K. Svendsen +- Ryan X. Charles +- Saivann +- sandakersmann +- SergioDemianLerner +- shshshsh +- sinetek +- Stuart Cardall +- Suhas Daftuar +- Tawanda Kembo +- Teran McKinney +- tm314159 +- Tom Harding +- Trevin Hofmann +- Whit J +- Wladimir J. van der Laan +- Yoichi Hirai +- Zak Wilcox + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). + diff --git a/doc/release-notes/release-notes-0.10.1.md b/doc/release-notes/release-notes-0.10.1.md new file mode 100644 index 0000000000..8f59f1f68c --- /dev/null +++ b/doc/release-notes/release-notes-0.10.1.md @@ -0,0 +1,143 @@ +Bitcoin Core version 0.10.1 is now available from: + + <https://bitcoin.org/bin/bitcoin-core-0.10.1/> + +This is a new minor version release, bringing bug fixes and translation +updates. It is recommended to upgrade to this version. + +Please report bugs using the issue tracker at github: + + <https://github.com/bitcoin/bitcoin/issues> + +Upgrading and downgrading +========================= + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Downgrade warning +------------------ + +Because release 0.10.0 and later makes use of headers-first synchronization and +parallel block download (see further), the block files and databases are not +backwards-compatible with pre-0.10 versions of Bitcoin Core or other software: + +* Blocks will be stored on disk out of order (in the order they are +received, really), which makes it incompatible with some tools or +other programs. Reindexing using earlier versions will also not work +anymore as a result of this. + +* The block index database will now hold headers for which no block is +stored on disk, which earlier versions won't support. + +If you want to be able to downgrade smoothly, make a backup of your entire data +directory. Without this your node will need start syncing (or importing from +bootstrap.dat) anew afterwards. It is possible that the data from a completely +synchronised 0.10 node may be usable in older versions as-is, but this is not +supported and may break as soon as the older version attempts to reindex. + +This does not affect wallet forward or backward compatibility. + +Notable changes +=============== + +This is a minor release and hence there are no notable changes. +For the notable changes in 0.10, refer to the release notes for the +0.10.0 release at https://github.com/bitcoin/bitcoin/blob/v0.10.0/doc/release-notes.md + +0.10.1 Change log +================= + +Detailed release notes follow. This overview includes changes that affect external +behavior, not code moves, refactors or string updates. + +RPC: +- `7f502be` fix crash: createmultisig and addmultisigaddress +- `eae305f` Fix missing lock in submitblock + +Block (database) and transaction handling: +- `1d2cdd2` Fix InvalidateBlock to add chainActive.Tip to setBlockIndexCandidates +- `c91c660` fix InvalidateBlock to repopulate setBlockIndexCandidates +- `002c8a2` fix possible block db breakage during re-index +- `a1f425b` Add (optional) consistency check for the block chain data structures +- `1c62e84` Keep mempool consistent during block-reorgs +- `57d1f46` Fix CheckBlockIndex for reindex +- `bac6fca` Set nSequenceId when a block is fully linked + +P2P protocol and network code: +- `78f64ef` don't trickle for whitelisted nodes +- `ca301bf` Reduce fingerprinting through timestamps in 'addr' messages. +- `200f293` Ignore getaddr messages on Outbound connections. +- `d5d8998` Limit message sizes before transfer +- `aeb9279` Better fingerprinting protection for non-main-chain getdatas. +- `cf0218f` Make addrman's bucket placement deterministic (countermeasure 1 against eclipse attacks, see http://cs-people.bu.edu/heilman/eclipse/) +- `0c6f334` Always use a 50% chance to choose between tried and new entries (countermeasure 2 against eclipse attacks) +- `214154e` Do not bias outgoing connections towards fresh addresses (countermeasure 2 against eclipse attacks) +- `aa587d4` Scale up addrman (countermeasure 6 against eclipse attacks) +- `139cd81` Cap nAttempts penalty at 8 and switch to pow instead of a division loop + +Validation: +- `d148f62` Acquire CCheckQueue's lock to avoid race condition + +Build system: +- `8752b5c` 0.10 fix for crashes on OSX 10.6 + +Wallet: +- N/A + +GUI: +- `2c08406` some mac specifiy cleanup (memory handling, unnecessary code) +- `81145a6` fix OSX dock icon window reopening +- `786cf72` fix a issue where "command line options"-action overwrite "Preference"-action (on OSX) + +Tests: +- `1117378` add RPC test for InvalidateBlock + +Miscellaneous: +- `c9e022b` Initialization: set Boost path locale in main thread +- `23126a0` Sanitize command strings before logging them. +- `323de27` Initialization: setup environment before starting Qt tests +- `7494e09` Initialization: setup environment before starting tests +- `df45564` Initialization: set fallback locale as environment variable + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Alex Morcos +- Cory Fields +- dexX7 +- fsb4000 +- Gavin Andresen +- Gregory Maxwell +- Ivan Pustogarov +- Jonas Schnelli +- Matt Corallo +- mrbandrews +- Pieter Wuille +- Ruben de Vries +- Suhas Daftuar +- Wladimir J. van der Laan + +And all those who contributed additional code review and/or security research: +- 21E14 +- Alison Kendler +- Aviv Zohar +- Ethan Heilman +- Evil-Knievel +- fanquake +- Jeff Garzik +- Jonas Nick +- Luke Dashjr +- Patrick Strateman +- Philip Kaufmann +- Sergio Demian Lerner +- Sharon Goldberg + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-notes/release-notes-0.10.2.md b/doc/release-notes/release-notes-0.10.2.md new file mode 100644 index 0000000000..192ed69d29 --- /dev/null +++ b/doc/release-notes/release-notes-0.10.2.md @@ -0,0 +1,86 @@ +Bitcoin Core version 0.10.2 is now available from: + + <https://bitcoin.org/bin/bitcoin-core-0.10.2/> + +This is a new minor version release, bringing minor bug fixes and translation +updates. It is recommended to upgrade to this version. + +Please report bugs using the issue tracker at github: + + <https://github.com/bitcoin/bitcoin/issues> + +Upgrading and downgrading +========================= + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Downgrade warning +------------------ + +Because release 0.10.0 and later makes use of headers-first synchronization and +parallel block download (see further), the block files and databases are not +backwards-compatible with pre-0.10 versions of Bitcoin Core or other software: + +* Blocks will be stored on disk out of order (in the order they are +received, really), which makes it incompatible with some tools or +other programs. Reindexing using earlier versions will also not work +anymore as a result of this. + +* The block index database will now hold headers for which no block is +stored on disk, which earlier versions won't support. + +If you want to be able to downgrade smoothly, make a backup of your entire data +directory. Without this your node will need start syncing (or importing from +bootstrap.dat) anew afterwards. It is possible that the data from a completely +synchronised 0.10 node may be usable in older versions as-is, but this is not +supported and may break as soon as the older version attempts to reindex. + +This does not affect wallet forward or backward compatibility. + +Notable changes +=============== + +This fixes a serious problem on Windows with data directories that have non-ASCII +characters (https://github.com/bitcoin/bitcoin/issues/6078). + +For other platforms there are no notable changes. + +For the notable changes in 0.10, refer to the release notes +at https://github.com/bitcoin/bitcoin/blob/v0.10.0/doc/release-notes.md + +0.10.2 Change log +================= + +Detailed release notes follow. This overview includes changes that affect external +behavior, not code moves, refactors or string updates. + +Wallet: +- `824c011` fix boost::get usage with boost 1.58 + +Miscellaneous: +- `da65606` Avoid crash on start in TestBlockValidity with gen=1. +- `424ae66` don't imbue boost::filesystem::path with locale "C" on windows (fixes #6078) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Cory Fields +- Gregory Maxwell +- Jonas Schnelli +- Wladimir J. van der Laan + +And all those who contributed additional code review and/or security research: + +- dexX7 +- Pieter Wuille +- vayvanne + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-notes/release-notes-0.10.3.md b/doc/release-notes/release-notes-0.10.3.md new file mode 100644 index 0000000000..8a110e562c --- /dev/null +++ b/doc/release-notes/release-notes-0.10.3.md @@ -0,0 +1,165 @@ +Bitcoin Core version 0.10.3 is now available from: + + <https://bitcoin.org/bin/bitcoin-core-0.10.3/> + +This is a new minor version release, bringing security fixes and translation +updates. It is recommended to upgrade to this version as soon as possible. + +Please report bugs using the issue tracker at github: + + <https://github.com/bitcoin/bitcoin/issues> + +Upgrading and downgrading +========================= + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Downgrade warning +------------------ + +Because release 0.10.0 and later makes use of headers-first synchronization and +parallel block download (see further), the block files and databases are not +backwards-compatible with pre-0.10 versions of Bitcoin Core or other software: + +* Blocks will be stored on disk out of order (in the order they are +received, really), which makes it incompatible with some tools or +other programs. Reindexing using earlier versions will also not work +anymore as a result of this. + +* The block index database will now hold headers for which no block is +stored on disk, which earlier versions won't support. + +If you want to be able to downgrade smoothly, make a backup of your entire data +directory. Without this your node will need start syncing (or importing from +bootstrap.dat) anew afterwards. It is possible that the data from a completely +synchronised 0.10 node may be usable in older versions as-is, but this is not +supported and may break as soon as the older version attempts to reindex. + +This does not affect wallet forward or backward compatibility. + +Notable changes +=============== + +Fix buffer overflow in bundled upnp +------------------------------------ + +Bundled miniupnpc was updated to 1.9.20151008. This fixes a buffer overflow in +the XML parser during initial network discovery. + +Details can be found here: http://talosintel.com/reports/TALOS-2015-0035/ + +This applies to the distributed executables only, not when building from source or +using distribution provided packages. + +Additionally, upnp has been disabled by default. This may result in a lower +number of reachable nodes on IPv4, however this prevents future libupnpc +vulnerabilities from being a structural risk to the network +(see https://github.com/bitcoin/bitcoin/pull/6795). + +Test for LowS signatures before relaying +----------------------------------------- + +Make the node require the canonical 'low-s' encoding for ECDSA signatures when +relaying or mining. This removes a nuisance malleability vector. + +Consensus behavior is unchanged. + +If widely deployed this change would eliminate the last remaining known vector +for nuisance malleability on SIGHASH_ALL P2PKH transactions. On the down-side +it will block most transactions made by sufficiently out of date software. + +Unlike the other avenues to change txids on transactions this +one was randomly violated by all deployed bitcoin software prior to +its discovery. So, while other malleability vectors where made +non-standard as soon as they were discovered, this one has remained +permitted. Even BIP62 did not propose applying this rule to +old version transactions, but conforming implementations have become +much more common since BIP62 was initially written. + +Bitcoin Core has produced compatible signatures since a28fb70e in +September 2013, but this didn't make it into a release until 0.9 +in March 2014; Bitcoinj has done so for a similar span of time. +Bitcoinjs and electrum have been more recently updated. + +This does not replace the need for BIP62 or similar, as miners can +still cooperate to break transactions. Nor does it replace the +need for wallet software to handle malleability sanely[1]. This +only eliminates the cheap and irritating DOS attack. + +[1] On the Malleability of Bitcoin Transactions +Marcin Andrychowicz, Stefan Dziembowski, Daniel Malinowski, Łukasz Mazurek +http://fc15.ifca.ai/preproceedings/bitcoin/paper_9.pdf + +Minimum relay fee default increase +----------------------------------- + +The default for the `-minrelaytxfee` setting has been increased from `0.00001` +to `0.00005`. + +This is necessitated by the current transaction flooding, causing +outrageous memory usage on nodes due to the mempool ballooning. This is a +temporary measure, bridging the time until a dynamic method for determining +this fee is merged (which will be in 0.12). + +(see https://github.com/bitcoin/bitcoin/pull/6793, as well as the 0.11.0 +release notes, in which this value was suggested) + +0.10.3 Change log +================= + +Detailed release notes follow. This overview includes changes that affect external +behavior, not code moves, refactors or string updates. + +- #6186 `e4a7d51` Fix two problems in CSubnet parsing +- #6153 `ebd7d8d` Parameter interaction: disable upnp if -proxy set +- #6203 `ecc96f5` Remove P2SH coinbase flag, no longer interesting +- #6226 `181771b` json: fail read_string if string contains trailing garbage +- #6244 `09334e0` configure: Detect (and reject) LibreSSL +- #6276 `0fd8464` Fix getbalance * 0 +- #6274 `be64204` Add option `-alerts` to opt out of alert system +- #6319 `3f55638` doc: update mailing list address +- #6438 `7e66e9c` openssl: avoid config file load/race +- #6439 `255eced` Updated URL location of netinstall for Debian +- #6412 `0739e6e` Test whether created sockets are select()able +- #6694 `f696ea1` [QT] fix thin space word wrap line brake issue +- #6704 `743cc9e` Backport bugfixes to 0.10 +- #6769 `1cea6b0` Test LowS in standardness, removes nuisance malleability vector. +- #6789 `093d7b5` Update miniupnpc to 1.9.20151008 +- #6795 `f2778e0` net: Disable upnp by default +- #6797 `91ef4d9` Do not store more than 200 timedata samples +- #6793 `842c48d` Bump minrelaytxfee default + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Adam Weiss +- Alex Morcos +- Casey Rodarmor +- Cory Fields +- fanquake +- Gregory Maxwell +- Jonas Schnelli +- J Ross Nicoll +- Luke Dashjr +- Pavel Vasin +- Pieter Wuille +- randy-waterhouse +- ฿tcDrak +- Tom Harding +- Veres Lajos +- Wladimir J. van der Laan + +And all those who contributed additional code review and/or security research: + +- timothy on IRC for reporting the issue +- Vulnerability in miniupnp discovered by Aleksandar Nikolic of Cisco Talos + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-notes/release-notes-0.10.4.md b/doc/release-notes/release-notes-0.10.4.md new file mode 100644 index 0000000000..38a2c1347d --- /dev/null +++ b/doc/release-notes/release-notes-0.10.4.md @@ -0,0 +1,172 @@ +Bitcoin Core version 0.10.4 is now available from: + + <https://bitcoin.org/bin/bitcoin-core-0.10.4/> + +This is a new minor version release, bringing bug fixes, the BIP65 +(CLTV) consensus change, and relay policy preparation for BIP113. It is +recommended to upgrade to this version as soon as possible. + +Please report bugs using the issue tracker at github: + + <https://github.com/bitcoin/bitcoin/issues> + +Upgrading and downgrading +========================= + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Downgrade warning +------------------ + +Because release 0.10.0 and later makes use of headers-first synchronization and +parallel block download (see further), the block files and databases are not +backwards-compatible with pre-0.10 versions of Bitcoin Core or other software: + +* Blocks will be stored on disk out of order (in the order they are +received, really), which makes it incompatible with some tools or +other programs. Reindexing using earlier versions will also not work +anymore as a result of this. + +* The block index database will now hold headers for which no block is +stored on disk, which earlier versions won't support. + +If you want to be able to downgrade smoothly, make a backup of your entire data +directory. Without this your node will need start syncing (or importing from +bootstrap.dat) anew afterwards. It is possible that the data from a completely +synchronised 0.10 node may be usable in older versions as-is, but this is not +supported and may break as soon as the older version attempts to reindex. + +This does not affect wallet forward or backward compatibility. There are no +known problems when downgrading from 0.11.x to 0.10.x. + +Notable changes since 0.10.3 +============================ + +BIP65 soft fork to enforce OP_CHECKLOCKTIMEVERIFY opcode +-------------------------------------------------------- + +This release includes several changes related to the [BIP65][] soft fork +which redefines the existing OP_NOP2 opcode as OP_CHECKLOCKTIMEVERIFY +(CLTV) so that a transaction output can be made unspendable until a +specified point in the future. + +1. This release will only relay and mine transactions spending a CLTV + output if they comply with the BIP65 rules as provided in code. + +2. This release will produce version 4 blocks by default. Please see the + *notice to miners* below. + +3. Once 951 out of a sequence of 1,001 blocks on the local node's best block + chain contain version 4 (or higher) blocks, this release will no + longer accept new version 3 blocks and it will only accept version 4 + blocks if they comply with the BIP65 rules for CLTV. + +For more information about the soft-forking change, please see +<https://github.com/bitcoin/bitcoin/pull/6351> + +Graphs showing the progress towards block version 4 adoption may be +found at the URLs below: + +- Block versions over the last 50,000 blocks as progress towards BIP65 + consensus enforcement: <http://bitcoin.sipa.be/ver-50k.png> + +- Block versions over the last 2,000 blocks showing the days to the + earliest possible BIP65 consensus-enforced block: <http://bitcoin.sipa.be/ver-2k.png> + +**Notice to miners:** Bitcoin Core’s block templates are now for +version 4 blocks only, and any mining software relying on its +getblocktemplate must be updated in parallel to use libblkmaker either +version FIXME or any version from FIXME onward. + +- If you are solo mining, this will affect you the moment you upgrade + Bitcoin Core, which must be done prior to BIP65 achieving its 951/1001 + status. + +- If you are mining with the stratum mining protocol: this does not + affect you. + +- If you are mining with the getblocktemplate protocol to a pool: this + will affect you at the pool operator’s discretion, which must be no + later than BIP65 achieving its 951/1001 status. + +[BIP65]: https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki + +Windows bug fix for corrupted UTXO database on unclean shutdowns +---------------------------------------------------------------- + +Several Windows users reported that they often need to reindex the +entire blockchain after an unclean shutdown of Bitcoin Core on Windows +(or an unclean shutdown of Windows itself). Although unclean shutdowns +remain unsafe, this release no longer relies on memory-mapped files for +the UTXO database, which significantly reduced the frequency of unclean +shutdowns leading to required reindexes during testing. + +For more information, see: <https://github.com/bitcoin/bitcoin/pull/6917> + +Other fixes for database corruption on Windows are expected in the +next major release. + +0.10.4 Change log +================= + +Detailed release notes follow. This overview includes changes that affect +behavior, not code moves, refactors and string updates. For convenience in locating +the code changes and accompanying discussion, both the pull request and +git merge commit are mentioned. + +- #6953 `8b3311f` alias -h for --help +- #6953 `97546fc` Change URLs to https in debian/control +- #6953 `38671bf` Update debian/changelog and slight tweak to debian/control +- #6953 `256321e` Correct spelling mistakes in doc folder +- #6953 `eae0350` Clarification of unit test build instructions +- #6953 `90897ab` Update bluematt-key, the old one is long-since revoked +- #6953 `a2f2fb6` build: disable -Wself-assign +- #6953 `cf67d8b` Bugfix: Allow mining on top of old tip blocks for testnet (fixes testnet-in-a-box use case) +- #6953 `b3964e3` Drop "with minimal dependencies" from description +- #6953 `43c2789` Split bitcoin-tx into its own package +- #6953 `dfe0d4d` Include bitcoin-tx binary on Debian/Ubuntu +- #6953 `612efe8` [Qt] Raise debug window when requested +- #6953 `3ad96bd` Fix locking in GetTransaction +- #6953 `9c81005` Fix spelling of Qt +- #6946 `94b67e5` Update LevelDB +- #6706 `5dc72f8` CLTV: Add more tests to improve coverage +- #6706 `6a1343b` Add RPC tests for the CHECKLOCKTIMEVERIFY (BIP65) soft-fork +- #6706 `4137248` Add CHECKLOCKTIMEVERIFY (BIP65) soft-fork logic +- #6706 `0e01d0f` Enable CHECKLOCKTIMEVERIFY as a standard script verify flag +- #6706 `6d01325` Replace NOP2 with CHECKLOCKTIMEVERIFY (BIP65) +- #6706 `750d54f` Move LOCKTIME_THRESHOLD to src/script/script.h +- #6706 `6897468` Make CScriptNum() take nMaxNumSize as an argument +- #6867 `5297194` Set TCP_NODELAY on P2P sockets +- #6836 `fb818b6` Bring historical release notes up to date +- #6852 `0b3fd07` build: make sure OpenSSL heeds noexecstack + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Alex Morcos +- Daniel Cousens +- Diego Viola +- Eric Lombrozo +- Esteban Ordano +- Gregory Maxwell +- Luke Dashjr +- MarcoFalke +- Matt Corallo +- Micha +- Mitchell Cash +- Peter Todd +- Pieter Wuille +- Wladimir J. van der Laan +- Zak Wilcox + +And those who contributed additional code review and/or security research. + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-notes/release-notes-0.11.0.md b/doc/release-notes/release-notes-0.11.0.md new file mode 100644 index 0000000000..28e49fb7ea --- /dev/null +++ b/doc/release-notes/release-notes-0.11.0.md @@ -0,0 +1,505 @@ +Bitcoin Core version 0.11.0 is now available from: + + <https://bitcoin.org/bin/bitcoin-core-0.11.0/> + +This is a new major version release, bringing both new features and +bug fixes. + +Please report bugs using the issue tracker at github: + + <https://github.com/bitcoin/bitcoin/issues> + +Upgrading and downgrading +========================= + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Downgrade warning +------------------ + +Because release 0.10.0 and later makes use of headers-first synchronization and +parallel block download (see further), the block files and databases are not +backwards-compatible with pre-0.10 versions of Bitcoin Core or other software: + +* Blocks will be stored on disk out of order (in the order they are +received, really), which makes it incompatible with some tools or +other programs. Reindexing using earlier versions will also not work +anymore as a result of this. + +* The block index database will now hold headers for which no block is +stored on disk, which earlier versions won't support. + +If you want to be able to downgrade smoothly, make a backup of your entire data +directory. Without this your node will need start syncing (or importing from +bootstrap.dat) anew afterwards. It is possible that the data from a completely +synchronised 0.10 node may be usable in older versions as-is, but this is not +supported and may break as soon as the older version attempts to reindex. + +This does not affect wallet forward or backward compatibility. There are no +known problems when downgrading from 0.11.x to 0.10.x. + +Important information +====================== + +Transaction flooding +--------------------- + +At the time of this release, the P2P network is being flooded with low-fee +transactions. This causes a ballooning of the mempool size. + +If this growth of the mempool causes problematic memory use on your node, it is +possible to change a few configuration options to work around this. The growth +of the mempool can be monitored with the RPC command `getmempoolinfo`. + +One is to increase the minimum transaction relay fee `minrelaytxfee`, which +defaults to 0.00001. This will cause transactions with fewer BTC/kB fee to be +rejected, and thus fewer transactions entering the mempool. + +The other is to restrict the relaying of free transactions with +`limitfreerelay`. This option sets the number of kB/minute at which +free transactions (with enough priority) will be accepted. It defaults to 15. +Reducing this number reduces the speed at which the mempool can grow due +to free transactions. + +For example, add the following to `bitcoin.conf`: + + minrelaytxfee=0.00005 + limitfreerelay=5 + +More robust solutions are being worked on for a follow-up release. + +Notable changes +=============== + +Block file pruning +---------------------- + +This release supports running a fully validating node without maintaining a copy +of the raw block and undo data on disk. To recap, there are four types of data +related to the blockchain in the bitcoin system: the raw blocks as received over +the network (blk???.dat), the undo data (rev???.dat), the block index and the +UTXO set (both LevelDB databases). The databases are built from the raw data. + +Block pruning allows Bitcoin Core to delete the raw block and undo data once +it's been validated and used to build the databases. At that point, the raw data +is used only to relay blocks to other nodes, to handle reorganizations, to look +up old transactions (if -txindex is enabled or via the RPC/REST interfaces), or +for rescanning the wallet. The block index continues to hold the metadata about +all blocks in the blockchain. + +The user specifies how much space to allot for block & undo files. The minimum +allowed is 550MB. Note that this is in addition to whatever is required for the +block index and UTXO databases. The minimum was chosen so that Bitcoin Core will +be able to maintain at least 288 blocks on disk (two days worth of blocks at 10 +minutes per block). In rare instances it is possible that the amount of space +used will exceed the pruning target in order to keep the required last 288 +blocks on disk. + +Block pruning works during initial sync in the same way as during steady state, +by deleting block files "as you go" whenever disk space is allocated. Thus, if +the user specifies 550MB, once that level is reached the program will begin +deleting the oldest block and undo files, while continuing to download the +blockchain. + +For now, block pruning disables block relay. In the future, nodes with block +pruning will at a minimum relay "new" blocks, meaning blocks that extend their +active chain. + +Block pruning is currently incompatible with running a wallet due to the fact +that block data is used for rescanning the wallet and importing keys or +addresses (which require a rescan.) However, running the wallet with block +pruning will be supported in the near future, subject to those limitations. + +Block pruning is also incompatible with -txindex and will automatically disable +it. + +Once you have pruned blocks, going back to unpruned state requires +re-downloading the entire blockchain. To do this, re-start the node with +-reindex. Note also that any problem that would cause a user to reindex (e.g., +disk corruption) will cause a pruned node to redownload the entire blockchain. +Finally, note that when a pruned node reindexes, it will delete any blk???.dat +and rev???.dat files in the data directory prior to restarting the download. + +To enable block pruning on the command line: + +- `-prune=N`: where N is the number of MB to allot for raw block & undo data. + +Modified RPC calls: + +- `getblockchaininfo` now includes whether we are in pruned mode or not. +- `getblock` will check if the block's data has been pruned and if so, return an +error. +- `getrawtransaction` will no longer be able to locate a transaction that has a +UTXO but where its block file has been pruned. + +Pruning is disabled by default. + +Big endian support +-------------------- + +Experimental support for big-endian CPU architectures was added in this +release. All little-endian specific code was replaced with endian-neutral +constructs. This has been tested on at least MIPS and PPC hosts. The build +system will automatically detect the endianness of the target. + +Memory usage optimization +-------------------------- + +There have been many changes in this release to reduce the default memory usage +of a node, among which: + +- Accurate UTXO cache size accounting (#6102); this makes the option `-dbcache` + precise where this grossly underestimated memory usage before +- Reduce size of per-peer data structure (#6064 and others); this increases the + number of connections that can be supported with the same amount of memory +- Reduce the number of threads (#5964, #5679); lowers the amount of (esp. + virtual) memory needed + +Fee estimation changes +---------------------- + +This release improves the algorithm used for fee estimation. Previously, -1 +was returned when there was insufficient data to give an estimate. Now, -1 +will also be returned when there is no fee or priority high enough for the +desired confirmation target. In those cases, it can help to ask for an estimate +for a higher target number of blocks. It is not uncommon for there to be no +fee or priority high enough to be reliably (85%) included in the next block and +for this reason, the default for `-txconfirmtarget=n` has changed from 1 to 2. + +Privacy: Disable wallet transaction broadcast +---------------------------------------------- + +This release adds an option `-walletbroadcast=0` to prevent automatic +transaction broadcast and rebroadcast (#5951). This option allows separating +transaction submission from the node functionality. + +Making use of this, third-party scripts can be written to take care of +transaction (re)broadcast: + +- Send the transaction as normal, either through RPC or the GUI +- Retrieve the transaction data through RPC using `gettransaction` (NOT + `getrawtransaction`). The `hex` field of the result will contain the raw + hexadecimal representation of the transaction +- The transaction can then be broadcasted through arbitrary mechanisms + supported by the script + +One such application is selective Tor usage, where the node runs on the normal +internet but transactions are broadcasted over Tor. + +For an example script see [bitcoin-submittx](https://github.com/laanwj/bitcoin-submittx). + +Privacy: Stream isolation for Tor +---------------------------------- + +This release adds functionality to create a new circuit for every peer +connection, when the software is used with Tor. The new option, +`-proxyrandomize`, is on by default. + +When enabled, every outgoing connection will (potentially) go through a +different exit node. That significantly reduces the chance to get unlucky and +pick a single exit node that is either malicious, or widely banned from the P2P +network. This improves connection reliability as well as privacy, especially +for the initial connections. + +**Important note:** If a non-Tor SOCKS5 proxy is configured that supports +authentication, but doesn't require it, this change may cause that proxy to reject +connections. A user and password is sent where they weren't before. This setup +is exceedingly rare, but in this case `-proxyrandomize=0` can be passed to +disable the behavior. + +0.11.0 Change log +================= + +Detailed release notes follow. This overview includes changes that affect +behavior, not code moves, refactors and string updates. For convenience in locating +the code changes and accompanying discussion, both the pull request and +git merge commit are mentioned. + +### RPC and REST +- #5461 `5f7279a` signrawtransaction: validate private key +- #5444 `103f66b` Add /rest/headers/<count>/<hash>.<ext> +- #4964 `95ecc0a` Add scriptPubKey field to validateaddress RPC call +- #5476 `c986972` Add time offset into getpeerinfo output +- #5540 `84eba47` Add unconfirmed and immature balances to getwalletinfo +- #5599 `40e96a3` Get rid of the internal miner's hashmeter +- #5711 `87ecfb0` Push down RPC locks +- #5754 `1c4e3f9` fix getblocktemplate lock issue +- #5756 `5d901d8` Fix getblocktemplate_proposals test by mining one block +- #5548 `d48ce48` Add /rest/chaininfos +- #5992 `4c4f1b4` Push down RPC reqWallet flag +- #6036 `585b5db` Show zero value txouts in listunspent +- #5199 `6364408` Add RPC call `gettxoutproof` to generate and verify merkle blocks +- #5418 `16341cc` Report missing inputs in sendrawtransaction +- #5937 `40f5e8d` show script verification errors in signrawtransaction result +- #5420 `1fd2d39` getutxos REST command (based on Bip64) +- #6193 `42746b0` [REST] remove json input for getutxos, limit to query max. 15 outpoints +- #6226 `5901596` json: fail read_string if string contains trailing garbage + +### Configuration and command-line options +- #5636 `a353ad4` Add option `-allowselfsignedrootcertificate` to allow self signed root certs (for testing payment requests) +- #5900 `3e8a1f2` Add a consistency check `-checkblockindex` for the block chain data structures +- #5951 `7efc9cf` Make it possible to disable wallet transaction broadcast (using `-walletbroadcast=0`) +- #5911 `b6ea3bc` privacy: Stream isolation for Tor (on by default, use `-proxyrandomize=0` to disable) +- #5863 `c271304` Add autoprune functionality (`-prune=<size>`) +- #6153 `0bcf04f` Parameter interaction: disable upnp if -proxy set +- #6274 `4d9c7fe` Add option `-alerts` to opt out of alert system + +### Block and transaction handling +- #5367 `dcc1304` Do all block index writes in a batch +- #5253 `203632d` Check against MANDATORY flags prior to accepting to mempool +- #5459 `4406c3e` Reject headers that build on an invalid parent +- #5481 `055f3ae` Apply AreSane() checks to the fees from the network +- #5580 `40d65eb` Preemptively catch a few potential bugs +- #5349 `f55c5e9` Implement test for merkle tree malleability in CPartialMerkleTree +- #5564 `a89b837` clarify obscure uses of EvalScript() +- #5521 `8e4578a` Reject non-final txs even in testnet/regtest +- #5707 `6af674e` Change hardcoded character constants to descriptive named constants for db keys +- #5286 `fcf646c` Change the default maximum OP_RETURN size to 80 bytes +- #5710 `175d86e` Add more information to errors in ReadBlockFromDisk +- #5948 `b36f1ce` Use GetAncestor to compute new target +- #5959 `a0bfc69` Add additional block index consistency checks +- #6058 `7e0e7f8` autoprune minor post-merge improvements +- #5159 `2cc1372` New fee estimation code +- #6102 `6fb90d8` Implement accurate UTXO cache size accounting +- #6129 `2a82298` Bug fix for clearing fCheckForPruning +- #5947 `e9af4e6` Alert if it is very likely we are getting a bad chain +- #6203 `c00ae64` Remove P2SH coinbase flag, no longer interesting +- #5985 `37b4e42` Fix removing of orphan transactions +- #6221 `6cb70ca` Prune: Support noncontiguous block files +- #6256 `fce474c` Use best header chain timestamps to detect partitioning +- #6233 `a587606` Advance pindexLastCommonBlock for blocks in chainActive + +### P2P protocol and network code +- #5507 `844ace9` Prevent DOS attacks on in-flight data structures +- #5770 `32a8b6a` Sanitize command strings before logging them +- #5859 `dd4ffce` Add correct bool combiner for net signals +- #5876 `8e4fd0c` Add a NODE_GETUTXO service bit and document NODE_NETWORK +- #6028 `b9311fb` Move nLastTry from CAddress to CAddrInfo +- #5662 `5048465` Change download logic to allow calling getdata on inbound peers +- #5971 `18d2832` replace absolute sleep with conditional wait +- #5918 `7bf5d5e` Use equivalent PoW for non-main-chain requests +- #6059 `f026ab6` chainparams: use SeedSpec6's rather than CAddress's for fixed seeds +- #6080 `31c0bf1` Add jonasschnellis dns seeder +- #5976 `9f7809f` Reduce download timeouts as blocks arrive +- #6172 `b4bbad1` Ignore getheaders requests when not synced +- #5875 `304892f` Be stricter in processing unrequested blocks +- #6333 `41bbc85` Hardcoded seeds update June 2015 + +### Validation +- #5143 `48e1765` Implement BIP62 rule 6 +- #5713 `41e6e4c` Implement BIP66 + +### Build system +- #5501 `c76c9d2` Add mips, mipsel and aarch64 to depends platforms +- #5334 `cf87536` libbitcoinconsensus: Add pkg-config support +- #5514 `ed11d53` Fix 'make distcheck' +- #5505 `a99ef7d` Build winshutdownmonitor.cpp on Windows only +- #5582 `e8a6639` Osx toolchain update +- #5684 `ab64022` osx: bump build sdk to 10.9 +- #5695 `23ef5b7` depends: latest config.guess and config.sub +- #5509 `31dedb4` Fixes when compiling in c++11 mode +- #5819 `f8e68f7` release: use static libstdc++ and disable reduced exports by default +- #5510 `7c3fbc3` Big endian support +- #5149 `c7abfa5` Add script to verify all merge commits are signed +- #6082 `7abbb7e` qt: disable qt tests when one of the checks for the gui fails +- #6244 `0401aa2` configure: Detect (and reject) LibreSSL +- #6269 `95aca44` gitian: Use the new bitcoin-detached-sigs git repo for OSX signatures +- #6285 `ef1d506` Fix scheduler build with some boost versions. +- #6280 `25c2216` depends: fix Boost 1.55 build on GCC 5 +- #6303 `b711599` gitian: add a gitian-win-signer descriptor +- #6246 `8ea6d37` Fix build on FreeBSD +- #6282 `daf956b` fix crash on shutdown when e.g. changing -txindex and abort action +- #6354 `bdf0d94` Gitian windows signing normalization + +### Wallet +- #2340 `811c71d` Discourage fee sniping with nLockTime +- #5485 `d01bcc4` Enforce minRelayTxFee on wallet created tx and add a maxtxfee option +- #5508 `9a5cabf` Add RandAddSeedPerfmon to MakeNewKey +- #4805 `8204e19` Do not flush the wallet in AddToWalletIfInvolvingMe(..) +- #5319 `93b7544` Clean up wallet encryption code +- #5831 `df5c246` Subtract fee from amount +- #6076 `6c97fd1` wallet: fix boost::get usage with boost 1.58 +- #5511 `23c998d` Sort pending wallet transactions before reaccepting +- #6126 `26e08a1` Change default nTxConfirmTarget to 2 +- #6183 `75a4d51` Fix off-by-one error w/ nLockTime in the wallet +- #6276 `c9fd907` Fix getbalance * 0 + +### GUI +- #5219 `f3af0c8` New icons +- #5228 `bb3c75b` HiDPI (retina) support for splash screen +- #5258 `73cbf0a` The RPC Console should be a QWidget to make window more independent +- #5488 `851dfc7` Light blue icon color for regtest +- #5547 `a39aa74` New icon for the debug window +- #5493 `e515309` Adopt style colour for button icons +- #5557 `70477a0` On close of splashscreen interrupt verifyDB +- #5559 `83be8fd` Make the command-line-args dialog better +- #5144 `c5380a9` Elaborate on signverify message dialog warning +- #5489 `d1aa3c6` Optimize PNG files +- #5649 `e0cd2f5` Use text-color icons for system tray Send/Receive menu entries +- #5651 `848f55d` Coin Control: Use U+2248 "ALMOST EQUAL TO" rather than a simple tilde +- #5626 `ab0d798` Fix icon sizes and column width +- #5683 `c7b22aa` add new osx dmg background picture +- #5620 `7823598` Payment request expiration bug fix +- #5729 `9c4a5a5` Allow unit changes for read-only BitcoinAmountField +- #5753 `0f44672` Add bitcoin logo to about screen +- #5629 `a956586` Prevent amount overflow problem with payment requests +- #5830 `215475a` Don't save geometry for options and about/help window +- #5793 `d26f0b2` Honor current network when creating autostart link +- #5847 `f238add` Startup script for centos, with documentation +- #5915 `5bd3a92` Fix a static qt5 crash when using certain versions of libxcb +- #5898 `bb56781` Fix rpc console font size to flexible metrics +- #5467 `bc8535b` Payment request / server work - part 2 +- #6161 `180c164` Remove movable option for toolbar +- #6160 `0d862c2` Overviewpage: make sure warning icons gets colored + +### Tests +- #5453 `2f2d337` Add ability to run single test manually to RPC tests +- #5421 `886eb57` Test unexecuted OP_CODESEPARATOR +- #5530 `565b300` Additional rpc tests +- #5611 `37b185c` Fix spurious windows test failures after 012598880c +- #5613 `2eda47b` Fix smartfees test for change to relay policy +- #5612 `e3f5727` Fix zapwallettxes test +- #5642 `30a5b5f` Prepare paymentservertests for new unit tests +- #5784 `e3a3cd7` Fix usage of NegateSignatureS in script_tests +- #5813 `ee9f2bf` Add unit tests for next difficulty calculations +- #5855 `d7989c0` Travis: run unit tests in different orders +- #5852 `cdae53e` Reinitialize state in between individual unit tests. +- #5883 `164d7b6` tests: add a BasicTestingSetup and apply to all tests +- #5940 `446bb70` Regression test for ResendWalletTransactions +- #6052 `cf7adad` fix and enable bip32 unit test +- #6039 `734f80a` tests: Error when setgenerate is used on regtest +- #6074 `948beaf` Correct the PUSHDATA4 minimal encoding test in script_invalid.json +- #6032 `e08886d` Stop nodes after RPC tests, even with --nocleanup +- #6075 `df1609f` Add additional script edge condition tests +- #5981 `da38dc6` Python P2P testing +- #5958 `9ef00c3` Add multisig rpc tests +- #6112 `fec5c0e` Add more script edge condition tests + +### Miscellaneous +- #5457, #5506, #5952, #6047 Update libsecp256k1 +- #5437 `84857e8` Add missing CAutoFile::IsNull() check in main +- #5490 `ec20fd7` Replace uint256/uint160 with opaque blobs where possible +- #5654, #5764 Adding jonasschnelli's GPG key +- #5477 `5f04d1d` OS X 10.10: LSSharedFileListItemResolve() is deprecated +- #5679 `beff11a` Get rid of DetectShutdownThread +- #5787 `9bd8c9b` Add fanquake PGP key +- #5366 `47a79bb` No longer check osx compatibility in RenameThread +- #5689 `07f4386` openssl: abstract out OPENSSL_cleanse +- #5708 `8b298ca` Add list of implemented BIPs +- #5809 `46bfbe7` Add bitcoin-cli man page +- #5839 `86eb461` keys: remove libsecp256k1 verification until it's actually supported +- #5749 `d734d87` Help messages correctly formatted (79 chars) +- #5884 `7077fe6` BUGFIX: Stack around the variable 'rv' was corrupted +- #5849 `41259ca` contrib/init/bitcoind.openrc: Compatibility with previous OpenRC init script variables +- #5950 `41113e3` Fix locale fallback and guard tests against invalid locale settings +- #5965 `7c6bfb1` Add git-subtree-check.sh script +- #6033 `1623f6e` FreeBSD, OpenBSD thread renaming +- #6064 `b46e7c2` Several changes to mruset +- #6104 `3e2559c` Show an init message while activating best chain +- #6125 `351f73e` Clean up parsing of bool command line args +- #5964 `b4c219b` Lightweight task scheduler +- #6116 `30dc3c1` [OSX] rename Bitcoin-Qt.app to Bitcoin-Core.app +- #6168 `b3024f0` contrib/linearize: Support linearization of testnet blocks +- #6098 `7708fcd` Update Windows resource files (and add one for bitcoin-tx) +- #6159 `e1412d3` Catch errors on datadir lock and pidfile delete +- #6186 `182686c` Fix two problems in CSubnet parsing +- #6174 `df992b9` doc: add translation strings policy +- #6210 `dfdb6dd` build: disable optional use of gmp in internal secp256k1 build +- #6264 `94cd705` Remove translation for -help-debug options +- #6286 `3902c15` Remove berkeley-db4 workaround in MacOSX build docs +- #6319 `3f8fcc9` doc: update mailing list address + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- 21E14 +- Adam Weiss +- Alex Morcos +- ayeowch +- azeteki +- Ben Holden-Crowther +- bikinibabe +- BitcoinPRReadingGroup +- Blake Jakopovic +- BtcDrak +- charlescharles +- Chris Arnesen +- Ciemon +- CohibAA +- Corinne Dashjr +- Cory Fields +- Cozz Lovan +- Daira Hopwood +- Daniel Kraft +- Dave Collins +- David A. Harding +- dexX7 +- Earlz +- Eric Lombrozo +- Eric R. Schulz +- Everett Forth +- Flavien Charlon +- fsb4000 +- Gavin Andresen +- Gregory Maxwell +- Heath +- Ivan Pustogarov +- Jacob Welsh +- Jameson Lopp +- Jason Lewicki +- Jeff Garzik +- Jonas Schnelli +- Jonathan Brown +- Jorge Timón +- joshr +- jtimon +- Julian Yap +- Luca Venturini +- Luke Dashjr +- Manuel Araoz +- MarcoFalke +- Matt Bogosian +- Matt Corallo +- Micha +- Michael Ford +- Mike Hearn +- mrbandrews +- Nicolas Benoit +- paveljanik +- Pavel Janík +- Pavel Vasin +- Peter Todd +- Philip Kaufmann +- Pieter Wuille +- pstratem +- randy-waterhouse +- rion +- Rob Van Mieghem +- Ross Nicoll +- Ruben de Vries +- sandakersmann +- Shaul Kfir +- Shawn Wilkinson +- sinetek +- Suhas Daftuar +- svost +- Thomas Zander +- Tom Harding +- UdjinM6 +- Vitalii Demianets +- Wladimir J. van der Laan + +And all those who contributed additional code review and/or security research: + +- Sergio Demian Lerner + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). + diff --git a/doc/release-notes/release-notes-0.11.1.md b/doc/release-notes/release-notes-0.11.1.md new file mode 100644 index 0000000000..799205691e --- /dev/null +++ b/doc/release-notes/release-notes-0.11.1.md @@ -0,0 +1,172 @@ +Bitcoin Core version 0.11.1 is now available from: + + <https://bitcoin.org/bin/bitcoin-core-0.11.1/> + +This is a new minor version release, bringing security fixes. It is recommended +to upgrade to this version as soon as possible. + +Please report bugs using the issue tracker at github: + + <https://github.com/bitcoin/bitcoin/issues> + +Upgrading and downgrading +========================= + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Downgrade warning +------------------ + +Because release 0.10.0 and later makes use of headers-first synchronization and +parallel block download (see further), the block files and databases are not +backwards-compatible with pre-0.10 versions of Bitcoin Core or other software: + +* Blocks will be stored on disk out of order (in the order they are +received, really), which makes it incompatible with some tools or +other programs. Reindexing using earlier versions will also not work +anymore as a result of this. + +* The block index database will now hold headers for which no block is +stored on disk, which earlier versions won't support. + +If you want to be able to downgrade smoothly, make a backup of your entire data +directory. Without this your node will need start syncing (or importing from +bootstrap.dat) anew afterwards. It is possible that the data from a completely +synchronised 0.10 node may be usable in older versions as-is, but this is not +supported and may break as soon as the older version attempts to reindex. + +This does not affect wallet forward or backward compatibility. There are no +known problems when downgrading from 0.11.x to 0.10.x. + +Notable changes +=============== + +Fix buffer overflow in bundled upnp +------------------------------------ + +Bundled miniupnpc was updated to 1.9.20151008. This fixes a buffer overflow in +the XML parser during initial network discovery. + +Details can be found here: http://talosintel.com/reports/TALOS-2015-0035/ + +This applies to the distributed executables only, not when building from source or +using distribution provided packages. + +Additionally, upnp has been disabled by default. This may result in a lower +number of reachable nodes on IPv4, however this prevents future libupnpc +vulnerabilities from being a structural risk to the network +(see https://github.com/bitcoin/bitcoin/pull/6795). + +Test for LowS signatures before relaying +----------------------------------------- + +Make the node require the canonical 'low-s' encoding for ECDSA signatures when +relaying or mining. This removes a nuisance malleability vector. + +Consensus behavior is unchanged. + +If widely deployed this change would eliminate the last remaining known vector +for nuisance malleability on SIGHASH_ALL P2PKH transactions. On the down-side +it will block most transactions made by sufficiently out of date software. + +Unlike the other avenues to change txids on transactions this +one was randomly violated by all deployed bitcoin software prior to +its discovery. So, while other malleability vectors where made +non-standard as soon as they were discovered, this one has remained +permitted. Even BIP62 did not propose applying this rule to +old version transactions, but conforming implementations have become +much more common since BIP62 was initially written. + +Bitcoin Core has produced compatible signatures since a28fb70e in +September 2013, but this didn't make it into a release until 0.9 +in March 2014; Bitcoinj has done so for a similar span of time. +Bitcoinjs and electrum have been more recently updated. + +This does not replace the need for BIP62 or similar, as miners can +still cooperate to break transactions. Nor does it replace the +need for wallet software to handle malleability sanely[1]. This +only eliminates the cheap and irritating DOS attack. + +[1] On the Malleability of Bitcoin Transactions +Marcin Andrychowicz, Stefan Dziembowski, Daniel Malinowski, Łukasz Mazurek +http://fc15.ifca.ai/preproceedings/bitcoin/paper_9.pdf + +Minimum relay fee default increase +----------------------------------- + +The default for the `-minrelaytxfee` setting has been increased from `0.00001` +to `0.00005`. + +This is necessitated by the current transaction flooding, causing +outrageous memory usage on nodes due to the mempool ballooning. This is a +temporary measure, bridging the time until a dynamic method for determining +this fee is merged (which will be in 0.12). + +(see https://github.com/bitcoin/bitcoin/pull/6793, as well as the 0.11 +release notes, in which this value was suggested) + +0.11.1 Change log +================= + +Detailed release notes follow. This overview includes changes that affect +behavior, not code moves, refactors and string updates. For convenience in locating +the code changes and accompanying discussion, both the pull request and +git merge commit are mentioned. + +- #6438 `2531438` openssl: avoid config file load/race +- #6439 `980f820` Updated URL location of netinstall for Debian +- #6384 `8e5a969` qt: Force TLS1.0+ for SSL connections +- #6471 `92401c2` Depends: bump to qt 5.5 +- #6224 `93b606a` Be even stricter in processing unrequested blocks +- #6571 `100ac4e` libbitcoinconsensus: avoid a crash in multi-threaded environments +- #6545 `649f5d9` Do not store more than 200 timedata samples. +- #6694 `834e299` [QT] fix thin space word wrap line break issue +- #6703 `1cd7952` Backport bugfixes to 0.11 +- #6750 `5ed8d0b` Recent rejects backport to v0.11 +- #6769 `71cc9d9` Test LowS in standardness, removes nuisance malleability vector. +- #6789 `b4ad73f` Update miniupnpc to 1.9.20151008 +- #6785 `b4dc33e` Backport to v0.11: In (strCommand == "tx"), return if AlreadyHave() +- #6412 `0095b9a` Test whether created sockets are select()able +- #6795 `4dbcec0` net: Disable upnp by default +- #6793 `e7bcc4a` Bump minrelaytxfee default + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Adam Weiss +- Alex Morcos +- Casey Rodarmor +- Cory Fields +- fanquake +- Gregory Maxwell +- Jonas Schnelli +- J Ross Nicoll +- Luke Dashjr +- Pavel Janík +- Pavel Vasin +- Peter Todd +- Pieter Wuille +- randy-waterhouse +- Ross Nicoll +- Suhas Daftuar +- tailsjoin +- ฿tcDrak +- Tom Harding +- Veres Lajos +- Wladimir J. van der Laan + +And those who contributed additional code review and/or security research: + +- timothy on IRC for reporting the issue +- Vulnerability in miniupnp discovered by Aleksandar Nikolic of Cisco Talos + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). + diff --git a/doc/release-notes/release-notes-0.11.2.md b/doc/release-notes/release-notes-0.11.2.md new file mode 100644 index 0000000000..2351b80656 --- /dev/null +++ b/doc/release-notes/release-notes-0.11.2.md @@ -0,0 +1,217 @@ +Bitcoin Core version 0.11.2 is now available from: + + <https://bitcoin.org/bin/bitcoin-core-0.11.2/> + +This is a new minor version release, bringing bug fixes, the BIP65 +(CLTV) consensus change, and relay policy preparation for BIP113. It is +recommended to upgrade to this version as soon as possible. + +Please report bugs using the issue tracker at github: + + <https://github.com/bitcoin/bitcoin/issues> + +Upgrading and downgrading +========================= + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Downgrade warning +------------------ + +Because release 0.10.0 and later makes use of headers-first synchronization and +parallel block download (see further), the block files and databases are not +backwards-compatible with pre-0.10 versions of Bitcoin Core or other software: + +* Blocks will be stored on disk out of order (in the order they are +received, really), which makes it incompatible with some tools or +other programs. Reindexing using earlier versions will also not work +anymore as a result of this. + +* The block index database will now hold headers for which no block is +stored on disk, which earlier versions won't support. + +If you want to be able to downgrade smoothly, make a backup of your entire data +directory. Without this your node will need start syncing (or importing from +bootstrap.dat) anew afterwards. It is possible that the data from a completely +synchronised 0.10 node may be usable in older versions as-is, but this is not +supported and may break as soon as the older version attempts to reindex. + +This does not affect wallet forward or backward compatibility. There are no +known problems when downgrading from 0.11.x to 0.10.x. + +Notable changes since 0.11.1 +============================ + +BIP65 soft fork to enforce OP_CHECKLOCKTIMEVERIFY opcode +-------------------------------------------------------- + +This release includes several changes related to the [BIP65][] soft fork +which redefines the existing OP_NOP2 opcode as OP_CHECKLOCKTIMEVERIFY +(CLTV) so that a transaction output can be made unspendable until a +specified point in the future. + +1. This release will only relay and mine transactions spending a CLTV + output if they comply with the BIP65 rules as provided in code. + +2. This release will produce version 4 blocks by default. Please see the + *notice to miners* below. + +3. Once 951 out of a sequence of 1,001 blocks on the local node's best block + chain contain version 4 (or higher) blocks, this release will no + longer accept new version 3 blocks and it will only accept version 4 + blocks if they comply with the BIP65 rules for CLTV. + +For more information about the soft-forking change, please see +<https://github.com/bitcoin/bitcoin/pull/6351> + +Graphs showing the progress towards block version 4 adoption may be +found at the URLs below: + +- Block versions over the last 50,000 blocks as progress towards BIP65 + consensus enforcement: <http://bitcoin.sipa.be/ver-50k.png> + +- Block versions over the last 2,000 blocks showing the days to the + earliest possible BIP65 consensus-enforced block: <http://bitcoin.sipa.be/ver-2k.png> + +**Notice to miners:** Bitcoin Core’s block templates are now for +version 4 blocks only, and any mining software relying on its +getblocktemplate must be updated in parallel to use libblkmaker either +version 0.4.3 or any version from 0.5.2 onward. + +- If you are solo mining, this will affect you the moment you upgrade + Bitcoin Core, which must be done prior to BIP65 achieving its 951/1001 + status. + +- If you are mining with the stratum mining protocol: this does not + affect you. + +- If you are mining with the getblocktemplate protocol to a pool: this + will affect you at the pool operator’s discretion, which must be no + later than BIP65 achieving its 951/1001 status. + +[BIP65]: https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki + +BIP113 mempool-only locktime enforcement using GetMedianTimePast() +---------------------------------------------------------------- + +Bitcoin transactions currently may specify a locktime indicating when +they may be added to a valid block. Current consensus rules require +that blocks have a block header time greater than the locktime specified +in any transaction in that block. + +Miners get to choose what time they use for their header time, with the +consensus rule being that no node will accept a block whose time is more +than two hours in the future. This creates a incentive for miners to +set their header times to future values in order to include locktimed +transactions which weren't supposed to be included for up to two more +hours. + +The consensus rules also specify that valid blocks may have a header +time greater than that of the median of the 11 previous blocks. This +GetMedianTimePast() time has a key feature we generally associate with +time: it can't go backwards. + +[BIP113][] specifies a soft fork (**not enforced in this release**) that +weakens this perverse incentive for individual miners to use a future +time by requiring that valid blocks have a computed GetMedianTimePast() +greater than the locktime specified in any transaction in that block. + +Mempool inclusion rules currently require transactions to be valid for +immediate inclusion in a block in order to be accepted into the mempool. +This release begins applying the BIP113 rule to received transactions, +so transaction whose time is greater than the GetMedianTimePast() will +no longer be accepted into the mempool. + +**Implication for miners:** you will begin rejecting transactions that +would not be valid under BIP113, which will prevent you from producing +invalid blocks if/when BIP113 is enforced on the network. Any +transactions which are valid under the current rules but not yet valid +under the BIP113 rules will either be mined by other miners or delayed +until they are valid under BIP113. Note, however, that time-based +locktime transactions are more or less unseen on the network currently. + +**Implication for users:** GetMedianTimePast() always trails behind the +current time, so a transaction locktime set to the present time will be +rejected by nodes running this release until the median time moves +forward. To compensate, subtract one hour (3,600 seconds) from your +locktimes to allow those transactions to be included in mempools at +approximately the expected time. + +[BIP113]: https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki + +Windows bug fix for corrupted UTXO database on unclean shutdowns +---------------------------------------------------------------- + +Several Windows users reported that they often need to reindex the +entire blockchain after an unclean shutdown of Bitcoin Core on Windows +(or an unclean shutdown of Windows itself). Although unclean shutdowns +remain unsafe, this release no longer relies on memory-mapped files for +the UTXO database, which significantly reduced the frequency of unclean +shutdowns leading to required reindexes during testing. + +For more information, see: <https://github.com/bitcoin/bitcoin/pull/6917> + +Other fixes for database corruption on Windows are expected in the +next major release. + +0.11.2 Change log +================= + +Detailed release notes follow. This overview includes changes that affect +behavior, not code moves, refactors and string updates. For convenience in locating +the code changes and accompanying discussion, both the pull request and +git merge commit are mentioned. + +- #6124 `684636b` Make CScriptNum() take nMaxNumSize as an argument +- #6124 `4fa7a04` Replace NOP2 with CHECKLOCKTIMEVERIFY (BIP65) +- #6124 `6ea5ca4` Enable CHECKLOCKTIMEVERIFY as a standard script verify flag +- #6351 `5e82e1c` Add CHECKLOCKTIMEVERIFY (BIP65) soft-fork logic +- #6353 `ba1da90` Show softfork status in getblockchaininfo +- #6351 `6af25b0` Add BIP65 to getblockchaininfo softforks list +- #6688 `01878c9` Fix locking in GetTransaction +- #6653 `b3eaa30` [Qt] Raise debug window when requested +- #6600 `1e672ae` Debian/Ubuntu: Include bitcoin-tx binary +- #6600 `2394f4d` Debian/Ubuntu: Split bitcoin-tx into its own package +- #5987 `33d6825` Bugfix: Allow mining on top of old tip blocks for testnet +- #6852 `21e58b8` build: make sure OpenSSL heeds noexecstack +- #6846 `af6edac` alias `-h` for `--help` +- #6867 `95a5039` Set TCP_NODELAY on P2P sockets. +- #6856 `dfe55bd` Do not allow blockfile pruning during reindex. +- #6566 `a1d3c6f` Add rules--presently disabled--for using GetMedianTimePast as end point for lock-time calculations +- #6566 `f720c5f` Enable policy enforcing GetMedianTimePast as the end point of lock-time constraints +- #6917 `0af5b8e` leveldb: Win32WritableFile without memory mapping +- #6948 `4e895b0` Always flush block and undo when switching to new file + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Alex Morcos +- ฿tcDrak +- Chris Kleeschulte +- Daniel Cousens +- Diego Viola +- Eric Lombrozo +- Esteban Ordano +- Gregory Maxwell +- Luke Dashjr +- Marco Falke +- Mark Friedenbach +- Matt Corallo +- Micha +- Mitchell Cash +- Peter Todd +- Pieter Wuille +- Wladimir J. van der Laan +- Zak Wilcox + +And those who contributed additional code review and/or security research. + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-notes/release-notes-0.12.0.md b/doc/release-notes/release-notes-0.12.0.md new file mode 100644 index 0000000000..cf74a17975 --- /dev/null +++ b/doc/release-notes/release-notes-0.12.0.md @@ -0,0 +1,894 @@ +Bitcoin Core version 0.12.0 is now available from: + + <https://bitcoin.org/bin/bitcoin-core-0.12.0/> + +This is a new major version release, bringing new features and other improvements. + +Please report bugs using the issue tracker at github: + + <https://github.com/bitcoin/bitcoin/issues> + +Upgrading and downgrading +========================= + +How to Upgrade +-------------- + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Downgrade warning +----------------- + +### Downgrade to a version < 0.10.0 + +Because release 0.10.0 and later makes use of headers-first synchronization and +parallel block download (see further), the block files and databases are not +backwards-compatible with pre-0.10 versions of Bitcoin Core or other software: + +* Blocks will be stored on disk out of order (in the order they are +received, really), which makes it incompatible with some tools or +other programs. Reindexing using earlier versions will also not work +anymore as a result of this. + +* The block index database will now hold headers for which no block is +stored on disk, which earlier versions won't support. + +If you want to be able to downgrade smoothly, make a backup of your entire data +directory. Without this your node will need start syncing (or importing from +bootstrap.dat) anew afterwards. It is possible that the data from a completely +synchronised 0.10 node may be usable in older versions as-is, but this is not +supported and may break as soon as the older version attempts to reindex. + +This does not affect wallet forward or backward compatibility. + +### Downgrade to a version < 0.12.0 + +Because release 0.12.0 and later will obfuscate the chainstate on every +fresh sync or reindex, the chainstate is not backwards-compatible with +pre-0.12 versions of Bitcoin Core or other software. + +If you want to downgrade after you have done a reindex with 0.12.0 or later, +you will need to reindex when you first start Bitcoin Core version 0.11 or +earlier. + +Notable changes +=============== + +Signature validation using libsecp256k1 +--------------------------------------- + +ECDSA signatures inside Bitcoin transactions now use validation using +[libsecp256k1](https://github.com/bitcoin-core/secp256k1) instead of OpenSSL. + +Depending on the platform, this means a significant speedup for raw signature +validation speed. The advantage is largest on x86_64, where validation is over +five times faster. In practice, this translates to a raw reindexing and new +block validation times that are less than half of what it was before. + +Libsecp256k1 has undergone very extensive testing and validation. + +A side effect of this change is that libconsensus no longer depends on OpenSSL. + +Reduce upload traffic +--------------------- + +A major part of the outbound traffic is caused by serving historic blocks to +other nodes in initial block download state. + +It is now possible to reduce the total upload traffic via the `-maxuploadtarget` +parameter. This is *not* a hard limit but a threshold to minimize the outbound +traffic. When the limit is about to be reached, the uploaded data is cut by not +serving historic blocks (blocks older than one week). +Moreover, any SPV peer is disconnected when they request a filtered block. + +This option can be specified in MiB per day and is turned off by default +(`-maxuploadtarget=0`). +The recommended minimum is 144 * MAX_BLOCK_SIZE (currently 144MB) per day. + +Whitelisted peers will never be disconnected, although their traffic counts for +calculating the target. + +A more detailed documentation about keeping traffic low can be found in +[/doc/reduce-traffic.md](/doc/reduce-traffic.md). + +Direct headers announcement (BIP 130) +------------------------------------- + +Between compatible peers, [BIP 130] +(https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki) +direct headers announcement is used. This means that blocks are advertised by +announcing their headers directly, instead of just announcing the hash. In a +reorganization, all new headers are sent, instead of just the new tip. This +can often prevent an extra roundtrip before the actual block is downloaded. + +Memory pool limiting +-------------------- + +Previous versions of Bitcoin Core had their mempool limited by checking +a transaction's fees against the node's minimum relay fee. There was no +upper bound on the size of the mempool and attackers could send a large +number of transactions paying just slighly more than the default minimum +relay fee to crash nodes with relatively low RAM. A temporary workaround +for previous versions of Bitcoin Core was to raise the default minimum +relay fee. + +Bitcoin Core 0.12 will have a strict maximum size on the mempool. The +default value is 300 MB and can be configured with the `-maxmempool` +parameter. Whenever a transaction would cause the mempool to exceed +its maximum size, the transaction that (along with in-mempool descendants) has +the lowest total feerate (as a package) will be evicted and the node's effective +minimum relay feerate will be increased to match this feerate plus the initial +minimum relay feerate. The initial minimum relay feerate is set to +1000 satoshis per kB. + +Bitcoin Core 0.12 also introduces new default policy limits on the length and +size of unconfirmed transaction chains that are allowed in the mempool +(generally limiting the length of unconfirmed chains to 25 transactions, with a +total size of 101 KB). These limits can be overriden using command line +arguments; see the extended help (`--help -help-debug`) for more information. + +Opt-in Replace-by-fee transactions +---------------------------------- + +It is now possible to replace transactions in the transaction memory pool of +Bitcoin Core 0.12 nodes. Bitcoin Core will only allow replacement of +transactions which have any of their inputs' `nSequence` number set to less +than `0xffffffff - 1`. Moreover, a replacement transaction may only be +accepted when it pays sufficient fee, as described in [BIP 125] +(https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki). + +Transaction replacement can be disabled with a new command line option, +`-mempoolreplacement=0`. Transactions signaling replacement under BIP125 will +still be allowed into the mempool in this configuration, but replacements will +be rejected. This option is intended for miners who want to continue the +transaction selection behavior of previous releases. + +The `-mempoolreplacement` option is *not recommended* for wallet users seeking +to avoid receipt of unconfirmed opt-in transactions, because this option does +not prevent transactions which are replaceable under BIP 125 from being accepted +(only subsequent replacements, which other nodes on the network that implement +BIP 125 are likely to relay and mine). Wallet users wishing to detect whether +a transaction is subject to replacement under BIP 125 should instead use the +updated RPC calls `gettransaction` and `listtransactions`, which now have an +additional field in the output indicating if a transaction is replaceable under +BIP125 ("bip125-replaceable"). + +Note that the wallet in Bitcoin Core 0.12 does not yet have support for +creating transactions that would be replaceable under BIP 125. + + +RPC: Random-cookie RPC authentication +------------------------------------- + +When no `-rpcpassword` is specified, the daemon now uses a special 'cookie' +file for authentication. This file is generated with random content when the +daemon starts, and deleted when it exits. Its contents are used as +authentication token. Read access to this file controls who can access through +RPC. By default it is stored in the data directory but its location can be +overridden with the option `-rpccookiefile`. + +This is similar to Tor's CookieAuthentication: see +https://www.torproject.org/docs/tor-manual.html.en + +This allows running bitcoind without having to do any manual configuration. + +Relay: Any sequence of pushdatas in OP_RETURN outputs now allowed +----------------------------------------------------------------- + +Previously OP_RETURN outputs with a payload were only relayed and mined if they +had a single pushdata. This restriction has been lifted to allow any +combination of data pushes and numeric constant opcodes (OP_1 to OP_16) after +the OP_RETURN. The limit on OP_RETURN output size is now applied to the entire +serialized scriptPubKey, 83 bytes by default. (the previous 80 byte default plus +three bytes overhead) + +Relay: New and only new blocks relayed when pruning +--------------------------------------------------- + +When running in pruned mode, the client will now relay new blocks. When +responding to the `getblocks` message, only hashes of blocks that are on disk +and are likely to remain there for some reasonable time window (1 hour) will be +returned (previously all relevant hashes were returned). + +Relay and Mining: Priority transactions +--------------------------------------- + +Bitcoin Core has a heuristic 'priority' based on coin value and age. This +calculation is used for relaying of transactions which do not pay the +minimum relay fee, and can be used as an alternative way of sorting +transactions for mined blocks. Bitcoin Core will relay transactions with +insufficient fees depending on the setting of `-limitfreerelay=<r>` (default: +`r=15` kB per minute) and `-blockprioritysize=<s>`. + +In Bitcoin Core 0.12, when mempool limit has been reached a higher minimum +relay fee takes effect to limit memory usage. Transactions which do not meet +this higher effective minimum relay fee will not be relayed or mined even if +they rank highly according to the priority heuristic. + +The mining of transactions based on their priority is also now disabled by +default. To re-enable it, simply set `-blockprioritysize=<n>` where is the size +in bytes of your blocks to reserve for these transactions. The old default was +50k, so to retain approximately the same policy, you would set +`-blockprioritysize=50000`. + +Additionally, as a result of computational simplifications, the priority value +used for transactions received with unconfirmed inputs is lower than in prior +versions due to avoiding recomputing the amounts as input transactions confirm. + +External miner policy set via the `prioritisetransaction` RPC to rank +transactions already in the mempool continues to work as it has previously. +Note, however, that if mining priority transactions is left disabled, the +priority delta will be ignored and only the fee metric will be effective. + +This internal automatic prioritization handling is being considered for removal +entirely in Bitcoin Core 0.13, and it is at this time undecided whether the +more accurate priority calculation for chained unconfirmed transactions will be +restored. Community direction on this topic is particularly requested to help +set project priorities. + +Automatically use Tor hidden services +------------------------------------- + +Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket +API, to create and destroy 'ephemeral' hidden services programmatically. +Bitcoin Core has been updated to make use of this. + +This means that if Tor is running (and proper authorization is available), +Bitcoin Core automatically creates a hidden service to listen on, without +manual configuration. Bitcoin Core will also use Tor automatically to connect +to other .onion nodes if the control socket can be successfully opened. This +will positively affect the number of available .onion nodes and their usage. + +This new feature is enabled by default if Bitcoin Core is listening, and +a connection to Tor can be made. It can be configured with the `-listenonion`, +`-torcontrol` and `-torpassword` settings. To show verbose debugging +information, pass `-debug=tor`. + +Notifications through ZMQ +------------------------- + +Bitcoind can now (optionally) asynchronously notify clients through a +ZMQ-based PUB socket of the arrival of new transactions and blocks. +This feature requires installation of the ZMQ C API library 4.x and +configuring its use through the command line or configuration file. +Please see [docs/zmq.md](/doc/zmq.md) for details of operation. + +Wallet: Transaction fees +------------------------ + +Various improvements have been made to how the wallet calculates +transaction fees. + +Users can decide to pay a predefined fee rate by setting `-paytxfee=<n>` +(or `settxfee <n>` rpc during runtime). A value of `n=0` signals Bitcoin +Core to use floating fees. By default, Bitcoin Core will use floating +fees. + +Based on past transaction data, floating fees approximate the fees +required to get into the `m`th block from now. This is configurable +with `-txconfirmtarget=<m>` (default: `2`). + +Sometimes, it is not possible to give good estimates, or an estimate +at all. Therefore, a fallback value can be set with `-fallbackfee=<f>` +(default: `0.0002` BTC/kB). + +At all times, Bitcoin Core will cap fees at `-maxtxfee=<x>` (default: +0.10) BTC. +Furthermore, Bitcoin Core will never create transactions paying less than +the current minimum relay fee. +Finally, a user can set the minimum fee rate for all transactions with +`-mintxfee=<i>`, which defaults to 1000 satoshis per kB. + +Wallet: Negative confirmations and conflict detection +----------------------------------------------------- + +The wallet will now report a negative number for confirmations that indicates +how deep in the block chain the conflict is found. For example, if a transaction +A has 5 confirmations and spends the same input as a wallet transaction B, B +will be reported as having -5 confirmations. If another wallet transaction C +spends an output from B, it will also be reported as having -5 confirmations. +To detect conflicts with historical transactions in the chain a one-time +`-rescan` may be needed. + +Unlike earlier versions, unconfirmed but non-conflicting transactions will never +get a negative confirmation count. They are not treated as spendable unless +they're coming from ourself (change) and accepted into our local mempool, +however. The new "trusted" field in the `listtransactions` RPC output +indicates whether outputs of an unconfirmed transaction are considered +spendable. + +Wallet: Merkle branches removed +------------------------------- + +Previously, every wallet transaction stored a Merkle branch to prove its +presence in blocks. This wasn't being used for more than an expensive +sanity check. Since 0.12, these are no longer stored. When loading a +0.12 wallet into an older version, it will automatically rescan to avoid +failed checks. + +Wallet: Pruning +--------------- + +With 0.12 it is possible to use wallet functionality in pruned mode. +This can reduce the disk usage from currently around 60 GB to +around 2 GB. + +However, rescans as well as the RPCs `importwallet`, `importaddress`, +`importprivkey` are disabled. + +To enable block pruning set `prune=<N>` on the command line or in +`bitcoin.conf`, where `N` is the number of MiB to allot for +raw block & undo data. + +A value of 0 disables pruning. The minimal value above 0 is 550. Your +wallet is as secure with high values as it is with low ones. Higher +values merely ensure that your node will not shut down upon blockchain +reorganizations of more than 2 days - which are unlikely to happen in +practice. In future releases, a higher value may also help the network +as a whole: stored blocks could be served to other nodes. + +For further information about pruning, you may also consult the [release +notes of v0.11.0](https://github.com/bitcoin/bitcoin/blob/v0.11.0/doc/release-notes.md#block-file-pruning). + +`NODE_BLOOM` service bit +------------------------ + +Support for the `NODE_BLOOM` service bit, as described in [BIP +111](https://github.com/bitcoin/bips/blob/master/bip-0111.mediawiki), has been +added to the P2P protocol code. + +BIP 111 defines a service bit to allow peers to advertise that they support +bloom filters (such as used by SPV clients) explicitly. It also bumps the protocol +version to allow peers to identify old nodes which allow bloom filtering of the +connection despite lacking the new service bit. + +In this version, it is only enforced for peers that send protocol versions +`>=70011`. For the next major version it is planned that this restriction will be +removed. It is recommended to update SPV clients to check for the `NODE_BLOOM` +service bit for nodes that report versions newer than 70011. + +Option parsing behavior +----------------------- + +Command line options are now parsed strictly in the order in which they are +specified. It used to be the case that `-X -noX` ends up, unintuitively, with X +set, as `-X` had precedence over `-noX`. This is no longer the case. Like for +other software, the last specified value for an option will hold. + +RPC: Low-level API changes +-------------------------- + +- Monetary amounts can be provided as strings. This means that for example the + argument to sendtoaddress can be "0.0001" instead of 0.0001. This can be an + advantage if a JSON library insists on using a lossy floating point type for + numbers, which would be dangerous for monetary amounts. + +* The `asm` property of each scriptSig now contains the decoded signature hash + type for each signature that provides a valid defined hash type. + +* OP_NOP2 has been renamed to OP_CHECKLOCKTIMEVERIFY by [BIP 65](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki) + +The following items contain assembly representations of scriptSig signatures +and are affected by this change: + +- RPC `getrawtransaction` +- RPC `decoderawtransaction` +- RPC `decodescript` +- REST `/rest/tx/` (JSON format) +- REST `/rest/block/` (JSON format when including extended tx details) +- `bitcoin-tx -json` + +For example, the `scriptSig.asm` property of a transaction input that +previously showed an assembly representation of: + + 304502207fa7a6d1e0ee81132a269ad84e68d695483745cde8b541e3bf630749894e342a022100c1f7ab20e13e22fb95281a870f3dcf38d782e53023ee313d741ad0cfbc0c509001 400000 OP_NOP2 + +now shows as: + + 304502207fa7a6d1e0ee81132a269ad84e68d695483745cde8b541e3bf630749894e342a022100c1f7ab20e13e22fb95281a870f3dcf38d782e53023ee313d741ad0cfbc0c5090[ALL] 400000 OP_CHECKLOCKTIMEVERIFY + +Note that the output of the RPC `decodescript` did not change because it is +configured specifically to process scriptPubKey and not scriptSig scripts. + +RPC: SSL support dropped +------------------------ + +SSL support for RPC, previously enabled by the option `rpcssl` has been dropped +from both the client and the server. This was done in preparation for removing +the dependency on OpenSSL for the daemon completely. + +Trying to use `rpcssl` will result in an error: + + Error: SSL mode for RPC (-rpcssl) is no longer supported. + +If you are one of the few people that relies on this feature, a flexible +migration path is to use `stunnel`. This is an utility that can tunnel +arbitrary TCP connections inside SSL. On e.g. Ubuntu it can be installed with: + + sudo apt-get install stunnel4 + +Then, to tunnel a SSL connection on 28332 to a RPC server bound on localhost on port 18332 do: + + stunnel -d 28332 -r 127.0.0.1:18332 -p stunnel.pem -P '' + +It can also be set up system-wide in inetd style. + +Another way to re-attain SSL would be to setup a httpd reverse proxy. This solution +would allow the use of different authentication, loadbalancing, on-the-fly compression and +caching. A sample config for apache2 could look like: + + Listen 443 + + NameVirtualHost *:443 + <VirtualHost *:443> + + SSLEngine On + SSLCertificateFile /etc/apache2/ssl/server.crt + SSLCertificateKeyFile /etc/apache2/ssl/server.key + + <Location /bitcoinrpc> + ProxyPass http://127.0.0.1:8332/ + ProxyPassReverse http://127.0.0.1:8332/ + # optional enable digest auth + # AuthType Digest + # ... + + # optional bypass bitcoind rpc basic auth + # RequestHeader set Authorization "Basic <hash>" + # get the <hash> from the shell with: base64 <<< bitcoinrpc:<password> + </Location> + + # Or, balance the load: + # ProxyPass / balancer://balancer_cluster_name + + </VirtualHost> + +Mining Code Changes +------------------- + +The mining code in 0.12 has been optimized to be significantly faster and use less +memory. As part of these changes, consensus critical calculations are cached on a +transaction's acceptance into the mempool and the mining code now relies on the +consistency of the mempool to assemble blocks. However all blocks are still tested +for validity after assembly. + +Other P2P Changes +----------------- + +The list of banned peers is now stored on disk rather than in memory. +Restarting bitcoind will no longer clear out the list of banned peers; instead +a new RPC call (`clearbanned`) can be used to manually clear the list. The new +`setban` RPC call can also be used to manually ban or unban a peer. + +0.12.0 Change log +================= + +Detailed release notes follow. This overview includes changes that affect +behavior, not code moves, refactors and string updates. For convenience in locating +the code changes and accompanying discussion, both the pull request and +git merge commit are mentioned. + +### RPC and REST + +- #6121 `466f0ea` Convert entire source tree from json_spirit to UniValue (Jonas Schnelli) +- #6234 `d38cd47` fix rpcmining/getblocktemplate univalue transition logic error (Jonas Schnelli) +- #6239 `643114f` Don't go through double in AmountFromValue and ValueFromAmount (Wladimir J. van der Laan) +- #6266 `ebab5d3` Fix univalue handling of \u0000 characters. (Daniel Kraft) +- #6276 `f3d4dbb` Fix getbalance * 0 (Tom Harding) +- #6257 `5ebe7db` Add `paytxfee` and `errors` JSON fields where appropriate (Stephen) +- #6271 `754aae5` New RPC command disconnectnode (Alex van der Peet) +- #6158 `0abfa8a` Add setban/listbanned RPC commands (Jonas Schnelli) +- #6307 `7ecdcd9` rpcban fixes (Jonas Schnelli) +- #6290 `5753988` rpc: make `gettxoutsettinfo` run lock-free (Wladimir J. van der Laan) +- #6262 `247b914` Return all available information via RPC call "validateaddress" (dexX7) +- #6339 `c3f0490` UniValue: don't escape solidus, keep espacing of reverse solidus (Jonas Schnelli) +- #6353 `6bcb0a2` Show softfork status in getblockchaininfo (Wladimir J. van der Laan) +- #6247 `726e286` Add getblockheader RPC call (Peter Todd) +- #6362 `d6db115` Fix null id in RPC response during startup (Forrest Voight) +- #5486 `943b322` [REST] JSON support for /rest/headers (Jonas Schnelli) +- #6379 `c52e8b3` rpc: Accept scientific notation for monetary amounts in JSON (Wladimir J. van der Laan) +- #6388 `fd5dfda` rpc: Implement random-cookie based authentication (Wladimir J. van der Laan) +- #6457 `3c923e8` Include pruned state in chaininfo.json (Simon Males) +- #6456 `bfd807f` rpc: Avoid unnecessary parsing roundtrip in number formatting, fix locale issue (Wladimir J. van der Laan) +- #6380 `240b30e` rpc: Accept strings in AmountFromValue (Wladimir J. van der Laan) +- #6346 `6bb2805` Add OP_RETURN support in createrawtransaction RPC call, add tests. (paveljanik) +- #6013 `6feeec1` [REST] Add memory pool API (paveljanik) +- #6576 `da9beb2` Stop parsing JSON after first finished construct. (Daniel Kraft) +- #5677 `9aa9099` libevent-based http server (Wladimir J. van der Laan) +- #6633 `bbc2b39` Report minimum ping time in getpeerinfo (Matt Corallo) +- #6648 `cd381d7` Simplify logic of REST request suffix parsing. (Daniel Kraft) +- #6695 `5e21388` libevent http fixes (Wladimir J. van der Laan) +- #5264 `48efbdb` show scriptSig signature hash types in transaction decodes. fixes #3166 (mruddy) +- #6719 `1a9f19a` Make HTTP server shutdown more graceful (Wladimir J. van der Laan) +- #6859 `0fbfc51` http: Restrict maximum size of http + headers (Wladimir J. van der Laan) +- #5936 `bf7c195` [RPC] Add optional locktime to createrawtransaction (Tom Harding) +- #6877 `26f5b34` rpc: Add maxmempool and effective min fee to getmempoolinfo (Wladimir J. van der Laan) +- #6970 `92701b3` Fix crash in validateaddress with -disablewallet (Wladimir J. van der Laan) +- #5574 `755b4ba` Expose GUI labels in RPC as comments (Luke-Jr) +- #6990 `dbd2c13` http: speed up shutdown (Wladimir J. van der Laan) +- #7013 `36baa9f` Remove LOCK(cs_main) from decodescript (Peter Todd) +- #6999 `972bf9c` add (max)uploadtarget infos to getnettotals RPC help (Jonas Schnelli) +- #7011 `31de241` Add mediantime to getblockchaininfo (Peter Todd) +- #7065 `f91e29f` http: add Boost 1.49 compatibility (Wladimir J. van der Laan) +- #7087 `be281d8` [Net]Add -enforcenodebloom option (Patrick Strateman) +- #7044 `438ee59` RPC: Added additional config option for multiple RPC users. (Gregory Sanders) +- #7072 `c143c49` [RPC] Add transaction size to JSON output (Nikita Zhavoronkov) +- #7022 `9afbd96` Change default block priority size to 0 (Alex Morcos) +- #7141 `c0c08c7` rpc: Don't translate warning messages (Wladimir J. van der Laan) +- #7312 `fd4bd50` Add RPC call abandontransaction (Alex Morcos) +- #7222 `e25b158` RPC: indicate which transactions are replaceable (Suhas Daftuar) +- #7472 `b2f2b85` rpc: Add WWW-Authenticate header to 401 response (Wladimir J. van der Laan) +- #7469 `9cb31e6` net.h fix spelling: misbeha{b,v}ing (Matt) + +### Configuration and command-line options + +- #6164 `8d05ec7` Allow user to use -debug=1 to enable all debugging (lpescher) +- #5288 `4452205` Added `-whiteconnections=<n>` option (Josh Lehan) +- #6284 `10ac38e` Fix argument parsing oddity with -noX (Wladimir J. van der Laan) +- #6489 `c9c017a` Give a better error message if system clock is bad (Casey Rodarmor) +- #6462 `c384800` implement uacomment config parameter which can add comments to user agent as per BIP-0014 (Pavol Rusnak) +- #6647 `a3babc8` Sanitize uacomment (MarcoFalke) +- #6742 `3b2d37c` Changed logging to make -logtimestamps to work also for -printtoconsole (arnuschky) +- #6846 `2cd020d` alias -h for -help (Daniel Cousens) +- #6622 `7939164` Introduce -maxuploadtarget (Jonas Schnelli) +- #6881 `2b62551` Debug: Add option for microsecond precision in debug.log (Suhas Daftuar) +- #6776 `e06c14f` Support -checkmempool=N, which runs checks once every N transactions (Pieter Wuille) +- #6896 `d482c0a` Make -checkmempool=1 not fail through int32 overflow (Pieter Wuille) +- #6993 `b632145` Add -blocksonly option (Patrick Strateman) +- #7323 `a344880` 0.12: Backport -bytespersigop option (Luke-Jr) +- #7386 `da83ecd` Add option `-permitrbf` to set transaction replacement policy (Wladimir J. van der Laan) +- #7290 `b16b5bc` Add missing options help (MarcoFalke) +- #7440 `c76bfff` Rename permitrbf to mempoolreplacement and provide minimal string-list forward compatibility (Luke-Jr) + +### Block and transaction handling + +- #6203 `f00b623` Remove P2SH coinbase flag, no longer interesting (Luke-Jr) +- #6222 `9c93ee5` Explicitly set tx.nVersion for the genesis block and mining tests (Mark Friedenbach) +- #5985 `3a1d3e8` Fix removing of orphan transactions (Alex Morcos) +- #6221 `dd8fe82` Prune: Support noncontiguous block files (Adam Weiss) +- #6124 `41076aa` Mempool only CHECKLOCKTIMEVERIFY (BIP65) verification, unparameterized version (Peter Todd) +- #6329 `d0a10c1` acceptnonstdtxn option to skip (most) "non-standard transaction" checks, for testnet/regtest only (Luke-Jr) +- #6410 `7cdefb9` Implement accurate memory accounting for mempool (Pieter Wuille) +- #6444 `24ce77d` Exempt unspendable transaction outputs from dust checks (dexX7) +- #5913 `a0625b8` Add absurdly high fee message to validation state (Shaul Kfir) +- #6177 `2f746c6` Prevent block.nTime from decreasing (Mark Friedenbach) +- #6377 `e545371` Handle no chain tip available in InvalidChainFound() (Ross Nicoll) +- #6551 `39ddaeb` Handle leveldb::DestroyDB() errors on wipe failure (Adam Weiss) +- #6654 `b0ce450` Mempool package tracking (Suhas Daftuar) +- #6715 `82d2aef` Fix mempool packages (Suhas Daftuar) +- #6680 `4f44530` use CBlockIndex instead of uint256 for UpdatedBlockTip signal (Jonas Schnelli) +- #6650 `4fac576` Obfuscate chainstate (James O'Beirne) +- #6777 `9caaf6e` Unobfuscate chainstate data in CCoinsViewDB::GetStats (James O'Beirne) +- #6722 `3b20e23` Limit mempool by throwing away the cheapest txn and setting min relay fee to it (Matt Corallo) +- #6889 `38369dd` fix locking issue with new mempool limiting (Jonas Schnelli) +- #6464 `8f3b3cd` Always clean up manual transaction prioritization (Casey Rodarmor) +- #6865 `d0badb9` Fix chainstate serialized_size computation (Pieter Wuille) +- #6566 `ff057f4` BIP-113: Mempool-only median time-past as endpoint for lock-time calculations (Mark Friedenbach) +- #6934 `3038eb6` Restores mempool only BIP113 enforcement (Gregory Maxwell) +- #6965 `de7d459` Benchmark sanity checks and fork checks in ConnectBlock (Matt Corallo) +- #6918 `eb6172a` Make sigcache faster, more efficient, larger (Pieter Wuille) +- #6771 `38ed190` Policy: Lower default limits for tx chains (Alex Morcos) +- #6932 `73fa5e6` ModifyNewCoins saves database lookups (Alex Morcos) +- #5967 `05d5918` Alter assumptions in CCoinsViewCache::BatchWrite (Alex Morcos) +- #6871 `0e93586` nSequence-based Full-RBF opt-in (Peter Todd) +- #7008 `eb77416` Lower bound priority (Alex Morcos) +- #6915 `2ef5ffa` [Mempool] Improve removal of invalid transactions after reorgs (Suhas Daftuar) +- #6898 `4077ad2` Rewrite CreateNewBlock (Alex Morcos) +- #6872 `bdda4d5` Remove UTXO cache entries when the tx they were added for is removed/does not enter mempool (Matt Corallo) +- #7062 `12c469b` [Mempool] Fix mempool limiting and replace-by-fee for PrioritiseTransaction (Suhas Daftuar) +- #7276 `76de36f` Report non-mandatory script failures correctly (Pieter Wuille) +- #7217 `e08b7cb` Mark blocks with too many sigops as failed (Suhas Daftuar) +- #7387 `f4b2ce8` Get rid of inaccurate ScriptSigArgsExpected (Pieter Wuille) + +### P2P protocol and network code + +- #6172 `88a7ead` Ignore getheaders requests when not synced (Suhas Daftuar) +- #5875 `9d60602` Be stricter in processing unrequested blocks (Suhas Daftuar) +- #6256 `8ccc07c` Use best header chain timestamps to detect partitioning (Gavin Andresen) +- #6283 `a903ad7` make CAddrMan::size() return the correct type of size_t (Diapolo) +- #6272 `40400d5` Improve proxy initialization (continues #4871) (Wladimir J. van der Laan, Diapolo) +- #6310 `66e5465` banlist.dat: store banlist on disk (Jonas Schnelli) +- #6412 `1a2de32` Test whether created sockets are select()able (Pieter Wuille) +- #6498 `219b916` Keep track of recently rejected transactions with a rolling bloom filter (cont'd) (Peter Todd) +- #6556 `70ec975` Fix masking of irrelevant bits in address groups. (Alex Morcos) +- #6530 `ea19c2b` Improve addrman Select() performance when buckets are nearly empty (Pieter Wuille) +- #6583 `af9305a` add support for miniupnpc api version 14 (Pavel Vasin) +- #6374 `69dc5b5` Connection slot exhaustion DoS mitigation (Patrick Strateman) +- #6636 `536207f` net: correctly initialize nMinPingUsecTime (Wladimir J. van der Laan) +- #6579 `0c27795` Add NODE_BLOOM service bit and bump protocol version (Matt Corallo) +- #6148 `999c8be` Relay blocks when pruning (Suhas Daftuar) +- #6588 `cf9bb11` In (strCommand == "tx"), return if AlreadyHave() (Tom Harding) +- #6974 `2f71b07` Always allow getheaders from whitelisted peers (Wladimir J. van der Laan) +- #6639 `bd629d7` net: Automatically create hidden service, listen on Tor (Wladimir J. van der Laan) +- #6984 `9ffc687` don't enforce maxuploadtarget's disconnect for whitelisted peers (Jonas Schnelli) +- #7046 `c322652` Net: Improve blocks only mode. (Patrick Strateman) +- #7090 `d6454f6` Connect to Tor hidden services by default (when listening on Tor) (Peter Todd) +- #7106 `c894fbb` Fix and improve relay from whitelisted peers (Pieter Wuille) +- #7129 `5d5ef3a` Direct headers announcement (rebase of #6494) (Pieter Wuille) +- #7079 `1b5118b` Prevent peer flooding inv request queue (redux) (redux) (Gregory Maxwell) +- #7166 `6ba25d2` Disconnect on mempool requests from peers when over the upload limit. (Gregory Maxwell) +- #7133 `f31955d` Replace setInventoryKnown with a rolling bloom filter (rebase of #7100) (Pieter Wuille) +- #7174 `82aff88` Don't do mempool lookups for "mempool" command without a filter (Matt Corallo) +- #7179 `44fef99` net: Fix sent reject messages for blocks and transactions (Wladimir J. van der Laan) +- #7181 `8fc174a` net: Add and document network messages in protocol.h (Wladimir J. van der Laan) +- #7125 `10b88be` Replace global trickle node with random delays (Pieter Wuille) +- #7415 `cb83beb` net: Hardcoded seeds update January 2016 (Wladimir J. van der Laan) +- #7438 `e2d9a58` Do not absolutely protect local peers; decide group ties based on time (Gregory Maxwell) +- #7439 `86755bc` Add whitelistforcerelay to control forced relaying. [#7099 redux] (Gregory Maxwell) +- #7482 `e16f5b4` Ensure headers count is correct (Suhas Daftuar) + +### Validation + +- #5927 `8d9f0a6` Reduce checkpoints' effect on consensus. (Pieter Wuille) +- #6299 `24f2489` Bugfix: Don't check the genesis block header before accepting it (Jorge Timón) +- #6361 `d7ada03` Use real number of cores for default -par, ignore virtual cores (Wladimir J. van der Laan) +- #6519 `87f37e2` Make logging for validation optional (Wladimir J. van der Laan) +- #6351 `2a1090d` CHECKLOCKTIMEVERIFY (BIP65) IsSuperMajority() soft-fork (Peter Todd) +- #6931 `54e8bfe` Skip BIP 30 verification where not necessary (Alex Morcos) +- #6954 `e54ebbf` Switch to libsecp256k1-based ECDSA validation (Pieter Wuille) +- #6508 `61457c2` Switch to a constant-space Merkle root/branch algorithm. (Pieter Wuille) +- #6914 `327291a` Add pre-allocated vector type and use it for CScript (Pieter Wuille) +- #7500 `889e5b3` Correctly report high-S violations (Pieter Wuille) + + +### Build system + +- #6210 `0e4f2a0` build: disable optional use of gmp in internal secp256k1 build (Wladimir J. van der Laan) +- #6214 `87406aa` [OSX] revert renaming of Bitcoin-Qt.app and use CFBundleDisplayName (partial revert of #6116) (Jonas Schnelli) +- #6218 `9d67b10` build/gitian misc updates (Cory Fields) +- #6269 `d4565b6` gitian: Use the new bitcoin-detached-sigs git repo for OSX signatures (Cory Fields) +- #6418 `d4a910c` Add autogen.sh to source tarball. (randy-waterhouse) +- #6373 `1ae3196` depends: non-qt bumps for 0.12 (Cory Fields) +- #6434 `059b352` Preserve user-passed CXXFLAGS with --enable-debug (Gavin Andresen) +- #6501 `fee6554` Misc build fixes (Cory Fields) +- #6600 `ef4945f` Include bitcoin-tx binary on Debian/Ubuntu (Zak Wilcox) +- #6619 `4862708` depends: bump miniupnpc and ccache (Michael Ford) +- #6801 `ae69a75` [depends] Latest config.guess and config.sub (Michael Ford) +- #6938 `193f7b5` build: If both Qt4 and Qt5 are installed, use Qt5 (Wladimir J. van der Laan) +- #7092 `348b281` build: Set osx permissions in the dmg to make Gatekeeper happy (Cory Fields) +- #6980 `eccd671` [Depends] Bump Boost, miniupnpc, ccache & zeromq (Michael Ford) +- #7424 `aa26ee0` Add security/export checks to gitian and fix current failures (Cory Fields) + +### Wallet + +- #6183 `87550ee` Fix off-by-one error w/ nLockTime in the wallet (Peter Todd) +- #6057 `ac5476e` re-enable wallet in autoprune (Jonas Schnelli) +- #6356 `9e6c33b` Delay initial pruning until after wallet init (Adam Weiss) +- #6088 `91389e5` fundrawtransaction (Matt Corallo) +- #6415 `ddd8d80` Implement watchonly support in fundrawtransaction (Matt Corallo) +- #6567 `0f0f323` Fix crash when mining with empty keypool. (Daniel Kraft) +- #6688 `4939eab` Fix locking in GetTransaction. (Alex Morcos) +- #6645 `4dbd43e` Enable wallet key imports without rescan in pruned mode. (Gregory Maxwell) +- #6550 `5b77244` Do not store Merkle branches in the wallet. (Pieter Wuille) +- #5924 `12a7712` Clean up change computation in CreateTransaction. (Daniel Kraft) +- #6906 `48b5b84` Reject invalid pubkeys when reading ckey items from the wallet. (Gregory Maxwell) +- #7010 `e0a5ef8` Fix fundrawtransaction handling of includeWatching (Peter Todd) +- #6851 `616d61b` Optimisation: Store transaction list order in memory rather than compute it every need (Luke-Jr) +- #6134 `e92377f` Improve usage of fee estimation code (Alex Morcos) +- #7103 `a775182` [wallet, rpc tests] Fix settxfee, paytxfee (MarcoFalke) +- #7105 `30c2d8c` Keep track of explicit wallet conflicts instead of using mempool (Pieter Wuille) +- #7096 `9490bd7` [Wallet] Improve minimum absolute fee GUI options (Jonas Schnelli) +- #6216 `83f06ca` Take the training wheels off anti-fee-sniping (Peter Todd) +- #4906 `96e8d12` Issue#1643: Coinselection prunes extraneous inputs from ApproximateBestSubset (Murch) +- #7200 `06c6a58` Checks for null data transaction before issuing error to debug.log (Andy Craze) +- #7296 `a36d79b` Add sane fallback for fee estimation (Alex Morcos) +- #7293 `ff9b610` Add regression test for vValue sort order (MarcoFalke) +- #7306 `4707797` Make sure conflicted wallet tx's update balances (Alex Morcos) +- #7381 `621bbd8` [walletdb] Fix syntax error in key parser (MarcoFalke) +- #7491 `00ec73e` wallet: Ignore MarkConflict if block hash is not known (Wladimir J. van der Laan) +- #7502 `1329963` Update the wallet best block marker before pruning (Pieter Wuille) + +### GUI + +- #6217 `c57e12a` disconnect peers from peers tab via context menu (Diapolo) +- #6209 `ab0ec67` extend rpc console peers tab (Diapolo) +- #6484 `1369d69` use CHashWriter also in SignVerifyMessageDialog (Pavel Vasin) +- #6487 `9848d42` Introduce PlatformStyle (Wladimir J. van der Laan) +- #6505 `100c9d3` cleanup icons (MarcoFalke) +- #4587 `0c465f5` allow users to set -onion via GUI (Diapolo) +- #6529 `c0f66ce` show client user agent in debug window (Diapolo) +- #6594 `878ea69` Disallow duplicate windows. (Casey Rodarmor) +- #5665 `6f55cdd` add verifySize() function to PaymentServer (Diapolo) +- #6317 `ca5e2a1` minor optimisations in peertablemodel (Diapolo) +- #6315 `e59d2a8` allow banning and unbanning over UI->peers table (Jonas Schnelli) +- #6653 `e04b2fa` Pop debug window in foreground when opened twice (MarcoFalke) +- #6864 `c702521` Use monospace font (MarcoFalke) +- #6887 `3694b74` Update coin control and smartfee labels (MarcoFalke) +- #7000 `814697c` add shortcurts for debug-/console-window (Jonas Schnelli) +- #6951 `03403d8` Use maxTxFee instead of 10000000 (MarcoFalke) +- #7051 `a190777` ui: Add "Copy raw transaction data" to transaction list context menu (Wladimir J. van der Laan) +- #6979 `776848a` simple mempool info in debug window (Jonas Schnelli) +- #7006 `26af1ac` add startup option to reset Qt settings (Jonas Schnelli) +- #6780 `2a94cd6` Call init's parameter interaction before we create the UI options model (Jonas Schnelli) +- #7112 `96b8025` reduce cs_main locks during tip update, more fluently update UI (Jonas Schnelli) +- #7206 `f43c2f9` Add "NODE_BLOOM" to guiutil so that peers don't get UNKNOWN[4] (Matt Corallo) +- #7282 `5cadf3e` fix coincontrol update issue when deleting a send coins entry (Jonas Schnelli) +- #7319 `1320300` Intro: Display required space (MarcoFalke) +- #7318 `9265e89` quickfix for RPC timer interface problem (Jonas Schnelli) +- #7327 `b16b5bc` [Wallet] Transaction View: LastMonth calculation fixed (crowning-) +- #7364 `7726c48` [qt] Windows: Make rpcconsole monospace font larger (MarcoFalke) +- #7384 `294f432` [qt] Peertable: Increase SUBVERSION_COLUMN_WIDTH (MarcoFalke) + +### Tests and QA + +- #6305 `9005c91` build: comparison tool swap (Cory Fields) +- #6318 `e307e13` build: comparison tool NPE fix (Cory Fields) +- #6337 `0564c5b` Testing infrastructure: mocktime fixes (Gavin Andresen) +- #6350 `60abba1` add unit tests for the decodescript rpc (mruddy) +- #5881 `3203a08` Fix and improve txn_doublespend.py test (Tom Harding) +- #6390 `6a73d66` tests: Fix bitcoin-tx signing test case (Wladimir J. van der Laan) +- #6368 `7fc25c2` CLTV: Add more tests to improve coverage (Esteban Ordano) +- #6414 `5121c68` Fix intermittent test failure, reduce test time (Tom Harding) +- #6417 `44fa82d` [QA] fix possible reorg issue in (fund)rawtransaction(s).py RPC test (Jonas Schnelli) +- #6398 `3d9362d` rpc: Remove chain-specific RequireRPCPassword (Wladimir J. van der Laan) +- #6428 `bb59e78` tests: Remove old sh-based test framework (Wladimir J. van der Laan) +- #5515 `d946e9a` RFC: Assert on probable deadlocks if the second lock isnt try_lock (Matt Corallo) +- #6287 `d2464df` Clang lock debug (Cory Fields) +- #6465 `410fd74` Don't share objects between TestInstances (Casey Rodarmor) +- #6534 `6c1c7fd` Fix test locking issues and un-revert the probable-deadlines assertions commit (Cory Fields) +- #6509 `bb4faee` Fix race condition on test node shutdown (Casey Rodarmor) +- #6523 `561f8af` Add p2p-fullblocktest.py (Casey Rodarmor) +- #6590 `981fd92` Fix stale socket rebinding and re-enable python tests for Windows (Cory Fields) +- #6730 `cb4d6d0` build: Remove dependency of bitcoin-cli on secp256k1 (Wladimir J. van der Laan) +- #6616 `5ab5dca` Regression Tests: Migrated rpc-tests.sh to all Python rpc-tests.py (Peter Tschipper) +- #6720 `d479311` Creates unittests for addrman, makes addrman more testable. (Ethan Heilman) +- #6853 `c834f56` Added fPowNoRetargeting field to Consensus::Params (Eric Lombrozo) +- #6827 `87e5539` [rpc-tests] Check return code (MarcoFalke) +- #6848 `f2c869a` Add DERSIG transaction test cases (Ross Nicoll) +- #6813 `5242bb3` Support gathering code coverage data for RPC tests with lcov (dexX7) +- #6888 `c8322ff` Clear strMiscWarning before running PartitionAlert (Eric Lombrozo) +- #6894 `2675276` [Tests] Fix BIP65 p2p test (Suhas Daftuar) +- #6863 `725539e` [Test Suite] Fix test for null tx input (Daniel Kraft) +- #6926 `a6d0d62` tests: Initialize networking on windows (Wladimir J. van der Laan) +- #6822 `9fa54a1` [tests] Be more strict checking dust (MarcoFalke) +- #6804 `5fcc14e` [tests] Add basic coverage reporting for RPC tests (James O'Beirne) +- #7045 `72dccfc` Bugfix: Use unique autostart filenames on Linux for testnet/regtest (Luke-Jr) +- #7095 `d8368a0` Replace scriptnum_test's normative ScriptNum implementation (Wladimir J. van der Laan) +- #7063 `6abf6eb` [Tests] Add prioritisetransaction RPC test (Suhas Daftuar) +- #7137 `16f4a6e` Tests: Explicitly set chain limits in replace-by-fee test (Suhas Daftuar) +- #7216 `9572e49` Removed offline testnet DNSSeed 'alexykot.me'. (tnull) +- #7209 `f3ad812` test: don't override BITCOIND and BITCOINCLI if they're set (Wladimir J. van der Laan) +- #7226 `301f16a` Tests: Add more tests to p2p-fullblocktest (Suhas Daftuar) +- #7153 `9ef7c54` [Tests] Add mempool_limit.py test (Jonas Schnelli) +- #7170 `453c567` tests: Disable Tor interaction (Wladimir J. van der Laan) +- #7229 `1ed938b` [qa] wallet: Check if maintenance changes the balance (MarcoFalke) +- #7308 `d513405` [Tests] Eliminate intermittent failures in sendheaders.py (Suhas Daftuar) +- #7468 `947c4ff` [rpc-tests] Change solve() to use rehash (Brad Andrews) + +### Miscellaneous + +- #6213 `e54ff2f` [init] add -blockversion help and extend -upnp help (Diapolo) +- #5975 `1fea667` Consensus: Decouple ContextualCheckBlockHeader from checkpoints (Jorge Timón) +- #6061 `eba2f06` Separate Consensus::CheckTxInputs and GetSpendHeight in CheckInputs (Jorge Timón) +- #5994 `786ed11` detach wallet from miner (Jonas Schnelli) +- #6387 `11576a5` [bitcoin-cli] improve error output (Jonas Schnelli) +- #6401 `6db53b4` Add BITCOIND_SIGTERM_TIMEOUT to OpenRC init scripts (Florian Schmaus) +- #6430 `b01981e` doc: add documentation for shared library libbitcoinconsensus (Braydon Fuller) +- #6372 `dcc495e` Update Linearize tool to support Windows paths; fix variable scope; update README and example configuration (Paul Georgiou) +- #6453 `8fe5cce` Separate core memory usage computation in core_memusage.h (Pieter Wuille) +- #6149 `633fe10` Buffer log messages and explicitly open logs (Adam Weiss) +- #6488 `7cbed7f` Avoid leaking file descriptors in RegisterLoad (Casey Rodarmor) +- #6497 `a2bf40d` Make sure LogPrintf strings are line-terminated (Wladimir J. van der Laan) +- #6504 `b6fee6b` Rationalize currency unit to "BTC" (Ross Nicoll) +- #6507 `9bb4dd8` Removed contrib/bitrpc (Casey Rodarmor) +- #6527 `41d650f` Use unique name for AlertNotify tempfile (Casey Rodarmor) +- #6561 `e08a7d9` limitedmap fixes and tests (Casey Rodarmor) +- #6565 `a6f2aff` Make sure we re-acquire lock if a task throws (Casey Rodarmor) +- #6599 `f4d88c4` Make sure LogPrint strings are line-terminated (Ross Nicoll) +- #6630 `195942d` Replace boost::reverse_lock with our own (Casey Rodarmor) +- #6103 `13b8282` Add ZeroMQ notifications (João Barbosa) +- #6692 `d5d1d2e` devtools: don't push if signing fails in github-merge (Wladimir J. van der Laan) +- #6728 `2b0567b` timedata: Prevent warning overkill (Wladimir J. van der Laan) +- #6713 `f6ce59c` SanitizeString: Allow hypen char (MarcoFalke) +- #5987 `4899a04` Bugfix: Fix testnet-in-a-box use case (Luke-Jr) +- #6733 `b7d78fd` Simple benchmarking framework (Gavin Andresen) +- #6854 `a092970` devtools: Add security-check.py (Wladimir J. van der Laan) +- #6790 `fa1d252` devtools: add clang-format.py (MarcoFalke) +- #7114 `f3d0fdd` util: Don't set strMiscWarning on every exception (Wladimir J. van der Laan) +- #7078 `93e0514` uint256::GetCheapHash bigendian compatibility (arowser) +- #7094 `34e02e0` Assert now > 0 in GetTime GetTimeMillis GetTimeMicros (Patrick Strateman) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- accraze +- Adam Weiss +- Alex Morcos +- Alex van der Peet +- AlSzacrel +- Altoidnerd +- Andriy Voskoboinyk +- antonio-fr +- Arne Brutschy +- Ashley Holman +- Bob McElrath +- Braydon Fuller +- BtcDrak +- Casey Rodarmor +- centaur1 +- Chris Kleeschulte +- Christian Decker +- Cory Fields +- crowning- +- daniel +- Daniel Cousens +- Daniel Kraft +- David Hill +- dexX7 +- Diego Viola +- Elias Rohrer +- Eric Lombrozo +- Erik Mossberg +- Esteban Ordano +- EthanHeilman +- Florian Schmaus +- Forrest Voight +- Gavin Andresen +- Gregory Maxwell +- Gregory Sanders / instagibbs +- Ian T +- Irving Ruan +- Jacob Welsh +- James O'Beirne +- Jeff Garzik +- Johnathan Corgan +- Jonas Schnelli +- Jonathan Cross +- João Barbosa +- Jorge Timón +- Josh Lehan +- J Ross Nicoll +- kazcw +- Kevin Cooper +- lpescher +- Luke Dashjr +- MarcoFalke +- Mark Friedenbach +- Matt +- Matt Bogosian +- Matt Corallo +- Matt Quinn +- Micha +- Michael +- Michael Ford / fanquake +- Midnight Magic +- Mitchell Cash +- mrbandrews +- mruddy +- Nick +- Patrick Strateman +- Paul Georgiou +- Paul Rabahy +- Pavel Janík / paveljanik +- Pavel Vasin +- Pavol Rusnak +- Peter Josling +- Peter Todd +- Philip Kaufmann +- Pieter Wuille +- ptschip +- randy-waterhouse +- rion +- Ross Nicoll +- Ryan Havar +- Shaul Kfir +- Simon Males +- Stephen +- Suhas Daftuar +- tailsjoin +- Thomas Kerin +- Tom Harding +- tulip +- unsystemizer +- Veres Lajos +- Wladimir J. van der Laan +- xor-freenet +- Zak Wilcox +- zathras-crypto + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-notes/release-notes-0.6.3.md b/doc/release-notes/release-notes-0.6.3.md index 28bb20e104..c27f607b5c 100644 --- a/doc/release-notes/release-notes-0.6.3.md +++ b/doc/release-notes/release-notes-0.6.3.md @@ -23,7 +23,7 @@ hundreds of blocks long. Bitcoin-Qt no longer automatically selects the first address in the address book (Issue #1384). -Fixed minimize-to-dock behavior of Bitcon-Qt on the Mac. +Fixed minimize-to-dock behavior of Bitcoin-Qt on the Mac. Added a block checkpoint at block 185,333 to speed up initial blockchain download. diff --git a/doc/release-notes/release-notes-0.9.4.md b/doc/release-notes/release-notes-0.9.4.md new file mode 100644 index 0000000000..7ee73246a9 --- /dev/null +++ b/doc/release-notes/release-notes-0.9.4.md @@ -0,0 +1,95 @@ +Bitcoin Core version 0.9.4 is now available from: + + https://bitcoin.org/bin/0.9.4/ + +This is a new minor version release, bringing only bug fixes and updated +translations. Upgrading to this release is recommended. + +Please report bugs using the issue tracker at github: + + https://github.com/bitcoin/bitcoin/issues + +How to Upgrade +=============== + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +OpenSSL Warning +================ + +OpenSSL 1.0.0p / 1.0.1k was recently released and is being pushed out by +various operating system maintainers. Review by Gregory Maxwell determined that +this update is incompatible with the Bitcoin system and could lead to consensus +forks. + +Bitcoin Core released binaries from https://bitcoin.org are unaffected, +as are any built with the gitian deterministic build system. + +However, if you are running either + +- The Ubuntu PPA from https://launchpad.net/~bitcoin/+archive/ubuntu/bitcoin +- A third-party or self-compiled Bitcoin Core + +upgrade to Bitcoin Core 0.9.4, which includes a workaround, **before** updating +OpenSSL. + +The incompatibility is due to the OpenSSL update changing the +behavior of ECDSA validation to reject any signature which is +not encoded in a very rigid manner. This was a result of +OpenSSL's change for CVE-2014-8275 "Certificate fingerprints +can be modified". + +We are specifically aware of potential hard-forks due to signature +encoding handling and had been hoping to close them via BIP62 in 0.10. +BIP62's purpose is to improve transaction malleability handling and +as a side effect rigidly defines the encoding for signatures, but the +overall scope of BIP62 has made it take longer than we'd like to +deploy. + +0.9.4 changelog +================ + +Validation: +- `b8e81b7` consensus: guard against openssl's new strict DER checks +- `60c51f1` fail immediately on an empty signature +- `037bfef` Improve robustness of DER recoding code + +Command-line options: +- `cd5164a` Make -proxy set all network types, avoiding a connect leak. + +P2P: +- `bb424e4` Limit the number of new addressses to accumulate + +RPC: +- `0a94661` Disable SSLv3 (in favor of TLS) for the RPC client and server. + +Build system: +- `f047dfa` gitian: openssl-1.0.1i.tar.gz -> openssl-1.0.1k.tar.gz +- `5b9f78d` build: Fix OSX build when using Homebrew and qt5 +- `ffab1dd` Keep symlinks when copying into .app bundle +- `613247f` osx: fix signing to make Gatekeeper happy (again) + +Miscellaneous: +- `25b49b5` Refactor -alertnotify code +- `2743529` doc: Add instructions for consistent Mac OS X build names + +Credits +-------- + +Thanks to who contributed to this release, at least: + +- Cory Fields +- Gavin Andresen +- Gregory Maxwell +- Jeff Garzik +- Luke Dashjr +- Matt Corallo +- Pieter Wuille +- Saivann +- Sergio Demian Lerner +- Wladimir J. van der Laan + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-notes/release-notes-0.9.5.md b/doc/release-notes/release-notes-0.9.5.md new file mode 100644 index 0000000000..bed0af9879 --- /dev/null +++ b/doc/release-notes/release-notes-0.9.5.md @@ -0,0 +1,60 @@ +Bitcoin Core version 0.9.5 is now available from: + + https://bitcoin.org/bin/0.9.5/ + +This is a new minor version release, with the goal of backporting BIP66. There +are also a few bug fixes and updated translations. Upgrading to this release is +recommended. + +Please report bugs using the issue tracker at github: + + https://github.com/bitcoin/bitcoin/issues + +How to Upgrade +=============== + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over /Applications/Bitcoin-Qt (on Mac) or +bitcoind/bitcoin-qt (on Linux). + +Notable changes +================ + +Mining and relay policy enhancements +------------------------------------ + +Bitcoin Core's block templates are now for version 3 blocks only, and any mining +software relying on its `getblocktemplate` must be updated in parallel to use +libblkmaker either version 0.4.2 or any version from 0.5.1 onward. +If you are solo mining, this will affect you the moment you upgrade Bitcoin +Core, which must be done prior to BIP66 achieving its 951/1001 status. +If you are mining with the stratum mining protocol: this does not affect you. +If you are mining with the getblocktemplate protocol to a pool: this will affect +you at the pool operator's discretion, which must be no later than BIP66 +achieving its 951/1001 status. + +0.9.5 changelog +================ + +- `74f29c2` Check pindexBestForkBase for null +- `9cd1dd9` Fix priority calculation in CreateTransaction +- `6b4163b` Sanitize command strings before logging them. +- `3230b32` Raise version of created blocks, and enforce DERSIG in mempool +- `989d499` Backport of some of BIP66's tests +- `ab03660` Implement BIP 66 validation rules and switchover logic +- `8438074` build: fix dynamic boost check when --with-boost= is used + +Credits +-------- + +Thanks to who contributed to this release, at least: + +- 21E14 +- Alex Morcos +- Cory Fields +- Gregory Maxwell +- Pieter Wuille +- Wladimir J. van der Laan + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-process.md b/doc/release-process.md index a16d4ace4a..35ee1edae1 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -1,151 +1,276 @@ Release Process ==================== -* update translations (ping wumpus, Diapolo or tcatm on IRC) -* see https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#syncing-with-transifex +Before every release candidate: -* * * +* Update translations (ping wumpus on IRC) see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations). -###update (commit) version in sources +Before every minor and major release: - contrib/verifysfbinaries/verify.sh - doc/README* - share/setup.nsi - src/clientversion.h (change CLIENT_VERSION_IS_RELEASE to true) +* Update [bips.md](bips.md) to account for changes since the last release. +* Update version in sources (see below) +* Write release notes (see below) -###tag version in git +Before every major release: - git tag -s v(new version, e.g. 0.8.0) +* Update hardcoded [seeds](/contrib/seeds/README.md), see [this pull request](https://github.com/bitcoin/bitcoin/pull/7415) for an example. -###write release notes. git shortlog helps a lot, for example: +### First time / New builders - git shortlog --no-merges v(current version, e.g. 0.7.2)..v(new version, e.g. 0.8.0) +Check out the source code in the following directory hierarchy. -* * * + cd /path/to/your/toplevel/build + git clone https://github.com/bitcoin-core/gitian.sigs.git + git clone https://github.com/bitcoin-core/bitcoin-detached-sigs.git + git clone https://github.com/devrandom/gitian-builder.git + git clone https://github.com/bitcoin/bitcoin.git -###update gitian +### Bitcoin maintainers/release engineers, update version in sources - In order to take advantage of the new caching features in gitian, be sure to update to a recent version (e9741525c or higher is recommended) +Update the following: -###perform gitian builds +- `configure.ac`: + - `_CLIENT_VERSION_MAJOR` + - `_CLIENT_VERSION_MINOR` + - `_CLIENT_VERSION_REVISION` + - Don't forget to set `_CLIENT_VERSION_IS_RELEASE` to `true` +- `src/clientversion.h`: (this mirrors `configure.ac` - see issue #3539) + - `CLIENT_VERSION_MAJOR` + - `CLIENT_VERSION_MINOR` + - `CLIENT_VERSION_REVISION` + - Don't forget to set `CLIENT_VERSION_IS_RELEASE` to `true` +- `doc/README.md` and `doc/README_windows.txt` +- `doc/Doxyfile`: `PROJECT_NUMBER` contains the full version +- `contrib/gitian-descriptors/*.yml`: usually one'd want to do this on master after branching off the release - but be sure to at least do it before a new major release - From a directory containing the bitcoin source, gitian-builder and gitian.sigs - - export SIGNER=(your gitian key, ie bluematt, sipa, etc) - export VERSION=(new version, e.g. 0.8.0) - pushd ./bitcoin - git checkout v${VERSION} - popd - pushd ./gitian-builder +Write release notes. git shortlog helps a lot, for example: -###fetch and build inputs: (first time, or when dependency versions change) - - mkdir -p inputs; cd inputs/ + git shortlog --no-merges v(current version, e.g. 0.7.2)..v(new version, e.g. 0.8.0) - Register and download the Apple SDK: (see OSX Readme for details) - - https://developer.apple.com/downloads/download.action?path=Developer_Tools/xcode_4.6.3/xcode4630916281a.dmg - - Using a Mac, create a tarball for the 10.7 SDK and copy it to the inputs directory: - - tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.7.sdk.tar.gz MacOSX10.7.sdk +(or ping @wumpus on IRC, he has specific tooling to generate the list of merged pulls +and sort them into categories based on labels) - Build Bitcoin Core for Linux, Windows, and OS X: - - ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml - ./bin/gsign --signer $SIGNER --release ${VERSION}-linux --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml - mv build/out/bitcoin-*.tar.gz build/out/src/bitcoin-*.tar.gz ../ - ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml - ./bin/gsign --signer $SIGNER --release ${VERSION}-win --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win.yml - mv build/out/bitcoin-*.zip build/out/bitcoin-*.exe ../ - ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml - ./bin/gsign --signer $SIGNER --release ${VERSION}-osx-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml - mv build/out/bitcoin-*-unsigned.tar.gz inputs - mv build/out/bitcoin-*.tar.gz build/out/bitcoin-*.dmg ../ - popd -bitcoin-0.9.99-osx-unsigned.tar.gz - Build output expected: +Generate list of authors: - 1. source tarball (bitcoin-${VERSION}.tar.gz) - 2. linux 32-bit and 64-bit binaries dist tarballs (bitcoin-${VERSION}-linux[32|64].tar.gz) - 3. windows 32-bit and 64-bit installers and dist zips (bitcoin-${VERSION}-win[32|64]-setup.exe, bitcoin-${VERSION}-win[32|64].zip) - 4. OSX unsigned installer (bitcoin-${VERSION}-osx-unsigned.dmg) - 5. Gitian signatures (in gitian.sigs/${VERSION}-<linux|win|osx-unsigned>/(your gitian key)/ + git log --format='%aN' "$*" | sort -ui | sed -e 's/^/- /' -###Next steps: +Tag version (or release candidate) in git + + git tag -s v(new version, e.g. 0.8.0) + +### Setup and perform Gitian builds + +Setup Gitian descriptors: + + pushd ./bitcoin + export SIGNER=(your Gitian key, ie bluematt, sipa, etc) + export VERSION=(new version, e.g. 0.8.0) + git fetch + git checkout v${VERSION} + popd + +Ensure your gitian.sigs are up-to-date if you wish to gverify your builds against other Gitian signatures. + + pushd ./gitian.sigs + git pull + popd + +Ensure gitian-builder is up-to-date: + + pushd ./gitian-builder + git pull + popd + +### Fetch and create inputs: (first time, or when dependency versions change) + + pushd ./gitian-builder + mkdir -p inputs + wget -P inputs https://bitcoincore.org/cfields/osslsigncode-Backports-to-1.7.1.patch + wget -P inputs http://downloads.sourceforge.net/project/osslsigncode/osslsigncode/osslsigncode-1.7.1.tar.gz + popd + +Create the OS X SDK tarball, see the [OS X readme](README_osx.md) for details, and copy it into the inputs directory. + +### Optional: Seed the Gitian sources cache and offline git repositories + +By default, Gitian will fetch source files as needed. To cache them ahead of time: + + pushd ./gitian-builder + make -C ../bitcoin/depends download SOURCES_PATH=`pwd`/cache/common + popd + +Only missing files will be fetched, so this is safe to re-run for each build. + +NOTE: Offline builds must use the --url flag to ensure Gitian fetches only from local URLs. For example: + + pushd ./gitian-builder + ./bin/gbuild --url bitcoin=/path/to/bitcoin,signature=/path/to/sigs {rest of arguments} + popd + +The gbuild invocations below <b>DO NOT DO THIS</b> by default. + +### Build and sign Bitcoin Core for Linux, Windows, and OS X: + + pushd ./gitian-builder + ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml + ./bin/gsign --signer $SIGNER --release ${VERSION}-linux --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml + mv build/out/bitcoin-*.tar.gz build/out/src/bitcoin-*.tar.gz ../ + + ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml + ./bin/gsign --signer $SIGNER --release ${VERSION}-win-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win.yml + mv build/out/bitcoin-*-win-unsigned.tar.gz inputs/bitcoin-win-unsigned.tar.gz + mv build/out/bitcoin-*.zip build/out/bitcoin-*.exe ../ + + ./bin/gbuild --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml + ./bin/gsign --signer $SIGNER --release ${VERSION}-osx-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml + mv build/out/bitcoin-*-osx-unsigned.tar.gz inputs/bitcoin-osx-unsigned.tar.gz + mv build/out/bitcoin-*.tar.gz build/out/bitcoin-*.dmg ../ + popd + +Build output expected: + + 1. source tarball (`bitcoin-${VERSION}.tar.gz`) + 2. linux 32-bit and 64-bit dist tarballs (`bitcoin-${VERSION}-linux[32|64].tar.gz`) + 3. windows 32-bit and 64-bit unsigned installers and dist zips (`bitcoin-${VERSION}-win[32|64]-setup-unsigned.exe`, `bitcoin-${VERSION}-win[32|64].zip`) + 4. OS X unsigned installer and dist tarball (`bitcoin-${VERSION}-osx-unsigned.dmg`, `bitcoin-${VERSION}-osx64.tar.gz`) + 5. Gitian signatures (in `gitian.sigs/${VERSION}-<linux|{win,osx}-unsigned>/(your Gitian key)/`) + +### Verify other gitian builders signatures to your own. (Optional) + +Add other gitian builders keys to your gpg keyring + + gpg --import bitcoin/contrib/gitian-keys/*.pgp + +Verify the signatures + + pushd ./gitian-builder + ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-linux ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml + ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-unsigned ../bitcoin/contrib/gitian-descriptors/gitian-win.yml + ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-unsigned ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml + popd + +### Next steps: Commit your signature to gitian.sigs: - pushd gitian.sigs - git add ${VERSION}-linux/${SIGNER} - git add ${VERSION}-win/${SIGNER} - git add ${VERSION}-osx-unsigned/${SIGNER} - git commit -a - git push # Assuming you can push to the gitian.sigs tree - popd - -Wait for OSX detached signature: - Once the OSX build has 3 matching signatures, Gavin will sign it with the apple App-Store key. - He will then upload a detached signature to be combined with the unsigned app to create a signed binary. - -Create the signed OSX binary: - pushd ./gitian-builder - # Fetch the signature as instructed by Gavin - cp signature.tar.gz inputs/ - ./bin/gbuild -i ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml - ./bin/gsign --signer $SIGNER --release ${VERSION}-osx-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml - mv build/out/bitcoin-${VERSION}-osx.dmg ../ - popd - -Commit your signature for the signed OSX binary: - - pushd gitian.sigs - git add ${VERSION}-osx-signed/${SIGNER} - git commit -a - git push # Assuming you can push to the gitian.sigs tree - popd - -------------------------------------------------------------------------- + pushd gitian.sigs + git add ${VERSION}-linux/${SIGNER} + git add ${VERSION}-win-unsigned/${SIGNER} + git add ${VERSION}-osx-unsigned/${SIGNER} + git commit -a + git push # Assuming you can push to the gitian.sigs tree + popd -### After 3 or more people have gitian-built and their results match: +Wait for Windows/OS X detached signatures: + +- Once the Windows/OS X builds each have 3 matching signatures, they will be signed with their respective release keys. +- Detached signatures will then be committed to the [bitcoin-detached-sigs](https://github.com/bitcoin-core/bitcoin-detached-sigs) repository, which can be combined with the unsigned apps to create signed binaries. -- Perform code-signing. +Create (and optionally verify) the signed OS X binary: - - Code-sign Windows -setup.exe (in a Windows virtual machine using signtool) + pushd ./gitian-builder + ./bin/gbuild -i --commit signature=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml + ./bin/gsign --signer $SIGNER --release ${VERSION}-osx-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml + ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-osx-signed ../bitcoin/contrib/gitian-descriptors/gitian-osx-signer.yml + mv build/out/bitcoin-osx-signed.dmg ../bitcoin-${VERSION}-osx.dmg + popd - Note: only Gavin has the code-signing keys currently. +Create (and optionally verify) the signed Windows binaries: + + pushd ./gitian-builder + ./bin/gbuild -i --commit signature=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml + ./bin/gsign --signer $SIGNER --release ${VERSION}-win-signed --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml + ./bin/gverify -v -d ../gitian.sigs/ -r ${VERSION}-win-signed ../bitcoin/contrib/gitian-descriptors/gitian-win-signer.yml + mv build/out/bitcoin-*win64-setup.exe ../bitcoin-${VERSION}-win64-setup.exe + mv build/out/bitcoin-*win32-setup.exe ../bitcoin-${VERSION}-win32-setup.exe + popd + +Commit your signature for the signed OS X/Windows binaries: + + pushd gitian.sigs + git add ${VERSION}-osx-signed/${SIGNER} + git add ${VERSION}-win-signed/${SIGNER} + git commit -a + git push # Assuming you can push to the gitian.sigs tree + popd + +### After 3 or more people have gitian-built and their results match: - Create `SHA256SUMS.asc` for the builds, and GPG-sign it: + ```bash sha256sum * > SHA256SUMS +``` + +The list of files should be: +``` +bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz +bitcoin-${VERSION}-arm-linux-gnueabihf.tar.gz +bitcoin-${VERSION}-i686-pc-linux-gnu.tar.gz +bitcoin-${VERSION}-x86_64-linux-gnu.tar.gz +bitcoin-${VERSION}-osx64.tar.gz +bitcoin-${VERSION}-osx.dmg +bitcoin-${VERSION}.tar.gz +bitcoin-${VERSION}-win32-setup.exe +bitcoin-${VERSION}-win32.zip +bitcoin-${VERSION}-win64-setup.exe +bitcoin-${VERSION}-win64.zip +``` +The `*-debug*` files generated by the gitian build contain debug symbols +for troubleshooting by developers. It is assumed that anyone that is interested +in debugging can run gitian to generate the files for themselves. To avoid +end-user confusion about which file to pick, as well as save storage +space *do not upload these to the bitcoin.org server, nor put them in the torrent*. + +- GPG-sign it, delete the unsigned file: +``` gpg --digest-algo sha256 --clearsign SHA256SUMS # outputs SHA256SUMS.asc rm SHA256SUMS ``` (the digest algorithm is forced to sha256 to avoid confusion of the `Hash:` header that GPG adds with the SHA256 used for the files) +Note: check that SHA256SUMS itself doesn't end up in SHA256SUMS, which is a spurious/nonsensical entry. - Upload zips and installers, as well as `SHA256SUMS.asc` from last step, to the bitcoin.org server + into `/var/www/bin/bitcoin-core-${VERSION}` + +- A `.torrent` will appear in the directory after a few minutes. Optionally help seed this torrent. To get the `magnet:` URI use: +```bash +transmission-show -m <torrent file> +``` +Insert the magnet URI into the announcement sent to mailing lists. This permits +people without access to `bitcoin.org` to download the binary distribution. +Also put it into the `optional_magnetlink:` slot in the YAML file for +bitcoin.org (see below for bitcoin.org update instructions). - Update bitcoin.org version - - Make a pull request to add a file named `YYYY-MM-DD-vX.Y.Z.md` with the release notes - to https://github.com/bitcoin/bitcoin.org/tree/master/_releases - ([Example for 0.9.2.1](https://raw.githubusercontent.com/bitcoin/bitcoin.org/master/_releases/2014-06-19-v0.9.2.1.md)). + - First, check to see if the Bitcoin.org maintainers have prepared a + release: https://github.com/bitcoin-dot-org/bitcoin.org/labels/Releases - - After the pull request is merged, the website will automatically show the newest version, as well - as update the OS download links. Ping Saivann in case anything goes wrong + - If they have, it will have previously failed their Travis CI + checks because the final release files weren't uploaded. + Trigger a Travis CI rebuild---if it passes, merge. + + - If they have not prepared a release, follow the Bitcoin.org release + instructions: https://github.com/bitcoin-dot-org/bitcoin.org#release-notes + + - After the pull request is merged, the website will automatically show the newest version within 15 minutes, as well + as update the OS download links. Ping @saivann/@harding (saivann/harding on Freenode) in case anything goes wrong - Announce the release: - - Release sticky on bitcointalk: https://bitcointalk.org/index.php?board=1.0 + - bitcoin-dev and bitcoin-core-dev mailing list + + - Bitcoin Core announcements list https://bitcoincore.org/en/list/announcements/join/ - - Bitcoin-development mailing list + - bitcoincore.org blog post - Update title of #bitcoin on Freenode IRC - - Optionally reddit /r/Bitcoin, ... but this will usually sort out itself + - Optionally twitter, reddit /r/Bitcoin, ... but this will usually sort out itself -- Notify BlueMatt so that he can start building [https://launchpad.net/~bitcoin/+archive/ubuntu/bitcoin](the PPAs) + - Notify BlueMatt so that he can start building [the PPAs](https://launchpad.net/~bitcoin/+archive/ubuntu/bitcoin) -- Add release notes for the new version to the directory `doc/release-notes` in git master + - Add release notes for the new version to the directory `doc/release-notes` in git master -- Celebrate + - Celebrate diff --git a/doc/shared-libraries.md b/doc/shared-libraries.md new file mode 100644 index 0000000000..ec6f16c8aa --- /dev/null +++ b/doc/shared-libraries.md @@ -0,0 +1,44 @@ +Shared Libraries +================ + +## bitcoinconsensus + +The purpose of this library is to make the verification functionality that is critical to Bitcoin's consensus available to other applications, e.g. to language bindings. + +### API + +The interface is defined in the C header `bitcoinconsensus.h` located in `src/script/bitcoinconsensus.h`. + +#### Version + +`bitcoinconsensus_version` returns an `unsigned int` with the API version *(currently at an experimental `0`)*. + +#### Script Validation + +`bitcoinconsensus_verify_script` returns an `int` with the status of the verification. It will be `1` if the input script correctly spends the previous output `scriptPubKey`. + +##### Parameters +- `const unsigned char *scriptPubKey` - The previous output script that encumbers spending. +- `unsigned int scriptPubKeyLen` - The number of bytes for the `scriptPubKey`. +- `const unsigned char *txTo` - The transaction with the input that is spending the previous output. +- `unsigned int txToLen` - The number of bytes for the `txTo`. +- `unsigned int nIn` - The index of the input in `txTo` that spends the `scriptPubKey`. +- `unsigned int flags` - The script validation flags *(see below)*. +- `bitcoinconsensus_error* err` - Will have the error/success code for the operation *(see below)*. + +##### Script Flags +- `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_NONE` +- `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_P2SH` - Evaluate P2SH ([BIP16](https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki)) subscripts +- `bitcoinconsensus_SCRIPT_FLAGS_VERIFY_DERSIG` - Enforce strict DER ([BIP66](https://github.com/bitcoin/bips/blob/master/bip-0066.mediawiki)) compliance + +##### Errors +- `bitcoinconsensus_ERR_OK` - No errors with input parameters *(see the return value of `bitcoinconsensus_verify_script` for the verification status)* +- `bitcoinconsensus_ERR_TX_INDEX` - An invalid index for `txTo` +- `bitcoinconsensus_ERR_TX_SIZE_MISMATCH` - `txToLen` did not match with the size of `txTo` +- `bitcoinconsensus_ERR_DESERIALIZE` - An error deserializing `txTo` + +### Example Implementations +- [NBitcoin](https://github.com/NicolasDorier/NBitcoin/blob/master/NBitcoin/Script.cs#L814) (.NET Bindings) +- [node-libbitcoinconsensus](https://github.com/bitpay/node-libbitcoinconsensus) (Node.js Bindings) +- [java-libbitcoinconsensus](https://github.com/dexX7/java-libbitcoinconsensus) (Java Bindings) +- [bitcoinconsensus-php](https://github.com/Bit-Wasp/bitcoinconsensus-php) (PHP Bindings) diff --git a/doc/tor.md b/doc/tor.md index 560f71fa27..79f1563021 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -3,7 +3,7 @@ TOR SUPPORT IN BITCOIN It is possible to run Bitcoin as a Tor hidden service, and connect to such services. -The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on a random port. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly +The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly configure Tor. @@ -15,15 +15,15 @@ outgoing connections be anonymized, but more is possible. -proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy server will be used to try to reach .onion addresses as well. - + -onion=ip:port Set the proxy server to use for tor hidden services. You do not need to set this if it's the same as -proxy. You can use -noonion to explicitly disable access to hidden service. - + -listen When using -proxy, listening is disabled by default. If you want to run a hidden service (see next section), you'll need to enable it explicitly. - + -connect=X When behind a Tor proxy, you can specify .onion addresses instead -addnode=X of IP addresses or hostnames in these parameters. It requires -seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with @@ -52,13 +52,13 @@ your bitcoind's P2P listen port (8333 by default). this option, and this can be a .onion address. Given the above configuration, you can find your onion address in /var/lib/tor/bitcoin-service/hostname. Onion addresses are given - preference for your node to advertize itself with, for connections + preference for your node to advertise itself with, for connections coming from unroutable addresses (such as 127.0.0.1, where the Tor proxy typically runs). - + -listen You'll need to enable listening for incoming connections, as this is off by default behind a proxy. - + -discover When -externalip is specified, no attempt is made to discover local IPv4 or IPv6 addresses. If you want to run a dual stack, reachable from both Tor and IPv4 (or IPv6), you'll need to either pass your @@ -70,9 +70,14 @@ In a typical situation, where you're only reachable via Tor, this should suffice ./bitcoind -proxy=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -listen -(obviously, replace the Onion address with your own). If you don't care too much -about hiding your node, and want to be reachable on IPv4 as well, additionally -specify: +(obviously, replace the Onion address with your own). It should be noted that you still +listen on all devices and another node could establish a clearnet connection, when knowing +your address. To mitigate this, additionally bind the address of your Tor proxy: + + ./bitcoind ... -bind=127.0.0.1 + +If you don't care too much about hiding your node, and want to be reachable on IPv4 +as well, use `discover` instead: ./bitcoind ... -discover @@ -83,3 +88,29 @@ for normal IPv4/IPv6 communication, use: ./bitcoin -onion=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover +3. Automatically listen on Tor +-------------------------------- + +Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket +API, to create and destroy 'ephemeral' hidden services programmatically. +Bitcoin Core has been updated to make use of this. + +This means that if Tor is running (and proper authentication has been configured), +Bitcoin Core automatically creates a hidden service to listen on. This will positively +affect the number of available .onion nodes. + +This new feature is enabled by default if Bitcoin Core is listening, and +a connection to Tor can be made. It can be configured with the `-listenonion`, +`-torcontrol` and `-torpassword` settings. To show verbose debugging +information, pass `-debug=tor`. + +Connecting to Tor's control socket API requires one of two authentication methods to be +configured. For cookie authentication the user running bitcoind must have write access +to the `CookieAuthFile` specified in Tor configuration. In some cases this is +preconfigured and the creation of a hidden service is automatic. If permission problems +are seen with `-debug=tor` they can be resolved by adding both the user running tor and +the user running bitcoind to the same group and setting permissions appropriately. On +Debian-based systems the user running bitcoind can be added to the debian-tor group, +which has the appropriate permissions. An alternative authentication method is the use +of the `-torpassword` flag and a `hash-password` which can be enabled and specified in +Tor configuration.
\ No newline at end of file diff --git a/doc/translation_process.md b/doc/translation_process.md index 9475b1dc72..310d560b36 100644 --- a/doc/translation_process.md +++ b/doc/translation_process.md @@ -1,89 +1,111 @@ Translations ============ -The Bitcoin Core GUI can be easily translated into other languages. Here's how we -handle those translations. +The Bitcoin-Core project has been designed to support multiple localisations. This makes adding new phrases, and completely new languages easily achievable. For managing all application translations, Bitcoin-Core makes use of the Transifex online translation management tool. -Files and Folders ------------------ +### Helping to translate (using Transifex) +Transifex is setup to monitor the Github repo for updates, and when code containing new translations is found, Transifex will process any changes. It may take several hours after a pull-request has been merged, to appear in the Transifex web interface. -### bitcoin-qt.pro +Multiple language support is critical in assisting Bitcoin’s global adoption, and growth. One of Bitcoin’s greatest strengths is cross-boarder money transfers, any help making that easier is greatly appreciated. -This file takes care of generating `.qm` files from `.ts` files. It is mostly -automated. +See the [Transifex Bitcoin project](https://www.transifex.com/projects/p/bitcoin/) to assist in translations. You should also join the translation mailing list for announcements - see details below. -### src/qt/bitcoin.qrc +### Writing code with translations +We use automated scripts to help extract translations in both Qt, and non-Qt source files. It is rarely necessary to manually edit the files in `src/qt/locale/`. The translation source files must adhere to the following format: +`bitcoin_xx_YY.ts or bitcoin_xx.ts` -This file must be updated whenever a new translation is added. Please note that -files must end with `.qm`, not `.ts`. +`src/qt/locale/bitcoin_en.ts` is treated in a special way. It is used as the source for all other translations. Whenever a string in the source code is changed, this file must be updated to reflect those changes. A custom script is used to extract strings from the non-Qt parts. This script makes use of `gettext`, so make sure that utility is installed (ie, `apt-get install gettext` on Ubuntu/Debian). Once this has been updated, `lupdate` (included in the Qt SDK) is used to update `bitcoin_en.ts`. -```xml -<qresource prefix="/translations"> - <file alias="en">locale/bitcoin_en.qm</file> - ... -</qresource> +To automatically regenerate the `bitcoin_en.ts` file, run the following commands: +```sh +cd src/ +make translate ``` -### src/qt/locale/ +`contrib/bitcoin-qt.pro` takes care of generating `.qm` (binary compiled) files from `.ts` (source files) files. It’s mostly automated, and you shouldn’t need to worry about it. -This directory contains all translations. Filenames must adhere to this format: +**Example Qt translation** +```cpp +QToolBar *toolbar = addToolBar(tr("Tabs toolbar")); +``` - bitcoin_xx_YY.ts or bitcoin_xx.ts +### Creating a pull-request +For general PRs, you shouldn’t include any updates to the translation source files. They will be updated periodically, primarily around pre-releases, allowing time for any new phrases to be translated before public releases. This is also important in avoiding translation related merge conflicts. -#### bitcoin_en.ts (Source file) +When an updated source file is merged into the Github repo, Transifex will automatically detect it (although it can take several hours). Once processed, the new strings will show up as "Remaining" in the Transifex web interface and are ready for translators. -`src/qt/locale/bitcoin_en.ts` is treated in a special way. It is used as the -source for all other translations. Whenever a string in the code is changed -this file must be updated to reflect those changes. A custom script is used -to extract strings from the non-Qt parts. This script makes use of `gettext`, -so make sure that utility is installed (ie, `apt-get install gettext` on -Ubuntu/Debian). Once this has been updated, lupdate (included in the Qt SDK) -is used to update bitcoin_en.ts. This process has been automated, from src/qt, -simply run: - make translate - -##### Handling of plurals in the source file +To create the pull-request, use the following commands: +``` +git add src/qt/bitcoinstrings.cpp src/qt/locale/bitcoin_en.ts +git commit +``` -When new plurals are added to the source file, it's important to do the following steps: +### Creating a Transifex account +Visit the [Transifex Signup](https://www.transifex.com/signup/) page to create an account. Take note of your username and password, as they will be required to configure the command-line tool. -1. Open bitcoin_en.ts in Qt Linguist (also included in the Qt SDK) -2. Search for `%n`, which will take you to the parts in the translation that use plurals -3. Look for empty `English Translation (Singular)` and `English Translation (Plural)` fields -4. Add the appropriate strings for the singular and plural form of the base string -5. Mark the item as done (via the green arrow symbol in the toolbar) -6. Repeat from step 2. until all singular and plural forms are in the source file -7. Save the source file +You can find the Bitcoin translation project at [https://www.transifex.com/projects/p/bitcoin/](https://www.transifex.com/projects/p/bitcoin/). -##### Creating the pull-request +### Installing the Transifex client command-line tool +The client it used to fetch updated translations. If you are having problems, or need more details, see [http://docs.transifex.com/developer/client/setup](http://docs.transifex.com/developer/client/setup) -An updated source file should be merged to github and Transifex will pick it -up from there (can take some hours). Afterwards the new strings show up as "Remaining" -in Transifex and can be translated. +**For Linux and Mac** -To create the pull-request you have to do: +`pip install transifex-client` - git add src/qt/bitcoinstrings.cpp src/qt/locale/bitcoin_en.ts - git commit +Setup your transifex client config as follows. Please *ignore the token field*. -Syncing with Transifex ----------------------- +```ini +nano ~/.transifexrc -We are using https://transifex.com as a frontend for translating the client. +[https://www.transifex.com] +hostname = https://www.transifex.com +password = PASSWORD +token = +username = USERNAME +``` -https://www.transifex.com/projects/p/bitcoin/resource/tx/ +**For Windows** -The "Transifex client" (see: http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles) -is used to fetch new translations from Transifex. The configuration for this client (`.tx/config`) -is part of the repository. +Please see [http://docs.transifex.com/developer/client/setup#windows](http://docs.transifex.com/developer/client/setup#windows) for details on installation. -Do not directly download translations one by one from the Transifex website, as we do a few -postprocessing steps before committing the translations. +The Transifex Bitcoin project config file is included as part of the repo. It can be found at `.tx/config`, however you shouldn’t need change anything. -### Fetching new translations +### Synchronising translations +To assist in updating translations, we have created a script to help. 1. `python contrib/devtools/update-translations.py` -2. update `src/qt/bitcoin.qrc` manually or via +2. Update `src/qt/bitcoin_locale.qrc` manually or via `ls src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/<file alias="\2">locale\/\1.qm<\/file>/'` -3. update `src/qt/Makefile.am` manually or via - `ls src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/ locale\/\1.ts \\/'` +3. Update `src/Makefile.qt.include` manually or via + `ls src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/ qt\/locale\/\1.ts \\/'` 4. `git add` new translations from `src/qt/locale/` + +**Do not directly download translations** one by one from the Transifex website, as we do a few post-processing steps before committing the translations. + +### Handling Plurals (in source files) +When new plurals are added to the source file, it's important to do the following steps: + +1. Open `bitcoin_en.ts` in Qt Linguist (included in the Qt SDK) +2. Search for `%n`, which will take you to the parts in the translation that use plurals +3. Look for empty `English Translation (Singular)` and `English Translation (Plural)` fields +4. Add the appropriate strings for the singular and plural form of the base string +5. Mark the item as done (via the green arrow symbol in the toolbar) +6. Repeat from step 2, until all singular and plural forms are in the source file +7. Save the source file + +### Translating a new language +To create a new language template, you will need to edit the languages manifest file `src/qt/bitcoin.qrc` and add a new entry. Below is an example of the english language entry. + +```xml +<qresource prefix="/translations"> + <file alias="en">locale/bitcoin_en.qm</file> + ... +</qresource> +``` + +**Note:** that the language translation file **must end in `.qm`** (the compiled extension), and not `.ts`. + +### Questions and general assistance +The Bitcoin-Core translation maintainers include *tcatm, seone, Diapolo, wumpus and luke-jr*. You can find them, and others, in the Freenode IRC chatroom - `irc.freenode.net #bitcoin-core-dev`. + +If you are a translator, you should also subscribe to the mailing list, https://groups.google.com/forum/#!forum/bitcoin-translators. Announcements will be posted during application pre-releases to notify translators to check for updates. diff --git a/doc/translation_strings_policy.md b/doc/translation_strings_policy.md new file mode 100644 index 0000000000..b95259cdc9 --- /dev/null +++ b/doc/translation_strings_policy.md @@ -0,0 +1,109 @@ +Translation Strings Policy +=========================== + +This document provides guidelines for internationalization of the Bitcoin Core software. + +How to translate? +------------------ + +To mark a message as translatable + +- In GUI source code (under `src/qt`): use `tr("...")` + +- In non-GUI source code (under `src`): use `_("...")` + +No internationalization is used for e.g. developer scripts outside `src`. + +Strings to be translated +------------------------- + +On a high level, these strings are to be translated: + +- GUI strings, anything that appears in a dialog or window + +- Command-line option documentation + +### GUI strings + +Anything that appears to the user in the GUI is to be translated. This includes labels, menu items, button texts, tooltips and window titles. +This includes messages passed to the GUI through the UI interface through `InitMessage`, `ThreadSafeMessageBox` or `ShowProgress`. + +### Command-line options + +Documentation for the command line options in the output of `--help` should be translated as well. + +Make sure that default values do not end up in the string, but use string formatting like `strprintf(_("Threshold for disconnecting misbehaving peers (default: %u)"), 100)`. Putting default values in strings has led to accidental translations in the past, and forces the string to be retranslated every time the value changes. + +Do not translate messages that are only shown to developers, such as those that only appear when `--help-debug` is used. + +General recommendations +------------------------ + +### Avoid unnecessary translation strings + +Try not to burden translators with translating messages that are e.g. slight variations of other messages. +In the GUI, avoid the use of text where an icon or symbol will do. +Make sure that placeholder texts in forms don't end up in the list of strings to be translated (use `<string notr="true">`). + +### Make translated strings understandable + +Try to write translation strings in an understandable way, for both the user and the translator. Avoid overly technical or detailed messages + +### Do not translate internal errors + +Do not translate internal errors, or log messages, or messages that appear on the RPC interface. If an error is to be shown to the user, +use a translatable generic message, then log the detailed message to the log. E.g. "A fatal internal error occurred, see debug.log for details". +This helps troubleshooting; if the error is the same for everyone, the likelihood is increased that it can be found using a search engine. + +### Avoid fragments + +Avoid dividing up a message into fragments. Translators see every string separately, so may misunderstand the context if the messages are not self-contained. + +### Avoid HTML in translation strings + +There have been difficulties with use of HTML in translation strings; translators should not be able to accidentally affect the formatting of messages. +This may sometimes be at conflict with the recommendation in the previous section. + +### Plurals + +Plurals can be complex in some languages. A quote from the gettext documentation: + + In Polish we use e.g. plik (file) this way: + 1 plik, + 2,3,4 pliki, + 5-21 pliko'w, + 22-24 pliki, + 25-31 pliko'w + and so on + +In Qt code use tr's third argument for optional plurality. For example: + + tr("%n hour(s)","",secs/HOUR_IN_SECONDS); + tr("%n day(s)","",secs/DAY_IN_SECONDS); + tr("%n week(s)","",secs/WEEK_IN_SECONDS); + +This adds `<numerusform>`s to the respective `.ts` file, which can be translated separately depending on the language. In English, this is simply: + + <message numerus="yes"> + <source>%n active connection(s) to Bitcoin network</source> + <translation> + <numerusform>%n active connection to Bitcoin network</numerusform> + <numerusform>%n active connections to Bitcoin network</numerusform> + </translation> + </message> + +Where it is possible try to avoid embedding numbers into the flow of the string at all. e.g. + + WARNING: check your network connection, %d blocks received in the last %d hours (%d expected) + +versus + + WARNING: check your network connection, less blocks (%d) were received in the last %n hours than expected (%d). + +The second example reduces the number of pluralized words that translators have to handle from three to one, at no cost to comprehensibility of the sentence. + +### String freezes + +During a string freeze (often before a major release), no translation strings are to be added, modified or removed. + +This can be checked by executing `make translate` in the `src` directory, then verifying that `bitcoin_en.ts` remains unchanged. diff --git a/doc/travis-ci.txt b/doc/travis-ci.txt index 01f7d02a86..06410405d6 100644 --- a/doc/travis-ci.txt +++ b/doc/travis-ci.txt @@ -27,7 +27,7 @@ In order to avoid rebuilding all dependencies for each build, the binaries are cached and re-used when possible. Changes in the dependency-generator will trigger cache-invalidation and rebuilds as necessary. -These caches can be manually removed if necessary. This is one of the the very few +These caches can be manually removed if necessary. This is one of the very few manual operations that is possible with Travis, and it can be done by the Bitcoin Core committer via the Travis web interface. diff --git a/doc/unit-tests.md b/doc/unit-tests.md index f1d3a8bc50..afaece829c 100644 --- a/doc/unit-tests.md +++ b/doc/unit-tests.md @@ -1,18 +1,18 @@ Compiling/running unit tests ------------------------------------ -Unit tests will be automatically compiled if dependencies were met in configure +Unit tests will be automatically compiled if dependencies were met in `./configure` and tests weren't explicitly disabled. -After configuring, they can be run with 'make check'. +After configuring, they can be run with `make check`. -To run the bitcoind tests manually, launch src/test/test_bitcoin . +To run the bitcoind tests manually, launch `src/test/test_bitcoin`. To add more bitcoind tests, add `BOOST_AUTO_TEST_CASE` functions to the existing -.cpp files in the test/ directory or add new .cpp files that +.cpp files in the `test/` directory or add new .cpp files that implement new BOOST_AUTO_TEST_SUITE sections. -To run the bitcoin-qt tests manually, launch src/qt/test/bitcoin-qt_test +To run the bitcoin-qt tests manually, launch `src/qt/test/test_bitcoin-qt` To add more bitcoin-qt tests, add them to the `src/qt/test/` directory and the `src/qt/test/test_main.cpp` file. diff --git a/doc/zmq.md b/doc/zmq.md new file mode 100644 index 0000000000..6079e3254f --- /dev/null +++ b/doc/zmq.md @@ -0,0 +1,106 @@ +# Block and Transaction Broadcasting With ZeroMQ + +[ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP +connections, inter-process communication, and shared-memory, +providing various message-oriented semantics such as publish/subscribe, +request/reply, and push/pull. + +The Bitcoin Core daemon can be configured to act as a trusted "border +router", implementing the bitcoin wire protocol and relay, making +consensus decisions, maintaining the local blockchain database, +broadcasting locally generated transactions into the network, and +providing a queryable RPC interface to interact on a polled basis for +requesting blockchain related data. However, there exists only a +limited service to notify external software of events like the arrival +of new blocks or transactions. + +The ZeroMQ facility implements a notification interface through a set +of specific notifiers. Currently there are notifiers that publish +blocks and transactions. This read-only facility requires only the +connection of a corresponding ZeroMQ subscriber port in receiving +software; it is not authenticated nor is there any two-way protocol +involvement. Therefore, subscribers should validate the received data +since it may be out of date, incomplete or even invalid. + +ZeroMQ sockets are self-connecting and self-healing; that is, +connections made between two endpoints will be automatically restored +after an outage, and either end may be freely started or stopped in +any order. + +Because ZeroMQ is message oriented, subscribers receive transactions +and blocks all-at-once and do not need to implement any sort of +buffering or reassembly. + +## Prerequisites + +The ZeroMQ feature in Bitcoin Core requires ZeroMQ API version 4.x or +newer. Typically, it is packaged by distributions as something like +*libzmq3-dev*. The C++ wrapper for ZeroMQ is *not* needed. + +In order to run the example Python client scripts in contrib/ one must +also install *python3-zmq*, though this is not necessary for daemon +operation. + +## Enabling + +By default, the ZeroMQ feature is automatically compiled in if the +necessary prerequisites are found. To disable, use --disable-zmq +during the *configure* step of building bitcoind: + + $ ./configure --disable-zmq (other options) + +To actually enable operation, one must set the appropriate options on +the commandline or in the configuration file. + +## Usage + +Currently, the following notifications are supported: + + -zmqpubhashtx=address + -zmqpubhashblock=address + -zmqpubrawblock=address + -zmqpubrawtx=address + +The socket type is PUB and the address must be a valid ZeroMQ socket +address. The same address can be used in more than one notification. + +For instance: + + $ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \ + -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw + +Each PUB notification has a topic and body, where the header +corresponds to the notification type. For instance, for the +notification `-zmqpubhashtx` the topic is `hashtx` (no null +terminator) and the body is the hexadecimal transaction hash (32 +bytes). + +These options can also be provided in bitcoin.conf. + +ZeroMQ endpoint specifiers for TCP (and others) are documented in the +[ZeroMQ API](http://api.zeromq.org/4-0:_start). + +Client side, then, the ZeroMQ subscriber socket must have the +ZMQ_SUBSCRIBE option set to one or either of these prefixes (for +instance, just `hash`); without doing so will result in no messages +arriving. Please see `contrib/zmq/zmq_sub.py` for a working example. + +## Remarks + +From the perspective of bitcoind, the ZeroMQ socket is write-only; PUB +sockets don't even have a read function. Thus, there is no state +introduced into bitcoind directly. Furthermore, no information is +broadcast that wasn't already received from the public P2P network. + +No authentication or authorization is done on connecting clients; it +is assumed that the ZeroMQ port is exposed only to trusted entities, +using other means such as firewalling. + +Note that when the block chain tip changes, a reorganisation may occur +and just the tip will be notified. It is up to the subscriber to +retrieve the chain from the last known block to the new tip. + +There are several possibilities that ZMQ notification can get lost +during transmission depending on the communication type your are +using. Bitcoind appends an up-counting sequence number to each +notification which allows listeners to detect lost notifications. |
