diff options
Diffstat (limited to 'doc')
41 files changed, 2353 insertions, 458 deletions
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 58c65fb7e2..cd7ccf80ab 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -453,7 +453,7 @@ EXTRACT_PACKAGE = NO # included in the documentation. # The default value is: NO. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, @@ -790,7 +790,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = src +INPUT = src doc/README_doxygen.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -974,7 +974,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = doc/README_doxygen.md #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md index 982afd5d56..a0cfe84a3e 100644 --- a/doc/JSON-RPC-interface.md +++ b/doc/JSON-RPC-interface.md @@ -5,6 +5,18 @@ The headless daemon `bitcoind` has the JSON-RPC API enabled by default, the GUI option. In the GUI it is possible to execute RPC methods in the Debug Console Dialog. +## Versioning + +The RPC interface might change from one major version of Bitcoin Core to the +next. This makes the RPC interface implicitly versioned on the major version. +The version tuple can be retrieved by e.g. the `getnetworkinfo` RPC in +`version`. + +Usually deprecated features can be re-enabled during the grace-period of one +major version via the `-deprecatedrpc=` command line option. The release notes +of a new major release come with detailed instructions on what RPC features +were deprecated and how to re-enable them temporarily. + ## Security The RPC interface allows other programs to control Bitcoin Core, diff --git a/doc/README.md b/doc/README.md index 8876ffdd72..d3017de2ab 100644 --- a/doc/README.md +++ b/doc/README.md @@ -57,7 +57,6 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th - [Source Code Documentation (External Link)](https://dev.visucore.com/bitcoin/doxygen/) - [Translation Process](translation_process.md) - [Translation Strings Policy](translation_strings_policy.md) -- [Travis CI](travis-ci.md) - [JSON-RPC Interface](JSON-RPC-interface.md) - [Unauthenticated REST Interface](REST-interface.md) - [Shared Libraries](shared-libraries.md) @@ -75,6 +74,7 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th - [bitcoin.conf Configuration File](bitcoin-conf.md) - [Files](files.md) - [Fuzz-testing](fuzzing.md) +- [Reduce Memory](reduce-memory.md) - [Reduce Traffic](reduce-traffic.md) - [Tor Support](tor.md) - [Init Scripts (systemd/upstart/openrc)](init.md) diff --git a/doc/README_doxygen.md b/doc/README_doxygen.md new file mode 100644 index 0000000000..6888383a98 --- /dev/null +++ b/doc/README_doxygen.md @@ -0,0 +1,15 @@ +\mainpage notitle + +\section intro_sec Introduction + +This is the developer documentation of the reference client for an experimental new digital currency called Bitcoin, +which enables instant payments to anyone, anywhere in the world. Bitcoin uses peer-to-peer technology to operate +with no central authority: managing transactions and issuing money are carried out collectively by the network. + +The software is a community-driven open source project, released under the MIT license. + +See https://github.com/bitcoin/bitcoin and https://bitcoincore.org/ for further information about the project. + +\section Navigation +Use <a href="modules.html"><code>Modules</code></a>, <a href="namespaces.html"><code>Namespaces</code></a>, <a href="classes.html"><code>Classes</code></a>, or <a href="files.html"><code>Files</code></a> at the top of the page to start navigating the code. + diff --git a/doc/REST-interface.md b/doc/REST-interface.md index 02a665008b..3b8b0db162 100644 --- a/doc/REST-interface.md +++ b/doc/REST-interface.md @@ -81,7 +81,7 @@ $ curl localhost:18332/rest/getutxos/checkmempool/b2cdfd7b89def827ff8af7cd9bff76 { "txvers" : 1 "height" : 2147483647, - "value" : 8.8687, + "value" : 8.8687, "scriptPubKey" : { "asm" : "OP_DUP OP_HASH160 1c7cebb529b86a04c683dfa87be49de35bcf589e OP_EQUALVERIFY OP_CHECKSIG", "hex" : "76a9141c7cebb529b86a04c683dfa87be49de35bcf589e88ac", @@ -101,6 +101,7 @@ $ curl localhost:18332/rest/getutxos/checkmempool/b2cdfd7b89def827ff8af7cd9bff76 Returns various information about the TX mempool. Only supports JSON as output format. +* loaded : (boolean) if the mempool is fully loaded * 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 diff --git a/doc/benchmarking.md b/doc/benchmarking.md index 48f81cf6c1..8e3d88ab7a 100644 --- a/doc/benchmarking.md +++ b/doc/benchmarking.md @@ -2,10 +2,17 @@ Benchmarking ============ Bitcoin Core has an internal benchmarking framework, with benchmarks -for cryptographic algorithms (e.g. SHA1, SHA256, SHA512, RIPEMD160), as well as the rolling bloom filter. +for cryptographic algorithms (e.g. SHA1, SHA256, SHA512, RIPEMD160, Poly1305, ChaCha20), rolling bloom filter, coins selection, +thread queue, wallet balance. Running --------------------- + +For benchmarks purposes you only need to compile `bitcoin_bench`. Beware of configuring without `--enable-debug` as this would impact +benchmarking by unlatching log printers and lock analysis. + + make -C src bench_bitcoin + After compiling bitcoin-core, the benchmarks can be run with: src/bench/bench_bitcoin @@ -13,43 +20,29 @@ After compiling bitcoin-core, the benchmarks can be run with: The output will look similar to: ``` # Benchmark, evals, iterations, total, min, max, median -Base58CheckEncode, 5, 320000, 120.772, 7.49351e-05, 7.59374e-05, 7.54759e-05 -Base58Decode, 5, 800000, 122.833, 3.0467e-05, 3.11732e-05, 3.06304e-05 -Base58Encode, 5, 470000, 137.094, 5.81061e-05, 5.85109e-05, 5.84462e-05 -BenchLockedPool, 5, 530, 34.2023, 0.0128247, 0.0129613, 0.0129026 -CCheckQueueSpeedPrevectorJob, 5, 1400, 26.1762, 0.00365048, 0.00388629, 0.00367108 -CCoinsCaching, 5, 170000, 48.1074, 5.60229e-05, 5.72316e-05, 5.66214e-05 -CoinSelection, 5, 650, 34.6426, 0.0105801, 0.0107699, 0.010664 -DeserializeAndCheckBlockTest, 5, 160, 39.2084, 0.0483662, 0.0494199, 0.0490138 -DeserializeBlockTest, 5, 130, 23.8129, 0.0357731, 0.0373763, 0.0365858 -FastRandom_1bit, 5, 440000000, 38.1609, 1.72974e-08, 1.73882e-08, 1.73478e-08 -FastRandom_32bit, 5, 110000000, 72.8237, 1.29992e-07, 1.37014e-07, 1.30115e-07 -MempoolEviction, 5, 41000, 89.8883, 0.000432748, 0.000446857, 0.000438483 -PrevectorClear, 5, 5600, 47.9229, 0.00169952, 0.0017455, 0.00170315 -PrevectorDestructor, 5, 5700, 44.5498, 0.0015561, 0.00156977, 0.00156469 -RIPEMD160, 5, 440, 135.988, 0.0615496, 0.062268, 0.0617779 -RollingBloom, 5, 1500000, 36.5109, 4.80961e-06, 4.97463e-06, 4.85811e-06 -SHA1, 5, 570, 51.808, 0.018065, 0.0182623, 0.0181865 -SHA256, 5, 340, 8.31841, 0.00483231, 0.00499803, 0.00485486 -SHA256_32b, 5, 4700000, 10.469, 4.43441e-07, 4.47611e-07, 4.45223e-07 -SHA512, 5, 330, 33.3408, 0.02017, 0.0202554, 0.0201921 -SipHash_32b, 5, 40000000, 38.7088, 1.91103e-07, 1.96998e-07, 1.93792e-07 -Sleep100ms, 5, 10, 5.01062, 0.100131, 0.100368, 0.100147 -Trig, 5, 12000000, 5.95494, 9.78115e-08, 1.04354e-07, 9.80682e-08 -VerifyScriptBench, 5, 6300, 9.02493, 0.000285566, 0.000288433, 0.000286175 +AssembleBlock, 5, 700, 1.79954, 0.000510913, 0.000517018, 0.000514497 +... ``` Help --------------------- -`-?` will print a list of options and exit: - src/bench/bench_bitcoin -? + src/bench/bench_bitcoin --help + +To print options like scaling factor or per-benchmark filter. Notes --------------------- More benchmarks are needed for, in no particular order: - Script Validation -- CCoinDBView caching - Coins database - Memory pool -- Wallet coin selection +- Cuckoo Cache +- P2P throughput + +Going Further +-------------------- + +To monitor Bitcoin Core performance more in depth (like reindex or IBD): https://github.com/chaincodelabs/bitcoinperf + +To generate Flame Graphs for Bitcoin Core: https://github.com/eklitzke/bitcoin/blob/flamegraphs/doc/flamegraphs.md diff --git a/doc/bips.md b/doc/bips.md index 76edc94c29..3085fa424b 100644 --- a/doc/bips.md +++ b/doc/bips.md @@ -1,4 +1,4 @@ -BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.17.0**): +BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.18.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)). @@ -12,14 +12,14 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.17.0**): * [`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 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)). As of **v0.13.0**, this is only available for `NODE_BLOOM` (BIP 111) peers. +* [`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)). Disabled by default since **v0.19.0**, can be enabled by the `-peerbloomfilters` option. * [`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)). Starting *v0.17.0*, whether to send reject messages can be configured with the `-enablebip61` option. +* [`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)). Starting **v0.17.0**, whether to send reject messages can be configured with the `-enablebip61` option, and support is deprecated as of **v0.18.0**. * [`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 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)). Support can be optionally disabled at build time since **v0.18.0** ([PR 14451](https://github.com/bitcoin/bitcoin/pull/14451)). * [`BIP 90`](https://github.com/bitcoin/bips/blob/master/bip-0090.mediawiki): Trigger mechanism for activation of BIPs 34, 65, and 66 has been simplified to block height checks since **v0.14.0** ([PR #8391](https://github.com/bitcoin/bitcoin/pull/8391)). * [`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*. @@ -33,7 +33,7 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.17.0**): * [`BIP 145`](https://github.com/bitcoin/bips/blob/master/bip-0145.mediawiki): getblocktemplate updates for Segregated Witness as of **v0.13.0** ([PR 8149](https://github.com/bitcoin/bitcoin/pull/8149)). * [`BIP 147`](https://github.com/bitcoin/bips/blob/master/bip-0147.mediawiki): NULLDUMMY softfork as of **v0.13.1** ([PR 8636](https://github.com/bitcoin/bitcoin/pull/8636) and [PR 8937](https://github.com/bitcoin/bitcoin/pull/8937)). * [`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)). -* [`BIP 159`](https://github.com/bitcoin/bips/blob/master/bip-0159.mediawiki): NODE_NETWORK_LIMITED service bit [signaling only] is supported as of **v0.16.0** ([PR 11740](https://github.com/bitcoin/bitcoin/pull/11740)). +* [`BIP 159`](https://github.com/bitcoin/bips/blob/master/bip-0159.mediawiki): The NODE_NETWORK_LIMITED service bit is signalled as of **v0.16.0** ([PR 11740](https://github.com/bitcoin/bitcoin/pull/11740)), and such nodes are connected to as of **v0.17.0** ([PR 10387](https://github.com/bitcoin/bitcoin/pull/10387)). * [`BIP 173`](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki): Bech32 addresses for native Segregated Witness outputs are supported as of **v0.16.0** ([PR 11167](https://github.com/bitcoin/bitcoin/pull/11167)). * [`BIP 174`](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki): RPCs to operate on Partially Signed Bitcoin Transactions (PSBT) are present as of **v0.17.0** ([PR 13557](https://github.com/bitcoin/bitcoin/pull/13557)). * [`BIP 176`](https://github.com/bitcoin/bips/blob/master/bip-0176.mediawiki): Bits Denomination [QT only] is supported as of **v0.16.0** ([PR 12035](https://github.com/bitcoin/bitcoin/pull/12035)). diff --git a/doc/bitcoin-conf.md b/doc/bitcoin-conf.md index 88ecb8fe65..f4a8edec75 100644 --- a/doc/bitcoin-conf.md +++ b/doc/bitcoin-conf.md @@ -30,8 +30,33 @@ Network specific options can be: - placed into sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`) or `[regtest]`; - prefixed with a chain name; e.g., `regtest.maxmempool=100`. +Network specific options take precedence over non-network specific options. +If multiple values for the same option are found with the same precedence, the +first one is generally chosen. + +This means that given the following configuration, `regtest.rpcport` is set to `3000`: + +``` +regtest=1 +rpcport=2000 +regtest.rpcport=3000 + +[regtest] +rpcport=4000 +``` + ## Configuration File Path The configuration file is not automatically created; you can create it using your favorite text editor. By default, the configuration file name is `bitcoin.conf` and it is located in the Bitcoin data directory, but both the Bitcoin data directory and the configuration file path may be changed using the `-datadir` and `-conf` command-line options. The `includeconf=<file>` option in the `bitcoin.conf` file can be used to include additional configuration files. + +### Default configuration file locations + +Operating System | Data Directory | Example Path +-- | -- | -- +Windows | `%APPDATA%\Bitcoin\` | `C:\Users\username\AppData\Roaming\Bitcoin\bitcoin.conf` +Linux | `$HOME/.bitcoin/` | `/home/username/.bitcoin/bitcoin.conf` +macOS | `$HOME/Library/Application Support/Bitcoin/` | `/Users/username/Library/Application Support/Bitcoin/bitcoin.conf` + +You can find an example bitcoin.conf file in [share/examples/bitcoin.conf](../share/examples/bitcoin.conf). diff --git a/doc/build-osx.md b/doc/build-osx.md index 119896dc67..9942449bf6 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,33 +1,37 @@ -macOS Build Instructions and Notes -==================================== +# macOS Build Instructions and Notes + The commands in this guide should be executed in a Terminal application. -The built-in one is located in `/Applications/Utilities/Terminal.app`. +The built-in one is located in +``` +/Applications/Utilities/Terminal.app +``` -Preparation ------------ +## Preparation Install the macOS command line tools: -`xcode-select --install` +```shell +xcode-select --install +``` When the popup appears, click `Install`. Then install [Homebrew](https://brew.sh). -Dependencies ----------------------- - - brew install automake berkeley-db4 libtool boost miniupnpc openssl pkg-config protobuf python qt libevent qrencode +## Dependencies +```shell +brew install automake berkeley-db4 libtool boost miniupnpc openssl pkg-config python qt libevent qrencode +``` See [dependencies.md](dependencies.md) for a complete overview. If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG: +```shell +brew install librsvg +``` - brew install librsvg - -Berkeley DB ------------ +## Berkeley DB It is recommended to use Berkeley DB 4.8. If you have to build it yourself, -you can use [the installation script included in contrib/](/contrib/install_db4.sh) +you can use [this](/contrib/install_db4.sh) script to install it like so: ```shell @@ -38,170 +42,167 @@ from the root of the repository. **Note**: You only need Berkeley DB if the wallet is enabled (see [*Disable-wallet mode*](/doc/build-osx.md#disable-wallet-mode)). -Build Bitcoin Core ------------------------- +## Build Bitcoin Core 1. Clone the Bitcoin Core source code: - - git clone https://github.com/bitcoin/bitcoin - cd bitcoin + ```shell + git clone https://github.com/bitcoin/bitcoin + cd bitcoin + ``` 2. Build Bitcoin Core: Configure and build the headless Bitcoin Core binaries as well as the GUI (if Qt is found). You can disable the GUI build by passing `--without-gui` to configure. - - ./autogen.sh - ./configure - make + ```shell + ./autogen.sh + ./configure + make + ``` 3. It is recommended to build and run the unit tests: - - make check - -4. You can also create a .dmg that contains the .app bundle (optional): - - make deploy - -Disable-wallet mode --------------------- -When the intention is to run only a P2P node without a wallet, Bitcoin Core may be compiled in -disable-wallet mode with: - - ./configure --disable-wallet + ```shell + make check + ``` + +4. You can also create a `.dmg` that contains the `.app` bundle (optional): + ```shell + make deploy + ``` + +## `disable-wallet` mode +When the intention is to run only a P2P node without a wallet, Bitcoin Core may be +compiled in `disable-wallet` mode with: +```shell +./configure --disable-wallet +``` In this case there is no dependency on Berkeley DB 4.8. Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call. -Running -------- - +## Running Bitcoin Core is now available at `./src/bitcoind` Before running, you may create an empty configuration file: +```shell +mkdir -p "/Users/${USER}/Library/Application Support/Bitcoin" - touch "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" +touch "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" - chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" +chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" +``` -The first time you run bitcoind, it will start downloading the blockchain. This process could take many hours, or even days on slower than average systems. +The first time you run bitcoind, it will start downloading the blockchain. This process could +take many hours, or even days on slower than average systems. You can monitor the download process by looking at the debug.log file: +```shell +tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log +``` - tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log - -Other 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. - -Notes ------ - -* Tested on OS X 10.10 Yosemite through macOS 10.13 High Sierra on 64-bit Intel processors only. - -* Building with downloaded Qt binaries is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714) +## Other commands: +```shell +./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. +``` -Deterministic macOS DMG Notes ------------------------------ +## Notes +* Tested on OS X 10.10 Yosemite through macOS 10.14 Mojave on 64-bit Intel +processors only. +* Building with downloaded Qt binaries is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714). -Working macOS DMGs are created in Linux by combining a recent clang, -the Apple binutils (ld, ar, etc) and DMG authoring tools. +## Deterministic macOS DMG Notes +Working macOS 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 macOS. +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 macOS. -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: -[mingwandroid/toolchain4](https://github.com/mingwandroid/toolchain4). +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: [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. +In order to build a working toolchain, the following source packages are needed from +Apple: `cctools`, `dyld`, and `ld64`. -These tools inject timestamps by default, which produce non-deterministic -binaries. The ZERO_AR_DATE environment variable is used to disable that. +These tools inject timestamps by default, which produce non-deterministic binaries. The +`ZERO_AR_DATE` environment variable is used to disable that. -This version of cctools has been patched to use the current version of clang's -headers and its libLTO.so rather than those from llvmgcc, as it was -originally done in toolchain4. +This version of `cctools` has been patched to use the current version of `clang`'s headers +and its `libLTO.so` rather than those from `llvmgcc`, as it was 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 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). +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 an Apple 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: +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.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, there are two options: +Unfortunately, the usual Linux tools (7zip, hpmount, loopback mount) are incapable of +opening this file. To create a tarball suitable for Gitian input, there are two options: -Using macOS, you can mount the dmg, and then create it with: -``` - $ hdiutil attach Xcode_7.3.1.dmg - $ tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.11.sdk.tar.gz MacOSX10.11.sdk +Using macOS, you can mount the DMG, and then create it with: +```shell +hdiutil attach Xcode_7.3.1.dmg +tar -C /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ -czf MacOSX10.11.sdk.tar.gz MacOSX10.11.sdk ``` -Alternatively, you can use 7zip and SleuthKit to extract the files one by one. -The script contrib/macdeploy/extract-osx-sdk.sh automates this. First ensure -the dmg file is in the current directory, and then run the script. You may wish -to delete the intermediate 5.hfs file and MacOSX10.11.sdk (the directory) when -you've confirmed the extraction succeeded. +Alternatively, you can use 7zip and SleuthKit to extract the files one by one. The script +[`extract-osx-sdk.sh`](./../contrib/macdeploy/extract-osx-sdk.sh) automates this. First +ensure the DMG file is in the current directory, and then run the script. You may wish to +delete the `intermediate 5.hfs` file and `MacOSX10.11.sdk` (the directory) when you've +confirmed the extraction succeeded. -```bash +```shell apt-get install p7zip-full sleuthkit contrib/macdeploy/extract-osx-sdk.sh rm -rf 5.hfs MacOSX10.11.sdk ``` -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. +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. -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: [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` 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: [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: [theuni/libdmg-hfsplus](https://github.com/theuni/libdmg-hfsplus). +`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: [theuni/libdmg-hfsplus](https://github.com/theuni/libdmg-hfsplus). -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. +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. This is generated by the script -contrib/macdeploy/custom_dsstore.py. - -As of OS X 10.9 Mavericks, 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 - 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. 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. +`.DS_Store` before creation. This is generated by the script +`contrib/macdeploy/custom_dsstore.py`. + +As of OS X 10.9 Mavericks, 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 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. 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/build-unix.md b/doc/build-unix.md index da65bc347a..069c983e6e 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -44,7 +44,7 @@ Optional dependencies: miniupnpc | UPnP Support | Firewall-jumping support libdb4.8 | Berkeley DB | Wallet storage (only needed when wallet enabled) 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) + protobuf | Payments in GUI | Data interchange format used for payment protocol (only needed when BIP70 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.0.0) @@ -61,6 +61,14 @@ tuned to conserve memory with additional CXXFLAGS: ./configure CXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768" +Alternatively, or in addition, debugging information can be skipped for compilation. The default compile flags are +`-g -O2`, and can be changed with: + + ./configure CXXFLAGS="-O2" + +Finally, clang (often less resource hungry) can be used instead of gcc, which is used by default: + + ./configure CXX=clang++ CC=clang ## Linux Distribution Specific Instructions @@ -78,7 +86,7 @@ Now, you can either build from self-compiled [depends](/depends/README.md) or in BerkeleyDB is required for the wallet. -Ubuntu and Debian have their own libdb-dev and libdb++-dev packages, but these will install +Ubuntu and Debian have their own `libdb-dev` and `libdb++-dev` packages, but these will install BerkeleyDB 5.1 or later. This will 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. @@ -88,7 +96,7 @@ Otherwise, you can build from self-compiled `depends` (see above). To build Bitcoin Core without wallet, see [*Disable-wallet mode*](/doc/build-unix.md#disable-wallet-mode) -Optional (see --with-miniupnpc and --enable-upnp-default): +Optional (see `--with-miniupnpc` and `--enable-upnp-default`): sudo apt-get install libminiupnpc-dev @@ -104,12 +112,16 @@ To build without GUI pass `--without-gui`. To build with Qt 5 you need the following: - sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler + sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libqrencode (optional) can be installed with: sudo apt-get install libqrencode-dev +protobuf (optional) can be installed with: + + sudo apt-get install libprotobuf-dev protobuf-compiler + Once these are installed, they will be found by configure and a bitcoin-qt executable will be built by default. @@ -122,18 +134,26 @@ Build requirements: sudo dnf install gcc-c++ libtool make autoconf automake openssl-devel libevent-devel boost-devel libdb4-devel libdb4-cxx-devel python3 -Optional: +Optional (see `--with-miniupnpc` and `--enable-upnp-default`): sudo dnf install miniupnpc-devel +ZMQ dependencies (provides ZMQ API): + + sudo dnf install zeromq-devel + To build with Qt 5 you need the following: - sudo dnf install qt5-qttools-devel qt5-qtbase-devel protobuf-devel + sudo dnf install qt5-qttools-devel qt5-qtbase-devel libqrencode (optional) can be installed with: sudo dnf install qrencode-devel +protobuf (optional) can be installed with: + + sudo dnf install protobuf-devel + Notes ----- The release is built with GCC and then "strip bitcoind" to strip the debug diff --git a/doc/build-windows.md b/doc/build-windows.md index 036c585b44..5ca9f98475 100644 --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -102,30 +102,6 @@ Build using: CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/ make -## Building for 32-bit Windows - -To build executables for Windows 32-bit, install the following dependencies: - - sudo apt install g++-mingw-w64-i686 mingw-w64-i686-dev - -For Ubuntu Bionic 18.04 and Windows Subsystem for Linux <sup>[1](#footnote1)</sup>: - - sudo update-alternatives --config i686-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. - -Note that for WSL the Bitcoin Core source path MUST be somewhere in the default mount file system, for -example /usr/src/bitcoin, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. -This means you cannot use a directory that located directly on the host Windows file system to perform the build. - -Build using: - - PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var - cd depends - make HOST=i686-w64-mingw32 - cd .. - ./autogen.sh # not required when building from tarball - CONFIG_SITE=$PWD/depends/i686-w64-mingw32/share/config.site ./configure --prefix=/ - make - ## Depends system For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. diff --git a/doc/dependencies.md b/doc/dependencies.md index 0fb36184c2..e5b4084d99 100644 --- a/doc/dependencies.md +++ b/doc/dependencies.md @@ -6,27 +6,25 @@ These are the dependencies currently used by Bitcoin Core. You can find instruct | Dependency | Version used | Minimum required | CVEs | Shared | [Bundled Qt library](https://doc.qt.io/qt-5/configure-options.html#third-party-libraries) | | --- | --- | --- | --- | --- | --- | | Berkeley DB | [4.8.30](https://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html) | 4.8.x | No | | | -| Boost | [1.64.0](https://www.boost.org/users/download/) | [1.47.0](https://github.com/bitcoin/bitcoin/pull/8920) | No | | | -| Clang | | [3.3+](https://llvm.org/releases/download.html) (C++11 support) | | | | -| D-Bus | [1.10.18](https://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=dbus-1.10) | | No | Yes | | -| Expat | [2.2.6](https://libexpat.github.io/) | | No | Yes | | +| Boost | [1.70.0](https://www.boost.org/users/download/) | [1.47.0](https://github.com/bitcoin/bitcoin/pull/8920) | No | | | +| Clang | | [3.3+](https://releases.llvm.org/download.html) (C++11 support) | | | | +| Expat | [2.2.7](https://libexpat.github.io/) | | No | Yes | | | fontconfig | [2.12.1](https://www.freedesktop.org/software/fontconfig/release/) | | No | Yes | | | FreeType | [2.7.1](https://download.savannah.gnu.org/releases/freetype) | | No | | | | GCC | | [4.8+](https://gcc.gnu.org/) (C++11 support) | | | | | HarfBuzz-NG | | | | | | | libevent | [2.1.8-stable](https://github.com/libevent/libevent/releases) | 2.0.22 | No | | | -| libjpeg | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L65) | -| libpng | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L64) | -| libsrvg | | | | | | +| libpng | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | +| librsvg | | | | | | | MiniUPnPc | [2.0.20180203](http://miniupnp.free.fr/files) | | No | | | | OpenSSL | [1.0.1k](https://www.openssl.org/source) | | Yes | | | -| PCRE | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L66) | +| PCRE | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | | protobuf | [2.6.1](https://github.com/google/protobuf/releases) | | No | | | | Python (tests) | | [3.5](https://www.python.org/downloads) | | | | | qrencode | [3.4.4](https://fukuchi.org/works/qrencode) | | No | | | | Qt | [5.9.7](https://download.qt.io/official_releases/qt/) | [5.5.1](https://github.com/bitcoin/bitcoin/issues/13478) | No | | | -| XCB | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L87) (Linux only) | -| xkbcommon | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L86) (Linux only) | +| XCB | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) (Linux only) | +| xkbcommon | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) (Linux only) | | ZeroMQ | [4.3.1](https://github.com/zeromq/libzmq/releases) | 4.0.0 | No | | | | zlib | [1.2.11](https://zlib.net/) | | | | No | @@ -37,10 +35,10 @@ Some dependencies are not needed in all configurations. The following are some f #### Options passed to `./configure` * MiniUPnPc is not needed with `--with-miniupnpc=no`. * Berkeley DB is not needed with `--disable-wallet`. -* protobuf is not needed with `--disable-bip70`. +* protobuf is only needed with `--enable-bip70`. * Qt is not needed with `--without-gui`. * If the qrencode dependency is absent, QR support won't be added. To force an error when that happens, pass `--with-qrencode`. * ZeroMQ is needed only with the `--with-zmq` option. #### Other -* librsvg is only needed if you need to run `make deploy` on (cross-compliation to) macOS.
\ No newline at end of file +* librsvg is only needed if you need to run `make deploy` on (cross-compilation to) macOS. diff --git a/doc/descriptors.md b/doc/descriptors.md index 5dbcd95e1d..dbdac2c5b6 100644 --- a/doc/descriptors.md +++ b/doc/descriptors.md @@ -1,11 +1,18 @@ # Support for Output Descriptors in Bitcoin Core -Since Bitcoin Core v0.17, there is support for Output Descriptors in the -`scantxoutset` RPC call. This is a simple language which can be used to -describe collections of output scripts. - -This document describes the language. For the specifics on usage for scanning -the UTXO set, see the `scantxoutset` RPC help. +Since Bitcoin Core v0.17, there is support for Output Descriptors. This is a +simple language which can be used to describe collections of output scripts. +Supporting RPCs are: +- `scantxoutset` takes as input descriptors to scan for, and also reports + specialized descriptors for the matching UTXOs. +- `getdescriptorinfo` analyzes a descriptor, and reports a canonicalized version + with checksum added. +- `deriveaddresses` takes as input a descriptor and computes the corresponding + addresses. +- `listunspent` outputs a specialized descriptor for the reported unspent outputs. + +This document describes the language. For the specifics on usage, see the RPC +documentation for the functions mentioned above. ## Features diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 2662eea8fc..f4a5e2d330 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -27,14 +27,13 @@ Developer Notes - [General C++](#general-c) - [C++ data structures](#c-data-structures) - [Strings and formatting](#strings-and-formatting) - - [Variable names](#variable-names) + - [Shadowing](#shadowing) - [Threads and synchronization](#threads-and-synchronization) - [Scripts](#scripts) - [Shebang](#shebang) - [Source code organization](#source-code-organization) - [GUI](#gui) - [Subtrees](#subtrees) - - [Git and GitHub tips](#git-and-github-tips) - [Scripted diffs](#scripted-diffs) - [Release notes](#release-notes) - [RPC interface guidelines](#rpc-interface-guidelines) @@ -63,7 +62,7 @@ tool to clean up patches automatically before submission. - 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 `namespace`. - - No extra spaces inside parenthesis; don't do ( this ) + - No extra spaces inside parenthesis; don't do ( this ). - No space after function names; one space after `if`, `for` and `while`. - If an `if` only has a single-statement `then`-clause, it can appear on the same line as the `if`, without braces. In every other case, @@ -73,12 +72,12 @@ tool to clean up patches automatically before submission. - **Symbol naming conventions**. These are preferred in new code, but are not required when doing so would need changes to significant pieces of existing code. - - Variable (including function arguments) and namespace names are all lowercase, and may use `_` to + - Variable (including function arguments) and namespace names are all lowercase and may use `_` to separate words (snake_case). - Class member variables have a `m_` prefix. - Global variables have a `g_` prefix. - Constant names are all uppercase, and use `_` to separate words. - - Class names, function names and method names are UpperCamelCase + - Class names, function names, and method names are UpperCamelCase (PascalCase). Do not prefix class names with `C`. - Test suite naming convention: The Boost test suite in file `src/test/foo_tests.cpp` should be named `foo_tests`. Test suite names @@ -135,6 +134,7 @@ Bitcoin Core uses [Doxygen](http://www.doxygen.nl/) to generate its official doc Use Doxygen-compatible comment blocks for functions, methods, and fields. For example, to describe a function use: + ```c++ /** * ... text ... @@ -144,11 +144,12 @@ For example, to describe a function use: */ bool function(int arg1, const char *arg2) ``` + A complete list of `@xxx` commands can be found at http://www.doxygen.nl/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: +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 @@ -190,9 +191,9 @@ but the above styles are favored. Documentation can be generated with `make docs` and cleaned up with `make clean-docs`. The resulting files are located in `doc/doxygen/html`; open `index.html` to view the homepage. -Before running `make docs`, you will need to install dependencies `doxygen` and `dot`. For example, on MacOS via Homebrew: +Before running `make docs`, you will need to install dependencies `doxygen` and `dot`. For example, on macOS via Homebrew: ``` -brew install doxygen --with-graphviz +brew install graphviz doxygen ``` Development tips and tricks @@ -232,7 +233,7 @@ that run in `-regtest` mode. Bitcoin Core is a multi-threaded application, and deadlocks or other multi-threading bugs can be very difficult to track down. The `--enable-debug` configure option adds `-DDEBUG_LOCKORDER` to the compiler flags. This inserts -run-time checks to keep track of which locks are held, and adds warnings to the +run-time checks to keep track of which locks are held and adds warnings to the debug.log file if inconsistencies are detected. ### Valgrind suppressions file @@ -280,7 +281,7 @@ thread](https://askubuntu.com/questions/50145/how-to-install-perf-monitoring-too for specific instructions. Certain kernel parameters may need to be set for perf to be able to inspect the -running process' stack. +running process's stack. ```sh $ sudo sysctl -w kernel.perf_event_paranoid=-1 @@ -300,7 +301,7 @@ $ perf record \ -p `pgrep bitcoind` -- sleep 60 ``` -You could then analyze the results by running +You could then analyze the results by running: ```sh perf report --stdio | c++filt | less @@ -365,7 +366,7 @@ Additional resources: Locking/mutex usage notes ------------------------- -The code is multi-threaded, and uses mutexes and the +The code is multi-threaded and uses mutexes and the `LOCK` and `TRY_LOCK` macros to protect data structures. Deadlocks due to inconsistent lock ordering (thread 1 locks `cs_main` and then @@ -376,7 +377,7 @@ 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 `CBasicKeyStore` class +done by the components (e.g. see the self-contained `FillableSigningProvider` class and its `cs_KeyStore` lock for example). Threads @@ -390,7 +391,7 @@ Threads - ThreadDNSAddressSeed : Loads addresses of peers from the DNS. -- ThreadMapPort : Universal plug-and-play startup/shutdown +- ThreadMapPort : Universal plug-and-play startup/shutdown. - ThreadSocketHandler : Sends/Receives data from peers on port 8333. @@ -409,7 +410,7 @@ Threads Ignoring IDE/editor files -------------------------- -In closed-source environments in which everyone uses the same IDE it is common +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 @@ -447,19 +448,19 @@ 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 +- 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 + the GUI is very limited. -- Make sure pull requests pass Travis CI before merging +- 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 + 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 + be done first. Wallet ------- @@ -467,35 +468,43 @@ 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` + `validateaddress`), it is easy to forget that global pointer `pwalletMain` can be nullptr. See `test/functional/disablewallet.py` for functional tests - exercising the API with `-disablewallet` + exercising the API with `-disablewallet`. -- Include `db_cxx.h` (BerkeleyDB header) only when `ENABLE_WALLET` is set +- 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 + - *Rationale*: Otherwise compilation of the disable-wallet build will fail in environments without BerkeleyDB. General C++ ------------- -- Assertions should not have side-effects +For general C++ guidelines, you may refer to the [C++ Core +Guidelines](https://isocpp.github.io/CppCoreGuidelines/). + +Common misconceptions are clarified in those sections: + +- Passing (non-)fundamental types in the [C++ Core + Guideline](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-conventional). + +- Assertions should not have side-effects. - *Rationale*: Even though the source code is set to refuse to compile with assertions disabled, having side-effects in assertions is unexpected and - makes the code harder to understand + makes the code harder to understand. -- If you use the `.h`, you must link the `.cpp` +- 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 + 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 +- 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 + - *Rationale*: This avoids memory and resource leaks, and ensures exception safety. -- Use `MakeUnique()` to construct objects owned by `unique_ptr`s +- Use `MakeUnique()` to construct objects owned by `unique_ptr`s. - *Rationale*: `MakeUnique` is concise and ensures exception safety in complex expressions. `MakeUnique` is a temporary project local implementation of `std::make_unique` (C++14). @@ -503,27 +512,27 @@ General C++ C++ data structures -------------------- -- Never use the `std::map []` syntax when reading from a map, but instead use `.find()` +- 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 + 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) + 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 + 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 +- Vector bounds checking is only enabled in debug mode. Do not rely on it. - Initialize all non-static class members where they are defined. If this is skipped for a good reason (i.e., optimization on the critical - path), add an explicit comment about this + path), add an explicit comment about this. - *Rationale*: Ensure determinism by avoiding accidental use of uninitialized values. Also, static analyzers balk about this. @@ -547,12 +556,12 @@ class A `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 + out-of-bounds array accesses. -- Prefer explicit constructions over implicit ones that rely on 'magical' C++ behavior +- 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 + that are not language lawyers. Strings and formatting ------------------------ @@ -560,17 +569,17 @@ 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 + formatting mismatch, and it is easy to get wrong because of subtly similar naming. -- Use `std::string`, avoid C string manipulation functions +- 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 + 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 +- Use `ParseInt32`, `ParseInt64`, `ParseUInt32`, `ParseUInt64`, `ParseDouble` from `utilstrencodings.h` for number parsing. - - *Rationale*: These functions do overflow checking, and avoid pesky locale issues. + - *Rationale*: These functions do overflow checking and avoid pesky locale issues. - Avoid using locale dependent functions if possible. You can use the provided [`lint-locale-dependence.sh`](/test/lint/lint-locale-dependence.sh) @@ -600,48 +609,32 @@ Strings and formatting `wcstoll`, `wcstombs`, `wcstoul`, `wcstoull`, `wcstoumax`, `wcswidth`, `wcsxfrm`, `wctob`, `wctomb`, `wctrans`, `wctype`, `wcwidth`, `wprintf` -- For `strprintf`, `LogPrint`, `LogPrintf` formatting characters don't need size specifiers +- 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 + - *Rationale*: Bitcoin Core uses tinyformat, which is type safe. Leave them out to avoid confusion. -Variable names +Shadowing -------------- -Although the shadowing warning (`-Wshadow`) is not enabled by default (it prevents issues rising +Although the shadowing warning (`-Wshadow`) is not enabled by default (it prevents issues arising from using a different variable with the same name), please name variables so that their names do not shadow variables defined in the source code. -E.g. in member initializers, prepend `_` to the argument name shadowing the -member name: - -```c++ -class AddressBookPage -{ - Mode m_mode; -} - -AddressBookPage::AddressBookPage(Mode _mode) : - m_mode(_mode) -... -``` - When using nested cycles, do not name the inner cycle variable the same as in -upper cycle etc. - +the upper cycle, etc. 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` + 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 + with braces. OK: - ```c++ { TRY_LOCK(cs_vNodes, lockNodes); @@ -650,7 +643,6 @@ Threads and synchronization ``` Wrong: - ```c++ TRY_LOCK(cs_vNodes, lockNodes); { @@ -672,13 +664,11 @@ Scripts `#!/usr/bin/env bash` searches the user's PATH to find the bash binary. OK: - ```bash #!/usr/bin/env bash ``` Wrong: - ```bash #!/bin/bash ``` @@ -687,9 +677,9 @@ 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 + when performance due to inlining is critical. - - *Rationale*: Shorter and simpler header files are easier to read, and reduce compile time + - *Rationale*: Shorter and simpler header files are easier to read and reduce compile time. - Use only the lowercase alphanumerics (`a-z0-9`), underscore (`_`) and hyphen (`-`) in source code filenames. @@ -707,7 +697,7 @@ Source code organization - Don't import anything into the global namespace (`using namespace ...`). Use fully specified types such as `std::string`. - - *Rationale*: Avoids symbol conflicts + - *Rationale*: Avoids symbol conflicts. - Terminate namespaces with a comment (`// namespace mynamespace`). The comment should be placed on the same line as the brace closing the namespace, e.g. @@ -722,7 +712,7 @@ namespace { } // namespace ``` - - *Rationale*: Avoids confusion about the namespace context + - *Rationale*: Avoids confusion about the namespace context. - Use `#include <primitives/transaction.h>` bracket syntax instead of `#include "primitives/transactions.h"` quote syntax. @@ -745,13 +735,13 @@ namespace { GUI ----- -- Do not display or manipulate dialogs in model code (classes `*Model`) +- 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. -- Avoid adding slow or blocking code in the GUI thread. In particular do not +- Avoid adding slow or blocking code in the GUI thread. In particular, do not add new `interfaces::Node` and `interfaces::Wallet` method calls, even if they may be fast now, in case they are changed to lock or communicate across processes in the future. @@ -770,12 +760,12 @@ Subtrees Several parts of the repository are subtrees of software maintained elsewhere. Some of these are maintained by active developers of Bitcoin Core, in which case changes should probably go -directly upstream without being PRed directly against the project. They will be merged back in the next +directly upstream without being PRed directly against the project. They will be merged back in the next subtree merge. -Others are external projects without a tight relationship with our project. Changes to these should also -be sent upstream but bugfixes may also be prudent to PR against Bitcoin Core so that they can be integrated -quickly. Cosmetic changes should be purely taken upstream. +Others are external projects without a tight relationship with our project. Changes to these should also +be sent upstream, but bugfixes may also be prudent to PR against Bitcoin Core so that they can be integrated +quickly. Cosmetic changes should be purely taken upstream. There is a tool in `test/lint/git-subtree-check.sh` to check a subtree directory for consistency with its upstream repository. @@ -805,11 +795,11 @@ you must be aware of. ### File Descriptor Counts -In most configurations we use the default LevelDB value for `max_open_files`, +In most configurations, we use the default LevelDB value for `max_open_files`, which is 1000 at the time of this writing. If LevelDB actually uses this many -file descriptors it will cause problems with Bitcoin's `select()` loop, because +file descriptors, it will cause problems with Bitcoin's `select()` loop, because it may cause new sockets to be created where the fd value is >= 1024. For this -reason, on 64-bit Unix systems we rely on an internal LevelDB optimization that +reason, on 64-bit Unix systems, we rely on an internal LevelDB optimization that uses `mmap()` + `close()` to open table files without actually retaining references to the table file descriptors. If you are upgrading LevelDB, you must sanity check the changes to make sure that this assumption remains valid. @@ -834,14 +824,14 @@ details. It is possible for LevelDB changes to inadvertently change consensus compatibility between nodes. This happened in Bitcoin 0.8 (when LevelDB was -first introduced). When upgrading LevelDB you should review the upstream changes +first introduced). When upgrading LevelDB, you should review the upstream changes to check for issues affecting consensus compatibility. For example, if LevelDB had a bug that accidentally prevented a key from being returned in an edge case, and that bug was fixed upstream, the bug "fix" would -be an incompatible consensus change. In this situation the correct behavior +be an incompatible consensus change. In this situation, the correct behavior would be to revert the upstream fix before applying the updates to Bitcoin's -copy of LevelDB. In general you should be wary of any upstream changes affecting +copy of LevelDB. In general, you should be wary of any upstream changes affecting what data is returned from LevelDB queries. Scripted diffs @@ -860,7 +850,7 @@ To create a scripted-diff: - `-BEGIN VERIFY SCRIPT-` - `-END VERIFY SCRIPT-` -The scripted-diff is verified by the tool `test/lint/commit-script-check.sh`. The tool's default behavior when supplied +The scripted-diff is verified by the tool `test/lint/commit-script-check.sh`. The tool's default behavior, when supplied with a commit is to verify all scripted-diffs from the beginning of time up to said commit. Internally, the tool passes the first supplied argument to `git rev-list --reverse` to determine which commits to verify script-diffs for, ignoring commits that don't conform to the commit message format described above. @@ -893,23 +883,23 @@ RPC interface guidelines A few guidelines for introducing and reviewing new RPC interfaces: -- Method naming: use consecutive lower-case names such as `getrawtransaction` and `submitblock` +- Method naming: use consecutive lower-case names such as `getrawtransaction` and `submitblock`. - - *Rationale*: Consistency with existing interface. + - *Rationale*: Consistency with the existing interface. - Argument naming: use snake case `fee_delta` (and not, e.g. camel case `feeDelta`) - - *Rationale*: Consistency with existing interface. + - *Rationale*: Consistency with the existing interface. - Use the JSON parser for parsing, don't manually parse integers or strings from arguments unless absolutely necessary. - *Rationale*: Introduces hand-rolled string manipulation code at both the caller and callee sites, - which is error prone, and it is easy to get things such as escaping wrong. + which is error-prone, and it is easy to get things such as escaping wrong. JSON already supports nested data structures, no need to re-invent the wheel. - *Exception*: AmountFromValue can parse amounts as string. This was introduced because many JSON - parsers and formatters hard-code handling decimal numbers as floating point + parsers and formatters hard-code handling decimal numbers as floating-point values, resulting in potential loss of precision. This is unacceptable for monetary values. **Always** use `AmountFromValue` and `ValueFromAmount` when inputting or outputting monetary values. The only exceptions to this are @@ -918,7 +908,7 @@ A few guidelines for introducing and reviewing new RPC interfaces: - Missing arguments and 'null' should be treated the same: as default values. If there is no default value, both cases should fail in the same way. The easiest way to follow this - guideline is detect unspecified arguments with `params[x].isNull()` instead of + guideline is to detect unspecified arguments with `params[x].isNull()` instead of `params.size() <= x`. The former returns true if the argument is either null or missing, while the latter returns true if is missing, and false if it is null. @@ -952,8 +942,7 @@ A few guidelines for introducing and reviewing new RPC interfaces: from there. - A RPC method must either be a wallet method or a non-wallet method. Do not - introduce new methods such as `signrawtransaction` that differ in behavior - based on presence of a wallet. + introduce new methods that differ in behavior based on the presence of a wallet. - *Rationale*: as well as complicating the implementation and interfering with the introduction of multi-wallet, wallet and non-wallet code should be @@ -961,7 +950,7 @@ A few guidelines for introducing and reviewing new RPC interfaces: - Try to make the RPC response a JSON object. - - *Rationale*: If a RPC response is not a JSON object then it is harder to avoid API breakage if + - *Rationale*: If a RPC response is not a JSON object, then it is harder to avoid API breakage if new data in the response is needed. - Wallet RPCs call BlockUntilSyncedToCurrentChain to maintain consistency with diff --git a/doc/fuzzing.md b/doc/fuzzing.md index f9221dde5b..3dc6be8b86 100644 --- a/doc/fuzzing.md +++ b/doc/fuzzing.md @@ -46,7 +46,7 @@ export AFLPATH=$PWD To build Bitcoin Core using AFL instrumentation (this assumes that the `AFLPATH` was set as above): ``` -./configure --disable-ccache --disable-shared --enable-tests --enable-fuzz --disable-wallet --disable-bench --with-utils=no --with-daemon=no --with-libs=no --with-gui=no CC=${AFLPATH}/afl-gcc CXX=${AFLPATH}/afl-g++ +./configure --disable-ccache --disable-shared --enable-tests --enable-fuzz CC=${AFLPATH}/afl-gcc CXX=${AFLPATH}/afl-g++ export AFL_HARDEN=1 cd src/ make @@ -83,7 +83,7 @@ found in the `compiler-rt` runtime libraries package). To build all fuzz targets with libFuzzer, run ``` -./configure --disable-ccache --disable-wallet --disable-bench --with-utils=no --with-daemon=no --with-libs=no --with-gui=no --enable-fuzz --with-sanitizers=fuzzer,address CC=clang CXX=clang++ +./configure --disable-ccache --enable-fuzz --with-sanitizers=fuzzer,address CC=clang CXX=clang++ make ``` diff --git a/doc/init.md b/doc/init.md index a6c9bb94d8..0b327aab58 100644 --- a/doc/init.md +++ b/doc/init.md @@ -53,17 +53,17 @@ Paths 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` +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 `/run/bitcoind/bitcoind.pid` (systemd) -Lock file: `/var/lock/subsys/bitcoind` (CentOS) +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 -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. +The PID directory (if applicable) and data directory should both be owned by the +bitcoin user and group. It is advised for security 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. NOTE: When using the systemd .service file, the creation of the aforementioned directories and the setting of their permissions is automatically handled by @@ -83,10 +83,10 @@ OpenRC). ### macOS -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` +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` Installing Service Configuration ----------------------------------- diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 9b36319e64..edbc0911a1 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -15,3 +15,9 @@ endif if BUILD_BITCOIN_TX dist_man1_MANS+=bitcoin-tx.1 endif + +if ENABLE_WALLET +if BUILD_BITCOIN_WALLET + dist_man1_MANS+=bitcoin-wallet.1 +endif +endif diff --git a/doc/man/bitcoin-qt.1 b/doc/man/bitcoin-qt.1 index 052d420608..1e8443b1d3 100644 --- a/doc/man/bitcoin-qt.1 +++ b/doc/man/bitcoin-qt.1 @@ -488,9 +488,6 @@ Relay and mine data carrier transactions (default: 1) Maximum size of data in data carrier transactions we relay and mine (default: 83) .HP -\fB\-mempoolreplacement\fR -.IP -Enable transaction replacement in the memory pool (default: 1) .HP \fB\-minrelaytxfee=\fR<amt> .IP diff --git a/doc/man/bitcoind.1 b/doc/man/bitcoind.1 index 5e057d923f..2a79b6cb46 100644 --- a/doc/man/bitcoind.1 +++ b/doc/man/bitcoind.1 @@ -488,10 +488,6 @@ Relay and mine data carrier transactions (default: 1) Maximum size of data in data carrier transactions we relay and mine (default: 83) .HP -\fB\-mempoolreplacement\fR -.IP -Enable transaction replacement in the memory pool (default: 1) -.HP \fB\-minrelaytxfee=\fR<amt> .IP Fees (in BTC/kB) smaller than this are considered zero fee for relaying, diff --git a/doc/productivity.md b/doc/productivity.md index e0df558944..b25ddc94e5 100644 --- a/doc/productivity.md +++ b/doc/productivity.md @@ -8,7 +8,9 @@ Table of Contents * [Cache compilations with `ccache`](#cache-compilations-with-ccache) * [Disable features with `./configure`](#disable-features-with-configure) * [Make use of your threads with `make -j`](#make-use-of-your-threads-with-make--j) + * [Only build what you need](#only-build-what-you-need) * [Multiple working directories with `git worktrees`](#multiple-working-directories-with-git-worktrees) + * [Interactive "dummy rebases" for fixups and execs with `git merge-base`](#interactive-dummy-rebases-for-fixups-and-execs-with-git-merge-base) * [Writing code](#writing-code) * [Format C/C++/Protobuf diffs with `clang-format-diff.py`](#format-ccprotobuf-diffs-with-clang-format-diffpy) * [Format Python diffs with `yapf-diff.py`](#format-python-diffs-with-yapf-diffpy) @@ -32,6 +34,17 @@ Install `ccache` through your distribution's package manager, and run `./configu To use ccache for all your C/C++ projects, follow the symlinks method [here](https://ccache.samba.org/manual/latest.html#_run_modes) to set it up. +To get the most out of ccache, put something like this in `~/.ccache/ccache.conf`: + +``` +max_size = 50.0G # or whatever cache size you prefer; default is 5G; 0 means unlimited +base_dir = /home/yourname # or wherever you keep your source files +``` + +Note: base_dir is required for ccache to share cached compiles of the same file across different repositories / paths; it will only do this for paths under base_dir. So this option is required for effective use of ccache with git worktrees (described below). + +You _must not_ set base_dir to "/", or anywhere that contains system headers (according to the ccache docs). + ### Disable features with `./configure` After running `./autogen.sh`, which generates the `./configure` file, use `./configure --help` to identify features that you can disable to save on compilation time. A few common flags: @@ -43,6 +56,8 @@ After running `./autogen.sh`, which generates the `./configure` file, use `./con --without-gui ``` +If you do need the wallet enabled, it is common for devs to add `--with-incompatible-bdb`. This uses your system bdb version for the wallet, so you don't have to find a copy of bdb 4.8. Wallets from such a build will be incompatible with any release binary (and vice versa), so use with caution on mainnet. + ### Make use of your threads with `make -j` If you have multiple threads on your machine, you can tell `make` to utilize all of them with: @@ -51,6 +66,20 @@ If you have multiple threads on your machine, you can tell `make` to utilize all make -j"$(($(nproc)+1))" ``` +### Only build what you need + +When rebuilding during development, note that running `make`, without giving a target, will do a lot of work you probably don't need. It will build the GUI (unless you've disabled it) and all the tests (which take much longer to build than the app does). + +Obviously, it is important to build and run the tests at appropriate times -- but when you just want a quick compile to check your work, consider picking one or a set of build targets relevant to what you're working on, e.g.: + +```sh +make src/bitcoind src/bitcoin-cli +make src/qt/bitcoin-qt +make -C src bitcoin_bench +``` + +(You can and should combine this with `-j`, as above, for a parallel build.) + ### Multiple working directories with `git worktrees` If you work with multiple branches or multiple copies of the repository, you should try `git worktrees`. @@ -65,6 +94,21 @@ To simply check out a commit-ish under a new working directory without disruptin git worktree add --checkout ../where-my-checkout-commit-ish-will-live my-checkout-commit-ish ``` +### Interactive "dummy rebases" for fixups and execs with `git merge-base` + +When rebasing, we often want to do a "dummy rebase," whereby we are not rebasing over an updated master but rather over the last common commit with master. This might be useful for rearranging commits, `rebase --autosquash`ing, or `rebase --exec`ing without introducing conflicts that arise from an updated master. In these situations, we can use `git merge-base` to identify the last common commit with master, and rebase off of that. + +To squash in `git commit --fixup` commits without rebasing over an updated master, we can do the following: + +```sh +git rebase -i --autosquash "$(git merge-base master HEAD)" +``` + +To execute `make check` on every commit since last diverged from master, but without rebasing over an updated master, we can do the following: +```sh +git rebase -i --exec "make check" "$(git merge-base master HEAD)" +``` + ----- This synergizes well with [`ccache`](#cache-compilations-with-ccache) as objects resulting from unchanged code will most likely hit the cache and won't need to be recompiled. diff --git a/doc/psbt.md b/doc/psbt.md index 560b45ef31..c411b31d5d 100644 --- a/doc/psbt.md +++ b/doc/psbt.md @@ -67,6 +67,9 @@ hardware implementations will typically implement multiple roles simultaneously. input a PSBT, adds UTXO, key, and script data to inputs and outputs that miss it, and optionally signs inputs. Where possible it also finalizes the partial signatures. +- **`utxoupdatepsbt` (Updater)** is a node RPC that takes a PSBT and updates it + to include information available from the UTXO set (works only for SegWit + inputs). - **`finalizepsbt` (Finalizer, Extractor)** is a utility RPC that finalizes any partial signatures, and if all inputs are finalized, converts the result to a fully signed transaction which can be broadcast with `sendrawtransaction`. @@ -74,8 +77,16 @@ hardware implementations will typically implement multiple roles simultaneously. can be used at any point in the workflow to merge information added to different versions of the same PSBT. In particular it is useful to combine the output of multiple Updaters or Signers. +- **`joinpsbts`** (Creator) is a utility RPC that joins multiple PSBTs together, + concatenating the inputs and outputs. This can be used to construct CoinJoin + transactions. - **`decodepsbt`** is a diagnostic utility RPC which will show all information in a PSBT in human-readable form, as well as compute its eventual fee if known. +- **`analyzepsbt`** is a utility RPC that examines a PSBT and reports the + current status of its inputs, the next step in the workflow if known, and if + possible, computes the fee of the resulting transaction and estimates the + final weight and feerate. + ### Workflows diff --git a/doc/rapidcheck.md b/doc/rapidcheck.md new file mode 100644 index 0000000000..397a907f17 --- /dev/null +++ b/doc/rapidcheck.md @@ -0,0 +1,84 @@ +# RapidCheck property-based testing for Bitcoin Core + +## Concept + +Property-based testing is experimentally being added to Bitcoin Core with +[RapidCheck](https://github.com/emil-e/rapidcheck), a C++ framework for +property-based testing inspired by the Haskell library +[QuickCheck](https://hackage.haskell.org/package/QuickCheck). + +RapidCheck performs random testing of program properties. A specification of the +program is given in the form of properties which functions should satisfy, and +RapidCheck tests that the properties hold in a large number of randomly +generated cases. + +If an exception is found, RapidCheck tries to find the smallest case, for some +definition of smallest, for which the property is still false and displays it as +a counter-example. For example, if the input is an integer, RapidCheck tries to +find the smallest integer for which the property is false. + +## Running + +If RapidCheck is installed, Bitcoin Core will automatically run the +property-based tests with the unit tests during `make check`, unless the +`--without-rapidcheck` flag is passed when configuring. + +For more information, run `./configure --help` and see `--with-rapidcheck` under +Optional Packages. + +## Setup + +The following instructions have been tested with Linux Debian and macOS. + +1. Clone the RapidCheck source code and cd into the repository. + + ```shell + git clone https://github.com/emil-e/rapidcheck.git + cd rapidcheck + ``` + +2. Build RapidCheck (requires CMake to be installed). + + ```shell + cmake -DCMAKE_POSITION_INDEPENDENT_CODE:BOOL=true -DRC_ENABLE_BOOST_TEST=ON $(pwd) + make && make install + ``` + +3. Configure Bitcoin Core with RapidCheck. + + `cd` to the directory of your local bitcoin repository and run + `./configure`. In the output you should see: + + ```shell + checking rapidcheck.h usability... yes + checking rapidcheck.h presence... yes + checking for rapidcheck.h... yes + [...] + Options used to compile and link: + [...] + with test = yes + with prop = yes + ``` + +4. Build Bitcoin Core with RapidCheck. + + Now you can run `make` and should see the property-based tests compiled with + the unit tests: + + ```shell + Making all in src + [...] + CXX test/gen/test_bitcoin-crypto_gen.o + CXX test/test_bitcoin-key_properties.o + ``` + +5. Run the unit tests with `make check`. The property-based tests will be run + with the unit tests. + + ```shell + Running tests: crypto_tests from test/crypto_tests.cpp + [...] + Running tests: key_properties from test/key_properties.cpp + ``` + +That's it! You are now running property-based tests in Bitcoin Core. diff --git a/doc/reduce-memory.md b/doc/reduce-memory.md new file mode 100644 index 0000000000..8d8ccdfedc --- /dev/null +++ b/doc/reduce-memory.md @@ -0,0 +1,49 @@ +# Reduce Memory + +There are a few parameters that can be dialed down to reduce the memory usage of `bitcoind`. This can be useful on embedded systems or small VPSes. + +## In-memory caches + +The size of some in-memory caches can be reduced. As caches trade off memory usage for performance, reducing these will usually have a negative effect on performance. + +- `-dbcache=<n>` - the UTXO database cache size, this defaults to `450`. The unit is MiB (1024). + - The minimum value for `-dbcache` is 4. + - A lower `-dbcache` makes initial sync time much longer. After the initial sync, the effect is less pronounced for most use-cases, unless fast validation of blocks is important, such as for mining. + +## Memory pool + +- In Bitcoin Core there is a memory pool limiter which can be configured with `-maxmempool=<n>`, where `<n>` is the size in MB (1000). The default value is `300`. + - The minimum value for `-maxmempool` is 5. + - A lower maximum mempool size means that transactions will be evicted sooner. This will affect any uses of `bitcoind` that process unconfirmed transactions. + +- To completely disable mempool functionality there is the option `-blocksonly`. This will make the client opt out of receiving (and thus relaying) transactions completely, except as part of blocks. + + - Do not use this when using the client to broadcast transactions as any transaction sent will stick out like a sore thumb, affecting privacy. When used with the wallet it should be combined with `-walletbroadcast=0` and `-spendzeroconfchange=0`. Another mechanism for broadcasting outgoing transactions (if any) should be used. + +- Since `0.14.0`, unused memory allocated to the mempool (default: 300MB) is shared with the UTXO cache, so when trying to reduce memory usage you should limit the mempool, with the `-maxmempool` command line argument. + +## Number of peers + +- `-maxconnections=<n>` - the maximum number of connections, this defaults to `125`. Each active connection takes up some memory. Only significant if incoming + connections are enabled, otherwise the number of connections will never be more than `8`. + +## Thread configuration + +For each thread a thread stack needs to be allocated. By default on Linux, +threads take up 8MiB for the thread stack on a 64-bit system, and 4MiB in a +32-bit system. + +- `-par=<n>` - the number of script verification threads, defaults to the number of cores in the system minus one. +- `-rpcthreads=<n>` - the number of threads used for processing RPC requests, defaults to `4`. + +## Linux specific + +By default, since glibc `2.10`, the C library will create up to two heap arenas per core. This is known to cause excessive memory usage in some scenarios. To avoid this make a script that sets `MALLOC_ARENA_MAX` before starting bitcoind: + +```bash +#!/bin/bash +export MALLOC_ARENA_MAX=1 +bitcoind +``` + +The behavior was introduced to increase CPU locality of allocated memory and performance with concurrent allocation, so this setting could in theory reduce performance. However, in Bitcoin Core very little parallel allocation happens, so the impact is expected to be small or absent. diff --git a/doc/reduce-traffic.md b/doc/reduce-traffic.md index dd1469f563..5a71f62e0f 100644 --- a/doc/reduce-traffic.md +++ b/doc/reduce-traffic.md @@ -35,3 +35,16 @@ blocks and transactions to fewer nodes. 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. + +## 4. Turn off transaction relay (`-blocksonly`) + +Forwarding transactions to peers increases the P2P traffic. To only sync blocks +with other peers, you can disable transaction relay. + +Be reminded of the effects of this setting. + +- Fee estimation will no longer work. +- Not relaying other's transactions could hurt your privacy if used while a + wallet is loaded or if you use the node to broadcast transactions. +- It makes block propagation slower because compact block relay can only be + used when transaction relay is enabled. diff --git a/doc/release-notes-14054.md b/doc/release-notes-14054.md deleted file mode 100644 index d8cad369c5..0000000000 --- a/doc/release-notes-14054.md +++ /dev/null @@ -1,7 +0,0 @@ -P2P changes ------------ - -BIP 61 reject messages were deprecated in v0.18. They are now disabled by -default, but can be enabled by setting the `-enablebip61` command line option. -BIP 61 reject messages will be removed entirely in a future version of -Bitcoin Core. diff --git a/doc/release-notes-15566.md b/doc/release-notes-15566.md deleted file mode 100644 index 49964d7550..0000000000 --- a/doc/release-notes-15566.md +++ /dev/null @@ -1,3 +0,0 @@ -Miscellaneous CLI Changes -------------------------- -- The `testnet` field in `bitcoin-cli -getinfo` has been renamed to `chain` and now returns the current network name as defined in BIP70 (main, test, regtest).
\ No newline at end of file diff --git a/doc/release-notes-15584.md b/doc/release-notes-15584.md new file mode 100644 index 0000000000..3d9b1cc903 --- /dev/null +++ b/doc/release-notes-15584.md @@ -0,0 +1,4 @@ +GUI Changes +----------- +- In 0.18.0 a `./configure` flag was introduced to allow disabling BIP70 support in the GUI (support was enabled by default). In 0.19.0 this flag is now __disabled__ by default. +- If you want compile Bitcoin Core with BIP70 support in the GUI, you can pass `--enable-bip70` to `./configure`.
\ No newline at end of file diff --git a/doc/release-notes-16185.md b/doc/release-notes-16185.md new file mode 100644 index 0000000000..2567ebea40 --- /dev/null +++ b/doc/release-notes-16185.md @@ -0,0 +1,6 @@ +RPC changes +----------- +The `gettransaction` RPC now accepts a third (boolean) argument `verbose`. If +set to `true`, a new `decoded` field will be added to the response containing +the decoded transaction. This field is equivalent to RPC `decoderawtransaction`, +or RPC `getrawtransaction` when `verbose` is passed. diff --git a/doc/release-notes-16512.md b/doc/release-notes-16512.md new file mode 100644 index 0000000000..9aa9cf36f9 --- /dev/null +++ b/doc/release-notes-16512.md @@ -0,0 +1,4 @@ +RPC changes +----------- +The RPC `joinpsbts` will shuffle the order of the inputs and outputs of the resulting joined psbt. +Previously inputs and outputs were added in the order that the PSBTs were provided which makes correlating inputs to outputs extremely easy. diff --git a/doc/release-notes-16695.md b/doc/release-notes-16695.md new file mode 100644 index 0000000000..7acf1dcf97 --- /dev/null +++ b/doc/release-notes-16695.md @@ -0,0 +1,5 @@ +Updated RPCs +------------ + +- The `getchaintxstats` RPC now returns the additional key of + `window_final_block_height`. diff --git a/doc/release-notes-16787.md b/doc/release-notes-16787.md new file mode 100644 index 0000000000..c42b7a5803 --- /dev/null +++ b/doc/release-notes-16787.md @@ -0,0 +1,3 @@ +RPC changes +----------- +The `getnetworkinfo` and `getpeerinfo` commands now contain a new field with decoded network service flags. diff --git a/doc/release-notes.md b/doc/release-notes.md index ebcdcda306..04aab56a72 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -1,12 +1,26 @@ -(note: this is a temporary file, to be added-to by anybody, and moved to -release-notes at release time) +*After branching off for a major version release of Bitcoin Core, use this +template to create the initial release notes draft.* + +*The release notes draft is a temporary file that can be added to by anyone. See +[/doc/developer-notes.md#release-notes](/doc/developer-notes.md#release-notes) +for the process.* + +*Create the draft, named* "*version* Release Notes Draft" +*(e.g. "0.20.0 Release Notes Draft"), as a collaborative wiki in:* + +https://github.com/bitcoin-core/bitcoin-devwiki/wiki/ + +*Before the final release, move the notes back to this git repository.* + +*version* Release Notes Draft +=============================== Bitcoin Core version *version* is now available from: <https://bitcoincore.org/bin/bitcoin-core-*version*/> -This is a new major version release, including new features, various bugfixes -and performance improvements, as well as updated translations. +This release includes new features, various bug fixes and performance +improvements, as well as updated translations. Please report bugs using the issue tracker at GitHub: @@ -24,39 +38,23 @@ 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). -The first time you run version 0.15.0, your chainstate database will be converted to a -new format, which will take anywhere from a few minutes to half an hour, -depending on the speed of your machine. - -Note that the block database format also changed in version 0.8.0 and there is no -automatic upgrade code from before version 0.8 to version 0.15.0. Upgrading -directly from 0.7.x and earlier without redownloading the blockchain is not supported. -However, as usual, old wallet versions are still supported. - -Downgrading warning -------------------- - -The chainstate database for this release is not compatible with previous -releases, so if you run 0.15 and then decide to switch back to any -older version, you will need to run the old release with the `-reindex-chainstate` -option to rebuild the chainstate data structures in the old format. - -If your node has pruning enabled, this will entail re-downloading and -processing the entire blockchain. +Upgrading directly from a version of Bitcoin Core that has reached its EOL is +possible, but might take some time if the datadir needs to be migrated. Old +wallet versions of Bitcoin Core are generally supported. Compatibility ============== Bitcoin Core is supported and extensively tested on operating systems using -the Linux kernel, macOS 10.10+, and Windows 7 and newer. It is not recommended +the Linux kernel, macOS 10.10+, and Windows 7 and newer. It is not recommended to use Bitcoin Core on unsupported systems. Bitcoin Core should also work on most other Unix-like systems but is not -frequently tested on them. +as frequently tested on them. -From 0.17.0 onwards, macOS <10.10 is no longer supported. 0.17.0 is +From 0.17.0 onwards, macOS <10.10 is no longer supported. 0.17.0 is built using Qt 5.9.x, which doesn't support versions of macOS older than -10.10. Additionally, Bitcoin Core does not yet change appearance when +10.10. Additionally, Bitcoin Core does not yet change appearance when macOS "dark mode" is activated. In addition to previously-supported CPU platforms, this release's @@ -66,16 +64,309 @@ platform. Notable changes =============== -Example item +New user documentation +---------------------- + +- [Reduce memory](https://github.com/bitcoin/bitcoin/blob/master/doc/reduce-memory.md) + suggests configuration tweaks for running Bitcoin Core on systems with + limited memory. (#16339) + +New RPCs +-------- + +- `getbalances` returns an object with all balances (`mine`, + `untrusted_pending` and `immature`). Please refer to the RPC help of + `getbalances` for details. The new RPC is intended to replace + `getbalance`, `getunconfirmedbalance`, and the balance fields in + `getwalletinfo`. These old calls and fields may be removed in a + future version. (#15930, #16239) + +- `setwalletflag` sets and unsets wallet flags that enable or disable + features specific to that existing wallet, such as the new + `avoid_reuse` feature documented elsewhere in these release notes. + (#13756) + +- `getblockfilter` gets the BIP158 filter for the specified block. This + RPC is only enabled if block filters have been created using the + `-blockfilterindex` configuration option. (#14121) + +New settings ------------ +- `-blockfilterindex` enables the creation of BIP158 block filters for + the entire blockchain. Filters will be created in the background and + currently use about 4 GiB of space. Note: this version of Bitcoin + Core does not serve block filters over the P2P network, although the + local user may obtain block filters using the `getblockfilter` RPC. + (#14121) + +Updated settings +---------------- + +- `whitebind` and `whitelist` now accept a list of permissions to + provide peers connecting using the indicated interfaces or IP + addresses. If no permissions are specified with an address or CIDR + network, the implicit default permissions are the same as previous + releases. See the `bitcoind -help` output for these two options for + details about the available permissions. (#16248) + +Updated RPCs +------------ + +Note: some low-level RPC changes mainly useful for testing are described in the +Low-level Changes section below. + +- `sendmany` no longer has a `minconf` argument. This argument was not + well specified and would lead to RPC errors even when the wallet's + coin selection succeeded. Users who want to influence coin selection + can use the existing `-spendzeroconfchange`, `-limitancestorcount`, + `-limitdescendantcount` and `-walletrejectlongchains` configuration + arguments. (#15596) + +- `getbalance` and `sendtoaddress`, plus the new RPCs `getbalances` and + `createwallet`, now accept an "avoid_reuse" parameter that controls + whether already used addresses should be included in the operation. + Additionally, `sendtoaddress` will avoid partial spends when + `avoid_reuse` is enabled even if this feature is not already enabled + via the `-avoidpartialspends` command line flag because not doing so + would risk using up the "wrong" UTXO for an address reuse case. + (#13756) + +- `listunspent` now returns a "reused" bool for each output if the + wallet flag "avoid_reuse" is enabled. (#13756) + +- `getblockstats` now uses BlockUndo data instead of the transaction + index, making it much faster, no longer dependent on the `-txindex` + configuration option, and functional for all non-pruned blocks. + (#14802) + +- `utxoupdatepsbt` now accepts a `descriptors` parameter that will fill + out input and output scripts and keys when known. P2SH-witness inputs + will be filled in from the UTXO set when a descriptor is provided that + shows they're spending segwit outputs. See the RPC help text for full + details. (#15427) + +- `sendrawtransaction` and `testmempoolaccept` no longer accept a + `allowhighfees` parameter to fail mempool acceptance if the + transaction fee exceedes the value of the configuration option + `-maxtxfee`. Now there is a hardcoded default maximum feerate that + can be changed when calling either RPC using a `maxfeerate` parameter. + (#15620) + +- `getmempoolancestors`, `getmempooldescendants`, `getmempoolentry`, and + `getrawmempool` no longer return a `size` field unless the + configuration option `-deprecatedrpc=size` is used. Instead a new + `vsize` field is returned with the transaction's virtual size + (consistent with other RPCs such as `getrawtransaction`). (#15637) + +- `getwalletinfo` now includes a `scanning` field that is either `false` + (no scanning) or an object with information about the duration and + progress of the wallet's scanning historical blocks for transactions + affecting its balances. (#15730) + +- `createwallet` accepts a new `passphrase` parameter. If set, this + will create the new wallet encrypted with the given passphrase. If + unset (the default) or set to an empty string, no encryption will be + used. (#16394) + +- `getmempoolentry` now provides a `weight` field containing the + transaction weight as defined in BIP141. (#16647) + +- `getdescriptorinfo` now returns an additional `checksum` field + containing the checksum for the unmodified descriptor provided by the + user (that is, before the descriptor is normalized for the + `descriptor` field). (#15986) + +- `walletcreatefundedpsbt` now signals BIP125 Replace-by-Fee if the + `-walletrbf` configuration option is set to true. (#15911) + +GUI changes +----------- + +- Provides bech32 addresses by default. The user may change the address + during invoice generation using a GUI toggle, or the default address + type may be changed by the `-addresstype` configuration option. + (#15711, #16497) + +Deprecated or removed configuration options +------------------------------------------- + +- `-mempoolreplacement` is removed, although default node behavior + remains the same. This option previously allowed the user to prevent + the node from accepting or relaying BIP125 transaction replacements. + This is different from the remaining configuration option + `-walletrbf`. (#16171) + +Deprecated or removed RPCs +-------------------------- + +- `bumpfee` no longer accepts a `totalFee` option unless the + configuration parameter `deprecatedrpc=totalFee` is specified. This + parameter will be fully removed in a subsequent release. (#15996) + +- `generate` is now removed after being deprecated in Bitcoin Core 0.18. + Use the `generatetoaddress` RPC instead. (#15492) + +P2P changes +----------- + +- BIP 61 reject messages were deprecated in v0.18. They are now disabled + by default, but can be enabled by setting the `-enablebip61` command + line option. BIP 61 reject messages will be removed entirely in a + future version of Bitcoin Core. (#14054) + +- To eliminate well-known denial-of-service vectors in Bitcoin Core, + especially for nodes with spinning disks, the default value for the + `-peerbloomfilters` configuration option has been changed to false. + This prevents Bitcoin Core from sending the BIP111 NODE_BLOOM service + flag, accepting BIP37 bloom filters, or serving merkle blocks or + transactions matching a bloom filter. Users who still want to provide + bloom filter support may either set the configuration option to true + to re-enable both BIP111 and BIP37 support or enable just BIP37 + support for specific peers using the updated `-whitelist` and + `-whitebind` configuration options described elsewhere in these + release notes. For the near future, lightweight clients using public + BIP111/BIP37 nodes should still be able to connect to older versions + of Bitcoin Core and nodes that have manually enabled BIP37 support, + but developers of such software should consider migrating to either + using specific BIP37 nodes or an alternative transaction filtering + system. (#16152) + +Miscellaneous CLI Changes +------------------------- + +- The `testnet` field in `bitcoin-cli -getinfo` has been renamed to + `chain` and now returns the current network name as defined in BIP70 + (main, test, regtest). (#15566) Low-level changes ================= -Example item +RPC +--- + +- `getblockchaininfo` no longer returns a `bip9_softforks` object. + Instead, information has been moved into the `softforks` object and + an additional `type` field describes how Bitcoin Core determines + whether that soft fork is active (e.g. BIP9 or BIP90). See the RPC + help for details. (#16060) + +- `getblocktemplate` no longer returns a `rules` array containing `CSV` + and `segwit` (the BIP9 deployments that are currently in active + state). (#16060) + +- `getrpcinfo` now returns a `logpath` field with the path to + `debug.log`. (#15483) + +Tests +----- + +- The regression test chain enabled by the `-regtest` command line flag + now requires transactions to not violate standard policy by default. + This is the same default used for mainnet and makes it easier to test + mainnet behavior on regtest. Note that the testnet still allows + non-standard txs by default and that the policy can be locally + adjusted with the `-acceptnonstdtxn` command line flag for both test + chains. (#15891) + +Configuration ------------ +- A setting specified in the default section but not also specified in a + network-specific section (e.g. testnet) will now produce a error + preventing startup instead of just a warning unless the network is + mainnet. This prevents settings intended for mainnet from being + applied to testnet or regtest. (#15629) + +- On platforms supporting `thread_local`, log lines can be prefixed with + the name of the thread that caused the log. To enable this behavior, + use `-logthreadnames=1`. (#15849) + +Network +------- + +- When fetching a transaction announced by multiple peers, previous versions of + Bitcoin Core would sequentially attempt to download the transaction from each + announcing peer until the transaction is received, in the order that those + peers' announcements were received. In this release, the download logic has + changed to randomize the fetch order across peers and to prefer sending + download requests to outbound peers over inbound peers. This fixes an issue + where inbound peers could prevent a node from getting a transaction. + (#14897, #15834) + +- If a Tor hidden service is being used, Bitcoin Core will be bound to + the standard port 8333 even if a different port is configured for + clearnet connections. This prevents leaking node identity through use + of identical non-default port numbers. (#15651) + +Mempool and transaction relay +----------------------------- + +- Allows one extra single-ancestor transaction per package. Previously, + if a transaction in the mempool had 25 descendants, or it and all of + its descendants were over 101,000 vbytes, any newly-received + transaction that was also a descendant would be ignored. Now, one + extra descendant will be allowed provided it is an immediate + descendant (child) and the child's size is 10,000 vbytes or less. + This makes it possible for two-party contract protocols such as + Lightning Network to give each participant an output they can spend + immediately for Child-Pays-For-Parent (CPFP) fee bumping without + allowing one malicious participant to fill the entire package and thus + prevent the other participant from spending their output. (#15681) + +- Transactions with outputs paying v1 to v16 witness versions (future + segwit versions) are now accepted into the mempool, relayed, and + mined. Attempting to spend those outputs remains forbidden by policy + ("non-standard"). When this change has been widely deployed, wallets + and services can accept any valid bech32 Bitcoin address without + concern that transactions paying future segwit versions will become + stuck in an unconfirmed state. (#15846) + +- Legacy transactions (transactions with no segwit inputs) must now be + sent using the legacy encoding format, enforcing the rule specified in + BIP144. (#14039) + +Wallet +------ + +- When in pruned mode, a rescan that was triggered by an `importwallet`, + `importpubkey`, `importaddress`, or `importprivkey` RPC will only fail + when blocks have been pruned. Previously it would fail when `-prune` + has been set. This change allows setting `-prune` to a high value + (e.g. the disk size) without the calls to any of the import RPCs + failing until the first block is pruned. (#15870) + +- When creating a transaction with a fee above `-maxtxfee` (default 0.1 + BTC), the RPC commands `walletcreatefundedpsbt` and + `fundrawtransaction` will now fail instead of rounding down the fee. + Be aware that the `feeRate` argument is specified in BTC per 1,000 + vbytes, not satoshi per vbyte. (#16257) + +- A new wallet flag `avoid_reuse` has been added (default off). When + enabled, a wallet will distinguish between used and unused addresses, + and default to not use the former in coin selection. When setting + this flag on an existing wallet, rescanning the blockchain is required + to correctly mark previously used destinations. Together with "avoid + partial spends" (added in Bitcoin Core v0.17.0), this can eliminate a + serious privacy issue where a malicious user can track spends by + sending small payments to a previously-paid address that would then + be included with unrelated inputs in future payments. (#13756) + +Build system changes +-------------------- + +- Python >=3.5 is now required by all aspects of the project. This + includes the build systems, test framework and linters. The previously + supported minimum (3.4), was EOL in March 2019. (#14954) + +- The minimum supported miniUPnPc API version is set to 10. This keeps + compatibility with Ubuntu 16.04 LTS and Debian 8 `libminiupnpc-dev` + packages. Please note, on Debian this package is still vulnerable to + [CVE-2017-8798](https://security-tracker.debian.org/tracker/CVE-2017-8798) + (in jessie only) and + [CVE-2017-1000494](https://security-tracker.debian.org/tracker/CVE-2017-1000494) + (both in jessie and in stretch). (#15993) + Credits ======= diff --git a/doc/release-notes/release-notes-0.12.0.md b/doc/release-notes/release-notes-0.12.0.md index cf74a17975..bc0d5ea3b0 100644 --- a/doc/release-notes/release-notes-0.12.0.md +++ b/doc/release-notes/release-notes-0.12.0.md @@ -127,7 +127,7 @@ minimum relay feerate. The initial minimum relay feerate is set to 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 +total size of 101 KB). These limits can be overridden using command line arguments; see the extended help (`--help -help-debug`) for more information. Opt-in Replace-by-fee transactions diff --git a/doc/release-notes/release-notes-0.18.0.md b/doc/release-notes/release-notes-0.18.0.md new file mode 100644 index 0000000000..3ca7d52243 --- /dev/null +++ b/doc/release-notes/release-notes-0.18.0.md @@ -0,0 +1,1224 @@ +Bitcoin Core version 0.18.0 is now available from: + + <https://bitcoincore.org/bin/bitcoin-core-0.18.0/> + +This is a new major version release, including new features, various bug +fixes and performance improvements, as well as updated translations. + +Please report bugs using the issue tracker at GitHub: + + <https://github.com/bitcoin/bitcoin/issues> + +To receive security and update notifications, please subscribe to: + + <https://bitcoincore.org/en/list/announcements/join/> + +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). + +The first time you run version 0.15.0 or newer, your chainstate database +will be converted to a new format, which will take anywhere from a few +minutes to half an hour, depending on the speed of your machine. + +Note that the block database format also changed in version 0.8.0 and +there is no automatic upgrade code from before version 0.8 to version +0.15.0 or later. Upgrading directly from 0.7.x and earlier without +redownloading the blockchain is not supported. However, as usual, old +wallet versions are still supported. + +Compatibility +============== + +Bitcoin Core is supported and extensively tested on operating systems +using the Linux kernel, macOS 10.10+, and Windows 7 and newer. It is not +recommended to use Bitcoin Core on unsupported systems. + +Bitcoin Core should also work on most other Unix-like systems but is not +as frequently tested on them. + +From 0.17.0 onwards, macOS <10.10 is no longer supported. 0.17.0 is +built using Qt 5.9.x, which doesn't support versions of macOS older than +10.10. Additionally, Bitcoin Core does not yet change appearance when +macOS "dark mode" is activated. + +In addition to previously-supported CPU platforms, this release's +pre-compiled distribution also provides binaries for the RISC-V +platform. + +If you are using the `systemd` unit configuration file located at +`contrib/init/bitcoind.service`, it has been changed to use +`/var/lib/bitcoind` as the data directory instead of +`~bitcoin/.bitcoin`. When switching over to the new configuration file, +please make sure that the filesystem on which `/var/lib/bitcoind` will +exist has enough space (check using `df -h /var/lib/bitcoind`), and +optionally copy over your existing data directory. See the [systemd init +file section](#systemd-init-file) for more details. + +Known issues +============ + +Wallet GUI +---------- + +For advanced users who have both (1) enabled coin control features, and +(2) are using multiple wallets loaded at the same time: The coin control +input selection dialog can erroneously retain wrong-wallet state when +switching wallets using the dropdown menu. For now, it is recommended +not to use coin control features with multiple wallets loaded. + +Notable changes +=============== + +Mining +------ + +- Calls to `getblocktemplate` will fail if the segwit rule is not + specified. Calling `getblocktemplate` without segwit specified is + almost certainly a misconfiguration since doing so results in lower + rewards for the miner. Failed calls will produce an error message + describing how to enable the segwit rule. + +Configuration option changes +---------------------------- + +- A warning is printed if an unrecognized section name is used in the + configuration file. Recognized sections are `[test]`, `[main]`, and + `[regtest]`. + +- Four new options are available for configuring the maximum number of + messages that ZMQ will queue in memory (the "high water mark") before + dropping additional messages. The default value is 1,000, the same as + was used for previous releases. See the [ZMQ + documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/zmq.md#usage) + for details. + +- The `rpcallowip` option can no longer be used to automatically listen + on all network interfaces. Instead, the `rpcbind` parameter must be + used to specify the IP addresses to listen on. Listening for RPC + commands over a public network connection is insecure and should be + disabled, so a warning is now printed if a user selects such a + configuration. If you need to expose RPC in order to use a tool like + Docker, ensure you only bind RPC to your localhost, e.g. `docker run + [...] -p 127.0.0.1:8332:8332` (this is an extra `:8332` over the + normal Docker port specification). + +- The `rpcpassword` option now causes a startup error if the password + set in the configuration file contains a hash character (#), as it's + ambiguous whether the hash character is meant for the password or as a + comment. + +- The `whitelistforcerelay` option is used to relay transactions from + whitelisted peers even when not accepted to the mempool. This option + now defaults to being off, so that changes in policy and + disconnect/ban behavior will not cause a node that is whitelisting + another to be dropped by peers. Users can still explicitly enable + this behavior with the command line option (and may want to consider + [contacting](https://bitcoincore.org/en/contact/) the Bitcoin Core + project to let us know about their use-case, as this feature could be + deprecated in the future). + +systemd init file +----------------- + +The systemd init file (`contrib/init/bitcoind.service`) has been changed +to use `/var/lib/bitcoind` as the data directory instead of +`~bitcoin/.bitcoin`. This change makes Bitcoin Core more consistent with +other services, and makes the systemd init config more consistent with +existing Upstart and OpenRC configs. + +The configuration, PID, and data directories are now completely managed +by systemd, which will take care of their creation, permissions, etc. +See [`systemd.exec(5)`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#RuntimeDirectory=) +for more details. + +When using the provided init files under `contrib/init`, overriding the +`datadir` option in `/etc/bitcoin/bitcoin.conf` will have no effect. +This is because the command line arguments specified in the init files +take precedence over the options specified in +`/etc/bitcoin/bitcoin.conf`. + + +Documentation +------------- + +- A new short [document](https://github.com/bitcoin/bitcoin/blob/master/doc/JSON-RPC-interface.md) + about the JSON-RPC interface describes cases where the results of an + RPC might contain inconsistencies between data sourced from different + subsystems, such as wallet state and mempool state. A note is added + to the [REST interface documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/REST-interface.md) + indicating that the same rules apply. + +- Further information is added to the [JSON-RPC + documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/JSON-RPC-interface.md) + about how to secure this interface. + +- A new [document](https://github.com/bitcoin/bitcoin/blob/master/doc/bitcoin-conf.md) + about the `bitcoin.conf` file describes how to use it to configure + Bitcoin Core. + +- A new document introduces Bitcoin Core's BIP174 [Partially-Signed + Bitcoin Transactions + (PSBT)](https://github.com/bitcoin/bitcoin/blob/master/doc/psbt.md) + interface, which is used to allow multiple programs to collaboratively + work to create, sign, and broadcast new transactions. This is useful + for offline (cold storage) wallets, multisig wallets, coinjoin + implementations, and many other cases where two or more programs need + to interact to generate a complete transaction. + +- The [output script + descriptor](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) + documentation has been updated with information about new features in + this still-developing language for describing the output scripts that + a wallet or other program wants to receive notifications for, such as + which addresses it wants to know received payments. The language is + currently used in multiple new and updated RPCs described in these + release notes and is expected to be adapted to other RPCs and to the + underlying wallet structure. + +Build system changes +-------------------- + +- A new `--disable-bip70` option may be passed to `./configure` to + prevent Bitcoin-Qt from being built with support for the BIP70 payment + protocol or from linking libssl. As the payment protocol has exposed + Bitcoin Core to libssl vulnerabilities in the past, builders who don't + need BIP70 support are encouraged to use this option to reduce their + exposure to future vulnerabilities. + +- The minimum required version of Qt (when building the GUI) has been + increased from 5.2 to 5.5.1 (the [depends + system](https://github.com/bitcoin/bitcoin/blob/master/depends/README.md) + provides 5.9.7) + +New RPCs +-------- + +- `getnodeaddresses` returns peer addresses known to this node. It may + be used to find nodes to connect to without using a DNS seeder. + +- `listwalletdir` returns a list of wallets in the wallet directory + (either the default wallet directory or the directory configured by + the `-walletdir` parameter). + +- `getrpcinfo` returns runtime details of the RPC server. At the moment, + it returns an array of the currently active commands and how long + they've been running. + +- `deriveaddresses` returns one or more addresses corresponding to an + [output descriptor](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md). + +- `getdescriptorinfo` accepts a descriptor and returns information about + it, including its computed checksum. + +- `joinpsbts` merges multiple distinct PSBTs into a single PSBT. The + multiple PSBTs must have different inputs. The resulting PSBT will + contain every input and output from all of the PSBTs. Any signatures + provided in any of the PSBTs will be dropped. + +- `analyzepsbt` examines a PSBT and provides information about what + the PSBT contains and the next steps that need to be taken in order + to complete the transaction. For each input of a PSBT, `analyzepsbt` + provides information about what information is missing for that + input, including whether a UTXO needs to be provided, what pubkeys + still need to be provided, which scripts need to be provided, and + what signatures are still needed. Every input will also list which + role is needed to complete that input, and `analyzepsbt` will also + list the next role in general needed to complete the PSBT. + `analyzepsbt` will also provide the estimated fee rate and estimated + virtual size of the completed transaction if it has enough + information to do so. + +- `utxoupdatepsbt` searches the set of Unspent Transaction Outputs + (UTXOs) to find the outputs being spent by the partial transaction. + PSBTs need to have the UTXOs being spent to be provided because + the signing algorithm requires information from the UTXO being spent. + For segwit inputs, only the UTXO itself is necessary. For + non-segwit outputs, the entire previous transaction is needed so + that signers can be sure that they are signing the correct thing. + Unfortunately, because the UTXO set only contains UTXOs and not full + transactions, `utxoupdatepsbt` will only add the UTXO for segwit + inputs. + +Updated RPCs +------------ + +Note: some low-level RPC changes mainly useful for testing are described +in the Low-level Changes section below. + +- `getpeerinfo` now returns an additional `minfeefilter` field set to + the peer's BIP133 fee filter. You can use this to detect that you + have peers that are willing to accept transactions below the default + minimum relay fee. + +- The mempool RPCs, such as `getrawmempool` with `verbose=true`, now + return an additional "bip125-replaceable" value indicating whether the + transaction (or its unconfirmed ancestors) opts-in to asking nodes and + miners to replace it with a higher-feerate transaction spending any of + the same inputs. + +- `settxfee` previously silently ignored attempts to set the fee below + the allowed minimums. It now prints a warning. The special value of + "0" may still be used to request the minimum value. + +- `getaddressinfo` now provides an `ischange` field indicating whether + the wallet used the address in a change output. + +- `importmulti` has been updated to support P2WSH, P2WPKH, P2SH-P2WPKH, + and P2SH-P2WSH. Requests for P2WSH and P2SH-P2WSH accept an additional + `witnessscript` parameter. + +- `importmulti` now returns an additional `warnings` field for each + request with an array of strings explaining when fields are being + ignored or are inconsistent, if there are any. + +- `getaddressinfo` now returns an additional `solvable` boolean field + when Bitcoin Core knows enough about the address's scriptPubKey, + optional redeemScript, and optional witnessScript in order for the + wallet to be able to generate an unsigned input spending funds sent to + that address. + +- The `getaddressinfo`, `listunspent`, and `scantxoutset` RPCs now + return an additional `desc` field that contains an output descriptor + containing all key paths and signing information for the address + (except for the private key). The `desc` field is only returned for + `getaddressinfo` and `listunspent` when the address is solvable. + +- `importprivkey` will preserve previously-set labels for addresses or + public keys corresponding to the private key being imported. For + example, if you imported a watch-only address with the label "cold + wallet" in earlier releases of Bitcoin Core, subsequently importing + the private key would default to resetting the address's label to the + default empty-string label (""). In this release, the previous label + of "cold wallet" will be retained. If you optionally specify any + label besides the default when calling `importprivkey`, the new label + will be applied to the address. + +- See the [Mining](#mining) section for changes to `getblocktemplate`. + +- `getmininginfo` now omits `currentblockweight` and `currentblocktx` + when a block was never assembled via RPC on this node. + +- The `getrawtransaction` RPC & REST endpoints no longer check the + unspent UTXO set for a transaction. The remaining behaviors are as + follows: 1. If a blockhash is provided, check the corresponding block. + 2. If no blockhash is provided, check the mempool. 3. If no blockhash + is provided but txindex is enabled, also check txindex. + +- `unloadwallet` is now synchronous, meaning it will not return until + the wallet is fully unloaded. + +- `importmulti` now supports importing of addresses from descriptors. A + "desc" parameter can be provided instead of the "scriptPubKey" in a + request, as well as an optional range for ranged descriptors to + specify the start and end of the range to import. Descriptors with key + origin information imported through `importmulti` will have their key + origin information stored in the wallet for use with creating PSBTs. + More information about descriptors can be found + [here](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md). + +- `listunspent` has been modified so that it also returns + `witnessScript`, the witness script in the case of a P2WSH or + P2SH-P2WSH output. + +- `createwallet` now has an optional `blank` argument that can be used + to create a blank wallet. Blank wallets do not have any keys or HD + seed. They cannot be opened in software older than 0.18. Once a blank + wallet has a HD seed set (by using `sethdseed`) or private keys, + scripts, addresses, and other watch only things have been imported, + the wallet is no longer blank and can be opened in 0.17.x. Encrypting + a blank wallet will also set a HD seed for it. + +Deprecated or removed RPCs +-------------------------- + +- `signrawtransaction` is removed after being deprecated and hidden + behind a special configuration option in version 0.17.0. + +- The 'account' API is removed after being deprecated in v0.17. The + 'label' API was introduced in v0.17 as a replacement for accounts. + See the [release notes from + v0.17](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.17.0.md#label-and-account-apis-for-wallet) + for a full description of the changes from the 'account' API to the + 'label' API. + +- `addwitnessaddress` is removed after being deprecated in version + 0.16.0. + +- `generate` is deprecated and will be fully removed in a subsequent + major version. This RPC is only used for testing, but its + implementation reached across multiple subsystems (wallet and mining), + so it is being deprecated to simplify the wallet-node interface. + Projects that are using `generate` for testing purposes should + transition to using the `generatetoaddress` RPC, which does not + require or use the wallet component. Calling `generatetoaddress` with + an address returned by the `getnewaddress` RPC gives the same + functionality as the old `generate` RPC. To continue using `generate` + in this version, restart bitcoind with the `-deprecatedrpc=generate` + configuration option. + +- Be reminded that parts of the `validateaddress` command have been + deprecated and moved to `getaddressinfo`. The following deprecated + fields have moved to `getaddressinfo`: `ismine`, `iswatchonly`, + `script`, `hex`, `pubkeys`, `sigsrequired`, `pubkey`, `embedded`, + `iscompressed`, `label`, `timestamp`, `hdkeypath`, `hdmasterkeyid`. + +- The `addresses` field has been removed from the `validateaddress` + and `getaddressinfo` RPC methods. This field was confusing since + it referred to public keys using their P2PKH address. Clients + should use the `embedded.address` field for P2SH or P2WSH wrapped + addresses, and `pubkeys` for inspecting multisig participants. + +REST changes +------------ + +- A new `/rest/blockhashbyheight/` endpoint is added for fetching the + hash of the block in the current best blockchain based on its height + (how many blocks it is after the Genesis Block). + +Graphical User Interface (GUI) +------------------------------ + +- A new Window menu is added alongside the existing File, Settings, and + Help menus. Several items from the other menus that opened new + windows have been moved to this new Window menu. + +- In the Send tab, the checkbox for "pay only the required fee" has been + removed. Instead, the user can simply decrease the value in the + Custom Feerate field all the way down to the node's configured minimum + relay fee. + +- In the Overview tab, the watch-only balance will be the only balance + shown if the wallet was created using the `createwallet` RPC and the + `disable_private_keys` parameter was set to true. + +- The launch-on-startup option is no longer available on macOS if + compiled with macosx min version greater than 10.11 (use + CXXFLAGS="-mmacosx-version-min=10.11" + CFLAGS="-mmacosx-version-min=10.11" for setting the deployment sdk + version) + +Tools +----- + +- A new `bitcoin-wallet` tool is now distributed alongside Bitcoin + Core's other executables. Without needing to use any RPCs, this tool + can currently create a new wallet file or display some basic + information about an existing wallet, such as whether the wallet is + encrypted, whether it uses an HD seed, how many transactions it + contains, and how many address book entries it has. + +Planned changes +=============== + +This section describes planned changes to Bitcoin Core that may affect +other Bitcoin software and services. + +- Since version 0.16.0, Bitcoin Core’s built-in wallet has defaulted to + generating P2SH-wrapped segwit addresses when users want to receive + payments. These addresses are backwards compatible with all + widely-used software. Starting with Bitcoin Core 0.20 (expected about + a year after 0.18), Bitcoin Core will default to native segwit + addresses (bech32) that provide additional fee savings and other + benefits. Currently, many wallets and services already support sending + to bech32 addresses, and if the Bitcoin Core project sees enough + additional adoption, it will instead default to bech32 receiving + addresses in Bitcoin Core 0.19 (approximately November 2019). + P2SH-wrapped segwit addresses will continue to be provided if the user + requests them in the GUI or by RPC, and anyone who doesn’t want the + update will be able to configure their default address type. + (Similarly, pioneering users who want to change their default now may + set the `addresstype=bech32` configuration option in any Bitcoin Core + release from 0.16.0 up.) + +Deprecated P2P messages +----------------------- + +- BIP 61 reject messages are now deprecated. Reject messages have no use + case on the P2P network and are only logged for debugging by most + network nodes. Furthermore, they increase bandwidth and can be harmful + for privacy and security. It has been possible to disable BIP 61 + messages since v0.17 with the `-enablebip61=0` option. BIP 61 messages + will be disabled by default in a future version, before being removed + entirely. + +Low-level changes +================= + +This section describes RPC changes mainly useful for testing, mostly not +relevant in production. The changes are mentioned for completeness. + +RPC +--- + +- The `submitblock` RPC previously returned the reason a rejected block + was invalid the first time it processed that block, but returned a + generic "duplicate" rejection message on subsequent occasions it + processed the same block. It now always returns the fundamental + reason for rejecting an invalid block and only returns "duplicate" for + valid blocks it has already accepted. + +- A new `submitheader` RPC allows submitting block headers independently + from their block. This is likely only useful for testing. + +- The `signrawtransactionwithkey` and `signrawtransactionwithwallet` + RPCs have been modified so that they also optionally accept a + `witnessScript`, the witness script in the case of a P2WSH or + P2SH-P2WSH output. This is compatible with the change to + `listunspent`. + +- For the `walletprocesspsbt` and `walletcreatefundedpsbt` RPCs, if the + `bip32derivs` parameter is set to true but the key metadata for a + public key has not been updated yet, then that key will have a + derivation path as if it were just an independent key (i.e. no + derivation path and its master fingerprint is itself). + +Configuration +------------- + +- The `-usehd` configuration option was removed in version 0.16. From + that version onwards, all new wallets created are hierarchical + deterministic wallets. This release makes specifying `-usehd` an + invalid configuration option. + +Network +------- + +- This release allows peers that your node automatically disconnected + for misbehavior (e.g. sending invalid data) to reconnect to your node + if you have unused incoming connection slots. If your slots fill up, + a misbehaving node will be disconnected to make room for nodes without + a history of problems (unless the misbehaving node helps your node in + some other way, such as by connecting to a part of the Internet from + which you don't have many other peers). Previously, Bitcoin Core + banned the IP addresses of misbehaving peers for a period of time + (default of 1 day); this was easily circumvented by attackers with + multiple IP addresses. If you manually ban a peer, such as by using + the `setban` RPC, all connections from that peer will still be + rejected. + +Wallet +------- + +- The key metadata will need to be upgraded the first time that the HD + seed is available. For unencrypted wallets this will occur on wallet + loading. For encrypted wallets this will occur the first time the + wallet is unlocked. + +- Newly encrypted wallets will no longer require restarting the + software. Instead such wallets will be completely unloaded and + reloaded to achieve the same effect. + +- A sub-project of Bitcoin Core now provides Hardware Wallet Interaction + (HWI) scripts that allow command-line users to use several popular + hardware key management devices with Bitcoin Core. See their [project + page](https://github.com/bitcoin-core/HWI#readme) for details. + +Security +-------- + +- This release changes the Random Number Generator (RNG) used from + OpenSSL to Bitcoin Core's own implementation, although entropy + gathered by Bitcoin Core is fed out to OpenSSL and then read back in + when the program needs strong randomness. This moves Bitcoin Core a + little closer to no longer needing to depend on OpenSSL, a dependency + that has caused security issues in the past. The new implementation + gathers entropy from multiple sources, including from hardware + supporting the rdseed CPU instruction. + +Changes for particular platforms +-------------------------------- + +- On macOS, Bitcoin Core now opts out of application CPU throttling + ("app nap") during initial blockchain download, when catching up from + over 100 blocks behind the current chain tip, or when reindexing chain + data. This helps prevent these operations from taking an excessively + long time because the operating system is attempting to conserve + power. + +0.18.0 change log +================= + +### Consensus +- #14247 Fix crash bug with duplicate inputs within a transaction (TheBlueMatt) + +### Mining +- #14811 Mining: Enforce that segwit option must be set in GBT (jnewbery) + +### Block and transaction handling +- #13310 Report progress in ReplayBlocks while rolling forward (promag) +- #13783 validation: Pass tx pool reference into CheckSequenceLocks (MarcoFalke) +- #14834 validation: Assert that pindexPrev is non-null when required (kallewoof) +- #14085 index: Fix for indexers skipping genesis block (jimpo) +- #14963 mempool, validation: Explain `cs_main` locking semantics (MarcoFalke) +- #15193 Default `-whitelistforcerelay` to off (sdaftuar) +- #15429 Update `assumevalid`, `minimumchainwork`, and `getchaintxstats` to height 563378 (gmaxwell) +- #15552 Granular invalidateblock and RewindBlockIndex (MarcoFalke) +- #14841 Move CheckBlock() call to critical section (hebasto) + +### P2P protocol and network code +- #14025 Remove dead code for nVersion=10300 (MarcoFalke) +- #12254 BIP 158: Compact Block Filters for Light Clients (jimpo) +- #14073 blockfilter: Avoid out-of-bounds script access (jimpo) +- #14140 Switch nPrevNodeCount to vNodesSize (pstratem) +- #14027 Skip stale tip checking if outbound connections are off or if reindexing (gmaxwell) +- #14532 Never bind `INADDR_ANY` by default, and warn when doing so explicitly (luke-jr) +- #14733 Make peer timeout configurable, speed up very slow test and ensure correct code path tested (zallarak) +- #14336 Implement poll (pstratem) +- #15051 IsReachable is the inverse of IsLimited (DRY). Includes unit tests (mmachicao) +- #15138 Drop IsLimited in favor of IsReachable (Empact) +- #14605 Return of the Banman (dongcarl) +- #14970 Add dnsseed.emzy.de to DNS seeds (Emzy) +- #14929 Allow connections from misbehavior banned peers (gmaxwell) +- #15345 Correct comparison of addr count (dongcarl) +- #15201 Add missing locking annotation for vNodes. vNodes is guarded by cs_vNodes (practicalswift) +- #14626 Select orphan transaction uniformly for eviction (sipa) +- #15486 Ensure tried collisions resolve, and allow feeler connections to existing outbound netgroups (sdaftuar) + +### Wallet +- #13962 Remove unused `dummy_tx` variable from FillPSBT (dongcarl) +- #13967 Don't report `minversion` wallet entry as unknown (instagibbs) +- #13988 Add checks for settxfee reasonableness (ajtowns) +- #12559 Avoid locking `cs_main` in some wallet RPC (promag) +- #13631 Add CMerkleTx::IsImmatureCoinBase method (Empact) +- #14023 Remove accounts RPCs (jnewbery) +- #13825 Kill accounts (jnewbery) +- #10605 Add AssertLockHeld assertions in CWallet::ListCoins (ryanofsky) +- #12490 Remove deprecated wallet rpc features from `bitcoin_server` (jnewbery) +- #14138 Set `encrypted_batch` to nullptr after delete. Avoid double free in the case of NDEBUG (practicalswift) +- #14168 Remove `ENABLE_WALLET` from `libbitcoin_server.a` (jnewbery) +- #12493 Reopen CDBEnv after encryption instead of shutting down (achow101) +- #14282 Remove `-usehd` option (jnewbery) +- #14146 Remove trailing separators from `-walletdir` arg (PierreRochard) +- #14291 Add ListWalletDir utility function (promag) +- #14468 Deprecate `generate` RPC method (jnewbery) +- #11634 Add missing `cs_wallet`/`cs_KeyStore` locks to wallet (practicalswift) +- #14296 Remove `addwitnessaddress` (jnewbery) +- #14451 Add BIP70 deprecation warning and allow building GUI without BIP70 support (jameshilliard) +- #14320 Fix duplicate fileid detection (ken2812221) +- #14561 Remove `fs::relative` call and fix listwalletdir tests (promag) +- #14454 Add SegWit support to importmulti (MeshCollider) +- #14410 rpcwallet: `ischange` field for `getaddressinfo` RPC (mrwhythat) +- #14350 Add WalletLocation class (promag) +- #14689 Require a public key to be retrieved when signing a P2PKH input (achow101) +- #14478 Show error to user when corrupt wallet unlock fails (MeshCollider) +- #14411 Restore ability to list incoming transactions by label (ryanofsky) +- #14552 Detect duplicate wallet by comparing the db filename (ken2812221) +- #14678 Remove redundant KeyOriginInfo access, already done in CreateSig (instagibbs) +- #14477 Add ability to convert solvability info to descriptor (sipa) +- #14380 Fix assert crash when specified change output spend size is unknown (instagibbs) +- #14760 Log env path in `BerkeleyEnvironment::Flush` (promag) +- #14646 Add expansion cache functions to descriptors (unused for now) (sipa) +- #13076 Fix ScanForWalletTransactions to return an enum indicating scan result: `success` / `failure` / `user_abort` (Empact) +- #14821 Replace CAffectedKeysVisitor with descriptor based logic (sipa) +- #14957 Initialize `stop_block` in CWallet::ScanForWalletTransactions (Empact) +- #14565 Overhaul `importmulti` logic (sipa) +- #15039 Avoid leaking nLockTime fingerprint when anti-fee-sniping (MarcoFalke) +- #14268 Introduce SafeDbt to handle Dbt with free or `memory_cleanse` raii-style (Empact) +- #14711 Remove uses of chainActive and mapBlockIndex in wallet code (ryanofsky) +- #15279 Clarify rescanblockchain doc (MarcoFalke) +- #15292 Remove `boost::optional`-related false positive -Wmaybe-uninitialized warnings on GCC compiler (hebasto) +- #13926 [Tools] bitcoin-wallet - a tool for creating and managing wallets offline (jnewbery) +- #11911 Free BerkeleyEnvironment instances when not in use (ryanofsky) +- #15235 Do not import private keys to wallets with private keys disabled (achow101) +- #15263 Descriptor expansions only need pubkey entries for PKH/WPKH (sipa) +- #15322 Add missing `cs_db` lock (promag) +- #15297 Releases dangling files on `BerkeleyEnvironment::Close` (promag) +- #14491 Allow descriptor imports with importmulti (MeshCollider) +- #15365 Add lock annotation for mapAddressBook (MarcoFalke) +- #15226 Allow creating blank (empty) wallets (alternative) (achow101) +- #15390 [wallet-tool] Close bdb when flushing wallet (jnewbery) +- #15334 Log absolute paths for the wallets (hebasto) +- #14978 Factor out PSBT utilities from RPCs for use in GUI code; related refactoring (gwillen) +- #14481 Add P2SH-P2WSH support to listunspent RPC (MeshCollider) +- #14021 Import key origin data through descriptors in importmulti (achow101) +- #14075 Import watch only pubkeys to the keypool if private keys are disabled (achow101) +- #15368 Descriptor checksums (sipa) +- #15433 Use a single wallet batch for `UpgradeKeyMetadata` (jonasschnelli) +- #15408 Remove unused `TransactionError` constants (MarcoFalke) +- #15583 Log and ignore errors in ListWalletDir and IsBerkeleyBtree (promag) +- #14195 Pass privkey export DER compression flag correctly (fingera) +- #15299 Fix assertion in `CKey::SignCompact` (promag) +- #14437 Start to separate wallet from node (ryanofsky) +- #15749 Fix: importmulti only imports origin info for PKH outputs (sipa) + +### RPC and other APIs +- #12842 Prevent concurrent `savemempool` (promag) +- #13987 Report `minfeefilter` value in `getpeerinfo` RPC (ajtowns) +- #13891 Remove getinfo deprecation warning (jnewbery) +- #13399 Add `submitheader` (MarcoFalke) +- #12676 Show `bip125-replaceable` flag, when retrieving mempool entries (dexX7) +- #13723 PSBT key path cleanups (sipa) +- #14008 Preserve a format of RPC command definitions (kostyantyn) +- #9332 Let wallet `importmulti` RPC accept labels for standard scriptPubKeys (ryanofsky) +- #13983 Return more specific reject reason for submitblock (MarcoFalke) +- #13152 Add getnodeaddresses RPC command (chris-belcher) +- #14298 rest: Improve performance for JSON calls (alecalve) +- #14297 Remove warning for removed estimatefee RPC (jnewbery) +- #14373 Consistency fixes for RPC descriptions (ch4ot1c) +- #14150 Add key origin support to descriptors (sipa) +- #14518 Always throw in getblockstats if `-txindex` is required (promag) +- #14060 ZMQ: add options to configure outbound message high water mark, aka SNDHWM (mruddy) +- #13381 Add possibility to preserve labels on importprivkey (marcoagner) +- #14530 Use `RPCHelpMan` to generate RPC doc strings (MarcoFalke) +- #14720 Correctly name RPC arguments (MarcoFalke) +- #14726 Use `RPCHelpMan` for all RPCs (MarcoFalke) +- #14796 Pass argument descriptions to `RPCHelpMan` (MarcoFalke) +- #14670 http: Fix HTTP server shutdown (promag) +- #14885 Assert that named arguments are unique in `RPCHelpMan` (promag) +- #14877 Document default values for optional arguments (MarcoFalke) +- #14875 RPCHelpMan: Support required arguments after optional ones (MarcoFalke) +- #14993 Fix data race (UB) in InterruptRPC() (practicalswift) +- #14653 rpcwallet: Add missing transaction categories to RPC helptexts (andrewtoth) +- #14981 Clarify RPC `getrawtransaction`'s time help text (benthecarman) +- #12151 Remove `cs_main` lock from blockToJSON and blockheaderToJSON (promag) +- #15078 Document `bytessent_per_msg` and `bytesrecv_per_msg` (MarcoFalke) +- #15057 Correct `reconsiderblock `help text, add test (MarcoFalke) +- #12153 Avoid permanent `cs_main` lock in `getblockheader` (promag) +- #14982 Add `getrpcinfo` command (promag) +- #15122 Expand help text for `importmulti` changes (jnewbery) +- #15186 remove duplicate solvable field from `getaddressinfo` (fanquake) +- #15209 zmq: log outbound message high water mark when reusing socket (fanquake) +- #15177 rest: Improve tests and documention of /headers and /block (promag) +- #14353 rest: Add blockhash call, fetch blockhash by height (jonasschnelli) +- #15248 Compile on GCC4.8 (MarcoFalke) +- #14987 RPCHelpMan: Pass through Result and Examples (MarcoFalke) +- #15159 Remove lookup to UTXO set from GetTransaction (amitiuttarwar) +- #15245 remove deprecated mentions of signrawtransaction from fundraw help (instagibbs) +- #14667 Add `deriveaddresses` RPC util method (Sjors) +- #15357 Don't ignore `-maxtxfee` when wallet is disabled (JBaczuk) +- #15337 Fix for segfault if combinepsbt called with empty inputs (benthecarman) +- #14918 RPCHelpMan: Check default values are given at compile-time (MarcoFalke) +- #15383 mining: Omit uninitialized currentblockweight, currentblocktx (MarcoFalke) +- #13932 Additional utility RPCs for PSBT (achow101) +- #15401 Actually throw help when passed invalid number of params (MarcoFalke) +- #15471 rpc/gui: Remove 'Unknown block versions being mined' warning (laanwj) +- #15497 Consistent range arguments in scantxoutset/importmulti/deriveaddresses (sipa) +- #15510 deriveaddresses: add range to CRPCConvertParam (Sjors) +- #15582 Fix overflow bug in analyzepsbt fee: CAmount instead of int (sipa) +- #13424 Consistently validate txid / blockhash length and encoding in rpc calls (Empact) +- #15750 Remove the addresses field from the getaddressinfo return object (jnewbery) + +### GUI +- #13634 Compile `boost::signals2` only once (MarcoFalke) +- #13248 Make proxy icon from statusbar clickable (mess110) +- #12818 TransactionView: highlight replacement tx after fee bump (Sjors) +- #13529 Use new Qt5 connect syntax (promag) +- #14162 Also log and print messages or questions like bitcoind (MarcoFalke) +- #14385 Avoid system harfbuzz and bz2 (theuni) +- #14450 Fix QCompleter popup regression (hebasto) +- #14177 Set C locale for amountWidget (hebasto) +- #14374 Add `Blocksdir` to Debug window (hebasto) +- #14554 Remove unused `adjustedTime` parameter (hebasto) +- #14228 Enable system tray icon by default if available (hebasto) +- #14608 Remove the "Pay only required fee…" checkbox (hebasto) +- #14521 qt, docs: Fix `bitcoin-qt -version` output formatting (hebasto) +- #13966 When private key is disabled, only show watch-only balance (ken2812221) +- #14828 Remove hidden columns in coin control dialog (promag) +- #14783 Fix `boost::signals2::no_slots_error` in early calls to InitWarning (promag) +- #14854 Cleanup SplashScreen class (hebasto) +- #14801 Use window() instead of obsolete topLevelWidget() (hebasto) +- #14573 Add Window menu (promag) +- #14979 Restore < Qt5.6 compatibility for addAction (jonasschnelli) +- #14975 Refactoring with QString::toNSString() (hebasto) +- #15000 Fix broken notificator on GNOME (hebasto) +- #14375 Correct misleading "overridden options" label (hebasto) +- #15007 Notificator class refactoring (hebasto) +- #14784 Use `WalletModel*` instead of the wallet name as map key (promag) +- #11625 Add BitcoinApplication & RPCConsole tests (ryanofsky) +- #14517 Fix start with the `-min` option (hebasto) +- #13216 implements concept for different disk sizes on intro (marcoagner) +- #15114 Replace remaining 0 with nullptr (Empact) +- #14594 Fix minimized window bug on Linux (hebasto) +- #14556 Fix confirmed transaction labeled "open" (#13299) (hebasto) +- #15149 Show current wallet name in window title (promag) +- #15136 "Peers" tab overhaul (hebasto) +- #14250 Remove redundant stopThread() and stopExecutor() signals (hebasto) +- #15040 Add workaround for QProgressDialog bug on macOS (hebasto) +- #15101 Add WalletController (promag) +- #15178 Improve "help-console" message (hebasto) +- #15210 Fix window title update (promag) +- #15167 Fix wallet selector size adjustment (hebasto) +- #15208 Remove macOS launch-at-startup when compiled with > macOS 10.11, fix memory mismanagement (jonasschnelli) +- #15163 Correct units for "-dbcache" and "-prune" (hebasto) +- #15225 Change the receive button to respond to keypool state changing (achow101) +- #15280 Fix shutdown order (promag) +- #15203 Fix issue #9683 "gui, wallet: random abort (segmentation fault) (dooglus) +- #15091 Fix model overlay header sync (jonasschnelli) +- #15153 Add Open Wallet menu (promag) +- #15183 Fix `m_assumed_blockchain_size` variable value (marcoagner) +- #15063 If BIP70 is disabled, attempt to fall back to BIP21 parsing (luke-jr) +- #15195 Add Close Wallet action (promag) +- #15462 Fix async open wallet call order (promag) +- #15801 Bugfix: GUI: Options: Initialise prune setting range before loading current value, and remove upper bound limit (luke-jr) + +### Build system +- #13955 gitian: Bump descriptors for (0.)18 (fanquake) +- #13899 Enable -Wredundant-decls where available. Remove redundant redeclarations (practicalswift) +- #13665 Add RISC-V support to gitian (ken2812221) +- #14062 Generate MSVC project files via python script (ken2812221) +- #14037 Add README.md to linux release tarballs (hebasto) +- #14183 Remove unused Qt 4 dependencies (ken2812221) +- #14127 Avoid getifaddrs when unavailable (greenaddress) +- #14184 Scripts and tools: increased timeout downloading (cisba) +- #14204 Move `interfaces/*` to `libbitcoin_server` (laanwj) +- #14208 Actually remove `ENABLE_WALLET` (jnewbery) +- #14212 Remove libssl from LDADD unless GUI (MarcoFalke) +- #13578 Upgrade zeromq to 4.2.5 and avoid deprecated zeromq API functions (mruddy) +- #14281 lcov: filter /usr/lib/ from coverage reports (MarcoFalke) +- #14325 gitian: Use versioned unsigned tarballs instead of generically named ones (achow101) +- #14253 During 'make clean', remove some files that are currently missed (murrayn) +- #14455 Unbreak `make clean` (jamesob) +- #14495 Warn (don't fail!) on spelling errors (practicalswift) +- #14496 Pin to specific versions of Python packages we install from PyPI in Travis (practicalswift) +- #14568 Fix Qt link order for Windows build (ken2812221) +- #14252 Run functional tests and benchmarks under the undefined behaviour sanitizer (UBSan) (practicalswift) +- #14612 Include full version number in released file names (achow101) +- #14840 Remove duplicate libconsensus linking in test make (AmirAbrams) +- #14564 Adjust configure so that only BIP70 is disabled when protobuf is missing instead of the GUI (jameshilliard) +- #14883 Add `--retry 5` to curl opts in `install_db4.sh` (qubenix) +- #14701 Add `CLIENT_VERSION_BUILD` to CFBundleGetInfoString (fanquake) +- #14849 Qt 5.9.7 (fanquake) +- #15020 Add names to Travis jobs (gkrizek) +- #15047 Allow to configure --with-sanitizers=fuzzer (MarcoFalke) +- #15154 Configure: bitcoin-tx doesn't need libevent, so don't pull it in (luke-jr) +- #15175 Drop macports support (Empact) +- #15308 Restore compatibility with older boost (Empact) +- #15407 msvc: Fix silent merge conflict between #13926 and #14372 part II (ken2812221) +- #15388 Makefile.am: add rule for src/bitcoin-wallet (Sjors) +- #15393 Bump minimum Qt version to 5.5.1 (Sjors) +- #15285 Prefer Python 3.4 even if newer versions are present on the system (Sjors) +- #15398 msvc: Add rapidcheck property tests (ken2812221) +- #15431 msvc: scripted-diff: Remove NDEBUG pre-define in project file (ken2812221) +- #15549 gitian: Improve error handling (laanwj) +- #15548 use full version string in setup.exe (MarcoFalke) +- #11526 Visual Studio build configuration for Bitcoin Core (sipsorcery) +- #15110 build\_msvc: Fix the build problem in `libbitcoin_server` (Mr-Leshiy) +- #14372 msvc: build secp256k1 and leveldb locally (ken2812221) +- #15325 msvc: Fix silent merge conflict between #13926 and #14372 (ken2812221) +- #15391 Add compile time verification of assumptions we're currently making implicitly/tacitly (practicalswift) +- #15503 msvc: Use a single file to specify the include path (ken2812221) +- #13765 contrib: Add gitian build support for github pull request (ken2812221) +- #15809 gitignore: plist and dat (jamesob) + +### Tests and QA +- #15405 appveyor: Clean cache when build configuration changes (Sjors) +- #13953 Fix deprecation in bitcoin-util-test.py (isghe) +- #13963 Replace usage of tostring() with tobytes() (dongcarl) +- #13964 ci: Add appveyor ci (ken2812221) +- #13997 appveyor: fetch the latest port data (ken2812221) +- #13707 Add usage note to check-rpc-mappings.py (masonicboom) +- #14036 travis: Run unit tests --with-sanitizers=undefined (MarcoFalke) +- #13861 Add testing of `value_ret` for SelectCoinsBnB (Empact) +- #13863 travis: Move script sections to files in `.travis/` subject to shellcheck (scravy) +- #14081 travis: Fix missing differentiation between unit and functional tests (scravy) +- #14042 travis: Add cxxflags=-wno-psabi at arm job (ken2812221) +- #14051 Make `combine_logs.py` handle multi-line logs (jnewbery) +- #14093 Fix accidental trunction from int to bool (practicalswift) +- #14108 Add missing locking annotations and locks (`g_cs_orphans`) (practicalswift) +- #14088 Don't assert(…) with side effects (practicalswift) +- #14086 appveyor: Use clcache to speed up build (ken2812221) +- #13954 Warn (don't fail!) on spelling errors. Fix typos reported by codespell (practicalswift) +- #12775 Integration of property based testing into Bitcoin Core (Christewart) +- #14119 Read reject reasons from debug log, not P2P messages (MarcoFalke) +- #14189 Fix silent merge conflict in `wallet_importmulti` (MarcoFalke) +- #13419 Speed up `knapsack_solver_test` by not recreating wallet 100 times (lucash-dev) +- #14199 Remove redundant BIP174 test from `rpc_psbt.json` (araspitzu) +- #14179 Fixups to "Run all tests even if wallet is not compiled" (MarcoFalke) +- #14225 Reorder tests and move most of extended tests up to normal tests (ken2812221) +- #14236 `generate` --> `generatetoaddress` change to allow tests run without wallet (sanket1729) +- #14287 Use MakeUnique to construct objects owned by `unique_ptrs` (practicalswift) +- #14007 Run functional test on Windows and enable it on Appveyor (ken2812221) +- #14275 Write the notification message to different files to avoid race condition in `feature_notifications.py` (ken2812221) +- #14306 appveyor: Move AppVeyor YAML to dot-file-style YAML (MitchellCash) +- #14305 Enforce critical class instance attributes in functional tests, fix segwit test specificity (JustinTArthur) +- #12246 Bugfix: Only run bitcoin-tx tests when bitcoin-tx is enabled (luke-jr) +- #14316 Exclude all tests with difference parameters in `--exclude` list (ken2812221) +- #14381 Add missing call to `skip_if_no_cli()` (practicalswift) +- #14389 travis: Set codespell version to avoid breakage (MarcoFalke) +- #14398 Don't access out of bounds array index: array[sizeof(array)] (Empact) +- #14419 Remove `rpc_zmq.py` (jnewbery) +- #14241 appveyor: Script improvement (ken2812221) +- #14413 Allow closed RPC handler in `assert_start_raises_init_error` (ken2812221) +- #14324 Run more tests with wallet disabled (MarcoFalke) +- #13649 Allow arguments to be forwarded to flake8 in lint-python.sh (jamesob) +- #14465 Stop node before removing the notification file (ken2812221) +- #14460 Improve 'CAmount' tests (hebasto) +- #14456 forward timeouts properly in `send_blocks_and_test` (jamesob) +- #14527 Revert "Make qt wallet test compatible with qt4" (MarcoFalke) +- #14504 Show the progress of functional tests (isghe) +- #14559 appveyor: Enable multiwallet tests (ken2812221) +- #13515 travis: Enable qt for all jobs (ken2812221) +- #14571 Test that nodes respond to `getdata` with `notfound` (MarcoFalke) +- #14569 Print dots by default in functional tests (ken2812221) +- #14631 Move deterministic address import to `setup_nodes` (jnewbery) +- #14630 test: Remove travis specific code (MarcoFalke) +- #14528 travis: Compile once on xenial (MarcoFalke) +- #14092 Dry run `bench_bitcoin` as part `make check` to allow for quick identification of assertion/sanitizer failures in benchmarking code (practicalswift) +- #14664 `example_test.py`: fixup coinbase height argument, derive number clearly (instagibbs) +- #14522 Add invalid P2P message tests (jamesob) +- #14619 Fix value display name in `test_runner` help text (merland) +- #14672 Send fewer spam messages in `p2p_invalid_messages` (jamesob) +- #14673 travis: Fail the ubsan travis build in case of newly introduced ubsan errors (practicalswift) +- #14665 appveyor: Script improvement part II (ken2812221) +- #14365 Add Python dead code linter (vulture) to Travis (practicalswift) +- #14693 `test_node`: `get_mem_rss` fixups (MarcoFalke) +- #14714 util.h: explicitly include required QString header (1Il1) +- #14705 travis: Avoid timeout on verify-commits check (MarcoFalke) +- #14770 travis: Do not specify sudo in `.travis` (scravy) +- #14719 Check specific reject reasons in `feature_block` (MarcoFalke) +- #14771 Add `BOOST_REQUIRE` to getters returning optional (MarcoFalke) +- #14777 Add regtest for JSON-RPC batch calls (domob1812) +- #14764 travis: Run thread sanitizer on unit tests (MarcoFalke) +- #14400 Add Benchmark to test input de-duplication worst case (JeremyRubin) +- #14812 Fix `p2p_invalid_messages` on macOS (jamesob) +- #14813 Add `wallet_encryption` error tests (MarcoFalke) +- #14820 Fix `descriptor_tests` not checking ToString output of public descriptors (ryanofsky) +- #14794 Add AddressSanitizer (ASan) Travis build (practicalswift) +- #14819 Bugfix: `test/functional/mempool_accept`: Ensure oversize transaction is actually oversize (luke-jr) +- #14822 bench: Destroy wallet txs instead of leaking their memory (MarcoFalke) +- #14683 Better `combine_logs.py` behavior (jamesob) +- #14231 travis: Save cache even when build or test fail (ken2812221) +- #14816 Add CScriptNum decode python implementation in functional suite (instagibbs) +- #14861 Modify `rpc_bind` to conform to #14532 behaviour (dongcarl) +- #14864 Run scripted-diff in subshell (dongcarl) +- #14795 Allow `test_runner` command line to receive parameters for each test (marcoagner) +- #14788 Possible fix the permission error when the tests open the cookie file (ken2812221) +- #14857 `wallet_keypool_topup.py`: Test for all keypool address types (instagibbs) +- #14886 Refactor importmulti tests (jnewbery) +- #14908 Removed implicit CTransaction constructor calls from tests and benchmarks (lucash-dev) +- #14903 Handle ImportError explicitly, improve comparisons against None (daniel-s-ingram) +- #14884 travis: Enforce python 3.4 support through linter (Sjors) +- #14940 Add test for truncated pushdata script (MarcoFalke) +- #14926 consensus: Check that final transactions are valid (MarcoFalke) +- #14937 travis: Fix travis would always be green even if it fail (ken2812221) +- #14953 Make `g_insecure_rand_ctx` `thread_local` (MarcoFalke) +- #14931 mempool: Verify prioritization is dumped correctly (MarcoFalke) +- #14935 Test for expected return values when calling functions returning a success code (practicalswift) +- #14969 Fix `cuckoocache_tests` TSAN failure introduced in 14935 (practicalswift) +- #14964 Fix race in `mempool_accept` (MarcoFalke) +- #14829 travis: Enable functional tests in the threadsanitizer (tsan) build job (practicalswift) +- #14985 Remove `thread_local` from `test_bitcoin` (MarcoFalke) +- #15005 Bump timeout to run tests in travis thread sanitizer (MarcoFalke) +- #15013 Avoid race in `p2p_timeouts` (MarcoFalke) +- #14960 lint/format-strings: Correctly exclude escaped percent symbols (luke-jr) +- #14930 pruning: Check that verifychain can be called when pruned (MarcoFalke) +- #15022 Upgrade Travis OS to Xenial (gkrizek) +- #14738 Fix running `wallet_listtransactions.py` individually through `test_runner.py` (kristapsk) +- #15026 Rename `rpc_timewait` to `rpc_timeout` (MarcoFalke) +- #15069 Fix `rpc_net.py` `pong` race condition (Empact) +- #14790 Allow running `rpc_bind.py` --nonloopback test without IPv6 (kristapsk) +- #14457 add invalid tx templates for use in functional tests (jamesob) +- #14855 Correct ineffectual WithOrVersion from `transactions_tests` (Empact) +- #15099 Use `std::vector` API for construction of test data (domob1812) +- #15102 Run `invalid_txs.InputMissing` test in `feature_block` (MarcoFalke) +- #15059 Add basic test for BIP34 (MarcoFalke) +- #15108 Tidy up `wallet_importmulti.py` (amitiuttarwar) +- #15164 Ignore shellcheck warning SC2236 (promag) +- #15170 refactor/lint: Add ignored shellcheck suggestions to an array (koalaman) +- #14958 Remove race between connecting and shutdown on separate connections (promag) +- #15166 Pin shellcheck version (practicalswift) +- #15196 Update all `subprocess.check_output` functions to be Python 3.4 compatible (gkrizek) +- #15043 Build fuzz targets into seperate executables (MarcoFalke) +- #15276 travis: Compile once on trusty (MarcoFalke) +- #15246 Add tests for invalid message headers (MarcoFalke) +- #15301 When testing with --usecli, unify RPC arg to cli arg conversion and handle dicts and lists (achow101) +- #15247 Use wallet to retrieve raw transactions (MarcoFalke) +- #15303 travis: Remove unused `functional_tests_config` (MarcoFalke) +- #15330 Fix race in `p2p_invalid_messages` (MarcoFalke) +- #15324 Make bloom tests deterministic (MarcoFalke) +- #15328 travis: Revert "run extended tests once daily" (MarcoFalke) +- #15327 Make test `updatecoins_simulation_test` deterministic (practicalswift) +- #14519 add utility to easily profile node performance with perf (jamesob) +- #15349 travis: Only exit early if compilation took longer than 30 min (MarcoFalke) +- #15350 Drop RPC connection if --usecli (promag) +- #15370 test: Remove unused --force option (MarcoFalke) +- #14543 minor `p2p_sendheaders` fix of height in coinbase (instagibbs) +- #13787 Test for Windows encoding issue (ken2812221) +- #15378 Added missing tests for RPC wallet errors (benthecarman) +- #15238 remove some magic mining constants in functional tests (instagibbs) +- #15411 travis: Combine --disable-bip70 into existing job (MarcoFalke) +- #15295 fuzz: Add `test/fuzz/test_runner.py` and run it in travis (MarcoFalke) +- #15413 Add missing `cs_main` locks required when accessing pcoinsdbview, pcoinsTip or pblocktree (practicalswift) +- #15399 fuzz: Script validation flags (MarcoFalke) +- #15410 txindex: interrupt threadGroup before calling destructor (MarcoFalke) +- #15397 Remove manual byte editing in `wallet_tx_clone` func test (instagibbs) +- #15415 functional: allow custom cwd, use tmpdir as default (Sjors) +- #15404 Remove `-txindex` to start nodes (amitiuttarwar) +- #15439 remove `byte.hex()` to keep compatibility (AkioNak) +- #15419 Always refresh cache to be out of ibd (MarcoFalke) +- #15507 Bump timeout on tests that timeout on windows (MarcoFalke) +- #15506 appveyor: fix cache issue and reduce dependencies build time (ken2812221) +- #15485 add `rpc_misc.py`, mv test getmemoryinfo, add test mallocinfo (adamjonas) +- #15321 Add `cs_main` lock annotations for mapBlockIndex (MarcoFalke) +- #14128 lint: Make sure we read the command line inputs using UTF-8 decoding in python (ken2812221) +- #14115 lint: Make all linters work under the default macos dev environment (build-osx.md) (practicalswift) +- #15219 lint: Enable python linters via an array (Empact) + +### Platform support +- #13866 utils: Use `_wfopen` and `_wfreopen` on windows (ken2812221) +- #13886 utils: Run commands using UTF-8 string on windows (ken2812221) +- #14192 utils: Convert `fs::filesystem_error` messages from local multibyte to UTF-8 on windows (ken2812221) +- #13877 utils: Make fs::path::string() always return UTF-8 string on windows (ken2812221) +- #13883 utils: Convert windows args to UTF-8 string (ken2812221) +- #13878 utils: Add fstream wrapper to allow to pass unicode filename on windows (ken2812221) +- #14426 utils: Fix broken windows filelock (ken2812221) +- #14686 Fix windows build error if `--disable-bip70` (ken2812221) +- #14922 windows: Set `_WIN32_WINNT` to 0x0601 (Windows 7) (ken2812221) +- #13888 Call unicode API on Windows (ken2812221) +- #15468 Use `fsbridge::ifstream` to fix Windows path issue (ken2812221) +- #13734 Drop `boost::scoped_array` and use `wchar_t` API explicitly on Windows (ken2812221) +- #13884 Enable bdb unicode support for Windows (ken2812221) + +### Miscellaneous +- #13935 contrib: Adjust output to current test format (AkioNak) +- #14097 validation: Log FormatStateMessage on ConnectBlock error in ConnectTip (MarcoFalke) +- #13724 contrib: Support ARM and RISC-V symbol check (ken2812221) +- #13159 Don't close old debug log file handle prematurely when trying to re-open (on SIGHUP) (practicalswift) +- #14186 bitcoin-cli: don't translate command line options (HashUnlimited) +- #14057 logging: Only log `using config file path_to_bitcoin.conf` message on startup if conf file exists (leishman) +- #14164 Update univalue subtree (MarcoFalke) +- #14272 init: Remove deprecated args from hidden args (MarcoFalke) +- #14494 Error if # is used in rpcpassword in conf (MeshCollider) +- #14742 Properly generate salt in rpcauth.py (dongcarl) +- #14708 Warn unrecognised sections in the config file (AkioNak) +- #14756 Improve rpcauth.py by using argparse and getpass modules (promag) +- #14785 scripts: Fix detection of copyright holders (cornelius) +- #14831 scripts: Use `#!/usr/bin/env bash` instead of `#!/bin/bash` (vim88) +- #14869 Scripts: Add trusted key for samuel dobson (laanwj) +- #14809 Tools: improve verify-commits.py script (jlopp) +- #14624 Some simple improvements to the RNG code (sipa) +- #14947 scripts: Remove python 2 import workarounds (practicalswift) +- #15087 Error if rpcpassword contains hash in conf sections (MeshCollider) +- #14433 Add checksum in gitian build scripts for ossl (TheCharlatan) +- #15165 contrib: Allow use of github api authentication in github-merge (laanwj) +- #14409 utils and libraries: Make 'blocksdir' always net specific (hebasto) +- #14839 threads: Fix unitialized members in `sched_param` (fanquake) +- #14955 Switch all RNG code to the built-in PRNG (sipa) +- #15258 Scripts and tools: Fix `devtools/copyright_header.py` to always honor exclusions (Empact) +- #12255 Update bitcoin.service to conform to init.md (dongcarl) +- #15266 memory: Construct globals on first use (MarcoFalke) +- #15347 Fix build after pr 15266 merged (hebasto) +- #15351 Update linearize-hashes.py (OverlordQ) +- #15358 util: Add setuphelpoptions() (MarcoFalke) +- #15216 Scripts and tools: Replace script name with a special parameter (hebasto) +- #15250 Use RdSeed when available, and reduce RdRand load (sipa) +- #15278 Improve PID file error handling (hebasto) +- #15270 Pull leveldb subtree (MarcoFalke) +- #15456 Enable PID file creation on WIN (riordant) +- #12783 macOS: disable AppNap during sync (krab) +- #13910 Log progress while verifying blocks at level 4 (domob1812) +- #15124 Fail AppInitMain if either disk space check fails (Empact) +- #15117 Fix invalid memory write in case of failing mmap(…) in PosixLockedPageAllocator::AllocateLocked (practicalswift) +- #14357 streams: Fix broken `streams_vector_reader` test. Remove unused `seek(size_t)` +- #11640 Make `LOCK`, `LOCK2`, `TRY_LOCK` work with CWaitableCriticalSection (ryanofsky) +- #14074 Use `std::unordered_set` instead of `set` in blockfilter interface (jimpo) +- #15275 Add gitian PGP key for hebasto (hebasto) + +### Documentation +- #14120 Notes about control port and read access to cookie (JBaczuk) +- #14135 correct GetDifficulty doc after #13288 (fanquake) +- #14013 Add new regtest ports in man following #10825 ports reattributions (ariard) +- #14149 Remove misleading checkpoints comment in CMainParams (MarcoFalke) +- #14153 Add disable-wallet section to OSX build instructions, update line in Unix instructions (bitstein) +- #13662 Explain when reindex-chainstate can be used instead of reindex (Sjors) +- #14207 `-help-debug` implies `-help` (laanwj) +- #14213 Fix reference to lint-locale-dependence.sh (hebasto) +- #14206 Document `-checklevel` levels (laanwj) +- #14217 Add GitHub PR template (MarcoFalke) +- #14331 doxygen: Fix member comments (MarcoFalke) +- #14264 Split depends installation instructions per arch (MarcoFalke) +- #14393 Add missing apt-get install (poiuty) +- #14428 Fix macOS files description in qt/README.md (hebasto) +- #14390 release process: RPC documentation (karel-3d) +- #14472 getblocktemplate: use SegWit in example (Sjors) +- #14497 Add doc/bitcoin-conf.md (hebasto) +- #14526 Document lint tests (fanquake) +- #14511 Remove explicit storage requirement from README.md (merland) +- #14600 Clarify commit message guidelines (merland) +- #14617 FreeBSD: Document Python 3 requirement for 'gmake check' (murrayn) +- #14592 Add external interface consistency guarantees (MarcoFalke) +- #14625 Make clear function argument case in dev notes (dongcarl) +- #14515 Update OpenBSD build guide for 6.4 (fanquake) +- #14436 Add comment explaining recentRejects-DoS behavior (jamesob) +- #14684 conf: Remove deprecated options from docs, Other cleanup (MarcoFalke) +- #14731 Improve scripted-diff developer docs (dongcarl) +- #14778 A few minor formatting fixes and clarifications to descriptors.md (jnewbery) +- #14448 Clarify rpcwallet flag url change (JBaczuk) +- #14808 Clarify RPC rawtransaction documentation (jlopp) +- #14804 Less confusing documentation for `torpassword` (fanquake) +- #14848 Fix broken Gmane URL in security-check.py (cyounkins-bot) +- #14882 developer-notes.md: Point out that UniValue deviates from upstream (Sjors) +- #14909 Update minimum required Qt (fanquake) +- #14914 Add nice table to files.md (emilengler) +- #14741 Indicate `-rpcauth` option password hashing alg (dongcarl) +- #14950 Add NSIS setup/install steps to windows docs (fanquake) +- #13930 Better explain GetAncestor check for `m_failed_blocks` in AcceptBlockHeader (Sjors) +- #14973 Improve Windows native build instructions (murrayn) +- #15073 Botbot.me (IRC logs) not available anymore (anduck) +- #15038 Get more info about GUI-related issue on Linux (hebasto) +- #14832 Add more Doxygen information to Developer Notes (ch4ot1c) +- #15128 Fix download link in doc/README.md (merland) +- #15127 Clarifying testing instructions (benthecarman) +- #15132 Add FreeBSD build notes link to doc/README.md (fanquake) +- #15173 Explain what .python-version does (Sjors) +- #15223 Add information about security to the JSON-RPC doc (harding) +- #15249 Update python docs to reflect that wildcard imports are disallowed (Empact) +- #15176 Get rid of badly named `doc/README_osx.md` (merland) +- #15272 Correct logging return type and RPC example (fanquake) +- #15244 Gdb attaching to process during tests has non-sudo solution (instagibbs) +- #15332 Small updates to `getrawtransaction` description (amitiuttarwar) +- #15354 Add missing `bitcoin-wallet` tool manpages (MarcoFalke) +- #15343 netaddress: Make IPv4 loopback comment more descriptive (dongcarl) +- #15353 Minor textual improvements in `translation_strings_policy.md` (merland) +- #15426 importmulti: add missing description of keypool option (harding) +- #15425 Add missing newline to listunspent help for witnessScript (harding) +- #15348 Add separate productivity notes document (dongcarl) +- #15416 Update FreeBSD build guide for 12.0 (fanquake) +- #15222 Add info about factors that affect dependency list (merland) +- #13676 Explain that mempool memory is added to `-dbcache` (Sjors) +- #15273 Slight tweak to the verify-commits script directions (droark) +- #15477 Remove misleading hint in getrawtransaction (MarcoFalke) +- #15489 Update release process for snap package (MarcoFalke) +- #15524 doc: Remove berkeleydb PPA from linux build instructions (MarcoFalke) +- #15559 Correct `analyzepsbt` rpc doc (fanquake) +- #15194 Add comment describing `fDisconnect` behavior (dongcarl) +- #15754 getrpcinfo docs (benthecarman) +- #15763 Update bips.md for 0.18.0 (sipa) +- #15757 List new RPCs in psbt.md and descriptors.md (sipa) +- #15765 correct bitcoinconsensus_version in shared-libraries.md (fanquake) +- #15792 describe onlynet option in doc/tor.md (jonatack) +- #15802 mention creating application support bitcoin folder on OSX (JimmyMow) +- #15799 Clarify RPC versioning (MarcoFalke) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- 1Il1 +- 251 +- Aaron Clauson +- Adam Jonas +- Akio Nakamura +- Alexander Leishman +- Alexey Ivanov +- Alexey Poghilenkov +- Amir Abrams +- Amiti Uttarwar +- Andrew Chow +- andrewtoth +- Anthony Towns +- Antoine Le Calvez +- Antoine Riard +- Antti Majakivi +- araspitzu +- Arvid Norberg +- Ben Carman +- Ben Woosley +- benthecarman +- bitcoinhodler +- Carl Dong +- Chakib Benziane +- Chris Moore +- Chris Stewart +- chris-belcher +- Chun Kuan Lee +- Cornelius Schumacher +- Cory Fields +- Craig Younkins +- Cristian Mircea Messel +- Damian Mee +- Daniel Ingram +- Daniel Kraft +- David A. Harding +- DesWurstes +- dexX7 +- Dimitri Deijs +- Dimitris Apostolou +- Douglas Roark +- DrahtBot +- Emanuele Cisbani +- Emil Engler +- Eric Scrivner +- fridokus +- Gal Buki +- Gleb Naumenko +- Glenn Willen +- Graham Krizek +- Gregory Maxwell +- Gregory Sanders +- gustavonalle +- Harry Moreno +- Hennadii Stepanov +- Isidoro Ghezzi +- Jack Mallers +- James Hilliard +- James O'Beirne +- Jameson Lopp +- Jeremy Rubin +- Jesse Cohen +- Jim Posen +- John Newbery +- Jon Layton +- Jonas Schnelli +- João Barbosa +- Jordan Baczuk +- Jorge Timón +- Julian Fleischer +- Justin Turner Arthur +- Karel Bílek +- Karl-Johan Alm +- Kaz Wesley +- ken2812221 +- Kostiantyn Stepaniuk +- Kristaps Kaupe +- Lawrence Nahum +- Lenny Maiorani +- liuyujun +- lucash-dev +- luciana +- Luke Dashjr +- marcaiaf +- marcoagner +- MarcoFalke +- Martin Erlandsson +- Marty Jones +- Mason Simon +- Michael Ford +- Michael Goldstein +- Michael Polzer +- Mitchell Cash +- mruddy +- Murray Nesbitt +- OverlordQ +- Patrick Strateman +- Pierre Rochard +- Pieter Wuille +- poiuty +- practicalswift +- priscoan +- qubenix +- riordant +- Russell Yanofsky +- Samuel Dobson +- sanket1729 +- Sjors Provoost +- Stephan Oeste +- Steven Roose +- Suhas Daftuar +- TheCharlatan +- Tim Ruffing +- Vidar Holen +- vim88 +- Walter +- whythat +- Wladimir J. van der Laan +- Zain Iqbal Allarakhia + +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.18.1.md b/doc/release-notes/release-notes-0.18.1.md new file mode 100644 index 0000000000..483cc5075e --- /dev/null +++ b/doc/release-notes/release-notes-0.18.1.md @@ -0,0 +1,136 @@ +Bitcoin Core version 0.18.1 is now available from: + + <https://bitcoincore.org/bin/bitcoin-core-0.18.1/> + +This is a new minor version release, including new features, various bug +fixes and performance improvements, as well as updated translations. + +Please report bugs using the issue tracker at GitHub: + + <https://github.com/bitcoin/bitcoin/issues> + +To receive security and update notifications, please subscribe to: + + <https://bitcoincore.org/en/list/announcements/join/> + +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). + +The first time you run version 0.15.0 or newer, your chainstate database +will be converted to a new format, which will take anywhere from a few +minutes to half an hour, depending on the speed of your machine. + +Note that the block database format also changed in version 0.8.0 and +there is no automatic upgrade code from before version 0.8 to version +0.15.0 or later. Upgrading directly from 0.7.x and earlier without +redownloading the blockchain is not supported. However, as usual, old +wallet versions are still supported. + +Compatibility +============== + +Bitcoin Core is supported and extensively tested on operating systems +using the Linux kernel, macOS 10.10+, and Windows 7 and newer. It is not +recommended to use Bitcoin Core on unsupported systems. + +Bitcoin Core should also work on most other Unix-like systems but is not +as frequently tested on them. + +From 0.17.0 onwards, macOS <10.10 is no longer supported. 0.17.0 is +built using Qt 5.9.x, which doesn't support versions of macOS older than +10.10. Additionally, Bitcoin Core does not yet change appearance when +macOS "dark mode" is activated. + +Known issues +============ + +Wallet GUI +---------- + +For advanced users who have both (1) enabled coin control features, and +(2) are using multiple wallets loaded at the same time: The coin control +input selection dialog can erroneously retain wrong-wallet state when +switching wallets using the dropdown menu. For now, it is recommended +not to use coin control features with multiple wallets loaded. + +0.18.1 change log +================= + +### P2P protocol and network code +- #15990 Add tests and documentation for blocksonly (MarcoFalke) +- #16021 Avoid logging transaction decode errors to stderr (MarcoFalke) +- #16405 fix: tor: Call `event_base_loopbreak` from the event's callback (promag) +- #16412 Make poll in InterruptibleRecv only filter for POLLIN events (tecnovert) + +### Wallet +- #15913 Add -ignorepartialspends to list of ignored wallet options (luke-jr) + +### RPC and other APIs +- #15991 Bugfix: fix pruneblockchain returned prune height (jonasschnelli) +- #15899 Document iswitness flag and fix bug in converttopsbt (MarcoFalke) +- #16026 Ensure that uncompressed public keys in a multisig always returns a legacy address (achow101) +- #14039 Disallow extended encoding for non-witness transactions (sipa) +- #16210 add 2nd arg to signrawtransactionwithkey examples (dooglus) +- #16250 signrawtransactionwithkey: report error when missing redeemScript/witnessScript (ajtowns) + +### GUI +- #16044 fix the bug of OPEN CONFIGURATION FILE on Mac (shannon1916) +- #15957 Show "No wallets available" in open menu instead of nothing (meshcollider) +- #16118 Enable open wallet menu on setWalletController (promag) +- #16135 Set progressDialog to nullptr (promag) +- #16231 Fix open wallet menu initialization order (promag) +- #16254 Set `AA_EnableHighDpiScaling` attribute early (hebasto) +- #16122 Enable console line edit on setClientModel (promag) +- #16348 Assert QMetaObject::invokeMethod result (promag) + +### Build system +- #15985 Add test for GCC bug 90348 (sipa) +- #15947 Install bitcoin-wallet manpage (domob1812) +- #15983 build with -fstack-reuse=none (MarcoFalke) + +### Tests and QA +- #15826 Pure python EC (sipa) +- #15893 Add test for superfluous witness record in deserialization (instagibbs) +- #14818 Bugfix: test/functional/rpc_psbt: Remove check for specific error message that depends on uncertain assumptions (luke-jr) +- #15831 Add test that addmultisigaddress fails for watchonly addresses (MarcoFalke) + +### Documentation +- #15890 Remove text about txes always relayed from -whitelist (harding) + +### Miscellaneous +- #16095 Catch by reference not value in wallettool (kristapsk) +- #16205 Replace fprintf with tfm::format (MarcoFalke) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Andrew Chow +- Anthony Towns +- Chris Moore +- Daniel Kraft +- David A. Harding +- fanquake +- Gregory Sanders +- Hennadii Stepanov +- John Newbery +- Jonas Schnelli +- João Barbosa +- Kristaps Kaupe +- Luke Dashjr +- MarcoFalke +- Michele Federici +- Pieter Wuille +- Samuel Dobson +- shannon1916 +- tecnovert +- 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 8e1f966812..7eb8002c6c 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -1,18 +1,19 @@ Release Process ==================== -Before every release candidate: +## Branch updates -* Update translations (ping wumpus on IRC) see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations). +### 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 manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh). -* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`) +* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`). -Before every minor and major release: +### Before every major and minor release * Update [bips.md](bips.md) to account for changes since the last release. -* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_IS_RELEASE` to `true`) (don't forget to set `CLIENT_VERSION_RC` to `0`) -* Write release notes (see below) +* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_RC` to `0`). +* Write release notes (see "Write the release notes" below). * Update `src/chainparams.cpp` nMinimumChainWork with information from the getblockchaininfo rpc. * Update `src/chainparams.cpp` defaultAssumeValid with information from the getblockhash rpc. - The selected value must not be orphaned so it may be useful to set the value two blocks back from the tip. @@ -20,13 +21,38 @@ Before every minor and major release: - This update should be reviewed with a reindex-chainstate with assumevalid=0 to catch any defect that causes rejection of blocks in the past history. -Before every major release: +### Before every major release * Update hardcoded [seeds](/contrib/seeds/README.md), see [this pull request](https://github.com/bitcoin/bitcoin/pull/7415) for an example. * Update [`src/chainparams.cpp`](/src/chainparams.cpp) m_assumed_blockchain_size and m_assumed_chain_state_size with the current size plus some overhead (see [this](#how-to-calculate-m_assumed_blockchain_size-and-m_assumed_chain_state_size) for information on how to calculate them). * Update `src/chainparams.cpp` chainTxData with statistics about the transaction count and rate. Use the output of the RPC `getchaintxstats`, see [this pull request](https://github.com/bitcoin/bitcoin/pull/12270) for an example. Reviewers can verify the results by running `getchaintxstats <window_block_count> <window_last_block_hash>` with the `window_block_count` and `window_last_block_hash` from your output. -* Update version of `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 +* On both the master branch and the new release branch: + - update `CLIENT_VERSION_MINOR` in [`configure.ac`](../configure.ac) + - update `CLIENT_VERSION_MINOR`, `PACKAGE_VERSION`, and `PACKAGE_STRING` in [`build_msvc/bitcoin_config.h`](/build_msvc/bitcoin_config.h) +* On the new release branch in [`configure.ac`](../configure.ac) and [`build_msvc/bitcoin_config.h`](/build_msvc/bitcoin_config.h) (see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd)): + - set `CLIENT_VERSION_REVISION` to `0` + - set `CLIENT_VERSION_IS_RELEASE` to `true` + +#### Before branch-off + +- Clear the release notes and move them to the wiki (see "Write the release notes" below). + +#### After branch-off (on master) + +- Update the version of `contrib/gitian-descriptors/*.yml`. + +#### After branch-off (on the major release branch) + +- Update the versions and the link to the release notes draft in `doc/release-notes.md`. + +#### Before final release + +- Merge the release notes from the wiki into the branch. +- Ensure the "Needs release note" label is removed from all relevant pull requests and issues. + + +## Building ### First time / New builders @@ -40,22 +66,26 @@ Check out the source code in the following directory hierarchy. git clone https://github.com/devrandom/gitian-builder.git git clone https://github.com/bitcoin/bitcoin.git -### Bitcoin maintainers/release engineers, suggestion for writing release notes +### Write the release notes -Write release notes. git shortlog helps a lot, for example: +Open a draft of the release notes for collaborative editing at https://github.com/bitcoin-core/bitcoin-devwiki/wiki. - git shortlog --no-merges v(current version, e.g. 0.7.2)..v(new version, e.g. 0.8.0) +For the period during which the notes are being edited on the wiki, the version on the branch should be wiped and replaced with a link to the wiki which should be used for all announcements until `-final`. + +Write the release notes. `git shortlog` helps a lot, for example: + + git shortlog --no-merges v(current version, e.g. 0.19.2)..v(new version, e.g. 0.20.0) (or ping @wumpus on IRC, he has specific tooling to generate the list of merged pulls -and sort them into categories based on labels) +and sort them into categories based on labels). Generate list of authors: - git log --format='- %aN' v(current version, e.g. 0.16.0)..v(new version, e.g. 0.16.1) | sort -fiu + git log --format='- %aN' v(current version, e.g. 0.20.0)..v(new version, e.g. 0.20.1) | sort -fiu -Tag version (or release candidate) in git +Tag the version (or release candidate) in git: - git tag -s v(new version, e.g. 0.8.0) + git tag -s v(new version, e.g. 0.20.0) ### Setup and perform Gitian builds @@ -65,7 +95,7 @@ Setup Gitian descriptors: pushd ./bitcoin export SIGNER="(your Gitian key, ie bluematt, sipa, etc)" - export VERSION=(new version, e.g. 0.8.0) + export VERSION=(new version, e.g. 0.20.0) git fetch git checkout v${VERSION} popd @@ -216,7 +246,6 @@ Create (and optionally verify) the signed Windows binaries: ./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 macOS/Windows binaries: @@ -224,7 +253,7 @@ Commit your signature for the signed macOS/Windows binaries: pushd gitian.sigs git add ${VERSION}-osx-signed/"${SIGNER}" git add ${VERSION}-win-signed/"${SIGNER}" - git commit -a + git commit -m "Add ${SIGNER} ${VERSION} signed binaries signatures" git push # Assuming you can push to the gitian.sigs tree popd @@ -241,12 +270,11 @@ 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}-riscv64-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 ``` @@ -295,6 +323,9 @@ bitcoin.org (see below for bitcoin.org update instructions). - bitcoincore.org blog post + - bitcoincore.org maintained versions update: + [table](https://github.com/bitcoin-core/bitcoincore.org/commits/master/_includes/posts/maintenance-table.md) + - bitcoincore.org RPC documentation update - Update packaging repo @@ -321,9 +352,11 @@ bitcoin.org (see below for bitcoin.org update instructions). - This repo - - Archive release notes for the new version to `doc/release-notes/` (branch `master` and branch of the release) + - Archive the release notes for the new version to `doc/release-notes/` (branch `master` and branch of the release) + + - Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes - - Create a [new GitHub release](https://github.com/bitcoin/bitcoin/releases/new) with a link to the archived release notes. + - Create a pinned meta-issue for testing the release candidate (see [this issue](https://github.com/bitcoin/bitcoin/issues/15555) for an example) and provide a link to it in the release announcements where useful - Announce the release: diff --git a/doc/shared-libraries.md b/doc/shared-libraries.md index dc363582cc..e960863a80 100644 --- a/doc/shared-libraries.md +++ b/doc/shared-libraries.md @@ -7,11 +7,11 @@ The purpose of this library is to make the verification functionality that is cr ### API -The interface is defined in the C header `bitcoinconsensus.h` located in `src/script/bitcoinconsensus.h`. +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`)*. +`bitcoinconsensus_version` returns an `unsigned int` with the API version *(currently `1`)*. #### Script Validation diff --git a/doc/tor.md b/doc/tor.md index c46b7e9f60..2c54e32f84 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -16,7 +16,7 @@ outgoing connections, but more is possible. -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. + to explicitly disable access to hidden services. -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 @@ -27,6 +27,11 @@ outgoing connections, but more is possible. -seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with other P2P nodes. + -onlynet=onion Make outgoing connections only to .onion addresses. Incoming + connections are not affected by this option. This option can be + specified multiple times to allow multiple network types, e.g. + ipv4, ipv6, or onion. + In a typical situation, this suffices to run behind a Tor proxy: ./bitcoind -proxy=127.0.0.1:9050 @@ -109,7 +114,10 @@ preconfigured and the creation of a hidden service is automatic. If permission p 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. +which has the appropriate permissions. Before starting bitcoind you will need to re-login +to allow debian-tor group to be applied. Otherwise you will see the following notice: "tor: +Authentication cookie /run/tor/control.authcookie could not be opened (check permissions)" +on debug.log. An alternative authentication method is the use of the `-torpassword=password` option. The `password` is the clear text form that diff --git a/doc/translation_process.md b/doc/translation_process.md index b9a10b6527..39f878cea3 100644 --- a/doc/translation_process.md +++ b/doc/translation_process.md @@ -65,24 +65,18 @@ username = USERNAME 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 to change anything. ### Synchronising translations -To assist in updating translations, we have created a script to help. +To assist in updating translations, a helper script is available in the [maintainer-tools repo](https://github.com/bitcoin-core/bitcoin-maintainer-tools). -1. `python contrib/devtools/update-translations.py` +1. `python3 ../bitcoin-maintainer-tools/update-translations.py` 2. `git add` new translations from `src/qt/locale/` 3. Update `src/qt/bitcoin_locale.qrc` manually or via ```bash -git ls-files src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/<file alias="\2">locale\/\1.qm<\/file>/' +git ls-files src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/ <file alias="\2">locale\/\1.qm<\/file>/' ``` -4. Update `src/Makefile.qt.include` manually or via +4. Update `src/Makefile.qt_locale.include` manually or via ```bash git ls-files src/qt/locale/*ts|xargs -n1 basename|sed 's/\(bitcoin_\(.*\)\).ts/ qt\/locale\/\1.ts \\/' ``` -5. Update `build_msvc/libbitcoin_qt/libbitcoin_qt.vcxproj` or via -```bash -git ls-files src/qt/locale/*ts|xargs -n1 basename | - sed 's/@/%40/' | - sed 's/\(bitcoin_\(.*\)\).ts/ <None Include="..\\..\\src\\qt\\locale\\\1.ts">\n <DeploymentContent>true<\/DeploymentContent>\n <\/None>/' -``` **Do not directly download translations** one by one from the Transifex website, as we do a few post-processing steps before committing the translations. diff --git a/doc/travis-ci.md b/doc/travis-ci.md deleted file mode 100644 index 38085cec35..0000000000 --- a/doc/travis-ci.md +++ /dev/null @@ -1,42 +0,0 @@ -Travis CI -========= - -Support for using travis-ci has been added in order to automate pull-testing. -See [travis-ci.org](https://travis-ci.org/) for more info - -This procedure is different than the pull-tester that came before it in a few -ways. - -There is nothing to administer. This is a major feature as it means -that builds have no local state. Because there is no ability to login to the -builders to install packages (tools, dependencies, etc), the entire build -procedure must instead be controlled by a declarative script `.travis.yml`. -This script declares each build configuration, creates virtual machines as -necessary, builds, then discards the virtual machines. - -A build matrix is constructed to test a wide range of configurations, rather -than a single pass/fail. This helps to catch build failures and logic errors -that present on platforms other than the ones the author has tested. This -matrix is defined in the build script and can be changed at any time. - -All builders use the dependency-generator in the [depends dir](/depends), rather than -using apt-get to install build dependencies. This guarantees that the tester -is using the same versions as Gitian, so the build results are nearly identical -to what would be found in a final release. However, this also means that builds -will fail if new dependencies are introduced without being added to the -dependency generator. - -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 very few -manual operations that is possible with Travis, and it can be done by the -Bitcoin Core committer via the Travis web interface. - -In some cases, secure strings may be needed for hiding sensitive info such as -private keys or URLs. The travis client may be used to create these strings: -http://docs.travis-ci.com/user/encryption-keys/ - -For the details of the build descriptor, see the official docs: -http://docs.travis-ci.com/user/build-configuration/ diff --git a/doc/zmq.md b/doc/zmq.md index 7ffc5623b6..a309abd0cc 100644 --- a/doc/zmq.md +++ b/doc/zmq.md @@ -111,7 +111,9 @@ 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. +retrieve the chain from the last known block to the new tip. Also note +that no notification occurs if the tip was in the active chain - this +is the case after calling invalidateblock RPC. There are several possibilities that ZMQ notification can get lost during transmission depending on the communication type you are |