diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/JSON-RPC-interface.md | 38 | ||||
| -rw-r--r-- | doc/README.md | 10 | ||||
| -rw-r--r-- | doc/REST-interface.md | 6 | ||||
| -rw-r--r-- | doc/bitcoin-conf.md | 37 | ||||
| -rw-r--r-- | doc/build-freebsd.md | 20 | ||||
| -rw-r--r-- | doc/build-openbsd.md | 12 | ||||
| -rw-r--r-- | doc/build-osx.md | 14 | ||||
| -rw-r--r-- | doc/build-unix.md | 22 | ||||
| -rw-r--r-- | doc/build-windows.md | 18 | ||||
| -rw-r--r-- | doc/descriptors.md | 91 | ||||
| -rw-r--r-- | doc/developer-notes.md | 2 | ||||
| -rw-r--r-- | doc/release-notes-13152.md | 3 | ||||
| -rw-r--r-- | doc/release-notes-14282.md | 3 | ||||
| -rw-r--r-- | doc/release-notes-14296.md | 5 | ||||
| -rw-r--r-- | doc/release-notes-14454.md | 6 | ||||
| -rw-r--r-- | doc/release-notes-14468.md | 15 | ||||
| -rw-r--r-- | doc/release-notes/release-notes-0.17.0.1.md | 41 | ||||
| -rw-r--r-- | doc/release-notes/release-notes-0.17.0.md | 2 | ||||
| -rw-r--r-- | doc/release-process.md | 2 | ||||
| -rw-r--r-- | doc/zmq.md | 13 |
20 files changed, 293 insertions, 67 deletions
diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md new file mode 100644 index 0000000000..59df541567 --- /dev/null +++ b/doc/JSON-RPC-interface.md @@ -0,0 +1,38 @@ +# JSON-RPC Interface + +The headless daemon `bitcoind` has the JSON-RPC API enabled by default, the GUI +`bitcoin-qt` has it disabled by default. This can be changed with the `-server` +option. In the GUI it is possible to execute RPC methods in the Debug Console +Dialog. + +## RPC consistency guarantees + +State that can be queried via RPCs is guaranteed to be at least up-to-date with +the chain state immediately prior to the call's execution. However, the state +returned by RPCs that reflect the mempool may not be up-to-date with the +current mempool state. + +### Transaction Pool + +The mempool state returned via an RPC is consistent with itself and with the +chain state at the time of the call. Thus, the mempool state only encompasses +transactions that are considered mine-able by the node at the time of the RPC. + +The mempool state returned via an RPC reflects all effects of mempool and chain +state related RPCs that returned prior to this call. + +### Wallet + +The wallet state returned via an RPC is consistent with itself and with the +chain state at the time of the call. + +Wallet RPCs will return the latest chain state consistent with prior non-wallet +RPCs. The effects of all blocks (and transactions in blocks) at the time of the +call is reflected in the state of all wallet transactions. For example, if a +block contains transactions that conflicted with mempool transactions, the +wallet would reflect the removal of these mempool transactions in the state. + +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. diff --git a/doc/README.md b/doc/README.md index b3f875c4a4..344b1be5c4 100644 --- a/doc/README.md +++ b/doc/README.md @@ -3,7 +3,7 @@ Bitcoin Core Setup --------------------- -Bitcoin Core is the original Bitcoin client and it builds the backbone of the network. It downloads and, by default, stores the entire history of Bitcoin transactions (which is currently more than 100 GBs); depending on the speed of your computer and network connection, the synchronization process can take anywhere from a few hours to a day or more. +Bitcoin Core is the original Bitcoin client and it builds the backbone of the network. It downloads and, by default, stores the entire history of Bitcoin transactions, which requires a few hundred gigabytes of disk space. Depending on the speed of your computer and network connection, the synchronization process can take anywhere from a few hours to a day or more. To download Bitcoin Core, visit [bitcoincore.org](https://bitcoincore.org/en/releases/). @@ -30,7 +30,7 @@ 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](http://webchat.freenode.net?channels=bitcoin) on Freenode. If you don't have an IRC client use [webchat here](http://webchat.freenode.net?channels=bitcoin). +* Ask for help on [#bitcoin](http://webchat.freenode.net?channels=bitcoin) on Freenode. If you don't have an IRC client, use [webchat here](http://webchat.freenode.net?channels=bitcoin). * Ask for help on the [BitcoinTalk](https://bitcointalk.org/) forums, in the [Technical Support board](https://bitcointalk.org/index.php?board=4.0). Building @@ -56,6 +56,7 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th - [Translation Process](translation_process.md) - [Translation Strings Policy](translation_strings_policy.md) - [Travis CI](travis-ci.md) +- [JSON-RPC Interface](JSON-RPC-interface.md) - [Unauthenticated REST Interface](REST-interface.md) - [Shared Libraries](shared-libraries.md) - [BIPS](bips.md) @@ -64,11 +65,12 @@ 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](http://webchat.freenode.net/?channels=bitcoin-core-dev). -* Discuss general Bitcoin development on #bitcoin-dev on Freenode. If you don't have an IRC client use [webchat here](http://webchat.freenode.net/?channels=bitcoin-dev). +* Discuss project-specific development on #bitcoin-core-dev on Freenode. If you don't have an IRC client, use [webchat here](http://webchat.freenode.net/?channels=bitcoin-core-dev). +* Discuss general Bitcoin development on #bitcoin-dev on Freenode. If you don't have an IRC client, use [webchat here](http://webchat.freenode.net/?channels=bitcoin-dev). ### Miscellaneous - [Assets Attribution](assets-attribution.md) +- [bitcoin.conf Configuration File](bitcoin-conf.md) - [Files](files.md) - [Fuzz-testing](fuzzing.md) - [Reduce Traffic](reduce-traffic.md) diff --git a/doc/REST-interface.md b/doc/REST-interface.md index 7010edfcd3..44df698382 100644 --- a/doc/REST-interface.md +++ b/doc/REST-interface.md @@ -6,6 +6,12 @@ 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. +REST Interface consistency guarantees +------------------------------------- + +The [same guarantees as for the RPC Interface](/doc/JSON-RPC-interface.md#rpc-consistency-guarantees) +apply. + Supported API ------------- diff --git a/doc/bitcoin-conf.md b/doc/bitcoin-conf.md new file mode 100644 index 0000000000..88ecb8fe65 --- /dev/null +++ b/doc/bitcoin-conf.md @@ -0,0 +1,37 @@ +# `bitcoin.conf` Configuration File + +The configuration file is used by `bitcoind`, `bitcoin-qt` and `bitcoin-cli`. + +All command-line options (except for `-?`, `-help`, `-version` and `-conf`) may be specified in a configuration file, and all configuration file options (except for `includeconf`) may also be specified on the command line. Command-line options override values set in the configuration file and configuration file options override values set in the GUI. + +## Configuration File Format + +The configuration file is a plain text file and consists of `option=value` entries, one per line. Leading and trailing whitespaces are removed. + +In contrast to the command-line usage: +- an option must be specified without leading `-`; +- a value of the given option is mandatory; e.g., `testnet=1` (for chain selection options), `noconnect=1` (for negated options). + +### Blank lines + +Blank lines are allowed and ignored by the parser. + +### Comments + +A comment starts with a number sign (`#`) and extends to the end of the line. All comments are ignored by the parser. + +Comments may appear in two ways: +- on their own on an otherwise empty line (_preferable_); +- after an `option=value` entry. + +### Network specific options + +Network specific options can be: +- placed into sections with headers `[main]` (not `[mainnet]`), `[test]` (not `[testnet]`) or `[regtest]`; +- prefixed with a chain name; e.g., `regtest.maxmempool=100`. + +## Configuration File Path + +The configuration file is not automatically created; you can create it using your favorite text editor. By default, the configuration file name is `bitcoin.conf` and it is located in the Bitcoin data directory, but both the Bitcoin data directory and the configuration file path may be changed using the `-datadir` and `-conf` command-line options. + +The `includeconf=<file>` option in the `bitcoin.conf` file can be used to include additional configuration files. diff --git a/doc/build-freebsd.md b/doc/build-freebsd.md index 48746ce0c2..70f5dfc882 100644 --- a/doc/build-freebsd.md +++ b/doc/build-freebsd.md @@ -14,6 +14,12 @@ You will need the following dependencies, which can be installed as root via pkg pkg install autoconf automake boost-libs git gmake libevent libtool openssl pkgconf ``` +In order to run the test suite (recommended), you will need to have Python 3 installed: + +``` +pkg install python3 +``` + For the wallet (optional): ``` ./contrib/install_db4.sh `pwd` @@ -29,17 +35,29 @@ git clone https://github.com/bitcoin/bitcoin ## Building Bitcoin Core -**Important**: Use `gmake` (the non-GNU `make` will exit with an error). +**Important**: Use `gmake` (the non-GNU `make` will exit with an error): ``` ./autogen.sh ./configure # to build with wallet OR ./configure --disable-wallet # to build without wallet +``` + +followed by either: +``` gmake ``` +to build without testing, or + +``` +gmake check +``` + +to also run the test suite (recommended, if Python 3 is installed). + *Note on debugging*: The version of `gdb` installed by default is [ancient and considered harmful](https://wiki.freebsd.org/GdbRetirement). It is not suitable for debugging a multi-threaded C++ program, not even for getting backtraces. Please install the package `gdb` and use the versioned gdb command (e.g. `gdb7111`). diff --git a/doc/build-openbsd.md b/doc/build-openbsd.md index 63288acf16..dad2566a6c 100644 --- a/doc/build-openbsd.md +++ b/doc/build-openbsd.md @@ -1,6 +1,6 @@ OpenBSD build guide ====================== -(updated for OpenBSD 6.3) +(updated for OpenBSD 6.4) This guide describes how to build bitcoind and command-line utilities on OpenBSD. @@ -14,7 +14,7 @@ Run the following as root to install the base dependencies for building: ```bash pkg_add git gmake libevent libtool boost pkg_add autoconf # (select highest version, e.g. 2.69) -pkg_add automake # (select highest version, e.g. 1.15) +pkg_add automake # (select highest version, e.g. 1.16) pkg_add python # (select highest version, e.g. 3.6) git clone https://github.com/bitcoin/bitcoin.git @@ -36,7 +36,7 @@ BerkeleyDB is only necessary for the wallet functionality. To skip this, pass It is recommended to use Berkeley DB 4.8. You cannot use the BerkeleyDB library from ports, for the same reason as boost above (g++/libstd++ incompatibility). If you have to build it yourself, you can use [the installation script included -in contrib/](/contrib/install_db4.sh) like so +in contrib/](/contrib/install_db4.sh) like so: ```shell ./contrib/install_db4.sh `pwd` CC=cc CXX=c++ @@ -60,8 +60,8 @@ Preparation: export AUTOCONF_VERSION=2.69 # Replace this with the automake version that you installed. Include only -# the major and minor parts of the version: use "1.15" for "automake-1.15.1". -export AUTOMAKE_VERSION=1.15 +# the major and minor parts of the version: use "1.16" for "automake-1.16.1". +export AUTOMAKE_VERSION=1.16 ./autogen.sh ``` @@ -94,7 +94,7 @@ The standard ulimit restrictions in OpenBSD are very strict: data(kbytes) 1572864 -This, unfortunately, in some cases not enough to compile some `.cpp` files in the project, +This is, unfortunately, in some cases not enough to compile some `.cpp` files in the project, (see issue [#6658](https://github.com/bitcoin/bitcoin/issues/6658)). If your user is in the `staff` group the limit can be raised with: diff --git a/doc/build-osx.md b/doc/build-osx.md index 1fa01d0d6e..c9a59bab83 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -20,7 +20,7 @@ Dependencies See [dependencies.md](dependencies.md) for a complete overview. -If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG +If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG: brew install librsvg @@ -28,7 +28,7 @@ Berkeley DB ----------- It is recommended to use Berkeley DB 4.8. If you have to build it yourself, you can use [the installation script included in contrib/](/contrib/install_db4.sh) -like so +like so: ```shell ./contrib/install_db4.sh . @@ -36,12 +36,12 @@ like so from the root of the repository. -**Note**: You only need Berkeley DB if the wallet is enabled (see the section *Disable-Wallet mode* below). +**Note**: You only need Berkeley DB if the wallet is enabled (see [*Disable-wallet mode*](/doc/build-osx.md#disable-wallet-mode)). Build Bitcoin Core ------------------------ -1. Clone the Bitcoin Core source code and cd into `bitcoin` +1. Clone the Bitcoin Core source code: git clone https://github.com/bitcoin/bitcoin cd bitcoin @@ -80,13 +80,13 @@ Running Bitcoin Core is now available at `./src/bitcoind` -Before running, it's recommended that you create an RPC configuration file. +Before running, you may create an empty configuration file: - echo -e "rpcuser=bitcoinrpc\nrpcpassword=$(xxd -l 16 -p /dev/urandom)" > "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" + touch "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" -The first time you run bitcoind, it will start downloading the blockchain. This process could take several hours. +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: diff --git a/doc/build-unix.md b/doc/build-unix.md index 87dade42a3..522e3069ce 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -6,8 +6,8 @@ Some notes on how to build Bitcoin Core in Unix. Note --------------------- -Always use absolute paths to configure and compile Bitcoin Core and the dependencies, -for example, when specifying the path of the dependency: +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 @@ -24,7 +24,7 @@ make make install # optional ``` -This will build bitcoin-qt as well if the dependencies are met. +This will build bitcoin-qt as well, if the dependencies are met. Dependencies --------------------- @@ -87,11 +87,12 @@ You can add the repository and install using the following commands: sudo apt-get install libdb4.8-dev libdb4.8++-dev Ubuntu and Debian have their own libdb-dev and libdb++-dev packages, but these will install -BerkeleyDB 5.1 or later, which break binary wallet compatibility with the distributed executables which +BerkeleyDB 5.1 or later. This will break binary wallet compatibility with the distributed executables, which are based on BerkeleyDB 4.8. If you do not care about wallet compatibility, pass `--with-incompatible-bdb` to configure. -See the section "Disable-wallet mode" to build Bitcoin Core without wallet. +To build Bitcoin Core without wallet, see [*Disable-wallet mode*](/doc/build-unix.md#disable-wallet-mode) + Optional (see --with-miniupnpc and --enable-upnp-default): @@ -161,7 +162,7 @@ Berkeley DB ----------- It is recommended to use Berkeley DB 4.8. If you have to build it yourself, you can use [the installation script included in contrib/](/contrib/install_db4.sh) -like so +like so: ```shell ./contrib/install_db4.sh `pwd` @@ -169,7 +170,7 @@ like so from the root of the repository. -**Note**: You only need Berkeley DB if the wallet is enabled (see the section *Disable-Wallet mode* below). +**Note**: You only need Berkeley DB if the wallet is enabled (see [*Disable-wallet mode*](/doc/build-unix.md#disable-wallet-mode)). Boost ----- @@ -193,9 +194,7 @@ Hardening Flags: Hardening enables the following features: - -* Position Independent Executable - Build position independent code to take advantage of Address Space Layout Randomization +* _Position Independent Executable_: Build position independent code to take advantage of Address Space Layout Randomization offered by some kernels. Attackers who can cause execution of code at an arbitrary memory location are thwarted if they don't know where anything useful is located. The stack and heap are randomly located by default, but this allows the code section to be @@ -213,8 +212,7 @@ Hardening enables the following features: TYPE ET_DYN -* Non-executable Stack - If the stack is executable then trivial stack-based buffer overflow exploits are possible if +* _Non-executable Stack_: If the stack is executable then trivial stack-based buffer overflow exploits are possible if vulnerable buffers are found. By default, Bitcoin Core should be built with a non-executable stack, but if one of the libraries it uses asks for an executable stack or someone makes a mistake and uses a compiler extension which requires an executable stack, it will silently build an diff --git a/doc/build-windows.md b/doc/build-windows.md index 8c4b79bebc..fc93a0c6e4 100644 --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -5,15 +5,15 @@ Below are some notes on how to build Bitcoin Core for Windows. The options known to work for building Bitcoin Core on Windows are: -* On Linux using the [Mingw-w64](https://mingw-w64.org/doku.php) cross compiler tool chain. Ubuntu Bionic 18.04 is required +* On Linux, using the [Mingw-w64](https://mingw-w64.org/doku.php) cross compiler tool chain. Ubuntu Bionic 18.04 is required and is the platform used to build the Bitcoin Core Windows release binaries. -* On Windows using [Windows +* On Windows, using [Windows Subsystem for Linux (WSL)](https://msdn.microsoft.com/commandline/wsl/about) and the Mingw-w64 cross compiler tool chain. Other options which may work, but which have not been extensively tested are (please contribute instructions): -* On Windows using a POSIX compatibility layer application such as [cygwin](http://www.cygwin.com/) or [msys2](http://www.msys2.org/). -* On Windows using a native compiler tool chain such as [Visual Studio](https://www.visualstudio.com). +* On Windows, using a POSIX compatibility layer application such as [cygwin](http://www.cygwin.com/) or [msys2](http://www.msys2.org/). +* On Windows, using a native compiler tool chain such as [Visual Studio](https://www.visualstudio.com). Installing Windows Subsystem for Linux --------------------------------------- @@ -69,7 +69,7 @@ See also: [dependencies.md](dependencies.md). ## Building for 64-bit Windows -The first step is to install the mingw-w64 cross-compilation tool chain. +The first step is to install the mingw-w64 cross-compilation tool chain: sudo apt install g++-mingw-w64-x86-64 @@ -81,13 +81,13 @@ Once the toolchain is installed the build steps are common: Note that for WSL the Bitcoin Core source path MUST be somewhere in the default mount file system, for example /usr/src/bitcoin, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. -This means you cannot use a directory that located directly on the host Windows file system to perform the build. +This means you cannot use a directory that is located directly on the host Windows file system to perform the build. Acquire the source in the usual way: git clone https://github.com/bitcoin/bitcoin.git -Once the source code is ready the build steps are below. +Once the source code is ready the build steps are below: PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var cd depends @@ -142,9 +142,9 @@ way. This will install to `c:\workspace\bitcoin`, for example: Footnotes --------- -<a name="footnote1">1</a>: Starting from Ubuntu Xenial 16.04 both the 32 and 64 bit Mingw-w64 packages install two different +<a name="footnote1">1</a>: Starting from Ubuntu Xenial 16.04, both the 32 and 64 bit Mingw-w64 packages install two different compiler options to allow a choice between either posix or win32 threads. The default option is win32 threads which is the more efficient since it will result in binary code that links directly with the Windows kernel32.lib. Unfortunately, the headers -required to support win32 threads conflict with some of the classes in the C++11 standard library in particular std::mutex. +required to support win32 threads conflict with some of the classes in the C++11 standard library, in particular std::mutex. It's not possible to build the Bitcoin Core code using the win32 version of the Mingw-w64 cross compilers (at least not without modifying headers in the Bitcoin Core source code). diff --git a/doc/descriptors.md b/doc/descriptors.md index c23ac06e8f..b25678e06a 100644 --- a/doc/descriptors.md +++ b/doc/descriptors.md @@ -22,19 +22,20 @@ Output descriptors currently support: ## Examples -- `pk(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` represents a P2PK output. -- `pkh(02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5)` represents a P2PKH output. -- `wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)` represents a P2WPKH output. -- `sh(wpkh(03fff97bd5755eeea420453a14355235d382f6472f8568a18b2f057a1460297556))` represents a P2SH-P2WPKH output. -- `combo(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` represents a P2PK, P2PKH, P2WPKH, and P2SH-P2WPKH output. -- `sh(wsh(pkh(02e493dbf1c10d80f3581e4904930b1404cc6c13900ee0758474fa94abe8c4cd13)))` represents a (overly complicated) P2SH-P2WSH-P2PKH output. -- `multi(1,022f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,025cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc)` represents a bare *1-of-2* multisig. -- `sh(multi(2,022f01e5e15cca351daff3843fb70f3c2f0a1bdd05e5af888a67784ef3e10a2a01,03acd484e2f0c7f65309ad178a9f559abde09796974c57e714c35f110dfc27ccbe))` represents a P2SH *2-of-2* multisig. -- `wsh(multi(2,03a0434d9e47f3c86235477c7b1ae6ae5d3442d49b1943c2b752a68e2a47e247c7,03774ae7f858a9411e5ef4246b70c65aac5649980be5c17891bbec17895da008cb,03d01115d548e7561b15c38f004d734633687cf4419620095bc5b0f47070afe85a))` represents a P2WSH *2-of-3* multisig. -- `sh(wsh(multi(1,03f28773c2d975288bc7d1d205c3748651b075fbc6610e58cddeeddf8f19405aa8,03499fdf9e895e719cfd64e67f07d38e3226aa7b63678949e6e49b241a60e823e4,02d7924d4f7d43ea965a465ae3095ff41131e5946f3c85f79e44adbcf8e27e080e)))` represents a P2SH-P2WSH *1-of-3* multisig. -- `pk(xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8)` refers to a single P2PK output, using the public key part from the specified xpub. -- `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1'/2)` refers to a single P2PKH output, using child key *1'/2* of the specified xpub. -- `wsh(multi(1,xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB/1/0/*,xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/1/0/*))` refers to a chain of *1-of-2* P2WSH multisig outputs, using public keys taken from two HD chains with corresponding derivation paths. +- `pk(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` describes a P2PK output with the specified public key. +- `pkh(02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5)` describes a P2PKH output with the specified public key. +- `wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)` describes a P2WPKH output with the specified public key. +- `sh(wpkh(03fff97bd5755eeea420453a14355235d382f6472f8568a18b2f057a1460297556))` describes a P2SH-P2WPKH output with the specified public key. +- `combo(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` describes any P2PK, P2PKH, P2WPKH, or P2SH-P2WPKH output with the specified public key. +- `sh(wsh(pkh(02e493dbf1c10d80f3581e4904930b1404cc6c13900ee0758474fa94abe8c4cd13)))` describes an (overly complicated) P2SH-P2WSH-P2PKH output with the specified public key. +- `multi(1,022f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,025cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc)` describes a bare *1-of-2* multisig output with keys in the specified order. +- `sh(multi(2,022f01e5e15cca351daff3843fb70f3c2f0a1bdd05e5af888a67784ef3e10a2a01,03acd484e2f0c7f65309ad178a9f559abde09796974c57e714c35f110dfc27ccbe))` describes a P2SH *2-of-2* multisig output with keys in the specified order. +- `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([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). ## Reference @@ -52,14 +53,20 @@ Descriptors consist of several types of expressions. The top level expression is - `raw(HEX)` (top level only): the script whose hex encoding is HEX. `KEY` expressions: -- Hex encoded public keys (66 characters starting with `02` or `03`, or 130 characters starting with `04`). - - Inside `wpkh` and `wsh`, only compressed public keys are permitted. -- [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 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. - - Instead of a `'`, the suffix `h` can be used to denote hardened derivation. +- Optionally, key origin information, consisting of: + - An open bracket `[` + - Exactly 8 hex characters for the fingerprint of the key where the derivation starts (see BIP32 for details) + - Followed by zero or more `/NUM` or `/NUM'` path elements to indicate unhardened or hardened derivation steps between the fingerprint and the key or xpub/xprv root that follows + - A closing bracket `]` +- Followed by the actual key, which is either: + - Hex encoded public keys (66 characters starting with `02` or `03`, or 130 characters starting with `04`). + - Inside `wpkh` and `wsh`, only compressed public keys are permitted. + - [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 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. +- Anywhere a `'` suffix is permitted to denote hardened derivation, the suffix `h` can be used instead. `ADDR` expressions are any type of supported address: - P2PKH addresses (base58, of the form `1...`). Note that P2PKH addresses in descriptors cannot be used for P2PK outputs (use the `pk` function instead). @@ -91,6 +98,15 @@ on Bitcoin's OP_CHECKMULTISIG opcode. To support these, we introduce the multisig policy, where any *k* out of the *n* provided public keys must sign. +Key order is significant. A `multi()` expression describes a multisig script +with keys in the specified order, and in a search for TXOs, it will not match +outputs with multisig scriptPubKeys that have the same keys in a different +order. Also, to prevent a combinatorial explosion of the search space, if more +than one of the `multi()` key arguments is a BIP32 wildcard path ending in `/*` +or `*'`, the `multi()` expression only matches multisig scripts with the `i`th +child key from each wildcard path in lockstep, rather than scripts with any +combination of child keys from each wildcard path. + ### BIP32 derived keys and chains Most modern wallet software and hardware uses keys that are derived using @@ -101,12 +117,39 @@ path consists of a sequence of 0 or more integers (in the range *0..2<sup>31</sup>-1*) each optionally followed by `'` or `h`, and separated by `/` characters. The string may optionally end with the literal `/*` or `/*'` (or `/*h`) to refer to all unhardened or hardened -child keys instead. +child keys in a configurable range (by default `0-1000`, inclusive). Whenever a public key is described using a hardened derivation step, the script cannot be computed without access to the corresponding private key. +### Key origin identification + +In order to describe scripts whose signing keys reside on another device, +it may be necessary to identify the master key and derivation path an +xpub was derived with. + +For example, when following BIP44, it would be useful to describe a +change chain directly as `xpub.../44'/0'/0'/1/*` where `xpub...` +corresponds with the master key `m`. Unfortunately, since there are +hardened derivation steps that follow the xpub, this descriptor does not +let you compute scripts without access to the corresponding private keys. +Instead, it should be written as `xpub.../1/*`, where xpub corresponds to +`m/44'/0'/0'`. + +When interacting with a hardware device, it may be necessary to include +the entire path from the master down. BIP174 standardizes this by +providing the master key *fingerprint* (first 32 bit of the Hash160 of +the master pubkey), plus all derivation steps. To support constructing +these, we permit providing this key origin information inside the +descriptor language, even though it does not affect the actual +scriptPubKeys it refers to. + +Every public key can be prefixed by an 8-character hexadecimal +fingerprint plus optional derivation steps (hardened and unhardened) +surrounded by brackets, identifying the master and derivation path the key or xpub +that follows was derived with. + ### Including private keys Often it is useful to communicate a description of scripts along with the @@ -119,6 +162,6 @@ 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 constructs the P2PK, +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 -uncompressed, it only constructs P2PK and P2PKH. +uncompressed, the set only includes P2PK and P2PKH scripts. diff --git a/doc/developer-notes.md b/doc/developer-notes.md index c86648c5b8..fd5cc78297 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -69,7 +69,7 @@ tool to clean up patches automatically before submission. - **Symbol naming conventions**. These are preferred in new code, but are not required when doing so would need changes to significant pieces of existing code. - - Variable and namespace names are all lowercase, and may use `_` to + - Variable (including function arguments) and namespace names are all lowercase, and may use `_` to separate words (snake_case). - Class member variables have a `m_` prefix. - Global variables have a `g_` prefix. diff --git a/doc/release-notes-13152.md b/doc/release-notes-13152.md index 72526f5355..ace56f4d1b 100644 --- a/doc/release-notes-13152.md +++ b/doc/release-notes-13152.md @@ -1,4 +1,5 @@ New RPC methods ------------ -- `getnodeaddresses` returns peer addresses known to this node. It may be used to connect to nodes over TCP without using the DNS seeds.
\ No newline at end of file +- `getnodeaddresses` returns peer addresses known to this node. It may be used to connect to nodes over TCP without using the DNS seeds. +- `listwalletdir` returns a list of wallets in the wallet directory which is configured with `-walletdir` parameter. diff --git a/doc/release-notes-14282.md b/doc/release-notes-14282.md index e6d8e0b70c..900ca04324 100644 --- a/doc/release-notes-14282.md +++ b/doc/release-notes-14282.md @@ -4,3 +4,6 @@ Low-level RPC changes `-usehd` was removed in version 0.16. From that version onwards, all new wallets created are hierarchical deterministic wallets. Version 0.18 makes specifying `-usehd` invalid config. + +`ischange` field of boolean type that shows if an address was used for change +output was added to `getaddressinfo` method response. diff --git a/doc/release-notes-14296.md b/doc/release-notes-14296.md new file mode 100644 index 0000000000..f7c52baace --- /dev/null +++ b/doc/release-notes-14296.md @@ -0,0 +1,5 @@ +addwitnessaddress RPC method removed +------------------------------------ + +The `addwitnessaddress` RPC was added for segwit testing in version 0.13.0. It +was deprecated in version 0.16.0. This version fully removes the RPC method. diff --git a/doc/release-notes-14454.md b/doc/release-notes-14454.md new file mode 100644 index 0000000000..dd2c6c7ced --- /dev/null +++ b/doc/release-notes-14454.md @@ -0,0 +1,6 @@ +Low-level RPC changes +---------------------- + +The `importmulti` RPC has been updated to support P2WSH, P2WPKH, P2SH-P2WPKH, +P2SH-P2WSH. Each request now accepts an additional `witnessscript` to be used +for P2WSH or P2SH-P2WSH. diff --git a/doc/release-notes-14468.md b/doc/release-notes-14468.md new file mode 100644 index 0000000000..fb0243aba8 --- /dev/null +++ b/doc/release-notes-14468.md @@ -0,0 +1,15 @@ +Wallet `generate` RPC method deprecated +--------------------------------------- + +The wallet's `generate` RPC method has been deprecated and will be fully +removed in v0.19. + +`generate` is only used for testing. The RPC call reaches across multiple +subsystems (wallet and mining), so is deprecated to simplify the wallet-node +interface. Projects that are using `generate` for testing purposes should +transition to using the `generatetoaddress` call, which does not require or use +the wallet component. Calling `generatetoaddress` with an address returned by +`getnewaddress` gives the same functionality as the old `generate` method. + +To continue using `generate` in v0.18, restart bitcoind with the +`-deprecatedrpc=generate` configuration. diff --git a/doc/release-notes/release-notes-0.17.0.1.md b/doc/release-notes/release-notes-0.17.0.1.md new file mode 100644 index 0000000000..92db7dac7d --- /dev/null +++ b/doc/release-notes/release-notes-0.17.0.1.md @@ -0,0 +1,41 @@ +Bitcoin Core version 0.17.0.1 is now available from: + + <https://bitcoincore.org/bin/bitcoin-core-0.17.0.1/> + +This release provides a minor bug fix for 0.17.0. + +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/> + +Notable changes +=============== + +An issue was solved with OSX dmg generation, affecting macOS 10.12 to 10.14, +which could cause Finder to crash on install. + +There are no significant changes for other operating systems. + +0.17.0.1 change log +=================== + +### Build system +- #14416 `eb2cc84` Fix OSX dmg issue (10.12 to 10.14) (jonasschnelli) + +### Documentation +- #14509 `1b5af2c` [0.17] doc: use SegWit in getblocktemplate example (Sjors) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Jonas Schnelli +- Pieter Wuille +- Sjors Provoost +- Wladimir J. van der Laan + diff --git a/doc/release-notes/release-notes-0.17.0.md b/doc/release-notes/release-notes-0.17.0.md index ce7a1f6ac1..418d7ba5f9 100644 --- a/doc/release-notes/release-notes-0.17.0.md +++ b/doc/release-notes/release-notes-0.17.0.md @@ -270,7 +270,7 @@ Low-level RPC changes - The new RPC `scantxoutset` can be used to scan the UTXO set for entries that match certain output descriptors. Refer to the [output descriptors - reference documentation](doc/descriptors.md) for more details. This call + reference documentation](/doc/descriptors.md) for more details. This call is similar to `listunspent` but does not use a wallet, meaning that the wallet can be disabled at compile or run time. This call is experimental, as such, is subject to changes or removal in future releases. diff --git a/doc/release-process.md b/doc/release-process.md index 3ba622ee6d..f2fe44c8bf 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -296,6 +296,8 @@ bitcoin.org (see below for bitcoin.org update instructions). - bitcoincore.org blog post + - bitcoincore.org RPC documentation update + - Update title of #bitcoin on Freenode IRC - Optionally twitter, reddit /r/Bitcoin, ... but this will usually sort out itself diff --git a/doc/zmq.md b/doc/zmq.md index a1a506f2e7..7ffc5623b6 100644 --- a/doc/zmq.md +++ b/doc/zmq.md @@ -66,10 +66,21 @@ Currently, the following notifications are supported: 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 option to set the PUB socket's outbound message high water mark +(SNDHWM) may be set individually for each notification: + + -zmqpubhashtxhwm=n + -zmqpubhashblockhwm=n + -zmqpubrawblockhwm=n + -zmqpubrawtxhwm=n + +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 \ - -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw + -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw \ + -zmqpubhashtxhwm=10000 Each PUB notification has a topic and body, where the header corresponds to the notification type. For instance, for the |