diff options
Diffstat (limited to 'doc')
45 files changed, 4468 insertions, 1883 deletions
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 7e307ab7c8..21bf587eaf 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -2073,7 +2073,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = +PREDEFINED = ENABLE_EXTERNAL_SIGNER # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md index a0cfe84a3e..12807bfb86 100644 --- a/doc/JSON-RPC-interface.md +++ b/doc/JSON-RPC-interface.md @@ -60,7 +60,7 @@ RPC interface will be abused. are sent as clear text that can be read by anyone on your network path. Additionally, the RPC interface has not been hardened to withstand arbitrary Internet traffic, so changing the above settings - to expose it to the Internet (even using something like a Tor hidden + to expose it to the Internet (even using something like a Tor onion service) could expose you to unconsidered vulnerabilities. See `bitcoind -help` for more information about these settings and other settings described in this document. @@ -88,13 +88,14 @@ RPC interface will be abused. - **Secure string handling:** The RPC interface does not guarantee any escaping of data beyond what's necessary to encode it as JSON, although it does usually provide serialized data using a hex - representation of the bytes. If you use RPC data in your programs or - provide its data to other programs, you must ensure any problem - strings are properly escaped. For example, multiple websites have - been manipulated because they displayed decoded hex strings that - included HTML `<script>` tags. For this reason, and other - non-security reasons, it is recommended to display all serialized data - in hex form only. + representation of the bytes. If you use RPC data in your programs or + provide its data to other programs, you must ensure any problem strings + are properly escaped. For example, the `createwallet` RPC accepts + arguments such as `wallet_name` which is a string and could be used + for a path traversal attack without application level checks. Multiple + websites have been manipulated because they displayed decoded hex strings + that included HTML `<script>` tags. For this reason, and others, it is + recommended to display all serialized data in hex form only. ## RPC consistency guarantees @@ -127,3 +128,14 @@ However, the wallet may not be up-to-date with the current state of the mempool or the state of the mempool by an RPC that returned before this RPC. For example, a wallet transaction that was BIP-125-replaced in the mempool prior to this RPC may not yet be reflected as such in this RPC response. + +## Limitations + +There is a known issue in the JSON-RPC interface that can cause a node to crash if +too many http connections are being opened at the same time because the system runs +out of available file descriptors. To prevent this from happening you might +want to increase the number of maximum allowed file descriptors in your system +and try to prevent opening too many connections to your JSON-RPC interface at the +same time if this is under your control. It is hard to give general advice +since this depends on your system but if you make several hundred requests at +once you are definitely at risk of encountering this issue. diff --git a/doc/README.md b/doc/README.md index 19d8204d83..38f6b1d327 100644 --- a/doc/README.md +++ b/doc/README.md @@ -30,7 +30,8 @@ Drag Bitcoin Core to your applications folder, and then run Bitcoin Core. * See the documentation at the [Bitcoin Wiki](https://en.bitcoin.it/wiki/Main_Page) for help and more information. -* Ask for help on [#bitcoin](https://webchat.freenode.net/#bitcoin) on Freenode. If you don't have an IRC client, use [webchat here](https://webchat.freenode.net/#bitcoin). +* Ask for help on [Bitcoin StackExchange](https://bitcoin.stackexchange.com). +* Ask for help on #bitcoin on Libera Chat. If you don't have an IRC client, you can use [web.libera.chat](https://web.libera.chat/#bitcoin). * Ask for help on the [BitcoinTalk](https://bitcointalk.org/) forums, in the [Technical Support board](https://bitcointalk.org/index.php?board=4.0). Building @@ -44,6 +45,7 @@ The following are developer notes on how to build Bitcoin Core on your native pl - [FreeBSD Build Notes](build-freebsd.md) - [OpenBSD Build Notes](build-openbsd.md) - [NetBSD Build Notes](build-netbsd.md) +- [Android Build Notes](build-android.md) - [Gitian Building Guide (External Link)](https://github.com/bitcoin-core/docs/blob/master/gitian-building.md) Development @@ -66,20 +68,20 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th ### Resources * Discuss on the [BitcoinTalk](https://bitcointalk.org/) forums, in the [Development & Technical Discussion board](https://bitcointalk.org/index.php?board=6.0). -* Discuss project-specific development on #bitcoin-core-dev on Freenode. If you don't have an IRC client, use [webchat here](https://webchat.freenode.net/#bitcoin-core-dev). -* Discuss general Bitcoin development on #bitcoin-dev on Freenode. If you don't have an IRC client, use [webchat here](https://webchat.freenode.net/#bitcoin-dev). +* Discuss project-specific development on #bitcoin-core-dev on Libera Chat. If you don't have an IRC client, you can use [web.libera.chat](https://web.libera.chat/#bitcoin-core-dev). ### Miscellaneous - [Assets Attribution](assets-attribution.md) - [bitcoin.conf Configuration File](bitcoin-conf.md) - [Files](files.md) - [Fuzz-testing](fuzzing.md) +- [I2P Support](i2p.md) +- [Init Scripts (systemd/upstart/openrc)](init.md) +- [PSBT support](psbt.md) - [Reduce Memory](reduce-memory.md) - [Reduce Traffic](reduce-traffic.md) - [Tor Support](tor.md) -- [Init Scripts (systemd/upstart/openrc)](init.md) - [ZMQ](zmq.md) -- [PSBT support](psbt.md) License --------------------- diff --git a/doc/REST-interface.md b/doc/REST-interface.md index a63391e01a..8b281acca7 100644 --- a/doc/REST-interface.md +++ b/doc/REST-interface.md @@ -4,7 +4,7 @@ Unauthenticated REST Interface The REST API can be enabled with the `-rest` option. The interface runs on the same port as the JSON-RPC interface, by default port 8332 for mainnet, port 18332 for testnet, -and port 18443 for regtest. +port 38332 for signet, and port 18443 for regtest. REST Interface consistency guarantees ------------------------------------- @@ -12,6 +12,18 @@ REST Interface consistency guarantees The [same guarantees as for the RPC Interface](/doc/JSON-RPC-interface.md#rpc-consistency-guarantees) apply. +Limitations +----------- + +There is a known issue in the REST interface that can cause a node to crash if +too many http connections are being opened at the same time because the system runs +out of available file descriptors. To prevent this from happening you might +want to increase the number of maximum allowed file descriptors in your system +and try to prevent opening too many connections to your rest interface at the +same time if this is under your control. It is hard to give general advice +since this depends on your system but if you make several hundred requests at +once you are definitely at risk of encountering this issue. + Supported API ------------- @@ -30,7 +42,7 @@ To query for a confirmed transaction, enable the transaction index via "txindex= Given a block hash: returns a block, in binary, hex-encoded binary or JSON formats. Responds with 404 if the block doesn't exist. -The HTTP request and response are both handled entirely in-memory, thus making maximum memory usage at least 2.66MB (1 MB max block, plus hex encoding) per request. +The HTTP request and response are both handled entirely in-memory. With the /notxdetails/ option JSON response will only contain the transaction hash instead of the complete transaction details. The option only affects the JSON response. @@ -50,7 +62,7 @@ Given a height: returns hash of block in best-block-chain at height provided. Returns various state info regarding block chain processing. Only supports JSON as output format. -* chain : (string) current network name (main, test, regtest) +* chain : (string) current network name (main, test, signet, regtest) * blocks : (numeric) the current number of blocks processed in the server * headers : (numeric) the current number of headers we have validated * bestblockhash : (string) the hash of the currently best block @@ -61,7 +73,6 @@ Only supports JSON as output format. * pruned : (boolean) if the blocks are subject to pruning * pruneheight : (numeric) highest block available * softforks : (array) status of softforks in progress -* bip9_softforks : (object) status of BIP9 softforks in progress #### Query UTXO set `GET /rest/getutxos/<checkmempool>/<txid>-<n>/<txid>-<n>/.../<txid>-<n>.<bin|hex|json>` @@ -79,17 +90,13 @@ $ curl localhost:18332/rest/getutxos/checkmempool/b2cdfd7b89def827ff8af7cd9bff76 "bitmap": "1", "utxos" : [ { - "txvers" : 1 "height" : 2147483647, "value" : 8.8687, "scriptPubKey" : { "asm" : "OP_DUP OP_HASH160 1c7cebb529b86a04c683dfa87be49de35bcf589e OP_EQUALVERIFY OP_CHECKSIG", "hex" : "76a9141c7cebb529b86a04c683dfa87be49de35bcf589e88ac", - "reqSigs" : 1, "type" : "pubkeyhash", - "addresses" : [ - "mi7as51dvLJsizWnTMurtRmrP8hG2m1XvD" - ] + "address" : "mi7as51dvLJsizWnTMurtRmrP8hG2m1XvD" } } ] @@ -101,12 +108,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 -* maxmempool : (numeric) maximum memory usage for the mempool in bytes -* mempoolminfee : (numeric) minimum feerate (BTC per KB) for tx to be accepted +Refer to the `getmempoolinfo` RPC for documentation of the fields. `GET /rest/mempool/contents.json` diff --git a/doc/benchmarking.md b/doc/benchmarking.md index b1a06009b5..b6cd86eafe 100644 --- a/doc/benchmarking.md +++ b/doc/benchmarking.md @@ -19,8 +19,10 @@ After compiling bitcoin-core, the benchmarks can be run with: The output will look similar to: ``` -# Benchmark, evals, iterations, total, min, max, median -AssembleBlock, 5, 700, 1.79954, 0.000510913, 0.000517018, 0.000514497 +| ns/byte | byte/s | error % | benchmark +|--------------------:|--------------------:|--------:|:---------------------------------------------- +| 64.13 | 15,592,356.01 | 0.1% | `Base58CheckEncode` +| 24.56 | 40,722,672.68 | 0.2% | `Base58Decode` ... ``` diff --git a/doc/bips.md b/doc/bips.md index b96862297f..45954bcfd8 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.19.0**): +BIPs that are implemented by Bitcoin Core (up-to-date up to **v22.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)). @@ -15,6 +15,9 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.19.0**): * [`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 43`](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki): The experimental descriptor wallets introduced in **v0.21.0** by default use the Hierarchical Deterministic Wallet derivation proposed by BIP 43. ([PR #16528](https://github.com/bitcoin/bitcoin/pull/16528)) +* [`BIP 44`](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki): The experimental descriptor wallets introduced in **v0.21.0** by default use the Hierarchical Deterministic Wallet derivation proposed by BIP 44. ([PR #16528](https://github.com/bitcoin/bitcoin/pull/16528)) +* [`BIP 49`](https://github.com/bitcoin/bips/blob/master/bip-0049.mediawiki): The experimental descriptor wallets introduced in **v0.21.0** by default use the Hierarchical Deterministic Wallet derivation proposed by BIP 49. ([PR #16528](https://github.com/bitcoin/bitcoin/pull/16528)) * [`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 (disabled by default) as of **v0.18.0**. Support was removed in **v0.20.0** ([PR #15437](https://github.com/bitcoin/bitcoin/pull/15437)). * [`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)). @@ -24,6 +27,7 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.19.0**): Support can be optionally disabled at build time since **v0.18.0** ([PR 14451](https://github.com/bitcoin/bitcoin/pull/14451)), and it is disabled by default at build time since **v0.19.0** ([PR #15584](https://github.com/bitcoin/bitcoin/pull/15584)). It has been removed as of **v0.20.0** ([PR 17165](https://github.com/bitcoin/bitcoin/pull/17165)). +* [`BIP 84`](https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki): The experimental descriptor wallets introduced in **v0.21.0** by default use the Hierarchical Deterministic Wallet derivation proposed by BIP 84. ([PR #16528](https://github.com/bitcoin/bitcoin/pull/16528)) * [`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 *buried* since **v0.19.0** ([PR #16060](https://github.com/bitcoin/bitcoin/pull/16060)). @@ -37,8 +41,19 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.19.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)), *buried* since **v0.19.0** ([PR #16060](https://github.com/bitcoin/bitcoin/pull/16060)). * [`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 158`](https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki): Compact Block Filters for Light Clients can be indexed as of **v0.19.0** ([PR #14121](https://github.com/bitcoin/bitcoin/pull/14121)). +* [`BIP 155`](https://github.com/bitcoin/bips/blob/master/bip-0155.mediawiki): The 'addrv2' and 'sendaddrv2' messages which enable relay of Tor V3 addresses (and other networks) are supported as of **v0.21.0** ([PR 19954](https://github.com/bitcoin/bitcoin/pull/19954)). +* [`BIP 158`](https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki): Compact Block Filters for Light Clients can be indexed as of **v0.19.0** ([PR #14121](https://github.com/bitcoin/bitcoin/pull/14121)). * [`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)). Bech32 addresses are generated by default as of **v0.20.0** ([PR 16884](https://github.com/bitcoin/bitcoin/pull/16884)). * [`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)). +* [`BIP 325`](https://github.com/bitcoin/bips/blob/master/bip-0325.mediawiki): Signet test network is supported as of **v0.21.0** ([PR 18267](https://github.com/bitcoin/bitcoin/pull/18267)). +* [`BIP 339`](https://github.com/bitcoin/bips/blob/master/bip-0339.mediawiki): Relay of transactions by wtxid is supported as of **v0.21.0** ([PR 18044](https://github.com/bitcoin/bitcoin/pull/18044)). +* [`BIP 340`](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki) + [`341`](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) + [`342`](https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki): + Validation rules for Taproot (including Schnorr signatures and Tapscript + leaves) are implemented as of **v0.21.0** ([PR 19953](https://github.com/bitcoin/bitcoin/pull/19953)), + with mainnet activation as of **v0.21.1** ([PR 21377](https://github.com/bitcoin/bitcoin/pull/21377), + [PR 21686](https://github.com/bitcoin/bitcoin/pull/21686)). +* [`BIP 350`](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki): Addresses for native v1+ segregated Witness outputs use Bech32m instead of Bech32 as of **v22.0** ([PR 20861](https://github.com/bitcoin/bitcoin/pull/20861)). diff --git a/doc/bitcoin-conf.md b/doc/bitcoin-conf.md index f4a8edec75..9a312bc33c 100644 --- a/doc/bitcoin-conf.md +++ b/doc/bitcoin-conf.md @@ -27,7 +27,7 @@ Comments may appear in two ways: ### Network specific options Network specific options can be: -- placed into sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`) or `[regtest]`; +- placed into sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`), `[signet]` or `[regtest]`; - prefixed with a chain name; e.g., `regtest.maxmempool=100`. Network specific options take precedence over non-network specific options. diff --git a/doc/build-android.md b/doc/build-android.md new file mode 100644 index 0000000000..7a8a9e6a65 --- /dev/null +++ b/doc/build-android.md @@ -0,0 +1,12 @@ +ANDROID BUILD NOTES +====================== + +This guide describes how to build and package the `bitcoin-qt` GUI for Android on Linux and macOS. + +## Preparation + +You will need to get the Android NDK and build dependencies for Android as described in [depends/README.md](../depends/README.md). + +## Building and packaging + +After the depends are built configure with one of the resulting prefixes and run `make && make apk` in `src/qt`.
\ No newline at end of file diff --git a/doc/build-freebsd.md b/doc/build-freebsd.md index f48855a344..da2ab61c2a 100644 --- a/doc/build-freebsd.md +++ b/doc/build-freebsd.md @@ -1,61 +1,129 @@ -FreeBSD build guide -====================== -(updated for FreeBSD 12.0) +# FreeBSD Build Guide -This guide describes how to build bitcoind and command-line utilities on FreeBSD. +**Updated for FreeBSD [12.2](https://www.freebsd.org/releases/12.2R/announce.html)** -This guide does not contain instructions for building the GUI. +This guide describes how to build bitcoind, command-line utilities, and GUI on FreeBSD. + +## Dependencies + +The following dependencies are **required**: + + Library | Purpose | Description + ----------------------------------------------------------------------|------------|---------------------- + [autoconf](https://svnweb.freebsd.org/ports/head/devel/autoconf/) | Build | Automatically configure software source code + [automake](https://svnweb.freebsd.org/ports/head/devel/automake/) | Build | Generate makefile (requires autoconf) + [libtool](https://svnweb.freebsd.org/ports/head/devel/libtool/) | Build | Shared library support + [pkgconf](https://svnweb.freebsd.org/ports/head/devel/pkgconf/) | Build | Configure compiler and linker flags + [git](https://svnweb.freebsd.org/ports/head/devel/git/) | Clone | Version control system + [gmake](https://svnweb.freebsd.org/ports/head/devel/gmake/) | Compile | Generate executables + [boost-libs](https://svnweb.freebsd.org/ports/head/devel/boost-libs/) | Utility | Library for threading, data structures, etc + [libevent](https://svnweb.freebsd.org/ports/head/devel/libevent/) | Networking | OS independent asynchronous networking + + +The following dependencies are **optional**: + + Library | Purpose | Description + ---------------------------------------------------------------------------|------------------|---------------------- + [db5](https://svnweb.freebsd.org/ports/head/databases/db5/) | Berkeley DB | Wallet storage (only needed when wallet enabled) + [qt5](https://svnweb.freebsd.org/ports/head/devel/qt5/) | GUI | GUI toolkit (only needed when GUI enabled) + [libqrencode](https://svnweb.freebsd.org/ports/head/graphics/libqrencode/) | QR codes in GUI | Generating QR codes (only needed when GUI enabled) + [libzmq4](https://svnweb.freebsd.org/ports/head/net/libzmq4/) | ZMQ notification | Allows generating ZMQ notifications (requires ZMQ version >= 4.0.0) + [sqlite3](https://svnweb.freebsd.org/ports/head/databases/sqlite3/) | SQLite DB | Wallet storage (only needed when wallet enabled) + [python3](https://svnweb.freebsd.org/ports/head/lang/python3/) | Testing | Python Interpreter (only needed when running the test suite) + + See [dependencies.md](dependencies.md) for a complete overview. ## Preparation -You will need the following dependencies, which can be installed as root via pkg: +### 1. Install Required Dependencies +Install the required dependencies the usual way you [install software on FreeBSD](https://www.freebsd.org/doc/en/books/handbook/ports.html) - either with `pkg` or via the Ports collection. The example commands below use `pkg` which is usually run as `root` or via `sudo`. If you want to use `sudo`, and you haven't set it up: [use this guide](http://www.freebsdwiki.net/index.php/Sudo%2C_configuring) to setup `sudo` access on FreeBSD. ```bash pkg install autoconf automake boost-libs git gmake libevent libtool pkgconf +``` + +### 2. Clone Bitcoin Repo +Now that `git` and all the required dependencies are installed, let's clone the Bitcoin Core repository to a directory. All build scripts and commands will run from this directory. +``` bash git clone https://github.com/bitcoin/bitcoin.git ``` -In order to run the test suite (recommended), you will need to have Python 3 installed: +### 3. Install Optional Dependencies + +#### Wallet Dependencies +It is not necessary to build wallet functionality to run bitcoind or the GUI. To enable legacy wallets, you must install `db5`. To enable [descriptor wallets](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md), `sqlite3` is required. Skip `db5` if you intend to *exclusively* use descriptor wallets + +###### Legacy Wallet Support +`db5` is required to enable support for legacy wallets. Skip if you don't intend to use legacy wallets ```bash -pkg install python3 +pkg install db5 ``` -See [dependencies.md](dependencies.md) for a complete overview. +###### Descriptor Wallet Support -### Building BerkeleyDB +`sqlite3` is required to enable support for descriptor wallets. Skip if you don't intend to use descriptor wallets. +``` bash +pkg install sqlite3 +``` +--- -BerkeleyDB is only necessary for the wallet functionality. To skip this, pass -`--disable-wallet` to `./configure` and skip to the next section. +#### GUI Dependencies +###### Qt5 +Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install `qt5`. Skip if you don't intend to use the GUI. ```bash -./contrib/install_db4.sh `pwd` -export BDB_PREFIX="$PWD/db4" +pkg install qt5 ``` +###### libqrencode + +The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `libqrencode`. Skip if not using the GUI or don't want QR code functionality. +```bash +pkg install libqrencode +``` +--- + +#### Test Suite Dependencies +There is an included test suite that is useful for testing code changes when developing. +To run the test suite (recommended), you will need to have Python 3 installed: + +```bash +pkg install python3 +``` +--- ## Building Bitcoin Core -**Important**: Use `gmake` (the non-GNU `make` will exit with an error). +### 1. Configuration -With wallet: +There are many ways to configure Bitcoin Core, here are a few common examples: +##### Wallet (BDB + SQlite) Support, No GUI: +This explicitly enables legacy wallet support and disables the GUI. If `sqlite3` is installed, then descriptor wallet support will be built. ```bash ./autogen.sh -./configure --with-gui=no \ - BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ - BDB_CFLAGS="-I${BDB_PREFIX}/include" \ +./configure --with-gui=no --with-incompatible-bdb \ + BDB_LIBS="-ldb_cxx-5" \ + BDB_CFLAGS="-I/usr/local/include/db5" \ MAKE=gmake ``` -Without wallet: +##### Wallet (only SQlite) and GUI Support: +This explicitly enables the GUI and disables legacy wallet support. If `qt5` is not installed, this will throw an error. If `sqlite3` is installed then descriptor wallet functionality will be built. If `sqlite3` is not installed, then wallet functionality will be disabled. ```bash ./autogen.sh -./configure --with-gui=no --disable-wallet MAKE=gmake +./configure --without-bdb --with-gui=yes MAKE=gmake +``` +##### No Wallet or GUI +``` bash +./autogen.sh +./configure --without-wallet --with-gui=no MAKE=gmake ``` -followed by: +### 2. Compile +**Important**: Use `gmake` (the non-GNU `make` will exit with an error). ```bash -gmake # use -jX here for parallelism +gmake # use "-j N" for N parallel jobs gmake check # Run tests if Python 3 is available ``` diff --git a/doc/build-netbsd.md b/doc/build-netbsd.md index 47049a780e..edabd71611 100644 --- a/doc/build-netbsd.md +++ b/doc/build-netbsd.md @@ -76,6 +76,6 @@ Without wallet: Build and run the tests: ```bash -gmake # use -jX here for parallelism +gmake # use "-j N" here for N parallel jobs gmake check ``` diff --git a/doc/build-openbsd.md b/doc/build-openbsd.md index 53c647ae34..613aea438f 100644 --- a/doc/build-openbsd.md +++ b/doc/build-openbsd.md @@ -1,10 +1,8 @@ OpenBSD build guide ====================== -(updated for OpenBSD 6.4) +(updated for OpenBSD 6.7) -This guide describes how to build bitcoind and command-line utilities on OpenBSD. - -OpenBSD is most commonly used as a server OS, so this guide does not contain instructions for building the GUI. +This guide describes how to build bitcoind, bitcoin-qt, and command-line utilities on OpenBSD. Preparation ------------- @@ -13,9 +11,11 @@ Run the following as root to install the base dependencies for building: ```bash pkg_add git gmake libevent libtool boost +pkg_add qt5 # (optional for enabling the GUI) pkg_add autoconf # (select highest version, e.g. 2.69) pkg_add automake # (select highest version, e.g. 1.16) -pkg_add python # (select highest version, e.g. 3.6) +pkg_add python # (select highest version, e.g. 3.8) +pkg_add bash git clone https://github.com/bitcoin/bitcoin.git ``` @@ -23,10 +23,10 @@ git clone https://github.com/bitcoin/bitcoin.git See [dependencies.md](dependencies.md) for a complete overview. **Important**: From OpenBSD 6.2 onwards a C++11-supporting clang compiler is -part of the base image, and while building it is necessary to make sure that this -compiler is used and not ancient g++ 4.2.1. This is done by appending -`CC=cc CXX=c++` to configuration commands. Mixing different compilers -within the same executable will result in linker errors. +part of the base image, and while building it is necessary to make sure that +this compiler is used and not ancient g++ 4.2.1. This is done by appending +`CC=cc CC_FOR_BUILD=cc CXX=c++` to configuration commands. Mixing different +compilers within the same executable will result in errors. ### Building BerkeleyDB @@ -77,12 +77,20 @@ To configure with wallet: To configure without wallet: ```bash -./configure --disable-wallet --with-gui=no CC=cc CXX=c++ MAKE=gmake +./configure --disable-wallet --with-gui=no CC=cc CC_FOR_BUILD=cc CXX=c++ MAKE=gmake +``` + +To configure with GUI: +```bash +./configure --with-gui=yes CC=cc CXX=c++ \ + BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ + BDB_CFLAGS="-I${BDB_PREFIX}/include" \ + MAKE=gmake ``` Build and run the tests: ```bash -gmake # use -jX here for parallelism +gmake # use "-j N" here for N parallel jobs gmake check ``` diff --git a/doc/build-osx.md b/doc/build-osx.md index 7b76117c8b..467feff410 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,92 +1,311 @@ -# macOS Build Instructions and Notes +# macOS Build Guide + +**Updated for MacOS [11.2](https://www.apple.com/macos/big-sur/)** + +This guide describes how to build bitcoind, command-line utilities, and GUI on macOS + +**Note:** The following is for Intel Macs only! + +## Dependencies + +The following dependencies are **required**: + +Library | Purpose | Description +-----------------------------------------------------------|------------|---------------------- +[automake](https://formulae.brew.sh/formula/automake) | Build | Generate makefile +[libtool](https://formulae.brew.sh/formula/libtool) | Build | Shared library support +[pkg-config](https://formulae.brew.sh/formula/pkg-config) | Build | Configure compiler and linker flags +[boost](https://formulae.brew.sh/formula/boost) | Utility | Library for threading, data structures, etc +[libevent](https://formulae.brew.sh/formula/libevent) | Networking | OS independent asynchronous networking + +The following dependencies are **optional**: + +Library | Purpose | Description +--------------------------------------------------------------- |------------------|---------------------- +[berkeley-db@4](https://formulae.brew.sh/formula/berkeley-db@4) | Berkeley DB | Wallet storage (only needed when wallet enabled) +[qt@5](https://formulae.brew.sh/formula/qt@5) | GUI | GUI toolkit (only needed when GUI enabled) +[qrencode](https://formulae.brew.sh/formula/qrencode) | QR codes in GUI | Generating QR codes (only needed when GUI enabled) +[zeromq](https://formulae.brew.sh/formula/zeromq) | ZMQ notification | Allows generating ZMQ notifications (requires ZMQ version >= 4.0.0) +[sqlite](https://formulae.brew.sh/formula/sqlite) | SQLite DB | Wallet storage (only needed when wallet enabled) +[miniupnpc](https://formulae.brew.sh/formula/miniupnpc) | UPnP Support | Firewall-jumping support (needed for port mapping support) +[libnatpmp](https://formulae.brew.sh/formula/libnatpmp) | NAT-PMP Support | Firewall-jumping support (needed for port mapping support) +[python3](https://formulae.brew.sh/formula/python@3.9) | Testing | Python Interpreter (only needed when running the test suite) + +The following dependencies are **optional** packages required for deploying: + +Library | Purpose | Description +----------------------------------------------------|------------------|---------------------- +[librsvg](https://formulae.brew.sh/formula/librsvg) | Deploy Dependency| Library to render SVG files +[ds_store](https://pypi.org/project/ds-store/) | Deploy Dependency| Examine and modify .DS_Store files +[mac_alias](https://pypi.org/project/mac-alias/) | Deploy Dependency| Generate/Read binary alias and bookmark records + +See [dependencies.md](dependencies.md) for a complete overview. + +## Preparation The commands in this guide should be executed in a Terminal application. -The built-in one is located in +macOS comes with a built-in Terminal located in: + ``` /Applications/Utilities/Terminal.app ``` -## Preparation -Install the macOS command line tools: +### 1. Xcode Command Line Tools -```shell +The Xcode Command Line Tools are a collection of build tools for macOS. +These tools must be installed in order to build Bitcoin Core from source. + +To install, run the following command from your terminal: + +``` bash xcode-select --install ``` -When the popup appears, click `Install`. +Upon running the command, you should see a popup appear. +Click on `Install` to continue the installation process. -Then install [Homebrew](https://brew.sh). +### 2. Homebrew Package Manager -## Dependencies -```shell -brew install automake berkeley-db4 libtool boost miniupnpc pkg-config python qt libevent qrencode +Homebrew is a package manager for macOS that allows one to install packages from the command line easily. +While several package managers are available for macOS, this guide will focus on Homebrew as it is the most popular. +Since the examples in this guide which walk through the installation of a package will use Homebrew, it is recommended that you install it to follow along. +Otherwise, you can adapt the commands to your package manager of choice. + +To install the Homebrew package manager, see: https://brew.sh + +Note: If you run into issues while installing Homebrew or pulling packages, refer to [Homebrew's troubleshooting page](https://docs.brew.sh/Troubleshooting). + +### 3. Install Required Dependencies + +The first step is to download the required dependencies. +These dependencies represent the packages required to get a barebones installation up and running. +To install, run the following from your terminal: + +``` bash +brew install automake libtool boost pkg-config libevent ``` -If you run into issues, check [Homebrew's troubleshooting page](https://docs.brew.sh/Troubleshooting). -See [dependencies.md](dependencies.md) for a complete overview. +### 4. Clone Bitcoin repository -If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG: -```shell +`git` should already be installed by default on your system. +Now that all the required dependencies are installed, let's clone the Bitcoin Core repository to a directory. +All build scripts and commands will run from this directory. + +``` bash +git clone https://github.com/bitcoin/bitcoin.git +``` + +### 5. Install Optional Dependencies + +#### Wallet Dependencies + +It is not necessary to build wallet functionality to run `bitcoind` or `bitcoin-qt`. +To enable legacy wallets, you must install `berkeley-db@4`. +To enable [descriptor wallets](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md), `sqlite` is required. +Skip `berkeley-db@4` if you intend to *exclusively* use descriptor wallets. + +###### Legacy Wallet Support + +`berkeley-db@4` is required to enable support for legacy wallets. +Skip if you don't intend to use legacy wallets. + +``` bash +brew install berkeley-db@4 +``` + +###### Descriptor Wallet Support + +Note: Apple has included a useable `sqlite` package since macOS 10.14. +You may not need to install this package. + +`sqlite` is required to enable support for descriptor wallets. +Skip if you don't intend to use descriptor wallets. + +``` bash +brew install sqlite +``` +--- + +#### GUI Dependencies + +###### Qt + +Bitcoin Core includes a GUI built with the cross-platform Qt Framework. +To compile the GUI, we need to install `qt@5`. +Skip if you don't intend to use the GUI. + +``` bash +brew install qt@5 +``` + +Ensure that the `qt@5` package is installed, not the `qt` package. +If 'qt' is installed, the build process will fail. +if installed, remove the `qt` package with the following command: + +``` bash +brew uninstall qt +``` + +Note: Building with Qt binaries downloaded from the Qt website is not officially supported. +See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714). + +###### qrencode + +The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `qrencode`. +Skip if not using the GUI or don't want QR code functionality. + +``` bash +brew install qrencode +``` +--- + +#### Port Mapping Dependencies + +###### miniupnpc + +miniupnpc may be used for UPnP port mapping. +Skip if you do not need this functionality. + +``` bash +brew install miniupnpc +``` + +###### libnatpmp + +libnatpmp may be used for NAT-PMP port mapping. +Skip if you do not need this functionality. + +``` bash +brew install libnatpmp +``` + +Note: UPnP and NAT-PMP support will be compiled in and disabled by default. +Check out the [further configuration](#further-configuration) section for more information. + +--- + +#### ZMQ Dependencies + +Support for ZMQ notifications requires the following dependency. +Skip if you do not need ZMQ functionality. + +``` bash +brew install zeromq +``` + +ZMQ is automatically compiled in and enabled if the dependency is detected. +Check out the [further configuration](#further-configuration) section for more information. + +For more information on ZMQ, see: [zmq.md](zmq.md) + +--- + +#### Test Suite Dependencies + +There is an included test suite that is useful for testing code changes when developing. +To run the test suite (recommended), you will need to have Python 3 installed: + +``` bash +brew install python +``` + +--- + +#### Deploy Dependencies + +You can deploy a `.dmg` containing the Bitcoin Core application using `make deploy`. +This command depends on a couple of python packages, so it is required that you have `python` installed. + +Ensuring that `python` is installed, you can install the deploy dependencies by running the following commands in your terminal: + +``` bash brew install librsvg ``` -## Berkeley DB -It is recommended to use Berkeley DB 4.8. If you have to build it yourself, -you can use [this](/contrib/install_db4.sh) script to install it -like so: +``` bash +pip3 install ds_store mac_alias +``` -```shell -./contrib/install_db4.sh . +## Building Bitcoin Core + +### 1. Configuration + +There are many ways to configure Bitcoin Core, here are a few common examples: + +##### Wallet (BDB + SQlite) Support, No GUI: + +If `berkeley-db@4` is installed, then legacy wallet support will be built. +If `berkeley-db@4` is not installed, then this will throw an error. +If `sqlite` is installed, then descriptor wallet support will also be built. +Additionally, this explicitly disables the GUI. + +``` bash +./autogen.sh +./configure --with-gui=no ``` -from the root of the repository. +##### Wallet (only SQlite) and GUI Support: -**Note**: You only need Berkeley DB if the wallet is enabled (see [*Disable-wallet mode*](/doc/build-osx.md#disable-wallet-mode)). +This explicitly enables the GUI and disables legacy wallet support. +If `qt` is not installed, this will throw an error. +If `sqlite` is installed then descriptor wallet functionality will be built. +If `sqlite` is not installed, then wallet functionality will be disabled. -## Build Bitcoin Core +``` bash +./autogen.sh +./configure --without-bdb --with-gui=yes +``` -1. Clone the Bitcoin Core source code: - ```shell - git clone https://github.com/bitcoin/bitcoin - cd bitcoin - ``` +##### No Wallet or GUI -2. Build Bitcoin Core: +``` bash +./autogen.sh +./configure --without-wallet --with-gui=no +``` - Configure and build the headless Bitcoin Core binaries as well as the GUI (if Qt is found). +##### Further Configuration - You can disable the GUI build by passing `--without-gui` to configure. - ```shell - ./autogen.sh - ./configure - make - ``` +You may want to dig deeper into the configuration options to achieve your desired behavior. +Examine the output of the following command for a full list of configuration options: -3. It is recommended to build and run the unit tests: - ```shell - make check - ``` +``` bash +./configure -help +``` -4. You can also create a `.dmg` that contains the `.app` bundle (optional): - ```shell - make deploy - ``` +### 2. Compile -## `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 +After configuration, you are ready to compile. +Run the following in your terminal to compile Bitcoin Core: + +``` bash +make # use "-j N" here for N parallel jobs +make check # Run tests if Python 3 is available ``` -In this case there is no dependency on Berkeley DB 4.8. +### 3. Deploy (optional) + +You can also create a `.dmg` containing the `.app` bundle by running the following command: + +``` bash +make deploy +``` -Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call. +## Running Bitcoin Core -## Running -Bitcoin Core is now available at `./src/bitcoind` +Bitcoin Core should now be available at `./src/bitcoind`. +If you compiled support for the GUI, it should be available at `./src/qt/bitcoin-qt`. + +The first time you run `bitcoind` or `bitcoin-qt`, it will start downloading the blockchain. +This process could take many hours, or even days on slower than average systems. + +By default, blockchain and wallet data files will be stored in: + +``` bash +/Users/${USER}/Library/Application Support/Bitcoin/ +``` Before running, you may create an empty configuration file: + ```shell mkdir -p "/Users/${USER}/Library/Application Support/Bitcoin" @@ -95,22 +314,17 @@ touch "/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. - You can monitor the download process by looking at the debug.log file: + ```shell tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log ``` ## 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. +./src/qt/bitcoin-qt -server # Starts the bitcoin-qt server mode, allows bitcoin-cli control ``` - -## Notes -* Tested on OS X 10.12 Sierra through macOS 10.15 Catalina 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). diff --git a/doc/build-unix.md b/doc/build-unix.md index 6b51db5f55..73c0bf8779 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -9,7 +9,7 @@ Note Always use absolute paths to configure and compile Bitcoin Core and the dependencies. For example, when specifying the path of the dependency: - ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX + ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX Here BDB_PREFIX must be an absolute path - it is defined using $(pwd) which ensures the usage of the absolute path. @@ -20,7 +20,7 @@ To Build ```bash ./autogen.sh ./configure -make +make # use "-j N" for N parallel jobs make install # optional ``` @@ -41,11 +41,13 @@ Optional dependencies: Library | Purpose | Description ------------|------------------|---------------------- miniupnpc | UPnP Support | Firewall-jumping support - libdb4.8 | Berkeley DB | Wallet storage (only needed when wallet enabled) + libnatpmp | NAT-PMP Support | Firewall-jumping support + libdb4.8 | Berkeley DB | Optional, wallet storage (only needed when wallet enabled) qt | GUI | GUI toolkit (only needed when GUI enabled) libqrencode | QR codes in GUI | Optional for generating QR codes (only needed when GUI enabled) univalue | Utility | JSON parsing and encoding (bundled version will be used unless --with-system-univalue passed to configure) libzmq3 | ZMQ notification | Optional, allows generating ZMQ notifications (requires ZMQ version >= 4.0.0) + sqlite3 | SQLite DB | Optional, wallet storage (only needed when wallet enabled) For the versions used, see [dependencies.md](dependencies.md) @@ -80,23 +82,26 @@ Build requirements: Now, you can either build from self-compiled [depends](/depends/README.md) or install the required dependencies: - sudo apt-get install libevent-dev libboost-system-dev libboost-filesystem-dev libboost-test-dev libboost-thread-dev + sudo apt-get install libevent-dev libboost-dev libboost-system-dev libboost-filesystem-dev libboost-test-dev -BerkeleyDB is required for the wallet. +Berkeley DB is required for the wallet. 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 +Berkeley DB 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. -Otherwise, you can build from self-compiled `depends` (see above). +Otherwise, you can build Berkeley DB [yourself](#berkeley-db). -To build Bitcoin Core without wallet, see [*Disable-wallet mode*](/doc/build-unix.md#disable-wallet-mode) +SQLite is required for the descriptor wallet: + sudo apt install libsqlite3-dev -Optional (see `--with-miniupnpc` and `--enable-upnp-default`): +To build Bitcoin Core without wallet, see [*Disable-wallet mode*](#disable-wallet-mode) - sudo apt-get install libminiupnpc-dev +Optional port mapping libraries (see: `--with-miniupnpc`, `--enable-upnp-default`, and `--with-natpmp`, `--enable-natpmp-default`): + + sudo apt install libminiupnpc-dev libnatpmp-dev ZMQ dependencies (provides ZMQ API): @@ -126,16 +131,43 @@ built by default. Build requirements: - sudo dnf install gcc-c++ libtool make autoconf automake libevent-devel boost-devel libdb4-devel libdb4-cxx-devel python3 + sudo dnf install gcc-c++ libtool make autoconf automake python3 + +Now, you can either build from self-compiled [depends](/depends/README.md) or install the required dependencies: + + sudo dnf install libevent-devel boost-devel -Optional (see `--with-miniupnpc` and `--enable-upnp-default`): +Berkeley DB is required for the wallet: + + sudo dnf install libdb4-devel libdb4-cxx-devel + +Newer Fedora releases, since Fedora 33, have only `libdb-devel` and `libdb-cxx-devel` packages, but these will install +Berkeley DB 5.3 or later. This will break binary wallet compatibility with the distributed executables, which +are based on Berkeley DB 4.8. If you do not care about wallet compatibility, +pass `--with-incompatible-bdb` to configure. - sudo dnf install miniupnpc-devel +Otherwise, you can build Berkeley DB [yourself](#berkeley-db). + +SQLite is required for the descriptor wallet: + + sudo dnf install sqlite-devel + +To build Bitcoin Core without wallet, see [*Disable-wallet mode*](#disable-wallet-mode) + +Optional port mapping libraries (see: `--with-miniupnpc`, `--enable-upnp-default`, and `--with-natpmp`, `--enable-natpmp-default`): + + sudo dnf install miniupnpc-devel libnatpmp-devel ZMQ dependencies (provides ZMQ API): sudo dnf install zeromq-devel +GUI dependencies: + +If you want to build bitcoin-qt, make sure that the required packages for Qt development +are installed. Qt 5 is necessary to build the GUI. +To build without GUI pass `--without-gui`. + To build with Qt 5 you need the following: sudo dnf install qt5-qttools-devel qt5-qtbase-devel @@ -144,23 +176,35 @@ libqrencode (optional) can be installed with: sudo dnf install qrencode-devel +Once these are installed, they will be found by configure and a bitcoin-qt executable will be +built by default. + Notes ----- The release is built with GCC and then "strip bitcoind" to strip the debug symbols, which reduces the executable size by about 90%. - miniupnpc --------- [miniupnpc](https://miniupnp.tuxfamily.org) may be used for UPnP port mapping. It can be downloaded from [here]( https://miniupnp.tuxfamily.org/files/). UPnP support is compiled in and -turned off by default. See the configure options for upnp behavior desired: +turned off by default. See the configure options for UPnP behavior desired: + + --without-miniupnpc No UPnP support, miniupnp not required + --disable-upnp-default (the default) UPnP support turned off by default at runtime + --enable-upnp-default UPnP support turned on by default at runtime - --without-miniupnpc No UPnP support miniupnp not required - --disable-upnp-default (the default) UPnP support turned off by default at runtime - --enable-upnp-default UPnP support turned on by default at runtime +libnatpmp +--------- + +[libnatpmp](https://miniupnp.tuxfamily.org/libnatpmp.html) may be used for NAT-PMP port mapping. It can be downloaded +from [here](https://miniupnp.tuxfamily.org/files/). NAT-PMP support is compiled in and +turned off by default. See the configure options for NAT-PMP behavior desired: + --without-natpmp No NAT-PMP support, libnatpmp not required + --disable-natpmp-default (the default) NAT-PMP support turned off by default at runtime + --enable-natpmp-default NAT-PMP support turned on by default at runtime Berkeley DB ----------- @@ -174,15 +218,17 @@ like so: from the root of the repository. -**Note**: You only need Berkeley DB if the wallet is enabled (see [*Disable-wallet mode*](/doc/build-unix.md#disable-wallet-mode)). +Otherwise, you can build Bitcoin Core from self-compiled [depends](/depends/README.md). + +**Note**: You only need Berkeley DB if the wallet is enabled (see [*Disable-wallet mode*](#disable-wallet-mode)). Boost ----- If you need to build Boost yourself: - sudo su - ./bootstrap.sh - ./bjam install + sudo su + ./bootstrap.sh + ./bjam install Security @@ -193,8 +239,8 @@ This can be disabled with: Hardening Flags: - ./configure --enable-hardening - ./configure --disable-hardening + ./configure --enable-hardening + ./configure --disable-hardening Hardening enables the following features: @@ -209,7 +255,7 @@ Hardening enables the following features: To test that you have built PIE executable, install scanelf, part of paxutils, and use: - scanelf -e ./bitcoin + scanelf -e ./bitcoin The output should contain: @@ -226,8 +272,8 @@ Hardening enables the following features: `scanelf -e ./bitcoin` The output should contain: - STK/REL/PTL - RW- R-- RW- + STK/REL/PTL + RW- R-- RW- The STK RW- means that the stack is readable and writeable but not executable. @@ -238,7 +284,7 @@ disable-wallet mode with: ./configure --disable-wallet -In this case there is no dependency on Berkeley DB 4.8. +In this case there is no dependency on Berkeley DB 4.8 and SQLite. Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call. @@ -285,7 +331,7 @@ To build executables for ARM: make HOST=arm-linux-gnueabihf NO_QT=1 cd .. ./autogen.sh - ./configure --prefix=$PWD/depends/arm-linux-gnueabihf --enable-glibc-back-compat --enable-reduce-exports LDFLAGS=-static-libstdc++ + CONFIG_SITE=$PWD/depends/arm-linux-gnueabihf/share/config.site ./configure --enable-glibc-back-compat --enable-reduce-exports LDFLAGS=-static-libstdc++ make diff --git a/doc/build-windows.md b/doc/build-windows.md index bbff638b90..f88b9739de 100644 --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -9,7 +9,7 @@ The options known to work for building Bitcoin Core on Windows are: and is the platform used to build the Bitcoin Core Windows release binaries. * On Windows, using [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/windows/wsl/about) and the Mingw-w64 cross compiler tool chain. -* On Windows, using a native compiler tool chain such as [Visual Studio](https://www.visualstudio.com). +* On Windows, using a native compiler tool chain such as [Visual Studio](https://www.visualstudio.com). See [README.md](/build_msvc/README.md). Other options which may work, but which have not been extensively tested are (please contribute instructions): @@ -81,9 +81,26 @@ The first step is to install the mingw-w64 cross-compilation tool chain: sudo apt install g++-mingw-w64-x86-64 -Ubuntu Bionic 18.04 <sup>[1](#footnote1)</sup>: +Next, set the default `mingw32 g++` compiler option to POSIX<sup>[1](#footnote1)</sup>: - sudo update-alternatives --config x86_64-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. +``` +sudo update-alternatives --config x86_64-w64-mingw32-g++ +``` + +After running the above command, you should see output similar to that below. +Choose the option that ends with `posix`. + +``` +There are 2 choices for the alternative x86_64-w64-mingw32-g++ (providing /usr/bin/x86_64-w64-mingw32-g++). + + Selection Path Priority Status +------------------------------------------------------------ + 0 /usr/bin/x86_64-w64-mingw32-g++-win32 60 auto mode +* 1 /usr/bin/x86_64-w64-mingw32-g++-posix 30 manual mode + 2 /usr/bin/x86_64-w64-mingw32-g++-win32 60 manual mode + +Press <enter> to keep the current choice[*], or type selection number: +``` Once the toolchain is installed the build steps are common: @@ -91,15 +108,22 @@ Note that for WSL the Bitcoin Core source path MUST be somewhere in the default 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 is located directly on the host Windows file system to perform the build. +Additional WSL Note: WSL support for [launching Win32 applications](https://docs.microsoft.com/en-us/archive/blogs/wsl/windows-and-ubuntu-interoperability#launching-win32-applications-from-within-wsl) +results in `Autoconf` configure scripts being able to execute Windows Portable Executable files. This can cause +unexpected behaviour during the build, such as Win32 error dialogs for missing libraries. The recommended approach +is to temporarily disable WSL support for Win32 applications. + Build using: PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var + sudo bash -c "echo 0 > /proc/sys/fs/binfmt_misc/status" # Disable WSL support for Win32 applications. cd depends make HOST=x86_64-w64-mingw32 cd .. - ./autogen.sh # not required when building from tarball + ./autogen.sh CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/ - make + make # use "-j N" for N parallel jobs + sudo bash -c "echo 1 > /proc/sys/fs/binfmt_misc/status" # Enable WSL support for Win32 applications. ## Depends system diff --git a/doc/dependencies.md b/doc/dependencies.md index 51a2240107..66c5a76b3b 100644 --- a/doc/dependencies.md +++ b/doc/dependencies.md @@ -6,36 +6,43 @@ 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.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) | | | | +| Boost | [1.71.0](https://www.boost.org/users/download/) | [1.64.0](https://github.com/bitcoin/bitcoin/pull/22320) | No | | | +| Clang<sup>[ \* ](#note1)</sup> | | [5.0+](https://releases.llvm.org/download.html) (C++17 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 | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) (Android only) | -| GCC | | [4.8+](https://gcc.gnu.org/) (C++11 support) | | | | +| GCC | | [7+](https://gcc.gnu.org/) (C++17 support) | | | | | HarfBuzz-NG | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | -| libevent | [2.1.11-stable](https://github.com/libevent/libevent/releases) | 2.0.22 | No | | | +| libevent | [2.1.12-stable](https://github.com/libevent/libevent/releases) | [2.0.21](https://github.com/bitcoin/bitcoin/pull/18676) | No | | | +| libnatpmp | git commit [4536032...](https://github.com/miniupnp/libnatpmp/tree/4536032ae32268a45c073a4d5e91bbab4534773a) | | No | | | | libpng | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | | librsvg | | | | | | -| MiniUPnPc | [2.0.20180203](https://miniupnp.tuxfamily.org/files) | | No | | | +| MiniUPnPc | [2.2.2](https://miniupnp.tuxfamily.org/files) | | No | | | | PCRE | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | -| Python (tests) | | [3.5](https://www.python.org/downloads) | | | | +| Python (tests) | | [3.6](https://www.python.org/downloads) | | | | | qrencode | [3.4.4](https://fukuchi.org/works/qrencode) | | No | | | -| Qt | [5.9.8](https://download.qt.io/official_releases/qt/) | [5.5.1](https://github.com/bitcoin/bitcoin/issues/13478) | No | | | +| Qt | [5.12.11](https://download.qt.io/official_releases/qt/) | [5.9.5](https://github.com/bitcoin/bitcoin/issues/20104) | No | | | +| SQLite | [3.32.1](https://sqlite.org/download.html) | [3.7.17](https://github.com/bitcoin/bitcoin/pull/19077) | | | | | 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 | +| zlib | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | + +<a name="note1">Note \*</a> : When compiling with `-stdlib=libc++`, the minimum supported libc++ version is 7.0. Controlling dependencies ------------------------ Some dependencies are not needed in all configurations. The following are some factors that affect the dependency list. #### Options passed to `./configure` -* MiniUPnPc is not needed with `--with-miniupnpc=no`. -* Berkeley DB is not needed with `--disable-wallet`. +* MiniUPnPc is not needed with `--without-miniupnpc`. +* libnatpmp is not needed with `--without-natpmp`. +* Berkeley DB is not needed with `--disable-wallet` or `--without-bdb`. +* SQLite is not needed with `--disable-wallet` or `--without-sqlite`. * 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-compilation to) macOS. +* Not-Qt-bundled zlib is required to build the [DMG tool](../contrib/macdeploy/README.md#deterministic-macos-dmg-notes) from the libdmg-hfsplus project. diff --git a/doc/descriptors.md b/doc/descriptors.md index 181ff77e50..e27ff87546 100644 --- a/doc/descriptors.md +++ b/doc/descriptors.md @@ -30,6 +30,7 @@ Output descriptors currently support: - Pay-to-witness-pubkey-hash scripts (P2WPKH), through the `wpkh` function. - Pay-to-script-hash scripts (P2SH), through the `sh` function. - Pay-to-witness-script-hash scripts (P2WSH), through the `wsh` function. +- Pay-to-taproot outputs (P2TR), through the `tr` function. - Multisig scripts, through the `multi` function. - Multisig scripts where the public keys are sorted lexicographically, through the `sortedmulti` function. - Any type of supported address through the `addr` function. @@ -50,10 +51,11 @@ Output descriptors currently support: - `wsh(multi(2,03a0434d9e47f3c86235477c7b1ae6ae5d3442d49b1943c2b752a68e2a47e247c7,03774ae7f858a9411e5ef4246b70c65aac5649980be5c17891bbec17895da008cb,03d01115d548e7561b15c38f004d734633687cf4419620095bc5b0f47070afe85a))` describes a P2WSH *2-of-3* multisig output with keys in the specified order. - `sh(wsh(multi(1,03f28773c2d975288bc7d1d205c3748651b075fbc6610e58cddeeddf8f19405aa8,03499fdf9e895e719cfd64e67f07d38e3226aa7b63678949e6e49b241a60e823e4,02d7924d4f7d43ea965a465ae3095ff41131e5946f3c85f79e44adbcf8e27e080e)))` describes a P2SH-P2WSH *1-of-3* multisig output with keys in the specified order. - `pk(xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8)` describes a P2PK output with the public key of the specified xpub. -- `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1'/2)` describes a P2PKH output with child key *1'/2* of the specified xpub. +- `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1/2)` describes a P2PKH output with child key *1/2* of the specified xpub. - `pkh([d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/1/*)` describes a set of P2PKH outputs, but additionally specifies that the specified xpub is a child of a master with fingerprint `d34db33f`, and derived using path `44'/0'/0'`. - `wsh(multi(1,xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB/1/0/*,xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/0/0/*))` describes a set of *1-of-2* P2WSH multisig outputs where the first multisig key is the *1/0/`i`* child of the first specified xpub and the second multisig key is the *0/0/`i`* child of the second specified xpub, and `i` is any number in a configurable range (`0-1000` by default). - `wsh(sortedmulti(1,xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB/1/0/*,xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/0/0/*))` describes a set of *1-of-2* P2WSH multisig outputs where one multisig key is the *1/0/`i`* child of the first specified xpub and the other multisig key is the *0/0/`i`* child of the second specified xpub, and `i` is any number in a configurable range (`0-1000` by default). The order of public keys in the resulting witnessScripts is determined by the lexicographic order of the public keys at that index. +- `tr(c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5,{pk(fff97bd5755eeea420453a14355235d382f6472f8568a18b2f057a1460297556),pk(e493dbf1c10d80f3581e4904930b1404cc6c13900ee0758474fa94abe8c4cd13)})` describes a P2TR output with the `c6...` x-only pubkey as internal key, and two script paths. ## Reference @@ -61,13 +63,14 @@ Descriptors consist of several types of expressions. The top level expression is `SCRIPT` expressions: - `sh(SCRIPT)` (top level only): P2SH embed the argument. -- `wsh(SCRIPT)` (not inside another 'wsh'): P2WSH embed the argument. +- `wsh(SCRIPT)` (top level or inside `sh` only): P2WSH embed the argument. - `pk(KEY)` (anywhere): P2PK output for the given public key. -- `pkh(KEY)` (anywhere): P2PKH output for the given public key (use `addr` if you only know the pubkey hash). -- `wpkh(KEY)` (not inside `wsh`): P2WPKH output for the given compressed pubkey. +- `pkh(KEY)` (not inside `tr`): P2PKH output for the given public key (use `addr` if you only know the pubkey hash). +- `wpkh(KEY)` (top level or inside `sh` only): P2WPKH output for the given compressed pubkey. - `combo(KEY)` (top level only): an alias for the collection of `pk(KEY)` and `pkh(KEY)`. If the key is compressed, it also includes `wpkh(KEY)` and `sh(wpkh(KEY))`. -- `multi(k,KEY_1,KEY_2,...,KEY_n)` (anywhere): k-of-n multisig script. -- `sortedmulti(k,KEY_1,KEY_2,...,KEY_n)` (anywhere): k-of-n multisig script with keys sorted lexicographically in the resulting script. +- `multi(k,KEY_1,KEY_2,...,KEY_n)` (not inside `tr`): k-of-n multisig script. +- `sortedmulti(k,KEY_1,KEY_2,...,KEY_n)` (not inside `tr`): k-of-n multisig script with keys sorted lexicographically in the resulting script. +- `tr(KEY)` or `tr(KEY,TREE)` (top level only): P2TR output with the specified key as internal key, and optionally a tree of script paths. - `addr(ADDR)` (top level only): the script which ADDR expands to. - `raw(HEX)` (top level only): the script whose hex encoding is HEX. @@ -80,12 +83,17 @@ Descriptors consist of several types of expressions. The top level expression is - Followed by the actual key, which is either: - Hex encoded public keys (either 66 characters starting with `02` or `03` for a compressed pubkey, or 130 characters starting with `04` for an uncompressed pubkey). - Inside `wpkh` and `wsh`, only compressed public keys are permitted. + - Inside `tr`, x-only pubkeys are also permitted (64 hex characters). - [WIF](https://en.bitcoin.it/wiki/Wallet_import_format) encoded private keys may be specified instead of the corresponding public key, with the same meaning. - `xpub` encoded extended public key or `xprv` encoded extended private key (as defined in [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)). - Followed by zero or more `/NUM` unhardened and `/NUM'` hardened BIP32 derivation steps. - Optionally followed by a single `/*` or `/*'` final step to denote all (direct) unhardened or hardened children. - The usage of hardened derivation steps requires providing the private key. +`TREE` expressions: +- any `SCRIPT` expression +- An open brace `{`, a `TREE` expression, a comma `,`, a `TREE` expression, and a closing brace `}` + (Anywhere a `'` suffix is permitted to denote hardened derivation, the suffix `h` can be used instead.) `ADDR` expressions are any type of supported address: @@ -191,7 +199,7 @@ steps, or for dumping wallet descriptors including private key material. In order to easily represent the sets of scripts currently supported by existing Bitcoin Core wallets, a convenience function `combo` is provided, which takes as input a public key, and describes a set of P2PK, -P2PKH, P2WPKH, and P2SH-P2WPH scripts for that key. In case the key is +P2PKH, P2WPKH, and P2SH-P2WPKH scripts for that key. In case the key is uncompressed, the set only includes P2PK and P2PKH scripts. ### Checksums diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 97659cf76a..583c50a763 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -14,7 +14,7 @@ Developer Notes - [Compiling for debugging](#compiling-for-debugging) - [Compiling for gprof profiling](#compiling-for-gprof-profiling) - [`debug.log`](#debuglog) - - [Testnet and Regtest modes](#testnet-and-regtest-modes) + - [Signet, testnet, and regtest modes](#signet-testnet-and-regtest-modes) - [DEBUG_LOCKORDER](#debug_lockorder) - [Valgrind suppressions file](#valgrind-suppressions-file) - [Compiling for test coverage](#compiling-for-test-coverage) @@ -75,6 +75,11 @@ tool to clean up patches automatically before submission. on the same line as the `if`, without braces. In every other case, braces are required, and the `then` and `else` clauses must appear correctly indented on a new line. + - There's no hard limit on line width, but prefer to keep lines to <100 + characters if doing so does not decrease readability. Break up long + function declarations over multiple lines using the Clang Format + [AlignAfterOpenBracket](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) + style option. - **Symbol naming conventions**. These are preferred in new code, but are not required when doing so would need changes to significant pieces of existing @@ -135,7 +140,7 @@ Refer to [/test/functional/README.md#style-guidelines](/test/functional/README.m Coding Style (Doxygen-compatible comments) ------------------------------------------ -Bitcoin Core uses [Doxygen](http://www.doxygen.nl/) to generate its official documentation. +Bitcoin Core uses [Doxygen](https://www.doxygen.nl/) to generate its official documentation. Use Doxygen-compatible comment blocks for functions, methods, and fields. @@ -156,7 +161,7 @@ For example, to describe a function use: bool function(int arg1, const char *arg2, std::string& arg3) ``` -A complete list of `@xxx` commands can be found at http://www.doxygen.nl/manual/commands.html. +A complete list of `@xxx` commands can be found at https://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. @@ -203,7 +208,7 @@ Also not picked up by Doxygen: */ ``` -A full list of comment syntaxes picked up by Doxygen can be found at http://www.doxygen.nl/manual/docblocks.html, +A full list of comment syntaxes picked up by Doxygen can be found at https://www.doxygen.nl/manual/docblocks.html, but the above styles are favored. Recommendations: @@ -216,7 +221,7 @@ Recommendations: - Backticks aren't required when referring to functions Doxygen already knows about; it will build hyperlinks for these automatically. See - http://www.doxygen.nl/manual/autolink.html for complete info. + https://www.doxygen.nl/manual/autolink.html for complete info. - Avoid linking to external documentation; links can break. @@ -259,14 +264,15 @@ on all categories (and give you a very large `debug.log` file). The Qt code routes `qDebug()` output to `debug.log` under category "qt": run with `-debug=qt` to see it. -### Testnet and Regtest modes +### Signet, testnet, and regtest modes -Run with the `-testnet` option to run with "play bitcoins" on the test network, if you -are testing multi-machine code that needs to operate across the internet. +If you are testing multi-machine code that needs to operate across the internet, +you can run with either the `-signet` or the `-testnet` config option to test +with "play bitcoins" on a test network. -If you are testing something that can run on one machine, run with the `-regtest` option. -In regression test mode, blocks can be created on-demand; see [test/functional/](/test/functional) for tests -that run in `-regtest` mode. +If you are testing something that can run on one machine, run with the +`-regtest` option. In regression test mode, blocks can be created on demand; +see [test/functional/](/test/functional) for tests that run in `-regtest` mode. ### DEBUG_LOCKORDER @@ -276,6 +282,33 @@ 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 `debug.log` file if inconsistencies are detected. +### Assertions and Checks + +The util file `src/util/check.h` offers helpers to protect against coding and +internal logic bugs. They must never be used to validate user, network or any +other input. + +* `assert` or `Assert` should be used to document assumptions when any + violation would mean that it is not safe to continue program execution. The + code is always compiled with assertions enabled. + - For example, a nullptr dereference or any other logic bug in validation + code means the program code is faulty and must terminate immediately. +* `CHECK_NONFATAL` should be used for recoverable internal logic bugs. On + failure, it will throw an exception, which can be caught to recover from the + error. + - For example, a nullptr dereference or any other logic bug in RPC code + means that the RPC code is faulty and can not be executed. However, the + logic bug can be shown to the user and the program can continue to run. +* `Assume` should be used to document assumptions when program execution can + safely continue even if the assumption is violated. In debug builds it + behaves like `Assert`/`assert` to notify developers and testers about + nonfatal errors. In production it doesn't warn or log anything, though the + expression is always evaluated. + - For example it can be assumed that a variable is only initialized once, + but a failed assumption does not result in a fatal bug. A failed + assumption may or may not result in a slightly degraded user experience, + but it is safe to continue program execution. + ### Valgrind suppressions file Valgrind is a programming tool for memory debugging, memory leak detection, and @@ -423,27 +456,52 @@ and its `cs_KeyStore` lock for example). Threads ------- -- ThreadScriptCheck : Verifies block scripts. +- [Main thread (`bitcoind`)](https://doxygen.bitcoincore.org/bitcoind_8cpp.html#a0ddf1224851353fc92bfbff6f499fa97) + : Started from `main()` in `bitcoind.cpp`. Responsible for starting up and + shutting down the application. + +- [ThreadImport (`b-loadblk`)](https://doxygen.bitcoincore.org/init_8cpp.html#ae9e290a0e829ec0198518de2eda579d1) + : Loads blocks from `blk*.dat` files or `-loadblock=<file>` on startup. + +- [ThreadScriptCheck (`b-scriptch.x`)](https://doxygen.bitcoincore.org/validation_8cpp.html#a925a33e7952a157922b0bbb8dab29a20) + : Parallel script validation threads for transactions in blocks. -- ThreadImport : Loads blocks from `blk*.dat` files or `-loadblock=<file>`. +- [ThreadHTTP (`b-http`)](https://doxygen.bitcoincore.org/httpserver_8cpp.html#abb9f6ea8819672bd9a62d3695070709c) + : Libevent thread to listen for RPC and REST connections. -- ThreadDNSAddressSeed : Loads addresses of peers from the DNS. +- [HTTP worker threads(`b-httpworker.x`)](https://doxygen.bitcoincore.org/httpserver_8cpp.html#aa6a7bc27265043bc0193220c5ae3a55f) + : Threads to service RPC and REST requests. -- ThreadMapPort : Universal plug-and-play startup/shutdown. +- [Indexer threads (`b-txindex`, etc)](https://doxygen.bitcoincore.org/class_base_index.html#a96a7407421fbf877509248bbe64f8d87) + : One thread per indexer. -- ThreadSocketHandler : Sends/Receives data from peers on port 8333. +- [SchedulerThread (`b-scheduler`)](https://doxygen.bitcoincore.org/class_c_scheduler.html#a14d2800815da93577858ea078aed1fba) + : Does asynchronous background tasks like dumping wallet contents, dumping + addrman and running asynchronous validationinterface callbacks. -- ThreadOpenAddedConnections : Opens network connections to added nodes. +- [TorControlThread (`b-torcontrol`)](https://doxygen.bitcoincore.org/torcontrol_8cpp.html#a4faed3692d57a0d7bdbecf3b37f72de0) + : Libevent thread for tor connections. -- ThreadOpenConnections : Initiates new connections to peers. +- Net threads: -- ThreadMessageHandler : Higher-level message handling (sending and receiving). + - [ThreadMessageHandler (`b-msghand`)](https://doxygen.bitcoincore.org/class_c_connman.html#aacdbb7148575a31bb33bc345e2bf22a9) + : Application level message handling (sending and receiving). Almost + all net_processing and validation logic runs on this thread. -- DumpAddresses : Dumps IP addresses of nodes to `peers.dat`. + - [ThreadDNSAddressSeed (`b-dnsseed`)](https://doxygen.bitcoincore.org/class_c_connman.html#aa7c6970ed98a4a7bafbc071d24897d13) + : Loads addresses of peers from the DNS. -- ThreadRPCServer : Remote procedure call handler, listens on port 8332 for connections and services them. + - [ThreadMapPort (`b-upnp`)](https://doxygen.bitcoincore.org/net_8cpp.html#a63f82a71c4169290c2db1651a9bbe249) + : Universal plug-and-play startup/shutdown. -- Shutdown : Does an orderly shutdown of everything. + - [ThreadSocketHandler (`b-net`)](https://doxygen.bitcoincore.org/class_c_connman.html#a765597cbfe99c083d8fa3d61bb464e34) + : Sends/Receives data from peers on port 8333. + + - [ThreadOpenAddedConnections (`b-addcon`)](https://doxygen.bitcoincore.org/class_c_connman.html#a0b787caf95e52a346a2b31a580d60a62) + : Opens network connections to added nodes. + + - [ThreadOpenConnections (`b-opencon`)](https://doxygen.bitcoincore.org/class_c_connman.html#a55e9feafc3bab78e5c9d408c207faa45) + : Initiates new connections to peers. Ignoring IDE/editor files -------------------------- @@ -491,7 +549,7 @@ General Bitcoin Core - *Rationale*: RPC allows for better automatic testing. The test suite for the GUI is very limited. -- Make sure pull requests pass Travis CI before merging. +- Make sure pull requests pass 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 @@ -537,11 +595,6 @@ Common misconceptions are clarified in those sections: - *Rationale*: This avoids memory and resource leaks, and ensures exception safety. -- 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). - C++ data structures -------------------- @@ -595,6 +648,19 @@ class A - *Rationale*: Easier to understand what is happening, thus easier to spot mistakes, even for those that are not language lawyers. +- Use `Span` as function argument when it can operate on any range-like container. + + - *Rationale*: Compared to `Foo(const vector<int>&)` this avoids the need for a (potentially expensive) + conversion to vector if the caller happens to have the input stored in another type of container. + However, be aware of the pitfalls documented in [span.h](../src/span.h). + +```cpp +void Foo(Span<const int> data); + +std::vector<int> vec{1,2,3}; +Foo(vec); +``` + - Prefer `enum class` (scoped enumerations) over `enum` (traditional enumerations) where possible. - *Rationale*: Scoped enumerations avoid two potential pitfalls/problems with traditional C++ enumerations: implicit conversions to `int`, and name clashes due to enumerators being exported to the surrounding scope. @@ -708,6 +774,58 @@ the upper cycle, etc. Threads and synchronization ---------------------------- +- Prefer `Mutex` type to `RecursiveMutex` one + +- Consistently use [Clang Thread Safety Analysis](https://clang.llvm.org/docs/ThreadSafetyAnalysis.html) annotations to + get compile-time warnings about potential race conditions in code. Combine annotations in function declarations with + run-time asserts in function definitions: + + - In functions that are declared separately from where they are defined, the + thread safety annotations should be added exclusively to the function + declaration. Annotations on the definition could lead to false positives + (lack of compile failure) at call sites between the two. + +```C++ +// txmempool.h +class CTxMemPool +{ +public: + ... + mutable RecursiveMutex cs; + ... + void UpdateTransactionsFromBlock(...) EXCLUSIVE_LOCKS_REQUIRED(::cs_main, cs); + ... +} + +// txmempool.cpp +void CTxMemPool::UpdateTransactionsFromBlock(...) +{ + AssertLockHeld(::cs_main); + AssertLockHeld(cs); + ... +} +``` + +```C++ +// validation.h +class ChainstateManager +{ +public: + ... + bool ProcessNewBlock(...) LOCKS_EXCLUDED(::cs_main); + ... +} + +// validation.cpp +bool ChainstateManager::ProcessNewBlock(...) +{ + AssertLockNotHeld(::cs_main); + ... + LOCK(::cs_main); + ... +} +``` + - 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`. @@ -849,7 +967,7 @@ Others are external projects without a tight relationship with our project. Chan 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 +There is a tool in `test/lint/git-subtree-check.sh` ([instructions](../test/lint#git-subtree-checksh)) to check a subtree directory for consistency with its upstream repository. Current subtrees include: @@ -924,7 +1042,7 @@ Scripted diffs -------------- For reformatting and refactoring commits where the changes can be easily automated using a bash script, we use -scripted-diff commits. The bash script is included in the commit message and our Travis CI job checks that +scripted-diff commits. The bash script is included in the commit message and our CI job checks that the result of the script is identical to the commit. This aids reviewers since they can verify that the script does exactly what it is supposed to do. It is also helpful for rebasing (since the same script can just be re-run on the new master commit). @@ -965,7 +1083,7 @@ Some good examples of scripted-diff: - [scripted-diff: Rename InitInterfaces to NodeContext](https://github.com/bitcoin/bitcoin/commit/301bd41a2e6765b185bd55f4c541f9e27aeea29d) uses an elegant script to replace occurrences of multiple terms in all source files. -- [scripted-diff: Remove g_connman, g_banman globals](https://github.com/bitcoin/bitcoin/commit/301bd41a2e6765b185bd55f4c541f9e27aeea29d) +- [scripted-diff: Remove g_connman, g_banman globals](https://github.com/bitcoin/bitcoin/commit/8922d7f6b751a3e6b3b9f6fb7961c442877fb65a) replaces specific terms in a list of specific source files. - [scripted-diff: Replace fprintf with tfm::format](https://github.com/bitcoin/bitcoin/commit/fac03ec43a15ad547161e37e53ea82482cc508f9) @@ -1042,13 +1160,6 @@ A few guidelines for introducing and reviewing new RPC interfaces: - *Rationale*: If not, the call can not be used with name-based arguments. -- Set okSafeMode in the RPC command table to a sensible value: safe mode is when the - blockchain is regarded to be in a confused state, and the client deems it unsafe to - do anything irreversible such as send. Anything that just queries should be permitted. - - - *Rationale*: Troubleshooting a node in safe mode is difficult if half the - RPCs don't work. - - Add every non-string RPC argument `(method, idx, name)` to the table `vRPCConvertParams` in `rpc/client.cpp`. - *Rationale*: `bitcoin-cli` and the GUI debug console use this table to determine how to diff --git a/doc/external-signer.md b/doc/external-signer.md new file mode 100644 index 0000000000..de44cdd880 --- /dev/null +++ b/doc/external-signer.md @@ -0,0 +1,171 @@ +# Support for signing transactions outside of Bitcoin Core + +Bitcoin Core can be launched with `-signer=<cmd>` where `<cmd>` is an external tool which can sign transactions and perform other functions. For example, it can be used to communicate with a hardware wallet. + +## Example usage + +The following example is based on the [HWI](https://github.com/bitcoin-core/HWI) tool. Version 2.0 or newer is required. Although this tool is hosted under the Bitcoin Core GitHub organization and maintained by Bitcoin Core developers, it should be used with caution. It is considered experimental and has far less review than Bitcoin Core itself. Be particularly careful when running tools such as these on a computer with private keys on it. + +When using a hardware wallet, consult the manufacturer website for (alternative) software they recommend. As long as their software conforms to the standard below, it should be able to work with Bitcoin Core. + +Start Bitcoin Core: + +```sh +$ bitcoind -signer=../HWI/hwi.py +``` + +### Device setup + +Follow the hardware manufacturers instructions for the initial device setup, as well as their instructions for creating a backup. Alternatively, for some devices, you can use the `setup`, `restore` and `backup` commands provided by [HWI](https://github.com/bitcoin-core/HWI). + +### Create wallet and import keys + +Get a list of signing devices / services: + +``` +$ bitcoin-cli enumeratesigners +{ + "signers": [ + { + "fingerprint": "c8df832a" + } +] +``` + +The master key fingerprint is used to identify a device. + +Create a wallet, this automatically imports the public keys: + +```sh +$ bitcoin-cli createwallet "hww" true true "" true true true +``` + +### Verify an address + +Display an address on the device: + +```sh +$ bitcoin-cli -rpcwallet=<wallet> getnewaddress +$ bitcoin-cli -rpcwallet=<wallet> walletdisplayaddress <address> +``` + +Replace `<address>` with the result of `getnewaddress`. + +### Spending + +Under the hood this uses a [Partially Signed Bitcoin Transaction](psbt.md). + +```sh +$ bitcoin-cli -rpcwallet=<wallet> sendtoaddress <address> <amount> +``` + +This prompts your hardware wallet to sign, and fail if it's not connected. If successful +it automatically broadcasts the transaction. + +```sh +{"complete": true, "txid": <txid>} +``` + +## Signer API + +In order to be compatible with Bitcoin Core any signer command should conform to the specification below. This specification is subject to change. Ideally a BIP should propose a standard so that other wallets can also make use of it. + +Prerequisite knowledge: +* [Output Descriptors](descriptors.md) +* Partially Signed Bitcoin Transaction ([PSBT](psbt.md)) + +### `enumerate` (required) + +Usage: +``` +$ <cmd> enumerate +[ + { + "fingerprint": "00000000" + } +] +``` + +The command MUST return an (empty) array with at least a `fingerprint` field. + +A future extension could add an optional return field with device capabilities. Perhaps a descriptor with wildcards. For example: `["pkh("44'/0'/$'/{0,1}/*"), sh(wpkh("49'/0'/$'/{0,1}/*")), wpkh("84'/0'/$'/{0,1}/*")]`. This would indicate the device supports legacy, wrapped SegWit and native SegWit. In addition it restricts the derivation paths that can used for those, to maintain compatibility with other wallet software. It also indicates the device, or the driver, doesn't support multisig. + +A future extension could add an optional return field `reachable`, in case `<cmd>` knows a signer exists but can't currently reach it. + +### `signtransaction` (required) + +Usage: +``` +$ <cmd> --fingerprint=<fingerprint> (--testnet) signtransaction <psbt> +base64_encode_signed_psbt +``` + +The command returns a psbt with any signatures. + +The `psbt` SHOULD include bip32 derivations. The command SHOULD fail if none of the bip32 derivations match a key owned by the device. + +The command SHOULD fail if the user cancels. + +The command MAY complain if `--testnet` is set, but any of the BIP32 derivation paths contain a coin type other than `1h` (and vice versa). + +### `getdescriptors` (optional) + +Usage: + +``` +$ <cmd> --fingerprint=<fingerprint> (--testnet) getdescriptors <account> +<xpub> +``` + +Returns descriptors supported by the device. Example: + +``` +$ <cmd> --fingerprint=00000000 --testnet getdescriptors +{ + "receive": [ + "pkh([00000000/44h/0h/0h]xpub6C.../0/*)#fn95jwmg", + "sh(wpkh([00000000/49h/0h/0h]xpub6B..../0/*))#j4r9hntt", + "wpkh([00000000/84h/0h/0h]xpub6C.../0/*)#qw72dxa9" + ], + "internal": [ + "pkh([00000000/44h/0h/0h]xpub6C.../1/*)#c8q40mts", + "sh(wpkh([00000000/49h/0h/0h]xpub6B..../1/*))#85dn0v75", + "wpkh([00000000/84h/0h/0h]xpub6C..../1/*)#36mtsnda" + ] +} +``` + +### `displayaddress` (optional) + +Usage: +``` +<cmd> --fingerprint=<fingerprint> (--testnet) displayaddress --desc descriptor +``` + +Example, display the first native SegWit receive address on Testnet: + +``` +<cmd> --fingerprint=00000000 --testnet displayaddress --desc "wpkh([00000000/84h/1h/0h]tpubDDUZ..../0/0)" +``` + +The command MUST be able to figure out the address type from the descriptor. + +If <descriptor> contains a master key fingerprint, the command MUST fail if it does not match the fingerprint known by the device. + +If <descriptor> contains an xpub, the command MUST fail if it does not match the xpub known by the device. + +The command MAY complain if `--testnet` is set, but the BIP32 coin type is not `1h` (and vice versa). + +## How Bitcoin Core uses the Signer API + +The `enumeratesigners` RPC simply calls `<cmd> enumerate`. + +The `createwallet` RPC calls: + +* `<cmd> --fingerprint=00000000 getdescriptors 0` + +It then imports descriptors for all support address types, in a BIP44/49/84 compatible manner. + +The `walletdisplayaddress` RPC reuses some code from `getaddressinfo` on the provided address and obtains the inferred descriptor. It then calls `<cmd> --fingerprint=00000000 displayaddress --desc=<descriptor>`. + +`sendtoaddress` and `sendmany` check `inputs->bip32_derivs` to see if any inputs have the same `master_fingerprint` as the signer. If so, it calls `<cmd> --fingerprint=00000000 signtransaction <psbt>`. It waits for the device to return a (partially) signed psbt, tries to finalize it and broadcasts the transaction. diff --git a/doc/files.md b/doc/files.md index cd23d547bb..e670d77ae5 100644 --- a/doc/files.md +++ b/doc/files.md @@ -8,6 +8,10 @@ - [Multi-wallet environment](#multi-wallet-environment) + - [Berkeley DB database based wallets](#berkeley-db-database-based-wallets) + + - [SQLite database based wallets](#sqlite-database-based-wallets) + - [GUI settings](#gui-settings) - [Legacy subdirectories and files](#legacy-subdirectories-and-files) @@ -26,15 +30,16 @@ Linux | `$HOME/.bitcoin/` macOS | `$HOME/Library/Application Support/Bitcoin/` Windows | `%APPDATA%\Bitcoin\` <sup>[\[1\]](#note1)</sup> -2. The non-default data directory path can be specified by `-datadir` option. +2. A custom data directory path can be specified with the `-datadir` option. 3. All content of the data directory, except for `bitcoin.conf` file, is chain-specific. This means the actual data directory paths for non-mainnet cases differ: -Chain option | Data directory path ---------------------|-------------------- -no option (mainnet) | *path_to_datadir*`/` -`-testnet` | *path_to_datadir*`/testnet3/` -`-regtest` | *path_to_datadir*`/regtest/` +Chain option | Data directory path +-------------------------------|------------------------------ +`-chain=main` (default) | *path_to_datadir*`/` +`-chain=test` or `-testnet` | *path_to_datadir*`/testnet3/` +`-chain=signet` or `-signet` | *path_to_datadir*`/signet/` +`-chain=regtest` or `-regtest` | *path_to_datadir*`/regtest/` ## Data directory layout @@ -44,51 +49,68 @@ Subdirectory | File(s) | Description `blocks/index/` | LevelDB database | Block index; `-blocksdir` option does not affect this path `blocks/` | `blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Actual Bitcoin blocks (in network format, dumped in raw on disk, 128 MiB per file) `blocks/` | `revNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Block undo data (custom format) -`chainstate/` | LevelDB database | Blockchain state (a compact representation of all currently unspent transaction outputs and some metadata about the transactions they are from) +`chainstate/` | LevelDB database | Blockchain state (a compact representation of all currently unspent transaction outputs (UTXOs) and metadata about the transactions they are from) `indexes/txindex/` | LevelDB database | Transaction index; *optional*, used if `-txindex=1` `indexes/blockfilter/basic/db/` | LevelDB database | Blockfilter index LevelDB database for the basic filtertype; *optional*, used if `-blockfilterindex=basic` `indexes/blockfilter/basic/` | `fltrNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Blockfilter index filters for the basic filtertype; *optional*, used if `-blockfilterindex=basic` -`wallets/` | | [Contains wallets](#multi-wallet-environment); can be specified by `-walletdir` option; if `wallets/` subdirectory does not exist, a wallet resides in the data directory -`./` | `banlist.dat` | Stores the IPs/subnets of banned nodes -`./` | `bitcoin.conf` | Contains [configuration settings](bitcoin-conf.md) for `bitcoind` or `bitcoin-qt`; can be specified by `-conf` option +`indexes/coinstats/db/` | LevelDB database | Coinstats index; *optional*, used if `-coinstatsindex=1` +`wallets/` | | [Contains wallets](#multi-wallet-environment); can be specified by `-walletdir` option; if `wallets/` subdirectory does not exist, wallets reside in the [data directory](#data-directory-location) +`./` | `anchors.dat` | Anchor IP address database, created on shutdown and deleted at startup. Anchors are last known outgoing block-relay-only peers that are tried to re-connect to on startup +`./` | `banlist.dat` | Stores the addresses/subnets of banned nodes (deprecated). `bitcoind` or `bitcoin-qt` no longer save the banlist to this file, but read it on startup if `banlist.json` is not present. +`./` | `banlist.json` | Stores the addresses/subnets of banned nodes. +`./` | `bitcoin.conf` | User-defined [configuration settings](bitcoin-conf.md) for `bitcoind` or `bitcoin-qt`. File is not written to by the software and must be created manually. Path can be specified by `-conf` option `./` | `bitcoind.pid` | Stores the process ID (PID) of `bitcoind` or `bitcoin-qt` while running; created at start and deleted on shutdown; can be specified by `-pid` option `./` | `debug.log` | Contains debug information and general logging generated by `bitcoind` or `bitcoin-qt`; can be specified by `-debuglogfile` option -`./` | `fee_estimates.dat` | Stores statistics used to estimate minimum transaction fees and priorities required for confirmation +`./` | `fee_estimates.dat` | Stores statistics used to estimate minimum transaction fees required for confirmation `./` | `guisettings.ini.bak` | Backup of former [GUI settings](#gui-settings) after `-resetguisettings` option is used +`./` | `ip_asn.map` | IP addresses to Autonomous System Numbers (ASNs) mapping used for bucketing of the peers; path can be specified with the `-asmap` option `./` | `mempool.dat` | Dump of the mempool's transactions -`./` | `onion_private_key` | Cached Tor hidden service private key for `-listenonion` option +`./` | `onion_v3_private_key` | Cached Tor onion service private key for `-listenonion` option +`./` | `i2p_private_key` | Private key that corresponds to our I2P address. When `-i2psam=` is specified the contents of this file is used to identify ourselves for making outgoing connections to I2P peers and possibly accepting incoming ones. Automatically generated if it does not exist. `./` | `peers.dat` | Peer IP address database (custom format) +`./` | `settings.json` | Read-write settings set through GUI or RPC interfaces, augmenting manual settings from [bitcoin.conf](bitcoin-conf.md). File is created automatically if read-write settings storage is not disabled with `-nosettings` option. Path can be specified with `-settings` option `./` | `.cookie` | Session RPC authentication cookie; if used, created at start and deleted on shutdown; can be specified by `-rpccookiefile` option `./` | `.lock` | Data directory lock file ## Multi-wallet environment -Wallets are Berkeley DB (BDB) databases: - -Subdirectory | File(s) | Description --------------|-------------------|------------ -`database/` | BDB logging files | Part of BDB environment; created at start and deleted on shutdown; a user *must keep it as safe* as personal wallet `wallet.dat` -`./` | `db.log` | BDB error file -`./` | `wallet.dat` | Personal wallet (BDB) with keys and transactions -`./` | `.walletlock` | Wallet lock file +Wallets are Berkeley DB (BDB) or SQLite databases. -1. Each user-defined wallet named "wallet_name" resides in `wallets/wallet_name/` subdirectory. +1. Each user-defined wallet named "wallet_name" resides in the `wallets/wallet_name/` subdirectory. 2. The default (unnamed) wallet resides in `wallets/` subdirectory; if the latter does not exist, the wallet resides in the data directory. -3. A wallet database path can be specified by `-wallet` option. +3. A wallet database path can be specified with the `-wallet` option. 4. `wallet.dat` files must not be shared across different node instances, as that can result in key-reuse and double-spends due the lack of synchronization between instances. 5. Any copy or backup of the wallet should be done through a `backupwallet` call in order to update and lock the wallet, preventing any file corruption caused by updates during the copy. + +### Berkeley DB database based wallets + +Subdirectory | File(s) | Description +-------------|-------------------|------------- +`database/` | BDB logging files | Part of BDB environment; created at start and deleted on shutdown; a user *must keep it as safe* as personal wallet `wallet.dat` +`./` | `db.log` | BDB error file +`./` | `wallet.dat` | Personal wallet (a BDB database) with keys and transactions +`./` | `.walletlock` | BDB wallet lock file + +### SQLite database based wallets + +Subdirectory | File | Description +-------------|----------------------|------------- +`./` | `wallet.dat` | Personal wallet (a SQLite database) with keys and transactions +`./` | `wallet.dat-journal` | SQLite Rollback Journal file for `wallet.dat`. Usually created at start and deleted on shutdown. A user *must keep it as safe* as the `wallet.dat` file. + + ## GUI settings `bitcoin-qt` uses [`QSettings`](https://doc.qt.io/qt-5/qsettings.html) class; this implies platform-specific [locations where application settings are stored](https://doc.qt.io/qt-5/qsettings.html#locations-where-application-settings-are-stored). ## Legacy subdirectories and files -These subdirectories and files are no longer used by the Bitcoin Core: +These subdirectories and files are no longer used by Bitcoin Core: Path | Description | Repository notes ---------------|-------------|----------------- @@ -97,10 +119,10 @@ Path | Description | Repository notes `blkindex.dat` | Blockchain index BDB database; replaced by {`chainstate/`, `blocks/index/`, `blocks/revNNNNN.dat`<sup>[\[2\]](#note2)</sup>} in 0.8.0 | [PR #1677](https://github.com/bitcoin/bitcoin/pull/1677) `blk000?.dat` | Block data (custom format, 2 GiB per file); replaced by `blocks/blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> in 0.8.0 | [PR #1677](https://github.com/bitcoin/bitcoin/pull/1677) `addr.dat` | Peer IP address BDB database; replaced by `peers.dat` in [0.7.0](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.7.0.md) | [PR #1198](https://github.com/bitcoin/bitcoin/pull/1198), [`928d3a01`](https://github.com/bitcoin/bitcoin/commit/928d3a011cc66c7f907c4d053f674ea77dc611cc) +`onion_private_key` | Cached Tor onion service private key for `-listenonion` option. Was used for Tor v2 services; replaced by `onion_v3_private_key` in [0.21.0](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.21.0.md) | [PR #19954](https://github.com/bitcoin/bitcoin/pull/19954) ## Notes -<a name="note1">1</a>. The `/` (slash, U+002F) is used as the platform-independent path component separator in this paper. +<a name="note1">1</a>. The `/` (slash, U+002F) is used as the platform-independent path component separator in this document. <a name="note2">2</a>. `NNNNN` matches `[0-9]{5}` regex. - diff --git a/doc/fuzzing.md b/doc/fuzzing.md index 9642337821..6fc9077e4c 100644 --- a/doc/fuzzing.md +++ b/doc/fuzzing.md @@ -12,11 +12,11 @@ $ CC=clang CXX=clang++ ./configure --enable-fuzz --with-sanitizers=address,fuzze # macOS users: If you have problem with this step then make sure to read "macOS hints for # libFuzzer" on https://github.com/bitcoin/bitcoin/blob/master/doc/fuzzing.md#macos-hints-for-libfuzzer $ make -$ src/test/fuzz/process_message +$ FUZZ=process_message src/test/fuzz/fuzz # abort fuzzing using ctrl-c ``` -## Fuzzing harnesses, fuzzing output and fuzzing corpora +## Fuzzing harnesses and output [`process_message`](https://github.com/bitcoin/bitcoin/blob/master/src/test/fuzz/process_message.cpp) is a fuzzing harness for the [`ProcessMessage(...)` function (`net_processing`)](https://github.com/bitcoin/bitcoin/blob/master/src/net_processing.cpp). The available fuzzing harnesses are found in [`src/test/fuzz/`](https://github.com/bitcoin/bitcoin/tree/master/src/test/fuzz). @@ -26,7 +26,7 @@ If you specify a corpus directory then any new coverage increasing inputs will b ```sh $ mkdir -p process_message-seeded-from-thin-air/ -$ src/test/fuzz/process_message process_message-seeded-from-thin-air/ +$ FUZZ=process_message src/test/fuzz/fuzz process_message-seeded-from-thin-air/ INFO: Seed: 840522292 INFO: Loaded 1 modules (424174 inline 8-bit counters): 424174 [0x55e121ef9ab8, 0x55e121f613a6), INFO: Loaded 1 PC tables (424174 PCs): 424174 [0x55e121f613a8,0x55e1225da288), @@ -64,13 +64,15 @@ block^@M-^?M-^?M-^?M-^?M-^?nM-^?M-^? In this case the fuzzer managed to create a `block` message which when passed to `ProcessMessage(...)` increased coverage. +## Fuzzing corpora + The project's collection of seed corpora is found in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. To fuzz `process_message` using the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) seed corpus: ```sh $ git clone https://github.com/bitcoin-core/qa-assets -$ src/test/fuzz/process_message qa-assets/fuzz_seed_corpus/process_message/ +$ FUZZ=process_message src/test/fuzz/fuzz qa-assets/fuzz_seed_corpus/process_message/ INFO: Seed: 1346407872 INFO: Loaded 1 modules (424174 inline 8-bit counters): 424174 [0x55d8a9004ab8, 0x55d8a906c3a6), INFO: Loaded 1 PC tables (424174 PCs): 424174 [0x55d8a906c3a8,0x55d8a96e5288), @@ -81,6 +83,20 @@ INFO: seed corpus: files: 991 min: 1b max: 1858b total: 288291b rss: 150Mb … ``` +## Reproduce a fuzzer crash reported by the CI + +- `cd` into the `qa-assets` directory and update it with `git pull qa-assets` +- locate the crash case described in the CI output, e.g. `Test unit written to + ./crash-1bc91feec9fc00b107d97dc225a9f2cdaa078eb6` +- make sure to compile with all sanitizers, if they are needed (fuzzing runs + more slowly with sanitizers enabled, but a crash should be reproducible very + quickly from a crash case) +- run the fuzzer with the case number appended to the seed corpus path: + `FUZZ=process_message src/test/fuzz/fuzz + qa-assets/fuzz_seed_corpus/process_message/1bc91feec9fc00b107d97dc225a9f2cdaa078eb6` + +## Submit improved coverage + If you find coverage increasing inputs when fuzzing you are highly encouraged to submit them for inclusion in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. Every single pull request submitted against the Bitcoin Core repo is automatically tested against all inputs in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. Contributing new coverage increasing inputs is an easy way to help make Bitcoin Core more robust. @@ -108,28 +124,139 @@ Full configure that was tested on macOS Catalina with `brew` installed `llvm`: Read the [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html) for more information. This [libFuzzer tutorial](https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md) might also be of interest. -# Fuzzing Bitcoin Core using american fuzzy lop (`afl-fuzz`) +# Fuzzing Bitcoin Core using afl++ ## Quickstart guide -To quickly get started fuzzing Bitcoin Core using [`afl-fuzz`](https://github.com/google/afl): +To quickly get started fuzzing Bitcoin Core using [afl++](https://github.com/AFLplusplus/AFLplusplus): ```sh $ git clone https://github.com/bitcoin/bitcoin $ cd bitcoin/ -$ git clone https://github.com/google/afl -$ make -C afl/ -$ make -C afl/llvm_mode/ +$ git clone https://github.com/AFLplusplus/AFLplusplus +$ make -C AFLplusplus/ source-only $ ./autogen.sh -$ CC=$(pwd)/afl/afl-clang-fast CXX=$(pwd)/afl/afl-clang-fast++ ./configure --enable-fuzz +# If afl-clang-lto is not available, see +# https://github.com/AFLplusplus/AFLplusplus#a-selecting-the-best-afl-compiler-for-instrumenting-the-target +$ CC=$(pwd)/AFLplusplus/afl-clang-lto CXX=$(pwd)/AFLplusplus/afl-clang-lto++ ./configure --enable-fuzz $ make # For macOS you may need to ignore x86 compilation checks when running "make". If so, # try compiling using: AFL_NO_X86=1 make $ mkdir -p inputs/ outputs/ $ echo A > inputs/thin-air-input -$ afl/afl-fuzz -i inputs/ -o outputs/ -- src/test/fuzz/bech32 +$ FUZZ=bech32 AFLplusplus/afl-fuzz -i inputs/ -o outputs/ -- src/test/fuzz/fuzz # You may have to change a few kernel parameters to test optimally - afl-fuzz # will print an error and suggestion if so. ``` -Read the [`afl-fuzz` documentation](https://github.com/google/afl) for more information. +Read the [afl++ documentation](https://github.com/AFLplusplus/AFLplusplus) for more information. + +# Fuzzing Bitcoin Core using Honggfuzz + +## Quickstart guide + +To quickly get started fuzzing Bitcoin Core using [Honggfuzz](https://github.com/google/honggfuzz): + +```sh +$ git clone https://github.com/bitcoin/bitcoin +$ cd bitcoin/ +$ ./autogen.sh +$ git clone https://github.com/google/honggfuzz +$ cd honggfuzz/ +$ make +$ cd .. +$ CC=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang CXX=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++ ./configure --enable-fuzz --with-sanitizers=address,undefined +$ make +$ mkdir -p inputs/ +$ FUZZ=process_message honggfuzz/honggfuzz -i inputs/ -- src/test/fuzz/fuzz +``` + +Read the [Honggfuzz documentation](https://github.com/google/honggfuzz/blob/master/docs/USAGE.md) for more information. + +## Fuzzing the Bitcoin Core P2P layer using Honggfuzz NetDriver + +Honggfuzz NetDriver allows for very easy fuzzing of TCP servers such as Bitcoin +Core without having to write any custom fuzzing harness. The `bitcoind` server +process is largely fuzzed without modification. + +This makes the fuzzing highly realistic: a bug reachable by the fuzzer is likely +also remotely triggerable by an untrusted peer. + +To quickly get started fuzzing the P2P layer using Honggfuzz NetDriver: + +```sh +$ mkdir bitcoin-honggfuzz-p2p/ +$ cd bitcoin-honggfuzz-p2p/ +$ git clone https://github.com/bitcoin/bitcoin +$ cd bitcoin/ +$ ./autogen.sh +$ git clone https://github.com/google/honggfuzz +$ cd honggfuzz/ +$ make +$ cd .. +$ CC=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang \ + CXX=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++ \ + ./configure --disable-wallet --with-gui=no \ + --with-sanitizers=address,undefined +$ git apply << "EOF" +diff --git a/src/bitcoind.cpp b/src/bitcoind.cpp +index 455a82e39..2faa3f80f 100644 +--- a/src/bitcoind.cpp ++++ b/src/bitcoind.cpp +@@ -158,7 +158,11 @@ static bool AppInit(int argc, char* argv[]) + return fRet; + } + ++#ifdef HFND_FUZZING_ENTRY_FUNCTION_CXX ++HFND_FUZZING_ENTRY_FUNCTION_CXX(int argc, char* argv[]) ++#else + int main(int argc, char* argv[]) ++#endif + { + #ifdef WIN32 + util::WinCmdLineArgs winArgs; +diff --git a/src/net.cpp b/src/net.cpp +index cf987b699..636a4176a 100644 +--- a/src/net.cpp ++++ b/src/net.cpp +@@ -709,7 +709,7 @@ int V1TransportDeserializer::readHeader(const char *pch, unsigned int nBytes) + } + + // Check start string, network magic +- if (memcmp(hdr.pchMessageStart, m_chain_params.MessageStart(), CMessageHeader::MESSAGE_START_SIZE) != 0) { ++ if (false && memcmp(hdr.pchMessageStart, m_chain_params.MessageStart(), CMessageHeader::MESSAGE_START_SIZE) != 0) { // skip network magic checking + LogPrint(BCLog::NET, "HEADER ERROR - MESSAGESTART (%s, %u bytes), received %s, peer=%d\n", hdr.GetCommand(), hdr.nMessageSize, HexStr(hdr.pchMessageStart), m_node_id); + return -1; + } +@@ -768,7 +768,7 @@ Optional<CNetMessage> V1TransportDeserializer::GetMessage(const std::chrono::mic + RandAddEvent(ReadLE32(hash.begin())); + + // Check checksum and header command string +- if (memcmp(hash.begin(), hdr.pchChecksum, CMessageHeader::CHECKSUM_SIZE) != 0) { ++ if (false && memcmp(hash.begin(), hdr.pchChecksum, CMessageHeader::CHECKSUM_SIZE) != 0) { // skip checksum checking + LogPrint(BCLog::NET, "CHECKSUM ERROR (%s, %u bytes), expected %s was %s, peer=%d\n", + SanitizeString(msg->m_command), msg->m_message_size, + HexStr(Span<uint8_t>(hash.begin(), hash.begin() + CMessageHeader::CHECKSUM_SIZE)), +EOF +$ make -C src/ bitcoind +$ mkdir -p inputs/ +$ honggfuzz/honggfuzz --exit_upon_crash --quiet --timeout 4 -n 1 -Q \ + -E HFND_TCP_PORT=18444 -f inputs/ -- \ + src/bitcoind -regtest -discover=0 -dns=0 -dnsseed=0 -listenonion=0 \ + -nodebuglogfile -bind=127.0.0.1:18444 -logthreadnames \ + -debug +``` + +# OSS-Fuzz + +Bitcoin Core participates in Google's [OSS-Fuzz](https://github.com/google/oss-fuzz/tree/master/projects/bitcoin-core) +program, which includes a dashboard of [publicly disclosed vulnerabilities](https://bugs.chromium.org/p/oss-fuzz/issues/list?q=bitcoin-core). +Generally, we try to disclose vulnerabilities as soon as possible after they +are fixed to give users the knowledge they need to be protected. However, +because Bitcoin is a live P2P network, and not just standalone local software, +we might not fully disclose every issue within Google's standard +[90-day disclosure window](https://google.github.io/oss-fuzz/getting-started/bug-disclosure-guidelines/) +if a partial or delayed disclosure is important to protect users or the +function of the network. + +OSS-Fuzz also produces [a fuzzing coverage report](https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_bitcoin-core/latest). diff --git a/doc/guix.md b/doc/guix.md new file mode 100644 index 0000000000..fa9c74f486 --- /dev/null +++ b/doc/guix.md @@ -0,0 +1,3 @@ +# Bootstrappable Bitcoin Core Builds + +See [contrib/guix/README.md](../contrib/guix/README.md) diff --git a/doc/i2p.md b/doc/i2p.md new file mode 100644 index 0000000000..8b4607208a --- /dev/null +++ b/doc/i2p.md @@ -0,0 +1,72 @@ +# I2P support in Bitcoin Core + +It is possible to run Bitcoin Core as an +[I2P (Invisible Internet Project)](https://en.wikipedia.org/wiki/I2P) +service and connect to such services. + +This [glossary](https://geti2p.net/en/about/glossary) may be useful to get +started with I2P terminology. + +## Run Bitcoin Core with an I2P router (proxy) + +A running I2P router (proxy) with [SAM](https://geti2p.net/en/docs/api/samv3) +enabled is required (there is an [official one](https://geti2p.net) and +[a few alternatives](https://en.wikipedia.org/wiki/I2P#Routers)). Notice the IP +address and port the SAM proxy is listening to; usually, it is +`127.0.0.1:7656`. Once it is up and running with SAM enabled, use the following +Bitcoin Core options: + +``` +-i2psam=<ip:port> + I2P SAM proxy to reach I2P peers and accept I2P connections (default: + none) + +-i2pacceptincoming + If set and -i2psam is also set then incoming I2P connections are + accepted via the SAM proxy. If this is not set but -i2psam is set + then only outgoing connections will be made to the I2P network. + Ignored if -i2psam is not set. Listening for incoming I2P + connections is done through the SAM proxy, not by binding to a + local address and port (default: 1) +``` + +In a typical situation, this suffices: + +``` +bitcoind -i2psam=127.0.0.1:7656 +``` + +The first time Bitcoin Core connects to the I2P router, its I2P address (and +corresponding private key) will be automatically generated and saved in a file +named `i2p_private_key` in the Bitcoin Core data directory. + +## Additional configuration options related to I2P + +You may set the `debug=i2p` config logging option to have additional +information in the debug log about your I2P configuration and connections. Run +`bitcoin-cli help logging` for more information. + +It is possible to restrict outgoing connections in the usual way with +`onlynet=i2p`. I2P support was added to Bitcoin Core in version 22.0 (mid 2021) +and there may be fewer I2P peers than Tor or IP ones. Therefore, using +`onlynet=i2p` alone (without other `onlynet=`) may make a node more susceptible +to [Sybil attacks](https://en.bitcoin.it/wiki/Weaknesses#Sybil_attack). Use +`bitcoin-cli -addrinfo` to see the number of I2P addresses known to your node. + +## I2P related information in Bitcoin Core + +There are several ways to see your I2P address in Bitcoin Core: +- in the debug log (grep for `AddLocal`, the I2P address ends in `.b32.i2p`) +- in the output of the `getnetworkinfo` RPC in the "localaddresses" section +- in the output of `bitcoin-cli -netinfo` peer connections dashboard + +To see which I2P peers your node is connected to, use `bitcoin-cli -netinfo 4` +or the `getpeerinfo` RPC (e.g. `bitcoin-cli getpeerinfo`). + +To see which I2P addresses your node knows, use the `getnodeaddresses 0 i2p` +RPC. + +## Compatibility + +Bitcoin Core uses the [SAM v3.1](https://geti2p.net/en/docs/api/samv3) protocol +to connect to the I2P network. Any I2P router that supports it can be used. diff --git a/doc/init.md b/doc/init.md index 0b327aab58..399b819bf4 100644 --- a/doc/init.md +++ b/doc/init.md @@ -20,9 +20,9 @@ The macOS configuration assumes bitcoind will be set up for the current user. Configuration --------------------------------- -At a bare minimum, bitcoind requires that the rpcpassword setting be set -when running as a daemon. If the configuration file does not exist or this -setting is not set, bitcoind will shut down promptly after startup. +Running bitcoind as a daemon does not require any manual configuration. You may +set the `rpcauth` setting in the `bitcoin.conf` configuration file to override +the default behaviour of using a special cookie for authentication. This password does not have to be remembered or typed as it is mostly used as a fixed token that bitcoind and client programs read from the configuration @@ -53,11 +53,12 @@ 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` -PID file: `/var/run/bitcoind/bitcoind.pid` (OpenRC and Upstart) or `/run/bitcoind/bitcoind.pid` (systemd) -Lock file: `/var/lock/subsys/bitcoind` (CentOS) + 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) 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 @@ -83,10 +84,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 edbc0911a1..8f890da532 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -16,6 +16,10 @@ if BUILD_BITCOIN_TX dist_man1_MANS+=bitcoin-tx.1 endif +if BUILD_BITCOIN_UTIL + dist_man1_MANS+=bitcoin-util.1 +endif + if ENABLE_WALLET if BUILD_BITCOIN_WALLET dist_man1_MANS+=bitcoin-wallet.1 diff --git a/doc/man/bitcoin-cli.1 b/doc/man/bitcoin-cli.1 index 129651d8e9..6bcad7006b 100644 --- a/doc/man/bitcoin-cli.1 +++ b/doc/man/bitcoin-cli.1 @@ -1,115 +1,5 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-CLI "1" "February 2019" "bitcoin-cli v0.17.99.0" "User Commands" +.TH BITCOIN-CLI "1" .SH NAME -bitcoin-cli \- manual page for bitcoin-cli v0.17.99.0 -.SH SYNOPSIS -.B bitcoin-cli -[\fI\,options\/\fR] \fI\,<command> \/\fR[\fI\,params\/\fR] \fI\,Send command to Bitcoin Core\/\fR -.br -.B bitcoin-cli -[\fI\,options\/\fR] \fI\,-named <command> \/\fR[\fI\,name=value\/\fR]... \fI\,Send command to Bitcoin Core (with named arguments)\/\fR -.br -.B bitcoin-cli -[\fI\,options\/\fR] \fI\,help List commands\/\fR -.br -.B bitcoin-cli -[\fI\,options\/\fR] \fI\,help <command> Get help for a command\/\fR -.SH DESCRIPTION -Bitcoin Core RPC client version v0.17.99.0 -.SH OPTIONS -.HP -\-? -.IP -Print this help message and exit -.HP -\fB\-conf=\fR<file> -.IP -Specify configuration file. Relative paths will be prefixed by datadir -location. (default: bitcoin.conf) -.HP -\fB\-datadir=\fR<dir> -.IP -Specify data directory -.HP -\fB\-getinfo\fR -.IP -Get general information from the remote server. Note that unlike -server\-side RPC calls, the results of \fB\-getinfo\fR is the result of -multiple non\-atomic requests. Some entries in the result may -represent results from different states (e.g. wallet balance may -be as of a different block from the chain state reported) -.HP -\fB\-named\fR -.IP -Pass named instead of positional arguments (default: false) -.HP -\fB\-rpcclienttimeout=\fR<n> -.IP -Timeout in seconds during HTTP requests, or 0 for no timeout. (default: -900) -.HP -\fB\-rpcconnect=\fR<ip> -.IP -Send commands to node running on <ip> (default: 127.0.0.1) -.HP -\fB\-rpccookiefile=\fR<loc> -.IP -Location of the auth cookie. Relative paths will be prefixed by a -net\-specific datadir location. (default: data dir) -.HP -\fB\-rpcpassword=\fR<pw> -.IP -Password for JSON\-RPC connections -.HP -\fB\-rpcport=\fR<port> -.IP -Connect to JSON\-RPC on <port> (default: 8332, testnet: 18332, regtest: -18443) -.HP -\fB\-rpcuser=\fR<user> -.IP -Username for JSON\-RPC connections -.HP -\fB\-rpcwait\fR -.IP -Wait for RPC server to start -.HP -\fB\-rpcwallet=\fR<walletname> -.IP -Send RPC for non\-default wallet on RPC server (needs to exactly match -corresponding \fB\-wallet\fR option passed to bitcoind). This changes -the RPC endpoint used, e.g. -http://127.0.0.1:8332/wallet/<walletname> -.HP -\fB\-stdin\fR -.IP -Read extra arguments from standard input, one per line until EOF/Ctrl\-D -(recommended for sensitive information such as passphrases). When -combined with \fB\-stdinrpcpass\fR, the first line from standard input -is used for the RPC password. -.HP -\fB\-stdinrpcpass\fR -.IP -Read RPC password from standard input as a single line. When combined -with \fB\-stdin\fR, the first line from standard input is used for the -RPC password. -.HP -\fB\-version\fR -.IP -Print version and exit -.PP -Chain selection options: -.HP -\fB\-testnet\fR -.IP -Use the test chain -.SH COPYRIGHT -Copyright (C) 2009-2019 The Bitcoin Core developers +bitcoin-cli \- manual page for bitcoin-cli -Please contribute if you find Bitcoin Core useful. Visit -<https://bitcoincore.org> for further information about the software. -The source code is available from <https://github.com/bitcoin/bitcoin>. - -This is experimental software. -Distributed under the MIT software license, see the accompanying file COPYING -or <https://opensource.org/licenses/MIT> +This is a placeholder file. Please follow the instructions in \fIcontrib/devtools/README.md\fR to generate the manual pages after a release. diff --git a/doc/man/bitcoin-qt.1 b/doc/man/bitcoin-qt.1 index f68be21e8d..ff4d1d2c7a 100644 --- a/doc/man/bitcoin-qt.1 +++ b/doc/man/bitcoin-qt.1 @@ -1,610 +1,5 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-QT "1" "February 2019" "bitcoin-qt v0.17.99.0" "User Commands" +.TH BITCOIN-QT "1" .SH NAME -bitcoin-qt \- manual page for bitcoin-qt v0.17.99.0 -.SH SYNOPSIS -.B bitcoin-qt -[\fI\,command-line options\/\fR] -.SH DESCRIPTION -Bitcoin Core version v0.17.99.0 (64\-bit) -.SH OPTIONS -.HP -\-? -.IP -Print this help message and exit -.HP -\fB\-alertnotify=\fR<cmd> -.IP -Execute command when a relevant alert is received or we see a really -long fork (%s in cmd is replaced by message) -.HP -\fB\-assumevalid=\fR<hex> -.IP -If this block is in the chain assume that it and its ancestors are valid -and potentially skip their script verification (0 to verify all, -default: -0000000000000000002e63058c023a9a1de233554f28c7b21380b6c9003f36a8, -testnet: -0000000000000037a8cd3e06cd5edbfe9dd1dbcc5dacab279376ef7cfc2b4c75) -.HP -\fB\-blocknotify=\fR<cmd> -.IP -Execute command when the best block changes (%s in cmd is replaced by -block hash) -.HP -\fB\-blockreconstructionextratxn=\fR<n> -.IP -Extra transactions to keep in memory for compact block reconstructions -(default: 100) -.HP -\fB\-blocksdir=\fR<dir> -.IP -Specify blocks directory (default: <datadir>/blocks) -.HP -\fB\-conf=\fR<file> -.IP -Specify configuration file. Relative paths will be prefixed by datadir -location. (default: bitcoin.conf) -.HP -\fB\-daemon\fR -.IP -Run in the background as a daemon and accept commands -.HP -\fB\-datadir=\fR<dir> -.IP -Specify data directory -.HP -\fB\-dbcache=\fR<n> -.IP -Set database cache size in MiB (4 to 16384, default: 450) -.HP -\fB\-debuglogfile=\fR<file> -.IP -Specify location of debug log file. Relative paths will be prefixed by a -net\-specific datadir location. (\fB\-nodebuglogfile\fR to disable; -default: debug.log) -.HP -\fB\-includeconf=\fR<file> -.IP -Specify additional configuration file, relative to the \fB\-datadir\fR path -(only useable from configuration file, not command line) -.HP -\fB\-loadblock=\fR<file> -.IP -Imports blocks from external blk000??.dat file on startup -.HP -\fB\-maxmempool=\fR<n> -.IP -Keep the transaction memory pool below <n> megabytes (default: 300) -.HP -\fB\-maxorphantx=\fR<n> -.IP -Keep at most <n> unconnectable transactions in memory (default: 100) -.HP -\fB\-mempoolexpiry=\fR<n> -.IP -Do not keep transactions in the mempool longer than <n> hours (default: -336) -.HP -\fB\-par=\fR<n> -.IP -Set the number of script verification threads (\fB\-8\fR to 16, 0 = auto, <0 = -leave that many cores free, default: 0) -.HP -\fB\-persistmempool\fR -.IP -Whether to save the mempool on shutdown and load on restart (default: 1) -.HP -\fB\-pid=\fR<file> -.IP -Specify pid file. Relative paths will be prefixed by a net\-specific -datadir location. (default: bitcoind.pid) -.HP -\fB\-prune=\fR<n> -.IP -Reduce storage requirements by enabling pruning (deleting) of old -blocks. This allows the pruneblockchain RPC to be called to -delete specific blocks, and enables automatic pruning of old -blocks if a target size in MiB is provided. This mode is -incompatible with \fB\-txindex\fR and \fB\-rescan\fR. Warning: Reverting this -setting requires re\-downloading the entire blockchain. (default: -0 = disable pruning blocks, 1 = allow manual pruning via RPC, ->=550 = automatically prune block files to stay under the -specified target size in MiB) -.HP -\fB\-reindex\fR -.IP -Rebuild chain state and block index from the blk*.dat files on disk -.HP -\fB\-reindex\-chainstate\fR -.IP -Rebuild chain state from the currently indexed blocks. When in pruning -mode or if blocks on disk might be corrupted, use full \fB\-reindex\fR -instead. -.HP -\fB\-sysperms\fR -.IP -Create new files with system default permissions, instead of umask 077 -(only effective with disabled wallet functionality) -.HP -\fB\-txindex\fR -.IP -Maintain a full transaction index, used by the getrawtransaction rpc -call (default: 0) -.HP -\fB\-version\fR -.IP -Print version and exit -.PP -Connection options: -.HP -\fB\-addnode=\fR<ip> -.IP -Add a node to connect to and attempt to keep the connection open (see -the `addnode` RPC command help for more info). This option can be -specified multiple times to add multiple nodes. -.HP -\fB\-banscore=\fR<n> -.IP -Threshold for disconnecting misbehaving peers (default: 100) -.HP -\fB\-bantime=\fR<n> -.IP -Number of seconds to keep misbehaving peers from reconnecting (default: -86400) -.HP -\fB\-bind=\fR<addr> -.IP -Bind to given address and always listen on it. Use [host]:port notation -for IPv6 -.HP -\fB\-connect=\fR<ip> -.IP -Connect only to the specified node; \fB\-noconnect\fR disables automatic -connections (the rules for this peer are the same as for -\fB\-addnode\fR). This option can be specified multiple times to connect -to multiple nodes. -.HP -\fB\-discover\fR -.IP -Discover own IP addresses (default: 1 when listening and no \fB\-externalip\fR -or \fB\-proxy\fR) -.HP -\fB\-dns\fR -.IP -Allow DNS lookups for \fB\-addnode\fR, \fB\-seednode\fR and \fB\-connect\fR (default: 1) -.HP -\fB\-dnsseed\fR -.IP -Query for peer addresses via DNS lookup, if low on addresses (default: 1 -unless \fB\-connect\fR used) -.HP -\fB\-externalip=\fR<ip> -.IP -Specify your own public address -.HP -\fB\-forcednsseed\fR -.IP -Always query for peer addresses via DNS lookup (default: 0) -.HP -\fB\-listen\fR -.IP -Accept connections from outside (default: 1 if no \fB\-proxy\fR or \fB\-connect\fR) -.HP -\fB\-listenonion\fR -.IP -Automatically create Tor hidden service (default: 1) -.HP -\fB\-maxconnections=\fR<n> -.IP -Maintain at most <n> connections to peers (default: 125) -.HP -\fB\-maxreceivebuffer=\fR<n> -.IP -Maximum per\-connection receive buffer, <n>*1000 bytes (default: 5000) -.HP -\fB\-maxsendbuffer=\fR<n> -.IP -Maximum per\-connection send buffer, <n>*1000 bytes (default: 1000) -.HP -\fB\-maxtimeadjustment\fR -.IP -Maximum allowed median peer time offset adjustment. Local perspective of -time may be influenced by peers forward or backward by this -amount. (default: 4200 seconds) -.HP -\fB\-maxuploadtarget=\fR<n> -.IP -Tries to keep outbound traffic under the given target (in MiB per 24h), -0 = no limit (default: 0) -.HP -\fB\-onion=\fR<ip:port> -.IP -Use separate SOCKS5 proxy to reach peers via Tor hidden services, set -\fB\-noonion\fR to disable (default: \fB\-proxy\fR) -.HP -\fB\-onlynet=\fR<net> -.IP -Make outgoing connections only through network <net> (ipv4, ipv6 or -onion). Incoming connections are not affected by this option. -This option can be specified multiple times to allow multiple -networks. -.HP -\fB\-peerbloomfilters\fR -.IP -Support filtering of blocks and transaction with bloom filters (default: -1) -.HP -\fB\-permitbaremultisig\fR -.IP -Relay non\-P2SH multisig (default: 1) -.HP -\fB\-port=\fR<port> -.IP -Listen for connections on <port> (default: 8333, testnet: 18333, -regtest: 18444) -.HP -\fB\-proxy=\fR<ip:port> -.IP -Connect through SOCKS5 proxy, set \fB\-noproxy\fR to disable (default: -disabled) -.HP -\fB\-proxyrandomize\fR -.IP -Randomize credentials for every proxy connection. This enables Tor -stream isolation (default: 1) -.HP -\fB\-seednode=\fR<ip> -.IP -Connect to a node to retrieve peer addresses, and disconnect. This -option can be specified multiple times to connect to multiple -nodes. -.HP -\fB\-timeout=\fR<n> -.IP -Specify connection timeout in milliseconds (minimum: 1, default: 5000) -.HP -\fB\-torcontrol=\fR<ip>:<port> -.IP -Tor control port to use if onion listening enabled (default: -127.0.0.1:9051) -.HP -\fB\-torpassword=\fR<pass> -.IP -Tor control port password (default: empty) -.HP -\fB\-upnp\fR -.IP -Use UPnP to map the listening port (default: 0) -.HP -\fB\-whitebind=\fR<addr> -.IP -Bind to given address and whitelist peers connecting to it. Use -[host]:port notation for IPv6 -.HP -\fB\-whitelist=\fR<IP address or network> -.IP -Whitelist peers connecting from the given IP address (e.g. 1.2.3.4) or -CIDR notated network (e.g. 1.2.3.0/24). Can be specified multiple -times. Whitelisted peers cannot be DoS banned and their -transactions are always relayed, even if they are already in the -mempool, useful e.g. for a gateway -.PP -Wallet options: -.HP -\fB\-addresstype\fR -.IP -What type of addresses to use ("legacy", "p2sh\-segwit", or "bech32", -default: "p2sh\-segwit") -.HP -\fB\-avoidpartialspends\fR -.IP -Group outputs by address, selecting all or none, instead of selecting on -a per\-output basis. Privacy is improved as an address is only -used once (unless someone sends to it after spending from it), -but may result in slightly higher fees as suboptimal coin -selection may result due to the added limitation (default: 0) -.HP -\fB\-changetype\fR -.IP -What type of change to use ("legacy", "p2sh\-segwit", or "bech32"). -Default is same as \fB\-addresstype\fR, except when -\fB\-addresstype\fR=\fI\,p2sh\-segwit\/\fR a native segwit output is used when -sending to a native segwit address) -.HP -\fB\-disablewallet\fR -.IP -Do not load the wallet and disable wallet RPC calls -.HP -\fB\-discardfee=\fR<amt> -.IP -The fee rate (in BTC/kB) that indicates your tolerance for discarding -change by adding it to the fee (default: 0.0001). Note: An output -is discarded if it is dust at this rate, but we will always -discard up to the dust relay fee and a discard fee above that is -limited by the fee estimate for the longest target -.HP -\fB\-fallbackfee=\fR<amt> -.IP -A fee rate (in BTC/kB) that will be used when fee estimation has -insufficient data (default: 0.0002) -.HP -\fB\-keypool=\fR<n> -.IP -Set key pool size to <n> (default: 1000) -.HP -\fB\-mintxfee=\fR<amt> -.IP -Fees (in BTC/kB) smaller than this are considered zero fee for -transaction creation (default: 0.00001) -.HP -\fB\-paytxfee=\fR<amt> -.IP -Fee (in BTC/kB) to add to transactions you send (default: 0.00) -.HP -\fB\-rescan\fR -.IP -Rescan the block chain for missing wallet transactions on startup -.HP -\fB\-salvagewallet\fR -.IP -Attempt to recover private keys from a corrupt wallet on startup -.HP -\fB\-spendzeroconfchange\fR -.IP -Spend unconfirmed change when sending transactions (default: 1) -.HP -\fB\-txconfirmtarget=\fR<n> -.IP -If paytxfee is not set, include enough fee so transactions begin -confirmation on average within n blocks (default: 6) -.HP -\fB\-upgradewallet\fR -.IP -Upgrade wallet to latest format on startup -.HP -\fB\-wallet=\fR<path> -.IP -Specify wallet database path. Can be specified multiple times to load -multiple wallets. Path is interpreted relative to <walletdir> if -it is not absolute, and will be created if it does not exist (as -a directory containing a wallet.dat file and log files). For -backwards compatibility this will also accept names of existing -data files in <walletdir>.) -.HP -\fB\-walletbroadcast\fR -.IP -Make the wallet broadcast transactions (default: 1) -.HP -\fB\-walletdir=\fR<dir> -.IP -Specify directory to hold wallets (default: <datadir>/wallets if it -exists, otherwise <datadir>) -.HP -\fB\-walletnotify=\fR<cmd> -.IP -Execute command when a wallet transaction changes (%s in cmd is replaced -by TxID) -.HP -\fB\-walletrbf\fR -.IP -Send transactions with full\-RBF opt\-in enabled (RPC only, default: 0) -.HP -\fB\-zapwallettxes=\fR<mode> -.IP -Delete all wallet transactions and only recover those parts of the -blockchain through \fB\-rescan\fR on startup (1 = keep tx meta data e.g. -payment request information, 2 = drop tx meta data) -.PP -ZeroMQ notification options: -.HP -\fB\-zmqpubhashblock=\fR<address> -.IP -Enable publish hash block in <address> -.HP -\fB\-zmqpubhashtx=\fR<address> -.IP -Enable publish hash transaction in <address> -.HP -\fB\-zmqpubrawblock=\fR<address> -.IP -Enable publish raw block in <address> -.HP -\fB\-zmqpubrawtx=\fR<address> -.IP -Enable publish raw transaction in <address> -.PP -Debugging/Testing options: -.HP -\fB\-debug=\fR<category> -.IP -Output debugging information (default: \fB\-nodebug\fR, supplying <category> is -optional). If <category> is not supplied or if <category> = 1, -output all debugging information. <category> can be: net, tor, -mempool, http, bench, zmq, db, rpc, estimatefee, addrman, -selectcoins, reindex, cmpctblock, rand, prune, proxy, mempoolrej, -libevent, coindb, qt, leveldb. -.HP -\fB\-debugexclude=\fR<category> -.IP -Exclude debugging information for a category. Can be used in conjunction -with \fB\-debug\fR=\fI\,1\/\fR to output debug logs for all categories except one -or more specified categories. -.HP -\fB\-help\-debug\fR -.IP -Print help message with debugging options and exit -.HP -\fB\-logips\fR -.IP -Include IP addresses in debug output (default: 0) -.HP -\fB\-logtimestamps\fR -.IP -Prepend debug output with timestamp (default: 1) -.HP -\fB\-maxtxfee=\fR<amt> -.IP -Maximum total fees (in BTC) to use in a single wallet transaction or raw -transaction; setting this too low may abort large transactions -(default: 0.10) -.HP -\fB\-printtoconsole\fR -.IP -Send trace/debug info to console (default: 1 when no \fB\-daemon\fR. To disable -logging to file, set \fB\-nodebuglogfile\fR) -.HP -\fB\-shrinkdebugfile\fR -.IP -Shrink debug.log file on client startup (default: 1 when no \fB\-debug\fR) -.HP -\fB\-uacomment=\fR<cmt> -.IP -Append comment to the user agent string -.PP -Chain selection options: -.HP -\fB\-testnet\fR -.IP -Use the test chain -.PP -Node relay options: -.HP -\fB\-bytespersigop\fR -.IP -Equivalent bytes per sigop in transactions for relay and mining -(default: 20) -.HP -\fB\-datacarrier\fR -.IP -Relay and mine data carrier transactions (default: 1) -.HP -\fB\-datacarriersize\fR -.IP -Maximum size of data in data carrier transactions we relay and mine -(default: 83) -.HP -.HP -\fB\-minrelaytxfee=\fR<amt> -.IP -Fees (in BTC/kB) smaller than this are considered zero fee for relaying, -mining and transaction creation (default: 0.00001) -.HP -\fB\-whitelistforcerelay\fR -.IP -Force relay of transactions from whitelisted peers even if they violate -local relay policy (default: 0) -.HP -\fB\-whitelistrelay\fR -.IP -Accept relayed transactions received from whitelisted peers even when -not relaying transactions (default: 1) -.PP -Block creation options: -.HP -\fB\-blockmaxweight=\fR<n> -.IP -Set maximum BIP141 block weight (default: 3996000) -.HP -\fB\-blockmintxfee=\fR<amt> -.IP -Set lowest fee rate (in BTC/kB) for transactions to be included in block -creation. (default: 0.00001) -.PP -RPC server options: -.HP -\fB\-rest\fR -.IP -Accept public REST requests (default: 0) -.HP -\fB\-rpcallowip=\fR<ip> -.IP -Allow JSON\-RPC connections from specified source. Valid for <ip> are a -single IP (e.g. 1.2.3.4), a network/netmask (e.g. -1.2.3.4/255.255.255.0) or a network/CIDR (e.g. 1.2.3.4/24). This -option can be specified multiple times -.HP -\fB\-rpcauth=\fR<userpw> -.IP -Username and HMAC\-SHA\-256 hashed password for JSON\-RPC connections. The -field <userpw> comes in the format: <USERNAME>:<SALT>$<HASH>. A -canonical python script is included in share/rpcauth. The client -then connects normally using the -rpcuser=<USERNAME>/rpcpassword=<PASSWORD> pair of arguments. This -option can be specified multiple times -.HP -\fB\-rpcbind=\fR<addr>[:port] -.IP -Bind to given address to listen for JSON\-RPC connections. Do not expose -the RPC server to untrusted networks such as the public internet! -This option is ignored unless \fB\-rpcallowip\fR is also passed. Port is -optional and overrides \fB\-rpcport\fR. Use [host]:port notation for -IPv6. This option can be specified multiple times (default: -127.0.0.1 and ::1 i.e., localhost) -.HP -\fB\-rpccookiefile=\fR<loc> -.IP -Location of the auth cookie. Relative paths will be prefixed by a -net\-specific datadir location. (default: data dir) -.HP -\fB\-rpcpassword=\fR<pw> -.IP -Password for JSON\-RPC connections -.HP -\fB\-rpcport=\fR<port> -.IP -Listen for JSON\-RPC connections on <port> (default: 8332, testnet: -18332, regtest: 18443) -.HP -\fB\-rpcserialversion\fR -.IP -Sets the serialization of raw transaction or block hex returned in -non\-verbose mode, non\-segwit(0) or segwit(1) (default: 1) -.HP -\fB\-rpcthreads=\fR<n> -.IP -Set the number of threads to service RPC calls (default: 4) -.HP -\fB\-rpcuser=\fR<user> -.IP -Username for JSON\-RPC connections -.HP -\fB\-server\fR -.IP -Accept command line and JSON\-RPC commands -.PP -UI Options: -.HP -\fB\-choosedatadir\fR -.IP -Choose data directory on startup (default: 0) -.HP -\fB\-lang=\fR<lang> -.IP -Set language, for example "de_DE" (default: system locale) -.HP -\fB\-min\fR -.IP -Start minimized -.HP -\fB\-resetguisettings\fR -.IP -Reset all settings changed in the GUI -.HP -\fB\-rootcertificates=\fR<file> -.IP -Set SSL root certificates for payment request (default: \fB\-system\-\fR) -.HP -\fB\-splash\fR -.IP -Show splash screen on startup (default: 1) -.SH COPYRIGHT -Copyright (C) 2009-2019 The Bitcoin Core developers +bitcoin-qt \- manual page for bitcoin-qt -Please contribute if you find Bitcoin Core useful. Visit -<https://bitcoincore.org> for further information about the software. -The source code is available from <https://github.com/bitcoin/bitcoin>. - -This is experimental software. -Distributed under the MIT software license, see the accompanying file COPYING -or <https://opensource.org/licenses/MIT> +This is a placeholder file. Please follow the instructions in \fIcontrib/devtools/README.md\fR to generate the manual pages after a release. diff --git a/doc/man/bitcoin-tx.1 b/doc/man/bitcoin-tx.1 index b4c7698896..776bb46234 100644 --- a/doc/man/bitcoin-tx.1 +++ b/doc/man/bitcoin-tx.1 @@ -1,116 +1,5 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-TX "1" "February 2019" "bitcoin-tx v0.17.99.0" "User Commands" +.TH BITCOIN-TX "1" .SH NAME -bitcoin-tx \- manual page for bitcoin-tx v0.17.99.0 -.SH SYNOPSIS -.B bitcoin-tx -[\fI\,options\/\fR] \fI\,<hex-tx> \/\fR[\fI\,commands\/\fR] \fI\,Update hex-encoded bitcoin transaction\/\fR -.br -.B bitcoin-tx -[\fI\,options\/\fR] \fI\,-create \/\fR[\fI\,commands\/\fR] \fI\,Create hex-encoded bitcoin transaction\/\fR -.SH DESCRIPTION -Bitcoin Core bitcoin\-tx utility version v0.17.99.0 -.SH OPTIONS -.HP -\-? -.IP -Print this help message and exit -.HP -\fB\-create\fR -.IP -Create new, empty TX. -.HP -\fB\-json\fR -.IP -Select JSON output -.HP -\fB\-txid\fR -.IP -Output only the hex\-encoded transaction id of the resultant transaction. -.PP -Chain selection options: -.HP -\fB\-testnet\fR -.IP -Use the test chain -.PP -Commands: -.IP -delin=N -.IP -Delete input N from TX -.IP -delout=N -.IP -Delete output N from TX -.IP -in=TXID:VOUT(:SEQUENCE_NUMBER) -.IP -Add input to TX -.IP -locktime=N -.IP -Set TX lock time to N -.IP -nversion=N -.IP -Set TX version to N -.IP -outaddr=VALUE:ADDRESS -.IP -Add address\-based output to TX -.IP -outdata=[VALUE:]DATA -.IP -Add data\-based output to TX -.IP -outmultisig=VALUE:REQUIRED:PUBKEYS:PUBKEY1:PUBKEY2:....[:FLAGS] -.IP -Add Pay To n\-of\-m Multi\-sig output to TX. n = REQUIRED, m = PUBKEYS. -Optionally add the "W" flag to produce a -pay\-to\-witness\-script\-hash output. Optionally add the "S" flag to -wrap the output in a pay\-to\-script\-hash. -.IP -outpubkey=VALUE:PUBKEY[:FLAGS] -.IP -Add pay\-to\-pubkey output to TX. Optionally add the "W" flag to produce a -pay\-to\-witness\-pubkey\-hash output. Optionally add the "S" flag to -wrap the output in a pay\-to\-script\-hash. -.IP -outscript=VALUE:SCRIPT[:FLAGS] -.IP -Add raw script output to TX. Optionally add the "W" flag to produce a -pay\-to\-witness\-script\-hash output. Optionally add the "S" flag to -wrap the output in a pay\-to\-script\-hash. -.IP -replaceable(=N) -.IP -Set RBF opt\-in sequence number for input N (if not provided, opt\-in all -available inputs) -.IP -sign=SIGHASH\-FLAGS -.IP -Add zero or more signatures to transaction. This command requires JSON -registers:prevtxs=JSON object, privatekeys=JSON object. See -signrawtransactionwithkey docs for format of sighash flags, JSON -objects. -.PP -Register Commands: -.IP -load=NAME:FILENAME -.IP -Load JSON file FILENAME into register NAME -.IP -set=NAME:JSON\-STRING -.IP -Set register NAME to given JSON\-STRING -.SH COPYRIGHT -Copyright (C) 2009-2019 The Bitcoin Core developers +bitcoin-tx \- manual page for bitcoin-tx -Please contribute if you find Bitcoin Core useful. Visit -<https://bitcoincore.org> for further information about the software. -The source code is available from <https://github.com/bitcoin/bitcoin>. - -This is experimental software. -Distributed under the MIT software license, see the accompanying file COPYING -or <https://opensource.org/licenses/MIT> +This is a placeholder file. Please follow the instructions in \fIcontrib/devtools/README.md\fR to generate the manual pages after a release. diff --git a/doc/man/bitcoin-util.1 b/doc/man/bitcoin-util.1 new file mode 100644 index 0000000000..5c733c6e21 --- /dev/null +++ b/doc/man/bitcoin-util.1 @@ -0,0 +1,5 @@ +.TH BITCOIN-UTIL "1" +.SH NAME +bitcoin-util \- manual page for bitcoin-util + +This is a placeholder file. Please follow the instructions in \fIcontrib/devtools/README.md\fR to generate the manual pages after a release. diff --git a/doc/man/bitcoin-wallet.1 b/doc/man/bitcoin-wallet.1 index aadea09a2b..2da43dec66 100644 --- a/doc/man/bitcoin-wallet.1 +++ b/doc/man/bitcoin-wallet.1 @@ -1,63 +1,5 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-WALLET "1" "February 2019" "bitcoin-wallet v0.17.99.0" "User Commands" +.TH BITCOIN-WALLET "1" .SH NAME -bitcoin-wallet \- manual page for bitcoin-wallet v0.17.99.0 -.SH DESCRIPTION -Bitcoin Core bitcoin\-wallet version v0.17.99.0 -.PP -wallet\-tool is an offline tool for creating and interacting with Bitcoin Core wallet files. -By default wallet\-tool will act on wallets in the default mainnet wallet directory in the datadir. -To change the target wallet, use the \fB\-datadir\fR, \fB\-wallet\fR and \fB\-testnet\fR/\-regtest arguments. -.SS "Usage:" -.IP -bitcoin\-wallet [options] <command> -.SH OPTIONS -.HP -\-? -.IP -Print this help message and exit -.HP -\fB\-datadir=\fR<dir> -.IP -Specify data directory -.HP -\fB\-wallet=\fR<wallet\-name> -.IP -Specify wallet name -.PP -Debugging/Testing options: -.HP -\fB\-debug=\fR<category> -.IP -Output debugging information (default: 0). -.HP -\fB\-printtoconsole\fR -.IP -Send trace/debug info to console (default: 1 when no \fB\-debug\fR is true, 0 -otherwise. -.PP -Chain selection options: -.HP -\fB\-testnet\fR -.IP -Use the test chain -.PP -Commands: -.IP -create -.IP -Create new wallet file -.IP -info -.IP -Get wallet info -.SH COPYRIGHT -Copyright (C) 2009-2019 The Bitcoin Core developers +bitcoin-wallet \- manual page for bitcoin-wallet -Please contribute if you find Bitcoin Core useful. Visit -<https://bitcoincore.org> for further information about the software. -The source code is available from <https://github.com/bitcoin/bitcoin>. - -This is experimental software. -Distributed under the MIT software license, see the accompanying file COPYING -or <https://opensource.org/licenses/MIT> +This is a placeholder file. Please follow the instructions in \fIcontrib/devtools/README.md\fR to generate the manual pages after a release. diff --git a/doc/man/bitcoind.1 b/doc/man/bitcoind.1 index 211ba10285..2c88f74520 100644 --- a/doc/man/bitcoind.1 +++ b/doc/man/bitcoind.1 @@ -1,583 +1,5 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIND "1" "February 2019" "bitcoind v0.17.99.0" "User Commands" +.TH BITCOIND "1" .SH NAME -bitcoind \- manual page for bitcoind v0.17.99.0 -.SH SYNOPSIS -.B bitcoind -[\fI\,options\/\fR] \fI\,Start Bitcoin Core Daemon\/\fR -.SH DESCRIPTION -Bitcoin Core Daemon version v0.17.99.0 -.SH OPTIONS -.HP -\-? -.IP -Print this help message and exit -.HP -\fB\-alertnotify=\fR<cmd> -.IP -Execute command when a relevant alert is received or we see a really -long fork (%s in cmd is replaced by message) -.HP -\fB\-assumevalid=\fR<hex> -.IP -If this block is in the chain assume that it and its ancestors are valid -and potentially skip their script verification (0 to verify all, -default: -0000000000000000002e63058c023a9a1de233554f28c7b21380b6c9003f36a8, -testnet: -0000000000000037a8cd3e06cd5edbfe9dd1dbcc5dacab279376ef7cfc2b4c75) -.HP -\fB\-blocknotify=\fR<cmd> -.IP -Execute command when the best block changes (%s in cmd is replaced by -block hash) -.HP -\fB\-blockreconstructionextratxn=\fR<n> -.IP -Extra transactions to keep in memory for compact block reconstructions -(default: 100) -.HP -\fB\-blocksdir=\fR<dir> -.IP -Specify blocks directory (default: <datadir>/blocks) -.HP -\fB\-conf=\fR<file> -.IP -Specify configuration file. Relative paths will be prefixed by datadir -location. (default: bitcoin.conf) -.HP -\fB\-daemon\fR -.IP -Run in the background as a daemon and accept commands -.HP -\fB\-datadir=\fR<dir> -.IP -Specify data directory -.HP -\fB\-dbcache=\fR<n> -.IP -Set database cache size in MiB (4 to 16384, default: 450) -.HP -\fB\-debuglogfile=\fR<file> -.IP -Specify location of debug log file. Relative paths will be prefixed by a -net\-specific datadir location. (\fB\-nodebuglogfile\fR to disable; -default: debug.log) -.HP -\fB\-includeconf=\fR<file> -.IP -Specify additional configuration file, relative to the \fB\-datadir\fR path -(only useable from configuration file, not command line) -.HP -\fB\-loadblock=\fR<file> -.IP -Imports blocks from external blk000??.dat file on startup -.HP -\fB\-maxmempool=\fR<n> -.IP -Keep the transaction memory pool below <n> megabytes (default: 300) -.HP -\fB\-maxorphantx=\fR<n> -.IP -Keep at most <n> unconnectable transactions in memory (default: 100) -.HP -\fB\-mempoolexpiry=\fR<n> -.IP -Do not keep transactions in the mempool longer than <n> hours (default: -336) -.HP -\fB\-par=\fR<n> -.IP -Set the number of script verification threads (\fB\-8\fR to 16, 0 = auto, <0 = -leave that many cores free, default: 0) -.HP -\fB\-persistmempool\fR -.IP -Whether to save the mempool on shutdown and load on restart (default: 1) -.HP -\fB\-pid=\fR<file> -.IP -Specify pid file. Relative paths will be prefixed by a net\-specific -datadir location. (default: bitcoind.pid) -.HP -\fB\-prune=\fR<n> -.IP -Reduce storage requirements by enabling pruning (deleting) of old -blocks. This allows the pruneblockchain RPC to be called to -delete specific blocks, and enables automatic pruning of old -blocks if a target size in MiB is provided. This mode is -incompatible with \fB\-txindex\fR and \fB\-rescan\fR. Warning: Reverting this -setting requires re\-downloading the entire blockchain. (default: -0 = disable pruning blocks, 1 = allow manual pruning via RPC, ->=550 = automatically prune block files to stay under the -specified target size in MiB) -.HP -\fB\-reindex\fR -.IP -Rebuild chain state and block index from the blk*.dat files on disk -.HP -\fB\-reindex\-chainstate\fR -.IP -Rebuild chain state from the currently indexed blocks. When in pruning -mode or if blocks on disk might be corrupted, use full \fB\-reindex\fR -instead. -.HP -\fB\-sysperms\fR -.IP -Create new files with system default permissions, instead of umask 077 -(only effective with disabled wallet functionality) -.HP -\fB\-txindex\fR -.IP -Maintain a full transaction index, used by the getrawtransaction rpc -call (default: 0) -.HP -\fB\-version\fR -.IP -Print version and exit -.PP -Connection options: -.HP -\fB\-addnode=\fR<ip> -.IP -Add a node to connect to and attempt to keep the connection open (see -the `addnode` RPC command help for more info). This option can be -specified multiple times to add multiple nodes. -.HP -\fB\-banscore=\fR<n> -.IP -Threshold for disconnecting misbehaving peers (default: 100) -.HP -\fB\-bantime=\fR<n> -.IP -Number of seconds to keep misbehaving peers from reconnecting (default: -86400) -.HP -\fB\-bind=\fR<addr> -.IP -Bind to given address and always listen on it. Use [host]:port notation -for IPv6 -.HP -\fB\-connect=\fR<ip> -.IP -Connect only to the specified node; \fB\-noconnect\fR disables automatic -connections (the rules for this peer are the same as for -\fB\-addnode\fR). This option can be specified multiple times to connect -to multiple nodes. -.HP -\fB\-discover\fR -.IP -Discover own IP addresses (default: 1 when listening and no \fB\-externalip\fR -or \fB\-proxy\fR) -.HP -\fB\-dns\fR -.IP -Allow DNS lookups for \fB\-addnode\fR, \fB\-seednode\fR and \fB\-connect\fR (default: 1) -.HP -\fB\-dnsseed\fR -.IP -Query for peer addresses via DNS lookup, if low on addresses (default: 1 -unless \fB\-connect\fR used) -.HP -\fB\-externalip=\fR<ip> -.IP -Specify your own public address -.HP -\fB\-forcednsseed\fR -.IP -Always query for peer addresses via DNS lookup (default: 0) -.HP -\fB\-listen\fR -.IP -Accept connections from outside (default: 1 if no \fB\-proxy\fR or \fB\-connect\fR) -.HP -\fB\-listenonion\fR -.IP -Automatically create Tor hidden service (default: 1) -.HP -\fB\-maxconnections=\fR<n> -.IP -Maintain at most <n> connections to peers (default: 125) -.HP -\fB\-maxreceivebuffer=\fR<n> -.IP -Maximum per\-connection receive buffer, <n>*1000 bytes (default: 5000) -.HP -\fB\-maxsendbuffer=\fR<n> -.IP -Maximum per\-connection send buffer, <n>*1000 bytes (default: 1000) -.HP -\fB\-maxtimeadjustment\fR -.IP -Maximum allowed median peer time offset adjustment. Local perspective of -time may be influenced by peers forward or backward by this -amount. (default: 4200 seconds) -.HP -\fB\-maxuploadtarget=\fR<n> -.IP -Tries to keep outbound traffic under the given target (in MiB per 24h), -0 = no limit (default: 0) -.HP -\fB\-onion=\fR<ip:port> -.IP -Use separate SOCKS5 proxy to reach peers via Tor hidden services, set -\fB\-noonion\fR to disable (default: \fB\-proxy\fR) -.HP -\fB\-onlynet=\fR<net> -.IP -Make outgoing connections only through network <net> (ipv4, ipv6 or -onion). Incoming connections are not affected by this option. -This option can be specified multiple times to allow multiple -networks. -.HP -\fB\-peerbloomfilters\fR -.IP -Support filtering of blocks and transaction with bloom filters (default: -1) -.HP -\fB\-permitbaremultisig\fR -.IP -Relay non\-P2SH multisig (default: 1) -.HP -\fB\-port=\fR<port> -.IP -Listen for connections on <port> (default: 8333, testnet: 18333, -regtest: 18444) -.HP -\fB\-proxy=\fR<ip:port> -.IP -Connect through SOCKS5 proxy, set \fB\-noproxy\fR to disable (default: -disabled) -.HP -\fB\-proxyrandomize\fR -.IP -Randomize credentials for every proxy connection. This enables Tor -stream isolation (default: 1) -.HP -\fB\-seednode=\fR<ip> -.IP -Connect to a node to retrieve peer addresses, and disconnect. This -option can be specified multiple times to connect to multiple -nodes. -.HP -\fB\-timeout=\fR<n> -.IP -Specify connection timeout in milliseconds (minimum: 1, default: 5000) -.HP -\fB\-torcontrol=\fR<ip>:<port> -.IP -Tor control port to use if onion listening enabled (default: -127.0.0.1:9051) -.HP -\fB\-torpassword=\fR<pass> -.IP -Tor control port password (default: empty) -.HP -\fB\-upnp\fR -.IP -Use UPnP to map the listening port (default: 0) -.HP -\fB\-whitebind=\fR<addr> -.IP -Bind to given address and whitelist peers connecting to it. Use -[host]:port notation for IPv6 -.HP -\fB\-whitelist=\fR<IP address or network> -.IP -Whitelist peers connecting from the given IP address (e.g. 1.2.3.4) or -CIDR notated network (e.g. 1.2.3.0/24). Can be specified multiple -times. Whitelisted peers cannot be DoS banned and their -transactions are always relayed, even if they are already in the -mempool, useful e.g. for a gateway -.PP -Wallet options: -.HP -\fB\-addresstype\fR -.IP -What type of addresses to use ("legacy", "p2sh\-segwit", or "bech32", -default: "p2sh\-segwit") -.HP -\fB\-avoidpartialspends\fR -.IP -Group outputs by address, selecting all or none, instead of selecting on -a per\-output basis. Privacy is improved as an address is only -used once (unless someone sends to it after spending from it), -but may result in slightly higher fees as suboptimal coin -selection may result due to the added limitation (default: 0) -.HP -\fB\-changetype\fR -.IP -What type of change to use ("legacy", "p2sh\-segwit", or "bech32"). -Default is same as \fB\-addresstype\fR, except when -\fB\-addresstype\fR=\fI\,p2sh\-segwit\/\fR a native segwit output is used when -sending to a native segwit address) -.HP -\fB\-disablewallet\fR -.IP -Do not load the wallet and disable wallet RPC calls -.HP -\fB\-discardfee=\fR<amt> -.IP -The fee rate (in BTC/kB) that indicates your tolerance for discarding -change by adding it to the fee (default: 0.0001). Note: An output -is discarded if it is dust at this rate, but we will always -discard up to the dust relay fee and a discard fee above that is -limited by the fee estimate for the longest target -.HP -\fB\-fallbackfee=\fR<amt> -.IP -A fee rate (in BTC/kB) that will be used when fee estimation has -insufficient data (default: 0.0002) -.HP -\fB\-keypool=\fR<n> -.IP -Set key pool size to <n> (default: 1000) -.HP -\fB\-mintxfee=\fR<amt> -.IP -Fees (in BTC/kB) smaller than this are considered zero fee for -transaction creation (default: 0.00001) -.HP -\fB\-paytxfee=\fR<amt> -.IP -Fee (in BTC/kB) to add to transactions you send (default: 0.00) -.HP -\fB\-rescan\fR -.IP -Rescan the block chain for missing wallet transactions on startup -.HP -\fB\-salvagewallet\fR -.IP -Attempt to recover private keys from a corrupt wallet on startup -.HP -\fB\-spendzeroconfchange\fR -.IP -Spend unconfirmed change when sending transactions (default: 1) -.HP -\fB\-txconfirmtarget=\fR<n> -.IP -If paytxfee is not set, include enough fee so transactions begin -confirmation on average within n blocks (default: 6) -.HP -\fB\-upgradewallet\fR -.IP -Upgrade wallet to latest format on startup -.HP -\fB\-wallet=\fR<path> -.IP -Specify wallet database path. Can be specified multiple times to load -multiple wallets. Path is interpreted relative to <walletdir> if -it is not absolute, and will be created if it does not exist (as -a directory containing a wallet.dat file and log files). For -backwards compatibility this will also accept names of existing -data files in <walletdir>.) -.HP -\fB\-walletbroadcast\fR -.IP -Make the wallet broadcast transactions (default: 1) -.HP -\fB\-walletdir=\fR<dir> -.IP -Specify directory to hold wallets (default: <datadir>/wallets if it -exists, otherwise <datadir>) -.HP -\fB\-walletnotify=\fR<cmd> -.IP -Execute command when a wallet transaction changes (%s in cmd is replaced -by TxID) -.HP -\fB\-walletrbf\fR -.IP -Send transactions with full\-RBF opt\-in enabled (RPC only, default: 0) -.HP -\fB\-zapwallettxes=\fR<mode> -.IP -Delete all wallet transactions and only recover those parts of the -blockchain through \fB\-rescan\fR on startup (1 = keep tx meta data e.g. -payment request information, 2 = drop tx meta data) -.PP -ZeroMQ notification options: -.HP -\fB\-zmqpubhashblock=\fR<address> -.IP -Enable publish hash block in <address> -.HP -\fB\-zmqpubhashtx=\fR<address> -.IP -Enable publish hash transaction in <address> -.HP -\fB\-zmqpubrawblock=\fR<address> -.IP -Enable publish raw block in <address> -.HP -\fB\-zmqpubrawtx=\fR<address> -.IP -Enable publish raw transaction in <address> -.PP -Debugging/Testing options: -.HP -\fB\-debug=\fR<category> -.IP -Output debugging information (default: \fB\-nodebug\fR, supplying <category> is -optional). If <category> is not supplied or if <category> = 1, -output all debugging information. <category> can be: net, tor, -mempool, http, bench, zmq, db, rpc, estimatefee, addrman, -selectcoins, reindex, cmpctblock, rand, prune, proxy, mempoolrej, -libevent, coindb, qt, leveldb. -.HP -\fB\-debugexclude=\fR<category> -.IP -Exclude debugging information for a category. Can be used in conjunction -with \fB\-debug\fR=\fI\,1\/\fR to output debug logs for all categories except one -or more specified categories. -.HP -\fB\-help\-debug\fR -.IP -Print help message with debugging options and exit -.HP -\fB\-logips\fR -.IP -Include IP addresses in debug output (default: 0) -.HP -\fB\-logtimestamps\fR -.IP -Prepend debug output with timestamp (default: 1) -.HP -\fB\-maxtxfee=\fR<amt> -.IP -Maximum total fees (in BTC) to use in a single wallet transaction or raw -transaction; setting this too low may abort large transactions -(default: 0.10) -.HP -\fB\-printtoconsole\fR -.IP -Send trace/debug info to console (default: 1 when no \fB\-daemon\fR. To disable -logging to file, set \fB\-nodebuglogfile\fR) -.HP -\fB\-shrinkdebugfile\fR -.IP -Shrink debug.log file on client startup (default: 1 when no \fB\-debug\fR) -.HP -\fB\-uacomment=\fR<cmt> -.IP -Append comment to the user agent string -.PP -Chain selection options: -.HP -\fB\-testnet\fR -.IP -Use the test chain -.PP -Node relay options: -.HP -\fB\-bytespersigop\fR -.IP -Equivalent bytes per sigop in transactions for relay and mining -(default: 20) -.HP -\fB\-datacarrier\fR -.IP -Relay and mine data carrier transactions (default: 1) -.HP -\fB\-datacarriersize\fR -.IP -Maximum size of data in data carrier transactions we relay and mine -(default: 83) -.HP -\fB\-minrelaytxfee=\fR<amt> -.IP -Fees (in BTC/kB) smaller than this are considered zero fee for relaying, -mining and transaction creation (default: 0.00001) -.HP -\fB\-whitelistforcerelay\fR -.IP -Force relay of transactions from whitelisted peers even if they violate -local relay policy (default: 0) -.HP -\fB\-whitelistrelay\fR -.IP -Accept relayed transactions received from whitelisted peers even when -not relaying transactions (default: 1) -.PP -Block creation options: -.HP -\fB\-blockmaxweight=\fR<n> -.IP -Set maximum BIP141 block weight (default: 3996000) -.HP -\fB\-blockmintxfee=\fR<amt> -.IP -Set lowest fee rate (in BTC/kB) for transactions to be included in block -creation. (default: 0.00001) -.PP -RPC server options: -.HP -\fB\-rest\fR -.IP -Accept public REST requests (default: 0) -.HP -\fB\-rpcallowip=\fR<ip> -.IP -Allow JSON\-RPC connections from specified source. Valid for <ip> are a -single IP (e.g. 1.2.3.4), a network/netmask (e.g. -1.2.3.4/255.255.255.0) or a network/CIDR (e.g. 1.2.3.4/24). This -option can be specified multiple times -.HP -\fB\-rpcauth=\fR<userpw> -.IP -Username and HMAC\-SHA\-256 hashed password for JSON\-RPC connections. The -field <userpw> comes in the format: <USERNAME>:<SALT>$<HASH>. A -canonical python script is included in share/rpcauth. The client -then connects normally using the -rpcuser=<USERNAME>/rpcpassword=<PASSWORD> pair of arguments. This -option can be specified multiple times -.HP -\fB\-rpcbind=\fR<addr>[:port] -.IP -Bind to given address to listen for JSON\-RPC connections. Do not expose -the RPC server to untrusted networks such as the public internet! -This option is ignored unless \fB\-rpcallowip\fR is also passed. Port is -optional and overrides \fB\-rpcport\fR. Use [host]:port notation for -IPv6. This option can be specified multiple times (default: -127.0.0.1 and ::1 i.e., localhost) -.HP -\fB\-rpccookiefile=\fR<loc> -.IP -Location of the auth cookie. Relative paths will be prefixed by a -net\-specific datadir location. (default: data dir) -.HP -\fB\-rpcpassword=\fR<pw> -.IP -Password for JSON\-RPC connections -.HP -\fB\-rpcport=\fR<port> -.IP -Listen for JSON\-RPC connections on <port> (default: 8332, testnet: -18332, regtest: 18443) -.HP -\fB\-rpcserialversion\fR -.IP -Sets the serialization of raw transaction or block hex returned in -non\-verbose mode, non\-segwit(0) or segwit(1) (default: 1) -.HP -\fB\-rpcthreads=\fR<n> -.IP -Set the number of threads to service RPC calls (default: 4) -.HP -\fB\-rpcuser=\fR<user> -.IP -Username for JSON\-RPC connections -.HP -\fB\-server\fR -.IP -Accept command line and JSON\-RPC commands -.SH COPYRIGHT -Copyright (C) 2009-2019 The Bitcoin Core developers +bitcoind \- manual page for bitcoind -Please contribute if you find Bitcoin Core useful. Visit -<https://bitcoincore.org> for further information about the software. -The source code is available from <https://github.com/bitcoin/bitcoin>. - -This is experimental software. -Distributed under the MIT software license, see the accompanying file COPYING -or <https://opensource.org/licenses/MIT> +This is a placeholder file. Please follow the instructions in \fIcontrib/devtools/README.md\fR to generate the manual pages after a release. diff --git a/doc/multiprocess.md b/doc/multiprocess.md new file mode 100644 index 0000000000..e3f389a6d3 --- /dev/null +++ b/doc/multiprocess.md @@ -0,0 +1,72 @@ +# Multiprocess Bitcoin + +On unix systems, the `--enable-multiprocess` build option can be passed to `./configure` to build new `bitcoin-node`, `bitcoin-wallet`, and `bitcoin-gui` executables alongside existing `bitcoind` and `bitcoin-qt` executables. + +`bitcoin-node` is a drop-in replacement for `bitcoind`, and `bitcoin-gui` is a drop-in replacement for `bitcoin-qt`, and there are no differences in use or external behavior between the new and old executables. But internally (after [#10102](https://github.com/bitcoin/bitcoin/pull/10102)), `bitcoin-gui` will spawn a `bitcoin-node` process to run P2P and RPC code, communicating with it across a socket pair, and `bitcoin-node` will spawn `bitcoin-wallet` to run wallet code, also communicating over a socket pair. This will let node, wallet, and GUI code run in separate address spaces for better isolation, and allow future improvements like being able to start and stop components independently on different machines and environments. + +## Next steps + +Specific next steps after [#10102](https://github.com/bitcoin/bitcoin/pull/10102) will be: + +- [ ] Adding `-ipcbind` and `-ipcconnect` options to `bitcoin-node`, `bitcoin-wallet`, and `bitcoin-gui` executables so they can listen and connect to TCP ports and unix socket paths. This will allow separate processes to be started and stopped any time and connect to each other. +- [ ] Adding `-server` and `-rpcbind` options to the `bitcoin-wallet` executable so wallet processes can handle RPC requests directly without going through the node. +- [ ] Supporting windows, not just unix systems. The existing socket code is already cross-platform, so the only windows-specific code that needs to be written is code spawning a process and passing a socket descriptor. This can be implemented with `CreateProcess` and `WSADuplicateSocket`. Example: https://memset.wordpress.com/2010/10/13/win32-api-passing-socket-with-ipc-method/. +- [ ] Adding sandbox features, restricting subprocess access to resources and data. See [https://eklitzke.org/multiprocess-bitcoin](https://eklitzke.org/multiprocess-bitcoin). + +## Debugging + +The `-debug=ipc` command line option can be used to see requests and responses between processes. + +## Installation + +The multiprocess feature requires [Cap'n Proto](https://capnproto.org/) and [libmultiprocess](https://github.com/chaincodelabs/libmultiprocess) as dependencies. A simple way to get starting using it without installing these dependencies manually is to use the [depends system](../depends) with the `MULTIPROCESS=1` [dependency option](../depends#dependency-options) passed to make: + +``` +cd <BITCOIN_SOURCE_DIRECTORY> +make -C depends NO_QT=1 MULTIPROCESS=1 +CONFIG_SITE=$PWD/depends/x86_64-pc-linux-gnu/share/config.site ./configure +make +src/bitcoin-node -regtest -printtoconsole -debug=ipc +BITCOIND=bitcoin-node test/functional/test_runner.py +``` + +The configure script will pick up settings and library locations from the depends directory, so there is no need to pass `--enable-multiprocess` as a separate flag when using the depends system (it's controlled by the `MULTIPROCESS=1` option). + +Alternately, you can install [Cap'n Proto](https://capnproto.org/) and [libmultiprocess](https://github.com/chaincodelabs/libmultiprocess) packages on your system, and just run `./configure --enable-multiprocess` without using the depends system. The configure script will be able to locate the installed packages via [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/). See [Installation](https://github.com/chaincodelabs/libmultiprocess#installation) section of the libmultiprocess readme for install steps. See [build-unix.md](build-unix.md) and [build-osx.md](build-osx.md) for information about installing dependencies in general. + +## IPC implementation details + +Cross process Node, Wallet, and Chain interfaces are defined in +[`src/interfaces/`](../src/interfaces/). These are C++ classes which follow +[conventions](developer-notes.md#internal-interface-guidelines), like passing +serializable arguments so they can be called from different processes, and +making methods pure virtual so they can have proxy implementations that forward +calls between processes. + +When Wallet, Node, and Chain code is running in the same process, calling any +interface method invokes the implementation directly. When code is running in +different processes, calling an interface method invokes a proxy interface +implementation that communicates with a remote process and invokes the real +implementation in the remote process. The +[libmultiprocess](https://github.com/chaincodelabs/libmultiprocess) code +generation tool internally generates proxy client classes and proxy server +classes for this purpose that are thin wrappers around Cap'n Proto +[client](https://capnproto.org/cxxrpc.html#clients) and +[server](https://capnproto.org/cxxrpc.html#servers) classes, which handle the +actual serialization and socket communication. + +As much as possible, calls between processes are meant to work the same as +calls within a single process without adding limitations or requiring extra +implementation effort. Processes communicate with each other by calling regular +[C++ interface methods](../src/interfaces/README.md). Method arguments and +return values are automatically serialized and sent between processes. Object +references and `std::function` arguments are automatically tracked and mapped +to allow invoked code to call back into invoking code at any time, and there is +a 1:1 threading model where any thread invoking a method in another process has +a corresponding thread in the invoked process responsible for executing all +method calls from the source thread, without blocking I/O or holding up another +call, and using the same thread local variables, locks, and callbacks between +calls. The forwarding, tracking, and threading is implemented inside the +[libmultiprocess](https://github.com/chaincodelabs/libmultiprocess) library +which has the design goal of making calls between processes look like calls in +the same process to the extent possible. diff --git a/doc/productivity.md b/doc/productivity.md index 1bf3d9afb5..a01c6f545d 100644 --- a/doc/productivity.md +++ b/doc/productivity.md @@ -12,7 +12,7 @@ Table of Contents * [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 C/C++ diffs with `clang-format-diff.py`](#format-cc-diffs-with-clang-format-diffpy) * [Format Python diffs with `yapf-diff.py`](#format-python-diffs-with-yapf-diffpy) * [Rebasing/Merging code](#rebasingmerging-code) * [More conflict context with `merge.conflictstyle diff3`](#more-conflict-context-with-mergeconflictstyle-diff3) @@ -51,6 +51,7 @@ After running `./autogen.sh`, which generates the `./configure` file, use `./con ```sh --without-miniupnpc +--without-natpmp --disable-bench --disable-wallet --without-gui @@ -118,13 +119,13 @@ You can also set up [upstream refspecs](#reference-prs-easily-with-refspecs) to Writing code ------------ -### Format C/C++/Protobuf diffs with `clang-format-diff.py` +### Format C/C++ diffs with `clang-format-diff.py` See [contrib/devtools/README.md](/contrib/devtools/README.md#clang-format-diff.py). ### Format Python diffs with `yapf-diff.py` -Usage is exactly the same as [`clang-format-diff.py`](#format-ccprotobuf-diffs-with-clang-format-diffpy). You can get it [here](https://github.com/MarcoFalke/yapf-diff). +Usage is exactly the same as [`clang-format-diff.py`](#format-cc-diffs-with-clang-format-diffpy). You can get it [here](https://github.com/MarcoFalke/yapf-diff). Rebasing/Merging code ------------- diff --git a/doc/reduce-memory.md b/doc/reduce-memory.md index 6e7a578ecc..296b172bde 100644 --- a/doc/reduce-memory.md +++ b/doc/reduce-memory.md @@ -24,9 +24,13 @@ The size of some in-memory caches can be reduced. As caches trade off memory usa ## Number of peers -- `-maxconnections=<n>` - the maximum number of connections, this defaults to 125. Each active connection takes up some - memory. This option applies only if incoming connections are enabled, otherwise the number of connections will never - be more than 10. Of the 10 outbound peers, there can be 8 full-relay connections and 2 block-relay-only ones. +- `-maxconnections=<n>` - the maximum number of connections, which defaults to 125. Each active connection takes up some + memory. This option applies only if inbound connections are enabled; otherwise, the number of connections will not + be more than 11. Of the 11 outbound peers, there can be 8 full-relay connections, 2 block-relay-only ones, + and occasionally 1 short-lived feeler or extra outbound block-relay-only connection. + +- These limits do not apply to connections added manually with the `-addnode` configuration option or + the `addnode` RPC, which have a separate limit of 8 connections. ## Thread configuration diff --git a/doc/reduce-traffic.md b/doc/reduce-traffic.md index e39e43df7a..86943b1f72 100644 --- a/doc/reduce-traffic.md +++ b/doc/reduce-traffic.md @@ -23,7 +23,7 @@ longer serving historic blocks (blocks older than one week). Keep in mind that new nodes require other nodes that are willing to serve historic blocks. -Whitelisted peers will never be disconnected, although their traffic counts for +Peers with the `download` permission will never be disconnected, although their traffic counts for calculating the target. ## 2. Disable "listening" (`-listen=0`) @@ -50,7 +50,7 @@ Be reminded of the effects of this setting. Doing so disables the automatic broadcasting of transactions from wallet. 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. -- If a peer is whitelisted and "-whitelistforcerelay" is set to "1" (which will - also set "whitelistrelay" to "1"), we will still receive and relay their transactions. +- If a peer has the forcerelay permission, we will still receive and relay + their 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.md b/doc/release-notes.md index cd6a4d6b59..dc28ccb9ed 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -1,5 +1,223 @@ -Please edit the release notes here: +# Release notes now being edited on https://github.com/bitcoin-core/bitcoin-devwiki/wiki/22.0-Release-Notes-draft -https://github.com/bitcoin-core/bitcoin-devwiki/wiki/0.20.0-Release-Notes-Draft +*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 release includes 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 in some cases), then run the +installer (on Windows) or just copy over `/Applications/Bitcoin-Qt` (on Mac) +or `bitcoind`/`bitcoin-qt` (on Linux). + +Upgrading directly from a version of Bitcoin Core that has reached its EOL is +possible, but it might take some time if the data directory 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.14+, and Windows 7 and newer. Bitcoin +Core should also work on most other Unix-like systems but is not as +frequently tested on them. It is not recommended to use Bitcoin Core on +unsupported systems. + +From Bitcoin Core 22.0 onwards, macOS versions earlier than 10.14 are no longer supported. + +Notable changes +=============== + +P2P and network changes +----------------------- + +- This release removes support for Tor version 2 hidden services in favor of Tor + v3 only, as the Tor network [dropped support for Tor + v2](https://blog.torproject.org/v2-deprecation-timeline) with the release of + Tor version 0.4.6. Henceforth, Bitcoin Core ignores Tor v2 addresses; it + neither rumors them over the network to other peers, nor stores them in memory + or to `peers.dat`. (#22050) + +- Added NAT-PMP port mapping support via + [`libnatpmp`](https://miniupnp.tuxfamily.org/libnatpmp.html). (#18077) + +Updated RPCs +------------ + +- Due to [BIP 350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) + being implemented, behavior for all RPCs that accept addresses is changed when + a native witness version 1 (or higher) is passed. These now require a Bech32m + encoding instead of a Bech32 one, and Bech32m encoding will be used for such + addresses in RPC output as well. No version 1 addresses should be created + for mainnet until consensus rules are adopted that give them meaning + (e.g. through [BIP 341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki)). + Once that happens, Bech32m is expected to be used for them, so this shouldn't + affect any production systems, but may be observed on other networks where such + addresses already have meaning (like signet). (#20861) + +- The `getpeerinfo` RPC returns two new boolean fields, `bip152_hb_to` and + `bip152_hb_from`, that respectively indicate whether we selected a peer to be + in compact blocks high-bandwidth mode or whether a peer selected us as a + compact blocks high-bandwidth peer. High-bandwidth peers send new block + announcements via a `cmpctblock` message rather than the usual inv/headers + announcements. See BIP 152 for more details. (#19776) + +- `getpeerinfo` no longer returns the following fields: `addnode`, `banscore`, + and `whitelisted`, which were previously deprecated in 0.21. Instead of + `addnode`, the `connection_type` field returns manual. Instead of + `whitelisted`, the `permissions` field indicates if the peer has special + privileges. The `banscore` field has simply been removed. (#20755) + +- The following RPCs: `gettxout`, `getrawtransaction`, `decoderawtransaction`, + `decodescript`, `gettransaction`, and REST endpoints: `/rest/tx`, + `/rest/getutxos`, `/rest/block` deprecated the following fields (which are no + longer returned in the responses by default): `addresses`, `reqSigs`. + The `-deprecatedrpc=addresses` flag must be passed for these fields to be + included in the RPC response. This flag/option will be available only for this major release, after which + the deprecation will be removed entirely. Note that these fields are attributes of + the `scriptPubKey` object returned in the RPC response. However, in the response + of `decodescript` these fields are top-level attributes, and included again as attributes + of the `scriptPubKey` object. (#20286) + +- When creating a hex-encoded bitcoin transaction using the `bitcoin-tx` utility + with the `-json` option set, the following fields: `addresses`, `reqSigs` are no longer + returned in the tx output of the response. (#20286) + +- The `listbanned` RPC now returns two new numeric fields: `ban_duration` and `time_remaining`. + Respectively, these new fields indicate the duration of a ban and the time remaining until a ban expires, + both in seconds. Additionally, the `ban_created` field is repositioned to come before `banned_until`. (#21602) + +- The `getnodeaddresses` RPC now returns a "network" field indicating the + network type (ipv4, ipv6, onion, or i2p) for each address. (#21594) + +- `getnodeaddresses` now also accepts a "network" argument (ipv4, ipv6, onion, + or i2p) to return only addresses of the specified network. (#21843) + +- The `testmempoolaccept` RPC now accepts multiple transactions (still experimental at the moment, + API may be unstable). This is intended for testing transaction packages with dependency + relationships; it is not recommended for batch-validating independent transactions. In addition to + mempool policy, package policies apply: the list cannot contain more than 25 transactions or have a + total size exceeding 101K virtual bytes, and cannot conflict with (spend the same inputs as) each other or + the mempool, even if it would be a valid BIP125 replace-by-fee. There are some known limitations to + the accuracy of the test accept: it's possible for `testmempoolaccept` to return "allowed"=True for a + group of transactions, but "too-long-mempool-chain" if they are actually submitted. (#20833) + +- `addmultisigaddress` and `createmultisig` now support up to 20 keys for + Segwit addresses. (#20867) + +Changes to Wallet or GUI related RPCs can be found in the GUI or Wallet section below. + +New RPCs +-------- + +Build System +------------ + +New settings +------------ + +- The `-natpmp` option has been added to use NAT-PMP to map the listening port. + If both UPnP and NAT-PMP are enabled, a successful allocation from UPnP + prevails over one from NAT-PMP. (#18077) + +Updated settings +---------------- + +Changes to Wallet or GUI related settings can be found in the GUI or Wallet section below. + +- Passing an invalid `-rpcauth` argument now cause bitcoind to fail to start. (#20461) + +Tools and Utilities +------------------- + +- A new CLI `-addrinfo` command returns the number of addresses known to the + node per network type (including Tor v2 versus v3) and total. This can be + useful to see if the node knows enough addresses in a network to use options + like `-onlynet=<network>` or to upgrade to this release of Bitcoin Core 22.0 + that supports Tor v3 only. (#21595) + +- A new `-rpcwaittimeout` argument to `bitcoin-cli` sets the timeout + in seconds to use with `-rpcwait`. If the timeout expires, + `bitcoin-cli` will report a failure. (#21056) + +Wallet +------ + +- A new `listdescriptors` RPC is available to inspect the contents of descriptor-enabled wallets. + The RPC returns public versions of all imported descriptors, including their timestamp and flags. + For ranged descriptors, it also returns the range boundaries and the next index to generate addresses from. (#20226) + +- The `bumpfee` RPC is not available with wallets that have private keys + disabled. `psbtbumpfee` can be used instead. (#20891) + +- The `fundrawtransaction`, `send` and `walletcreatefundedpsbt` RPCs now support an `include_unsafe` option + that when `true` allows using unsafe inputs to fund the transaction. + Note that the resulting transaction may become invalid if one of the unsafe inputs disappears. + If that happens, the transaction must be funded with different inputs and republished. (#21359) + +- We now support up to 20 keys in `multi()` and `sortedmulti()` descriptors + under `wsh()`. (#20867) + +GUI changes +----------- + +Low-level changes +================= + +RPC +--- + +- The RPC server can process a limited number of simultaneous RPC requests. + Previously, if this limit was exceeded, the RPC server would respond with + [status code 500 (`HTTP_INTERNAL_SERVER_ERROR`)](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#5xx_server_errors). + Now it returns status code 503 (`HTTP_SERVICE_UNAVAILABLE`). (#18335) + +- Error codes have been updated to be more accurate for the following error cases (#18466): + - `signmessage` now returns RPC_INVALID_ADDRESS_OR_KEY (-5) if the + passed address is invalid. Previously returned RPC_TYPE_ERROR (-3). + - `verifymessage` now returns RPC_INVALID_ADDRESS_OR_KEY (-5) if the + passed address is invalid. Previously returned RPC_TYPE_ERROR (-3). + - `verifymessage` now returns RPC_TYPE_ERROR (-3) if the passed signature + is malformed. Previously returned RPC_INVALID_ADDRESS_OR_KEY (-5). + +Tests +----- + +Credits +======= + +Thanks to everyone who directly contributed to this release: + + +As well as to everyone that helped with translations on +[Transifex](https://www.transifex.com/bitcoin/bitcoin/). diff --git a/doc/release-notes/release-notes-0.20.0.md b/doc/release-notes/release-notes-0.20.0.md new file mode 100644 index 0000000000..6fc1606b37 --- /dev/null +++ b/doc/release-notes/release-notes-0.20.0.md @@ -0,0 +1,987 @@ +0.20.0 Release Notes +==================== + +Bitcoin Core version 0.20.0 is now available from: + + <https://bitcoincore.org/bin/bitcoin-core-0.20.0/> + +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: + + <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 in some cases), then run the +installer (on Windows) or just copy over `/Applications/Bitcoin-Qt` (on Mac) +or `bitcoind`/`bitcoin-qt` (on Linux). + +Upgrading directly from a version of Bitcoin Core that has reached its EOL is +possible, but it might take some time if the data directory 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.12+, and Windows 7 and newer. Bitcoin +Core should also work on most other Unix-like systems but is not as +frequently tested on them. It is not recommended to use Bitcoin Core on +unsupported systems. + +From Bitcoin Core 0.20.0 onwards, macOS versions earlier than 10.12 are no +longer supported. Additionally, Bitcoin Core does not yet change appearance +when macOS "dark mode" is activated. + +Known Bugs +========== + +The process for generating the source code release ("tarball") has changed in an +effort to make it more complete, however, there are a few regressions in +this release: + +- The generated `configure` script is currently missing, and you will need to + install autotools and run `./autogen.sh` before you can run + `./configure`. This is the same as when checking out from git. + +- Instead of running `make` simply, you should instead run + `BITCOIN_GENBUILD_NO_GIT=1 make`. + +Notable changes +=============== + +P2P and network changes +----------------------- + +#### Removal of BIP61 reject network messages from Bitcoin Core + +The `-enablebip61` command line option to enable BIP61 has been removed. +(#17004) + +This feature has been disabled by default since Bitcoin Core version 0.18.0. +Nodes on the network can not generally be trusted to send valid messages +(including reject messages), so this should only ever be used when +connected to a trusted node. Please use the alternatives recommended +below if you rely on this removed feature: + +- Testing or debugging of implementations of the Bitcoin P2P network protocol + should be done by inspecting the log messages that are produced by a recent + version of Bitcoin Core. Bitcoin Core logs debug messages + (`-debug=<category>`) to a stream (`-printtoconsole`) or to a file + (`-debuglogfile=<debug.log>`). + +- Testing the validity of a block can be achieved by specific RPCs: + + - `submitblock` + + - `getblocktemplate` with `'mode'` set to `'proposal'` for blocks with + potentially invalid POW + +- Testing the validity of a transaction can be achieved by specific RPCs: + + - `sendrawtransaction` + + - `testmempoolaccept` + +- Wallets should not assume a transaction has propagated to the network + just because there are no reject messages. Instead, listen for the + transaction to be announced by other peers on the network. Wallets + should not assume a lack of reject messages means a transaction pays + an appropriate fee. Instead, set fees using fee estimation and use + replace-by-fee to increase a transaction's fee if it hasn't confirmed + within the desired amount of time. + +The removal of BIP61 reject message support also has the following minor RPC +and logging implications: + +- `testmempoolaccept` and `sendrawtransaction` no longer return the P2P reject + code when a transaction is not accepted to the mempool. They still return the + verbal reject reason. + +- Log messages that previously reported the reject code when a transaction was + not accepted to the mempool now no longer report the reject code. The reason + for rejection is still reported. + +Updated RPCs +------------ + +- The RPCs which accept descriptors now accept the new `sortedmulti(...)` descriptor + type which supports multisig scripts where the public keys are sorted + lexicographically in the resulting script. (#17056) + +- The `walletprocesspsbt` and `walletcreatefundedpsbt` RPCs now include + BIP32 derivation paths by default for public keys if we know them. + This can be disabled by setting the `bip32derivs` parameter to + `false`. (#17264) + +- The `bumpfee` RPC's parameter `totalFee`, which was deprecated in + 0.19, has been removed. (#18312) + +- The `bumpfee` RPC will return a PSBT when used with wallets that have + private keys disabled. (#16373) + +- The `getpeerinfo` RPC now includes a `mapped_as` field to indicate the + mapped Autonomous System used for diversifying peer selection. See the + `-asmap` configuration option described below in _New Settings_. (#16702) + +- The `createmultisig` and `addmultisigaddress` RPCs now return an + output script descriptor for the newly created address. (#18032) + +Build System +------------ + +- OpenSSL is no longer used by Bitcoin Core. (#17265) + +- BIP70 support has been fully removed from Bitcoin Core. The + `--enable-bip70` option remains, but it will throw an error during configure. + (#17165) + +- glibc 2.17 or greater is now required to run the release binaries. This + retains compatibility with RHEL 7, CentOS 7, Debian 8 and Ubuntu 14.04 LTS. (#17538) + +- The source code archives that are provided with gitian builds no longer contain + any autotools artifacts. Therefore, to build from such source, a user + should run the `./autogen.sh` script from the root of the unpacked archive. + This implies that `autotools` and other required packages are installed on the + user's system. (#18331) + +New settings +------------ + +- New `rpcwhitelist` and `rpcwhitelistdefault` configuration parameters + allow giving certain RPC users permissions to only some RPC calls. + (#12763) + +- A new `-asmap` configuration option has been added to diversify the + node's network connections by mapping IP addresses Autonomous System + Numbers (ASNs) and then limiting the number of connections made to any + single ASN. See [issue #16599](https://github.com/bitcoin/bitcoin/issues/16599), + [PR #16702](https://github.com/bitcoin/bitcoin/pull/16702), and the + `bitcoind help` for more information. This option is experimental and + subject to removal or breaking changes in future releases, so the + legacy /16 prefix mapping of IP addresses remains the default. (#16702) + +Updated settings +---------------- + +- All custom settings configured when Bitcoin Core starts are now + written to the `debug.log` file to assist troubleshooting. (#16115) + +- Importing blocks upon startup via the `bootstrap.dat` file no longer + occurs by default. The file must now be specified with + `-loadblock=<file>`. (#17044) + +- The `-debug=db` logging category has been renamed to + `-debug=walletdb` to distinguish it from `coindb`. The `-debug=db` + option has been deprecated and will be removed in the next major + release. (#17410) + +- The `-walletnotify` configuration parameter will now replace any `%w` + in its argument with the name of the wallet generating the + notification. This is not supported on Windows. (#13339) + +Removed settings +---------------- + +- The `-whitelistforcerelay` configuration parameter has been removed after + it was discovered that it was rendered ineffective in version 0.13 and + hasn't actually been supported for almost four years. (#17985) + +GUI changes +----------- + +- The "Start Bitcoin Core on system login" option has been removed on macOS. + (#17567) + +- In the Peers window, the details for a peer now displays a `Mapped AS` + field to indicate the mapped Autonomous System used for diversifying + peer selection. See the `-asmap` configuration option in _New + Settings_, above. (#18402) + +- A "known bug" [announced](https://bitcoincore.org/en/releases/0.18.0/#wallet-gui) + in the release notes of version 0.18 has been fixed. The issue + affected anyone who simultaneously used multiple Bitcoin Core wallets + and the GUI coin control feature. (#18894) + +- For watch-only wallets, creating a new transaction in the Send screen + or fee bumping an existing transaction in the Transactions screen will + automatically copy a Partially-Signed Bitcoin Transaction (PSBT) to + the system clipboard. This can then be pasted into an external + program such as [HWI](https://github.com/bitcoin-core/HWI) for + signing. Future versions of Bitcoin Core should support a GUI option + for finalizing and broadcasting PSBTs, but for now the debug console + may be used with the `finalizepsbt` and `sendrawtransaction` RPCs. + (#16944, #17492) + +Wallet +------ + +- The wallet now by default uses bech32 addresses when using RPC, and + creates native segwit change outputs. (#16884) + +- The way that output trust was computed has been fixed, which affects + confirmed/unconfirmed balance status and coin selection. (#16766) + +- The `gettransaction`, `listtransactions` and `listsinceblock` RPC + responses now also include the height of the block that contains the + wallet transaction, if any. (#17437) + +- The `getaddressinfo` RPC has had its `label` field deprecated + (re-enable for this release using the configuration parameter + `-deprecatedrpc=label`). The `labels` field is altered from returning + JSON objects to returning a JSON array of label names (re-enable + previous behavior for this release using the configuration parameter + `-deprecatedrpc=labelspurpose`). Backwards compatibility using the + deprecated configuration parameters is expected to be dropped in the + 0.21 release. (#17585, #17578) + +Documentation changes +--------------------- + +- Bitcoin Core's automatically-generated source code documentation is + now available at https://doxygen.bitcoincore.org. (#17596) + +Low-level changes +================= + +Utilities +--------- + +- The `bitcoin-cli` utility used with the `-getinfo` parameter now + returns a `headers` field with the number of downloaded block headers + on the best headers chain (similar to the `blocks` field that is also + returned) and a `verificationprogress` field that estimates how much + of the best block chain has been synced by the local node. The + information returned no longer includes the `protocolversion`, + `walletversion`, and `keypoololdest` fields. (#17302, #17650) + +- The `bitcoin-cli` utility now accepts a `-stdinwalletpassphrase` + parameter that can be used when calling the `walletpassphrase` and + `walletpassphrasechange` RPCs to read the passphrase from standard + input without echoing it to the terminal, improving security against + anyone who can look at your screen. The existing `-stdinrpcpass` + parameter is also updated to not echo the passphrase. (#13716) + +Command line +------------ + +- Command line options prefixed with main/test/regtest network names like + `-main.port=8333` `-test.server=1` previously were allowed but ignored. Now + they trigger "Invalid parameter" errors on startup. (#17482) + +New RPCs +-------- + +- The `dumptxoutset` RPC outputs a serialized snapshot of the current + UTXO set. A script is provided in the `contrib/devtools` directory + for generating a snapshot of the UTXO set at a particular block + height. (#16899) + +- The `generatetodescriptor` RPC allows testers using regtest mode to + generate blocks that pay an arbitrary output script descriptor. + (#16943) + +Updated RPCs +------------ + +- The `verifychain` RPC default values are now static instead of + depending on the command line options or configuration file + (`-checklevel`, and `-checkblocks`). Users can pass in the RPC + arguments explicitly when they don't want to rely on the default + values. (#18541) + +- The `getblockchaininfo` RPC's `verificationprogress` field will no + longer report values higher than 1. Previously it would occasionally + report the chain was more than 100% verified. (#17328) + +Tests +----- + +- It is now an error to use an unqualified `walletdir=path` setting in + the config file if running on testnet or regtest networks. The setting + now needs to be qualified as `chain.walletdir=path` or placed in the + appropriate `[chain]` section. (#17447) + +- `-fallbackfee` was 0 (disabled) by default for the main chain, but + 0.0002 by default for the test chains. Now it is 0 by default for all + chains. Testnet and regtest users will have to add + `fallbackfee=0.0002` to their configuration if they weren't setting it + and they want it to keep working like before. (#16524) + +Build system +------------ + +- Support is provided for building with the Android Native Development + Kit (NDK). (#16110) + +0.20.0 change log +================= + +### Mining +- #18742 miner: Avoid stack-use-after-return in validationinterface (MarcoFalke) + +### Block and transaction handling +- #15283 log: Fix UB with bench on genesis block (instagibbs) +- #16507 feefilter: Compute the absolute fee rather than stored rate (instagibbs) +- #16688 log: Add validation interface logging (jkczyz) +- #16805 log: Add timing information to FlushStateToDisk() (jamesob) +- #16902 O(1) `OP_IF/NOTIF/ELSE/ENDIF` script implementation (sipa) +- #16945 introduce CChainState::GetCoinsCacheSizeState (jamesob) +- #16974 Walk pindexBestHeader back to ChainActive().Tip() if it is invalid (TheBlueMatt) +- #17004 Remove REJECT code from CValidationState (jnewbery) +- #17080 Explain why `fCheckDuplicateInputs` can not be skipped and remove it (MarcoFalke) +- #17328 GuessVerificationProgress: cap the ratio to 1 (darosior) +- #17399 Templatize ValidationState instead of subclassing (jkczyz) +- #17407 node: Add reference to mempool in NodeContext (MarcoFalke) +- #17708 prevector: Avoid misaligned member accesses (ajtowns) +- #17850,#17896,#17957,#18021,#18021,#18112 Serialization improvements (sipa) +- #17925 Improve UpdateTransactionsFromBlock with Epochs (JeremyRubin) +- #18002 Abstract out script execution out of `VerifyWitnessProgram()` (sipa) +- #18388 Make VerifyWitnessProgram use a Span stack (sipa) +- #18433 serialization: prevent int overflow for big Coin::nHeight (pierreN) +- #18500 chainparams: Bump assumed valid hash (MarcoFalke) +- #18551 Do not clear validationinterface entries being executed (sipa) + +### P2P protocol and network code +- #15437 Remove BIP61 reject messages (MarcoFalke) +- #16702 Supply and use asmap to improve IP bucketing in addrman (naumenkogs) +- #16851 Continue relaying transactions after they expire from mapRelay (ajtowns) +- #17164 Avoid allocating memory for addrKnown where we don't need it (naumenkogs) +- #17243 tools: add PoissonNextSend method that returns mockable time (amitiuttarwar) +- #17251 SocketHandler logs peer id for close and disconnect (Sjors) +- #17573 Seed RNG with precision timestamps on receipt of net messages (TheBlueMatt) +- #17624 Fix an uninitialized read in ProcessMessage(…, "tx", …) when receiving a transaction we already have (practicalswift) +- #17754 Don't allow resolving of std::string with embedded NUL characters. Add tests (practicalswift) +- #17758 Fix CNetAddr::IsRFC2544 comment + tests (tynes) +- #17812 config, net, test: Asmap feature refinements and functional tests (jonatack) +- #17951 Use rolling bloom filter of recent block txs for AlreadyHave() check (sdaftuar) +- #17985 Remove forcerelay of rejected txs (MarcoFalke) +- #18023 Fix some asmap issues (sipa) +- #18054 Reference instead of copy in BlockConnected range loop (jonatack) +- #18376 Fix use-after-free in tests (vasild) +- #18454 Make addr relay mockable, add test (MarcoFalke) +- #18458 Add missing `cs_vNodes` lock (MarcoFalke) +- #18506 Hardcoded seeds update for 0.20 (laanwj) +- #18808 Drop unknown types in getdata (jnewbery) +- #18962 Only send a getheaders for one block in an INV (jnewbery) + +### Wallet +- #13339 Replace %w by wallet name in -walletnotify script (promag) +- #15931 Remove GetDepthInMainChain dependency on locked chain interface (ariard) +- #16373 bumpfee: Return PSBT when wallet has privkeys disabled (instagibbs) +- #16524 Disable -fallbackfee by default (jtimon) +- #16766 Make IsTrusted scan parents recursively (JeremyRubin) +- #16884 Change default address type to bech32 (instagibbs) +- #16911 Only check the hash of transactions loaded from disk (achow101) +- #16923 Handle duplicate fileid exception (promag) +- #17056 descriptors: Introduce sortedmulti descriptor (achow101) +- #17070 Avoid showing GUI popups on RPC errors (MarcoFalke) +- #17138 Remove wallet access to some node arguments (jnewbery) +- #17237 LearnRelatedScripts only if KeepDestination (promag) +- #17260 Split some CWallet functions into new LegacyScriptPubKeyMan (achow101) +- #17261 Make ScriptPubKeyMan an actual interface and the wallet to have multiple (achow101) +- #17290 Enable BnB coin selection for preset inputs and subtract fee from outputs (achow101) +- #17373 Various fixes and cleanup to keypool handling in LegacyScriptPubKeyMan and CWallet (achow101) +- #17410 Rename `db` log category to `walletdb` (like `coindb`) (laanwj) +- #17444 Avoid showing GUI popups on RPC errors (take 2) (MarcoFalke) +- #17447 Make -walletdir network only (promag) +- #17537 Cleanup and move opportunistic and superfluous TopUp()s (achow101) +- #17553 Remove out of date comments for CalculateMaximumSignedTxSize (instagibbs) +- #17568 Fix when sufficient preset inputs and subtractFeeFromOutputs (achow101) +- #17677 Activate watchonly wallet behavior for LegacySPKM only (instagibbs) +- #17719 Document better -keypool as a look-ahead safety mechanism (ariard) +- #17843 Reset reused transactions cache (fjahr) +- #17889 Improve CWallet:MarkDestinationsDirty (promag) +- #18034 Get the OutputType for a descriptor (achow101) +- #18067 Improve LegacyScriptPubKeyMan::CanProvide script recognition (ryanofsky) +- #18115 Pass in transactions and messages for signing instead of exporting the private keys (achow101) +- #18192,#18546 Bugfix: Wallet: Safely deal with change in the address book (luke-jr) +- #18204 descriptors: Improve descriptor cache and cache xpubs (achow101) +- #18274 rpc/wallet: Initialize nFeeRequired to avoid using garbage value on failure (kallewoof) +- #18312 Remove deprecated fee bumping by totalFee (jonatack) +- #18338 Fix wallet unload race condition (promag) + +### RPC and other APIs +- #12763 Add RPC Whitelist Feature from #12248 (JeremyRubin) +- #13716 cli: `-stdinwalletpassphrase` and non-echo stdin passwords (kallewoof) +- #16689 Add missing fields to wallet rpc help output (ariard) +- #16821 Fix bug where duplicate PSBT keys are accepted (erasmospunk) +- #16899 UTXO snapshot creation (dumptxoutset) +- #17156 psbt: Check that various indexes and amounts are within bounds (achow101) +- #17264 Set default bip32derivs to true for psbt methods (Sjors) +- #17283 improve getaddressinfo test coverage, help, code docs (jonatack) +- #17302 cli: Add "headers" and "verificationprogress" to -getinfo (laanwj) +- #17318 replace asserts in RPC code with `CHECK_NONFATAL` and add linter (adamjonas) +- #17437 Expose block height of wallet transactions (promag) +- #17519 Remove unused `COINBASE_FLAGS` (narula) +- #17578 Simplify getaddressinfo labels, deprecate previous behavior (jonatack) +- #17585 deprecate getaddressinfo label (jonatack) +- #17746 Remove vector copy from listtransactions (promag) +- #17809 Auto-format RPCResult (MarcoFalke) +- #18032 Output a descriptor in createmultisig and addmultisigaddress (achow101) +- #18122 Update validateaddress RPCExamples to bech32 (theStack) +- #18208 Change RPCExamples to bech32 (yusufsahinhamza) +- #18268 Remove redundant types from descriptions (docallag) +- #18346 Document an RPCResult for all calls; Enforce at compile time (MarcoFalke) +- #18396 Add missing HelpExampleRpc for getblockfilter (theStack) +- #18398 Fix broken RPCExamples for waitforblock(height) (theStack) +- #18444 Remove final comma for last entry of fixed-size arrays/objects in RPCResult (luke-jr) +- #18459 Remove unused getbalances() code (jonatack) +- #18484 Correctly compute redeemScript from witnessScript for signrawtransaction (achow101) +- #18487 Fix rpcRunLater race in walletpassphrase (promag) +- #18499 Make rpc documentation not depend on call-time rpc args (MarcoFalke) +- #18532 Avoid initialization-order-fiasco on static CRPCCommand tables (MarcoFalke) +- #18541 Make verifychain default values static, not depend on global args (MarcoFalke) +- #18809 Do not advertise dumptxoutset as a way to flush the chainstate (MarcoFalke) +- #18814 Relock wallet only if most recent callback (promag) + +### GUI +- #15023 Restore RPC Console to non-wallet tray icon menu (luke-jr) +- #15084 Don't disable the sync overlay when wallet is disabled (benthecarman) +- #15098 Show addresses for "SendToSelf" transactions (hebasto) +- #15756 Add shortcuts for tab tools (promag) +- #16944 create PSBT with watch-only wallet (Sjors) +- #16964 Change sendcoins dialogue Yes to Send (instagibbs) +- #17068 Always generate `bitcoinstrings.cpp` on `make translate` (D4nte) +- #17096 Rename debug window (Zero-1729) +- #17105 Make RPCConsole::TabTypes an enum class (promag) +- #17125 Add toolTip and placeholderText to sign message fields (dannmat) +- #17165 Remove BIP70 support (fanquake) +- #17180 Improved tooltip for send amount field (JeremyCrookshank) +- #17186 Add placeholder text to the sign message field (Danny-Scott) +- #17195 Send amount placeholder value (JeremyCrookshank) +- #17226 Fix payAmount tooltip in SendCoinsEntry (promag) +- #17360 Cleaning up hide button tool tip (Danny-Scott) +- #17446 Changed tooltip for 'Label' & 'Message' text fields to be more clear (dannmat) +- #17453 Fix intro dialog labels when the prune button is toggled (hebasto) +- #17474 Bugfix: GUI: Recognise `NETWORK_LIMITED` in formatServicesStr (luke-jr) +- #17492 Bump fee returns PSBT on clipboard for watchonly-only wallets (instagibbs) +- #17567 Remove macOS start on login code (fanquake) +- #17587 Show watch-only balance in send screen (Sjors) +- #17694 Disable 3rd-party tx-urls when wallet disabled (brakmic) +- #17696 Force set nPruneSize in QSettings after the intro dialog (hebasto) +- #17702 Move static placeholder texts to forms (laanwj) +- #17826 Log Qt related info (hebasto) +- #17886 Restore English translation option (achow101) +- #17906 Set CConnman byte counters earlier to avoid uninitialized reads (ryanofsky) +- #17935 Hide HD & encryption icons when no wallet loaded (brakmic) +- #17998 Shortcut to close ModalOverlay (emilengler) +- #18007 Bugfix: GUI: Hide the HD/encrypt icons earlier so they get re-shown if another wallet is open (luke-jr) +- #18060 Drop PeerTableModel dependency to ClientModel (promag) +- #18062 Fix unintialized WalletView::progressDialog (promag) +- #18091 Pass clientmodel changes from walletframe to walletviews (jonasschnelli) +- #18101 Fix deprecated QCharRef usage (hebasto) +- #18121 Throttle GUI update pace when -reindex (hebasto) +- #18123 Fix race in WalletModel::pollBalanceChanged (ryanofsky) +- #18160 Avoid Wallet::GetBalance in WalletModel::pollBalanceChanged (promag) +- #18360 Bump transifex slug and update English translations for 0.20 (laanwj) +- #18402 Display mapped AS in peers info window (jonatack) +- #18492 Translations update pre-branch (laanwj) +- #18549 Fix Window -> Minimize menu item (hebasto) +- #18578 Fix leak in CoinControlDialog::updateView (promag) +- #18894 Fix manual coin control with multiple wallets loaded (promag) + +### Build system +- #16667 Remove mingw linker workaround from win gitian descriptor (fanquake) +- #16669 Use new fork of osslsigncode for windows gitian signing (fanquake) +- #16949 Only pass --disable-dependency-tracking to packages that understand it (fanquake) +- #17008 Bump libevent to 2.1.11 in depends (stefanwouldgo) +- #17029 gitian: Various improvements for windows descriptor (dongcarl) +- #17033 Disable _FORTIFY_SOURCE when enable-debug (achow101) +- #17057 Switch to upstream libdmg-hfsplus (fanquake) +- #17066 Remove workaround for ancient libtool (hebasto) +- #17074 Added double quotes (mztriz) +- #17087 Add variable printing target to Makefiles (dongcarl) +- #17118 depends macOS: point --sysroot to SDK (Sjors) +- #17231 Fix boost mac cross build with clang 9+ (theuni) +- #17265 Remove OpenSSL (fanquake) +- #17284 Update retry to current version (RandyMcMillan) +- #17308 nsis: Write to correct filename in first place (dongcarl) +- #17324,#18099 Update univalue subtree (MarcoFalke) +- #17398 Update leveldb to 1.22+ (laanwj) +- #17409 Avoid hardcoded libfaketime dir in gitian (MarcoFalke) +- #17466 Fix C{,XX} pickup (dongcarl) +- #17483 Set gitian arch back to amd64 (MarcoFalke) +- #17486 Make Travis catch unused variables (Sjors) +- #17538 Bump minimum libc to 2.17 for release binaries (fanquake) +- #17542 Create test utility library from src/test/util/ (brakmic) +- #17545 Remove libanl.so.1 from ALLOWED_LIBRARIES (fanquake) +- #17547 Fix configure report about qr (hebasto) +- #17569 Allow export of environ symbols and work around rv64 toolchain issue (laanwj) +- #17647 lcov: filter depends from coverage reports (nijynot) +- #17658 Add ability to skip building qrencode (fanquake) +- #17678 Support for S390X and POWER targets (MarcoFalke) +- #17682 util: Update tinyformat to upstream (laanwj) +- #17698 Don't configure `xcb_proto` (fanquake) +- #17730 Remove Qt networking features (fanquake) +- #17738 Remove linking librt for backwards compatibility (fanquake) +- #17740 Remove configure checks for win libraries we don't link against (fanquake) +- #17741 Included `test_bitcoin-qt` in msvc build (sipsorcery) +- #17756 Remove `WINDOWS_BITS` from build system (fanquake) +- #17769 Set `AC_PREREQ` to 2.69 (fanquake) +- #17880 Add -Wdate-time to Werror flags (fanquake) +- #17910 Remove double `LIBBITCOIN_SERVER` linking (fanquake) +- #17928 Consistent use of package variable (Bushstar) +- #17933 guix: Pin Guix using `guix time-machine` (dongcarl) +- #17948 pass -fno-ident in Windows gitian descriptor (fanquake) +- #18003 Remove --large-address-aware linker flag (fanquake) +- #18004 Don't embed a build-id when building libdmg-hfsplus (fanquake) +- #18051 Fix behavior when `ALLOW_HOST_PACKAGES` unset (hebasto) +- #18059 Add missing attributes to Win installer (fanquake) +- #18104 Skip i686 build by default in guix and gitian (MarcoFalke) +- #18107 Add `cov_fuzz` target (MarcoFalke) +- #18135 Add --enable-determinism configure flag (fanquake) +- #18145 Add Wreturn-type to Werror flags, check on more Travis machines (Sjors) +- #18264 Remove Boost Chrono (fanquake) +- #18290 Set minimum Automake version to 1.13 (hebasto) +- #18320 guix: Remove now-unnecessary gcc make flag (dongcarl) +- #18331 Use git archive as source tarball (hebasto) +- #18397 Fix libevent linking for `bench_bitcoin` binary (hebasto) +- #18426 scripts: `Previous_release`: improve behaviour on failed download (theStack) +- #18429 Remove double `LIBBITCOIN_SERVER` from bench-Makefile (brakmic) +- #18528 Create `test_fuzz` library from src/test/fuzz/fuzz.cpp (brakmic) +- #18558 Fix boost detection for arch armv7l (hebasto) +- #18598 gitian: Add missing automake package to gitian-win-signer.yml (achow101) +- #18676 Check libevent minimum version in configure script (hebasto) +- #18945 Ensure source tarball has leading directory name (laanwj) + +### Platform support +- #16110 Add Android NDK support (icota) +- #16392 macOS toolchain update (fanquake) +- #16569 Increase init file stop timeout (setpill) +- #17151 Remove OpenSSL PRNG seeding (Windows, Qt only) (fanquake) +- #17365 Update README.md with working Android targets and API levels (icota) +- #17521 Only use D-Bus with Qt on linux (fanquake) +- #17550 Set minimum supported macOS to 10.12 (fanquake) +- #17592 Appveyor install libevent[thread] vcpkg (sipsorcery) +- #17660 Remove deprecated key from macOS Info.plist (fanquake) +- #17663 Pass `-dead_strip_dylibs` to ld on macOS (fanquake) +- #17676 Don't use OpenGL in Qt on macOS (fanquake) +- #17686 Add `-bind_at_load` to macOS hardened LDFLAGS (fanquake) +- #17787 scripts: Add macho pie check to security-check.py (fanquake) +- #17800 random: don't special case clock usage on macOS (fanquake) +- #17863 scripts: Add macho dylib checks to symbol-check.py (fanquake) +- #17899 msvc: Ignore msvc linker warning and update to msvc build instructions (sipsorcery) +- #17916 windows: Enable heap terminate-on-corruption (fanquake) +- #18082 logging: Enable `thread_local` usage on macos (fanquake) +- #18108 Fix `.gitignore` policy in `build_msvc` directory (hebasto) +- #18295 scripts: Add macho lazy bindings check to security-check.py (fanquake) +- #18358 util: Fix compilation with mingw-w64 7.0.0 (fanquake) +- #18359 Fix sysctl() detection on macOS (fanquake) +- #18364 random: remove getentropy() fallback for macOS < 10.12 (fanquake) +- #18395 scripts: Add pe dylib checking to symbol-check.py (fanquake) +- #18415 scripts: Add macho tests to test-security-check.py (fanquake) +- #18425 releases: Update with new Windows code signing certificate (achow101) +- #18702 Fix ASLR for bitcoin-cli on Windows (fanquake) + +### Tests and QA +- #12134 Build previous releases and run functional tests (Sjors) +- #13693 Add coverage to estimaterawfee and estimatesmartfee (Empact) +- #13728 lint: Run the ci lint stage on mac (Empact) +- #15443 Add getdescriptorinfo functional test (promag) +- #15888 Add `wallet_implicitsegwit` to test the ability to transform keys between address types (luke-jr) +- #16540 Add `ASSERT_DEBUG_LOG` to unit test framework (MarcoFalke) +- #16597 travis: Run full test suite on native macos (Sjors) +- #16681 Use self.chain instead of 'regtest' in all current tests (jtimon) +- #16786 add unit test for wallet watch-only methods involving PubKeys (theStack) +- #16943 Add generatetodescriptor RPC (MarcoFalke) +- #16973 Fix `combine_logs.py` for AppVeyor build (mzumsande) +- #16975 Show debug log on unit test failure (MarcoFalke) +- #16978 Seed test RNG context for each test case, print seed (MarcoFalke) +- #17009, #17018, #17050, #17051, #17071, #17076, #17083, #17093, #17109, #17113, #17136, #17229, #17291, #17357, #17771, #17777, #17917, #17926, #17972, #17989, #17996, #18009, #18029, #18047, #18126, #18176, #18206, #18353, #18363, #18407, #18417, #18423, #18445, #18455, #18565 Add fuzzing harnesses (practicalswift) +- #17011 ci: Use busybox utils for one build (MarcoFalke) +- #17030 Fix Python Docstring to include all Args (jbampton) +- #17041 ci: Run tests on arm (MarcoFalke) +- #17069 Pass fuzzing inputs as constant references (practicalswift) +- #17091 Add test for loadblock option and linearize scripts (fjahr) +- #17108 fix "tx-size-small" errors after default address change (theStack) +- #17121 Speed up `wallet_backup` by whitelisting peers (immediate tx relay) (theStack) +- #17124 Speed up `wallet_address_types` by whitelisting peers (immediate tx relay) (theStack) +- #17140 Fix bug in `blockfilter_index_tests` (jimpo) +- #17199 use default address type (bech32) for `wallet_bumpfee` tests (theStack) +- #17205 ci: Enable address sanitizer (asan) stack-use-after-return checking (practicalswift) +- #17206 Add testcase to simulate bitcoin schema in leveldb (adamjonas) +- #17209 Remove no longer needed UBSan suppressions (issues fixed). Add documentation (practicalswift) +- #17220 Add unit testing for the CompressScript function (adamjonas) +- #17225 Test serialisation as part of deserialisation fuzzing. Test round-trip equality where possible (practicalswift) +- #17228 Add RegTestingSetup to `setup_common` (MarcoFalke) +- #17233 travis: Run unit and functional tests on native arm (MarcoFalke) +- #17235 Skip unnecessary fuzzer initialisation. Hold ECCVerifyHandle only when needed (practicalswift) +- #17240 ci: Disable functional tests on mac host (MarcoFalke) +- #17254 Fix `script_p2sh_tests` `OP_PUSHBACK2/4` missing (adamjonas) +- #17267 bench: Fix negative values and zero for -evals flag (nijynot) +- #17275 pubkey: Assert CPubKey's ECCVerifyHandle precondition (practicalswift) +- #17288 Added TestWrapper class for interactive Python environments (jachiang) +- #17292 Add new mempool benchmarks for a complex pool (JeremyRubin) +- #17299 add reason checks for non-standard txs in `test_IsStandard` (theStack) +- #17322 Fix input size assertion in `wallet_bumpfee.py` (instagibbs) +- #17327 Add `rpc_fundrawtransaction` logging (jonatack) +- #17330 Add `shrinkdebugfile=0` to regtest bitcoin.conf (sdaftuar) +- #17340 Speed up fundrawtransaction test (jnewbery) +- #17345 Do not instantiate CAddrDB for static call CAddrDB::Read() (hebasto) +- #17362 Speed up `wallet_avoidreuse`, add logging (jonatack) +- #17363 add "diamond" unit test to MempoolAncestryTests (theStack) +- #17366 Reset global args between test suites (MarcoFalke) +- #17367 ci: Run non-cross-compile builds natively (MarcoFalke) +- #17378 TestShell: Fix typos & implement cleanups (jachiang) +- #17384 Create new test library (MarcoFalke) +- #17387 `wallet_importmulti`: use addresses of the same type as being imported (achow101) +- #17388 Add missing newline in `util_ChainMerge` test (ryanofsky) +- #17390 Add `util_ArgParsing` test (ryanofsky) +- #17420 travis: Rework `cache_err_msg` (MarcoFalke) +- #17423 ci: Make ci system read-only on the git work tree (MarcoFalke) +- #17435 check custom ancestor limit in `mempool_packages.py` (theStack) +- #17455 Update valgrind suppressions (practicalswift) +- #17461 Check custom descendant limit in `mempool_packages.py` (theStack) +- #17469 Remove fragile `assert_memory_usage_stable` (MarcoFalke) +- #17470 ci: Use clang-8 for fuzzing to run on aarch64 ci systems (MarcoFalke) +- #17480 Add unit test for non-standard txs with too large scriptSig (theStack) +- #17497 Skip tests when utils haven't been compiled (fanquake) +- #17502 Add unit test for non-standard bare multisig txs (theStack) +- #17511 Add bounds checks before base58 decoding (sipa) +- #17517 ci: Bump to clang-8 for asan build to avoid segfaults on ppc64le (MarcoFalke) +- #17522 Wait until mempool is loaded in `wallet_abandonconflict` (MarcoFalke) +- #17532 Add functional test for non-standard txs with too large scriptSig (theStack) +- #17541 Add functional test for non-standard bare multisig txs (theStack) +- #17555 Add unit test for non-standard txs with wrong nVersion (dspicher) +- #17571 Add `libtest_util` library to msvc build configuration (sipsorcery) +- #17591 ci: Add big endian platform - s390x (elichai) +- #17593 Move more utility functions into test utility library (mzumsande) +- #17633 Add option --valgrind to run the functional tests under Valgrind (practicalswift) +- #17635 ci: Add centos 7 build (hebasto) +- #17641 Add unit test for leveldb creation with unicode path (sipsorcery) +- #17674 Add initialization order fiasco detection in Travis (practicalswift) +- #17675 Enable tests which are incorrectly skipped when running `test_runner.py --usecli` (practicalswift) +- #17685 Fix bug in the descriptor parsing fuzzing harness (`descriptor_parse`) (practicalswift) +- #17705 re-enable CLI test support by using EncodeDecimal in json.dumps() (fanquake) +- #17720 add unit test for non-standard "scriptsig-not-pushonly" txs (theStack) +- #17767 ci: Fix qemu issues (MarcoFalke) +- #17793 ci: Update github actions ci vcpkg cache on msbuild update (hebasto) +- #17806 Change filemode of `rpc_whitelist.py` (emilengler) +- #17849 ci: Fix brew python link (hebasto) +- #17851 Add `std::to_string` to list of locale dependent functions (practicalswift) +- #17893 Fix double-negative arg test (hebasto) +- #17900 ci: Combine 32-bit build with centos 7 build (theStack) +- #17921 Test `OP_CSV` empty stack fail in `feature_csv_activation.py` (theStack) +- #17931 Fix `p2p_invalid_messages` failing in Python 3.8 because of warning (elichai) +- #17947 add unit test for non-standard txs with too large tx size (theStack) +- #17959 Check specific reject reasons in `feature_csv_activation.py` (theStack) +- #17984 Add p2p test for forcerelay permission (MarcoFalke) +- #18001 Updated appveyor job to checkout a specific vcpkg commit ID (sipsorcery) +- #18008 fix fuzzing using libFuzzer on macOS (fanquake) +- #18013 bench: Fix benchmarks filters (elichai) +- #18018 reset fIsBareMultisigStd after bare-multisig tests (fanquake) +- #18022 Fix appveyor `test_bitcoin` build of `*.raw` (MarcoFalke) +- #18037 util: Allow scheduler to be mocked (amitiuttarwar) +- #18056 ci: Check for submodules (emilengler) +- #18069 Replace 'regtest' leftovers by self.chain (theStack) +- #18081 Set a name for CI Docker containers (fanquake) +- #18109 Avoid hitting some known minor tinyformat issues when fuzzing strprintf(…) (practicalswift) +- #18155 Add harness which fuzzes EvalScript and VerifyScript using a fuzzed signature checker (practicalswift) +- #18159 Add --valgrind option to `test/fuzz/test_runner.py` for running fuzzing test cases under valgrind (practicalswift) +- #18166 ci: Run fuzz testing test cases (bitcoin-core/qa-assets) under valgrind to catch memory errors (practicalswift) +- #18172 Transaction expiry from mempool (0xB10C) +- #18181 Remove incorrect assumptions in `validation_flush_tests` (MarcoFalke) +- #18183 Set `catch_system_errors=no` on boost unit tests (MarcoFalke) +- #18195 Add `cost_of_change` parameter assertions to `bnb_search_test` (yancyribbens) +- #18209 Reduce unneeded whitelist permissions in tests (MarcoFalke) +- #18211 Disable mockforward scheduler unit test for now (MarcoFalke) +- #18213 Fix race in `p2p_segwit` (MarcoFalke) +- #18224 Make AnalyzePSBT next role calculation simple, correct (instagibbs) +- #18228 Add missing syncwithvalidationinterfacequeue (MarcoFalke) +- #18247 Wait for both veracks in `add_p2p_connection` (MarcoFalke) +- #18249 Bump timeouts to accomodate really slow disks (MarcoFalke) +- #18255 Add `bad-txns-*-toolarge` test cases to `invalid_txs` (MarcoFalke) +- #18263 rpc: change setmocktime check to use IsMockableChain (gzhao408) +- #18285 Check that `wait_until` returns if time point is in the past (MarcoFalke) +- #18286 Add locale fuzzer to `FUZZERS_MISSING_CORPORA` (practicalswift) +- #18292 fuzz: Add `assert(script == decompressed_script)` (MarcoFalke) +- #18299 Update `FUZZERS_MISSING_CORPORA` to enable regression fuzzing for all harnesses in master (practicalswift) +- #18300 fuzz: Add option to merge input dir to test runner (MarcoFalke) +- #18305 Explain why test logging should be used (MarcoFalke) +- #18306 Add logging to `wallet_listsinceblock.py` (jonatack) +- #18311 Bumpfee test fix (instagibbs) +- #18314 Add deserialization fuzzing of SnapshotMetadata (`utxo_snapshot`) (practicalswift) +- #18319 fuzz: Add missing `ECC_Start` to `key_io` test (MarcoFalke) +- #18334 Add basic test for BIP 37 (MarcoFalke) +- #18350 Fix mining to an invalid target + ensure that a new block has the correct hash internally (TheQuantumPhysicist) +- #18378 Bugfix & simplify bn2vch using `int.to_bytes` (sipa) +- #18393 Don't assume presence of `__builtin_mul_overflow(…)` in `MultiplicationOverflow(…)` fuzzing harness (practicalswift) +- #18406 add executable flag for `rpc_estimatefee.py` (theStack) +- #18420 listsinceblock block height checks (jonatack) +- #18430 ci: Only clone bitcoin-core/qa-assets when fuzzing (MarcoFalke) +- #18438 ci: Use homebrew addon on native macos (hebasto) +- #18447 Add coverage for script parse error in ParseScript (pierreN) +- #18472 Remove unsafe `BOOST_TEST_MESSAGE` (MarcoFalke) +- #18474 check that peer is connected when calling sync_* (MarcoFalke) +- #18477 ci: Use focal for fuzzers (MarcoFalke) +- #18481 add BIP37 'filterclear' test to p2p_filter.py (theStack) +- #18496 Remove redundant `sync_with_ping` after `add_p2p_connection` (jonatack) +- #18509 fuzz: Avoid running over all inputs after merging them (MarcoFalke) +- #18510 fuzz: Add CScriptNum::getint coverage (MarcoFalke) +- #18514 remove rapidcheck integration and tests (fanquake) +- #18515 Add BIP37 remote crash bug [CVE-2013-5700] test to `p2p_filter.py` (theStack) +- #18516 relax bumpfee `dust_to_fee` txsize an extra vbyte (jonatack) +- #18518 fuzz: Extend descriptor fuzz test (MarcoFalke) +- #18519 fuzz: Extend script fuzz test (MarcoFalke) +- #18521 fuzz: Add `process_messages` harness (MarcoFalke) +- #18529 Add fuzzer version of randomized prevector test (sipa) +- #18534 skip backwards compat tests if not compiled with wallet (fanquake) +- #18540 `wallet_bumpfee` assertion fixup (jonatack) +- #18543 Use one node to avoid a race due to missing sync in `rpc_signrawtransaction` (MarcoFalke) +- #18561 Properly raise FailedToStartError when rpc shutdown before warmup finished (MarcoFalke) +- #18562 ci: Run unit tests sequential once (MarcoFalke) +- #18563 Fix `unregister_all_during_call` cleanup (ryanofsky) +- #18566 Set `-use_value_profile=1` when merging fuzz inputs (MarcoFalke) +- #18757 Remove enumeration of expected deserialization exceptions in ProcessMessage(…) fuzzer (practicalswift) +- #18878 Add test for conflicted wallet tx notifications (ryanofsky) +- #18975 Remove const to work around compiler error on xenial (laanwj) + +### Documentation +- #16947 Doxygen-friendly script/descriptor.h comments (ch4ot1c) +- #16983 Add detailed info about Bitcoin Core files (hebasto) +- #16986 Doxygen-friendly CuckooCache comments (ch4ot1c) +- #17022 move-only: Steps for "before major release branch-off" (MarcoFalke) +- #17026 Update bips.md for default bech32 addresses in 0.20.0 (MarcoFalke) +- #17081 Fix Makefile target in benchmarking.md (theStack) +- #17102 Add missing indexes/blockfilter/basic to doc/files.md (MarcoFalke) +- #17119 Fix broken bitcoin-cli examples (andrewtoth) +- #17134 Add switch on enum example to developer notes (hebasto) +- #17142 Update macdeploy README to include all files produced by `make deploy` (za-kk) +- #17146 github: Add warning for bug reports (laanwj) +- #17157 Added instructions for how to add an upsteam to forked repo (dannmat) +- #17159 Add a note about backporting (carnhofdaki) +- #17169 Correct function name in ReportHardwareRand() (fanquake) +- #17177 Describe log files + consistent paths in test READMEs (fjahr) +- #17239 Changed miniupnp links to https (sandakersmann) +- #17281 Add developer note on `c_str()` (laanwj) +- #17285 Bip70 removal follow-up (fjahr) +- #17286 Fix help-debug -checkpoints (ariard) +- #17309 update MSVC instructions to remove Qt OpenSSL linking (fanquake) +- #17339 Add template for good first issues (michaelfolkson) +- #17351 Fix some misspellings (RandyMcMillan) +- #17353 Add ShellCheck to lint tests dependencies (hebasto) +- #17370 Update doc/bips.md with recent changes in master (MarcoFalke) +- #17393 Added regtest config for linearize script (gr0kchain) +- #17411 Add some better examples for scripted diff (laanwj) +- #17503 Remove bitness from bitcoin-qt help message and manpage (laanwj) +- #17539 Update and improve Developer Notes (hebasto) +- #17561 Changed MiniUPnPc link to https in dependencies.md (sandakersmann) +- #17596 Change doxygen URL to doxygen.bitcoincore.org (laanwj) +- #17598 Update release process with latest changes (MarcoFalke) +- #17617 Unify unix epoch time descriptions (jonatack) +- #17637 script: Add keyserver to verify-commits readme (emilengler) +- #17648 Rename wallet-tool references to bitcoin-wallet (hel-o) +- #17688 Add "ci" prefix to CONTRIBUTING.md (hebasto) +- #17751 Use recommended shebang approach in documentation code block (hackerrdave) +- #17752 Fix directory path for secp256k1 subtree in developer-notes (hackerrdave) +- #17772 Mention PR Club in CONTRIBUTING.md (emilengler) +- #17804 Misc RPC help fixes (MarcoFalke) +- #17819 Developer notes guideline on RPCExamples addresses (jonatack) +- #17825 Update dependencies.md (hebasto) +- #17873 Add to Doxygen documentation guidelines (jonatack) +- #17907 Fix improper Doxygen inline comments (Empact) +- #17942 Improve fuzzing docs for macOS users (fjahr) +- #17945 Fix doxygen errors (Empact) +- #18025 Add missing supported rpcs to doc/descriptors.md (andrewtoth) +- #18070 Add note about `brew doctor` (givanse) +- #18125 Remove PPA note from release-process.md (fanquake) +- #18170 Minor grammatical changes and flow improvements (travinkeith) +- #18212 Add missing step in win deployment instructions (dangershony) +- #18219 Add warning against wallet.dat re-use (corollari) +- #18253 Correct spelling errors in comments (Empact) +- #18278 interfaces: Describe and follow some code conventions (ryanofsky) +- #18283 Explain rebase policy in CONTRIBUTING.md (MarcoFalke) +- #18340 Mention MAKE=gmake workaround when building on a BSD (fanquake) +- #18341 Replace remaining literal BTC with `CURRENCY_UNIT` (domob1812) +- #18342 Add fuzzing quickstart guides for libFuzzer and afl-fuzz (practicalswift) +- #18344 Fix nit in getblockchaininfo (stevenroose) +- #18379 Comment fix merkle.cpp (4d55397500) +- #18382 note the costs of fetching all pull requests (vasild) +- #18391 Update init and reduce-traffic docs for -blocksonly (glowang) +- #18464 Block-relay-only vs blocksonly (MarcoFalke) +- #18486 Explain new test logging (MarcoFalke) +- #18505 Update webchat URLs in README.md (SuriyaaKudoIsc) +- #18513 Fix git add argument (HashUnlimited) +- #18577 Correct scripted-diff example link (yahiheb) +- #18589 Fix naming of macOS SDK and clarify version (achow101) + +### Miscellaneous +- #15600 lockedpool: When possible, use madvise to avoid including sensitive information in core dumps (luke-jr) +- #15934 Merge settings one place instead of five places (ryanofsky) +- #16115 On bitcoind startup, write config args to debug.log (LarryRuane) +- #16117 util: Replace boost sleep with std sleep (MarcoFalke) +- #16161 util: Fix compilation errors in support/lockedpool.cpp (jkczyz) +- #16802 scripts: In linearize, search for next position of magic bytes rather than fail (takinbo) +- #16889 Add some general std::vector utility functions (sipa) +- #17049 contrib: Bump gitian descriptors for 0.20 (MarcoFalke) +- #17052 scripts: Update `copyright_header` script to include additional files (GChuf) +- #17059 util: Simplify path argument for cblocktreedb ctor (hebasto) +- #17191 random: Remove call to `RAND_screen()` (Windows only) (fanquake) +- #17192 util: Add `check_nonfatal` and use it in src/rpc (MarcoFalke) +- #17218 Replace the LogPrint function with a macro (jkczyz) +- #17266 util: Rename decodedumptime to parseiso8601datetime (elichai) +- #17270 Feed environment data into RNG initializers (sipa) +- #17282 contrib: Remove accounts from bash completion (fanquake) +- #17293 Add assertion to randrange that input is not 0 (JeremyRubin) +- #17325 log: Fix log message for -par=1 (hebasto) +- #17329 linter: Strip trailing / in path for git-subtree-check (jnewbery) +- #17336 scripts: Search for first block file for linearize-data with some block files pruned (Rjected) +- #17361 scripts: Lint gitian descriptors with shellcheck (hebasto) +- #17482 util: Disallow network-qualified command line options (ryanofsky) +- #17507 random: mark RandAddPeriodic and SeedPeriodic as noexcept (fanquake) +- #17527 Fix CPUID subleaf iteration (sipa) +- #17604 util: Make schedulebatchpriority advisory only (fanquake) +- #17650 util: Remove unwanted fields from bitcoin-cli -getinfo (malevolent) +- #17671 script: Fixed wget call in gitian-build.py (willyko) +- #17699 Make env data logging optional (sipa) +- #17721 util: Don't allow base58 decoding of non-base58 strings. add base58 tests (practicalswift) +- #17750 util: Change getwarnings parameter to bool (jnewbery) +- #17753 util: Don't allow base32/64-decoding or parsemoney(…) on strings with embedded nul characters. add tests (practicalswift) +- #17823 scripts: Read suspicious hosts from a file instead of hardcoding (sanjaykdragon) +- #18162 util: Avoid potential uninitialized read in `formatiso8601datetime(int64_t)` by checking `gmtime_s`/`gmtime_r` return value (practicalswift) +- #18167 Fix a violation of C++ standard rules where unions are used for type-punning (TheQuantumPhysicist) +- #18225 util: Fail to parse empty string in parsemoney (MarcoFalke) +- #18270 util: Fail to parse whitespace-only strings in parsemoney(…) (instead of parsing as zero) (practicalswift) +- #18316 util: Helpexamplerpc formatting (jonatack) +- #18357 Fix missing header in sync.h (promag) +- #18412 script: Fix `script_err_sig_pushonly` error string (theStack) +- #18416 util: Limit decimal range of numbers parsescript accepts (pierreN) +- #18503 init: Replace `URL_WEBSITE` with `PACKAGE_URL` (MarcoFalke) +- #18526 Remove PID file at the very end (hebasto) +- #18553 Avoid non-trivial global constants in SHA-NI code (sipa) +- #18665 Do not expose and consider `-logthreadnames` when it does not work (hebasto) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- 0xb10c +- 251 +- 4d55397500 +- Aaron Clauson +- Adam Jonas +- Albert +- Amiti Uttarwar +- Andrew Chow +- Andrew Toth +- Anthony Towns +- Antoine Riard +- Ava Barron +- Ben Carman +- Ben Woosley +- Block Mechanic +- Brian Solon +- Bushstar +- Carl Dong +- Carnhof Daki +- Cory Fields +- Daki Carnhof +- Dan Gershony +- Daniel Kraft +- dannmat +- Danny-Scott +- darosior +- David O'Callaghan +- Dominik Spicher +- Elichai Turkel +- Emil Engler +- emu +- Fabian Jahr +- fanquake +- Filip Gospodinov +- Franck Royer +- Gastón I. Silva +- gchuf +- Gleb Naumenko +- Gloria Zhao +- glowang +- Gr0kchain +- Gregory Sanders +- hackerrdave +- Harris +- hel0 +- Hennadii Stepanov +- ianliu +- Igor Cota +- James Chiang +- James O'Beirne +- Jan Beich +- Jan Sarenik +- Jeffrey Czyz +- Jeremy Rubin +- JeremyCrookshank +- Jim Posen +- John Bampton +- John L. Jegutanis +- John Newbery +- Jon Atack +- Jon Layton +- Jonas Schnelli +- João Barbosa +- Jorge Timón +- Karl-Johan Alm +- kodslav +- Larry Ruane +- Luke Dashjr +- malevolent +- MapleLaker +- marcaiaf +- MarcoFalke +- Marius Kjærstad +- Mark Erhardt +- Mark Tyneway +- Martin Erlandsson +- Martin Zumsande +- Matt Corallo +- Matt Ward +- Michael Folkson +- Michael Polzer +- Micky Yun Chan +- Neha Narula +- nijynot +- naumenkogs +- NullFunctor +- Peter Bushnell +- pierrenn +- Pieter Wuille +- practicalswift +- randymcmillan +- Rjected +- Russell Yanofsky +- Samer Afach +- Samuel Dobson +- Sanjay K +- Sebastian Falbesoner +- setpill +- Sjors Provoost +- Stefan Richter +- stefanwouldgo +- Steven Roose +- Suhas Daftuar +- Suriyaa Sundararuban +- TheCharlatan +- Tim Akinbo +- Travin Keith +- tryphe +- Vasil Dimov +- Willy Ko +- Wilson Ccasihue S +- Wladimir J. van der Laan +- Yahia Chiheb +- Yancy Ribbens +- Yusuf Sahin HAMZA +- Zakk +- Zero + +As well as to everyone that helped with translations on +[Transifex](https://www.transifex.com/bitcoin/bitcoin/). diff --git a/doc/release-notes/release-notes-0.20.1.md b/doc/release-notes/release-notes-0.20.1.md new file mode 100644 index 0000000000..9fbb29cb82 --- /dev/null +++ b/doc/release-notes/release-notes-0.20.1.md @@ -0,0 +1,158 @@ +0.20.1 Release Notes +==================== + +Bitcoin Core version 0.20.1 is now available from: + + <https://bitcoincore.org/bin/bitcoin-core-0.20.1/> + +This minor release includes 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 in some cases), then run the +installer (on Windows) or just copy over `/Applications/Bitcoin-Qt` (on Mac) +or `bitcoind`/`bitcoin-qt` (on Linux). + +Upgrading directly from a version of Bitcoin Core that has reached its EOL is +possible, but it might take some time if the data directory 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.12+, and Windows 7 and newer. Bitcoin +Core should also work on most other Unix-like systems but is not as +frequently tested on them. It is not recommended to use Bitcoin Core on +unsupported systems. + +From Bitcoin Core 0.20.0 onwards, macOS versions earlier than 10.12 are no +longer supported. Additionally, Bitcoin Core does not yet change appearance +when macOS "dark mode" is activated. + +Known Bugs +========== + +The process for generating the source code release ("tarball") has changed in an +effort to make it more complete, however, there are a few regressions in +this release: + +- The generated `configure` script is currently missing, and you will need to + install autotools and run `./autogen.sh` before you can run + `./configure`. This is the same as when checking out from git. + +- Instead of running `make` simply, you should instead run + `BITCOIN_GENBUILD_NO_GIT=1 make`. + +Notable changes +=============== + +Changes regarding misbehaving peers +----------------------------------- + +Peers that misbehave (e.g. send us invalid blocks) are now referred to as +discouraged nodes in log output, as they're not (and weren't) strictly banned: +incoming connections are still allowed from them, but they're preferred for +eviction. + +Furthermore, a few additional changes are introduced to how discouraged +addresses are treated: + +- Discouraging an address does not time out automatically after 24 hours + (or the `-bantime` setting). Depending on traffic from other peers, + discouragement may time out at an indeterminate time. + +- Discouragement is not persisted over restarts. + +- There is no method to list discouraged addresses. They are not returned by + the `listbanned` RPC. That RPC also no longer reports the `ban_reason` + field, as `"manually added"` is the only remaining option. + +- Discouragement cannot be removed with the `setban remove` RPC command. + If you need to remove a discouragement, you can remove all discouragements by + stop-starting your node. + +Notification changes +-------------------- + +`-walletnotify` notifications are now sent for wallet transactions that are +removed from the mempool because they conflict with a new block. These +notifications were sent previously before the v0.19 release, but had been +broken since that release (bug +[#18325](https://github.com/bitcoin/bitcoin/issues/18325)). + +PSBT changes +------------ + +PSBTs will contain both the non-witness utxo and the witness utxo for segwit +inputs in order to restore compatibility with wallet software that are now +requiring the full previous transaction for segwit inputs. The witness utxo +is still provided to maintain compatibility with software which relied on its +existence to determine whether an input was segwit. + +0.20.1 change log +================= + +### Mining +- #19019 Fix GBT: Restore "!segwit" and "csv" to "rules" key (luke-jr) + +### P2P protocol and network code +- #19219 Replace automatic bans with discouragement filter (sipa) + +### Wallet +- #19300 Handle concurrent wallet loading (promag) +- #18982 Minimal fix to restore conflicted transaction notifications (ryanofsky) + +### RPC and other APIs +- #19524 Increment input value sum only once per UTXO in decodepsbt (fanquake) +- #19517 psbt: Increment input value sum only once per UTXO in decodepsbt (achow101) +- #19215 psbt: Include and allow both non_witness_utxo and witness_utxo for segwit inputs (achow101) + +### GUI +- #19097 Add missing QPainterPath include (achow101) +- #19059 update Qt base translations for macOS release (fanquake) + +### Build system +- #19152 improve build OS configure output (skmcontrib) +- #19536 qt, build: Fix QFileDialog for static builds (hebasto) + +### Tests and QA +- #19444 Remove cached directories and associated script blocks from appveyor config (sipsorcery) +- #18640 appveyor: Remove clcache (MarcoFalke) + +### Miscellaneous +- #19194 util: Don't reference errno when pthread fails (miztake) +- #18700 Fix locking on WSL using flock instead of fcntl (meshcollider) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Aaron Clauson +- Andrew Chow +- fanquake +- Hennadii Stepanov +- João Barbosa +- Luke Dashjr +- MarcoFalke +- MIZUTA Takeshi +- Pieter Wuille +- Russell Yanofsky +- sachinkm77 +- Samuel Dobson +- Wladimir J. van der Laan + +As well as to everyone that helped with translations on +[Transifex](https://www.transifex.com/bitcoin/bitcoin/). diff --git a/doc/release-notes/release-notes-0.21.0.md b/doc/release-notes/release-notes-0.21.0.md new file mode 100644 index 0000000000..3baba3d49b --- /dev/null +++ b/doc/release-notes/release-notes-0.21.0.md @@ -0,0 +1,1336 @@ +0.21.0 Release Notes +==================== + +Bitcoin Core version 0.21.0 is now available from: + + <https://bitcoincore.org/bin/bitcoin-core-0.21.0/> + +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: + + <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 in some cases), then run the +installer (on Windows) or just copy over `/Applications/Bitcoin-Qt` (on Mac) +or `bitcoind`/`bitcoin-qt` (on Linux). + +Upgrading directly from a version of Bitcoin Core that has reached its EOL is +possible, but it might take some time if the data directory 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.12+, and Windows 7 and newer. Bitcoin +Core should also work on most other Unix-like systems but is not as +frequently tested on them. It is not recommended to use Bitcoin Core on +unsupported systems. + +From Bitcoin Core 0.20.0 onwards, macOS versions earlier than 10.12 are no +longer supported. Additionally, Bitcoin Core does not yet change appearance +when macOS "dark mode" is activated. + +The node's known peers are persisted to disk in a file called `peers.dat`. The +format of this file has been changed in a backwards-incompatible way in order to +accommodate the storage of Tor v3 and other BIP155 addresses. This means that if +the file is modified by 0.21.0 or newer then older versions will not be able to +read it. Those old versions, in the event of a downgrade, will log an error +message "Incorrect keysize in addrman deserialization" and will continue normal +operation as if the file was missing, creating a new empty one. (#19954, #20284) + +Notable changes +=============== + +P2P and network changes +----------------------- + +- The mempool now tracks whether transactions submitted via the wallet or RPCs + have been successfully broadcast. Every 10-15 minutes, the node will try to + announce unbroadcast transactions until a peer requests it via a `getdata` + message or the transaction is removed from the mempool for other reasons. + The node will not track the broadcast status of transactions submitted to the + node using P2P relay. This version reduces the initial broadcast guarantees + for wallet transactions submitted via P2P to a node running the wallet. (#18038) + +- The size of the set of transactions that peers have announced and we consider + for requests has been reduced from 100000 to 5000 (per peer), and further + announcements will be ignored when that limit is reached. If you need to dump + (very) large batches of transactions, exceptions can be made for trusted + peers using the "relay" network permission. For localhost for example it can + be enabled using the command line option `-whitelist=relay@127.0.0.1`. + (#19988) + +- This release adds support for Tor version 3 hidden services, and rumoring them + over the network to other peers using + [BIP155](https://github.com/bitcoin/bips/blob/master/bip-0155.mediawiki). + Version 2 hidden services are still fully supported by Bitcoin Core, but the + Tor network will start + [deprecating](https://blog.torproject.org/v2-deprecation-timeline) them in the + coming months. (#19954) + +- The Tor onion service that is automatically created by setting the + `-listenonion` configuration parameter will now be created as a Tor v3 service + instead of Tor v2. The private key that was used for Tor v2 (if any) will be + left untouched in the `onion_private_key` file in the data directory (see + `-datadir`) and can be removed if not needed. Bitcoin Core will no longer + attempt to read it. The private key for the Tor v3 service will be saved in a + file named `onion_v3_private_key`. To use the deprecated Tor v2 service (not + recommended), the `onion_private_key` can be copied over + `onion_v3_private_key`, e.g. + `cp -f onion_private_key onion_v3_private_key`. (#19954) + +- The client writes a file (`anchors.dat`) at shutdown with the network addresses + of the node’s two outbound block-relay-only peers (so called "anchors"). The + next time the node starts, it reads this file and attempts to reconnect to those + same two peers. This prevents an attacker from using node restarts to trigger a + complete change in peers, which would be something they could use as part of an + eclipse attack. (#17428) + +- This release adds support for serving + [BIP157](https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki) compact + filters to peers on the network when enabled using + `-blockfilterindex=1 -peerblockfilters=1`. (#16442) + +- This release adds support for signets + ([BIP325](https://github.com/bitcoin/bips/blob/master/bip-0325.mediawiki)) in + addition to the existing mainnet, testnet, and regtest networks. Signets are + centrally-controlled test networks, allowing them to be more predictable + test environments than the older testnet. One public signet is maintained, and + selectable using `-signet`. It is also possible to create personal signets. + (#18267). + +- This release implements + [BIP339](https://github.com/bitcoin/bips/blob/master/bip-0339.mediawiki) + wtxid relay. When negotiated, transactions are announced using their wtxid + instead of their txid. (#18044). + +- This release implements the proposed Taproot consensus rules + ([BIP341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) and + [BIP342](https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki)), + without activation on mainnet. Experimentation with Taproot can be done on + signet, where its rules are already active. (#19553) + +Updated RPCs +------------ + +- The `getpeerinfo` RPC has a new `network` field that provides the type of + network ("ipv4", "ipv6", or "onion") that the peer connected through. (#20002) + +- The `getpeerinfo` RPC now has additional `last_block` and `last_transaction` + fields that return the UNIX epoch time of the last block and the last *valid* + transaction received from each peer. (#19731) + +- `getnetworkinfo` now returns two new fields, `connections_in` and + `connections_out`, that provide the number of inbound and outbound peer + connections. These new fields are in addition to the existing `connections` + field, which returns the total number of peer connections. (#19405) + +- Exposed transaction version numbers are now treated as unsigned 32-bit + integers instead of signed 32-bit integers. This matches their treatment in + consensus logic. Versions greater than 2 continue to be non-standard + (matching previous behavior of smaller than 1 or greater than 2 being + non-standard). Note that this includes the `joinpsbt` command, which combines + partially-signed transactions by selecting the highest version number. + (#16525) + +- `getmempoolinfo` now returns an additional `unbroadcastcount` field. The + mempool tracks locally submitted transactions until their initial broadcast + is acknowledged by a peer. This field returns the count of transactions + waiting for acknowledgement. + +- Mempool RPCs such as `getmempoolentry` and `getrawmempool` with + `verbose=true` now return an additional `unbroadcast` field. This indicates + whether initial broadcast of the transaction has been acknowledged by a + peer. `getmempoolancestors` and `getmempooldescendants` are also updated. + +- The `getpeerinfo` RPC no longer returns the `banscore` field unless the configuration + option `-deprecatedrpc=banscore` is used. The `banscore` field will be fully + removed in the next major release. (#19469) + +- The `testmempoolaccept` RPC returns `vsize` and a `fees` object with the `base` fee + if the transaction would pass validation. (#19940) + +- The `getpeerinfo` RPC now returns a `connection_type` field. This indicates + the type of connection established with the peer. It will return one of six + options. For more information, see the `getpeerinfo` help documentation. + (#19725) + +- The `getpeerinfo` RPC no longer returns the `addnode` field by default. This + field will be fully removed in the next major release. It can be accessed + with the configuration option `-deprecatedrpc=getpeerinfo_addnode`. However, + it is recommended to instead use the `connection_type` field (it will return + `manual` when addnode is true). (#19725) + +- The `getpeerinfo` RPC no longer returns the `whitelisted` field by default. + This field will be fully removed in the next major release. It can be accessed + with the configuration option `-deprecatedrpc=getpeerinfo_whitelisted`. However, + it is recommended to instead use the `permissions` field to understand if specific + privileges have been granted to the peer. (#19770) + +- The `walletcreatefundedpsbt` RPC call will now fail with + `Insufficient funds` when inputs are manually selected but are not enough to cover + the outputs and fee. Additional inputs can automatically be added through the + new `add_inputs` option. (#16377) + +- The `fundrawtransaction` RPC now supports `add_inputs` option that when `false` + prevents adding more inputs if necessary and consequently the RPC fails. + +Changes to Wallet or GUI related RPCs can be found in the GUI or Wallet section below. + +New RPCs +-------- + +- The `getindexinfo` RPC returns the actively running indices of the node, + including their current sync status and height. It also accepts an `index_name` + to specify returning the status of that index only. (#19550) + +Build System +------------ + +Updated settings +---------------- + +- The same ZeroMQ notification (e.g. `-zmqpubhashtx=address`) can now be + specified multiple times to publish the same notification to different ZeroMQ + sockets. (#18309) + +- The `-banscore` configuration option, which modified the default threshold for + disconnecting and discouraging misbehaving peers, has been removed as part of + changes in 0.20.1 and in this release to the handling of misbehaving peers. + Refer to "Changes regarding misbehaving peers" in the 0.20.1 release notes for + details. (#19464) + +- The `-debug=db` logging category, which was deprecated in 0.20 and replaced by + `-debug=walletdb` to distinguish it from `coindb`, has been removed. (#19202) + +- A `download` permission has been extracted from the `noban` permission. For + compatibility, `noban` implies the `download` permission, but this may change + in future releases. Refer to the help of the affected settings `-whitebind` + and `-whitelist` for more details. (#19191) + +- Netmasks that contain 1-bits after 0-bits (the 1-bits are not contiguous on + the left side, e.g. 255.0.255.255) are no longer accepted. They are invalid + according to RFC 4632. Netmasks are used in the `-rpcallowip` and `-whitelist` + configuration options and in the `setban` RPC. (#19628) + +- The `-blocksonly` setting now completely disables fee estimation. (#18766) + +Changes to Wallet or GUI related settings can be found in the GUI or Wallet section below. + +Tools and Utilities +------------------- + +- A new `bitcoin-cli -netinfo` command provides a network peer connections + dashboard that displays data from the `getpeerinfo` and `getnetworkinfo` RPCs + in a human-readable format. An optional integer argument from `0` to `4` may + be passed to see increasing levels of detail. (#19643) + +- A new `bitcoin-cli -generate` command, equivalent to RPC `generatenewaddress` + followed by `generatetoaddress`, can generate blocks for command line testing + purposes. This is a client-side version of the former `generate` RPC. See the + help for details. (#19133) + +- The `bitcoin-cli -getinfo` command now displays the wallet name and balance for + each of the loaded wallets when more than one is loaded (e.g. in multiwallet + mode) and a wallet is not specified with `-rpcwallet`. (#18594) + +- The `connections` field of `bitcoin-cli -getinfo` is now expanded to return a JSON + object with `in`, `out` and `total` numbers of peer connections. It previously + returned a single integer value for the total number of peer connections. (#19405) + +New settings +------------ + +- The `startupnotify` option is used to specify a command to + execute when Bitcoin Core has finished with its startup + sequence. (#15367) + +Wallet +------ + +- Backwards compatibility has been dropped for two `getaddressinfo` RPC + deprecations, as notified in the 0.20 release notes. The deprecated `label` + field has been removed as well as the deprecated `labels` behavior of + returning a JSON object containing `name` and `purpose` key-value pairs. Since + 0.20, the `labels` field returns a JSON array of label names. (#19200) + +- To improve wallet privacy, the frequency of wallet rebroadcast attempts is + reduced from approximately once every 15 minutes to once every 12-36 hours. + To maintain a similar level of guarantee for initial broadcast of wallet + transactions, the mempool tracks these transactions as a part of the newly + introduced unbroadcast set. See the "P2P and network changes" section for + more information on the unbroadcast set. (#18038) + +- The `sendtoaddress` and `sendmany` RPCs accept an optional `verbose=True` + argument to also return the fee reason about the sent tx. (#19501) + +- The wallet can create a transaction without change even when the keypool is + empty. Previously it failed. (#17219) + +- The `-salvagewallet` startup option has been removed. A new `salvage` command + has been added to the `bitcoin-wallet` tool which performs the salvage + operations that `-salvagewallet` did. (#18918) + +- A new configuration flag `-maxapsfee` has been added, which sets the max + allowed avoid partial spends (APS) fee. It defaults to 0 (i.e. fee is the + same with and without APS). Setting it to -1 will disable APS, unless + `-avoidpartialspends` is set. (#14582) + +- The wallet will now avoid partial spends (APS) by default, if this does not + result in a difference in fees compared to the non-APS variant. The allowed + fee threshold can be adjusted using the new `-maxapsfee` configuration + option. (#14582) + +- The `createwallet`, `loadwallet`, and `unloadwallet` RPCs now accept + `load_on_startup` options to modify the settings list. Unless these options + are explicitly set to true or false, the list is not modified, so the RPC + methods remain backwards compatible. (#15937) + +- A new `send` RPC with similar syntax to `walletcreatefundedpsbt`, including + support for coin selection and a custom fee rate, is added. The `send` RPC is + experimental and may change in subsequent releases. (#16378) + +- The `estimate_mode` parameter is now case-insensitive in the `bumpfee`, + `fundrawtransaction`, `sendmany`, `sendtoaddress`, `send` and + `walletcreatefundedpsbt` RPCs. (#11413) + +- The `bumpfee` RPC now uses `conf_target` rather than `confTarget` in the + options. (#11413) + +- `fundrawtransaction` and `walletcreatefundedpsbt` when used with the + `lockUnspents` argument now lock manually selected coins, in addition to + automatically selected coins. Note that locked coins are never used in + automatic coin selection, but can still be manually selected. (#18244) + +- The `-zapwallettxes` startup option has been removed and its functionality + removed from the wallet. This option was originally intended to allow for + rescuing wallets which were affected by a malleability attack. More recently, + it has been used in the fee bumping of transactions that did not signal RBF. + This functionality has been superseded with the abandon transaction feature. (#19671) + +- The error code when no wallet is loaded, but a wallet RPC is called, has been + changed from `-32601` (method not found) to `-18` (wallet not found). + (#20101) + +### Automatic wallet creation removed + +Bitcoin Core will no longer automatically create new wallets on startup. It will +load existing wallets specified by `-wallet` options on the command line or in +`bitcoin.conf` or `settings.json` files. And by default it will also load a +top-level unnamed ("") wallet. However, if specified wallets don't exist, +Bitcoin Core will now just log warnings instead of creating new wallets with +new keys and addresses like previous releases did. + +New wallets can be created through the GUI (which has a more prominent create +wallet option), through the `bitcoin-cli createwallet` or `bitcoin-wallet +create` commands, or the `createwallet` RPC. (#15454, #20186) + +### Experimental Descriptor Wallets + +Please note that Descriptor Wallets are still experimental and not all expected functionality +is available. Additionally there may be some bugs and current functions may change in the future. +Bugs and missing functionality can be reported to the [issue tracker](https://github.com/bitcoin/bitcoin/issues). + +0.21 introduces a new type of wallet - Descriptor Wallets. Descriptor Wallets store +scriptPubKey information using output descriptors. This is in contrast to the Legacy Wallet +structure where keys are used to implicitly generate scriptPubKeys and addresses. Because of this +shift to being script based instead of key based, many of the confusing things that Legacy +Wallets do are not possible with Descriptor Wallets. Descriptor Wallets use a definition +of "mine" for scripts which is simpler and more intuitive than that used by Legacy Wallets. +Descriptor Wallets also uses different semantics for watch-only things and imports. + +As Descriptor Wallets are a new type of wallet, their introduction does not affect existing wallets. +Users who already have a Bitcoin Core wallet can continue to use it as they did before without +any change in behavior. Newly created Legacy Wallets (which remains the default type of wallet) will +behave as they did in previous versions of Bitcoin Core. + +The differences between Descriptor Wallets and Legacy Wallets are largely limited to non user facing +things. They are intended to behave similarly except for the import/export and watchonly functionality +as described below. + +#### Creating Descriptor Wallets + +Descriptor wallets are not the default type of wallet. + +In the GUI, a checkbox has been added to the Create Wallet Dialog to indicate that a +Descriptor Wallet should be created. And a `descriptors` option has been added to `createwallet` RPC. +Setting `descriptors` to `true` will create a Descriptor Wallet instead of a Legacy Wallet. + +Without those options being set, a Legacy Wallet will be created instead. + +#### `IsMine` Semantics + +`IsMine` refers to the function used to determine whether a script belongs to the wallet. +This is used to determine whether an output belongs to the wallet. `IsMine` in Legacy Wallets +returns true if the wallet would be able to sign an input that spends an output with that script. +Since keys can be involved in a variety of different scripts, this definition for `IsMine` can +lead to many unexpected scripts being considered part of the wallet. + +With Descriptor Wallets, descriptors explicitly specify the set of scripts that are owned by +the wallet. Since descriptors are deterministic and easily enumerable, users will know exactly +what scripts the wallet will consider to belong to it. Additionally the implementation of `IsMine` +in Descriptor Wallets is far simpler than for Legacy Wallets. Notably, in Legacy Wallets, `IsMine` +allowed for users to take one type of address (e.g. P2PKH), mutate it into another address type +(e.g. P2WPKH), and the wallet would still detect outputs sending to the new address type +even without that address being requested from the wallet. Descriptor Wallets do not +allow for this and will only watch for the addresses that were explicitly requested from the wallet. + +These changes to `IsMine` will make it easier to reason about what scripts the wallet will +actually be watching for in outputs. However for the vast majority of users, this change is +largely transparent and will not have noticeable effect. + +#### Imports and Exports + +In Legacy Wallets, raw scripts and keys could be imported to the wallet. Those imported scripts +and keys are treated separately from the keys generated by the wallet. This complicates the `IsMine` +logic as it has to distinguish between spendable and watchonly. + +Descriptor Wallets handle importing scripts and keys differently. Only complete descriptors can be +imported. These descriptors are then added to the wallet as if it were a descriptor generated by +the wallet itself. This simplifies the `IsMine` logic so that it no longer has to distinguish +between spendable and watchonly. As such, the watchonly model for Descriptor Wallets is also +different and described in more detail in the next section. + +To import into a Descriptor Wallet, a new `importdescriptors` RPC has been added that uses a syntax +similar to that of `importmulti`. + +As Legacy Wallets and Descriptor Wallets use different mechanisms for storing and importing scripts and keys +the existing import RPCs have been disabled for descriptor wallets. +New export RPCs for Descriptor Wallets have not yet been added. + +The following RPCs are disabled for Descriptor Wallets: + +* `importprivkey` +* `importpubkey` +* `importaddress` +* `importwallet` +* `dumpprivkey` +* `dumpwallet` +* `importmulti` +* `addmultisigaddress` +* `sethdseed` + +#### Watchonly Wallets + +A Legacy Wallet contains both private keys and scripts that were being watched. +Those watched scripts would not contribute to your normal balance. In order to see the watchonly +balance and to use watchonly things in transactions, an `include_watchonly` option was added +to many RPCs that would allow users to do that. However it is easy to forget to include this option. + +Descriptor Wallets move to a per-wallet watchonly model. Instead an entire wallet is considered to be +watchonly depending on whether it was created with private keys disabled. This eliminates the need +to distinguish between things that are watchonly and things that are not within a wallet itself. + +This change does have a caveat. If a Descriptor Wallet with private keys *enabled* has +a multiple key descriptor without all of the private keys (e.g. `multi(...)` with only one private key), +then the wallet will fail to sign and broadcast transactions. Such wallets would need to use the PSBT +workflow but the typical GUI Send, `sendtoaddress`, etc. workflows would still be available, just +non-functional. + +This issue is worsened if the wallet contains both single key (e.g. `wpkh(...)`) descriptors and such +multiple key descriptors as some transactions could be signed and broadcast and others not. This is +due to some transactions containing only single key inputs, while others would contain both single +key and multiple key inputs, depending on which are available and how the coin selection algorithm +selects inputs. However this is not considered to be a supported use case; multisigs +should be in their own wallets which do not already have descriptors. Although users cannot export +descriptors with private keys for now as explained earlier. + +#### BIP 44/49/84 Support + +The change to using descriptors changes the default derivation paths used by Bitcoin Core +to adhere to BIP 44/49/84. Descriptors with different derivation paths can be imported without +issue. + +#### SQLite Database Backend + +Descriptor wallets use SQLite for the wallet file instead of the Berkeley DB used in legacy wallets. +This will break compatibility with any existing tooling that operates on wallets, however compatibility +was already being broken by the move to descriptors. + +### Wallet RPC changes + +- The `upgradewallet` RPC replaces the `-upgradewallet` command line option. + (#15761) + +- The `settxfee` RPC will fail if the fee was set higher than the `-maxtxfee` + command line setting. The wallet will already fail to create transactions + with fees higher than `-maxtxfee`. (#18467) + +- A new `fee_rate` parameter/option denominated in satoshis per vbyte (sat/vB) + is introduced to the `sendtoaddress`, `sendmany`, `fundrawtransaction` and + `walletcreatefundedpsbt` RPCs as well as to the experimental new `send` + RPC. The legacy `feeRate` option in `fundrawtransaction` and + `walletcreatefundedpsbt` still exists for setting a fee rate in BTC per 1,000 + vbytes (BTC/kvB), but it is expected to be deprecated soon to avoid + confusion. For these RPCs, the fee rate error message is updated from BTC/kB + to sat/vB and the help documentation in BTC/kB is updated to BTC/kvB. The + `send` and `sendtoaddress` RPC examples are updated to aid users in creating + transactions with explicit fee rates. (#20305, #11413) + +- The `bumpfee` RPC `fee_rate` option is changed from BTC/kvB to sat/vB and the + help documentation is updated. Users are warned that this is a breaking API + change, but it should be relatively benign: the large (100,000 times) + difference between BTC/kvB and sat/vB units means that a transaction with a + fee rate mistakenly calculated in BTC/kvB rather than sat/vB should raise an + error due to the fee rate being set too low. In the worst case, the + transaction may send at 1 sat/vB, but as Replace-by-Fee (BIP125 RBF) is active + by default when an explicit fee rate is used, the transaction fee can be + bumped. (#20305) + +GUI changes +----------- + +- Wallets created or loaded in the GUI will now be automatically loaded on + startup, so they don't need to be manually reloaded next time Bitcoin Core is + started. The list of wallets to load on startup is stored in + `\<datadir\>/settings.json` and augments any command line or `bitcoin.conf` + `-wallet=` settings that specify more wallets to load. Wallets that are + unloaded in the GUI get removed from the settings list so they won't load + again automatically next startup. (#19754) + +- The GUI Peers window no longer displays a "Ban Score" field. This is part of + changes in 0.20.1 and in this release to the handling of misbehaving + peers. Refer to "Changes regarding misbehaving peers" in the 0.20.1 release + notes for details. (#19512) + +Low-level changes +================= + +RPC +--- + +- To make RPC `sendtoaddress` more consistent with `sendmany` the following error + `sendtoaddress` codes were changed from `-4` to `-6`: + - Insufficient funds + - Fee estimation failed + - Transaction has too long of a mempool chain + +- The `sendrawtransaction` error code for exceeding `maxfeerate` has been changed from + `-26` to `-25`. The error string has been changed from "absurdly-high-fee" to + "Fee exceeds maximum configured by user (e.g. -maxtxfee, maxfeerate)." The + `testmempoolaccept` RPC returns `max-fee-exceeded` rather than `absurdly-high-fee` + as the `reject-reason`. (#19339) + +- To make wallet and rawtransaction RPCs more consistent, the error message for + exceeding maximum feerate has been changed to "Fee exceeds maximum configured by user + (e.g. -maxtxfee, maxfeerate)." (#19339) + +Tests +----- + +- The BIP 325 default signet can be enabled by the `-chain=signet` or `-signet` + setting. The settings `-signetchallenge` and `-signetseednode` allow + enabling a custom signet. + +- The `generateblock` RPC allows testers using regtest mode to + generate blocks that consist of a custom set of transactions. (#17693) + +0.21.0 change log +================= + +### Consensus +- #18267 BIP-325: Signet (kallewoof) +- #20016 uint256: 1 is a constant (ajtowns) +- #20006 Fix misleading error message: Clean stack rule (sanket1729) +- #19953 Implement BIP 340-342 validation (Schnorr/taproot/tapscript) (sipa) +- #20169 Taproot follow-up: Make ComputeEntrySchnorr and ComputeEntryECDSA const to clarify contract (practicalswift) + +### Policy +- #18766 Disable fee estimation in blocksonly mode (darosior) +- #19630 Cleanup fee estimation code (darosior) +- #20165 Only relay Taproot spends if next block has it active (sipa) + +### Mining +- #17946 Fix GBT: Restore "!segwit" and "csv" to "rules" key (luke-jr) + +### Privacy +- #16432 Add privacy to the Overview page (hebasto) +- #18861 Do not answer GETDATA for to-be-announced tx (sipa) +- #18038 Mempool tracks locally submitted transactions to improve wallet privacy (amitiuttarwar) +- #19109 Only allow getdata of recently announced invs (sipa) + +### Block and transaction handling +- #17737 Add ChainstateManager, remove BlockManager global (jamesob) +- #18960 indexes: Add compact block filter headers cache (jnewbery) +- #13204 Faster sigcache nonce (JeremyRubin) +- #19088 Use std::chrono throughout some validation functions (fanquake) +- #19142 Make VerifyDB level 4 interruptible (MarcoFalke) +- #17994 Flush undo files after last block write (kallewoof) +- #18990 log: Properly log txs rejected from mempool (MarcoFalke) +- #18984 Remove unnecessary input blockfile SetPos (dgenr8) +- #19526 log: Avoid treating remote misbehvior as local system error (MarcoFalke) +- #18044 Use wtxid for transaction relay (sdaftuar) +- #18637 coins: allow cache resize after init (jamesob) +- #19854 Avoid locking CTxMemPool::cs recursively in simple cases (hebasto) +- #19478 Remove CTxMempool::mapLinks data structure member (JeremyRubin) +- #19927 Reduce direct `g_chainman` usage (dongcarl) +- #19898 log: print unexpected version warning in validation log category (n-thumann) +- #20036 signet: Add assumed values for default signet (MarcoFalke) +- #20048 chainparams: do not log signet startup messages for other chains (jonatack) +- #19339 re-delegate absurd fee checking from mempool to clients (glozow) +- #20035 signet: Fix uninitialized read in validation (MarcoFalke) +- #20157 Bugfix: chainparams: Add missing (always enabled) Taproot deployment for Signet (luke-jr) +- #20263 Update assumed chain params (MarcoFalke) +- #20372 Avoid signed integer overflow when loading a mempool.dat file with a malformed time field (practicalswift) +- #18621 script: Disallow silent bool -> cscript conversion (MarcoFalke) +- #18612, #18732 script: Remove undocumented and unused operator+ (MarcoFalke) +- #19317 Add a left-justified width field to `log2_work` component for a uniform debug.log output (jamesgmorgan) + +### P2P protocol and network code +- #18544 Limit BIP37 filter lifespan (active between `filterload`..`filterclear`) (theStack) +- #18806 Remove is{Empty,Full} flags from CBloomFilter, clarify CVE fix (theStack) +- #18512 Improve asmap checks and add sanity check (sipa) +- #18877 Serve cfcheckpt requests (jnewbery) +- #18895 Unbroadcast followups: rpcs, nLastResend, mempool sanity check (gzhao408) +- #19010 net processing: Add support for `getcfheaders` (jnewbery) +- #16939 Delay querying DNS seeds (ajtowns) +- #18807 Unbroadcast follow-ups (amitiuttarwar) +- #19044 Add support for getcfilters (jnewbery) +- #19084 improve code documentation for dns seed behaviour (ajtowns) +- #19260 disconnect peers that send filterclear + update existing filter msg disconnect logic (gzhao408) +- #19284 Add seed.bitcoin.wiz.biz to DNS seeds (wiz) +- #19322 split PushInventory() (jnewbery) +- #19204 Reduce inv traffic during IBD (MarcoFalke) +- #19470 banlist: log post-swept banlist size at startup (fanquake) +- #19191 Extract download permission from noban (MarcoFalke) +- #14033 Drop `CADDR_TIME_VERSION` checks now that `MIN_PEER_PROTO_VERSION` is greater (Empact) +- #19464 net, rpc: remove -banscore option, deprecate banscore in getpeerinfo (jonatack) +- #19514 [net/net processing] check banman pointer before dereferencing (jnewbery) +- #19512 banscore updates to gui, tests, release notes (jonatack) +- #19360 improve encapsulation of CNetAddr (vasild) +- #19217 disambiguate block-relay-only variable names from blocksonly variables (glowang) +- #19473 Add -networkactive option (hebasto) +- #19472 [net processing] Reduce `cs_main` scope in MaybeDiscourageAndDisconnect() (jnewbery) +- #19583 clean up Misbehaving() (jnewbery) +- #19534 save the network type explicitly in CNetAddr (vasild) +- #19569 Enable fetching of orphan parents from wtxid peers (sipa) +- #18991 Cache responses to GETADDR to prevent topology leaks (naumenkogs) +- #19596 Deduplicate parent txid loop of requested transactions and missing parents of orphan transactions (sdaftuar) +- #19316 Cleanup logic around connection types (amitiuttarwar) +- #19070 Signal support for compact block filters with `NODE_COMPACT_FILTERS` (jnewbery) +- #19705 Shrink CAddress from 48 to 40 bytes on x64 (vasild) +- #19704 Move ProcessMessage() to PeerLogicValidation (jnewbery) +- #19628 Change CNetAddr::ip to have flexible size (vasild) +- #19797 Remove old check for 3-byte shifted IP addresses from pre-0.2.9 nodes (#19797) +- #19607 Add Peer struct for per-peer data in net processing (jnewbery) +- #19857 improve nLastBlockTime and nLastTXTime documentation (jonatack) +- #19724 Cleanup connection types- followups (amitiuttarwar) +- #19670 Protect localhost and block-relay-only peers from eviction (sdaftuar) +- #19728 Increase the ip address relay branching factor for unreachable networks (sipa) +- #19879 Miscellaneous wtxid followups (amitiuttarwar) +- #19697 Improvements on ADDR caching (naumenkogs) +- #17785 Unify Send and Receive protocol versions (hebasto) +- #19845 CNetAddr: add support to (un)serialize as ADDRv2 (vasild) +- #19107 Move all header verification into the network layer, extend logging (troygiorshev) +- #20003 Exit with error message if -proxy is specified without arguments (instead of continuing without proxy server) (practicalswift) +- #19991 Use alternative port for incoming Tor connections (hebasto) +- #19723 Ignore unknown messages before VERACK (sdaftuar) +- #19954 Complete the BIP155 implementation and upgrade to TORv3 (vasild) +- #20119 BIP155 follow-ups (sipa) +- #19988 Overhaul transaction request logic (sipa) +- #17428 Try to preserve outbound block-relay-only connections during restart (hebasto) +- #19911 Guard `vRecvGetData` with `cs_vRecv` and `orphan_work_set` with `g_cs_orphans` (narula) +- #19753 Don't add AlreadyHave transactions to recentRejects (troygiorshev) +- #20187 Test-before-evict bugfix and improvements for block-relay-only peers (sdaftuar) +- #20237 Hardcoded seeds update for 0.21 (laanwj) +- #20212 Fix output of peer address in version message (vasild) +- #20284 Ensure old versions don't parse peers.dat (vasild) +- #20405 Avoid calculating onion address checksum when version is not 3 (lontivero) +- #20564 Don't send 'sendaddrv2' to pre-70016 software, and send before 'verack' (sipa) +- #20660 Move signet onion seed from v2 to v3 (Sjors) + +### Wallet +- #18262 Exit selection when `best_waste` is 0 (achow101) +- #17824 Prefer full destination groups in coin selection (fjahr) +- #17219 Allow transaction without change if keypool is empty (Sjors) +- #15761 Replace -upgradewallet startup option with upgradewallet RPC (achow101) +- #18671 Add BlockUntilSyncedToCurrentChain to dumpwallet (MarcoFalke) +- #16528 Native Descriptor Wallets using DescriptorScriptPubKeyMan (achow101) +- #18777 Recommend absolute path for dumpwallet (MarcoFalke) +- #16426 Reverse `cs_main`, `cs_wallet` lock order and reduce `cs_main` locking (ariard) +- #18699 Avoid translating RPC errors (MarcoFalke) +- #18782 Make sure no DescriptorScriptPubKeyMan or WalletDescriptor members are left uninitialized after construction (practicalswift) +- #9381 Remove CWalletTx merging logic from AddToWallet (ryanofsky) +- #16946 Include a checksum of encrypted private keys (achow101) +- #17681 Keep inactive seeds after sethdseed and derive keys from them as needed (achow101) +- #18918 Move salvagewallet into wallettool (achow101) +- #14988 Fix for confirmed column in csv export for payment to self transactions (benthecarman) +- #18275 Error if an explicit fee rate was given but the needed fee rate differed (kallewoof) +- #19054 Skip hdKeypath of 'm' when determining inactive hd seeds (achow101) +- #17938 Disallow automatic conversion between disparate hash types (Empact) +- #19237 Check size after unserializing a pubkey (elichai) +- #11413 sendtoaddress/sendmany: Add explicit feerate option (kallewoof) +- #18850 Fix ZapSelectTx to sync wallet spends (bvbfan) +- #18923 Never schedule MaybeCompactWalletDB when `-flushwallet` is off (MarcoFalke) +- #19441 walletdb: Don't reinitialize desc cache with multiple cache entries (achow101) +- #18907 walletdb: Don't remove database transaction logs and instead error (achow101) +- #19334 Introduce WalletDatabase abstract class (achow101) +- #19335 Cleanup and separate BerkeleyDatabase and BerkeleyBatch (achow101) +- #19102 Introduce and use DummyDatabase instead of dummy BerkeleyDatabase (achow101) +- #19568 Wallet should not override signing errors (fjahr) +- #17204 Do not turn `OP_1NEGATE` in scriptSig into `0x0181` in signing code (sipa) (meshcollider) +- #19457 Cleanup wallettool salvage and walletdb extraneous declarations (achow101) +- #15937 Add loadwallet and createwallet `load_on_startup` options (ryanofsky) +- #16841 Replace GetScriptForWitness with GetScriptForDestination (meshcollider) +- #14582 always do avoid partial spends if fees are within a specified range (kallewoof) +- #19743 -maxapsfee follow-up (kallewoof) +- #19289 GetWalletTx and IsMine require `cs_wallet` lock (promag) +- #19671 Remove -zapwallettxes (achow101) +- #19805 Avoid deserializing unused records when salvaging (achow101) +- #19754 wallet, gui: Reload previously loaded wallets on startup (achow101) +- #19738 Avoid multiple BerkeleyBatch in DelAddressBook (promag) +- #19919 bugfix: make LoadWallet assigns status always (AkioNak) +- #16378 The ultimate send RPC (Sjors) +- #15454 Remove the automatic creation and loading of the default wallet (achow101) +- #19501 `send*` RPCs in the wallet returns the "fee reason" (stackman27) +- #20130 Remove db mode string (S3RK) +- #19077 Add sqlite as an alternative wallet database and use it for new descriptor wallets (achow101) +- #20125 Expose database format in getwalletinfo (promag) +- #20198 Show name, format and if uses descriptors in bitcoin-wallet tool (jonasschnelli) +- #20216 Fix buffer over-read in SQLite file magic check (theStack) +- #20186 Make -wallet setting not create wallets (ryanofsky) +- #20230 Fix bug when just created encrypted wallet cannot get address (hebasto) +- #20282 Change `upgradewallet` return type to be an object (jnewbery) +- #20220 Explicit fee rate follow-ups/fixes for 0.21 (jonatack) +- #20199 Ignore (but warn) on duplicate -wallet parameters (jonasschnelli) +- #20324 Set DatabaseStatus::SUCCESS in MakeSQLiteDatabase (MarcoFalke) +- #20266 Fix change detection of imported internal descriptors (achow101) +- #20153 Do not import a descriptor with hardened derivations into a watch-only wallet (S3RK) +- #20344 Fix scanning progress calculation for single block range (theStack) +- #19502 Bugfix: Wallet: Soft-fail exceptions within ListWalletDir file checks (luke-jr) +- #20378 Fix potential division by 0 in WalletLogPrintf (jonasschnelli) +- #18836 Upgradewallet fixes and additional tests (achow101) +- #20139 Do not return warnings from UpgradeWallet() (stackman27) +- #20305 Introduce `fee_rate` sat/vB param/option (jonatack) +- #20426 Allow zero-fee fundrawtransaction/walletcreatefundedpsbt and other fixes (jonatack) +- #20573 wallet, bugfix: allow send with string `fee_rate` amounts (jonatack) + +### RPC and other APIs +- #18574 cli: Call getbalances.ismine.trusted instead of getwalletinfo.balance (jonatack) +- #17693 Add `generateblock` to mine a custom set of transactions (andrewtoth) +- #18495 Remove deprecated migration code (vasild) +- #18493 Remove deprecated "size" from mempool txs (vasild) +- #18467 Improve documentation and return value of settxfee (fjahr) +- #18607 Fix named arguments in documentation (MarcoFalke) +- #17831 doc: Fix and extend getblockstats examples (asoltys) +- #18785 Prevent valgrind false positive in `rest_blockhash_by_height` (ryanofsky) +- #18999 log: Remove "No rpcpassword set" from logs (MarcoFalke) +- #19006 Avoid crash when `g_thread_http` was never started (MarcoFalke) +- #18594 cli: Display multiwallet balances in -getinfo (jonatack) +- #19056 Make gettxoutsetinfo/GetUTXOStats interruptible (MarcoFalke) +- #19112 Remove special case for unknown service flags (MarcoFalke) +- #18826 Expose txinwitness for coinbase in JSON form from RPC (rvagg) +- #19282 Rephrase generatetoaddress help, and use `PACKAGE_NAME` (luke-jr) +- #16377 don't automatically append inputs in walletcreatefundedpsbt (Sjors) +- #19200 Remove deprecated getaddressinfo fields (jonatack) +- #19133 rpc, cli, test: add bitcoin-cli -generate command (jonatack) +- #19469 Deprecate banscore field in getpeerinfo (jonatack) +- #16525 Dump transaction version as an unsigned integer in RPC/TxToUniv (TheBlueMatt) +- #19555 Deduplicate WriteHDKeypath() used in decodepsbt (theStack) +- #19589 Avoid useless mempool query in gettxoutproof (MarcoFalke) +- #19585 RPCResult Type of MempoolEntryDescription should be OBJ (stylesuxx) +- #19634 Document getwalletinfo's `unlocked_until` field as optional (justinmoon) +- #19658 Allow RPC to fetch all addrman records and add records to addrman (jnewbery) +- #19696 Fix addnode remove command error (fjahr) +- #18654 Separate bumpfee's psbt creation function into psbtbumpfee (achow101) +- #19655 Catch listsinceblock `target_confirmations` exceeding block count (adaminsky) +- #19644 Document returned error fields as optional if applicable (theStack) +- #19455 rpc generate: print useful help and error message (jonatack) +- #19550 Add listindices RPC (fjahr) +- #19169 Validate provided keys for `query_options` parameter in listunspent (PastaPastaPasta) +- #18244 fundrawtransaction and walletcreatefundedpsbt also lock manually selected coins (Sjors) +- #14687 zmq: Enable TCP keepalive (mruddy) +- #19405 Add network in/out connections to `getnetworkinfo` and `-getinfo` (jonatack) +- #19878 rawtransaction: Fix argument in combinerawtransaction help message (pinheadmz) +- #19940 Return fee and vsize from testmempoolaccept (gzhao408) +- #13686 zmq: Small cleanups in the ZMQ code (domob1812) +- #19386, #19528, #19717, #19849, #19994 Assert that RPCArg names are equal to CRPCCommand ones (MarcoFalke) +- #19725 Add connection type to getpeerinfo, improve logs (amitiuttarwar) +- #19969 Send RPC bug fix and touch-ups (Sjors) +- #18309 zmq: Add support to listen on multiple interfaces (n-thumann) +- #20055 Set HTTP Content-Type in bitcoin-cli (laanwj) +- #19956 Improve invalid vout value rpc error message (n1rna) +- #20101 Change no wallet loaded message to be clearer (achow101) +- #19998 Add `via_tor` to `getpeerinfo` output (hebasto) +- #19770 getpeerinfo: Deprecate "whitelisted" field (replaced by "permissions") (luke-jr) +- #20120 net, rpc, test, bugfix: update GetNetworkName, GetNetworksInfo, regression tests (jonatack) +- #20595 Improve heuristic hex transaction decoding (sipa) +- #20731 Add missing description of vout in getrawtransaction help text (benthecarman) +- #19328 Add gettxoutsetinfo `hash_type` option (fjahr) +- #19731 Expose nLastBlockTime/nLastTXTime as last `block/last_transaction` in getpeerinfo (jonatack) +- #19572 zmq: Create "sequence" notifier, enabling client-side mempool tracking (instagibbs) +- #20002 Expose peer network in getpeerinfo; simplify/improve -netinfo (jonatack) + +### GUI +- #17905 Avoid redundant tx status updates (ryanofsky) +- #18646 Use `PACKAGE_NAME` in exception message (fanquake) +- #17509 Save and load PSBT (Sjors) +- #18769 Remove bug fix for Qt < 5.5 (10xcryptodev) +- #15768 Add close window shortcut (IPGlider) +- #16224 Bilingual GUI error messages (hebasto) +- #18922 Do not translate InitWarning messages in debug.log (hebasto) +- #18152 Use NotificationStatus enum for signals to GUI (hebasto) +- #18587 Avoid wallet tryGetBalances calls in WalletModel::pollBalanceChanged (ryanofsky) +- #17597 Fix height of QR-less ReceiveRequestDialog (hebasto) +- #17918 Hide non PKHash-Addresses in signing address book (emilengler) +- #17956 Disable unavailable context menu items in transactions tab (kristapsk) +- #17968 Ensure that ModalOverlay is resized properly (hebasto) +- #17993 Balance/TxStatus polling update based on last block hash (furszy) +- #18424 Use parent-child relation to manage lifetime of OptionsModel object (hebasto) +- #18452 Fix shutdown when `waitfor*` cmds are called from RPC console (hebasto) +- #15202 Add Close All Wallets action (promag) +- #19132 lock `cs_main`, `m_cached_tip_mutex` in that order (vasild) +- #18898 Display warnings as rich text (hebasto) +- #19231 add missing translation.h include to fix build (fanquake) +- #18027 "PSBT Operations" dialog (gwillen) +- #19256 Change combiner for signals to `optional_last_value` (fanquake) +- #18896 Reset toolbar after all wallets are closed (hebasto) +- #18993 increase console command max length (10xcryptodev) +- #19323 Fix regression in *txoutset* in GUI console (hebasto) +- #19210 Get rid of cursor in out-of-focus labels (hebasto) +- #19011 Reduce `cs_main` lock accumulation during GUI startup (jonasschnelli) +- #19844 Remove usage of boost::bind (fanquake) +- #20479 Fix QPainter non-determinism on macOS (0.21 backport) (laanwj) +- gui#6 Do not truncate node flag strings in debugwindow peers details tab (Saibato) +- gui#8 Fix regression in TransactionTableModel (hebasto) +- gui#17 doc: Remove outdated comment in TransactionTablePriv (MarcoFalke) +- gui#20 Wrap tooltips in the intro window (hebasto) +- gui#30 Disable the main window toolbar when the modal overlay is shown (hebasto) +- gui#34 Show permissions instead of whitelisted (laanwj) +- gui#35 Parse params directly instead of through node (ryanofsky) +- gui#39 Add visual accenting for the 'Create new receiving address' button (hebasto) +- gui#40 Clarify block height label (hebasto) +- gui#43 bugfix: Call setWalletActionsEnabled(true) only for the first wallet (hebasto) +- gui#97 Relax GUI freezes during IBD (jonasschnelli) +- gui#71 Fix visual quality of text in QR image (hebasto) +- gui#96 Slight improve create wallet dialog (Sjors) +- gui#102 Fix SplashScreen crash when run with -disablewallet (hebasto) +- gui#116 Fix unreasonable default size of the main window without loaded wallets (hebasto) +- gui#120 Fix multiwallet transaction notifications (promag) + +### Build system +- #18504 Drop bitcoin-tx and bitcoin-wallet dependencies on libevent (ryanofsky) +- #18586 Bump gitian descriptors to 0.21 (laanwj) +- #17595 guix: Enable building for `x86_64-w64-mingw32` target (dongcarl) +- #17929 add linker optimisation flags to gitian & guix (Linux) (fanquake) +- #18556 Drop make dist in gitian builds (hebasto) +- #18088 ensure we aren't using GNU extensions (fanquake) +- #18741 guix: Make source tarball using git-archive (dongcarl) +- #18843 warn on potentially uninitialized reads (vasild) +- #17874 make linker checks more robust (fanquake) +- #18535 remove -Qunused-arguments workaround for clang + ccache (fanquake) +- #18743 Add --sysroot option to mac os native compile flags (ryanofsky) +- #18216 test, build: Enable -Werror=sign-compare (Empact) +- #18928 don't pass -w when building for Windows (fanquake) +- #16710 Enable -Wsuggest-override if available (hebasto) +- #18738 Suppress -Wdeprecated-copy warnings (hebasto) +- #18862 Remove fdelt_chk back-compat code and sanity check (fanquake) +- #18887 enable -Werror=gnu (vasild) +- #18956 enforce minimum required Windows version (7) (fanquake) +- #18958 guix: Make V=1 more powerful for debugging (dongcarl) +- #18677 Multiprocess build support (ryanofsky) +- #19094 Only allow ASCII identifiers (laanwj) +- #18820 Propagate well-known vars into depends (dongcarl) +- #19173 turn on --enable-c++17 by --enable-fuzz (vasild) +- #18297 Use pkg-config in BITCOIN_QT_CONFIGURE for all hosts including Windows (hebasto) +- #19301 don't warn when doxygen isn't found (fanquake) +- #19240 macOS toolchain simplification and bump (dongcarl) +- #19356 Fix search for brew-installed BDB 4 on OS X (gwillen) +- #19394 Remove unused `RES_IMAGES` (Bushstar) +- #19403 improve `__builtin_clz*` detection (fanquake) +- #19375 target Windows 7 when building libevent and fix ipv6 usage (fanquake) +- #19331 Do not include server symbols in wallet (MarcoFalke) +- #19257 remove BIP70 configure option (fanquake) +- #18288 Add MemorySanitizer (MSan) in Travis to detect use of uninitialized memory (practicalswift) +- #18307 Require pkg-config for all of the hosts (hebasto) +- #19445 Update msvc build to use ISO standard C++17 (sipsorcery) +- #18882 fix -Wformat-security check when compiling with GCC (fanquake) +- #17919 Allow building with system clang (dongcarl) +- #19553 pass -fcommon when building genisoimage (fanquake) +- #19565 call `AC_PATH_TOOL` for dsymutil in macOS cross-compile (fanquake) +- #19530 build LTO support into Apple's ld64 (theuni) +- #19525 add -Wl,-z,separate-code to hardening flags (fanquake) +- #19667 set minimum required Boost to 1.58.0 (fanquake) +- #19672 make clean removes .gcda and .gcno files from fuzz directory (Crypt-iQ) +- #19622 Drop ancient hack in gitian-linux descriptor (hebasto) +- #19688 Add support for llvm-cov (hebasto) +- #19718 Add missed gcov files to 'make clean' (hebasto) +- #19719 Add Werror=range-loop-analysis (MarcoFalke) +- #19015 Enable some commonly enabled compiler diagnostics (practicalswift) +- #19689 build, qt: Add Qt version checking (hebasto) +- #17396 modest Android improvements (icota) +- #18405 Drop all of the ZeroMQ patches (hebasto) +- #15704 Move Win32 defines to configure.ac to ensure they are globally defined (luke-jr) +- #19761 improve sed robustness by not using sed (fanquake) +- #19758 Drop deprecated and unused `GUARDED_VAR` and `PT_GUARDED_VAR` annotations (hebasto) +- #18921 add stack-clash and control-flow protection options to hardening flags (fanquake) +- #19803 Bugfix: Define and use `HAVE_FDATASYNC` correctly outside LevelDB (luke-jr) +- #19685 CMake invocation cleanup (dongcarl) +- #19861 add /usr/local/ to `LCOV_FILTER_PATTERN` for macOS builds (Crypt-iQ) +- #19916 allow user to specify `DIR_FUZZ_SEED_CORPUS` for `cov_fuzz` (Crypt-iQ) +- #19944 Update secp256k1 subtree (including BIP340 support) (sipa) +- #19558 Split pthread flags out of ldflags and dont use when building libconsensus (fanquake) +- #19959 patch qt libpng to fix powerpc build (fanquake) +- #19868 Fix target name (hebasto) +- #19960 The vcpkg tool has introduced a proper way to use manifests (sipsorcery) +- #20065 fuzz: Configure check for main function (MarcoFalke) +- #18750 Optionally skip external warnings (vasild) +- #20147 Update libsecp256k1 (endomorphism, test improvements) (sipa) +- #20156 Make sqlite support optional (compile-time) (luke-jr) +- #20318 Ensure source tarball has leading directory name (MarcoFalke) +- #20447 Patch `qt_intersect_spans` to avoid non-deterministic behavior in LLVM 8 (achow101) +- #20505 Avoid secp256k1.h include from system (dergoegge) +- #20527 Do not ignore Homebrew's SQLite on macOS (hebasto) +- #20478 Don't set BDB flags when configuring without (jonasschnelli) +- #20563 Check that Homebrew's berkeley-db4 package is actually installed (hebasto) +- #19493 Fix clang build on Mac (bvbfan) + +### Tests and QA +- #18593 Complete impl. of `msg_merkleblock` and `wait_for_merkleblock` (theStack) +- #18609 Remove REJECT message code (hebasto) +- #18584 Check that the version message does not leak the local address (MarcoFalke) +- #18597 Extend `wallet_dump` test to cover comments (MarcoFalke) +- #18596 Try once more when RPC connection fails on Windows (MarcoFalke) +- #18451 shift coverage from getunconfirmedbalance to getbalances (jonatack) +- #18631 appveyor: Disable functional tests for now (MarcoFalke) +- #18628 Add various low-level p2p tests (MarcoFalke) +- #18615 Avoid accessing free'd memory in `validation_chainstatemanager_tests` (MarcoFalke) +- #18571 fuzz: Disable debug log file (MarcoFalke) +- #18653 add coverage for bitcoin-cli -rpcwait (jonatack) +- #18660 Verify findCommonAncestor always initializes outputs (ryanofsky) +- #17669 Have coins simulation test also use CCoinsViewDB (jamesob) +- #18662 Replace gArgs with local argsman in bench (MarcoFalke) +- #18641 Create cached blocks not in the future (MarcoFalke) +- #18682 fuzz: `http_request` workaround for libevent < 2.1.1 (theStack) +- #18692 Bump timeout in `wallet_import_rescan` (MarcoFalke) +- #18695 Replace boost::mutex with std::mutex (hebasto) +- #18633 Properly raise FailedToStartError when rpc shutdown before warmup finished (MarcoFalke) +- #18675 Don't initialize PrecomputedTransactionData in txvalidationcache tests (jnewbery) +- #18691 Add `wait_for_cookie_credentials()` to framework for rpcwait tests (jonatack) +- #18672 Add further BIP37 size limit checks to `p2p_filter.py` (theStack) +- #18721 Fix linter issue (hebasto) +- #18384 More specific `feature_segwit` test error messages and fixing incorrect comments (gzhao408) +- #18575 bench: Remove requirement that all benches use same testing setup (MarcoFalke) +- #18690 Check object hashes in `wait_for_getdata` (robot-visions) +- #18712 display command line options passed to `send_cli()` in debug log (jonatack) +- #18745 Check submitblock return values (MarcoFalke) +- #18756 Use `wait_for_getdata()` in `p2p_compactblocks.py` (theStack) +- #18724 Add coverage for -rpcwallet cli option (jonatack) +- #18754 bench: Add caddrman benchmarks (vasild) +- #18585 Use zero-argument super() shortcut (Python 3.0+) (theStack) +- #18688 fuzz: Run in parallel (MarcoFalke) +- #18770 Remove raw-tx byte juggling in `mempool_reorg` (MarcoFalke) +- #18805 Add missing `sync_all` to `wallet_importdescriptors.py` (achow101) +- #18759 bench: Start nodes with -nodebuglogfile (MarcoFalke) +- #18774 Added test for upgradewallet RPC (brakmic) +- #18485 Add `mempool_updatefromblock.py` (hebasto) +- #18727 Add CreateWalletFromFile test (ryanofsky) +- #18726 Check misbehavior more independently in `p2p_filter.py` (robot-visions) +- #18825 Fix message for `ECC_InitSanityCheck` test (fanquake) +- #18576 Use unittest for `test_framework` unit testing (gzhao408) +- #18828 Strip down previous releases boilerplate (MarcoFalke) +- #18617 Add factor option to adjust test timeouts (brakmic) +- #18855 `feature_backwards_compatibility.py` test downgrade after upgrade (achow101) +- #18864 Add v0.16.3 backwards compatibility test, bump v0.19.0.1 to v0.19.1 (Sjors) +- #18917 fuzz: Fix vector size problem in system fuzzer (brakmic) +- #18901 fuzz: use std::optional for `sep_pos_opt` variable (brakmic) +- #18888 Remove RPCOverloadWrapper boilerplate (MarcoFalke) +- #18952 Avoid os-dependent path (fametrano) +- #18938 Fill fuzzing coverage gaps for functions in consensus/validation.h, primitives/block.h and util/translation.h (practicalswift) +- #18986 Add capability to disable RPC timeout in functional tests (rajarshimaitra) +- #18530 Add test for -blocksonly and -whitelistforcerelay param interaction (glowang) +- #19014 Replace `TEST_PREVIOUS_RELEASES` env var with `test_framework` option (MarcoFalke) +- #19052 Don't limit fuzzing inputs to 1 MB for afl-fuzz (now: ∞ ∀ fuzzers) (practicalswift) +- #19060 Remove global `wait_until` from `p2p_getdata` (MarcoFalke) +- #18926 Pass ArgsManager into `getarg_tests` (glowang) +- #19110 Explain that a bug should be filed when the tests fail (MarcoFalke) +- #18965 Implement `base58_decode` (10xcryptodev) +- #16564 Always define the `raii_event_tests` test suite (candrews) +- #19122 Add missing `sync_blocks` to `wallet_hd` (MarcoFalke) +- #18875 fuzz: Stop nodes in `process_message*` fuzzers (MarcoFalke) +- #18974 Check that invalid witness destinations can not be imported (MarcoFalke) +- #18210 Type hints in Python tests (kiminuo) +- #19159 Make valgrind.supp work on aarch64 (MarcoFalke) +- #19082 Moved the CScriptNum asserts into the unit test in script.py (gillichu) +- #19172 Do not swallow flake8 exit code (hebasto) +- #19188 Avoid overwriting the NodeContext member of the testing setup [-Wshadow-field] (MarcoFalke) +- #18890 `disconnect_nodes` should warn if nodes were already disconnected (robot-visions) +- #19227 change blacklist to blocklist (TrentZ) +- #19230 Move base58 to own module to break circular dependency (sipa) +- #19083 `msg_mempool`, `fRelay`, and other bloomfilter tests (gzhao408) +- #16756 Connection eviction logic tests (mzumsande) +- #19177 Fix and clean `p2p_invalid_messages` functional tests (troygiorshev) +- #19264 Don't import asyncio to test magic bytes (jnewbery) +- #19178 Make `mininode_lock` non-reentrant (jnewbery) +- #19153 Mempool compatibility test (S3RK) +- #18434 Add a test-security target and run it in CI (fanquake) +- #19252 Wait for disconnect in `disconnect_p2ps` + bloomfilter test followups (gzhao408) +- #19298 Add missing `sync_blocks` (MarcoFalke) +- #19304 Check that message sends successfully when header is split across two buffers (troygiorshev) +- #19208 move `sync_blocks` and `sync_mempool` functions to `test_framework.py` (ycshao) +- #19198 Check that peers with forcerelay permission are not asked to feefilter (MarcoFalke) +- #19351 add two edge case tests for CSubNet (vasild) +- #19272 net, test: invalid p2p messages and test framework improvements (jonatack) +- #19348 Bump linter versions (duncandean) +- #19366 Provide main(…) function in fuzzer. Allow building uninstrumented harnesses with --enable-fuzz (practicalswift) +- #19412 move `TEST_RUNNER_EXTRA` into native tsan setup (fanquake) +- #19368 Improve functional tests compatibility with BSD/macOS (S3RK) +- #19028 Set -logthreadnames in unit tests (MarcoFalke) +- #18649 Add std::locale::global to list of locale dependent functions (practicalswift) +- #19140 Avoid fuzzer-specific nullptr dereference in libevent when handling PROXY requests (practicalswift) +- #19214 Auto-detect SHA256 implementation in benchmarks (sipa) +- #19353 Fix mistakenly swapped "previous" and "current" lock orders (hebasto) +- #19533 Remove unnecessary `cs_mains` in `denialofservice_tests` (jnewbery) +- #19423 add functional test for txrelay during and after IBD (gzhao408) +- #16878 Fix non-deterministic coverage of test `DoS_mapOrphans` (davereikher) +- #19548 fuzz: add missing overrides to `signature_checker` (jonatack) +- #19562 Fix fuzzer compilation on macOS (freenancial) +- #19370 Static asserts for consistency of fee defaults (domob1812) +- #19599 clean `message_count` and `last_message` (troygiorshev) +- #19597 test decodepsbt fee calculation (count input value only once per UTXO) (theStack) +- #18011 Replace current benchmarking framework with nanobench (martinus) +- #19489 Fail `wait_until` early if connection is lost (MarcoFalke) +- #19340 Preserve the `LockData` initial state if "potential deadlock detected" exception thrown (hebasto) +- #19632 Catch decimal.InvalidOperation from `TestNodeCLI#send_cli` (Empact) +- #19098 Remove duplicate NodeContext hacks (ryanofsky) +- #19649 Restore test case for p2p transaction blinding (instagibbs) +- #19657 Wait until `is_connected` in `add_p2p_connection` (MarcoFalke) +- #19631 Wait for 'cmpctblock' in `p2p_compactblocks` when it is expected (Empact) +- #19674 use throwaway _ variable for unused loop counters (theStack) +- #19709 Fix 'make cov' with clang (hebasto) +- #19564 `p2p_feefilter` improvements (logging, refactoring, speedup) (theStack) +- #19756 add `sync_all` to fix race condition in wallet groups test (kallewoof) +- #19727 Removing unused classes from `p2p_leak.py` (dhruv) +- #19722 Add test for getblockheader verboseness (torhte) +- #19659 Add a seed corpus generation option to the fuzzing `test_runner` (darosior) +- #19775 Activate segwit in TestChain100Setup (MarcoFalke) +- #19760 Remove confusing mininode terminology (jnewbery) +- #19752 Update `wait_until` usage in tests not to use the one from utils (slmtpz) +- #19839 Set appveyor VM version to previous Visual Studio 2019 release (sipsorcery) +- #19830 Add tsan supp for leveldb::DBImpl::DeleteObsoleteFiles (MarcoFalke) +- #19710 bench: Prevent thread oversubscription and decreases the variance of result values (hebasto) +- #19842 Update the vcpkg checkout commit ID in appveyor config (sipsorcery) +- #19507 Expand functional zmq transaction tests (instagibbs) +- #19816 Rename wait until helper to `wait_until_helper` (MarcoFalke) +- #19859 Fixes failing functional test by changing version (n-thumann) +- #19887 Fix flaky `wallet_basic` test (fjahr) +- #19897 Change `FILE_CHAR_BLOCKLIST` to `FILE_CHARS_DISALLOWED` (verretor) +- #19800 Mockwallet (MarcoFalke) +- #19922 Run `rpc_txoutproof.py` even with wallet disabled (MarcoFalke) +- #19936 batch rpc with params (instagibbs) +- #19971 create default wallet in extended tests (Sjors) +- #19781 add parameterized constructor for `msg_sendcmpct()` (theStack) +- #19963 Clarify blocksonly whitelistforcerelay test (t-bast) +- #20022 Use explicit p2p objects where available (guggero) +- #20028 Check that invalid peer traffic is accounted for (MarcoFalke) +- #20004 Add signet witness commitment section parse tests (MarcoFalke) +- #20034 Get rid of default wallet hacks (ryanofsky) +- #20069 Mention commit id in scripted diff error (laanwj) +- #19947 Cover `change_type` option of "walletcreatefundedpsbt" RPC (guggero) +- #20126 `p2p_leak_tx.py` improvements (use MiniWallet, add `p2p_lock` acquires) (theStack) +- #20129 Don't export `in6addr_loopback` (vasild) +- #20131 Remove unused nVersion=1 in p2p tests (MarcoFalke) +- #20161 Minor Taproot follow-ups (sipa) +- #19401 Use GBT to get block versions correct (luke-jr) +- #20159 `mining_getblocktemplate_longpoll.py` improvements (use MiniWallet, add logging) (theStack) +- #20039 Convert amounts from float to decimal (prayank23) +- #20112 Speed up `wallet_resendwallettransactions` with mockscheduler RPC (MarcoFalke) +- #20247 fuzz: Check for addrv1 compatibility before using addrv1 serializer. Fuzz addrv2 serialization (practicalswift) +- #20167 Add test for -blockversion (MarcoFalke) +- #19877 Clarify `rpc_net` & `p2p_disconnect_ban functional` tests (amitiuttarwar) +- #20258 Remove getnettotals/getpeerinfo consistency test (jnewbery) +- #20242 fuzz: Properly initialize PrecomputedTransactionData (MarcoFalke) +- #20262 Skip --descriptor tests if sqlite is not compiled (achow101) +- #18788 Update more tests to work with descriptor wallets (achow101) +- #20289 fuzz: Check for addrv1 compatibility before using addrv1 serializer/deserializer on CService (practicalswift) +- #20290 fuzz: Fix DecodeHexTx fuzzing harness issue (practicalswift) +- #20245 Run `script_assets_test` even if built --with-libs=no (MarcoFalke) +- #20300 fuzz: Add missing `ECC_Start` to `descriptor_parse` test (S3RK) +- #20283 Only try witness deser when checking for witness deser failure (MarcoFalke) +- #20303 fuzz: Assert expected DecodeHexTx behaviour when using legacy decoding (practicalswift) +- #20316 Fix `wallet_multiwallet` test issue on Windows (MarcoFalke) +- #20326 Fix `ecdsa_verify` in test framework (stepansnigirev) +- #20328 cirrus: Skip tasks on the gui repo main branch (MarcoFalke) +- #20355 fuzz: Check for addrv1 compatibility before using addrv1 serializer/deserializer on CSubNet (practicalswift) +- #20332 Mock IBD in `net_processing` fuzzers (MarcoFalke) +- #20218 Suppress `epoll_ctl` data race (MarcoFalke) +- #20375 fuzz: Improve coverage for CPartialMerkleTree fuzzing harness (practicalswift) +- #19669 contrib: Fixup valgrind suppressions file (MarcoFalke) +- #18879 valgrind: remove outdated suppressions (fanquake) +- #19226 Add BerkeleyDatabase tsan suppression (MarcoFalke) +- #20379 Remove no longer needed UBSan suppression (float divide-by-zero in validation.cpp) (practicalswift) +- #18190, #18736, #18744, #18775, #18783, #18867, #18994, #19065, + #19067, #19143, #19222, #19247, #19286, #19296, #19379, #19934, + #20188, #20395 Add fuzzing harnessses (practicalswift) +- #18638 Use mockable time for ping/pong, add tests (MarcoFalke) +- #19951 CNetAddr scoped ipv6 test coverage, rename scopeId to `m_scope_id` (jonatack) +- #20027 Use mockable time everywhere in `net_processing` (sipa) +- #19105 Add Muhash3072 implementation in Python (fjahr) +- #18704, #18752, #18753, #18765, #18839, #18866, #18873, #19022, + #19023, #19429, #19552, #19778, #20176, #20179, #20214, #20292, + #20299, #20322 Fix intermittent test issues (MarcoFalke) +- #20390 CI/Cirrus: Skip `merge_base` step for non-PRs (luke-jr) +- #18634 ci: Add fuzzbuzz integration configuration file (practicalswift) +- #18591 Add C++17 build to Travis (sipa) +- #18581, #18667, #18798, #19495, #19519, #19538 CI improvements (hebasto) +- #18683, #18705, #18735, #18778, #18799, #18829, #18912, #18929, + #19008, #19041, #19164, #19201, #19267, #19276, #19321, #19371, + #19427, #19730, #19746, #19881, #20294, #20339, #20368 CI improvements (MarcoFalke) +- #20489, #20506 MSVC CI improvements (sipsorcery) + +### Miscellaneous +- #18713 scripts: Add macho stack canary check to security-check.py (fanquake) +- #18629 scripts: Add pe .reloc section check to security-check.py (fanquake) +- #18437 util: `Detect posix_fallocate()` instead of assuming (vasild) +- #18413 script: Prevent ub when computing abs value for num opcode serialize (pierreN) +- #18443 lockedpool: avoid sensitive data in core files (FreeBSD) (vasild) +- #18885 contrib: Move optimize-pngs.py script to the maintainer repo (MarcoFalke) +- #18317 Serialization improvements step 6 (all except wallet/gui) (sipa) +- #16127 More thread safety annotation coverage (ajtowns) +- #19228 Update libsecp256k1 subtree (sipa) +- #19277 util: Add assert identity function (MarcoFalke) +- #19491 util: Make assert work with any value (MarcoFalke) +- #19205 script: `previous_release.sh` rewritten in python (bliotti) +- #15935 Add <datadir>/settings.json persistent settings storage (ryanofsky) +- #19439 script: Linter to check commit message formatting (Ghorbanian) +- #19654 lint: Improve commit message linter in travis (fjahr) +- #15382 util: Add runcommandparsejson (Sjors) +- #19614 util: Use `have_fdatasync` to determine fdatasync() use (fanquake) +- #19813 util, ci: Hard code previous release tarball checksums (hebasto) +- #19841 Implement Keccak and `SHA3_256` (sipa) +- #19643 Add -netinfo peer connections dashboard (jonatack) +- #15367 feature: Added ability for users to add a startup command (benthecarman) +- #19984 log: Remove static log message "Initializing chainstate Chainstate [ibd] @ height -1 (null)" (practicalswift) +- #20092 util: Do not use gargs global in argsmanager member functions (hebasto) +- #20168 contrib: Fix `gen_key_io_test_vectors.py` imports (MarcoFalke) +- #19624 Warn on unknown `rw_settings` (MarcoFalke) +- #20257 Update secp256k1 subtree to latest master (sipa) +- #20346 script: Modify security-check.py to use "==" instead of "is" for literal comparison (tylerchambers) +- #18881 Prevent UB in DeleteLock() function (hebasto) +- #19180, #19189, #19190, #19220, #19399 Replace RecursiveMutex with Mutex (hebasto) +- #19347 Make `cs_inventory` nonrecursive (jnewbery) +- #19773 Avoid recursive lock in IsTrusted (promag) +- #18790 Improve thread naming (hebasto) +- #20140 Restore compatibility with old CSubNet serialization (sipa) +- #17775 DecodeHexTx: Try case where txn has inputs first (instagibbs) + +### Documentation +- #18502 Update docs for getbalance (default minconf should be 0) (uzyn) +- #18632 Fix macos comments in release-notes (MarcoFalke) +- #18645 Update thread information in developer docs (jnewbery) +- #18709 Note why we can't use `thread_local` with glibc back compat (fanquake) +- #18410 Improve commenting for coins.cpp|h (jnewbery) +- #18157 fixing init.md documentation to not require rpcpassword (jkcd) +- #18739 Document how to fuzz Bitcoin Core using Honggfuzz (practicalswift) +- #18779 Better explain GNU ld's dislike of ld64's options (fanquake) +- #18663 Mention build docs in README.md (saahilshangle) +- #18810 Update rest info on block size and json (chrisabrams) +- #18939 Add c++17-enable flag to fuzzing instructions (mzumsande) +- #18957 Add a link from ZMQ doc to ZMQ example in contrib/ (meeDamian) +- #19058 Drop protobuf stuff (hebasto) +- #19061 Add link to Visual Studio build readme (maitrebitcoin) +- #19072 Expand section on Getting Started (MarcoFalke) +- #18968 noban precludes maxuploadtarget disconnects (MarcoFalke) +- #19005 Add documentation for 'checklevel' argument in 'verifychain' RPC… (kcalvinalvin) +- #19192 Extract net permissions doc (MarcoFalke) +- #19071 Separate repository for the gui (MarcoFalke) +- #19018 fixing description of the field sequence in walletcreatefundedpsbt RPC method (limpbrains) +- #19367 Span pitfalls (sipa) +- #19408 Windows WSL build recommendation to temporarily disable Win32 PE support (sipsorcery) +- #19407 explain why passing -mlinker-version is required when cross-compiling (fanquake) +- #19452 afl fuzzing comment about afl-gcc and afl-g++ (Crypt-iQ) +- #19258 improve subtree check instructions (Sjors) +- #19474 Use precise permission flags where possible (MarcoFalke) +- #19494 CONTRIBUTING.md improvements (jonatack) +- #19268 Add non-thread-safe note to FeeFilterRounder::round() (hebasto) +- #19547 Update macOS cross compilation dependencies for Focal (hebasto) +- #19617 Clang 8 or later is required with `FORCE_USE_SYSTEM_CLANG` (fanquake) +- #19639 Remove Reference Links #19582 (RobertHosking) +- #19605 Set `CC_FOR_BUILD` when building on OpenBSD (fanquake) +- #19765 Fix getmempoolancestors RPC result doc (MarcoFalke) +- #19786 Remove label from good first issue template (MarcoFalke) +- #19646 Updated outdated help command for getblocktemplate (jakeleventhal) +- #18817 Document differences in bitcoind and bitcoin-qt locale handling (practicalswift) +- #19870 update PyZMQ install instructions, fix `zmq_sub.py` file permissions (jonatack) +- #19903 Update build-openbsd.md with GUI support (grubles) +- #19241 help: Generate checkpoint height from chainparams (luke-jr) +- #18949 Add CODEOWNERS file to automatically nominate PR reviewers (adamjonas) +- #20014 Mention signet in -help output (hebasto) +- #20015 Added default signet config for linearize script (gr0kchain) +- #19958 Better document features of feelers (naumenkogs) +- #19871 Clarify scope of eviction protection of outbound block-relay peers (ariard) +- #20076 Update and improve files.md (hebasto) +- #20107 Collect release-notes snippets (MarcoFalke) +- #20109 Release notes and followups from 19339 (glozow) +- #20090 Tiny followups to new getpeerinfo connection type field (amitiuttarwar) +- #20152 Update wallet files in files.md (hebasto) +- #19124 Document `ALLOW_HOST_PACKAGES` dependency option (skmcontrib) +- #20271 Document that wallet salvage is experimental (MarcoFalke) +- #20281 Correct getblockstats documentation for `(sw)total_weight` (shesek) +- #20279 release process updates/fixups (jonatack) +- #20238 Missing comments for signet parameters (decryp2kanon) +- #20756 Add missing field (permissions) to the getpeerinfo help (amitiuttarwar) +- #20668 warn that incoming conns are unlikely when not using default ports (adamjonas) +- #19961 tor.md updates (jonatack) +- #19050 Add warning for rest interface limitation (fjahr) +- #19390 doc/REST-interface: Remove stale info (luke-jr) +- #19344 docs: update testgen usage example (Bushstar) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- 10xcryptodev +- Aaron Clauson +- Aaron Hook +- Adam Jonas +- Adam Soltys +- Adam Stein +- Akio Nakamura +- Alex Willmer +- Amir Ghorbanian +- Amiti Uttarwar +- Andrew Chow +- Andrew Toth +- Anthony Fieroni +- Anthony Towns +- Antoine Poinsot +- Antoine Riard +- Ben Carman +- Ben Woosley +- Benoit Verret +- Brian Liotti +- Bushstar +- Calvin Kim +- Carl Dong +- Chris Abrams +- Chris L +- Christopher Coverdale +- codeShark149 +- Cory Fields +- Craig Andrews +- Damian Mee +- Daniel Kraft +- Danny Lee +- David Reikher +- DesWurstes +- Dhruv Mehta +- Duncan Dean +- Elichai Turkel +- Elliott Jin +- Emil Engler +- Ethan Heilman +- eugene +- Fabian Jahr +- fanquake +- Ferdinando M. Ametrano +- freenancial +- furszy +- Gillian Chu +- Gleb Naumenko +- Glenn Willen +- Gloria Zhao +- glowang +- gr0kchain +- Gregory Sanders +- grubles +- gzhao408 +- Harris +- Hennadii Stepanov +- Hugo Nguyen +- Igor Cota +- Ivan Metlushko +- Ivan Vershigora +- Jake Leventhal +- James O'Beirne +- Jeremy Rubin +- jgmorgan +- Jim Posen +- “jkcd” +- jmorgan +- John Newbery +- Johnson Lau +- Jon Atack +- Jonas Schnelli +- Jonathan Schoeller +- João Barbosa +- Justin Moon +- kanon +- Karl-Johan Alm +- Kiminuo +- Kristaps Kaupe +- lontivero +- Luke Dashjr +- Marcin Jachymiak +- MarcoFalke +- Martin Ankerl +- Martin Zumsande +- maskoficarus +- Matt Corallo +- Matthew Zipkin +- MeshCollider +- Miguel Herranz +- MIZUTA Takeshi +- mruddy +- Nadav Ivgi +- Neha Narula +- Nicolas Thumann +- Niklas Gögge +- Nima Yazdanmehr +- nsa +- nthumann +- Oliver Gugger +- pad +- pasta +- Peter Bushnell +- pierrenn +- Pieter Wuille +- practicalswift +- Prayank +- Raúl Martínez (RME) +- RandyMcMillan +- Rene Pickhardt +- Riccardo Masutti +- Robert +- Rod Vagg +- Roy Shao +- Russell Yanofsky +- Saahil Shangle +- sachinkm77 +- saibato +- Samuel Dobson +- sanket1729 +- Sebastian Falbesoner +- Seleme Topuz +- Sishir Giri +- Sjors Provoost +- skmcontrib +- Stepan Snigirev +- Stephan Oeste +- Suhas Daftuar +- t-bast +- Tom Harding +- Torhte Butler +- TrentZ +- Troy Giorshev +- tryphe +- Tyler Chambers +- U-Zyn Chua +- Vasil Dimov +- wiz +- Wladimir J. van der Laan + +As well as to everyone that helped with translations on +[Transifex](https://www.transifex.com/bitcoin/bitcoin/). diff --git a/doc/release-notes/release-notes-0.21.1.md b/doc/release-notes/release-notes-0.21.1.md new file mode 100644 index 0000000000..d032fa8429 --- /dev/null +++ b/doc/release-notes/release-notes-0.21.1.md @@ -0,0 +1,203 @@ +0.21.1 Release Notes +==================== + +Bitcoin Core version 0.21.1 is now available from: + + <https://bitcoincore.org/bin/bitcoin-core-0.21.1/> + +This minor release includes 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 in some cases), then run the +installer (on Windows) or just copy over `/Applications/Bitcoin-Qt` (on Mac) +or `bitcoind`/`bitcoin-qt` (on Linux). + +Upgrading directly from a version of Bitcoin Core that has reached its EOL is +possible, but it might take some time if the data directory 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.12+, and Windows 7 and newer. Bitcoin +Core should also work on most other Unix-like systems but is not as +frequently tested on them. It is not recommended to use Bitcoin Core on +unsupported systems. + +From Bitcoin Core 0.20.0 onwards, macOS versions earlier than 10.12 are no +longer supported. Additionally, Bitcoin Core does not yet change appearance +when macOS "dark mode" is activated. + +Notable changes +=============== + +## Taproot Soft Fork + +Included in this release are the mainnet and testnet activation +parameters for the taproot soft fork (BIP341) which also adds support +for schnorr signatures (BIP340) and tapscript (BIP342). + +If activated, these improvements will allow users of single-signature +scripts, multisignature scripts, and complex contracts to all use +identical-appearing commitments that enhance their privacy and the +fungibility of all bitcoins. Spenders will enjoy lower fees and the +ability to resolve many multisig scripts and complex contracts with the +same efficiency, low fees, and large anonymity set as single-sig users. +Taproot and schnorr also include efficiency improvements for full nodes +such as the ability to batch signature verification. Together, the +improvements lay the groundwork for future potential +upgrades that may improve efficiency, privacy, and fungibility further. + +Activation for taproot is being managed using a variation of BIP9 +versionbits called Speedy Trial (described in BIP341). Taproot's +versionbit is bit 2, and nodes will begin tracking which blocks signal +support for taproot at the beginning of the first retarget period after +taproot’s start date of 24 April 2021. If 90% of blocks within a +2,016-block retarget period (about two weeks) signal support for taproot +prior to the first retarget period beginning after the time of 11 August +2021, the soft fork will be locked in, and taproot will then be active +as of block 709632 (expected in early or mid November). + +Should taproot not be locked in via Speedy Trial activation, it is +expected that a follow-up activation mechanism will be deployed, with +changes to address the reasons the Speedy Trial method failed. + +This release includes the ability to pay taproot addresses, although +payments to such addresses are not secure until taproot activates. +It also includes the ability to relay and mine taproot transactions +after activation. Beyond those two basic capabilities, this release +does not include any code that allows anyone to directly use taproot. +The addition of taproot-related features to Bitcoin Core's wallet is +expected in later releases once taproot activation is assured. + +All users, businesses, and miners are encouraged to upgrade to this +release (or a subsequent compatible release) unless they object to +activation of taproot. If taproot is locked in, then upgrading before +block 709632 is highly recommended to help enforce taproot's new rules +and to avoid the unlikely case of seeing falsely confirmed transactions. + +Miners who want to activate Taproot should preferably use this release +to control their signaling. The `getblocktemplate` RPC results will +automatically be updated to signal once the appropriate start has been +reached and continue signaling until the timeout occurs or taproot +activates. Alternatively, miners may manually start signaling on bit 2 +at any time; if taproot activates, they will need to ensure they update +their nodes before block 709632 or non-upgraded nodes could cause them to mine on +an invalid chain. See the [versionbits +FAQ](https://bitcoincore.org/en/2016/06/08/version-bits-miners-faq/) for +details. + + +For more information about taproot, please see the following resources: + +- Technical specifications + - [BIP340 Schnorr signatures for secp256k1](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki) + - [BIP341 Taproot: SegWit version 1 spending rules](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) + - [BIP342 Validation of Taproot scripts](https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki) + +- Popular articles; + - [Taproot Is Coming: What It Is, and How It Will Benefit Bitcoin](https://bitcoinmagazine.com/technical/taproot-coming-what-it-and-how-it-will-benefit-bitcoin) + - [What do Schnorr Signatures Mean for Bitcoin?](https://academy.binance.com/en/articles/what-do-schnorr-signatures-mean-for-bitcoin) + - [The Schnorr Signature & Taproot Softfork Proposal](https://blog.bitmex.com/the-schnorr-signature-taproot-softfork-proposal/) + +- Development history overview + - [Taproot](https://bitcoinops.org/en/topics/taproot/) + - [Schnorr signatures](https://bitcoinops.org/en/topics/schnorr-signatures/) + - [Tapscript](https://bitcoinops.org/en/topics/tapscript/) + - [Soft fork activation](https://bitcoinops.org/en/topics/soft-fork-activation/) + +- Other + - [Questions and answers related to taproot](https://bitcoin.stackexchange.com/questions/tagged/taproot) + - [Taproot review](https://github.com/ajtowns/taproot-review) + +Updated RPCs +------------ + +- Due to [BIP 350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) + being implemented, behavior for all RPCs that accept addresses is changed when + a native witness version 1 (or higher) is passed. These now require a Bech32m + encoding instead of a Bech32 one, and Bech32m encoding will be used for such + addresses in RPC output as well. No version 1 addresses should be created + for mainnet until consensus rules are adopted that give them meaning + (e.g. through [BIP 341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki)). + Once that happens, Bech32m is expected to be used for them, so this shouldn't + affect any production systems, but may be observed on other networks where such + addresses already have meaning (like signet). + +0.21.1 change log +================= + +### Consensus +- #21377 Speedy trial support for versionbits (ajtowns) +- #21686 Speedy trial activation parameters for Taproot (achow101) + +### P2P protocol and network code +- #20852 allow CSubNet of non-IP networks (vasild) +- #21043 Avoid UBSan warning in ProcessMessage(…) (practicalswift) + +### Wallet +- #21166 Introduce DeferredSignatureChecker and have SignatureExtractorClass subclass it (achow101) +- #21083 Avoid requesting fee rates multiple times during coin selection (achow101) + +### RPC and other APIs +- #21201 Disallow sendtoaddress and sendmany when private keys disabled (achow101) + +### Build system +- #21486 link against -lsocket if required for `*ifaddrs` (fanquake) +- #20983 Fix MSVC build after gui#176 (hebasto) + +### Tests and QA +- #21380 Add fuzzing harness for versionbits (ajtowns) +- #20812 fuzz: Bump FuzzedDataProvider.h (MarcoFalke) +- #20740 fuzz: Update FuzzedDataProvider.h from upstream (LLVM) (practicalswift) +- #21446 Update vcpkg checkout commit (sipsorcery) +- #21397 fuzz: Bump FuzzedDataProvider.h (MarcoFalke) +- #21081 Fix the unreachable code at `feature_taproot` (brunoerg) +- #20562 Test that a fully signed tx given to signrawtx is unchanged (achow101) +- #21571 Make sure non-IP peers get discouraged and disconnected (vasild, MarcoFalke) +- #21489 fuzz: cleanups for versionbits fuzzer (ajtowns) + +### Miscellaneous +- #20861 BIP 350: Implement Bech32m and use it for v1+ segwit addresses (sipa) + +### Documentation +- #21384 add signet to bitcoin.conf documentation (jonatack) +- #21342 Remove outdated comment (hebasto) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Aaron Clauson +- Andrew Chow +- Anthony Towns +- Bruno Garcia +- Fabian Jahr +- fanquake +- Hennadii Stepanov +- Jon Atack +- Luke Dashjr +- MarcoFalke +- Pieter Wuille +- practicalswift +- randymcmillan +- Sjors Provoost +- Vasil Dimov +- W. J. van der Laan + +As well as to everyone that helped with translations on +[Transifex](https://www.transifex.com/bitcoin/bitcoin/). diff --git a/doc/release-process.md b/doc/release-process.md index a61b67c35f..3ead1181b9 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -5,7 +5,7 @@ Release Process ### 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 translations 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`). @@ -18,20 +18,20 @@ Release Process ### Before every 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) + - update `CLIENT_VERSION_MAJOR` in [`configure.ac`](../configure.ac) + - update `CLIENT_VERSION_MAJOR`, `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_MINOR` to `0` + - set `CLIENT_VERSION_BUILD` to `0` - set `CLIENT_VERSION_IS_RELEASE` to `true` #### Before branch-off * 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/17002) 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 `src/chainparams.cpp` nMinimumChainWork with information from the getblockchaininfo rpc. -* Update `src/chainparams.cpp` defaultAssumeValid with information from the getblockhash rpc. +* 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-assumed-blockchain-and-chain-state-size) for information on how to calculate them). +* Update [`src/chainparams.cpp`](/src/chainparams.cpp) chainTxData with statistics about the transaction count and rate. Use the output of the `getchaintxstats` RPC, see + [this pull request](https://github.com/bitcoin/bitcoin/pull/20263) for an example. Reviewers can verify the results by running `getchaintxstats <window_block_count> <window_final_block_hash>` with the `window_block_count` and `window_final_block_hash` from your output. +* Update `src/chainparams.cpp` nMinimumChainWork and defaultAssumeValid (and the block height comment) with information from the `getblockheader` (and `getblockhash`) RPCs. - The selected value must not be orphaned so it may be useful to set the value two blocks back from the tip. - Testnet should be set some tens of thousands back from the tip due to reorgs there. - This update should be reviewed with a reindex-chainstate with assumevalid=0 to catch any defect @@ -52,6 +52,13 @@ Release Process - 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. +#### Tagging a release (candidate) + +To tag the version (or release candidate) in git, use the `make-tag.py` script from [bitcoin-maintainer-tools](https://github.com/bitcoin-core/bitcoin-maintainer-tools). From the root of the repository run: + + ../bitcoin-maintainer-tools/make-tag.py v(new version, e.g. 0.20.0) + +This will perform a few last-minute consistency checks in the build system files, and if they pass, create a signed tag. ## Building @@ -73,21 +80,12 @@ Open a draft of the release notes for collaborative editing at https://github.co 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). +Generate the change log. As this is a huge amount of work to do manually, there is the `list-pulls` script to do a pre-sorting step based on github PR metadata. See the [documentation in the README.md](https://github.com/bitcoin-core/bitcoin-maintainer-tools/blob/master/README.md#list-pulls). Generate list of authors: git log --format='- %aN' v(current version, e.g. 0.20.0)..v(new version, e.g. 0.20.1) | sort -fiu -Tag the version (or release candidate) in git: - - git tag -s v(new version, e.g. 0.20.0) - ### Setup and perform Gitian builds If you're using the automated script (found in [contrib/gitian-build.py](/contrib/gitian-build.py)), then at this point you should run it with the "--build" command. Otherwise ignore this. @@ -307,9 +305,9 @@ bitcoin.org (see below for bitcoin.org update instructions). - First, check to see if the Bitcoin.org maintainers have prepared a release: https://github.com/bitcoin-dot-org/bitcoin.org/labels/Core - - If they have, it will have previously failed their Travis CI + - If they have, it will have previously failed their CI checks because the final release files weren't uploaded. - Trigger a Travis CI rebuild---if it passes, merge. + Trigger a CI rebuild---if it passes, merge. - If they have not prepared a release, follow the Bitcoin.org release instructions: https://github.com/bitcoin-dot-org/bitcoin.org/blob/master/docs/adding-events-release-notes-and-alerts.md#release-notes @@ -326,6 +324,18 @@ bitcoin.org (see below for bitcoin.org update instructions). - bitcoincore.org RPC documentation update + - Install [golang](https://golang.org/doc/install) + + - Install the new Bitcoin Core release + + - Run bitcoind on regtest + + - Clone the [bitcoincore.org repository](https://github.com/bitcoin-core/bitcoincore.org) + + - Run: `go run generate.go` while being in `contrib/doc-gen` folder, and with bitcoin-cli in PATH + + - Add the generated files to git + - Update packaging repo - Push the flatpak to flathub, e.g. https://github.com/flathub/org.bitcoincore.bitcoin-qt/pull/2 @@ -363,15 +373,13 @@ bitcoin.org (see below for bitcoin.org update instructions). - Bitcoin Core announcements list https://bitcoincore.org/en/list/announcements/join/ - - Update title of #bitcoin on Freenode IRC - - - Optionally twitter, reddit /r/Bitcoin, ... but this will usually sort out itself + - Bitcoin Core Twitter https://twitter.com/bitcoincoreorg - Celebrate ### Additional information -#### How to calculate `m_assumed_blockchain_size` and `m_assumed_chain_state_size` +#### <a name="how-to-calculate-assumed-blockchain-and-chain-state-size"></a>How to calculate `m_assumed_blockchain_size` and `m_assumed_chain_state_size` Both variables are used as a guideline for how much space the user needs on their drive in total, not just strictly for the blockchain. Note that all values should be taken from a **fully synced** node and have an overhead of 5-10% added on top of its base value. diff --git a/doc/shared-libraries.md b/doc/shared-libraries.md index e960863a80..147e223711 100644 --- a/doc/shared-libraries.md +++ b/doc/shared-libraries.md @@ -41,9 +41,10 @@ The interface is defined in the C header `bitcoinconsensus.h` located in `src/sc - `bitcoinconsensus_ERR_TX_SIZE_MISMATCH` - `txToLen` did not match with the size of `txTo` - `bitcoinconsensus_ERR_DESERIALIZE` - An error deserializing `txTo` - `bitcoinconsensus_ERR_AMOUNT_REQUIRED` - Input amount is required if WITNESS is used +- `bitcoinconsensus_ERR_INVALID_FLAGS` - Script verification `flags` are invalid (i.e. not part of the libconsensus interface) ### Example Implementations -- [NBitcoin](https://github.com/NicolasDorier/NBitcoin/blob/master/NBitcoin/Script.cs#L814) (.NET Bindings) +- [NBitcoin](https://github.com/MetacoSA/NBitcoin/blob/5e1055cd7c4186dee4227c344af8892aea54faec/NBitcoin/Script.cs#L979-#L1031) (.NET Bindings) - [node-libbitcoinconsensus](https://github.com/bitpay/node-libbitcoinconsensus) (Node.js Bindings) - [java-libbitcoinconsensus](https://github.com/dexX7/java-libbitcoinconsensus) (Java Bindings) - [bitcoinconsensus-php](https://github.com/Bit-Wasp/bitcoinconsensus-php) (PHP Bindings) diff --git a/doc/tor.md b/doc/tor.md index 2c54e32f84..7d134b64e0 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -1,134 +1,225 @@ # TOR SUPPORT IN BITCOIN -It is possible to run Bitcoin Core as a Tor hidden service, and connect to such services. +It is possible to run Bitcoin Core as a Tor onion service, and connect to such services. The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly configure Tor. +## Compatibility + +- Starting with version 22.0, Bitcoin Core only supports Tor version 3 hidden + services (Tor v3). Tor v2 addresses are ignored by Bitcoin Core and neither + relayed nor stored. + +- Tor removed v2 support beginning with version 0.4.6. + +## How to see information about your Tor configuration via Bitcoin Core + +There are several ways to see your local onion address in Bitcoin Core: +- in the debug log (grep for "tor:" or "AddLocal") +- in the output of RPC `getnetworkinfo` in the "localaddresses" section +- in the output of the CLI `-netinfo` peer connections dashboard + +You may set the `-debug=tor` config logging option to have additional +information in the debug log about your Tor configuration. + +CLI `-addrinfo` returns the number of addresses known to your node per network +type, including Tor v2 and v3. This is useful to see how many onion addresses +are known to your node for `-onlynet=onion` and how many Tor v3 addresses it +knows when upgrading to Bitcoin Core v22.0 and up that supports Tor v3 only. ## 1. Run Bitcoin Core behind a Tor proxy The first step is running Bitcoin Core behind a Tor proxy. This will already anonymize all outgoing connections, but more is possible. - -proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy - server will be used to try to reach .onion addresses as well. + -proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy + server will be used to try to reach .onion addresses as well. + You need to use -noonion or -onion=0 to explicitly disable + outbound access to onion services. + + -onion=ip:port Set the proxy server to use for Tor onion services. You do not + need to set this if it's the same as -proxy. You can use -onion=0 + to explicitly disable access to onion services. + Note: Only the -proxy option sets the proxy for DNS requests; + with -onion they will not route over Tor, so use -proxy if you + have privacy concerns. + + -listen When using -proxy, listening is disabled by default. If you want + to manually configure an onion service (see section 3), you'll + need to enable it explicitly. + + -connect=X When behind a Tor proxy, you can specify .onion addresses instead + -addnode=X of IP addresses or hostnames in these parameters. It requires + -seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with + 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. If you use this option with values other + than onion you *cannot* disable onion connections; outgoing onion + connections will be enabled when you use -proxy or -onion. Use + -noonion or -onion=0 if you want to be sure there are no outbound + onion connections over the default proxy or your defined -proxy. - -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 services. +In a typical situation, this suffices to run behind a Tor proxy: - -listen When using -proxy, listening is disabled by default. If you want - to run a hidden service (see next section), you'll need to enable - it explicitly. + ./bitcoind -proxy=127.0.0.1:9050 - -connect=X When behind a Tor proxy, you can specify .onion addresses instead - -addnode=X of IP addresses or hostnames in these parameters. It requires - -seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with - other P2P nodes. +## 2. Automatically create a Bitcoin Core onion service - -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. +Bitcoin Core makes use of Tor's control socket API to create and destroy +ephemeral onion services programmatically. This means that if Tor is running and +proper authentication has been configured, Bitcoin Core automatically creates an +onion service to listen on. The goal is to increase the number of available +onion nodes. -In a typical situation, this suffices to run behind a Tor proxy: +This feature is enabled by default if Bitcoin Core is listening (`-listen`) and +it requires a Tor connection to work. It can be explicitly disabled with +`-listenonion=0`. If it is not disabled, it can be configured using the +`-torcontrol` and `-torpassword` settings. + +To see verbose Tor information in the bitcoind debug log, pass `-debug=tor`. + +### Control Port + +You may need to set up the Tor Control Port. On Linux distributions there may be +some or all of the following settings in `/etc/tor/torrc`, generally commented +out by default (if not, add them): + +``` +ControlPort 9051 +CookieAuthentication 1 +CookieAuthFileGroupReadable 1 +``` + +Add or uncomment those, save, and restart Tor (usually `systemctl restart tor` +or `sudo systemctl restart tor` on most systemd-based systems, including recent +Debian and Ubuntu, or just restart the computer). + +On some systems (such as Arch Linux), you may also need to add the following +line: + +``` +DataDirectoryGroupReadable 1 +``` + +### Authentication + +Connecting to Tor's control socket API requires one of two authentication +methods to be configured: cookie authentication or bitcoind's `-torpassword` +configuration option. + +#### Cookie authentication + +For cookie authentication, the user running bitcoind must have read access to +the `CookieAuthFile` specified in the Tor configuration. In some cases this is +preconfigured and the creation of an onion service is automatic. Don't forget to +use the `-debug=tor` bitcoind configuration option to enable Tor debug logging. + +If a permissions problem is seen in the debug log, e.g. `tor: Authentication +cookie /run/tor/control.authcookie could not be opened (check permissions)`, it +can be resolved by adding both the user running Tor and the user running +bitcoind to the same Tor group and setting permissions appropriately. + +On Debian-derived systems, the Tor group will likely be `debian-tor` and one way +to verify could be to list the groups and grep for a "tor" group name: + +``` +getent group | cut -d: -f1 | grep -i tor +``` + +You can also check the group of the cookie file. On most Linux systems, the Tor +auth cookie will usually be `/run/tor/control.authcookie`: + +``` +stat -c '%G' /run/tor/control.authcookie +``` + +Once you have determined the `${TORGROUP}` and selected the `${USER}` that will +run bitcoind, run this as root: + +``` +usermod -a -G ${TORGROUP} ${USER} +``` + +Then restart the computer (or log out) and log in as the `${USER}` that will run +bitcoind. + +#### `torpassword` authentication + +For the `-torpassword=password` option, the password is the clear text form that +was used when generating the hashed password for the `HashedControlPassword` +option in the Tor configuration file. + +The hashed password can be obtained with the command `tor --hash-password +password` (refer to the [Tor Dev +Manual](https://2019.www.torproject.org/docs/tor-manual.html.en) for more +details). - ./bitcoind -proxy=127.0.0.1:9050 +## 3. Manually create a Bitcoin Core onion service -## 2. Run a Bitcoin Core hidden server +You can also manually configure your node to be reachable from the Tor network. +Add these lines to your `/etc/tor/torrc` (or equivalent config file): -If you configure your Tor system accordingly, it is possible to make your node also -reachable from the Tor network. Add these lines to your /etc/tor/torrc (or equivalent -config file): *Needed for Tor version 0.2.7.0 and older versions of Tor only. For newer -versions of Tor see [Section 3](#3-automatically-listen-on-tor).* + HiddenServiceDir /var/lib/tor/bitcoin-service/ + HiddenServicePort 8333 127.0.0.1:8334 - HiddenServiceDir /var/lib/tor/bitcoin-service/ - HiddenServicePort 8333 127.0.0.1:8333 - HiddenServicePort 18333 127.0.0.1:18333 +The directory can be different of course, but virtual port numbers should be equal to +your bitcoind's P2P listen port (8333 by default), and target addresses and ports +should be equal to binding address and port for inbound Tor connections (127.0.0.1:8334 by default). -The directory can be different of course, but (both) port numbers should be equal to -your bitcoind's P2P listen port (8333 by default). + -externalip=X You can tell bitcoin about its publicly reachable addresses using + this option, and this can be an onion address. Given the above + configuration, you can find your onion address in + /var/lib/tor/bitcoin-service/hostname. For connections + coming from unroutable addresses (such as 127.0.0.1, where the + Tor proxy typically runs), onion addresses are given + preference for your node to advertise itself with. - -externalip=X You can tell bitcoin about its publicly reachable address using - this option, and this can be a .onion address. Given the above - configuration, you can find your .onion address in - /var/lib/tor/bitcoin-service/hostname. For connections - coming from unroutable addresses (such as 127.0.0.1, where the - Tor proxy typically runs), .onion addresses are given - preference for your node to advertise itself with. + You can set multiple local addresses with -externalip. The + one that will be rumoured to a particular peer is the most + compatible one and also using heuristics, e.g. the address + with the most incoming connections, etc. - -listen You'll need to enable listening for incoming connections, as this - is off by default behind a proxy. + -listen You'll need to enable listening for incoming connections, as this + is off by default behind a proxy. - -discover When -externalip is specified, no attempt is made to discover local - IPv4 or IPv6 addresses. If you want to run a dual stack, reachable - from both Tor and IPv4 (or IPv6), you'll need to either pass your - other addresses using -externalip, or explicitly enable -discover. - Note that both addresses of a dual-stack system may be easily - linkable using traffic analysis. + -discover When -externalip is specified, no attempt is made to discover local + IPv4 or IPv6 addresses. If you want to run a dual stack, reachable + from both Tor and IPv4 (or IPv6), you'll need to either pass your + other addresses using -externalip, or explicitly enable -discover. + Note that both addresses of a dual-stack system may be easily + linkable using traffic analysis. In a typical situation, where you're only reachable via Tor, this should suffice: - ./bitcoind -proxy=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -listen + ./bitcoind -proxy=127.0.0.1:9050 -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion -listen (obviously, replace the .onion address with your own). It should be noted that you still listen on all devices and another node could establish a clearnet connection, when knowing your address. To mitigate this, additionally bind the address of your Tor proxy: - ./bitcoind ... -bind=127.0.0.1 + ./bitcoind ... -bind=127.0.0.1 If you don't care too much about hiding your node, and want to be reachable on IPv4 as well, use `discover` instead: - ./bitcoind ... -discover + ./bitcoind ... -discover -and open port 8333 on your firewall (or use -upnp). +and open port 8333 on your firewall (or use port mapping, i.e., `-upnp` or `-natpmp`). If you only want to use Tor to reach .onion addresses, but not use it as a proxy for normal IPv4/IPv6 communication, use: - ./bitcoind -onion=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover - -## 3. Automatically listen on Tor - -Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket -API, to create and destroy 'ephemeral' hidden services programmatically. -Bitcoin Core has been updated to make use of this. - -This means that if Tor is running (and proper authentication has been configured), -Bitcoin Core automatically creates a hidden service to listen on. This will positively -affect the number of available .onion nodes. - -This new feature is enabled by default if Bitcoin Core is listening (`-listen`), and -requires a Tor connection to work. It can be explicitly disabled with `-listenonion=0` -and, if not disabled, configured using the `-torcontrol` and `-torpassword` settings. -To show verbose debugging information, pass `-debug=tor`. - -Connecting to Tor's control socket API requires one of two authentication methods to be -configured. It also requires the control socket to be enabled, e.g. put `ControlPort 9051` -in `torrc` config file. For cookie authentication the user running bitcoind must have read -access to the `CookieAuthFile` specified in Tor configuration. In some cases this is -preconfigured and the creation of a hidden service is automatic. If permission problems -are seen with `-debug=tor` they can be resolved by adding both the user running Tor and -the user running bitcoind to the same group and setting permissions appropriately. On -Debian-based systems the user running bitcoind can be added to the debian-tor group, -which has the appropriate permissions. 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 -was used when generating the hashed password for the `HashedControlPassword` option -in the tor configuration file. The hashed password can be obtained with the command -`tor --hash-password password` (read the tor manual for more details). + ./bitcoind -onion=127.0.0.1:9050 -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion -discover ## 4. Privacy recommendations -- Do not add anything but Bitcoin Core ports to the hidden service created in section 2. - If you run a web service too, create a new hidden service for that. - Otherwise it is trivial to link them, which may reduce privacy. Hidden - services created automatically (as in section 3) always have only one port +- Do not add anything but Bitcoin Core ports to the onion service created in section 3. + If you run a web service too, create a new onion service for that. + Otherwise it is trivial to link them, which may reduce privacy. Onion + services created automatically (as in section 2) always have only one port open. diff --git a/doc/translation_process.md b/doc/translation_process.md index 39f878cea3..f132693264 100644 --- a/doc/translation_process.md +++ b/doc/translation_process.md @@ -22,8 +22,6 @@ cd src/ make translate ``` -`contrib/bitcoin-qt.pro` takes care of generating `.qm` (binary compiled) files from `.ts` (source files) files. It’s mostly automated, and you shouldn’t need to worry about it. - **Example Qt translation** ```cpp QToolBar *toolbar = addToolBar(tr("Tabs toolbar")); @@ -104,6 +102,5 @@ To create a new language template, you will need to edit the languages manifest **Note:** that the language translation file **must end in `.qm`** (the compiled extension), and not `.ts`. ### Questions and general assistance -The Bitcoin-Core translation maintainers include *tcatm, seone, Diapolo, wumpus and luke-jr*. You can find them, and others, in the Freenode IRC chatroom - `irc.freenode.net #bitcoin-core-dev`. If you are a translator, you should also subscribe to the mailing list, https://groups.google.com/forum/#!forum/bitcoin-translators. Announcements will be posted during application pre-releases to notify translators to check for updates. diff --git a/doc/translation_strings_policy.md b/doc/translation_strings_policy.md index 634aca3559..1931302dda 100644 --- a/doc/translation_strings_policy.md +++ b/doc/translation_strings_policy.md @@ -23,7 +23,8 @@ On a high level, these strings are to be translated: ### GUI strings -Anything that appears to the user in the GUI is to be translated. This includes labels, menu items, button texts, tooltips and window titles. +Do not translate technical or extremely rare errors. +Anything else that appears to the user in the GUI is to be translated. This includes labels, menu items, button texts, tooltips and window titles. This includes messages passed to the GUI through the UI interface through `InitMessage`, `ThreadSafeMessageBox` or `ShowProgress`. General recommendations diff --git a/doc/zmq.md b/doc/zmq.md index a309abd0cc..85f3370130 100644 --- a/doc/zmq.md +++ b/doc/zmq.md @@ -1,6 +1,6 @@ # Block and Transaction Broadcasting with ZeroMQ -[ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP +[ZeroMQ](https://zeromq.org/) is a lightweight wrapper around TCP connections, inter-process communication, and shared-memory, providing various message-oriented semantics such as publish/subscribe, request/reply, and push/pull. @@ -39,8 +39,9 @@ For version information, see [dependencies.md](dependencies.md). Typically, it is packaged by distributions as something like *libzmq3-dev*. The C++ wrapper for ZeroMQ is *not* needed. -In order to run the example Python client scripts in contrib/ one must -also install *python3-zmq*, though this is not necessary for daemon +In order to run the example Python client scripts in the `contrib/zmq/` +directory, one must also install [PyZMQ](https://github.com/zeromq/pyzmq) +(generally with `pip install pyzmq`), though this is not necessary for daemon operation. ## Enabling @@ -62,9 +63,11 @@ Currently, the following notifications are supported: -zmqpubhashblock=address -zmqpubrawblock=address -zmqpubrawtx=address + -zmqpubsequence=address The socket type is PUB and the address must be a valid ZeroMQ socket address. The same address can be used in more than one notification. +The same notification can be specified more than once. The option to set the PUB socket's outbound message high water mark (SNDHWM) may be set individually for each notification: @@ -73,12 +76,14 @@ The option to set the PUB socket's outbound message high water mark -zmqpubhashblockhwm=n -zmqpubrawblockhwm=n -zmqpubrawtxhwm=n + -zmqpubsequencehwm=address The high water mark value must be an integer greater than or equal to 0. For instance: $ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \ + -zmqpubhashtx=tcp://192.168.1.2:28332 \ -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw \ -zmqpubhashtxhwm=10000 @@ -86,7 +91,15 @@ Each PUB notification has a topic and body, where the header corresponds to the notification type. For instance, for the notification `-zmqpubhashtx` the topic is `hashtx` (no null terminator) and the body is the transaction hash (32 -bytes). +bytes) for all but `sequence` topic. For `sequence`, the body +is structured as the following based on the type of message: + + <32-byte hash>C : Blockhash connected + <32-byte hash>D : Blockhash disconnected + <32-byte hash>R<8-byte LE uint> : Transactionhash removed from mempool for non-block inclusion reason + <32-byte hash>A<8-byte LE uint> : Transactionhash added mempool + +Where the 8-byte uints correspond to the mempool sequence number. These options can also be provided in bitcoin.conf. @@ -96,7 +109,21 @@ ZeroMQ endpoint specifiers for TCP (and others) are documented in the Client side, then, the ZeroMQ subscriber socket must have the ZMQ_SUBSCRIBE option set to one or either of these prefixes (for instance, just `hash`); without doing so will result in no messages -arriving. Please see `contrib/zmq/zmq_sub.py` for a working example. +arriving. Please see [`contrib/zmq/zmq_sub.py`](/contrib/zmq/zmq_sub.py) for a working example. + +The ZMQ_PUB socket's ZMQ_TCP_KEEPALIVE option is enabled. This means that +the underlying SO_KEEPALIVE option is enabled when using a TCP transport. +The effective TCP keepalive values are managed through the underlying +operating system configuration and must be configured prior to connection establishment. + +For example, when running on GNU/Linux, one might use the following +to lower the keepalive setting to 10 minutes: + +sudo sysctl -w net.ipv4.tcp_keepalive_time=600 + +Setting the keepalive values appropriately for your operating environment may +improve connectivity in situations where long-lived connections are silently +dropped by network middle boxes. ## Remarks @@ -109,13 +136,20 @@ No authentication or authorization is done on connecting clients; it is assumed that the ZeroMQ port is exposed only to trusted entities, using other means such as firewalling. -Note that when the block chain tip changes, a reorganisation may occur -and just the tip will be notified. It is up to the subscriber to -retrieve the chain from the last known block to the new tip. Also note -that no notification occurs if the tip was in the active chain - this -is the case after calling invalidateblock RPC. +Note that for `*block` topics, 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. Also note that no notification will occur if the tip +was in the active chain--as would be the case after calling invalidateblock RPC. +In contrast, the `sequence` topic publishes all block connections and +disconnections. There are several possibilities that ZMQ notification can get lost during transmission depending on the communication type you are using. Bitcoind appends an up-counting sequence number to each notification which allows listeners to detect lost notifications. + +The `sequence` topic refers specifically to the mempool sequence +number, which is also published along with all mempool events. This +is a different sequence value than in ZMQ itself in order to allow a total +ordering of mempool events to be constructed. |