diff options
Diffstat (limited to 'doc')
46 files changed, 676 insertions, 503 deletions
diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index 38498103bb..0000000000 --- a/doc/.gitignore +++ /dev/null @@ -1 +0,0 @@ -Doxyfile diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000000..310a90612b --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,25 @@ +# Copyright (c) 2024-present The Bitcoin Core developers +# Distributed under the MIT software license, see the accompanying +# file COPYING or https://opensource.org/license/mit/. + +find_package(Doxygen COMPONENTS dot) + +if(DOXYGEN_FOUND) + set(doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) + configure_file(Doxyfile.in ${doxyfile} USE_SOURCE_PERMISSIONS) + + # In CMake 3.27, The FindDoxygen module's doxygen_add_docs() + # command gained a CONFIG_FILE option to specify a custom doxygen + # configuration file. + # TODO: Consider using it. + add_custom_target(docs + COMMAND Doxygen::doxygen ${doxyfile} + WORKING_DIRECTORY ${PROJECT_SOURCE_DIR} + COMMENT "Generating developer documentation" + VERBATIM USES_TERMINAL + ) +else() + add_custom_target(docs + COMMAND ${CMAKE_COMMAND} -E echo "Error: Doxygen not found" + ) +endif() diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index d8fd46d1c7..ccaf31170a 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -58,7 +58,7 @@ PROJECT_LOGO = doc/bitcoin_logo_doxygen.png # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = doc/doxygen +OUTPUT_DIRECTORY = @PROJECT_BINARY_DIR@/doc/doxygen # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and diff --git a/doc/README.md b/doc/README.md index 74a85b04e6..7f5db1b5bf 100644 --- a/doc/README.md +++ b/doc/README.md @@ -41,7 +41,7 @@ The following are developer notes on how to build Bitcoin Core on your native pl - [Dependencies](dependencies.md) - [macOS Build Notes](build-osx.md) - [Unix Build Notes](build-unix.md) -- [Windows Build Notes](build-windows.md) +- [Windows Build Notes](build-windows-msvc.md) - [FreeBSD Build Notes](build-freebsd.md) - [OpenBSD Build Notes](build-openbsd.md) - [NetBSD Build Notes](build-netbsd.md) diff --git a/doc/REST-interface.md b/doc/REST-interface.md index 2d7d0e3769..6664bc2a3a 100644 --- a/doc/REST-interface.md +++ b/doc/REST-interface.md @@ -4,7 +4,7 @@ Unauthenticated REST Interface The REST API can be enabled with the `-rest` option. The interface runs on the same port as the JSON-RPC interface, by default port 8332 for mainnet, port 18332 for testnet, -port 38332 for signet, and port 18443 for regtest. +port 48332 for testnet4, port 38332 for signet, and port 18443 for regtest. REST Interface consistency guarantees ------------------------------------- diff --git a/doc/assumeutxo.md b/doc/assumeutxo.md new file mode 100644 index 0000000000..17858de540 --- /dev/null +++ b/doc/assumeutxo.md @@ -0,0 +1,85 @@ +# Assumeutxo Usage + +Assumeutxo is a feature that allows fast bootstrapping of a validating bitcoind +instance. + +For notes on the design of Assumeutxo, please refer to [the design doc](/doc/design/assumeutxo.md). + +## Loading a snapshot + +There is currently no canonical source for snapshots, but any downloaded snapshot +will be checked against a hash that's been hardcoded in source code. If there is +no source for the snapshot you need, you can generate it yourself using +`dumptxoutset` on another node that is already synced (see +[Generating a snapshot](#generating-a-snapshot)). + +Once you've obtained the snapshot, you can use the RPC command `loadtxoutset` to +load it. + +``` +$ bitcoin-cli -rpcclienttimeout=0 loadtxoutset /path/to/input +``` + +After the snapshot has loaded, the syncing process of both the snapshot chain +and the background IBD chain can be monitored with the `getchainstates` RPC. + +### Pruning + +A pruned node can load a snapshot. To save space, it's possible to delete the +snapshot file as soon as `loadtxoutset` finishes. + +The minimum `-prune` setting is 550 MiB, but this functionality ignores that +minimum and uses at least 1100 MiB. + +As the background sync continues there will be temporarily two chainstate +directories, each multiple gigabytes in size (likely growing larger than the +downloaded snapshot). + +### Indexes + +Indexes work but don't take advantage of this feature. They always start building +from the genesis block and can only apply blocks in order. Once the background +validation reaches the snapshot block, indexes will continue to build all the +way to the tip. + + +For indexes that support pruning, note that these indexes only allow blocks that +were already indexed to be pruned. Blocks that are not indexed yet will also +not be pruned. + +This means that, if the snapshot is old, then a lot of blocks after the snapshot +block will need to be downloaded, and these blocks can't be pruned until they +are indexed, so they could consume a lot of disk space until indexing catches up +to the snapshot block. + +## Generating a snapshot + +The RPC command `dumptxoutset` can be used to generate a snapshot for the current +tip (using type "latest") or a recent height (using type "rollback"). A generated +snapshot from one node can then be loaded +on any other node. However, keep in mind that the snapshot hash needs to be +listed in the chainparams to make it usable. If there is no snapshot hash for +the height you have chosen already, you will need to change the code there and +re-compile. + +Using the type parameter "rollback", `dumptxoutset` can also be used to verify the +hardcoded snapshot hash in the source code by regenerating the snapshot and +comparing the hash. + +Example usage: + +``` +$ bitcoin-cli -rpcclienttimeout=0 dumptxoutset /path/to/output rollback +``` + +For most of the duration of `dumptxoutset` running the node is in a temporary +state that does not actually reflect reality, i.e. blocks are marked invalid +although we know they are not invalid. Because of this it is discouraged to +interact with the node in any other way during this time to avoid inconsistent +results and race conditions, particularly RPCs that interact with blockstorage. +This inconsistent state is also why network activity is temporarily disabled, +causing us to disconnect from all peers. + +`dumptxoutset` takes some time to complete, independent of hardware and +what parameter is chosen. Because of that it is recommended to increase the RPC +client timeout value (use `-rpcclienttimeout=0` for no timeout). diff --git a/doc/benchmarking.md b/doc/benchmarking.md index 84d5f2c444..c6dc75dc5c 100644 --- a/doc/benchmarking.md +++ b/doc/benchmarking.md @@ -8,16 +8,17 @@ thread queue, wallet balance. Running --------------------- -For benchmarking, you only need to compile `bitcoin_bench`. The bench runner -warns if you configure with `--enable-debug`, but consider if building without +For benchmarking, you only need to compile `bench_bitcoin`. The bench runner +warns if you configure with `-DCMAKE_BUILD_TYPE=Debug`, but consider if building without it will impact the benchmark(s) you are interested in by unlatching log printers and lock analysis. - make -C src bitcoin_bench + cmake -B build -DBUILD_BENCH=ON + cmake --build build -t bench_bitcoin After compiling bitcoin-core, the benchmarks can be run with: - src/bench/bench_bitcoin + build/src/bench/bench_bitcoin The output will look similar to: ``` @@ -39,7 +40,7 @@ The output will look similar to: Help --------------------- - src/bench/bench_bitcoin -? + build/src/bench/bench_bitcoin -? To print the various options, like listing the benchmarks without running them or using a regex filter to only run certain benchmarks. diff --git a/doc/bips.md b/doc/bips.md index 19a8091f55..d544ff822b 100644 --- a/doc/bips.md +++ b/doc/bips.md @@ -30,10 +30,11 @@ BIPs that are implemented by Bitcoin Core: * [`BIP 84`](https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki): The experimental descriptor wallets introduced in **v0.21.0** by default use the Hierarchical Deterministic Wallet derivation proposed by BIP 84. ([PR #16528](https://github.com/bitcoin/bitcoin/pull/16528)) * [`BIP 86`](https://github.com/bitcoin/bips/blob/master/bip-0086.mediawiki): Descriptor wallets by default use the Hierarchical Deterministic Wallet derivation proposed by BIP 86 since **v23.0** ([PR #22364](https://github.com/bitcoin/bitcoin/pull/22364)). * [`BIP 90`](https://github.com/bitcoin/bips/blob/master/bip-0090.mediawiki): Trigger mechanism for activation of BIPs 34, 65, and 66 has been simplified to block height checks since **v0.14.0** ([PR #8391](https://github.com/bitcoin/bitcoin/pull/8391)). +* [`BIP 94`](https://github.com/bitcoin/bips/blob/master/bip-0094.mediawiki): Testnet 4 (`-testnet4`) supported as of **v28.0** ([PR #29775](https://github.com/bitcoin/bitcoin/pull/29775)). * [`BIP 111`](https://github.com/bitcoin/bips/blob/master/bip-0111.mediawiki): `NODE_BLOOM` service bit added, and enforced for all peer versions as of **v0.13.0** ([PR #6579](https://github.com/bitcoin/bitcoin/pull/6579) and [PR #6641](https://github.com/bitcoin/bitcoin/pull/6641)). * [`BIP 112`](https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki): The CHECKSEQUENCEVERIFY opcode has been implemented since **v0.12.1** ([PR #7524](https://github.com/bitcoin/bitcoin/pull/7524)), and has been *buried* since **v0.19.0** ([PR #16060](https://github.com/bitcoin/bitcoin/pull/16060)). * [`BIP 113`](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki): Median time past lock-time calculations have been implemented since **v0.12.1** ([PR #6566](https://github.com/bitcoin/bitcoin/pull/6566)), and has been *buried* since **v0.19.0** ([PR #16060](https://github.com/bitcoin/bitcoin/pull/16060)). -* [`BIP 125`](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki): Opt-in full replace-by-fee signaling partially implemented. See doc/policy/mempool-replacements.md. +* [`BIP 125`](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki): Opt-in full replace-by-fee partially implemented: signaling is enforced if configured. For other replacement rules, see doc/policy/mempool-replacements.md. * [`BIP 130`](https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki): direct headers announcement is negotiated with peer versions `>=70012` as of **v0.12.0** ([PR 6494](https://github.com/bitcoin/bitcoin/pull/6494)). * [`BIP 133`](https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki): feefilter messages are respected and sent for peer versions `>=70013` as of **v0.13.0** ([PR 7542](https://github.com/bitcoin/bitcoin/pull/7542)). * [`BIP 141`](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki): Segregated Witness (Consensus Layer) as of **v0.13.0** ([PR 8149](https://github.com/bitcoin/bitcoin/pull/8149)), defined for mainnet as of **v0.13.1** ([PR 8937](https://github.com/bitcoin/bitcoin/pull/8937)), and *buried* since **v0.19.0** ([PR #16060](https://github.com/bitcoin/bitcoin/pull/16060)). @@ -61,6 +62,7 @@ BIPs that are implemented by Bitcoin Core: [PR 21686](https://github.com/bitcoin/bitcoin/pull/21686)). * [`BIP 350`](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki): Addresses for native v1+ segregated Witness outputs use Bech32m instead of Bech32 as of **v22.0** ([PR 20861](https://github.com/bitcoin/bitcoin/pull/20861)). * [`BIP 371`](https://github.com/bitcoin/bips/blob/master/bip-0371.mediawiki): Taproot fields for PSBT as of **v24.0** ([PR 22558](https://github.com/bitcoin/bitcoin/pull/22558)). +* [`BIP 379`](https://github.com/bitcoin/bips/blob/master/bip-0379.md): Miniscript was partially implemented in **v24.0** ([PR 24148](https://github.com/bitcoin/bitcoin/pull/24148)), and fully implemented as of **v26.0** ([PR 27255](https://github.com/bitcoin/bitcoin/pull/27255)). * [`BIP 380`](https://github.com/bitcoin/bips/blob/master/bip-0380.mediawiki) [`381`](https://github.com/bitcoin/bips/blob/master/bip-0381.mediawiki) [`382`](https://github.com/bitcoin/bips/blob/master/bip-0382.mediawiki) @@ -69,4 +71,5 @@ BIPs that are implemented by Bitcoin Core: [`385`](https://github.com/bitcoin/bips/blob/master/bip-0385.mediawiki): Output Script Descriptors, and most of Script Expressions are implemented as of **v0.17.0** ([PR 13697](https://github.com/bitcoin/bitcoin/pull/13697)). * [`BIP 386`](https://github.com/bitcoin/bips/blob/master/bip-0386.mediawiki): tr() Output Script Descriptors are implemented as of **v22.0** ([PR 22051](https://github.com/bitcoin/bitcoin/pull/22051)). +* [`BIP 387`](https://github.com/bitcoin/bips/blob/master/bip-0387.mediawiki): Tapscript Multisig Output Script Descriptors are implemented as of **v24.0** ([PR 24043](https://github.com/bitcoin/bitcoin/pull/24043)). * [`BIP 431`](https://github.com/bitcoin/bips/blob/master/bip-0431.mediawiki): transactions with nVersion=3 are standard and treated as Topologically Restricted Until Confirmation as of **v28.0** ([PR 29496](https://github.com/bitcoin/bitcoin/pull/29496)). diff --git a/doc/build-freebsd.md b/doc/build-freebsd.md index bf86a0ee4b..6a25e9a834 100644 --- a/doc/build-freebsd.md +++ b/doc/build-freebsd.md @@ -10,15 +10,14 @@ This guide describes how to build bitcoind, command-line utilities, and GUI on F Run the following as root to install the base dependencies for building. ```bash -pkg install autoconf automake boost-libs git gmake libevent libtool pkgconf - +pkg install boost-libs cmake git libevent pkgconf ``` See [dependencies.md](dependencies.md) for a complete overview. ### 2. Clone Bitcoin Repo Now that `git` and all the required dependencies are installed, let's clone the Bitcoin Core repository to a directory. All build scripts and commands will run from this directory. -``` bash +```bash git clone https://github.com/bitcoin/bitcoin.git ``` @@ -31,7 +30,7 @@ It is not necessary to build wallet functionality to run either `bitcoind` or `b `sqlite3` is required to support [descriptor wallets](descriptors.md). Skip if you don't intend to use descriptor wallets. -``` bash +```bash pkg install sqlite3 ``` @@ -41,7 +40,8 @@ BerkeleyDB is only required if legacy wallet support is required. It is required to use Berkeley DB 4.8. You **cannot** use the BerkeleyDB library from ports. However, you can build DB 4.8 yourself [using depends](/depends). -``` +```bash +pkg install gmake gmake -C depends NO_BOOST=1 NO_LIBEVENT=1 NO_QT=1 NO_SQLITE=1 NO_NATPMP=1 NO_UPNP=1 NO_ZMQ=1 NO_USDT=1 ``` @@ -64,17 +64,23 @@ sh/bash: export BDB_PREFIX=[path displayed above] #### GUI Dependencies ###### Qt5 -Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install the necessary parts of Qt. Skip if you don't intend to use the GUI. +Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install +the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI. + ```bash pkg install qt5-buildtools qt5-core qt5-gui qt5-linguisttools qt5-testlib qt5-widgets ``` ###### libqrencode -The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `libqrencode`. Skip if not using the GUI or don't want QR code functionality. +The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run: + ```bash pkg install libqrencode ``` + +Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI. + --- #### Notifications @@ -101,33 +107,28 @@ pkg install python3 databases/py-sqlite3 There are many ways to configure Bitcoin Core, here are a few common examples: ##### Descriptor Wallet and GUI: -This explicitly enables the GUI and disables legacy wallet support, assuming `sqlite` and `qt` are installed. +This disables legacy wallet support and enables the GUI, assuming `sqlite` and `qt` are installed. ```bash -./autogen.sh -./configure --without-bdb --with-gui=yes MAKE=gmake +cmake -B build -DWITH_BDB=OFF -DBUILD_GUI=ON ``` +Run `cmake -B build -LH` to see the full list of available options. + ##### Descriptor & Legacy Wallet. No GUI: -This enables support for both wallet types and disables the GUI, assuming +This enables support for both wallet types, assuming `sqlite3` and `db4` are both installed. ```bash -./autogen.sh -./configure --with-gui=no \ - BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ - BDB_CFLAGS="-I${BDB_PREFIX}/include" \ - MAKE=gmake +cmake -B build -DBerkeleyDB_INCLUDE_DIR:PATH="${BDB_PREFIX}/include" -DWITH_BDB=ON ``` ##### No Wallet or GUI -``` bash -./autogen.sh -./configure --without-wallet --with-gui=no MAKE=gmake +```bash +cmake -B build -DENABLE_WALLET=OFF ``` ### 2. Compile -**Important**: Use `gmake` (the non-GNU `make` will exit with an error). ```bash -gmake # use "-j N" for N parallel jobs -gmake check # Run tests if Python 3 is available +cmake --build build # Use "-j N" for N parallel jobs. +ctest --test-dir build # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available. ``` diff --git a/doc/build-netbsd.md b/doc/build-netbsd.md index 5f54fd6d9a..63bfbd61db 100644 --- a/doc/build-netbsd.md +++ b/doc/build-netbsd.md @@ -12,8 +12,7 @@ Install the required dependencies the usual way you [install software on NetBSD] The example commands below use `pkgin`. ```bash -pkgin install autoconf automake libtool pkg-config git gmake boost-headers libevent - +pkgin install git cmake pkg-config boost-headers libevent ``` NetBSD currently ships with an older version of `gcc` than is needed to build. You should upgrade your `gcc` and then pass this new version to the configure script. @@ -25,10 +24,10 @@ pkgin install gcc12 Then, when configuring, pass the following: ```bash -./configure +cmake -B build ... - CC="/usr/pkg/gcc12/bin/gcc" \ - CXX="/usr/pkg/gcc12/bin/g++" \ + -DCMAKE_C_COMPILER="/usr/pkg/gcc12/bin/gcc" \ + -DCMAKE_CXX_COMPILER="/usr/pkg/gcc12/bin/g++" \ ... ``` @@ -65,19 +64,26 @@ pkgin install db4 ``` #### GUI Dependencies +###### Qt5 -Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, Qt 5 is required. +Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install +the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI. ```bash pkgin install qt5-qtbase qt5-qttools ``` -The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `qrencode`. +###### libqrencode + +The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run: ```bash pkgin install qrencode ``` +Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI. + + #### Test Suite Dependencies There is an included test suite that is useful for testing code changes when developing. @@ -89,28 +95,22 @@ pkgin install python39 ### Building Bitcoin Core -**Note**: Use `gmake` (the non-GNU `make` will exit with an error). - - ### 1. Configuration There are many ways to configure Bitcoin Core. Here is an example that explicitly disables the wallet and GUI: ```bash -./autogen.sh -./configure --without-wallet --with-gui=no \ - CPPFLAGS="-I/usr/pkg/include" \ - MAKE=gmake +cmake -B build -DENABLE_WALLET=OFF -DBUILD_GUI=OFF ``` -For a full list of configuration options, see the output of `./configure --help` +Run `cmake -B build -LH` to see the full list of available options. ### 2. Compile Build and run the tests: ```bash -gmake # use "-j N" here for N parallel jobs -gmake check # Run tests if Python 3 is available +cmake --build build # Use "-j N" for N parallel jobs. +ctest --test-dir build # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available. ``` diff --git a/doc/build-openbsd.md b/doc/build-openbsd.md index 264d5f2d08..fafc91fc5f 100644 --- a/doc/build-openbsd.md +++ b/doc/build-openbsd.md @@ -10,9 +10,7 @@ This guide describes how to build bitcoind, command-line utilities, and GUI on O Run the following as root to install the base dependencies for building. ```bash -pkg_add bash git gmake libevent libtool boost -# Select the newest version of the following packages: -pkg_add autoconf automake python +pkg_add git cmake boost libevent ``` See [dependencies.md](dependencies.md) for a complete overview. @@ -31,7 +29,7 @@ It is not necessary to build wallet functionality to run either `bitcoind` or `b ###### Descriptor Wallet Support -`sqlite3` is required to support [descriptor wallets](descriptors.md). +SQLite is required to support [descriptor wallets](descriptors.md). ``` bash pkg_add sqlite3 @@ -48,65 +46,80 @@ Refer to [depends/README.md](/depends/README.md) for detailed instructions. ```bash gmake -C depends NO_BOOST=1 NO_LIBEVENT=1 NO_QT=1 NO_SQLITE=1 NO_NATPMP=1 NO_UPNP=1 NO_ZMQ=1 NO_USDT=1 ... -to: /path/to/bitcoin/depends/x86_64-unknown-openbsd +to: /path/to/bitcoin/depends/*-unknown-openbsd* ``` Then set `BDB_PREFIX`: ```bash -export BDB_PREFIX="/path/to/bitcoin/depends/x86_64-unknown-openbsd" +export BDB_PREFIX="[path displayed above]" ``` #### GUI Dependencies ###### Qt5 -Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, Qt 5 is required. +Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install +the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI. ```bash pkg_add qtbase qttools ``` -## Building Bitcoin Core +###### libqrencode + +The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run: + +```bash +pkg_add libqrencode +``` + +Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI. -**Important**: Use `gmake` (the non-GNU `make` will exit with an error). +--- -Preparation: +#### Notifications +###### ZeroMQ + +Bitcoin Core can provide notifications via ZeroMQ. If the package is installed, support will be compiled in. ```bash +pkg_add zeromq +``` -# Adapt the following for the version you installed (major.minor only): -export AUTOCONF_VERSION=2.71 -export AUTOMAKE_VERSION=1.16 +#### Test Suite Dependencies +There is an included test suite that is useful for testing code changes when developing. +To run the test suite (recommended), you will need to have Python 3 installed: -./autogen.sh +```bash +pkg_add python # Select the newest version of the package. ``` +## Building Bitcoin Core + ### 1. Configuration There are many ways to configure Bitcoin Core, here are a few common examples: ##### Descriptor Wallet and GUI: -This enables the GUI and descriptor wallet support, assuming `sqlite` and `qt5` are installed. +This enables descriptor wallet support and the GUI, assuming SQLite and Qt 5 are installed. ```bash -./configure MAKE=gmake +cmake -B build -DWITH_SQLITE=ON -DBUILD_GUI=ON ``` +Run `cmake -B build -LH` to see the full list of available options. + ##### Descriptor & Legacy Wallet. No GUI: -This enables support for both wallet types and disables the GUI: +This enables support for both wallet types: ```bash -./configure --with-gui=no \ - BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ - BDB_CFLAGS="-I${BDB_PREFIX}/include" \ - MAKE=gmake +cmake -B build -DBerkeleyDB_INCLUDE_DIR:PATH="${BDB_PREFIX}/include" -DWITH_BDB=ON ``` ### 2. Compile -**Important**: Use `gmake` (the non-GNU `make` will exit with an error). ```bash -gmake # use "-j N" for N parallel jobs -gmake check # Run tests if Python 3 is available +cmake --build build # Use "-j N" for N parallel jobs. +ctest --test-dir build # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available. ``` ## Resource limits diff --git a/doc/build-osx.md b/doc/build-osx.md index 20c92ab7a4..600eebb6ff 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,6 +1,6 @@ # macOS Build Guide -**Updated for MacOS [11.2](https://www.apple.com/macos/big-sur/)** +**Updated for MacOS [14](https://www.apple.com/macos/sonoma/)** This guide describes how to build bitcoind, command-line utilities, and GUI on macOS @@ -48,7 +48,7 @@ See [dependencies.md](dependencies.md) for a complete overview. To install, run the following from your terminal: ``` bash -brew install automake libtool boost pkg-config libevent +brew install cmake boost pkg-config libevent ``` For macOS 11 (Big Sur) and 12 (Monterey) you need to install a more recent version of llvm. @@ -60,7 +60,7 @@ brew install llvm And append the following to the configure commands below: ``` bash -CC=$(brew --prefix llvm)/bin/clang CXX=$(brew --prefix llvm)/bin/clang++ +-DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" ``` Try `llvm@17` if compilation fails with the default version of llvm. @@ -102,9 +102,8 @@ brew install berkeley-db@4 ###### Qt -Bitcoin Core includes a GUI built with the cross-platform Qt Framework. -To compile the GUI, we need to install `qt@5`. -Skip if you don't intend to use the GUI. +Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install +Qt, libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI. ``` bash brew install qt@5 @@ -113,14 +112,16 @@ brew install qt@5 Note: Building with Qt binaries downloaded from the Qt website is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714). -###### qrencode +###### libqrencode -The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `qrencode`. -Skip if not using the GUI or don't want QR code functionality. +The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run: ``` bash brew install qrencode ``` + +Otherwise, if you don't need QR encoding support, you can pass `-DWITH_QRENCODE=OFF` to disable this feature. + --- #### Port Mapping Dependencies @@ -143,7 +144,6 @@ Skip if you do not need this functionality. brew install libnatpmp ``` -Note: UPnP and NAT-PMP support will be compiled in and disabled by default. Check out the [further configuration](#further-configuration) section for more information. --- @@ -157,7 +157,6 @@ Skip if you do not need ZMQ functionality. brew install zeromq ``` -ZMQ is automatically compiled in and enabled if the dependency is detected. Check out the [further configuration](#further-configuration) section for more information. For more information on ZMQ, see: [zmq.md](zmq.md) @@ -177,7 +176,7 @@ brew install python #### Deploy Dependencies -You can deploy a `.zip` containing the Bitcoin Core application using `make deploy`. +You can [deploy](#3-deploy-optional) a `.zip` containing the Bitcoin Core application. It is required that you have `python` installed. ## Building Bitcoin Core @@ -188,32 +187,25 @@ There are many ways to configure Bitcoin Core, here are a few common examples: ##### Wallet (BDB + SQlite) Support, No GUI: -If `berkeley-db@4` is installed, then legacy wallet support will be built. -If `sqlite` is installed, then descriptor wallet support will also be built. -Additionally, this explicitly disables the GUI. +If `berkeley-db@4` or `sqlite` are not installed, this will throw an error. ``` bash -./autogen.sh -./configure --with-gui=no +cmake -B build -DWITH_BDB=ON ``` ##### Wallet (only SQlite) and GUI Support: -This explicitly enables the GUI and disables legacy wallet support. -If `qt` is not installed, this will throw an error. -If `sqlite` is installed then descriptor wallet functionality will be built. -If `sqlite` is not installed, then wallet functionality will be disabled. +This enables the GUI. +If `sqlite` or `qt` are not installed, this will throw an error. ``` bash -./autogen.sh -./configure --without-bdb --with-gui=yes +cmake -B build -DBUILD_GUI=ON ``` ##### No Wallet or GUI ``` bash -./autogen.sh -./configure --without-wallet --with-gui=no +cmake -B build -DENABLE_WALLET=OFF ``` ##### Further Configuration @@ -222,7 +214,7 @@ You may want to dig deeper into the configuration options to achieve your desire Examine the output of the following command for a full list of configuration options: ``` bash -./configure -help +cmake -B build -LH ``` ### 2. Compile @@ -231,8 +223,8 @@ After configuration, you are ready to compile. Run the following in your terminal to compile Bitcoin Core: ``` bash -make # use "-j N" here for N parallel jobs -make check # Run tests if Python 3 is available +cmake --build build # Use "-j N" here for N parallel jobs. +ctest --test-dir build # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available. ``` ### 3. Deploy (optional) @@ -240,13 +232,13 @@ make check # Run tests if Python 3 is available You can also create a `.zip` containing the `.app` bundle by running the following command: ``` bash -make deploy +cmake --build build --target deploy ``` ## Running Bitcoin Core -Bitcoin Core should now be available at `./src/bitcoind`. -If you compiled support for the GUI, it should be available at `./src/qt/bitcoin-qt`. +Bitcoin Core should now be available at `./build/src/bitcoind`. +If you compiled support for the GUI, it should be available at `./build/src/qt/bitcoin-qt`. The first time you run `bitcoind` or `bitcoin-qt`, it will start downloading the blockchain. This process could take many hours, or even days on slower than average systems. @@ -276,8 +268,8 @@ tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log ## Other commands: ```shell -./src/bitcoind -daemon # Starts the bitcoin daemon. -./src/bitcoin-cli --help # Outputs a list of command-line options. -./src/bitcoin-cli help # Outputs a list of RPC commands when the daemon is running. -./src/qt/bitcoin-qt -server # Starts the bitcoin-qt server mode, allows bitcoin-cli control +./build/src/bitcoind -daemon # Starts the bitcoin daemon. +./build/src/bitcoin-cli --help # Outputs a list of command-line options. +./build/src/bitcoin-cli help # Outputs a list of RPC commands when the daemon is running. +./build/src/qt/bitcoin-qt -server # Starts the bitcoin-qt server mode, allows bitcoin-cli control ``` diff --git a/doc/build-unix.md b/doc/build-unix.md index de54fb4eeb..4c3c659bff 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -8,10 +8,9 @@ To Build --------------------- ```bash -./autogen.sh -./configure -make # use "-j N" for N parallel jobs -make install # optional +cmake -B build +cmake --build build # use "-j N" for N parallel jobs +cmake --install build # optional ``` See below for instructions on how to [install the dependencies on popular Linux @@ -22,19 +21,20 @@ distributions](#linux-distribution-specific-instructions), or the C++ compilers are memory-hungry. It is recommended to have at least 1.5 GB of memory available when compiling Bitcoin Core. On systems with less, gcc can be -tuned to conserve memory with additional CXXFLAGS: +tuned to conserve memory with additional `CMAKE_CXX_FLAGS`: - ./configure CXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768" + cmake -B build -DCMAKE_CXX_FLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768" -Alternatively, or in addition, debugging information can be skipped for compilation. The default compile flags are -`-g -O2`, and can be changed with: +Alternatively, or in addition, debugging information can be skipped for compilation. +For the default build type `RelWithDebInfo`, the default compile flags are +`-O2 -g`, and can be changed with: - ./configure CXXFLAGS="-g0" + cmake -B build -DCMAKE_CXX_FLAGS_RELWITHDEBINFO="-O2 -g0" Finally, clang (often less resource hungry) can be used instead of gcc, which is used by default: - ./configure CXX=clang++ CC=clang + cmake -B build -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang ## Linux Distribution Specific Instructions @@ -44,7 +44,7 @@ Finally, clang (often less resource hungry) can be used instead of gcc, which is Build requirements: - sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils python3 + sudo apt-get install build-essential cmake pkg-config python3 Now, you can either build from self-compiled [depends](#dependencies) or install the required dependencies: @@ -56,12 +56,11 @@ SQLite is required for the descriptor wallet: Berkeley DB is only required for the legacy wallet. Ubuntu and Debian have their own `libdb-dev` and `libdb++-dev` packages, but these will install Berkeley DB 5.3 or later. This will break binary wallet compatibility with the distributed -executables, which are based on BerkeleyDB 4.8. If you do not care about wallet compatibility, pass -`--with-incompatible-bdb` to configure. Otherwise, you can build Berkeley DB [yourself](#berkeley-db). +executables, which are based on BerkeleyDB 4.8. Otherwise, you can build Berkeley DB [yourself](#berkeley-db). To build Bitcoin Core without wallet, see [*Disable-wallet mode*](#disable-wallet-mode) -Optional port mapping libraries (see: `--with-miniupnpc` and `--with-natpmp`): +Optional port mapping libraries (see: `-DWITH_MINIUPNPC=ON` and `-DWITH_NATPMP=ON`): sudo apt install libminiupnpc-dev libnatpmp-dev @@ -75,11 +74,8 @@ User-Space, Statically Defined Tracing (USDT) dependencies: GUI dependencies: -If you want to build bitcoin-qt, make sure that the required packages for Qt development -are installed. Qt 5 is necessary to build the GUI. -To build without GUI pass `--without-gui`. - -To build with Qt 5 you need the following: +Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install +the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI. sudo apt-get install qtbase5-dev qttools5-dev qttools5-dev-tools @@ -87,12 +83,11 @@ Additionally, to support Wayland protocol for modern desktop environments: sudo apt install qtwayland5 -libqrencode (optional) can be installed with: +The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run: sudo apt-get install libqrencode-dev -Once these are installed, they will be found by configure and a bitcoin-qt executable will be -built by default. +Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI. ### Fedora @@ -101,7 +96,7 @@ built by default. Build requirements: - sudo dnf install gcc-c++ libtool make autoconf automake python3 + sudo dnf install gcc-c++ cmake make python3 Now, you can either build from self-compiled [depends](#dependencies) or install the required dependencies: @@ -113,12 +108,11 @@ SQLite is required for the descriptor wallet: Berkeley DB is only required for the legacy wallet. Fedora releases have only `libdb-devel` and `libdb-cxx-devel` packages, but these will install Berkeley DB 5.3 or later. This will break binary wallet compatibility with the distributed executables, which -are based on Berkeley DB 4.8. If you do not care about wallet compatibility, -pass `--with-incompatible-bdb` to configure. Otherwise, you can build Berkeley DB [yourself](#berkeley-db). +are based on Berkeley DB 4.8. Otherwise, you can build Berkeley DB [yourself](#berkeley-db). To build Bitcoin Core without wallet, see [*Disable-wallet mode*](#disable-wallet-mode) -Optional port mapping libraries (see: `--with-miniupnpc` and `--with-natpmp`): +Optional port mapping libraries (see: `-DWITH_MINIUPNPC=ON` and `-DWITH_NATPMP=ON`): sudo dnf install miniupnpc-devel libnatpmp-devel @@ -132,11 +126,8 @@ User-Space, Statically Defined Tracing (USDT) dependencies: GUI dependencies: -If you want to build bitcoin-qt, make sure that the required packages for Qt development -are installed. Qt 5 is necessary to build the GUI. -To build without GUI pass `--without-gui`. - -To build with Qt 5 you need the following: +Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install +the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI. sudo dnf install qt5-qttools-devel qt5-qtbase-devel @@ -144,12 +135,11 @@ Additionally, to support Wayland protocol for modern desktop environments: sudo dnf install qt5-qtwayland -libqrencode (optional) can be installed with: +The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run: sudo dnf install qrencode-devel -Once these are installed, they will be found by configure and a bitcoin-qt executable will be -built by default. +Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI. ## Dependencies @@ -171,9 +161,7 @@ and configure using the following: ```bash export BDB_PREFIX="/path/to/bitcoin/depends/x86_64-pc-linux-gnu" -./configure \ - BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ - BDB_CFLAGS="-I${BDB_PREFIX}/include" +cmake -B build -DBerkeleyDB_INCLUDE_DIR:PATH="${BDB_PREFIX}/include" -DWITH_BDB=ON ``` **Note**: Make sure that `BDB_PREFIX` is an absolute path. @@ -185,7 +173,7 @@ Disable-wallet mode When the intention is to only run a P2P node, without a wallet, Bitcoin Core can be compiled in disable-wallet mode with: - ./configure --disable-wallet + cmake -B build -DENABLE_WALLET=OFF In this case there is no dependency on SQLite or Berkeley DB. @@ -195,19 +183,19 @@ Additional Configure Flags -------------------------- A list of additional configure flags can be displayed with: - ./configure --help + cmake -B build -LH Setup and Build Example: Arch Linux ----------------------------------- This example lists the steps necessary to setup and build a command line only distribution of the latest changes on Arch Linux: - pacman --sync --needed autoconf automake boost gcc git libevent libtool make pkgconf python sqlite + pacman --sync --needed cmake boost gcc git libevent make pkgconf python sqlite git clone https://github.com/bitcoin/bitcoin.git cd bitcoin/ - ./autogen.sh - ./configure - make check - ./src/bitcoind + cmake -B build + cmake --build build + ctest --test-dir build + ./build/src/bitcoind If you intend to work with legacy Berkeley DB wallets, see [Berkeley DB](#berkeley-db) section. diff --git a/doc/build-windows-msvc.md b/doc/build-windows-msvc.md new file mode 100644 index 0000000000..80c2b77f1e --- /dev/null +++ b/doc/build-windows-msvc.md @@ -0,0 +1,86 @@ +# Windows / MSVC Build Guide + +This guide describes how to build bitcoind, command-line utilities, and GUI on Windows using Microsoft Visual Studio. + +For cross-compiling options, please see [`build-windows.md`](./build-windows.md). + +## Preparation + +### 1. Visual Studio + +This guide relies on using CMake and vcpkg package manager provided with the Visual Studio installation. +Here are requirements for the Visual Studio installation: +1. Minimum required version: Visual Studio 2022 version 17.6. +2. Installed components: +- The "Desktop development with C++" workload. + +The commands in this guide should be executed in "Developer PowerShell for VS 2022" or "Developer Command Prompt for VS 2022". +The former is assumed hereinafter. + +### 2. Git + +Download and install [Git for Windows](https://git-scm.com/download/win). Once installed, Git is available from PowerShell or the Command Prompt. + +### 3. Clone Bitcoin Repository + +Clone the Bitcoin Core repository to a directory. All build scripts and commands will run from this directory. +``` +git clone https://github.com/bitcoin/bitcoin.git +``` + + +## Triplets and Presets + +The Bitcoin Core project supports the following vcpkg triplets: +- `x64-windows` (both CRT and library linkage is dynamic) +- `x64-windows-static` (both CRT and library linkage is static) + +To facilitate build process, the Bitcoin Core project provides presets, which are used in this guide. + +Available presets can be listed as follows: +``` +cmake --list-presets +``` + +By default, all presets: +- Set `BUILD_GUI` to `ON`. +- Set `WITH_QRENCODE` to `OFF`, due to known build issues when using vcpkg's `libqrencode` package. + +## Building + +CMake will put the resulting object files, libraries, and executables into a dedicated build directory. + +In the following instructions, the "Debug" configuration can be specified instead of the "Release" one. + +### 4. Building with Static Linking with GUI + +``` +cmake -B build --preset vs2022-static # It might take a while if the vcpkg binary cache is unpopulated or invalidated. +cmake --build build --config Release # Use "-j N" for N parallel jobs. +ctest --test-dir build --build-config Release # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available. +cmake --install build --config Release # Optional. +``` + +### 5. Building with Dynamic Linking without GUI + +``` +cmake -B build --preset vs2022 -DBUILD_GUI=OFF # It might take a while if the vcpkg binary cache is unpopulated or invalidated. +cmake --build build --config Release # Use "-j N" for N parallel jobs. +ctest --test-dir build --build-config Release # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available. +``` + +## Performance Notes + +### 6. vcpkg Manifest Default Features + +One can skip vcpkg manifest default features to speedup the configuration step. +For example, the following invocation will skip all features except for "wallet" and "tests" and their dependencies: +``` +cmake -B build --preset vs2022 -DVCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON -DVCPKG_MANIFEST_FEATURES="wallet;tests" -DBUILD_GUI=OFF +``` + +Available features are listed in the [`vcpkg.json`](/vcpkg.json) file. + +### 7. Antivirus Software + +To improve the build process performance, one might add the Bitcoin repository directory to the Microsoft Defender Antivirus exclusions. diff --git a/doc/build-windows.md b/doc/build-windows.md index 841693c77b..2e7b93da35 100644 --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -7,12 +7,15 @@ The options known to work for building Bitcoin Core on Windows are: * On Linux, using the [Mingw-w64](https://www.mingw-w64.org/) cross compiler tool chain. * On Windows, using [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/about) and Mingw-w64. -* On Windows, using [Microsoft Visual Studio](https://visualstudio.microsoft.com). See [README.md](/build_msvc/README.md). +* On Windows, using [Microsoft Visual Studio](https://visualstudio.microsoft.com). See [`build-windows-msvc.md`](./build-windows-msvc.md). 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](https://www.cygwin.com/) or [msys2](https://www.msys2.org/). +The instructions below work on Ubuntu and Debian. Make sure the distribution's `g++-mingw-w64-x86-64-posix` +package meets the minimum required `g++` version specified in [dependencies.md](dependencies.md). + Installing Windows Subsystem for Linux --------------------------------------- @@ -29,14 +32,14 @@ First, install the general dependencies: sudo apt update sudo apt upgrade - sudo apt install build-essential libtool autotools-dev automake pkg-config bsdmainutils curl git + sudo apt install cmake curl g++ git make pkg-config -A host toolchain (`build-essential`) is necessary because some dependency +A host toolchain (`g++`) is necessary because some dependency packages need to build host utilities that are used in the build process. 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): +If you want to build the Windows installer using the `deploy` build target, you will need [NSIS](https://nsis.sourceforge.io/Main_Page): sudo apt install nsis @@ -47,7 +50,7 @@ Acquire the source in the usual way: ## 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 toolchain: ```sh sudo apt install g++-mingw-w64-x86-64-posix @@ -59,22 +62,11 @@ Note that for WSL the Bitcoin Core source path MUST be somewhere in the default example /usr/src/bitcoin, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. This means you cannot use a directory that is located directly on the host Windows file system to perform the build. -Additional WSL Note: WSL support for [launching Win32 applications](https://learn.microsoft.com/en-us/archive/blogs/wsl/windows-and-ubuntu-interoperability#launching-win32-applications-from-within-wsl) -results in `Autoconf` configure scripts being able to execute Windows Portable Executable files. This can cause -unexpected behaviour during the build, such as Win32 error dialogs for missing libraries. The recommended approach -is to temporarily disable WSL support for Win32 applications. - Build using: - PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var - sudo bash -c "echo 0 > /proc/sys/fs/binfmt_misc/status" # Disable WSL support for Win32 applications. - cd depends - make HOST=x86_64-w64-mingw32 - cd .. - ./autogen.sh - CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/ - make # use "-j N" for N parallel jobs - sudo bash -c "echo 1 > /proc/sys/fs/binfmt_misc/status" # Enable WSL support for Win32 applications. + gmake -C depends HOST=x86_64-w64-mingw32 # Use "-j N" for N parallel jobs. + cmake -B build --toolchain depends/x86_64-w64-mingw32/toolchain.cmake + cmake --build build # Use "-j N" for N parallel jobs. ## Depends system @@ -88,8 +80,8 @@ executables to a directory on the Windows drive in the same directory structure as they appear in the release `.zip` archive. This can be done in the following way. This will install to `c:\workspace\bitcoin`, for example: - make install DESTDIR=/mnt/c/workspace/bitcoin + cmake --install build --prefix /mnt/c/workspace/bitcoin You can also create an installer using: - make deploy + cmake --build build --target deploy diff --git a/doc/dependencies.md b/doc/dependencies.md index 63c505c9cb..4c620cf876 100644 --- a/doc/dependencies.md +++ b/doc/dependencies.md @@ -6,9 +6,8 @@ You can find installation instructions in the `build-*.md` file for your platfor | Dependency | Minimum required | | --- | --- | -| [Autoconf](https://www.gnu.org/software/autoconf/) | [2.69](https://github.com/bitcoin/bitcoin/pull/17769) | -| [Automake](https://www.gnu.org/software/automake/) | [1.13](https://github.com/bitcoin/bitcoin/pull/18290) | -| [Clang](https://clang.llvm.org) | [15.0](https://github.com/bitcoin/bitcoin/pull/29165) | +| [Clang](https://clang.llvm.org) | [16.0](https://github.com/bitcoin/bitcoin/pull/30263) | +| [CMake](https://cmake.org/) | [3.22](https://github.com/bitcoin/bitcoin/pull/30454) | | [GCC](https://gcc.gnu.org) | [11.1](https://github.com/bitcoin/bitcoin/pull/29091) | | [Python](https://www.python.org) (scripts, tests) | [3.9](https://github.com/bitcoin/bitcoin/pull/28211) | | [systemtap](https://sourceware.org/systemtap/) ([tracing](tracing.md))| N/A | diff --git a/doc/descriptors.md b/doc/descriptors.md index 3b94ec03e4..8c55d4ae37 100644 --- a/doc/descriptors.md +++ b/doc/descriptors.md @@ -63,6 +63,7 @@ Output descriptors currently support: - `wsh(sortedmulti(1,xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB/1/0/*,xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/0/0/*))` describes a set of *1-of-2* P2WSH multisig outputs where one multisig key is the *1/0/`i`* child of the first specified xpub and the other multisig key is the *0/0/`i`* child of the second specified xpub, and `i` is any number in a configurable range (`0-1000` by default). The order of public keys in the resulting witnessScripts is determined by the lexicographic order of the public keys at that index. - `tr(c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5,{pk(fff97bd5755eeea420453a14355235d382f6472f8568a18b2f057a1460297556),pk(e493dbf1c10d80f3581e4904930b1404cc6c13900ee0758474fa94abe8c4cd13)})` describes a P2TR output with the `c6...` x-only pubkey as internal key, and two script paths. - `tr(c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5,sortedmulti_a(2,2f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,5cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc))` describes a P2TR output with the `c6...` x-only pubkey as internal key, and a single `multi_a` script that needs 2 signatures with 2 specified x-only keys, which will be sorted lexicographically. +- `wsh(sortedmulti(2,[6f53d49c/44h/1h/0h]tpubDDjsCRDQ9YzyaAq9rspCfq8RZFrWoBpYnLxK6sS2hS2yukqSczgcYiur8Scx4Hd5AZatxTuzMtJQJhchufv1FRFanLqUP7JHwusSSpfcEp2/0/*,[e6807791/44h/1h/0h]tpubDDAfvogaaAxaFJ6c15ht7Tq6ZmiqFYfrSmZsHu7tHXBgnjMZSHAeHSwhvjARNA6Qybon4ksPksjRbPDVp7yXA1KjTjSd5x18KHqbppnXP1s/0/*,[367c9cfa/44h/1h/0h]tpubDDtPnSgWYk8dDnaDwnof4ehcnjuL5VoUt1eW2MoAed1grPHuXPDnkX1fWMvXfcz3NqFxPbhqNZ3QBdYjLz2hABeM9Z2oqMR1Gt2HHYDoCgh/0/*))#av0kxgw0` describes a *2-of-3* multisig. For brevity, the internal "change" descriptor accompanying the above external "receiving" descriptor is not included here, but it typically differs only in the xpub derivation steps, ending in `/1/*` for change addresses. ## Reference @@ -97,6 +98,7 @@ Descriptors consist of several types of expressions. The top level expression is - [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. + - No more than one of these derivation steps may be of the form `<NUM;NUM;...;NUM>` (including hardened indicators with either or both `NUM`). If such specifiers are included, the descriptor will be parsed as multiple descriptors where the first descriptor uses all of the first `NUM` in the pair, and the second descriptor uses the second `NUM` in the pair for all `KEY` expressions, and so on. - 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. @@ -167,9 +169,9 @@ The basic steps are: the participant's signer wallet. Avoid reusing this wallet for any purpose other than signing transactions from the corresponding multisig we are about to create. Hint: extract the wallet's xpubs using `listdescriptors` and pick the one from the `pkh` descriptor since it's least likely to be accidentally reused (legacy addresses) - 2. Create a watch-only descriptor wallet (blank, private keys disabled). Now the multisig is created by importing the two descriptors: + 2. Create a watch-only descriptor wallet (blank, private keys disabled). Now the multisig is created by importing the external and internal descriptors: `wsh(sortedmulti(<M>,XPUB1/0/*,XPUB2/0/*,…,XPUBN/0/*))` and `wsh(sortedmulti(<M>,XPUB1/1/*,XPUB2/1/*,…,XPUBN/1/*))` - (one descriptor w/ `0` for receiving addresses and another w/ `1` for change). Every participant does this + (one descriptor w/ `0` for receiving addresses and another w/ `1` for change). Every participant does this. All key origin information (master key fingerprint and all derivation steps) should be included with xpubs for proper support of hardware devices / external signers 3. A receiving address is generated for the multisig. As a check to ensure step 2 was done correctly, every participant should verify they get the same addresses 4. Funds are sent to the resulting address @@ -256,6 +258,30 @@ Note how the first key is an xprv private key with a specific derivation path, while the other two are public keys. +### Specifying receiving and change descriptors in one descriptor + +Since receiving and change addresses are frequently derived from the same +extended key(s) but with a single derivation index changed, it is convenient +to be able to specify a descriptor that can derive at the two different +indexes. Thus a single tuple of indexes is allowed in each derivation path +following the extended key. When this descriptor is parsed, multiple descriptors +will be produced, the first one will use the first index in the tuple for all +key expressions, the second will use the second index, the third will use the +third index, and so on.. + +For example, a descriptor of the form: + + multi(2,xpub.../<0;1;2>/0/*,xpub.../<2;3;4>/*) + +will expand to the two descriptors + + multi(2,xpub.../0/0/*,xpub.../2/*) + multi(2,xpub.../1/0/*,xpub.../3/*) + multi(2,xpub.../2/0/*,xpub.../4*) + +When this tuple contains only two elements, wallet implementations can use the +first descriptor for receiving addresses and the second descriptor for change addresses. + ### Compatibility with old wallets In order to easily represent the sets of scripts currently supported by diff --git a/doc/design/assumeutxo.md b/doc/design/assumeutxo.md index a4980729d0..123c02ac13 100644 --- a/doc/design/assumeutxo.md +++ b/doc/design/assumeutxo.md @@ -1,47 +1,6 @@ -# assumeutxo +# Assumeutxo Design -Assumeutxo is a feature that allows fast bootstrapping of a validating bitcoind -instance. - -## Loading a snapshot - -There is currently no canonical source for snapshots, but any downloaded snapshot -will be checked against a hash that's been hardcoded in source code. - -Once you've obtained the snapshot, you can use the RPC command `loadtxoutset` to -load it. - -### Pruning - -A pruned node can load a snapshot. To save space, it's possible to delete the -snapshot file as soon as `loadtxoutset` finishes. - -The minimum `-prune` setting is 550 MiB, but this functionality ignores that -minimum and uses at least 1100 MiB. - -As the background sync continues there will be temporarily two chainstate -directories, each multiple gigabytes in size (likely growing larger than the -downloaded snapshot). - -### Indexes - -Indexes work but don't take advantage of this feature. They always start building -from the genesis block. Once the background validation reaches the snapshot block, -indexes will continue to build all the way to the tip. - -For indexes that support pruning, note that no pruning will take place between -the snapshot and the tip, until the background sync has completed - after which -everything is pruned. Depending on how old the snapshot is, this may temporarily -use a significant amount of disk space. - -## Generating a snapshot - -The RPC command `dumptxoutset` can be used to generate a snapshot. This can be used -to create a snapshot on one node that you wish to load on another node. -It can also be used to verify the hardcoded snapshot hash in the source code. - -The utility script -`./contrib/devtools/utxo_snapshot.sh` may be of use. +For notes on the usage of Assumeutxo, please refer to [the usage doc](/doc/assumeutxo.md). ## General background @@ -79,7 +38,7 @@ data. ### "Normal" operation via initial block download `ChainstateManager` manages a single Chainstate object, for which -`m_snapshot_blockhash` is null. This chainstate is (maybe obviously) +`m_from_snapshot_blockhash` is `std::nullopt`. This chainstate is (maybe obviously) considered active. This is the "traditional" mode of operation for bitcoind. | | | diff --git a/doc/design/libraries.md b/doc/design/libraries.md index aa8034ab37..335d3957d4 100644 --- a/doc/design/libraries.md +++ b/doc/design/libraries.md @@ -4,7 +4,7 @@ |--------------------------|-------------| | *libbitcoin_cli* | RPC client functionality used by *bitcoin-cli* executable | | *libbitcoin_common* | Home for common functionality shared by different executables and libraries. Similar to *libbitcoin_util*, but higher-level (see [Dependencies](#dependencies)). | -| *libbitcoin_consensus* | Stable, backwards-compatible consensus functionality used by *libbitcoin_node* and *libbitcoin_wallet*. | +| *libbitcoin_consensus* | Consensus functionality used by *libbitcoin_node* and *libbitcoin_wallet*. | | *libbitcoin_crypto* | Hardware-optimized functions for data encryption, hashing, message authentication, and key derivation. | | *libbitcoin_kernel* | Consensus engine and support library used for validation by *libbitcoin_node*. | | *libbitcoinqt* | GUI functionality used by *bitcoin-qt* and *bitcoin-gui* executables. | @@ -19,7 +19,7 @@ - Most libraries are internal libraries and have APIs which are completely unstable! There are few or no restrictions on backwards compatibility or rules about external dependencies. An exception is *libbitcoin_kernel*, which, at some future point, will have a documented external interface. -- Generally each library should have a corresponding source directory and namespace. Source code organization is a work in progress, so it is true that some namespaces are applied inconsistently, and if you look at [`libbitcoin_*_SOURCES`](../../src/Makefile.am) lists you can see that many libraries pull in files from outside their source directory. But when working with libraries, it is good to follow a consistent pattern like: +- Generally each library should have a corresponding source directory and namespace. Source code organization is a work in progress, so it is true that some namespaces are applied inconsistently, and if you look at [`add_library(bitcoin_* ...)`](../../src/CMakeLists.txt) lists you can see that many libraries pull in files from outside their source directory. But when working with libraries, it is good to follow a consistent pattern like: - *libbitcoin_node* code lives in `src/node/` in the `node::` namespace - *libbitcoin_wallet* code lives in `src/wallet/` in the `wallet::` namespace @@ -97,7 +97,7 @@ class bitcoin-qt,bitcoind,bitcoin-cli,bitcoin-wallet bold - *libbitcoin_consensus* should only depend on *libbitcoin_crypto*, and all other libraries besides *libbitcoin_crypto* should be allowed to depend on it. -- *libbitcoin_util* should be a standalone dependency that any library can depend on, and it should not depend on other libraries except *libbitcoin_crypto*. It provides basic utilities that fill in gaps in the C++ standard library and provide lightweight abstractions over platform-specific features. Since the util library is distributed with the kernel and is usable by kernel applications, it shouldn't contain functions that external code shouldn't call, like higher level code targetted at the node or wallet. (*libbitcoin_common* is a better place for higher level code, or code that is meant to be used by internal applications only.) +- *libbitcoin_util* should be a standalone dependency that any library can depend on, and it should not depend on other libraries except *libbitcoin_crypto*. It provides basic utilities that fill in gaps in the C++ standard library and provide lightweight abstractions over platform-specific features. Since the util library is distributed with the kernel and is usable by kernel applications, it shouldn't contain functions that external code shouldn't call, like higher level code targeted at the node or wallet. (*libbitcoin_common* is a better place for higher level code, or code that is meant to be used by internal applications only.) - *libbitcoin_common* is a home for miscellaneous shared code used by different Bitcoin Core applications. It should not depend on anything other than *libbitcoin_util*, *libbitcoin_consensus*, and *libbitcoin_crypto*. @@ -109,5 +109,4 @@ class bitcoin-qt,bitcoind,bitcoin-cli,bitcoin-wallet bold ## Work in progress -- Validation code is moving from *libbitcoin_node* to *libbitcoin_kernel* as part of [The libbitcoinkernel Project #24303](https://github.com/bitcoin/bitcoin/issues/24303) -- Source code organization is discussed in general in [Library source code organization #15732](https://github.com/bitcoin/bitcoin/issues/15732) +- Validation code is moving from *libbitcoin_node* to *libbitcoin_kernel* as part of [The libbitcoinkernel Project #27587](https://github.com/bitcoin/bitcoin/issues/27587) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index d9d5b392c5..a630957f41 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -214,14 +214,14 @@ int main() To run clang-tidy on Ubuntu/Debian, install the dependencies: ```sh -apt install clang-tidy bear clang +apt install clang-tidy clang ``` -Then, pass clang as compiler to configure, and use bear to produce the `compile_commands.json`: +Configure with clang as the compiler: ```sh -./autogen.sh && ./configure CC=clang CXX=clang++ -make clean && bear --config src/.bear-tidy-config -- make -j $(nproc) +cmake -B build -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON +cmake --build build -j $(nproc) ``` The output is denoised of errors from external dependencies. @@ -229,13 +229,13 @@ The output is denoised of errors from external dependencies. To run clang-tidy on all source files: ```sh -( cd ./src/ && run-clang-tidy -j $(nproc) ) +( cd ./src/ && run-clang-tidy -p ../build -j $(nproc) ) ``` To run clang-tidy on the changed source lines: ```sh -git diff | ( cd ./src/ && clang-tidy-diff -p2 -j $(nproc) ) +git diff | ( cd ./src/ && clang-tidy-diff -p2 -path ../build -j $(nproc) ) ``` Coding Style (Python) @@ -338,11 +338,12 @@ Recommendations: ### Generating Documentation -The 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` in that directory to view the homepage. +Assuming the build directory is named `build`, +the documentation can be generated with `cmake --build build --target docs`. +The resulting files will be located in `build/doc/doxygen/html`; +open `index.html` in that directory to view the homepage. -Before running `make docs`, you'll need to install these dependencies: +Before building the `docs` target, you'll need to install these dependencies: Linux: `sudo apt install doxygen graphviz` @@ -353,8 +354,14 @@ Development tips and tricks ### Compiling for debugging -Run configure with `--enable-debug` to add additional compiler flags that -produce better debugging builds. +When using the default build configuration by running `cmake -B build`, the +`-DCMAKE_BUILD_TYPE` is set to `RelWithDebInfo`. This option adds debug symbols +but also performs some compiler optimizations that may make debugging trickier +as the code may not correspond directly to the source. + +If you need to build exclusively for debugging, set the `-DCMAKE_BUILD_TYPE` +to `Debug` (i.e. `-DCMAKE_BUILD_TYPE=Debug`). You can always check the cmake +build options of an existing build with `ccmake build`. ### Show sources in debugging @@ -467,34 +474,43 @@ which includes known Valgrind warnings in our dependencies that cannot be fixed in-tree. Example use: ```shell -$ valgrind --suppressions=contrib/valgrind.supp src/test/test_bitcoin +$ valgrind --suppressions=contrib/valgrind.supp build/src/test/test_bitcoin $ valgrind --suppressions=contrib/valgrind.supp --leak-check=full \ - --show-leak-kinds=all src/test/test_bitcoin --log_level=test_suite -$ valgrind -v --leak-check=full src/bitcoind -printtoconsole -$ ./test/functional/test_runner.py --valgrind + --show-leak-kinds=all build/src/test/test_bitcoin --log_level=test_suite +$ valgrind -v --leak-check=full build/src/bitcoind -printtoconsole +$ ./build/test/functional/test_runner.py --valgrind ``` ### Compiling for test coverage -LCOV can be used to generate a test coverage report based upon `make check` +LCOV can be used to generate a test coverage report based upon `ctest` execution. LCOV must be installed on your system (e.g. the `lcov` package on Debian/Ubuntu). To enable LCOV report generation during test runs: ```shell -./configure --enable-lcov -make -make cov +cmake -B build -DCMAKE_BUILD_TYPE=Coverage +cmake --build build +cmake -P build/Coverage.cmake -# A coverage report will now be accessible at `./test_bitcoin.coverage/index.html`, -# which covers unit tests, and `./total.coverage/index.html`, which covers +# A coverage report will now be accessible at `./build/test_bitcoin.coverage/index.html`, +# which covers unit tests, and `./build/total.coverage/index.html`, which covers # unit and functional tests. ``` -Additional LCOV options can be specified using `LCOV_OPTS`, but may be dependant +Additional LCOV options can be specified using `LCOV_OPTS`, but may be dependent on the version of LCOV. For example, when using LCOV `2.x`, branch coverage can be -enabled by setting `LCOV_OPTS="--rc branch_coverage=1"`, when configuring. +enabled by setting `LCOV_OPTS="--rc branch_coverage=1"`: + +``` +cmake -DLCOV_OPTS="--rc branch_coverage=1" -P build/Coverage.cmake +``` + +To enable test parallelism: +``` +cmake -DJOBS=$(nproc) -P build/Coverage.cmake +``` ### Performance profiling with perf @@ -545,7 +561,7 @@ See the functional test documentation for how to invoke perf within tests. Bitcoin Core can be compiled with various "sanitizers" enabled, which add instrumentation for issues regarding things like memory safety, thread race conditions, or undefined behavior. This is controlled with the -`--with-sanitizers` configure flag, which should be a comma separated list of +`-DSANITIZERS` cmake build flag, which should be a comma separated list of sanitizers to enable. The sanitizer list should correspond to supported `-fsanitize=` options in your compiler. These sanitizers have runtime overhead, so they are most useful when testing changes or producing debugging builds. @@ -554,10 +570,10 @@ Some examples: ```bash # Enable both the address sanitizer and the undefined behavior sanitizer -./configure --with-sanitizers=address,undefined +cmake -B build -DSANITIZERS=address,undefined # Enable the thread sanitizer -./configure --with-sanitizers=thread +cmake -B build -DSANITIZERS=thread ``` If you are compiling with GCC you will typically need to install corresponding @@ -579,7 +595,7 @@ See the CI config for more examples, and upstream documentation for more informa about any additional options. Not all sanitizer options can be enabled at the same time, e.g. trying to build -with `--with-sanitizers=address,thread` will fail in the configure script as +with `-DSANITIZERS=address,thread` will fail in the configure script as these sanitizers are mutually incompatible. Refer to your compiler manual to learn more about these options and which sanitizers are supported by your compiler. @@ -593,7 +609,6 @@ Additional resources: * [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) * [GCC Instrumentation Options](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html) * [Google Sanitizers Wiki](https://github.com/google/sanitizers/wiki) - * [Issue #12691: Enable -fsanitize flags in Travis](https://github.com/bitcoin/bitcoin/issues/12691) Locking/mutex usage notes ------------------------- @@ -732,8 +747,6 @@ logging messages. They should be used as follows: useful for debugging and can reasonably be enabled on a production system (that has sufficient free storage space). They will be logged if the program is started with `-debug=category` or `-debug=1`. - Note that `LogPrint(BCLog::CATEGORY, fmt, params...)` is a deprecated - alias for `LogDebug`. - `LogInfo(fmt, params...)` should only be used rarely, e.g. for startup messages or for infrequent and important events such as a new block tip diff --git a/doc/files.md b/doc/files.md index 03e52f02c9..b738d6055a 100644 --- a/doc/files.md +++ b/doc/files.md @@ -34,12 +34,13 @@ Windows | `%LOCALAPPDATA%\Bitcoin\` <sup>[\[1\]](#note1)</sup> 3. All content of the data directory, except for `bitcoin.conf` file, is chain-specific. This means the actual data directory paths for non-mainnet cases differ: -Chain option | Data directory path --------------------------------|------------------------------ -`-chain=main` (default) | *path_to_datadir*`/` -`-chain=test` or `-testnet` | *path_to_datadir*`/testnet3/` -`-chain=signet` or `-signet` | *path_to_datadir*`/signet/` -`-chain=regtest` or `-regtest` | *path_to_datadir*`/regtest/` +Chain option | Data directory path +---------------------------------|------------------------------ +`-chain=main` (default) | *path_to_datadir*`/` +`-chain=test` or `-testnet` | *path_to_datadir*`/testnet3/` +`-chain=testnet4` or `-testnet4` | *path_to_datadir*`/testnet4/` +`-chain=signet` or `-signet` | *path_to_datadir*`/signet/` +`-chain=regtest` or `-regtest` | *path_to_datadir*`/regtest/` ## Data directory layout @@ -47,8 +48,9 @@ Subdirectory | File(s) | Description -------------------|-----------------------|------------ `blocks/` | | Blocks directory; can be specified by `-blocksdir` option (except for `blocks/index/`) `blocks/index/` | LevelDB database | Block index; `-blocksdir` option does not affect this path -`blocks/` | `blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Actual Bitcoin blocks (in network format, dumped in raw on disk, 128 MiB per file) +`blocks/` | `blkNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Actual Bitcoin blocks (dumped in network format, 128 MiB per file) `blocks/` | `revNNNNN.dat`<sup>[\[2\]](#note2)</sup> | Block undo data (custom format) +`blocks/` | `xor.dat` | Rolling XOR pattern for block and undo data files `chainstate/` | LevelDB database | Blockchain state (a compact representation of all currently unspent transaction outputs (UTXOs) and metadata about the transactions they are from) `indexes/txindex/` | LevelDB database | Transaction index; *optional*, used if `-txindex=1` `indexes/blockfilter/basic/db/` | LevelDB database | Blockfilter index LevelDB database for the basic filtertype; *optional*, used if `-blockfilterindex=basic` diff --git a/doc/fuzzing.md b/doc/fuzzing.md index c9fb918c8f..f3647c0840 100644 --- a/doc/fuzzing.md +++ b/doc/fuzzing.md @@ -7,15 +7,17 @@ To quickly get started fuzzing Bitcoin Core using [libFuzzer](https://llvm.org/d ```sh $ git clone https://github.com/bitcoin/bitcoin $ cd bitcoin/ -$ ./autogen.sh -$ CC=clang CXX=clang++ ./configure --enable-fuzz --with-sanitizers=address,fuzzer,undefined +$ cmake --preset=libfuzzer # macOS users: If you have problem with this step then make sure to read "macOS hints for # libFuzzer" on https://github.com/bitcoin/bitcoin/blob/master/doc/fuzzing.md#macos-hints-for-libfuzzer -$ make -$ FUZZ=process_message src/test/fuzz/fuzz +$ cmake --build build_fuzz +$ FUZZ=process_message build_fuzz/src/test/fuzz/fuzz # abort fuzzing using ctrl-c ``` +One can use `--prefix=libfuzzer-nosan` to do the same without common sanitizers enabled. +See [further](#run-without-sanitizers-for-increased-throughput) for more information. + There is also a runner script to execute all fuzz targets. Refer to `./test/fuzz/test_runner.py --help` for more details. @@ -33,7 +35,7 @@ If you specify a corpus directory then any new coverage increasing inputs will b ```sh $ mkdir -p process_message-seeded-from-thin-air/ -$ FUZZ=process_message src/test/fuzz/fuzz process_message-seeded-from-thin-air/ +$ FUZZ=process_message build_fuzz/src/test/fuzz/fuzz process_message-seeded-from-thin-air/ INFO: Seed: 840522292 INFO: Loaded 1 modules (424174 inline 8-bit counters): 424174 [0x55e121ef9ab8, 0x55e121f613a6), INFO: Loaded 1 PC tables (424174 PCs): 424174 [0x55e121f613a8,0x55e1225da288), @@ -77,7 +79,7 @@ of the test. Just make sure to use double-dash to distinguish them from the fuzzer's own arguments: ```sh -$ FUZZ=address_deserialize_v2 src/test/fuzz/fuzz -runs=1 fuzz_seed_corpus/address_deserialize_v2 --checkaddrman=5 --printtoconsole=1 +$ FUZZ=address_deserialize_v2 build_fuzz/src/test/fuzz/fuzz -runs=1 fuzz_corpora/address_deserialize_v2 --checkaddrman=5 --printtoconsole=1 ``` ## Fuzzing corpora @@ -88,11 +90,11 @@ To fuzz `process_message` using the [`bitcoin-core/qa-assets`](https://github.co ```sh $ git clone https://github.com/bitcoin-core/qa-assets -$ FUZZ=process_message src/test/fuzz/fuzz qa-assets/fuzz_seed_corpus/process_message/ +$ FUZZ=process_message build_fuzz/src/test/fuzz/fuzz qa-assets/fuzz_corpora/process_message/ INFO: Seed: 1346407872 INFO: Loaded 1 modules (424174 inline 8-bit counters): 424174 [0x55d8a9004ab8, 0x55d8a906c3a6), INFO: Loaded 1 PC tables (424174 PCs): 424174 [0x55d8a906c3a8,0x55d8a96e5288), -INFO: 991 files found in qa-assets/fuzz_seed_corpus/process_message/ +INFO: 991 files found in qa-assets/fuzz_corpora/process_message/ INFO: -max_len is not provided; libFuzzer will not generate inputs larger than 4096 bytes INFO: seed corpus: files: 991 min: 1b max: 1858b total: 288291b rss: 150Mb #993 INITED cov: 7063 ft: 8236 corp: 25/3821b exec/s: 0 rss: 181Mb @@ -101,7 +103,15 @@ INFO: seed corpus: files: 991 min: 1b max: 1858b total: 288291b rss: 150Mb ## Run without sanitizers for increased throughput -Fuzzing on a harness compiled with `--with-sanitizers=address,fuzzer,undefined` is good for finding bugs. However, the very slow execution even under libFuzzer will limit the ability to find new coverage. A good approach is to perform occasional long runs without the additional bug-detectors (configure `--with-sanitizers=fuzzer`) and then merge new inputs into a corpus as described in the qa-assets repo (https://github.com/bitcoin-core/qa-assets/blob/main/.github/PULL_REQUEST_TEMPLATE.md). Patience is useful; even with improved throughput, libFuzzer may need days and 10s of millions of executions to reach deep/hard targets. +Fuzzing on a harness compiled with `-DSANITIZERS=address,fuzzer,undefined` is +good for finding bugs. However, the very slow execution even under libFuzzer +will limit the ability to find new coverage. A good approach is to perform +occasional long runs without the additional bug-detectors +(`--preset=libfuzzer-nosan`) and then merge new inputs into a corpus as described in +the qa-assets repo +(https://github.com/bitcoin-core/qa-assets/blob/main/.github/PULL_REQUEST_TEMPLATE.md). +Patience is useful; even with improved throughput, libFuzzer may need days and +10s of millions of executions to reach deep/hard targets. ## Reproduce a fuzzer crash reported by the CI @@ -112,8 +122,8 @@ Fuzzing on a harness compiled with `--with-sanitizers=address,fuzzer,undefined` more slowly with sanitizers enabled, but a crash should be reproducible very quickly from a crash case) - run the fuzzer with the case number appended to the seed corpus path: - `FUZZ=process_message src/test/fuzz/fuzz - qa-assets/fuzz_seed_corpus/process_message/1bc91feec9fc00b107d97dc225a9f2cdaa078eb6` + `FUZZ=process_message build_fuzz/src/test/fuzz/fuzz + qa-assets/fuzz_corpora/process_message/1bc91feec9fc00b107d97dc225a9f2cdaa078eb6` ## Submit improved coverage @@ -131,10 +141,13 @@ You may also need to take care of giving the correct path for `clang` and `clang++`, like `CC=/path/to/clang CXX=/path/to/clang++` if the non-systems `clang` does not come first in your path. -Full configure that was tested on macOS with `brew` installed `llvm`: +Full configuration step that was tested on macOS with `brew` installed `llvm`: ```sh -./configure --enable-fuzz --with-sanitizers=fuzzer,address,undefined CC=$(brew --prefix llvm)/bin/clang CXX=$(brew --prefix llvm)/bin/clang++ +$ cmake --preset=libfuzzer \ + -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \ + -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \ + -DAPPEND_LDFLAGS=-Wl,-no_warn_duplicate_libraries ``` Read the [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html) for more information. This [libFuzzer tutorial](https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md) might also be of interest. @@ -150,16 +163,18 @@ $ git clone https://github.com/bitcoin/bitcoin $ cd bitcoin/ $ git clone https://github.com/AFLplusplus/AFLplusplus $ make -C AFLplusplus/ source-only -$ ./autogen.sh # If afl-clang-lto is not available, see # https://github.com/AFLplusplus/AFLplusplus#a-selecting-the-best-afl-compiler-for-instrumenting-the-target -$ CC=$(pwd)/AFLplusplus/afl-clang-lto CXX=$(pwd)/AFLplusplus/afl-clang-lto++ ./configure --enable-fuzz -$ make -# For macOS you may need to ignore x86 compilation checks when running "make". If so, -# try compiling using: AFL_NO_X86=1 make +$ cmake -B build_fuzz \ + -DCMAKE_C_COMPILER="$(pwd)/AFLplusplus/afl-clang-lto" \ + -DCMAKE_CXX_COMPILER="$(pwd)/AFLplusplus/afl-clang-lto++" \ + -DBUILD_FOR_FUZZING=ON +$ cmake --build build_fuzz +# For macOS you may need to ignore x86 compilation checks when running "cmake --build". If so, +# try compiling using: AFL_NO_X86=1 cmake --build build_fuzz $ mkdir -p inputs/ outputs/ $ echo A > inputs/thin-air-input -$ FUZZ=bech32 AFLplusplus/afl-fuzz -i inputs/ -o outputs/ -- src/test/fuzz/fuzz +$ FUZZ=bech32 ./AFLplusplus/afl-fuzz -i inputs/ -o outputs/ -- build_fuzz/src/test/fuzz/fuzz # You may have to change a few kernel parameters to test optimally - afl-fuzz # will print an error and suggestion if so. ``` @@ -175,15 +190,18 @@ To quickly get started fuzzing Bitcoin Core using [Honggfuzz](https://github.com ```sh $ git clone https://github.com/bitcoin/bitcoin $ cd bitcoin/ -$ ./autogen.sh $ git clone https://github.com/google/honggfuzz $ cd honggfuzz/ $ make $ cd .. -$ CC=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang CXX=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++ ./configure --enable-fuzz --with-sanitizers=address,undefined -$ make +$ cmake -B build_fuzz \ + -DCMAKE_C_COMPILER="$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang" \ + -DCMAKE_CXX_COMPILER="$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++" \ + -DBUILD_FOR_FUZZING=ON \ + -DSANITIZERS=address,undefined +$ cmake --build build_fuzz $ mkdir -p inputs/ -$ FUZZ=process_message honggfuzz/honggfuzz -i inputs/ -- src/test/fuzz/fuzz +$ FUZZ=process_message ./honggfuzz/honggfuzz -i inputs/ -- build_fuzz/src/test/fuzz/fuzz ``` Read the [Honggfuzz documentation](https://github.com/google/honggfuzz/blob/master/docs/USAGE.md) for more information. @@ -204,15 +222,10 @@ $ mkdir bitcoin-honggfuzz-p2p/ $ cd bitcoin-honggfuzz-p2p/ $ git clone https://github.com/bitcoin/bitcoin $ cd bitcoin/ -$ ./autogen.sh $ git clone https://github.com/google/honggfuzz $ cd honggfuzz/ $ make $ cd .. -$ CC=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang \ - CXX=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++ \ - ./configure --disable-wallet --with-gui=no \ - --with-sanitizers=address,undefined $ git apply << "EOF" diff --git a/src/compat/compat.h b/src/compat/compat.h index 8195bceaec..cce2b31ff0 100644 @@ -241,7 +254,7 @@ index 7601a6ea84..702d0f56ce 100644 // Check start string, network magic - if (memcmp(hdr.pchMessageStart, m_chain_params.MessageStart(), CMessageHeader::MESSAGE_START_SIZE) != 0) { + if (false && memcmp(hdr.pchMessageStart, m_chain_params.MessageStart(), CMessageHeader::MESSAGE_START_SIZE) != 0) { // skip network magic checking - LogPrint(BCLog::NET, "Header error: Wrong MessageStart %s received, peer=%d\n", HexStr(hdr.pchMessageStart), m_node_id); + LogDebug(BCLog::NET, "Header error: Wrong MessageStart %s received, peer=%d\n", HexStr(hdr.pchMessageStart), m_node_id); return -1; } @@ -788,7 +788,7 @@ CNetMessage V1TransportDeserializer::GetMessage(const std::chrono::microseconds @@ -250,15 +263,21 @@ index 7601a6ea84..702d0f56ce 100644 // Check checksum and header message type string - if (memcmp(hash.begin(), hdr.pchChecksum, CMessageHeader::CHECKSUM_SIZE) != 0) { + if (false && memcmp(hash.begin(), hdr.pchChecksum, CMessageHeader::CHECKSUM_SIZE) != 0) { // skip checksum checking - LogPrint(BCLog::NET, "Header error: Wrong checksum (%s, %u bytes), expected %s was %s, peer=%d\n", + LogDebug(BCLog::NET, "Header error: Wrong checksum (%s, %u bytes), expected %s was %s, peer=%d\n", SanitizeString(msg.m_type), msg.m_message_size, HexStr(Span{hash}.first(CMessageHeader::CHECKSUM_SIZE)), EOF -$ make -C src/ bitcoind +$ cmake -B build_fuzz \ + -DCMAKE_C_COMPILER="$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang" \ + -DCMAKE_CXX_COMPILER="$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++" \ + -DENABLE_WALLET=OFF \ + -DBUILD_GUI=OFF \ + -DSANITIZERS=address,undefined +$ cmake --build build_fuzz --target bitcoind $ mkdir -p inputs/ -$ honggfuzz/honggfuzz --exit_upon_crash --quiet --timeout 4 -n 1 -Q \ +$ ./honggfuzz/honggfuzz --exit_upon_crash --quiet --timeout 4 -n 1 -Q \ -E HFND_TCP_PORT=18444 -f inputs/ -- \ - src/bitcoind -regtest -discover=0 -dns=0 -dnsseed=0 -listenonion=0 \ + build_fuzz/src/bitcoind -regtest -discover=0 -dns=0 -dnsseed=0 -listenonion=0 \ -nodebuglogfile -bind=127.0.0.1:18444 -logthreadnames \ -debug ``` @@ -298,11 +317,9 @@ $ cd Eclipser $ git checkout v1.x $ make $ cd .. -$ ./autogen.sh -$ ./configure --enable-fuzz -$ make +$ cmake -B build_fuzz -DBUILD_FOR_FUZZING=ON $ mkdir -p outputs/ -$ FUZZ=bech32 dotnet Eclipser/build/Eclipser.dll fuzz -p src/test/fuzz/fuzz -t 36000 -o outputs --src stdin +$ FUZZ=bech32 dotnet ./Eclipser/build/Eclipser.dll fuzz -p build_fuzz/src/test/fuzz/fuzz -t 36000 -o outputs --src stdin ``` This will perform 10 hours of fuzzing. @@ -320,7 +337,7 @@ Fuzzing with Eclipser will likely be much more effective if using an existing co ```sh $ git clone https://github.com/bitcoin-core/qa-assets -$ FUZZ=bech32 dotnet Eclipser/build/Eclipser.dll fuzz -p src/test/fuzz/fuzz -t 36000 -i qa-assets/fuzz_seed_corpus/bech32 outputs --src stdin +$ FUZZ=bech32 dotnet Eclipser/build/Eclipser.dll fuzz -p build_fuzz/src/test/fuzz/fuzz -t 36000 -i qa-assets/fuzz_corpora/bech32 outputs --src stdin ``` Note that fuzzing with Eclipser on certain targets (those that create 'full nodes', e.g. `process_message*`) will, diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am deleted file mode 100644 index 8f890da532..0000000000 --- a/doc/man/Makefile.am +++ /dev/null @@ -1,27 +0,0 @@ -dist_man1_MANS= - -if BUILD_BITCOIND - dist_man1_MANS+=bitcoind.1 -endif - -if ENABLE_QT - dist_man1_MANS+=bitcoin-qt.1 -endif - -if BUILD_BITCOIN_CLI - dist_man1_MANS+=bitcoin-cli.1 -endif - -if BUILD_BITCOIN_TX - dist_man1_MANS+=bitcoin-tx.1 -endif - -if BUILD_BITCOIN_UTIL - dist_man1_MANS+=bitcoin-util.1 -endif - -if ENABLE_WALLET -if BUILD_BITCOIN_WALLET - dist_man1_MANS+=bitcoin-wallet.1 -endif -endif diff --git a/doc/multisig-tutorial.md b/doc/multisig-tutorial.md index 1d2b3244bc..1f21acc2be 100644 --- a/doc/multisig-tutorial.md +++ b/doc/multisig-tutorial.md @@ -9,15 +9,13 @@ This tutorial uses [jq](https://github.com/stedolan/jq) JSON processor to proces Before starting this tutorial, start the bitcoin node on the signet network. ```bash -./src/bitcoind -signet -daemon +./build/src/bitcoind -signet -daemon ``` This tutorial also uses the default WPKH derivation path to get the xpubs and does not conform to [BIP 45](https://github.com/bitcoin/bips/blob/master/bip-0045.mediawiki) or [BIP 87](https://github.com/bitcoin/bips/blob/master/bip-0087.mediawiki). At the time of writing, there is no way to extract a specific path from wallets in Bitcoin Core. For this, an external signer/xpub can be used. -[PR #22341](https://github.com/bitcoin/bitcoin/pull/22341), which is still under development, introduces a new wallet RPC `getxpub`. It takes a BIP32 path as an argument and returns the xpub, along with the master key fingerprint. - ## 1.1 Basic Multisig Workflow ### 1.1 Create the Descriptor Wallets @@ -29,7 +27,7 @@ These three wallets should not be used directly for privacy reasons (public key ```bash for ((n=1;n<=3;n++)) do - ./src/bitcoin-cli -signet createwallet "participant_${n}" + ./build/src/bitcoin-cli -signet createwallet "participant_${n}" done ``` @@ -49,9 +47,9 @@ declare -A xpubs for ((n=1;n<=3;n++)) do - xpubs["internal_xpub_${n}"]=$(./src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/1/*"))][0] | .desc' | grep -Po '(?<=\().*(?=\))') + xpubs["internal_xpub_${n}"]=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/1/*"))][0] | .desc' | grep -Po '(?<=\().*(?=\))') - xpubs["external_xpub_${n}"]=$(./src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/0/*") )][0] | .desc' | grep -Po '(?<=\().*(?=\))') + xpubs["external_xpub_${n}"]=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/0/*") )][0] | .desc' | grep -Po '(?<=\().*(?=\))') done ``` @@ -73,8 +71,8 @@ Define the external and internal multisig descriptors, add the checksum and then external_desc="wsh(sortedmulti(2,${xpubs["external_xpub_1"]},${xpubs["external_xpub_2"]},${xpubs["external_xpub_3"]}))" internal_desc="wsh(sortedmulti(2,${xpubs["internal_xpub_1"]},${xpubs["internal_xpub_2"]},${xpubs["internal_xpub_3"]}))" -external_desc_sum=$(./src/bitcoin-cli -signet getdescriptorinfo $external_desc | jq '.descriptor') -internal_desc_sum=$(./src/bitcoin-cli -signet getdescriptorinfo $internal_desc | jq '.descriptor') +external_desc_sum=$(./build/src/bitcoin-cli -signet getdescriptorinfo $external_desc | jq '.descriptor') +internal_desc_sum=$(./build/src/bitcoin-cli -signet getdescriptorinfo $internal_desc | jq '.descriptor') multisig_ext_desc="{\"desc\": $external_desc_sum, \"active\": true, \"internal\": false, \"timestamp\": \"now\"}" multisig_int_desc="{\"desc\": $internal_desc_sum, \"active\": true, \"internal\": true, \"timestamp\": \"now\"}" @@ -96,7 +94,7 @@ There are other fields that can be added to the descriptors: * `internal`: Indicates whether matching outputs should be treated as something other than incoming payments (e.g. change). * `timestamp`: Sets the time from which to start rescanning the blockchain for the descriptor, in UNIX epoch time. -Documentation for these and other parameters can be found by typing `./src/bitcoin-cli help importdescriptors`. +Documentation for these and other parameters can be found by typing `./build/src/bitcoin-cli help importdescriptors`. `multisig_desc` concatenates external and internal descriptors in a JSON array and then it will be used to create the multisig wallet. @@ -109,17 +107,17 @@ Then import the descriptors created in the previous step using the `importdescri After that, `getwalletinfo` can be used to check if the wallet was created successfully. ```bash -./src/bitcoin-cli -signet -named createwallet wallet_name="multisig_wallet_01" disable_private_keys=true blank=true +./build/src/bitcoin-cli -signet -named createwallet wallet_name="multisig_wallet_01" disable_private_keys=true blank=true -./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" importdescriptors "$multisig_desc" +./build/src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" importdescriptors "$multisig_desc" -./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getwalletinfo +./build/src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getwalletinfo ``` Once the wallets have already been created and this tutorial needs to be repeated or resumed, it is not necessary to recreate them, just load them with the command below: ```bash -for ((n=1;n<=3;n++)); do ./src/bitcoin-cli -signet loadwallet "participant_${n}"; done +for ((n=1;n<=3;n++)); do ./build/src/bitcoin-cli -signet loadwallet "participant_${n}"; done ``` ### 1.4 Fund the wallet @@ -133,9 +131,9 @@ The url used by the script can also be accessed directly. At time of writing, th Coins received by the wallet must have at least 1 confirmation before they can be spent. It is necessary to wait for a new block to be mined before continuing. ```bash -receiving_address=$(./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getnewaddress) +receiving_address=$(./build/src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getnewaddress) -./contrib/signet/getcoins.py -c ./src/bitcoin-cli -a $receiving_address +./contrib/signet/getcoins.py -c ./build/src/bitcoin-cli -a $receiving_address ``` To copy the receiving address onto the clipboard, use the following command. This can be useful when getting coins via the signet faucet mentioned above. @@ -147,7 +145,7 @@ echo -n "$receiving_address" | xclip -sel clip The `getbalances` RPC may be used to check the balance. Coins with `trusted` status can be spent. ```bash -./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalances +./build/src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalances ``` ### 1.5 Create a PSBT @@ -163,13 +161,13 @@ For simplicity, the destination address is taken from the `participant_1` wallet The `walletcreatefundedpsbt` RPC is used to create and fund a transaction in the PSBT format. It is the first step in creating the PSBT. ```bash -balance=$(./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalance) +balance=$(./build/src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalance) amount=$(echo "$balance * 0.8" | bc -l | sed -e 's/^\./0./' -e 's/^-\./-0./') -destination_addr=$(./src/bitcoin-cli -signet -rpcwallet="participant_1" getnewaddress) +destination_addr=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_1" getnewaddress) -funded_psbt=$(./src/bitcoin-cli -signet -named -rpcwallet="multisig_wallet_01" walletcreatefundedpsbt outputs="{\"$destination_addr\": $amount}" | jq -r '.psbt') +funded_psbt=$(./build/src/bitcoin-cli -signet -named -rpcwallet="multisig_wallet_01" walletcreatefundedpsbt outputs="{\"$destination_addr\": $amount}" | jq -r '.psbt') ``` There is also the `createpsbt` RPC, which serves the same purpose, but it has no access to the wallet or to the UTXO set. It is functionally the same as `createrawtransaction` and just drops the raw transaction into an otherwise blank PSBT. [[source](https://bitcointalk.org/index.php?topic=5131043.msg50573609#msg50573609)] In most cases, `walletcreatefundedpsbt` solves the problem. @@ -183,9 +181,9 @@ Optionally, the PSBT can be decoded to a JSON format using `decodepsbt` RPC. The `analyzepsbt` RPC analyzes and provides information about the current status of a PSBT and its inputs, e.g. missing signatures. ```bash -./src/bitcoin-cli -signet decodepsbt $funded_psbt +./build/src/bitcoin-cli -signet decodepsbt $funded_psbt -./src/bitcoin-cli -signet analyzepsbt $funded_psbt +./build/src/bitcoin-cli -signet analyzepsbt $funded_psbt ``` ### 1.7 Update the PSBT @@ -195,9 +193,9 @@ In the code above, two PSBTs are created. One signed by `participant_1` wallet a The `walletprocesspsbt` is used by the wallet to sign a PSBT. ```bash -psbt_1=$(./src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq '.psbt') +psbt_1=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq '.psbt') -psbt_2=$(./src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $funded_psbt | jq '.psbt') +psbt_2=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $funded_psbt | jq '.psbt') ``` ### 1.8 Combine the PSBT @@ -205,7 +203,7 @@ psbt_2=$(./src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt The PSBT, if signed separately by the co-signers, must be combined into one transaction before being finalized. This is done by `combinepsbt` RPC. ```bash -combined_psbt=$(./src/bitcoin-cli -signet combinepsbt "[$psbt_1, $psbt_2]") +combined_psbt=$(./build/src/bitcoin-cli -signet combinepsbt "[$psbt_1, $psbt_2]") ``` There is an RPC called `joinpsbts`, but it has a different purpose than `combinepsbt`. `joinpsbts` joins the inputs from multiple distinct PSBTs into one PSBT. @@ -219,9 +217,9 @@ The `finalizepsbt` RPC is used to produce a network serialized transaction which It checks that all inputs have complete scriptSigs and scriptWitnesses and, if so, encodes them into network serialized transactions. ```bash -finalized_psbt_hex=$(./src/bitcoin-cli -signet finalizepsbt $combined_psbt | jq -r '.hex') +finalized_psbt_hex=$(./build/src/bitcoin-cli -signet finalizepsbt $combined_psbt | jq -r '.hex') -./src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hex +./build/src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hex ``` ### 1.10 Alternative Workflow (PSBT sequential signatures) @@ -231,11 +229,11 @@ Instead of each wallet signing the original PSBT and combining them later, the w After that, the rest of the process is the same: the PSBT is finalized and transmitted to the network. ```bash -psbt_1=$(./src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq -r '.psbt') +psbt_1=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq -r '.psbt') -psbt_2=$(./src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $psbt_1 | jq -r '.psbt') +psbt_2=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $psbt_1 | jq -r '.psbt') -finalized_psbt_hex=$(./src/bitcoin-cli -signet finalizepsbt $psbt_2 | jq -r '.hex') +finalized_psbt_hex=$(./build/src/bitcoin-cli -signet finalizepsbt $psbt_2 | jq -r '.hex') -./src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hex +./build/src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hex ``` diff --git a/doc/offline-signing-tutorial.md b/doc/offline-signing-tutorial.md index 401ee52c1c..e03a0003a1 100644 --- a/doc/offline-signing-tutorial.md +++ b/doc/offline-signing-tutorial.md @@ -25,7 +25,7 @@ We are going to first create an `offline_wallet` on the offline host. We will th 1. On the offline machine create a wallet named `offline_wallet` secured by a wallet `passphrase`. This wallet will contain private keys and must remain unconnected to any networks at all times. ```sh -[offline]$ ./src/bitcoin-cli -signet -named createwallet \ +[offline]$ ./build/src/bitcoin-cli -signet -named createwallet \ wallet_name="offline_wallet" \ passphrase="** enter passphrase **" @@ -40,7 +40,7 @@ We are going to first create an `offline_wallet` on the offline host. We will th 2. Export the public key-only descriptors from the offline host to a JSON file named `descriptors.json`. We use `jq` here to extract the `.descriptors` field from the full RPC response. ```sh -[offline]$ ./src/bitcoin-cli -signet -rpcwallet="offline_wallet" listdescriptors \ +[offline]$ ./build/src/bitcoin-cli -signet -rpcwallet="offline_wallet" listdescriptors \ | jq -r '.descriptors' \ >> /path/to/descriptors.json ``` @@ -58,7 +58,7 @@ The `watch_only_wallet` wallet will be used to track and validate incoming trans > `disable_private_keys` indicates that the wallet should refuse to import private keys, i.e. will be a dedicated watch-only wallet. ```sh -[online]$ ./src/bitcoin-cli -signet -named createwallet \ +[online]$ ./build/src/bitcoin-cli -signet -named createwallet \ wallet_name="watch_only_wallet" \ disable_private_keys=true @@ -70,7 +70,7 @@ The `watch_only_wallet` wallet will be used to track and validate incoming trans 2. Import the `offline_wallet`s public key descriptors to the online `watch_only_wallet` using the `descriptors.json` file created on the offline wallet. ```sh -[online]$ ./src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" importdescriptors "$(cat /path/to/descriptors.json)" +[online]$ ./build/src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" importdescriptors "$(cat /path/to/descriptors.json)" [ { @@ -109,7 +109,7 @@ At this point, it's important to understand that both the `offline_wallet` and o 1. Generate an address to receive coins. You can use _either_ the `offline_wallet` or the online `watch_only_wallet` to generate this address, as they will produce the same addresses. For the sake of this guide, we'll use the online `watch_only_wallet` to generate the address. ```sh -[online]$ ./src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" getnewaddress +[online]$ ./build/src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" getnewaddress tb1qtu5qgc6ddhmqm5yqjvhg83qgk2t4ewajg0h6yh ``` @@ -119,7 +119,7 @@ tb1qtu5qgc6ddhmqm5yqjvhg83qgk2t4ewajg0h6yh 3. Confirm that coins were received using the online `watch_only_wallet`. Note that the transaction may take a few moments before being received on your local node, depending on its connectivity. Just re-run the command periodically until the transaction is received. ```sh -[online]$ ./src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" listunspent +[online]$ ./build/src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" listunspent [ { @@ -148,7 +148,7 @@ tb1qtu5qgc6ddhmqm5yqjvhg83qgk2t4ewajg0h6yh 2. Create a funded but unsigned PSBT to the destination address with the online `watch_only_wallet` by using `send [{"address":amount},...]` and export the unsigned PSBT to a file `funded_psbt.txt` for easy portability to the `offline_wallet` for signing: ```sh -[online]$ ./src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" send \ +[online]$ ./build/src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" send \ '{"tb1q9k5w0nhnhyeh78snpxh0t5t7c3lxdeg3erez32": 0.009}' \ | jq -r '.psbt' \ >> /path/to/funded_psbt.txt @@ -165,13 +165,13 @@ cHNidP8BAHECAAAAAWLHKR9/xAjetzL/FCmZU5lbfINRMWPRPHWO68PfUzkPAQAAAAD9////AoA4AQAA Decode and analyze the unsigned PSBT on the `offline_wallet` using the `funded_psbt.txt` file: ```sh -[offline]$ ./src/bitcoin-cli -signet decodepsbt $(cat /path/to/funded_psbt.txt) +[offline]$ ./build/src/bitcoin-cli -signet decodepsbt $(cat /path/to/funded_psbt.txt) { ... } -[offline]$ ./src/bitcoin-cli -signet analyzepsbt $(cat /path/to/funded_psbt.txt) +[offline]$ ./build/src/bitcoin-cli -signet analyzepsbt $(cat /path/to/funded_psbt.txt) { "inputs": [ @@ -202,13 +202,13 @@ Notice that the analysis of the PSBT shows that "signatures" are missing and sho Use the walletpassphrase command to unlock the `offline_wallet` with the passphrase. You should specify the passphrase and a timeout (in seconds) for how long you want the wallet to remain unlocked. ```sh -[offline]$ ./src/bitcoin-cli -signet -rpcwallet="offline_wallet" walletpassphrase "** enter passphrase **" 60 +[offline]$ ./build/src/bitcoin-cli -signet -rpcwallet="offline_wallet" walletpassphrase "** enter passphrase **" 60 ``` 2. Process, sign and finalize the PSBT on the `offline_wallet` using the `walletprocesspsbt` command, saving the output to a file `final_psbt.txt`. ```sh -[offline]$ ./src/bitcoin-cli -signet -rpcwallet="offline_wallet" walletprocesspsbt \ +[offline]$ ./build/src/bitcoin-cli -signet -rpcwallet="offline_wallet" walletprocesspsbt \ $(cat /path/to/funded_psbt.txt) \ | jq -r .hex \ >> /path/to/final_psbt.txt @@ -218,7 +218,7 @@ Use the walletpassphrase command to unlock the `offline_wallet` with the passphr Broadcast the funded, signed and finalized PSBT `final_psbt.txt` using `sendrawtransaction` with an online node: ```sh -[online]$ ./src/bitcoin-cli -signet sendrawtransaction $(cat /path/to/final_psbt.txt) +[online]$ ./build/src/bitcoin-cli -signet sendrawtransaction $(cat /path/to/final_psbt.txt) c2430a0e46df472b04b0ca887bbcd5c4abf7b2ce2eb71de981444a80e2b96d52 ``` @@ -228,7 +228,7 @@ c2430a0e46df472b04b0ca887bbcd5c4abf7b2ce2eb71de981444a80e2b96d52 Confirm the updated balance of the offline wallet using the `watch_only_wallet`. ```sh -[online]$ ./src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" getbalances +[online]$ ./build/src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" getbalances { "mine": { @@ -247,7 +247,7 @@ Confirm the updated balance of the offline wallet using the `watch_only_wallet`. You can also show transactions related to the wallet using `listtransactions` ```sh -[online]$ ./src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" listtransactions +[online]$ ./build/src/bitcoin-cli -signet -rpcwallet="watch_only_wallet" listtransactions { ... diff --git a/doc/policy/mempool-replacements.md b/doc/policy/mempool-replacements.md index d5642eaccc..f044a0f8ad 100644 --- a/doc/policy/mempool-replacements.md +++ b/doc/policy/mempool-replacements.md @@ -10,14 +10,12 @@ A transaction ("replacement transaction") may replace its directly conflicting t their in-mempool descendants (together, "original transactions") if, in addition to passing all other consensus and policy rules, each of the following conditions are met: -1. The directly conflicting transactions all signal replaceability explicitly. A transaction is +1. If `-mempoolfullrbf=0` (the value is 1 by default), the directly conflicting transactions all signal replaceability explicitly. A transaction is signaling BIP125 replaceability if any of its inputs have an nSequence number less than (0xffffffff - 1). A transaction also signals replaceability if its version field is set to 3. *Rationale*: See [BIP125 explanation](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki#motivation). - Use the (`-mempoolfullrbf`) configuration option to allow transaction replacement without enforcement of the - opt-in signaling rule. 2. The replacement transaction only include an unconfirmed input if that input was included in one of the directly conflicting transactions. An unconfirmed input spends an output from a @@ -80,3 +78,5 @@ This set of rules is similar but distinct from BIP125. * Full replace-by-fee enabled as a configurable mempool policy as of **v24.0** ([PR #25353](https://github.com/bitcoin/bitcoin/pull/25353)). + +* Full replace-by-fee is the default policy as of **v28.0** ([PR #30493](https://github.com/bitcoin/bitcoin/pull/30493)). diff --git a/doc/policy/packages.md b/doc/policy/packages.md index a220bdd17f..b432008d7b 100644 --- a/doc/policy/packages.md +++ b/doc/policy/packages.md @@ -38,11 +38,11 @@ The following rules are enforced for all packages: * Only limited package replacements are currently considered. (#28984) - - All direct conflicts must signal replacement (or have `-mempoolfullrbf=1` set). + - If `-mempoolfullrbf=0` (the value is 1 by default), all direct conflicts must signal replacement. - Packages are 1-parent-1-child, with no in-mempool ancestors of the package. - - All conflicting clusters(connected components of mempool transactions) must be clusters of up to size 2. + - All conflicting clusters (connected components of mempool transactions) must be clusters of up to size 2. - No more than MAX_REPLACEMENT_CANDIDATES transactions can be replaced, analogous to regular [replacement rule](./mempool-replacements.md) 5). @@ -56,7 +56,7 @@ The following rules are enforced for all packages: - *Rationale*: Basic support for package RBF can be used by wallets by making chains of no longer than two, then directly conflicting - those chains when needed. Combined with V3 transactions this can + those chains when needed. Combined with TRUC transactions this can result in more robust fee bumping. More general package RBF may be enabled in the future. diff --git a/doc/productivity.md b/doc/productivity.md index e9b7bc270c..f025b4bf6e 100644 --- a/doc/productivity.md +++ b/doc/productivity.md @@ -6,8 +6,8 @@ Table of Contents * [General](#general) * [Cache compilations with `ccache`](#cache-compilations-with-ccache) - * [Disable features with `./configure`](#disable-features-with-configure) - * [Make use of your threads with `make -j`](#make-use-of-your-threads-with-make--j) + * [Disable features when generating the build system](#disable-features-when-generating-the-build-system) + * [Make use of your threads with `-j`](#make-use-of-your-threads-with--j) * [Only build what you need](#only-build-what-you-need) * [Compile on multiple machines](#compile-on-multiple-machines) * [Multiple working directories with `git worktrees`](#multiple-working-directories-with-git-worktrees) @@ -31,9 +31,9 @@ The easiest way to faster compile times is to cache compiles. `ccache` is a way > ccache is a compiler cache. It speeds up recompilation by caching the result of previous compilations and detecting when the same compilation is being done again. Supported languages are C, C++, Objective-C and Objective-C++. -Install `ccache` through your distribution's package manager, and run `./configure` with your normal flags to pick it up. +Install `ccache` through your distribution's package manager, and run `cmake -B build` with your normal configuration options to pick it up. -To use ccache for all your C/C++ projects, follow the symlinks method [here](https://ccache.samba.org/manual/latest.html#_run_modes) to set it up. +To use ccache for all your C/C++ projects, follow the symlinks method [here](https://ccache.dev/manual/latest.html#_run_modes) to set it up. To get the most out of ccache, put something like this in `~/.ccache/ccache.conf`: @@ -46,38 +46,32 @@ Note: base_dir is required for ccache to share cached compiles of the same file You _must not_ set base_dir to "/", or anywhere that contains system headers (according to the ccache docs). -### Disable features with `./configure` +### Disable features when generating the build system -After running `./autogen.sh`, which generates the `./configure` file, use `./configure --help` to identify features that you can disable to save on compilation time. A few common flags: +During the generation of the build system only essential build options are enabled by default to save on compilation time. -```sh ---without-miniupnpc ---without-natpmp ---disable-bench ---disable-wallet ---without-gui -``` +Run `cmake -B build -LH` to see the full list of available options. GUI tools, such as `ccmake` and `cmake-gui`, can be also helpful. -If you do need the wallet enabled, it is common for devs to add `--with-incompatible-bdb`. This uses your system bdb version for the wallet, so you don't have to find a copy of bdb 4.8. Wallets from such a build will be incompatible with any release binary (and vice versa), so use with caution on mainnet. +If you do need the wallet enabled (`-DENABLE_WALLET=ON`), it is common for devs to use your system bdb version for the wallet, so you don't have to find a copy of bdb 4.8. Wallets from such a build will be incompatible with any release binary (and vice versa), so use with caution on mainnet. -### Make use of your threads with `make -j` +### Make use of your threads with `-j` -If you have multiple threads on your machine, you can tell `make` to utilize all of them with: +If you have multiple threads on your machine, you can utilize all of them with: ```sh -make -j"$(($(nproc)+1))" +cmake --build build -j "$(($(nproc)+1))" ``` ### Only build what you need -When rebuilding during development, note that running `make`, without giving a target, will do a lot of work you probably don't need. It will build the GUI (unless you've disabled it) and all the tests (which take much longer to build than the app does). +When rebuilding during development, note that running `cmake --build build`, without giving a target, will do a lot of work you probably don't need. It will build the GUI (if you've enabled it) and all the tests (which take much longer to build than the app does). Obviously, it is important to build and run the tests at appropriate times -- but when you just want a quick compile to check your work, consider picking one or a set of build targets relevant to what you're working on, e.g.: ```sh -make src/bitcoind src/bitcoin-cli -make src/qt/bitcoin-qt -make -C src bitcoin_bench +cmake --build build --target bitcoind bitcoin-cli +cmake --build build --target bitcoin-qt +cmake --build build --target bench_bitcoin ``` (You can and should combine this with `-j`, as above, for a parallel build.) @@ -110,9 +104,9 @@ To squash in `git commit --fixup` commits without rebasing over an updated maste git rebase -i --autosquash "$(git merge-base master HEAD)" ``` -To execute `make check` on every commit since last diverged from master, but without rebasing over an updated master, we can do the following: +To execute `cmake --build build && ctest --test-dir build` on every commit since last diverged from master, but without rebasing over an updated master, we can do the following: ```sh -git rebase -i --exec "make check" "$(git merge-base master HEAD)" +git rebase -i --exec "cmake --build build && ctest --test-dir build" "$(git merge-base master HEAD)" ``` ----- diff --git a/doc/release-28984.md b/doc/release-28984.md deleted file mode 100644 index 3da64f6578..0000000000 --- a/doc/release-28984.md +++ /dev/null @@ -1,6 +0,0 @@ -P2P and network changes ------------------------ - -- Limited package RBF is now enabled, where the proposed conflicting package would result in - a connected component, aka cluster, of size 2 in the mempool. All clusters being conflicted - against must be of size 2 or lower. diff --git a/doc/release-notes-27101.md b/doc/release-notes-27101.md deleted file mode 100644 index 7ce1e9a8c1..0000000000 --- a/doc/release-notes-27101.md +++ /dev/null @@ -1,6 +0,0 @@ -JSON-RPC --------- - -The JSON-RPC server now recognizes JSON-RPC 2.0 requests and responds with -strict adherence to the [specification](https://www.jsonrpc.org/specification). -See [JSON-RPC-interface.md](/doc/JSON-RPC-interface.md#json-rpc-11-vs-20) for details.
\ No newline at end of file diff --git a/doc/release-notes-27114.md b/doc/release-notes-27114.md deleted file mode 100644 index 980ffd78a4..0000000000 --- a/doc/release-notes-27114.md +++ /dev/null @@ -1,2 +0,0 @@ -- Additional flags "in" and "out" have been added to `-whitelist` to control whether - permissions apply to incoming connections and/or manual (default: incoming only).
\ No newline at end of file diff --git a/doc/release-notes-27307.md b/doc/release-notes-27307.md deleted file mode 100644 index 58fc7098b5..0000000000 --- a/doc/release-notes-27307.md +++ /dev/null @@ -1,8 +0,0 @@ -Wallet ---- - -The wallet now detects when wallet transactions conflict with the mempool. Mempool -conflicting transactions can be seen in the `"mempoolconflicts"` field of -`gettransaction`. The inputs of mempool conflicted transactions can now be respent -without manually abandoning the transactions when the parent transaction is dropped -from the mempool, which can cause wallet balances to appear higher. diff --git a/doc/release-notes-27375.md b/doc/release-notes-27375.md deleted file mode 100644 index e3f4ebdf77..0000000000 --- a/doc/release-notes-27375.md +++ /dev/null @@ -1,6 +0,0 @@ -P2P ---- - -UNIX domain sockets can now be used for proxy connections. Set `-onion` or `-proxy` -to the local socket path with the prefix `unix:` (e.g. `-onion=unix:/home/me/torsocket`). -(#27375)
\ No newline at end of file diff --git a/doc/release-notes-27679.md b/doc/release-notes-27679.md deleted file mode 100644 index dbbb30428c..0000000000 --- a/doc/release-notes-27679.md +++ /dev/null @@ -1,2 +0,0 @@ -- unix socket paths are now accepted for `-zmqpubrawblock` and `-zmqpubrawtx` with -the format `-zmqpubrawtx=unix:/path/to/file`
\ No newline at end of file diff --git a/doc/release-notes-29091-29165.md b/doc/release-notes-29091-29165.md deleted file mode 100644 index 9c9f8e4e50..0000000000 --- a/doc/release-notes-29091-29165.md +++ /dev/null @@ -1,5 +0,0 @@ -Build ------ - -GCC 11.1 or later, or Clang 15+ or later, -are now required to compile Bitcoin Core. diff --git a/doc/release-notes-29496.md b/doc/release-notes-29496.md deleted file mode 100644 index 799b2ca01d..0000000000 --- a/doc/release-notes-29496.md +++ /dev/null @@ -1,11 +0,0 @@ -Mempool Policy Changes ----------------------- - -- Transactions with version number set to 3 are now treated as standard on all networks (#29496), - subject to Opt-in Topologically Restricted Until Confirmation (TRUC) Transactions policy as - described in [BIP 431](https://github.com/bitcoin/bips/blob/master/bip-0431.mediawiki). The - policy includes limits on spending unconfirmed outputs (#28948), eviction of a previous descendant - if a more incentive-compatible one is submitted (#29306), and a maximum transaction size of 10,000vB - (#29873). These restrictions simplify the assessment of incentive compatibility of accepting or - replacing TRUC transactions, thus ensuring any replacements are more profitable for the node and - making fee-bumping more reliable. diff --git a/doc/release-notes-29612.md b/doc/release-notes-29612.md deleted file mode 100644 index 31af3cab09..0000000000 --- a/doc/release-notes-29612.md +++ /dev/null @@ -1,8 +0,0 @@ -RPC ---- - -- The `dumptxoutset` RPC now returns the UTXO set dump in a new and - improved format. At the same time the `loadtxoutset` RPC now - expects this new format in dumps it tries to load. Dumps with the - old format are no longer supported and need to be recreated using - the new format in order to be usable. diff --git a/doc/release-notes-29845.md b/doc/release-notes-29845.md deleted file mode 100644 index 4994d0a34d..0000000000 --- a/doc/release-notes-29845.md +++ /dev/null @@ -1,8 +0,0 @@ -RPC ---- - -- the `warnings` field in `getblockchaininfo`, `getmininginfo` and - `getnetworkinfo` now returns all the active node warnings as an array - of strings, instead of just a single warning. The current behaviour - can temporarily be restored by running bitcoind with configuration - option `-deprecatedrpc=warnings`.
\ No newline at end of file diff --git a/doc/release-notes-29987.md b/doc/release-notes-29987.md deleted file mode 100644 index 4d4c2358d1..0000000000 --- a/doc/release-notes-29987.md +++ /dev/null @@ -1,6 +0,0 @@ -Compatibility -============= - -The minimum required glibc to run Bitcoin Core is now -2.31. This means that RHEL 8 and Ubuntu 18.04 (Bionic) -are no-longer supported. (#29987)
\ No newline at end of file diff --git a/doc/release-notes-30058.md b/doc/release-notes-30058.md deleted file mode 100644 index 47e7ae704e..0000000000 --- a/doc/release-notes-30058.md +++ /dev/null @@ -1,7 +0,0 @@ -- When running with -alertnotify, an alert can now be raised multiple -times instead of just once. Previously, it was only raised when unknown -new consensus rules were activated, whereas the scope has now been -increased to include all kernel warnings. Specifically, alerts will now -also be raised when an invalid chain with a large amount of work has -been detected. Additional warnings may be added in the future. -(#30058) diff --git a/doc/release-notes-30192.md b/doc/release-notes-30192.md deleted file mode 100644 index 2a6c17d455..0000000000 --- a/doc/release-notes-30192.md +++ /dev/null @@ -1,6 +0,0 @@ -Build ------ - -`--enable-lcov-branch-coverage` has been removed, given -incompatibilities between lcov version 1 & 2. `LCOV_OPTS` -should be used to set any options instead. diff --git a/doc/release-notes/release-notes-26.2.md b/doc/release-notes/release-notes-26.2.md new file mode 100644 index 0000000000..67d8512dd0 --- /dev/null +++ b/doc/release-notes/release-notes-26.2.md @@ -0,0 +1,94 @@ +26.2 Release Notes +================== + +Bitcoin Core version 26.2 is now available from: + + <https://bitcoincore.org/bin/bitcoin-core-26.2/> + +This release includes new features, various bug fixes and performance +improvements, as well as updated translations. + +Please report bugs using the issue tracker at GitHub: + + <https://github.com/bitcoin/bitcoin/issues> + +To receive security and update notifications, please subscribe to: + + <https://bitcoincore.org/en/list/announcements/join/> + +How to Upgrade +============== + +If you are running an older version, shut it down. Wait until it has completely +shut down (which might take a few minutes in some cases), then run the +installer (on Windows) or just copy over `/Applications/Bitcoin-Qt` (on macOS) +or `bitcoind`/`bitcoin-qt` (on Linux). + +Upgrading directly from a version of Bitcoin Core that has reached its EOL is +possible, but it might take some time if the data directory needs to be migrated. Old +wallet versions of Bitcoin Core are generally supported. + +Compatibility +============== + +Bitcoin Core is supported and extensively tested on operating systems +using the Linux kernel, macOS 11.0+, and Windows 7 and newer. Bitcoin +Core should also work on most other Unix-like systems but is not as +frequently tested on them. It is not recommended to use Bitcoin Core on +unsupported systems. + +Notable changes +=============== + +### Script + +- #29853: sign: don't assume we are parsing a sane TapMiniscript + +### P2P and network changes + +- #29691: Change Luke Dashjr seed to dashjr-list-of-p2p-nodes.us +- #30085: p2p: detect addnode cjdns peers in GetAddedNodeInfo() + +### RPC + +- #29869: rpc, bugfix: Enforce maximum value for setmocktime +- #28554: bugfix: throw an error if an invalid parameter is passed to getnetworkhashps RPC +- #30094: rpc: move UniValue in blockToJSON +- #29870: rpc: Reword SighashFromStr error message + +### Build + +- #29747: depends: fix mingw-w64 Qt DEBUG=1 build +- #29985: depends: Fix build of Qt for 32-bit platforms with recent glibc +- #30151: depends: Fetch miniupnpc sources from an alternative website +- #30283: upnp: fix build with miniupnpc 2.2.8 + +### Misc + +- #29776: ThreadSanitizer: Fix #29767 +- #29856: ci: Bump s390x to ubuntu:24.04 +- #29764: doc: Suggest installing dev packages for debian/ubuntu qt5 build +- #30149: contrib: Renew Windows code signing certificate + +Credits +======= + +Thanks to everyone who directly contributed to this release: + +- Antoine Poinsot +- Ava Chow +- Cory Fields +- dergoegge +- fanquake +- glozow +- Hennadii Stepanov +- Jameson Lopp +- jonatack +- laanwj +- Luke Dashjr +- MarcoFalke +- nanlour +- willcl-ark + +As well as to everyone that helped with translations on +[Transifex](https://www.transifex.com/bitcoin/bitcoin/). diff --git a/doc/release-notes/release-notes-27064.md b/doc/release-notes/release-notes-27064.md deleted file mode 100644 index be3ecee1b8..0000000000 --- a/doc/release-notes/release-notes-27064.md +++ /dev/null @@ -1,7 +0,0 @@ -Files ------ - -The default data directory on Windows has been moved from `C:\Users\Username\AppData\Roaming\Bitcoin` -to `C:\Users\Username\AppData\Local\Bitcoin`. Bitcoin Core will check the existence -of the old directory first and continue to use that directory for backwards -compatibility if it is present.
\ No newline at end of file diff --git a/doc/release-process.md b/doc/release-process.md index 1e6d49100e..aeaed8d68c 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -5,14 +5,14 @@ Release Process ### Before every release candidate -* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`). +* Update release candidate version in `CMakeLists.txt` (`CLIENT_VERSION_RC`). * Update manpages (after rebuilding the binaries), see [gen-manpages.py](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagespy). * Update bitcoin.conf and commit changes if they exist, see [gen-bitcoin-conf.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-bitcoin-confsh). ### Before every major and minor release * Update [bips.md](bips.md) to account for changes since the last release. -* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_RC` to `0`). +* Update version in `CMakeLists.txt` (don't forget to set `CLIENT_VERSION_RC` to `0`). * Update manpages (see previous section) * Write release notes (see "Write the release notes" below) in doc/release-notes.md. If necessary, archive the previous release notes as doc/release-notes/release-notes-${VERSION}.md. @@ -20,8 +20,8 @@ Release Process ### Before every major release * On both the master branch and the new release branch: - - update `CLIENT_VERSION_MAJOR` in [`configure.ac`](../configure.ac) -* On the new release branch in [`configure.ac`](../configure.ac)(see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd)): + - update `CLIENT_VERSION_MAJOR` in [`CMakeLists.txt`](../CMakeLists.txt) +* On the new release branch in [`CMakeLists.txt`](../CMakeLists.txt)(see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd)): - set `CLIENT_VERSION_MINOR` to `0` - set `CLIENT_VERSION_BUILD` to `0` - set `CLIENT_VERSION_IS_RELEASE` to `true` @@ -311,13 +311,15 @@ Both variables are used as a guideline for how much space the user needs on thei Note that all values should be taken from a **fully synced** node and have an overhead of 5-10% added on top of its base value. To calculate `m_assumed_blockchain_size`, take the size in GiB of these directories: -- For `mainnet` -> the data directory, excluding the `/testnet3`, `/signet`, and `/regtest` directories and any overly large files, e.g. a huge `debug.log` +- For `mainnet` -> the data directory, excluding the `/testnet3`, `/testnet4`, `/signet`, and `/regtest` directories and any overly large files, e.g. a huge `debug.log` - For `testnet` -> `/testnet3` +- For `testnet4` -> `/testnet4` - For `signet` -> `/signet` To calculate `m_assumed_chain_state_size`, take the size in GiB of these directories: - For `mainnet` -> `/chainstate` - For `testnet` -> `/testnet3/chainstate` +- For `testnet4` -> `/testnet4/chainstate` - For `signet` -> `/signet/chainstate` Notes: diff --git a/doc/tor.md b/doc/tor.md index 65aa3ece02..9560dc29eb 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -193,7 +193,7 @@ In a typical situation, where you're only reachable via Tor, this should suffice listen on all devices and another node could establish a clearnet connection, when knowing your address. To mitigate this, additionally bind the address of your Tor proxy: - ./bitcoind ... -bind=127.0.0.1 + ./bitcoind ... -bind=127.0.0.1:8334=onion If you don't care too much about hiding your node, and want to be reachable on IPv4 as well, use `discover` instead: diff --git a/doc/tracing.md b/doc/tracing.md index 0e3414205a..3948b1ab49 100644 --- a/doc/tracing.md +++ b/doc/tracing.md @@ -366,13 +366,13 @@ USDT support. To list probes in Bitcoin Core, use `info probes` in `gdb`: ``` -$ gdb ./src/bitcoind +$ gdb ./build/src/bitcoind … (gdb) info probes Type Provider Name Where Semaphore Object -stap net inbound_message 0x000000000014419e /src/bitcoind -stap net outbound_message 0x0000000000107c05 /src/bitcoind -stap validation block_connected 0x00000000002fb10c /src/bitcoind +stap net inbound_message 0x000000000014419e /build/src/bitcoind +stap net outbound_message 0x0000000000107c05 /build/src/bitcoind +stap validation block_connected 0x00000000002fb10c /build/src/bitcoind … ``` @@ -382,7 +382,7 @@ The `readelf` tool can be used to display the USDT tracepoints in Bitcoin Core. Look for the notes with the description `NT_STAPSDT`. ``` -$ readelf -n ./src/bitcoind | grep NT_STAPSDT -A 4 -B 2 +$ readelf -n ./build/src/bitcoind | grep NT_STAPSDT -A 4 -B 2 Displaying notes found in: .note.stapsdt Owner Data size Description stapsdt 0x0000005d NT_STAPSDT (SystemTap probe descriptors) @@ -406,7 +406,7 @@ between distributions. For example, on [ubuntu binary]: https://github.com/iovisor/bcc/blob/master/INSTALL.md#ubuntu---binary ``` -$ tplist -l ./src/bitcoind -v +$ tplist -l ./build/src/bitcoind -v b'net':b'outbound_message' [sema 0x0] 1 location(s) 6 argument(s) |