diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/benchmarking.md | 51 | ||||
| -rw-r--r-- | doc/bips.md | 4 | ||||
| -rw-r--r-- | doc/bitcoin-conf.md | 15 | ||||
| -rw-r--r-- | doc/build-unix.md | 10 | ||||
| -rw-r--r-- | doc/dependencies.md | 11 | ||||
| -rw-r--r-- | doc/developer-notes.md | 155 | ||||
| -rw-r--r-- | doc/release-notes-15993.md | 3 | ||||
| -rw-r--r-- | doc/release-notes-16060.md | 15 | ||||
| -rw-r--r-- | doc/release-notes-16394.md | 4 | ||||
| -rw-r--r-- | doc/release-notes.md | 43 | ||||
| -rw-r--r-- | doc/release-notes/release-notes-0.18.1.md | 136 | ||||
| -rw-r--r-- | doc/release-notes/release-notes-16152.md | 7 |
12 files changed, 320 insertions, 134 deletions
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 eb24ce6f66..3085fa424b 100644 --- a/doc/bips.md +++ b/doc/bips.md @@ -12,8 +12,8 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.18.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, 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). diff --git a/doc/bitcoin-conf.md b/doc/bitcoin-conf.md index 88ecb8fe65..f8146b5d75 100644 --- a/doc/bitcoin-conf.md +++ b/doc/bitcoin-conf.md @@ -30,6 +30,21 @@ 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. diff --git a/doc/build-unix.md b/doc/build-unix.md index da65bc347a..9aca0336c0 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -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. diff --git a/doc/dependencies.md b/doc/dependencies.md index c9c6a93c01..0b23ca0a2d 100644 --- a/doc/dependencies.md +++ b/doc/dependencies.md @@ -7,25 +7,24 @@ These are the dependencies currently used by Bitcoin Core. You can find instruct | --- | --- | --- | --- | --- | --- | | Berkeley DB | [4.8.30](https://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html) | 4.8.x | No | | | | 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://llvm.org/releases/download.html) (C++11 support) | | | | +| 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) | +| 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 | diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 39463dc6f8..d1114b0c73 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -62,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, @@ -72,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 @@ -134,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 ... @@ -143,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 @@ -189,7 +191,7 @@ 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 ``` @@ -231,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 @@ -299,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 @@ -364,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 @@ -389,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. @@ -408,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 @@ -446,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 ------- @@ -466,13 +468,13 @@ 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++ ------------- @@ -483,26 +485,26 @@ 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) + Guideline](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-conventional). -- Assertions should not have side-effects +- 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). @@ -510,27 +512,27 @@ Common misconceptions are clarified in those sections: 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. @@ -554,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 ------------------------ @@ -567,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) @@ -607,14 +609,14 @@ 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 -------------- -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. @@ -633,22 +635,20 @@ AddressBookPage::AddressBookPage(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); @@ -657,7 +657,6 @@ Threads and synchronization ``` Wrong: - ```c++ TRY_LOCK(cs_vNodes, lockNodes); { @@ -679,13 +678,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 ``` @@ -694,9 +691,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. @@ -714,7 +711,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. @@ -729,7 +726,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. @@ -752,13 +749,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. @@ -777,12 +774,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. @@ -812,11 +809,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. @@ -841,14 +838,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 @@ -867,7 +864,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. @@ -900,23 +897,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 @@ -925,7 +922,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. @@ -959,7 +956,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 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 @@ -967,7 +964,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/release-notes-15993.md b/doc/release-notes-15993.md new file mode 100644 index 0000000000..493c7126ee --- /dev/null +++ b/doc/release-notes-15993.md @@ -0,0 +1,3 @@ +Build system changes +-------------------- +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). diff --git a/doc/release-notes-16060.md b/doc/release-notes-16060.md new file mode 100644 index 0000000000..7e150d10e7 --- /dev/null +++ b/doc/release-notes-16060.md @@ -0,0 +1,15 @@ +Low-level RPC changes +---------------------- + +- Soft fork reporting in the `getblockchaininfo` return object has been + updated. For full details, see the RPC help text. In summary: + - The `bip9_softforks` sub-object is no longer returned + - The `softforks` sub-object now returns an object keyed by soft fork name, + rather than an array + - Each softfork object in the `softforks` object contains a `type` value which + is either `buried` (for soft fork deployments where the activation height is + hard-coded into the client implementation), or `bip9` (for soft fork deployments + where activation is controlled by BIP 9 signaling). + +- `getblocktemplate` no longer returns a `rules` array containing `CSV` + and `segwit` (the BIP 9 deployments that are currently in active state). diff --git a/doc/release-notes-16394.md b/doc/release-notes-16394.md new file mode 100644 index 0000000000..f09cba4b6d --- /dev/null +++ b/doc/release-notes-16394.md @@ -0,0 +1,4 @@ +RPC changes +----------- +`createwallet` now returns a warning if an empty string is used as an encryption password, and does not encrypt the wallet, instead of raising an error. +This makes it easier to disable encryption but also specify other options when using the `bitcoin-cli` tool. diff --git a/doc/release-notes.md b/doc/release-notes.md index 9efb6cbabb..e0673ae7ee 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -19,8 +19,8 @@ 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: @@ -42,30 +42,19 @@ 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. -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. - 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 @@ -99,10 +88,30 @@ Low-level Changes section below. `-limitancestorcount`, `-limitdescendantcount` and `-walletrejectlongchains` command line arguments. +Deprecated or removed RPCs +-------------------------- + +- The `totalFee` option of the `bumpfee` RPC has been deprecated and will be + removed in 0.20. To continue using this option start with + `-deprecatedrpc=totalFee`. See the `bumpfee` RPC help text for more details. Low-level changes ================= +RPC +--- + + +Tests +----- + +- The regression test chain, that can be enabled by the `-regtest` command line + flag, now requires transactions to not violate standard policy by default. + Making the default the same as for mainnet, makes it easier to test mainnet + behavior on regtest. Be reminded 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. + Configuration ------------ 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-notes/release-notes-16152.md b/doc/release-notes/release-notes-16152.md new file mode 100644 index 0000000000..9c77cb9ae5 --- /dev/null +++ b/doc/release-notes/release-notes-16152.md @@ -0,0 +1,7 @@ +P2P Changes +----------- +- The default value for the -peerbloomfilters configuration option (and, thus, NODE_BLOOM support) has been changed to false. + This resolves well-known DoS vectors in Bitcoin Core, especially for nodes with spinning disks. It is not anticipated that + this will result in a significant lack of availability of NODE_BLOOM-enabled nodes in the coming years, however, clients + which rely on the availability of NODE_BLOOM-supporting nodes on the P2P network should consider the process of migrating + to a more modern (and less trustful and privacy-violating) alternative over the coming years. |