diff options
Diffstat (limited to 'doc')
30 files changed, 964 insertions, 275 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..51950d4a13 100644 --- a/doc/README.md +++ b/doc/README.md @@ -3,9 +3,9 @@ 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/). +To download Bitcoin Core, visit [bitcoincore.org](https://bitcoincore.org/en/download/). Running --------------------- @@ -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 @@ -41,9 +41,10 @@ The following are developer notes on how to build Bitcoin Core on your native pl - [macOS Build Notes](build-osx.md) - [Unix Build Notes](build-unix.md) - [Windows Build Notes](build-windows.md) +- [FreeBSD Build Notes](build-freebsd.md) - [OpenBSD Build Notes](build-openbsd.md) - [NetBSD Build Notes](build-netbsd.md) -- [Gitian Building Guide](gitian-building.md) +- [Gitian Building Guide (External Link)](https://github.com/bitcoin-core/docs/blob/master/gitian-building.md) Development --------------------- @@ -56,6 +57,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 +66,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-netbsd.md b/doc/build-netbsd.md index 5bf2d6b59b..ab422f6aa7 100644 --- a/doc/build-netbsd.md +++ b/doc/build-netbsd.md @@ -1,6 +1,6 @@ NetBSD build guide ====================== -(updated for NetBSD 7.0) +(updated for NetBSD 8.0) This guide describes how to build bitcoind and command-line utilities on NetBSD. @@ -15,21 +15,38 @@ You will need the following modules, which can be installed via pkgsrc or pkgin: autoconf automake boost -db4 git gmake libevent libtool -python27 -``` +pkg-config +python37 -Download the source code: -``` -git clone https://github.com/bitcoin/bitcoin +git clone https://github.com/bitcoin/bitcoin.git ``` See [dependencies.md](dependencies.md) for a complete overview. +### Building BerkeleyDB + +BerkeleyDB is only necessary for the wallet functionality. To skip this, pass +`--disable-wallet` to `./configure` and skip to the next section. + +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: + +```shell +./contrib/install_db4.sh `pwd` +``` + +from the root of the repository. Then set `BDB_PREFIX` for the next section: + +```shell +export BDB_PREFIX="$PWD/db4" +``` + ### Building Bitcoin Core **Important**: Use `gmake` (the non-GNU `make` will exit with an error). @@ -37,13 +54,26 @@ See [dependencies.md](dependencies.md) for a complete overview. With wallet: ``` ./autogen.sh -./configure CPPFLAGS="-I/usr/pkg/include" LDFLAGS="-L/usr/pkg/lib" BOOST_CPPFLAGS="-I/usr/pkg/include" BOOST_LDFLAGS="-L/usr/pkg/lib" -gmake +./configure --with-gui=no CPPFLAGS="-I/usr/pkg/include" \ + LDFLAGS="-L/usr/pkg/lib" \ + BOOST_CPPFLAGS="-I/usr/pkg/include" \ + BOOST_LDFLAGS="-L/usr/pkg/lib" \ + BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ + BDB_CFLAGS="-I${BDB_PREFIX}/include" ``` Without wallet: ``` ./autogen.sh -./configure --disable-wallet CPPFLAGS="-I/usr/pkg/include" LDFLAGS="-L/usr/pkg/lib" BOOST_CPPFLAGS="-I/usr/pkg/include" BOOST_LDFLAGS="-L/usr/pkg/lib" -gmake +./configure --with-gui=no --disable-wallet \ + CPPFLAGS="-I/usr/pkg/include" \ + LDFLAGS="-L/usr/pkg/lib" \ + BOOST_CPPFLAGS="-I/usr/pkg/include" \ + BOOST_LDFLAGS="-L/usr/pkg/lib" +``` + +Build and run the tests: +```bash +gmake # use -jX here for parallelism +gmake check ``` 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..9641e0d3fd 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 --------------------------------------- @@ -65,11 +65,15 @@ A host toolchain (`build-essential`) is necessary because some dependency packages (such as `protobuf`) need to build host utilities that are used in the build process. -See also: [dependencies.md](dependencies.md). +See [dependencies.md](dependencies.md) for a complete overview. + +If you want to build the windows installer with `make deploy` you need [NSIS](https://nsis.sourceforge.io/Main_Page): + + sudo apt install nsis ## 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 +85,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 @@ -139,12 +143,16 @@ way. This will install to `c:\workspace\bitcoin`, for example: make install DESTDIR=/mnt/c/workspace/bitcoin +You can also create an installer using: + + make deploy + 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/dependencies.md b/doc/dependencies.md index d777aaf66f..50dde02fad 100644 --- a/doc/dependencies.md +++ b/doc/dependencies.md @@ -3,15 +3,15 @@ Dependencies These are the dependencies currently used by Bitcoin Core. You can find instructions for installing them in the `build-*.md` file for your platform. -| Dependency | Version used | Minimum required | CVEs | Shared | [Bundled Qt library](https://doc.qt.io/qt-5/configure-options.html) | +| 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](http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html) | 4.8.x | No | | | +| Berkeley DB | [4.8.30](https://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html) | 4.8.x | No | | | | Boost | [1.64.0](https://www.boost.org/users/download/) | [1.47.0](https://github.com/bitcoin/bitcoin/pull/8920) | No | | | | Clang | | [3.3+](https://llvm.org/releases/download.html) (C++11 support) | | | | | D-Bus | [1.10.18](https://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=dbus-1.10) | | No | Yes | | -| Expat | [2.2.5](https://libexpat.github.io/) | | No | Yes | | +| Expat | [2.2.6](https://libexpat.github.io/) | | No | Yes | | | fontconfig | [2.12.1](https://www.freedesktop.org/software/fontconfig/release/) | | No | Yes | | -| FreeType | [2.7.1](http://download.savannah.gnu.org/releases/freetype) | | No | | | +| FreeType | [2.7.1](https://download.savannah.gnu.org/releases/freetype) | | No | | | | GCC | | [4.8+](https://gcc.gnu.org/) (C++11 support) | | | | | HarfBuzz-NG | | | | | | | libevent | [2.1.8-stable](https://github.com/libevent/libevent/releases) | 2.0.22 | No | | | @@ -23,7 +23,7 @@ These are the dependencies currently used by Bitcoin Core. You can find instruct | protobuf | [2.6.1](https://github.com/google/protobuf/releases) | | No | | | | Python (tests) | | [3.4](https://www.python.org/downloads) | | | | | qrencode | [3.4.4](https://fukuchi.org/works/qrencode) | | No | | | -| Qt | [5.9.6](https://download.qt.io/official_releases/qt/) | 5.x | No | | | +| Qt | [5.9.7](https://download.qt.io/official_releases/qt/) | [5.2](https://github.com/bitcoin/bitcoin/pull/14725) | No | | | | XCB | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L87) (Linux only) | | xkbcommon | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L86) (Linux only) | | ZeroMQ | [4.2.5](https://github.com/zeromq/libzmq/releases) | 4.0.0 | No | | | diff --git a/doc/descriptors.md b/doc/descriptors.md index c23ac06e8f..de4d4e574f 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,19 +53,26 @@ 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 (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. + - [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. + +(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). -- P2SH addresses (base58, of the form `3...`, defined in [BIP 13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki)). -- Segwit addresses (bech32, of the form `bc1...`, defined in [BIP 173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)). +- P2PKH addresses (base58, of the form `1...` for mainnet or `[nm]...` for testnet). Note that P2PKH addresses in descriptors cannot be used for P2PK outputs (use the `pk` function instead). +- P2SH addresses (base58, of the form `3...` for mainnet or `2...` for testnet, defined in [BIP 13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki)). +- Segwit addresses (bech32, of the form `bc1...` for mainnet or `tb1...` for testnet, defined in [BIP 173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)). ## Explanation @@ -76,10 +84,9 @@ imaginable, though they may not be optimal: P2SH-P2PK, P2SH-P2PKH, P2WSH-P2PK, P2WSH-P2PKH, P2SH-P2WSH-P2PK, P2SH-P2WSH-P2PKH. To describe these, we model these as functions. The functions `pk` -(P2PK), `pkh` (P2PKH) and `wpkh` (P2WPKH) take as input a public key in -hexadecimal notation (which will be extended later), and return the +(P2PK), `pkh` (P2PKH) and `wpkh` (P2WPKH) take as input a `KEY` expression, and return the corresponding *scriptPubKey*. The functions `sh` (P2SH) and `wsh` (P2WSH) -take as input a script, and return the script describing P2SH and P2WSH +take as input a `SCRIPT` expression, and return the script describing P2SH and P2WSH outputs with the input as embedded script. The names of the functions do not contain "p2" for brevity. @@ -88,9 +95,18 @@ not contain "p2" for brevity. Several pieces of software use multi-signature (multisig) scripts based on Bitcoin's OP_CHECKMULTISIG opcode. To support these, we introduce the `multi(k,key_1,key_2,...,key_n)` function. It represents a *k-of-n* -multisig policy, where any *k* out of the *n* provided public keys must +multisig policy, where any *k* out of the *n* provided `KEY` expressions 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,43 @@ 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](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki) 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. + +Note that the fingerprint of the parent only serves as a fast way to detect +parent and child nodes in software, and software must be willing to deal with +collisions. + ### Including private keys Often it is useful to communicate a description of scripts along with the @@ -119,6 +166,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..e0def4ea27 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -7,8 +7,8 @@ Developer Notes - [Developer Notes](#developer-notes) - [Coding Style (General)](#coding-style-general) - [Coding Style (C++)](#coding-style-c) - - [Doxygen comments](#doxygen-comments) - [Coding Style (Python)](#coding-style-python) + - [Coding Style (Doxygen-compatible comments)](#coding-style-doxygen-compatible-comments) - [Development tips and tricks](#development-tips-and-tricks) - [Compiling for debugging](#compiling-for-debugging) - [Compiling for gprof profiling](#compiling-for-gprof-profiling) @@ -28,6 +28,8 @@ Developer Notes - [Strings and formatting](#strings-and-formatting) - [Variable names](#variable-names) - [Threads and synchronization](#threads-and-synchronization) + - [Scripts](#scripts) + - [Shebang](#shebang) - [Source code organization](#source-code-organization) - [GUI](#gui) - [Subtrees](#subtrees) @@ -69,7 +71,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. @@ -118,10 +120,17 @@ public: } // namespace foo ``` -Doxygen comments ------------------ +Coding Style (Python) +--------------------- + +Refer to [/test/functional/README.md#style-guidelines](/test/functional/README.md#style-guidelines). + +Coding Style (Doxygen-compatible comments) +------------------------------------------ -To facilitate the generation of documentation, use doxygen-compatible comment blocks for functions, methods and fields. +Bitcoin Core uses [Doxygen](http://www.doxygen.nl/) to generate its official documentation. + +Use Doxygen-compatible comment blocks for functions, methods, and fields. For example, to describe a function use: ```c++ @@ -154,7 +163,7 @@ int var; //!< Detailed description after the member ``` or -```cpp +```c++ //! Description before the member int var; ``` @@ -174,15 +183,15 @@ Not OK (used plenty in the current source, but not picked up): // ``` -A full list of comment syntaxes picked up by doxygen can be found at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html, -but if possible use one of the above styles. - -Documentation can be generated with `make docs` and cleaned up with `make clean-docs`. +A full list of comment syntaxes picked up by Doxygen can be found at https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html, +but the above styles are favored. -Coding Style (Python) ---------------------- +Documentation can be generated with `make docs` and cleaned up with `make clean-docs`. The resulting files are located in `doc/doxygen/html`; open `index.html` to view the homepage. -Refer to [/test/functional/README.md#style-guidelines](/test/functional/README.md#style-guidelines). +Before running `make docs`, you will need to install dependencies `doxygen` and `dot`. For example, on MacOS via Homebrew: +``` +brew install doxygen --with-graphviz +``` Development tips and tricks --------------------------- @@ -602,6 +611,31 @@ TRY_LOCK(cs_vNodes, lockNodes); } ``` +Scripts +-------------------------- + +### Shebang + +- Use `#!/usr/bin/env bash` instead of obsolete `#!/bin/bash`. + + - [*Rationale*](https://github.com/dylanaraps/pure-bash-bible#shebang): + + `#!/bin/bash` assumes it is always installed to /bin/ which can cause issues; + + `#!/usr/bin/env bash` searches the user's PATH to find the bash binary. + + OK: + +```bash +#!/usr/bin/env bash +``` + + Wrong: + +```bash +#!/bin/bash +``` + Source code organization -------------------------- @@ -714,7 +748,7 @@ Current subtrees include: - Upstream at https://github.com/bitcoin-core/ctaes ; actively maintained by Core contributors. - src/univalue - - Upstream at https://github.com/jgarzik/univalue ; report important PRs to Core to avoid delay. + - Upstream at https://github.com/bitcoin-core/univalue ; actively maintained by Core contributors, deviates from upstream https://github.com/jgarzik/univalue Upgrading LevelDB --------------------- @@ -827,7 +861,16 @@ To create a scripted-diff: - `-BEGIN VERIFY SCRIPT-` - `-END VERIFY SCRIPT-` -The scripted-diff is verified by the tool `test/lint/commit-script-check.sh` +The scripted-diff is verified by the tool `test/lint/commit-script-check.sh`. The tool's default behavior when supplied +with a commit is to verify all scripted-diffs from the beginning of time up to said commit. Internally, the tool passes +the first supplied argument to `git rev-list --reverse` to determine which commits to verify script-diffs for, ignoring +commits that don't conform to the commit message format described above. + +For development, it might be more convenient to verify all scripted-diffs in a range `A..B`, for example: + +```bash +test/lint/commit-script-check.sh origin/master..HEAD +``` Commit [`bb81e173`](https://github.com/bitcoin/bitcoin/commit/bb81e173) is an example of a scripted-diff. diff --git a/doc/files.md b/doc/files.md index 5657b1e6cb..85c27f3fd0 100644 --- a/doc/files.md +++ b/doc/files.md @@ -1,25 +1,26 @@ - -* banlist.dat: stores the IPs/Subnets of banned nodes -* bitcoin.conf: contains configuration settings for bitcoind or bitcoin-qt -* bitcoind.pid: stores the process id of bitcoind while running -* blocks/blk000??.dat: block data (custom, 128 MiB per file); since 0.8.0 -* blocks/rev000??.dat; block undo data (custom); since 0.8.0 (format changed since pre-0.8) -* blocks/index/*; block index (LevelDB); since 0.8.0 -* chainstate/*; block chain state database (LevelDB); since 0.8.0 -* database/*: BDB database environment; only used for wallet since 0.8.0; moved to wallets/ directory on new installs since 0.16.0 -* db.log: wallet database log file; moved to wallets/ directory on new installs since 0.16.0 -* debug.log: contains debug information and general logging generated by bitcoind or bitcoin-qt -* fee_estimates.dat: stores statistics used to estimate minimum transaction fees and priorities required for confirmation; since 0.10.0 -* indexes/txindex/*: optional transaction index database (LevelDB); since 0.17.0 -* mempool.dat: dump of the mempool's transactions; since 0.14.0. -* peers.dat: peer IP address database (custom format); since 0.7.0 -* wallet.dat: personal wallet (BDB) with keys and transactions; moved to wallets/ directory on new installs since 0.16.0 -* wallets/database/*: BDB database environment; used for wallets since 0.16.0 -* wallets/db.log: wallet database log file; since 0.16.0 -* wallets/wallet.dat: personal wallet (BDB) with keys and transactions; since 0.16.0 -* .cookie: session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0 -* onion_private_key: cached Tor hidden service private key for `-listenonion`: since 0.12.0 -* guisettings.ini.bak: backup of former GUI settings after `-resetguisettings` is used +Filename | Description +--------------------|---------------------------------------------------------------------------------------------------------------------------- +banlist.dat | stores the IPs/Subnets of banned nodes +bitcoin.conf | contains configuration settings for bitcoind or bitcoin-qt +bitcoind.pid | stores the process id of bitcoind while running +blocks/blk000??.dat | block data (custom, 128 MiB per file); since 0.8.0 +blocks/rev000??.dat | block undo data (custom); since 0.8.0 (format changed since pre-0.8) +blocks/index/* | block index (LevelDB); since 0.8.0 +chainstate/* | blockchain state database (LevelDB); since 0.8.0 +database/* | BDB database environment; only used for wallet since 0.8.0; moved to wallets/ directory on new installs since 0.16.0 +db.log | wallet database log file; moved to wallets/ directory on new installs since 0.16.0 +debug.log | contains debug information and general logging generated by bitcoind or bitcoin-qt +fee_estimates.dat | stores statistics used to estimate minimum transaction fees and priorities required for confirmation; since 0.10.0 +indexes/txindex/* | optional transaction index database (LevelDB); since 0.17.0 +mempool.dat | dump of the mempool's transactions; since 0.14.0 +peers.dat | peer IP address database (custom format); since 0.7.0 +wallet.dat | personal wallet (BDB) with keys and transactions; moved to wallets/ directory on new installs since 0.16.0 +wallets/database/* | BDB database environment; used for wallets since 0.16.0 +wallets/db.log | wallet database log file; since 0.16.0 +wallets/wallet.dat | personal wallet (BDB) with keys and transactions; since 0.16.0 +.cookie | session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0 +onion_private_key | cached Tor hidden service private key for `-listenonion`: since 0.12.0 +guisettings.ini.bak | backup of former GUI settings after `-resetguisettings` is used Only used in pre-0.8.0 --------------------- diff --git a/doc/fuzzing.md b/doc/fuzzing.md index 5dedcb51c8..dff9e71bba 100644 --- a/doc/fuzzing.md +++ b/doc/fuzzing.md @@ -3,10 +3,11 @@ Fuzz-testing Bitcoin Core A special test harness `test_bitcoin_fuzzy` is provided to provide an easy entry point for fuzzers and the like. In this document we'll describe how to -use it with AFL. +use it with AFL and libFuzzer. -Building AFL -------------- +## AFL + +### Building AFL It is recommended to always use the latest version of afl: ``` @@ -17,8 +18,7 @@ make export AFLPATH=$PWD ``` -Instrumentation ----------------- +### Instrumentation To build Bitcoin Core using AFL instrumentation (this assumes that the `AFLPATH` was set as above): @@ -39,8 +39,7 @@ compiling using `afl-clang-fast`/`afl-clang-fast++` the resulting features "persistent mode" and "deferred forkserver" can be used. See https://github.com/mcarpenter/afl/tree/master/llvm_mode for details. -Preparing fuzzing ------------------- +### Preparing fuzzing AFL needs an input directory with examples, and an output directory where it will place examples that it found. These can be anywhere in the file system, @@ -60,8 +59,7 @@ Example inputs are available from: Extract these (or other starting inputs) into the `inputs` directory before starting fuzzing. -Fuzzing --------- +### Fuzzing To start the actual fuzzing use: ``` @@ -70,3 +68,21 @@ $AFLPATH/afl-fuzz -i ${AFLIN} -o ${AFLOUT} -m52 -- test/test_bitcoin_fuzzy You may have to change a few kernel parameters to test optimally - `afl-fuzz` will print an error and suggestion if so. + +## libFuzzer + +A recent version of `clang`, the address sanitizer and libFuzzer is needed (all +found in the `compiler-rt` runtime libraries package). + +To build the `test/test_bitcoin_fuzzy` executable run + +``` +./configure --disable-ccache --with-sanitizers=fuzzer,address CC=clang CXX=clang++ +make +``` + +The fuzzer needs some inputs to work on, but the inputs or seeds can be used +interchangably between libFuzzer and AFL. + +See https://llvm.org/docs/LibFuzzer.html#running on how to run the libFuzzer +instrumented executable. diff --git a/doc/man/bitcoin-cli.1 b/doc/man/bitcoin-cli.1 index bf24d929bc..553addfa84 100644 --- a/doc/man/bitcoin-cli.1 +++ b/doc/man/bitcoin-cli.1 @@ -1,17 +1,21 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-CLI "1" "July 2018" "bitcoin-cli v0.16.99.0" "User Commands" +.TH BITCOIN-CLI "1" "December 2018" "bitcoin-cli v0.17.99.0" "User Commands" .SH NAME -bitcoin-cli \- manual page for bitcoin-cli v0.16.99.0 +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.16.99.0 -.SS "Usage:" -.TP -bitcoin\-cli [options] <command> [params] -Send command to Bitcoin Core -.IP -bitcoin\-cli [options] \fB\-named\fR <command> [name=value] ... Send command to Bitcoin Core (with named arguments) -bitcoin\-cli [options] help List commands -bitcoin\-cli [options] help <command> Get help for a command +Bitcoin Core RPC client version v0.17.99.0 .SH OPTIONS .HP \-? @@ -59,7 +63,8 @@ Password for JSON\-RPC connections .HP \fB\-rpcport=\fR<port> .IP -Connect to JSON\-RPC on <port> (default: 8332 or testnet: 18332) +Connect to JSON\-RPC on <port> (default: 8332, testnet: 18332, regtest: +18443) .HP \fB\-rpcuser=\fR<user> .IP @@ -72,20 +77,20 @@ Wait for RPC server to start \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) +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. +(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 -.TP -Read RPC password from standard input as a single line. -When combined .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 diff --git a/doc/man/bitcoin-qt.1 b/doc/man/bitcoin-qt.1 index 3a18c9f49f..1d87acd3de 100644 --- a/doc/man/bitcoin-qt.1 +++ b/doc/man/bitcoin-qt.1 @@ -1,12 +1,12 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-QT "1" "July 2018" "bitcoin-qt v0.16.99.0" "User Commands" +.TH BITCOIN-QT "1" "December 2018" "bitcoin-qt v0.17.99.0" "User Commands" .SH NAME -bitcoin-qt \- manual page for bitcoin-qt v0.16.99.0 +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.16.99.0 (64\-bit) -Usage: -.IP -bitcoin\-qt [command\-line options] +Bitcoin Core version v0.17.99.0 (64\-bit) .SH OPTIONS .HP \-? @@ -23,9 +23,9 @@ long fork (%s in cmd is replaced by message) 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: -0000000000000000005214481d2d96f898e3d5416e43359c145944a909d242e0, +0000000000000000002e63058c023a9a1de233554f28c7b21380b6c9003f36a8, testnet: -0000000002e9e7b00e1f6dc5123a04aad68dd0f0968d8c7aa45f6640795c37b1) +0000000000000037a8cd3e06cd5edbfe9dd1dbcc5dacab279376ef7cfc2b4c75) .HP \fB\-blocknotify=\fR<cmd> .IP @@ -61,7 +61,8 @@ Set database cache size in megabytes (4 to 16384, default: 450) \fB\-debuglogfile=\fR<file> .IP Specify location of debug log file. Relative paths will be prefixed by a -net\-specific datadir location. (0 to disable; default: debug.log) +net\-specific datadir location. (\fB\-nodebuglogfile\fR to disable; +default: debug.log) .HP \fB\-includeconf=\fR<file> .IP @@ -108,7 +109,7 @@ 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 +>=550 = automatically prune block files to stay under the specified target size in MiB) .HP \fB\-reindex\fR @@ -117,7 +118,9 @@ 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 +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 @@ -157,7 +160,7 @@ for IPv6 .HP \fB\-connect=\fR<ip> .IP -Connect only to the specified node; \fB\-connect\fR=\fI\,0\/\fR disables automatic +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. @@ -178,7 +181,7 @@ unless \fB\-connect\fR used) .HP \fB\-enablebip61\fR .IP -Send reject messages per BIP61 (default: 1) +Send reject messages per BIP61 (default: 0) .HP \fB\-externalip=\fR<ip> .IP @@ -221,8 +224,8 @@ Tries to keep outbound traffic under the given target (in MiB per 24h), .HP \fB\-onion=\fR<ip:port> .IP -Use separate SOCKS5 proxy to reach peers via Tor hidden services -(default: \fB\-proxy\fR) +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 @@ -242,11 +245,13 @@ Relay non\-P2SH multisig (default: 1) .HP \fB\-port=\fR<port> .IP -Listen for connections on <port> (default: 8333 or testnet: 18333) +Listen for connections on <port> (default: 8333, testnet: 18333, +regtest: 18444) .HP \fB\-proxy=\fR<ip:port> .IP -Connect through SOCKS5 proxy +Connect through SOCKS5 proxy, set \fB\-noproxy\fR to disable (default: +disabled) .HP \fB\-proxyrandomize\fR .IP @@ -393,8 +398,7 @@ Send transactions with full\-RBF opt\-in enabled (RPC only, default: 0) .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. -account owner and payment request information, 2 = drop tx meta -data) +payment request information, 2 = drop tx meta data) .PP ZeroMQ notification options: .HP @@ -418,7 +422,7 @@ Debugging/Testing options: .HP \fB\-debug=\fR<category> .IP -Output debugging information (default: 0, supplying <category> is +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, @@ -433,7 +437,7 @@ or more specified categories. .HP \fB\-help\-debug\fR .IP -Show all debugging options (usage: \fB\-\-help\fR \fB\-help\-debug\fR) +Print help message with debugging options and exit .HP \fB\-logips\fR .IP @@ -452,7 +456,7 @@ transaction; setting this too low may abort large transactions \fB\-printtoconsole\fR .IP Send trace/debug info to console (default: 1 when no \fB\-daemon\fR. To disable -logging to file, set debuglogfile=0) +logging to file, set \fB\-nodebuglogfile\fR) .HP \fB\-shrinkdebugfile\fR .IP @@ -529,8 +533,8 @@ option can be specified multiple times .HP \fB\-rpcauth=\fR<userpw> .IP -Username and hashed password for JSON\-RPC connections. The field -<userpw> comes in the format: <USERNAME>:<SALT>$<HASH>. A +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 @@ -538,12 +542,12 @@ option can be specified multiple times .HP \fB\-rpcbind=\fR<addr>[:port] .IP -Bind to given address to listen for JSON\-RPC connections. 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, or if \fB\-rpcallowip\fR has been specified, -0.0.0.0 and :: i.e., all addresses) +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 @@ -556,8 +560,8 @@ Password for JSON\-RPC connections .HP \fB\-rpcport=\fR<port> .IP -Listen for JSON\-RPC connections on <port> (default: 8332 or testnet: -18332) +Listen for JSON\-RPC connections on <port> (default: 8332, testnet: +18332, regtest: 18443) .HP \fB\-rpcserialversion\fR .IP diff --git a/doc/man/bitcoin-tx.1 b/doc/man/bitcoin-tx.1 index e1b81bad6c..f16c68ca14 100644 --- a/doc/man/bitcoin-tx.1 +++ b/doc/man/bitcoin-tx.1 @@ -1,16 +1,15 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIN-TX "1" "July 2018" "bitcoin-tx v0.16.99.0" "User Commands" +.TH BITCOIN-TX "1" "December 2018" "bitcoin-tx v0.17.99.0" "User Commands" .SH NAME -bitcoin-tx \- manual page for bitcoin-tx v0.16.99.0 +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.16.99.0 -.SS "Usage:" -.TP -bitcoin\-tx [options] <hex\-tx> [commands] -Update hex\-encoded bitcoin transaction -.TP -bitcoin\-tx [options] \fB\-create\fR [commands] -Create hex\-encoded bitcoin transaction +Bitcoin Core bitcoin\-tx utility version v0.17.99.0 .SH OPTIONS .HP \-? diff --git a/doc/man/bitcoind.1 b/doc/man/bitcoind.1 index d0ba131cde..5c4b1cd03b 100644 --- a/doc/man/bitcoind.1 +++ b/doc/man/bitcoind.1 @@ -1,13 +1,12 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. -.TH BITCOIND "1" "July 2018" "bitcoind v0.16.99.0" "User Commands" +.TH BITCOIND "1" "December 2018" "bitcoind v0.17.99.0" "User Commands" .SH NAME -bitcoind \- manual page for bitcoind v0.16.99.0 +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.16.99.0 -.SS "Usage:" -.TP -bitcoind [options] -Start Bitcoin Core Daemon +Bitcoin Core Daemon version v0.17.99.0 .SH OPTIONS .HP \-? @@ -24,9 +23,9 @@ long fork (%s in cmd is replaced by message) 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: -0000000000000000005214481d2d96f898e3d5416e43359c145944a909d242e0, +0000000000000000002e63058c023a9a1de233554f28c7b21380b6c9003f36a8, testnet: -0000000002e9e7b00e1f6dc5123a04aad68dd0f0968d8c7aa45f6640795c37b1) +0000000000000037a8cd3e06cd5edbfe9dd1dbcc5dacab279376ef7cfc2b4c75) .HP \fB\-blocknotify=\fR<cmd> .IP @@ -62,7 +61,8 @@ Set database cache size in megabytes (4 to 16384, default: 450) \fB\-debuglogfile=\fR<file> .IP Specify location of debug log file. Relative paths will be prefixed by a -net\-specific datadir location. (0 to disable; default: debug.log) +net\-specific datadir location. (\fB\-nodebuglogfile\fR to disable; +default: debug.log) .HP \fB\-includeconf=\fR<file> .IP @@ -109,7 +109,7 @@ 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 +>=550 = automatically prune block files to stay under the specified target size in MiB) .HP \fB\-reindex\fR @@ -118,7 +118,9 @@ 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 +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 @@ -158,7 +160,7 @@ for IPv6 .HP \fB\-connect=\fR<ip> .IP -Connect only to the specified node; \fB\-connect\fR=\fI\,0\/\fR disables automatic +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. @@ -179,7 +181,7 @@ unless \fB\-connect\fR used) .HP \fB\-enablebip61\fR .IP -Send reject messages per BIP61 (default: 1) +Send reject messages per BIP61 (default: 0) .HP \fB\-externalip=\fR<ip> .IP @@ -222,8 +224,8 @@ Tries to keep outbound traffic under the given target (in MiB per 24h), .HP \fB\-onion=\fR<ip:port> .IP -Use separate SOCKS5 proxy to reach peers via Tor hidden services -(default: \fB\-proxy\fR) +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 @@ -243,11 +245,13 @@ Relay non\-P2SH multisig (default: 1) .HP \fB\-port=\fR<port> .IP -Listen for connections on <port> (default: 8333 or testnet: 18333) +Listen for connections on <port> (default: 8333, testnet: 18333, +regtest: 18444) .HP \fB\-proxy=\fR<ip:port> .IP -Connect through SOCKS5 proxy +Connect through SOCKS5 proxy, set \fB\-noproxy\fR to disable (default: +disabled) .HP \fB\-proxyrandomize\fR .IP @@ -394,8 +398,7 @@ Send transactions with full\-RBF opt\-in enabled (RPC only, default: 0) .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. -account owner and payment request information, 2 = drop tx meta -data) +payment request information, 2 = drop tx meta data) .PP ZeroMQ notification options: .HP @@ -419,7 +422,7 @@ Debugging/Testing options: .HP \fB\-debug=\fR<category> .IP -Output debugging information (default: 0, supplying <category> is +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, @@ -434,7 +437,7 @@ or more specified categories. .HP \fB\-help\-debug\fR .IP -Show all debugging options (usage: \fB\-\-help\fR \fB\-help\-debug\fR) +Print help message with debugging options and exit .HP \fB\-logips\fR .IP @@ -453,7 +456,7 @@ transaction; setting this too low may abort large transactions \fB\-printtoconsole\fR .IP Send trace/debug info to console (default: 1 when no \fB\-daemon\fR. To disable -logging to file, set debuglogfile=0) +logging to file, set \fB\-nodebuglogfile\fR) .HP \fB\-shrinkdebugfile\fR .IP @@ -530,8 +533,8 @@ option can be specified multiple times .HP \fB\-rpcauth=\fR<userpw> .IP -Username and hashed password for JSON\-RPC connections. The field -<userpw> comes in the format: <USERNAME>:<SALT>$<HASH>. A +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 @@ -539,12 +542,12 @@ option can be specified multiple times .HP \fB\-rpcbind=\fR<addr>[:port] .IP -Bind to given address to listen for JSON\-RPC connections. 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, or if \fB\-rpcallowip\fR has been specified, -0.0.0.0 and :: i.e., all addresses) +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 @@ -557,8 +560,8 @@ Password for JSON\-RPC connections .HP \fB\-rpcport=\fR<port> .IP -Listen for JSON\-RPC connections on <port> (default: 8332 or testnet: -18332) +Listen for JSON\-RPC connections on <port> (default: 8332, testnet: +18332, regtest: 18443) .HP \fB\-rpcserialversion\fR .IP diff --git a/doc/psbt.md b/doc/psbt.md index 95e2f7fa01..560b45ef31 100644 --- a/doc/psbt.md +++ b/doc/psbt.md @@ -90,7 +90,7 @@ the command line in case `bitcoin-cli` is used. Setup: - All three call `getnewaddress` to create a new address; call these addresses *Aalice*, *Abob*, and *Acarol*. -- All three call `getaddressinfo X`, with *X* their respective address, and +- All three call `getaddressinfo "X"`, with *X* their respective address, and remember the corresponding public keys. Call these public keys *Kalice*, *Kbob*, and *Kcarol*. - All three now run `addmultisigaddress 2 ["Kalice","Kbob","Kcarol"]` to teach @@ -105,28 +105,28 @@ Setup: output. Again, it may be necessary to explicitly specify the addresstype in order to get a result that matches. This command won't enable them to initiate transactions later, however. -- They can now give out *D* as address others can pay to. +- They can now give out *Amulti* as address others can pay to. Later, when *V* BTC has been received on *Amulti*, and Bob and Carol want to move the coins in their entirety to address *Asend*, with no change. Alice does not need to be involved. - One of them - let's assume Carol here - initiates the creation. She runs - `walletcreatefundedpsbt [] {"Asend":V} 0 false {"subtractFeeFromOutputs":[0], "includeWatching":true}`. - We call the resulting PSBT *P*. P does not contain any signatures. + `walletcreatefundedpsbt [] {"Asend":V} 0 {"subtractFeeFromOutputs":[0], "includeWatching":true}`. + We call the resulting PSBT *P*. *P* does not contain any signatures. - Carol needs to sign the transaction herself. In order to do so, she runs - `walletprocesspsbt P`, and gives the resulting PSBT *P2* to Bob. + `walletprocesspsbt "P"`, and gives the resulting PSBT *P2* to Bob. - Bob inspects the PSBT using `decodepsbt "P2"` to determine if the transaction has indeed just the expected input, and an output to *Asend*, and the fee is reasonable. If he agrees, he calls `walletprocesspsbt "P2"` to sign. The resulting PSBT *P3* contains both Carol's and Bob's signature. -- Now anyone can call `finalizepsbt "P2"` to extract a fully signed transaction +- Now anyone can call `finalizepsbt "P3"` to extract a fully signed transaction *T*. - Finally anyone can broadcast the transaction using `sendrawtransaction "T"`. In case there are more signers, it may be advantageous to let them all sign in -parallel, rather passing the PSBT from one signer to the next one. In the +parallel, rather than passing the PSBT from one signer to the next one. In the above example this would translate to Carol handing a copy of *P* to each signer -separately. They can then all invoke `walletprocesspsbt P`, and end up with +separately. They can then all invoke `walletprocesspsbt "P"`, and end up with their individually-signed PSBT structures. They then all send those back to Carol (or anyone) who can combine them using `combinepsbt`. The last two steps (`finalizepsbt` and `sendrawtransaction`) remain unchanged. diff --git a/doc/release-notes-13152.md b/doc/release-notes-13152.md deleted file mode 100644 index 72526f5355..0000000000 --- a/doc/release-notes-13152.md +++ /dev/null @@ -1,4 +0,0 @@ -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 diff --git a/doc/release-notes-14023.md b/doc/release-notes-14023.md deleted file mode 100644 index 18ea6f26d0..0000000000 --- a/doc/release-notes-14023.md +++ /dev/null @@ -1,8 +0,0 @@ -Account API removed -------------------- - -The 'account' API was deprecated in v0.17 and has been fully removed in v0.18. -The 'label' API was introduced in v0.17 as a replacement for accounts. - -See the release notes from v0.17 for a full description of the changes from the -'account' API to the 'label' API. diff --git a/doc/release-notes-14282.md b/doc/release-notes-14282.md deleted file mode 100644 index e6d8e0b70c..0000000000 --- a/doc/release-notes-14282.md +++ /dev/null @@ -1,6 +0,0 @@ -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. diff --git a/doc/release-notes.md b/doc/release-notes.md index 2044a50098..53b5a2119f 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -47,31 +47,255 @@ processing the entire blockchain. Compatibility ============== -Bitcoin Core is extensively tested on multiple operating systems using -the Linux kernel, macOS 10.10+, and Windows 7 and newer (Windows XP is not supported). +Bitcoin Core is supported and extensively tested on operating systems using +the Linux kernel, macOS 10.10+, and Windows 7 and newer. It is not recommended +to use Bitcoin Core on unsupported systems. Bitcoin Core should also work on most other Unix-like systems but is not frequently tested on them. -From 0.17.0 onwards macOS <10.10 is no longer supported. 0.17.0 is built using Qt 5.9.x, which doesn't -support versions of macOS older than 10.10. +From 0.17.0 onwards, macOS <10.10 is no longer supported. 0.17.0 is +built using Qt 5.9.x, which doesn't support versions of macOS older than +10.10. Additionally, Bitcoin Core does not yet change appearance when +macOS "dark mode" is activated. + +In addition to previously-supported CPU platforms, this release's +pre-compiled distribution also provides binaries for the RISC-V +platform. Notable changes =============== -Command line option changes ---------------------------- +Mining +------ + +- Calls to `getblocktemplate` will fail if the segwit rule is not specified. + Calling `getblocktemplate` without segwit specified is almost certainly + a misconfiguration since doing so results in lower rewards for the miner. + Failed calls will produce an error message describing how to enable the + segwit rule. + +Configuration option changes +---------------------------- + +- A warning is printed if an unrecognized section name is used in the + configuration file. Recognized sections are `[test]`, `[main]`, and + `[regtest]`. + +- Four new options are available for configuring the maximum number of + messages that ZMQ will queue in memory (the "high water mark") before + dropping additional messages. The default value is 1,000, the same as + was used for previous releases. See the [ZMQ + documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/zmq.md#usage) + for details. + +- The `enablebip61` option (introduced in Bitcoin Core 0.17.0) is + used to toggle sending of BIP 61 reject messages. Reject messages have no use + case on the P2P network and are only logged for debugging by most network + nodes. The option will now by default be off for improved privacy and security + as well as reduced upload usage. The option can explicitly be turned on for + local-network debugging purposes. + +- The `rpcallowip` option can no longer be used to automatically listen + on all network interfaces. Instead, the `rpcbind` parameter must also + be used to specify the IP addresses to listen on. Listening for RPC + commands over a public network connection is insecure and should be + disabled, so a warning is now printed if a user selects such a + configuration. If you need to expose RPC in order to use a tool + like Docker, ensure you only bind RPC to your localhost, e.g. `docker + run [...] -p 127.0.0.1:8332:8332` (this is an extra `:8332` over the + normal Docker port specification). + +- The `rpcpassword` option now causes a startup error if the password + set in the configuration file contains a hash character (#), as it's + ambiguous whether the hash character is meant for the password or as a + comment. + +Documentation +------------- + +- A new short + [document](https://github.com/bitcoin/bitcoin/blob/master/doc/JSON-RPC-interface.md) + about the JSON-RPC interface describes cases where the results of an + RPC might contain inconsistencies between data sourced from different + subsystems, such as wallet state and mempool state. A note is added + to the [REST interface documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/REST-interface.md) + indicating that the same rules apply. + +- A new [document](https://github.com/bitcoin/bitcoin/blob/master/doc/bitcoin-conf.md) + about the `bitcoin.conf` file describes how to use it to configure + Bitcoin Core. + +- A new document introduces Bitcoin Core's BIP174 + [Partially-Signed Bitcoin Transactions (PSBT)](https://github.com/bitcoin/bitcoin/blob/master/doc/psbt.md) + interface, which is used to allow multiple programs to collaboratively + work to create, sign, and broadcast new transactions. This is useful + for offline (cold storage) wallets, multisig wallets, coinjoin + implementations, and many other cases where two or more programs need + to interact to generate a complete transaction. -The `-enablebip61` command line option (introduced in Bitcoin Core 0.17.0) is -used to toggle sending of BIP 61 reject messages. Reject messages have no use -case on the P2P network and are only logged for debugging by most network -nodes. The option will now by default be off for improved privacy and security -as well as reduced upload usage. The option can explicitly be turned on for -local-network debugging purposes. +- The [output script descriptor](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) + documentation has been updated with information about new features in + this still-developing language for describing the output scripts that + a wallet or other program wants to receive notifications for, such as + which addresses it wants to know received payments. The language is + currently used in the `scantxoutset` RPC and is expected to be adapted + to other RPCs and to the underlying wallet structure. -Example item +Build system changes +-------------------- + +- A new `--disable-bip70` option may be passed to `./configure` to + prevent Bitcoin-Qt from being built with support for the BIP70 payment + protocol or from linking libssl. As the payment protocol has exposed + Bitcoin Core to libssl vulnerabilities in the past, builders who don't + need BIP70 support are encouraged to use this option to reduce their + exposure to future vulnerabilities. + +Deprecated or removed RPCs +-------------------------- + +- The `signrawtransaction` RPC is removed after being deprecated and + hidden behind a special configuration option in version 0.17.0. + +- The 'account' API is removed after being deprecated in v0.17. The + 'label' API was introduced in v0.17 as a replacement for accounts. + See the [release notes from v0.17](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.17.0.md#label-and-account-apis-for-wallet) + for a full description of the changes from the 'account' API to the + 'label' API. + +- The `addwitnessaddress` RPC is removed after being deprecated in + version 0.13.0. + +- The wallet's `generate` RPC method is deprecated and will be fully + removed in a subsequent major version. This RPC is only used for + testing, but its implementation reached across multiple subsystems + (wallet and mining), so it is being deprecated to simplify the + wallet-node interface. Projects that are using `generate` for testing + purposes should transition to using the `generatetoaddress` RPC, which + does not require or use the wallet component. Calling + `generatetoaddress` with an address returned by the `getnewaddress` + RPC gives the same functionality as the old `generate` RPC. To + continue using `generate` in this version, restart bitcoind with the + `-deprecatedrpc=generate` configuration option. + +New RPCs +-------- + +- A new `getnodeaddresses` RPC returns peer addresses known to this + node. It may be used to find nodes to connect to without using a DNS + seeder. + +- A new `listwalletdir` RPC returns a list of wallets in the wallet + directory (either the default wallet directory or the directory + configured by the `-walletdir` parameter). + +Updated RPCs ------------ +Note: some low-level RPC changes mainly useful for testing are described +in the Low-level Changes section below. + +- The `getpeerinfo` RPC now returns an additional `minfeefilter` field + set to the peer's BIP133 fee filter. You can use this to detect that + you have peers that are willing to accept transactions below the + default minimum relay fee. + +- The mempool RPCs, such as `getrawmempool` with `verbose=true`, now + return an additional "bip125-replaceable" value indicating whether the + transaction (or its unconfirmed ancestors) opts-in to asking nodes and + miners to replace it with a higher-feerate transaction spending any of + the same inputs. + +- The `settxfee` RPC previously silently ignored attempts to set the fee + below the allowed minimums. It now prints a warning. The special + value of "0" may still be used to request the minimum value. + +- The `getaddressinfo` RPC now provides an `ischange` field indicating + whether the wallet used the address in a change output. + +- The `importmulti` RPC has been updated to support P2WSH, P2WPKH, + P2SH-P2WPKH, and P2SH-P2WSH. Requests for P2WSH and P2SH-P2WSH accept + an additional `witnessscript` parameter. + +- The `importmulti` RPC now returns an additional `warnings` field for + each request with an array of strings explaining when fields are being + ignored or are inconsistent, if there are any. + +- The `getaddressinfo` RPC now returns an additional `solvable` boolean + field when Bitcoin Core knows enough about the address's scriptPubKey, + optional redeemScript, and optional witnessScript in order for the + wallet to be able to generate an unsigned input spending funds sent to + that address. + +- The `getaddressinfo`, `listunspent`, and `scantxoutset` RPCs now + return an additional `desc` field that contains an output descriptor + containing all key paths and signing information for the address + (except for the private key). The `desc` field is only returned for + `getaddressinfo` and `listunspent` when the address is solvable. + +- The `importprivkey` RPC will preserve previously-set labels for + addresses or public keys corresponding to the private key being + imported. For example, if you imported a watch-only address with the + label "cold wallet" in earlier releases of Bitcoin Core, subsequently + importing the private key would default to resetting the address's + label to the default empty-string label (""). In this release, the + previous label of "cold wallet" will be retained. If you optionally + specify any label besides the default when calling `importprivkey`, + the new label will be applied to the address. + +- See the [Mining](#mining) section for changes to `getblocktemplate`. + +Graphical User Interface (GUI) +------------------------------ + +- A new Window menu is added alongside the existing File, Settings, and + Help menus. Several items from the other menus that opened new + windows have been moved to this new Window menu. + +- In the Send tab, the checkbox for "pay only the required fee" + has been removed. Instead, the user can simply decrease the value in + the Custom Feerate field all the way down to the node's configured + minimum relay fee. + +- In the Overview tab, the watch-only balance will be the only + balance shown if the wallet was created using the `createwallet` RPC + and the `disable_private_keys` parameter was set to true. + +Low-level changes +================= + +RPC +--- + +- The `submitblock` RPC previously returned the reason a rejected block + was invalid the first time it processed that block but returned a + generic "duplicate" rejection message on subsequent occasions it + processed the same block. It now always returns the fundamental + reason for rejecting an invalid block and only returns "duplicate" for + valid blocks it has already accepted. + +- A new `submitheader` RPC allows submitting block headers independently + from their block. This is likely only useful for testing. + +Configuration +------------- + +- The `-usehd` configuration option was removed in version 0.16. From + that version onwards, all new wallets created are hierarchical + deterministic wallets. This release makes specifying `-usehd` an + invalid configuration option. + +Changes for particular platforms +-------------------------------- + +- On macOS, Bitcoin Core now opts out of application CPU throttling + ("app nap") during initial blockchain download, when catching up from + over 100 blocks behind the current chain tip, or when reindexing chain + data. This helps prevent these operations from taking an excessively + long time because the operating system is attempting to conserve + power. + Credits ======= 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-notes/release-notes-0.17.1.md b/doc/release-notes/release-notes-0.17.1.md new file mode 100644 index 0000000000..b1e50e0391 --- /dev/null +++ b/doc/release-notes/release-notes-0.17.1.md @@ -0,0 +1,168 @@ +Bitcoin Core version 0.17.1 is now available from: + + <https://bitcoincore.org/bin/bitcoin-core-0.17.1/> + +or through BitTorrent: + + magnet:?xt=urn:btih:c56c87ccfaa8e6fbccc90d549121e61efd97cb6f&dn=bitcoin-core-0.17.1&tr=udp%3A%2F%2Ftracker.openbittorrent.com%3A80&tr=udp%3A%2F%2Ftracker.opentrackr.org%3A1337&tr=udp%3A%2F%2Ftracker.coppersurfer.tk%3A6969&tr=udp%3A%2F%2Ftracker.leechers-paradise.org%3A6969&tr=udp%3A%2F%2Fzer0day.ch%3A1337&tr=udp%3A%2F%2Fexplodie.org%3A6969 + +This is a new minor version release, with various bugfixes +and performance improvements, as well as updated translations. + +Please report bugs using the issue tracker at GitHub: + + <https://github.com/bitcoin/bitcoin/issues> + +To receive security and update notifications, please subscribe to: + + <https://bitcoincore.org/en/list/announcements/join/> + +How to Upgrade +============== + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes for older versions), then run the +installer (on Windows) or just copy over `/Applications/Bitcoin-Qt` (on Mac) +or `bitcoind`/`bitcoin-qt` (on Linux). + +If your node has a txindex, the txindex db will be migrated the first time you run 0.17.0 or newer, which may take up to a few hours. Your node will not be functional until this migration completes. + +The first time you run version 0.15.0 or newer, your chainstate database will be converted to a +new format, which will take anywhere from a few minutes to half an hour, +depending on the speed of your machine. + +Note that the block database format also changed in version 0.8.0 and there is no +automatic upgrade code from before version 0.8 to version 0.15.0. Upgrading +directly from 0.7.x and earlier without redownloading the blockchain is not supported. +However, as usual, old wallet versions are still supported. + +Downgrading warning +------------------- + +The chainstate database for this release is not compatible with previous +releases, so if you run 0.15 and then decide to switch back to any +older version, you will need to run the old release with the `-reindex-chainstate` +option to rebuild the chainstate data structures in the old format. + +If your node has pruning enabled, this will entail re-downloading and +processing the entire blockchain. + +Compatibility +============== + +Bitcoin Core is extensively tested on multiple operating systems using +the Linux kernel, macOS 10.10+, and Windows 7 and newer (Windows XP is not supported). + +Bitcoin Core should also work on most other Unix-like systems but is not +frequently tested on them. + +From 0.17.0 onwards macOS <10.10 is no longer supported. 0.17.0 is built using Qt 5.9.x, which doesn't +support versions of macOS older than 10.10. + +Notable changes +=============== + +`listtransactions` label support +-------------------------------- + +The `listtransactions` RPC `account` parameter which was deprecated in 0.17.0 +and renamed to `dummy` has been un-deprecated and renamed again to `label`. + +When bitcoin is configured with the `-deprecatedrpc=accounts` setting, specifying +a label/account/dummy argument will return both outgoing and incoming +transactions. Without the `-deprecatedrpc=accounts` setting, it will only return +incoming transactions (because it used to be possible to create transactions +spending from specific accounts, but this is no longer possible with labels). + +When `-deprecatedrpc=accounts` is set, it's possible to pass the empty string "" +to list transactions that don't have any label. Without +`-deprecatedrpc=accounts`, passing the empty string is an error because returning +only non-labeled transactions is not generally useful behavior and can cause +confusion. + +0.17.1 change log +================= + +### P2P protocol and network code +- #14685 `9406502` Fix a deserialization overflow edge case (kazcw) +- #14728 `b901578` Fix uninitialized read when stringifying an addrLocal (kazcw) + +### Wallet +- #14441 `5150acc` Restore ability to list incoming transactions by label (jnewbery) +- #13546 `91fa15a` Fix use of uninitialized value `bnb_used` in CWallet::CreateTransaction(…) (practicalswift) +- #14310 `bb90695` Ensure wallet is unlocked before signing (gustavonalle) +- #14690 `5782fdc` Throw error if CPubKey is invalid during PSBT keypath serialization (instagibbs) +- #14852 `2528443` backport: [tests] Add `wallet_balance.py` (MarcoFalke) +- #14196 `3362a95` psbt: always drop the unnecessary utxo and convert non-witness utxo to witness when necessary (achow101) +- #14588 `70ee1f8` Refactor PSBT signing logic to enforce invariant and fix signing bug (gwillen) +- #14424 `89a9a9d` Stop requiring imported pubkey to sign non-PKH schemes (sipa, MeshCollider) + +### RPC and other APIs +- #14417 `fb9ad04` Fix listreceivedbyaddress not taking address as a string (etscrivner) +- #14596 `de5e48a` Bugfix: RPC: Add `address_type` named param for createmultisig (luke-jr) +- #14618 `9666dba` Make HTTP RPC debug logging more informative (practicalswift) +- #14197 `7bee414` [psbt] Convert non-witness UTXOs to witness if witness sig created (achow101) +- #14377 `a3fe125` Check that a separator is found for psbt inputs, outputs, and global map (achow101) +- #14356 `7a590d8` Fix converttopsbt permitsigdata arg, add basic test (instagibbs) +- #14453 `75b5d8c` Fix wallet unload during walletpassphrase timeout (promag) + +### GUI +- #14403 `0242b5a` Revert "Force TLS1.0+ for SSL connections" (real-or-random) +- #14593 `df5131b` Explicitly disable "Dark Mode" appearance on macOS (fanquake) + +### Build system +- #14647 `7edebed` Remove illegal spacing in darwin.mk (ch4ot1c) +- #14698 `ec71f06` Add bitcoin-tx.exe into Windows installer (ken2812221) + +### Tests and QA +- #13965 `29899ec` Fix extended functional tests fail (ken2812221) +- #14011 `9461f98` Disable wallet and address book Qt tests on macOS minimal platform (ryanofsky) +- #14180 `86fadee` Run all tests even if wallet is not compiled (MarcoFalke) +- #14122 `8bc1bad` Test `rpc_help.py` failed: Check whether ZMQ is enabled or not (Kvaciral) +- #14101 `96dc936` Use named args in validation acceptance tests (MarcoFalke) +- #14020 `24d796a` Add tests for RPC help (promag) +- #14052 `7ff32a6` Add some actual witness in `rpc_rawtransaction` (MarcoFalke) +- #14215 `b72fbab` Use correct python index slices in example test (sdaftuar) +- #14024 `06544fa` Add `TestNode::assert_debug_log` (MarcoFalke) +- #14658 `60f7a97` Add test to ensure node can generate all rpc help texts at runtime (MarcoFalke) +- #14632 `96f15e8` Fix a comment (fridokus) +- #14700 `f9db08e` Avoid race in `p2p_invalid_block` by waiting for the block request (MarcoFalke) +- #14845 `67225e2` Add `wallet_balance.py` (jnewbery) + +### Documentation +- #14161 `5f51fd6` doc/descriptors.md tweaks (ryanofsky) +- #14276 `85aacc4` Add autogen.sh in ARM Cross-compilation (walterwhite81) + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Andrew Chow +- Chun Kuan Lee +- David A. Harding +- Eric Scrivner +- fanquake +- fridokus +- Glenn Willen +- Gregory Sanders +- gustavonalle +- John Newbery +- Jon Layton +- Jonas Schnelli +- João Barbosa +- Kaz Wesley +- Kvaciral +- Luke Dashjr +- MarcoFalke +- MeshCollider +- Pieter Wuille +- practicalswift +- Russell Yanofsky +- Sjors Provoost +- Suhas Daftuar +- Tim Ruffing +- Walter +- Wladimir J. van der Laan + +As well as everyone that helped translating on [Transifex](https://www.transifex.com/projects/p/bitcoin/). diff --git a/doc/release-process.md b/doc/release-process.md index 91270b4f7e..3bdbabcf04 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -6,11 +6,12 @@ Before every release candidate: * Update translations (ping wumpus on IRC) see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations). * Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh). +* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`) Before every minor and major release: * Update [bips.md](bips.md) to account for changes since the last release. -* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_IS_RELEASE` to `true`) +* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_IS_RELEASE` to `true`) (don't forget to set `CLIENT_VERSION_RC` to `0`) * Write release notes (see below) * Update `src/chainparams.cpp` nMinimumChainWork with information from the getblockchaininfo rpc. * Update `src/chainparams.cpp` defaultAssumeValid with information from the getblockhash rpc. @@ -86,7 +87,7 @@ Ensure gitian-builder is up-to-date: pushd ./gitian-builder mkdir -p inputs wget -P inputs https://bitcoincore.org/cfields/osslsigncode-Backports-to-1.7.1.patch - wget -P inputs http://downloads.sourceforge.net/project/osslsigncode/osslsigncode/osslsigncode-1.7.1.tar.gz + wget -P inputs https://downloads.sourceforge.net/project/osslsigncode/osslsigncode/osslsigncode-1.7.1.tar.gz popd Create the macOS SDK tarball, see the [macOS readme](README_osx.md) for details, and copy it into the inputs directory. @@ -296,6 +297,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/tor.md b/doc/tor.md index dc0b88618a..c46b7e9f60 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -109,9 +109,13 @@ preconfigured and the creation of a hidden service is automatic. If permission p are seen with `-debug=tor` they can be resolved by adding both the user running Tor and the user running bitcoind to the same group and setting permissions appropriately. On Debian-based systems the user running bitcoind can be added to the debian-tor group, -which has the appropriate permissions. An alternative authentication method is the use -of the `-torpassword` flag and a `hash-password` which can be enabled and specified in -Tor configuration. +which has the appropriate permissions. + +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). ## 4. Privacy recommendations 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 |