diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build-freebsd.md | 19 | ||||
| -rw-r--r-- | doc/build-netbsd.md | 14 | ||||
| -rw-r--r-- | doc/build-openbsd.md | 12 | ||||
| -rw-r--r-- | doc/developer-notes.md | 122 | ||||
| -rw-r--r-- | doc/fuzzing.md | 249 | ||||
| -rw-r--r-- | doc/release-notes.md | 210 |
6 files changed, 272 insertions, 354 deletions
diff --git a/doc/build-freebsd.md b/doc/build-freebsd.md index 4831623504..f48855a344 100644 --- a/doc/build-freebsd.md +++ b/doc/build-freebsd.md @@ -10,7 +10,7 @@ This guide does not contain instructions for building the GUI. You will need the following dependencies, which can be installed as root via pkg: -```shell +```bash pkg install autoconf automake boost-libs git gmake libevent libtool pkgconf git clone https://github.com/bitcoin/bitcoin.git @@ -18,7 +18,7 @@ git clone https://github.com/bitcoin/bitcoin.git In order to run the test suite (recommended), you will need to have Python 3 installed: -```shell +```bash pkg install python3 ``` @@ -29,32 +29,33 @@ See [dependencies.md](dependencies.md) for a complete overview. BerkeleyDB is only necessary for the wallet functionality. To skip this, pass `--disable-wallet` to `./configure` and skip to the next section. -```shell +```bash ./contrib/install_db4.sh `pwd` export BDB_PREFIX="$PWD/db4" ``` ## Building Bitcoin Core -**Important**: Use `gmake` (the non-GNU `make` will exit with an error): +**Important**: Use `gmake` (the non-GNU `make` will exit with an error). With wallet: -```shell +```bash ./autogen.sh ./configure --with-gui=no \ BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ - BDB_CFLAGS="-I${BDB_PREFIX}/include" + BDB_CFLAGS="-I${BDB_PREFIX}/include" \ + MAKE=gmake ``` Without wallet: -```shell +```bash ./autogen.sh -./configure --with-gui=no --disable-wallet +./configure --with-gui=no --disable-wallet MAKE=gmake ``` followed by: -```shell +```bash gmake # use -jX here for parallelism gmake check # Run tests if Python 3 is available ``` diff --git a/doc/build-netbsd.md b/doc/build-netbsd.md index ab422f6aa7..47049a780e 100644 --- a/doc/build-netbsd.md +++ b/doc/build-netbsd.md @@ -37,13 +37,13 @@ from ports, for the same reason as boost above (g++/libstd++ incompatibility). If you have to build it yourself, you can use [the installation script included in contrib/](/contrib/install_db4.sh) like so: -```shell +```bash ./contrib/install_db4.sh `pwd` ``` from the root of the repository. Then set `BDB_PREFIX` for the next section: -```shell +```bash export BDB_PREFIX="$PWD/db4" ``` @@ -52,24 +52,26 @@ export BDB_PREFIX="$PWD/db4" **Important**: Use `gmake` (the non-GNU `make` will exit with an error). With wallet: -``` +```bash ./autogen.sh ./configure --with-gui=no CPPFLAGS="-I/usr/pkg/include" \ LDFLAGS="-L/usr/pkg/lib" \ BOOST_CPPFLAGS="-I/usr/pkg/include" \ BOOST_LDFLAGS="-L/usr/pkg/lib" \ BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ - BDB_CFLAGS="-I${BDB_PREFIX}/include" + BDB_CFLAGS="-I${BDB_PREFIX}/include" \ + MAKE=gmake ``` Without wallet: -``` +```bash ./autogen.sh ./configure --with-gui=no --disable-wallet \ CPPFLAGS="-I/usr/pkg/include" \ LDFLAGS="-L/usr/pkg/lib" \ BOOST_CPPFLAGS="-I/usr/pkg/include" \ - BOOST_LDFLAGS="-L/usr/pkg/lib" + BOOST_LDFLAGS="-L/usr/pkg/lib" \ + MAKE=gmake ``` Build and run the tests: diff --git a/doc/build-openbsd.md b/doc/build-openbsd.md index dad2566a6c..53c647ae34 100644 --- a/doc/build-openbsd.md +++ b/doc/build-openbsd.md @@ -38,19 +38,19 @@ from ports, for the same reason as boost above (g++/libstd++ incompatibility). If you have to build it yourself, you can use [the installation script included in contrib/](/contrib/install_db4.sh) like so: -```shell +```bash ./contrib/install_db4.sh `pwd` CC=cc CXX=c++ ``` from the root of the repository. Then set `BDB_PREFIX` for the next section: -```shell +```bash export BDB_PREFIX="$PWD/db4" ``` ### Building Bitcoin Core -**Important**: use `gmake`, not `make`. The non-GNU `make` will exit with a horrible error. +**Important**: Use `gmake` (the non-GNU `make` will exit with an error). Preparation: ```bash @@ -70,12 +70,14 @@ Make sure `BDB_PREFIX` is set to the appropriate path from the above steps. To configure with wallet: ```bash ./configure --with-gui=no CC=cc CXX=c++ \ - BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" BDB_CFLAGS="-I${BDB_PREFIX}/include" + BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \ + BDB_CFLAGS="-I${BDB_PREFIX}/include" \ + MAKE=gmake ``` To configure without wallet: ```bash -./configure --disable-wallet --with-gui=no CC=cc CXX=c++ +./configure --disable-wallet --with-gui=no CC=cc CXX=c++ MAKE=gmake ``` Build and run the tests: diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 6e8bde47f8..da07080724 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -43,6 +43,7 @@ Developer Notes - [Suggestions and examples](#suggestions-and-examples) - [Release notes](#release-notes) - [RPC interface guidelines](#rpc-interface-guidelines) + - [Internal interface guidelines](#internal-interface-guidelines) <!-- markdown-toc end --> @@ -1100,3 +1101,124 @@ A few guidelines for introducing and reviewing new RPC interfaces: timestamps in the documentation. - *Rationale*: User-facing consistency. + +Internal interface guidelines +----------------------------- + +Internal interfaces between parts of the codebase that are meant to be +independent (node, wallet, GUI), are defined in +[`src/interfaces/`](../src/interfaces/). The main interface classes defined +there are [`interfaces::Chain`](../src/interfaces/chain.h), used by wallet to +access the node's latest chain state, +[`interfaces::Node`](../src/interfaces/node.h), used by the GUI to control the +node, and [`interfaces::Wallet`](../src/interfaces/wallet.h), used by the GUI +to control an individual wallet. There are also more specialized interface +types like [`interfaces::Handler`](../src/interfaces/handler.h) +[`interfaces::ChainClient`](../src/interfaces/chain.h) passed to and from +various interface methods. + +Interface classes are written in a particular style so node, wallet, and GUI +code doesn't need to run in the same process, and so the class declarations +work more easily with tools and libraries supporting interprocess +communication: + +- Interface classes should be abstract and have methods that are [pure + virtual](https://en.cppreference.com/w/cpp/language/abstract_class). This + allows multiple implementations to inherit from the same interface class, + particularly so one implementation can execute functionality in the local + process, and other implementations can forward calls to remote processes. + +- Interface method definitions should wrap existing functionality instead of + implementing new functionality. Any substantial new node or wallet + functionality should be implemented in [`src/node/`](../src/node/) or + [`src/wallet/`](../src/wallet/) and just exposed in + [`src/interfaces/`](../src/interfaces/) instead of being implemented there, + so it can be more modular and accessible to unit tests. + +- Interface method parameter and return types should either be serializable or + be other interface classes. Interface methods shouldn't pass references to + objects that can't be serialized or accessed from another process. + + Examples: + + ```c++ + // Good: takes string argument and returns interface class pointer + virtual unique_ptr<interfaces::Wallet> loadWallet(std::string filename) = 0; + + // Bad: returns CWallet reference that can't be used from another process + virtual CWallet& loadWallet(std::string filename) = 0; + ``` + + ```c++ + // Good: accepts and returns primitive types + virtual bool findBlock(const uint256& hash, int& out_height, int64_t& out_time) = 0; + + // Bad: returns pointer to internal node in a linked list inaccessible to + // other processes + virtual const CBlockIndex* findBlock(const uint256& hash) = 0; + ``` + + ```c++ + // Good: takes plain callback type and returns interface pointer + using TipChangedFn = std::function<void(int block_height, int64_t block_time)>; + virtual std::unique_ptr<interfaces::Handler> handleTipChanged(TipChangedFn fn) = 0; + + // Bad: returns boost connection specific to local process + using TipChangedFn = std::function<void(int block_height, int64_t block_time)>; + virtual boost::signals2::scoped_connection connectTipChanged(TipChangedFn fn) = 0; + ``` + +- For consistency and friendliness to code generation tools, interface method + input and inout parameters should be ordered first and output parameters + should come last. + + Example: + + ```c++ + // Good: error output param is last + virtual bool broadcastTransaction(const CTransactionRef& tx, CAmount max_fee, std::string& error) = 0; + + // Bad: error output param is between input params + virtual bool broadcastTransaction(const CTransactionRef& tx, std::string& error, CAmount max_fee) = 0; + ``` + +- For friendliness to code generation tools, interface methods should not be + overloaded: + + Example: + + ```c++ + // Good: method names are unique + virtual bool disconnectByAddress(const CNetAddr& net_addr) = 0; + virtual bool disconnectById(NodeId id) = 0; + + // Bad: methods are overloaded by type + virtual bool disconnect(const CNetAddr& net_addr) = 0; + virtual bool disconnect(NodeId id) = 0; + ``` + +- For consistency and friendliness to code generation tools, interface method + names should be `lowerCamelCase` and standalone function names should be + `UpperCamelCase`. + + Examples: + + ```c++ + // Good: lowerCamelCase method name + virtual void blockConnected(const CBlock& block, int height) = 0; + + // Bad: uppercase class method + virtual void BlockConnected(const CBlock& block, int height) = 0; + ``` + + ```c++ + // Good: UpperCamelCase standalone function name + std::unique_ptr<Node> MakeNode(LocalInit& init); + + // Bad: lowercase standalone function + std::unique_ptr<Node> makeNode(LocalInit& init); + ``` + + Note: This last convention isn't generally followed outside of + [`src/interfaces/`](../src/interfaces/), though it did come up for discussion + before in [#14635](https://github.com/bitcoin/bitcoin/pull/14635). diff --git a/doc/fuzzing.md b/doc/fuzzing.md index c34ca4cb59..9642337821 100644 --- a/doc/fuzzing.md +++ b/doc/fuzzing.md @@ -1,125 +1,93 @@ -Fuzz-testing Bitcoin Core -========================== - -A special test harness in `src/test/fuzz/` is provided for each fuzz target to -provide an easy entry point for fuzzers and the like. In this document we'll -describe how to use it with AFL and libFuzzer. - -## Preparing fuzzing - -The fuzzer needs some inputs to work on, but the inputs or seeds can be used -interchangeably between libFuzzer and AFL. - -Extract the example seeds (or other starting inputs) into the inputs -directory before starting fuzzing. - -``` -git clone https://github.com/bitcoin-core/qa-assets -export DIR_FUZZ_IN=$PWD/qa-assets/fuzz_seed_corpus -``` - -AFL needs an input directory with examples, and an output directory where it -will place examples that it found. These can be anywhere in the file system, -we'll define environment variables to make it easy to reference them. - -So, only for AFL you need to configure the outputs path: - -``` -mkdir outputs -export AFLOUT=$PWD/outputs -``` - -libFuzzer will use the input directory as output directory. - -## AFL - -### Building AFL - -It is recommended to always use the latest version of afl: -``` -wget http://lcamtuf.coredump.cx/afl/releases/afl-latest.tgz -tar -zxvf afl-latest.tgz -cd afl-<version> -make -export AFLPATH=$PWD -``` - -For macOS you may need to ignore x86 compilation checks when running `make`: -`AFL_NO_X86=1 make`. - -### Instrumentation - -To build Bitcoin Core using AFL instrumentation (this assumes that the -`AFLPATH` was set as above): -``` -./configure --disable-ccache --disable-shared --enable-tests --enable-fuzz CC=${AFLPATH}/afl-gcc CXX=${AFLPATH}/afl-g++ -export AFL_HARDEN=1 -make -``` - -If you are using clang you will need to substitute `afl-gcc` with `afl-clang` -and `afl-g++` with `afl-clang++`, so the first line above becomes: -``` -./configure --disable-ccache --disable-shared --enable-tests --enable-fuzz CC=${AFLPATH}/afl-clang CXX=${AFLPATH}/afl-clang++ -``` - -We disable ccache because we don't want to pollute the ccache with instrumented -objects, and similarly don't want to use non-instrumented cached objects linked -in. - -The fuzzing can be sped up significantly (~200x) by using `afl-clang-fast` and -`afl-clang-fast++` in place of `afl-gcc` and `afl-g++` when compiling. When -compiling using `afl-clang-fast`/`afl-clang-fast++` the resulting -binary will be instrumented in such a way that the AFL -features "persistent mode" and "deferred forkserver" can be used. See -https://github.com/google/AFL/tree/master/llvm_mode for details. - -### Fuzzing - -To start the actual fuzzing use: - -``` -export FUZZ_TARGET=bech32 # Pick a fuzz_target -mkdir ${AFLOUT}/${FUZZ_TARGET} -$AFLPATH/afl-fuzz -i ${DIR_FUZZ_IN}/${FUZZ_TARGET} -o ${AFLOUT}/${FUZZ_TARGET} -m52 -- src/test/fuzz/${FUZZ_TARGET} -``` - -You may have to change a few kernel parameters to test optimally - `afl-fuzz` -will print an error and suggestion if so. - -On macOS you may need to set `AFL_NO_FORKSRV=1` to get the target to run. -``` -export FUZZ_TARGET=bech32 # Pick a fuzz_target -mkdir ${AFLOUT}/${FUZZ_TARGET} -AFL_NO_FORKSRV=1 $AFLPATH/afl-fuzz -i ${DIR_FUZZ_IN}/${FUZZ_TARGET} -o ${AFLOUT}/${FUZZ_TARGET} -m52 -- src/test/fuzz/${FUZZ_TARGET} -``` - -## libFuzzer - -A recent version of `clang`, the address/undefined sanitizers (ASan/UBSan) and -libFuzzer is needed (all found in the `compiler-rt` runtime libraries package). - -To build all fuzz targets with libFuzzer, run - -``` -./configure --disable-ccache --enable-fuzz --with-sanitizers=fuzzer,address,undefined CC=clang CXX=clang++ -make -``` - -See https://llvm.org/docs/LibFuzzer.html#running on how to run the libFuzzer -instrumented executable. - -Alternatively, you can run the script through the fuzzing test harness (only -libFuzzer supported so far). You need to pass it the inputs directory and -the specific test target you want to run. - -``` -./test/fuzz/test_runner.py ${DIR_FUZZ_IN} bech32 -``` - -### macOS hints for libFuzzer - -The default clang/llvm version supplied by Apple on macOS does not include +# Fuzzing Bitcoin Core using libFuzzer + +## Quickstart guide + +To quickly get started fuzzing Bitcoin Core using [libFuzzer](https://llvm.org/docs/LibFuzzer.html): + +```sh +$ git clone https://github.com/bitcoin/bitcoin +$ cd bitcoin/ +$ ./autogen.sh +$ CC=clang CXX=clang++ ./configure --enable-fuzz --with-sanitizers=address,fuzzer,undefined +# macOS users: If you have problem with this step then make sure to read "macOS hints for +# libFuzzer" on https://github.com/bitcoin/bitcoin/blob/master/doc/fuzzing.md#macos-hints-for-libfuzzer +$ make +$ src/test/fuzz/process_message +# abort fuzzing using ctrl-c +``` + +## Fuzzing harnesses, fuzzing output and fuzzing corpora + +[`process_message`](https://github.com/bitcoin/bitcoin/blob/master/src/test/fuzz/process_message.cpp) is a fuzzing harness for the [`ProcessMessage(...)` function (`net_processing`)](https://github.com/bitcoin/bitcoin/blob/master/src/net_processing.cpp). The available fuzzing harnesses are found in [`src/test/fuzz/`](https://github.com/bitcoin/bitcoin/tree/master/src/test/fuzz). + +The fuzzer will output `NEW` every time it has created a test input that covers new areas of the code under test. For more information on how to interpret the fuzzer output, see the [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html). + +If you specify a corpus directory then any new coverage increasing inputs will be saved there: + +```sh +$ mkdir -p process_message-seeded-from-thin-air/ +$ src/test/fuzz/process_message 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), +INFO: 0 files found in process_message-seeded-from-thin-air/ +INFO: -max_len is not provided; libFuzzer will not generate inputs larger than 4096 bytes +INFO: A corpus is not provided, starting from an empty corpus +#2 INITED cov: 94 ft: 95 corp: 1/1b exec/s: 0 rss: 150Mb +#3 NEW cov: 95 ft: 96 corp: 2/3b lim: 4 exec/s: 0 rss: 150Mb L: 2/2 MS: 1 InsertByte- +#4 NEW cov: 96 ft: 98 corp: 3/7b lim: 4 exec/s: 0 rss: 150Mb L: 4/4 MS: 1 CrossOver- +#21 NEW cov: 96 ft: 100 corp: 4/11b lim: 4 exec/s: 0 rss: 150Mb L: 4/4 MS: 2 ChangeBit-CrossOver- +#324 NEW cov: 101 ft: 105 corp: 5/12b lim: 6 exec/s: 0 rss: 150Mb L: 6/6 MS: 5 CrossOver-ChangeBit-CopyPart-ChangeBit-ChangeBinInt- +#1239 REDUCE cov: 102 ft: 106 corp: 6/24b lim: 14 exec/s: 0 rss: 150Mb L: 13/13 MS: 5 ChangeBit-CrossOver-EraseBytes-ChangeBit-InsertRepeatedBytes- +#1272 REDUCE cov: 102 ft: 106 corp: 6/23b lim: 14 exec/s: 0 rss: 150Mb L: 12/12 MS: 3 ChangeBinInt-ChangeBit-EraseBytes- + NEW_FUNC[1/677]: 0x55e11f456690 in std::_Function_base::~_Function_base() /usr/lib/gcc/x86_64-linux-gnu/8/../../../../include/c++/8/bits/std_function.h:255 + NEW_FUNC[2/677]: 0x55e11f465800 in CDataStream::CDataStream(std::vector<unsigned char, std::allocator<unsigned char> > const&, int, int) src/./streams.h:248 +#2125 REDUCE cov: 4820 ft: 4867 corp: 7/29b lim: 21 exec/s: 0 rss: 155Mb L: 6/12 MS: 2 CopyPart-CMP- DE: "block"- + NEW_FUNC[1/9]: 0x55e11f64d790 in std::_Rb_tree<uint256, std::pair<uint256 const, std::chrono::duration<long, std::ratio<1l, 1000000l> > >, std::_Select1st<std::pair<uint256 const, std::chrono::duration<long, std::ratio<1l, 1000000l> > > >, std::less<uint256>, std::allocator<std::pair<uint256 const, std::chrono::duration<long, std::ratio<1l, 1000000l> > > > >::~_Rb_tree() /usr/lib/gcc/x86_64-linux-gnu/8/../../../../include/c++/8/bits/stl_tree.h:972 + NEW_FUNC[2/9]: 0x55e11f64d870 in std::_Rb_tree<uint256, std::pair<uint256 const, std::chrono::duration<long, std::ratio<1l, 1000000l> > >, std::_Select1st<std::pair<uint256 const, std::chrono::duration<long, std::ratio<1l, 1000000l> > > >, std::less<uint256>, std::allocator<std::pair<uint256 const, std::chrono::duration<long, std::ratio<1l, 1000000l> > > > >::_M_erase(std::_Rb_tree_node<std::pair<uint256 const, std::chrono::duration<long, std::ratio<1l, 1000000l> > > >*) /usr/lib/gcc/x86_64-linux-gnu/8/../../../../include/c++/8/bits/stl_tree.h:1875 +#2228 NEW cov: 4898 ft: 4971 corp: 8/35b lim: 21 exec/s: 0 rss: 156Mb L: 6/12 MS: 3 EraseBytes-CopyPart-PersAutoDict- DE: "block"- + NEW_FUNC[1/5]: 0x55e11f46df70 in std::enable_if<__and_<std::allocator_traits<zero_after_free_allocator<char> >::__construct_helper<char, unsigned char const&>::type>::value, void>::type std::allocator_traits<zero_after_free_allocator<char> >::_S_construct<char, unsigned char const&>(zero_after_free_allocator<char>&, char*, unsigned char const&) /usr/lib/gcc/x86_64-linux-gnu/8/../../../../include/c++/8/bits/alloc_traits.h:243 + NEW_FUNC[2/5]: 0x55e11f477390 in std::vector<unsigned char, std::allocator<unsigned char> >::data() /usr/lib/gcc/x86_64-linux-gnu/8/../../../../include/c++/8/bits/stl_vector.h:1056 +#2456 NEW cov: 4933 ft: 5042 corp: 9/55b lim: 21 exec/s: 0 rss: 160Mb L: 20/20 MS: 3 ChangeByte-InsertRepeatedBytes-PersAutoDict- DE: "block"- +#2467 NEW cov: 4933 ft: 5043 corp: 10/76b lim: 21 exec/s: 0 rss: 161Mb L: 21/21 MS: 1 InsertByte- +#4215 NEW cov: 4941 ft: 5129 corp: 17/205b lim: 29 exec/s: 4215 rss: 350Mb L: 29/29 MS: 5 InsertByte-ChangeBit-CopyPart-InsertRepeatedBytes-CrossOver- +#4567 REDUCE cov: 4941 ft: 5129 corp: 17/204b lim: 29 exec/s: 4567 rss: 404Mb L: 24/29 MS: 2 ChangeByte-EraseBytes- +#6642 NEW cov: 4941 ft: 5138 corp: 18/244b lim: 43 exec/s: 2214 rss: 450Mb L: 43/43 MS: 3 CopyPart-CMP-CrossOver- DE: "verack"- +# abort fuzzing using ctrl-c +$ ls process_message-seeded-from-thin-air/ +349ac589fc66a09abc0b72bb4ae445a7a19e2cd8 4df479f1f421f2ea64b383cd4919a272604087a7 +a640312c98dcc55d6744730c33e41c5168c55f09 b135de16e4709558c0797c15f86046d31c5d86d7 +c000f7b41b05139de8b63f4cbf7d1ad4c6e2aa7f fc52cc00ec1eb1c08470e69f809ae4993fa70082 +$ cat --show-nonprinting process_message-seeded-from-thin-air/349ac589fc66a09abc0b72bb4ae445a7a19e2cd8 +block^@M-^?M-^?M-^?M-^?M-^?nM-^?M-^? +``` + +In this case the fuzzer managed to create a `block` message which when passed to `ProcessMessage(...)` increased coverage. + +The project's collection of seed corpora is found in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. + +To fuzz `process_message` using the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) seed corpus: + +```sh +$ git clone https://github.com/bitcoin-core/qa-assets +$ src/test/fuzz/process_message qa-assets/fuzz_seed_corpus/process_message/ +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: -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 +… +``` + +If you find coverage increasing inputs when fuzzing you are highly encouraged to submit them for inclusion in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. + +Every single pull request submitted against the Bitcoin Core repo is automatically tested against all inputs in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. Contributing new coverage increasing inputs is an easy way to help make Bitcoin Core more robust. + +## macOS hints for libFuzzer + +The default Clang/LLVM version supplied by Apple on macOS does not include fuzzing libraries, so macOS users will need to install a full version, for example using `brew install llvm`. @@ -128,11 +96,40 @@ may need to run `./configure` with `--disable-asm` to avoid errors with certain assembly code from Bitcoin Core's code. See [developer notes on sanitizers](https://github.com/bitcoin/bitcoin/blob/master/doc/developer-notes.md#sanitizers) for more information. -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. +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 Catalina with `brew` installed `llvm`: + +```sh +./configure --enable-fuzz --with-sanitizers=fuzzer,address,undefined CC=/usr/local/opt/llvm/bin/clang CXX=/usr/local/opt/llvm/bin/clang++ --disable-asm ``` -./configure --disable-ccache --enable-fuzz --with-sanitizers=fuzzer,address,undefined CC=/usr/local/opt/llvm/bin/clang CXX=/usr/local/opt/llvm/bin/clang++ --disable-asm + +Read the [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html) for more information. This [libFuzzer tutorial](https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md) might also be of interest. + +# Fuzzing Bitcoin Core using american fuzzy lop (`afl-fuzz`) + +## Quickstart guide + +To quickly get started fuzzing Bitcoin Core using [`afl-fuzz`](https://github.com/google/afl): + +```sh +$ git clone https://github.com/bitcoin/bitcoin +$ cd bitcoin/ +$ git clone https://github.com/google/afl +$ make -C afl/ +$ make -C afl/llvm_mode/ +$ ./autogen.sh +$ CC=$(pwd)/afl/afl-clang-fast CXX=$(pwd)/afl/afl-clang-fast++ ./configure --enable-fuzz +$ make +# For macOS you may need to ignore x86 compilation checks when running "make". If so, +# try compiling using: AFL_NO_X86=1 make +$ mkdir -p inputs/ outputs/ +$ echo A > inputs/thin-air-input +$ afl/afl-fuzz -i inputs/ -o outputs/ -- src/test/fuzz/bech32 +# You may have to change a few kernel parameters to test optimally - afl-fuzz +# will print an error and suggestion if so. ``` + +Read the [`afl-fuzz` documentation](https://github.com/google/afl) for more information. diff --git a/doc/release-notes.md b/doc/release-notes.md index 22d5767b7b..cd6a4d6b59 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -1,211 +1,5 @@ -*After branching off for a major version release of Bitcoin Core, use this -template to create the initial release notes draft.* +Please edit the release notes here: -*The release notes draft is a temporary file that can be added to by anyone. See -[/doc/developer-notes.md#release-notes](/doc/developer-notes.md#release-notes) -for the process.* - -*Create the draft, named* "*version* Release Notes Draft" -*(e.g. "0.20.0 Release Notes Draft"), as a collaborative wiki in:* - -https://github.com/bitcoin-core/bitcoin-devwiki/wiki/ +https://github.com/bitcoin-core/bitcoin-devwiki/wiki/0.20.0-Release-Notes-Draft *Before the final release, move the notes back to this git repository.* - -*version* Release Notes Draft -=============================== - -Bitcoin Core version *version* is now available from: - - <https://bitcoincore.org/bin/bitcoin-core-*version*/> - -This release includes new features, various bug fixes and performance -improvements, as well as updated translations. - -Please report bugs using the issue tracker at GitHub: - - <https://github.com/bitcoin/bitcoin/issues> - -To receive security and update notifications, please subscribe to: - - <https://bitcoincore.org/en/list/announcements/join/> - -How to Upgrade -============== - -If you are running an older version, shut it down. Wait until it has completely -shut down (which might take a few minutes for older versions), then run the -installer (on Windows) or just copy over `/Applications/Bitcoin-Qt` (on Mac) -or `bitcoind`/`bitcoin-qt` (on Linux). - -Upgrading directly from a version of Bitcoin Core that has reached its EOL is -possible, but it might take some time if the datadir needs to be migrated. Old -wallet versions of Bitcoin Core are generally supported. - -Compatibility -============== - -Bitcoin Core is supported and extensively tested on operating systems using -the Linux kernel, macOS 10.12+, and Windows 7 and newer. It is not recommended -to use Bitcoin Core on unsupported systems. - -Bitcoin Core should also work on most other Unix-like systems but is not -as frequently tested on them. - -From Bitcoin Core 0.20.0 onwards, macOS versions earlier than 10.12 are no -longer supported. Additionally, Bitcoin Core does not yet change appearance -when macOS "dark mode" is activated. - -In addition to previously supported CPU platforms, this release's pre-compiled -distribution provides binaries for the RISC-V platform. - -Notable changes -=============== - -P2P and network changes ------------------------ - -#### Removal of reject network messages from Bitcoin Core (BIP61) - -The command line option to enable BIP61 (`-enablebip61`) has been removed. - -This feature has been disabled by default since Bitcoin Core version 0.18.0. -Nodes on the network can not generally be trusted to send valid ("reject") -messages, so this should only ever be used when connected to a trusted node. -Please use the recommended alternatives if you rely on this deprecated feature: - -* Testing or debugging of implementations of the Bitcoin P2P network protocol - should be done by inspecting the log messages that are produced by a recent - version of Bitcoin Core. Bitcoin Core logs debug messages - (`-debug=<category>`) to a stream (`-printtoconsole`) or to a file - (`-debuglogfile=<debug.log>`). - -* Testing the validity of a block can be achieved by specific RPCs: - - `submitblock` - - `getblocktemplate` with `'mode'` set to `'proposal'` for blocks with - potentially invalid POW - -* Testing the validity of a transaction can be achieved by specific RPCs: - - `sendrawtransaction` - - `testmempoolaccept` - -* Wallets should not use the absence of "reject" messages to indicate a - transaction has propagated the network, nor should wallets use "reject" - messages to set transaction fees. Wallets should rather use fee estimation - to determine transaction fees and set replace-by-fee if desired. Thus, they - could wait until the transaction has confirmed (taking into account the fee - target they set (compare the RPC `estimatesmartfee`)) or listen for the - transaction announcement by other network peers to check for propagation. - -The removal of BIP61 REJECT message support also has the following minor RPC -and logging implications: - -* `testmempoolaccept` and `sendrawtransaction` no longer return the P2P REJECT - code when a transaction is not accepted to the mempool. They still return the - verbal reject reason. - -* Log messages that previously reported the REJECT code when a transaction was - not accepted to the mempool now no longer report the REJECT code. The reason - for rejection is still reported. - -Updated RPCs ------------- - -- `testmempoolaccept` and `sendrawtransaction` no longer return the P2P REJECT - code when a transaction is not accepted to the mempool. See the Section - _Removal of reject network messages from Bitcoin Core (BIP61)_ for details on - the removal of BIP61 REJECT message support. - -- A new descriptor type `sortedmulti(...)` has been added to support multisig scripts where the public keys are sorted lexicographically in the resulting script. - -- `walletprocesspsbt` and `walletcreatefundedpsbt` now include BIP 32 derivation paths by default for public keys if we know them. This can be disabled by setting `bip32derivs` to `false`. - -Build System ------------- - -- OpenSSL is no longer used by Bitcoin Core. The last usage of the library -was removed in #17265. - -- glibc 2.17 or greater is now required to run the release binaries. This -retains compatibility with RHEL 7, CentOS 7, Debian 8 and Ubuntu 14.04 LTS. -Further details can be found in #17538. - -New RPCs --------- - -New settings ------------- - -- RPC Whitelist system. It can give certain RPC users permissions to only some RPC calls. -It can be set with two command line arguments (`rpcwhitelist` and `rpcwhitelistdefault`). (#12763) - -- A new `-asmap` configuration option has been added to enable IP-to-ASN mapping - for bucketing of the network peers to diversify the network connections. The - legacy /16 prefix mapping remains the default. See [issue - #16599](https://github.com/bitcoin/bitcoin/issues/16599), [PR - #16702](https://github.com/bitcoin/bitcoin/pull/16702), and the `bitcoind - help` for more information. This option is experimental and subject to changes - or removal in future releases. - -Updated settings ----------------- - -Importing blocks upon startup via the `bootstrap.dat` file no longer occurs by default. The file must now be specified with `-loadblock=<file>`. - -- The `-debug=db` logging category has been renamed to `-debug=walletdb`, to distinguish it from `coindb`. - `-debug=db` has been deprecated and will be removed in the next major release. - -GUI changes ------------ - -- The "Start Bitcoin Core on system login" option has been removed on macOS. - -Wallet ------- - -- The wallet now by default uses bech32 addresses when using RPC, and creates native segwit change outputs. -- The way that output trust was computed has been fixed in #16766, which impacts confirmed/unconfirmed balance status and coin selection. - -- The RPC gettransaction, listtransactions and listsinceblock responses now also -includes the height of the block that contains the wallet transaction, if any. - -- RPC `getaddressinfo` changes: - - - the `label` field has been deprecated in favor of the `labels` field and - will be removed in 0.21. It can be re-enabled in the interim by launching - with `-deprecatedrpc=label`. - - - the `labels` behavior of returning an array of JSON objects containing name - and purpose key/value pairs has been deprecated in favor of an array of - label names and will be removed in 0.21. The previous behavior can be - re-enabled in the interim by launching with `-deprecatedrpc=labelspurpose`. - -Low-level changes -================= - -Command line ------------- - -Command line options prefixed with main/test/regtest network names like -`-main.port=8333` `-test.server=1` previously were allowed but ignored. Now -they trigger "Invalid parameter" errors on startup. - -Tests ------ - -- It is now an error to use an unqualified `walletdir=path` setting in the config file if running on testnet or regtest - networks. The setting now needs to be qualified as `chain.walletdir=path` or placed in the appropriate `[chain]` - section. (#17447) - -- `-fallbackfee` was 0 (disabled) by default for the main chain, but 0.0002 by default for the test chains. Now it is 0 - by default for all chains. Testnet and regtest users will have to add `fallbackfee=0.0002` to their configuration if - they weren't setting it and they want it to keep working like before. (#16524) - -Credits -======= - -Thanks to everyone who directly contributed to this release: - - -As well as to everyone that helped with translations on -[Transifex](https://www.transifex.com/bitcoin/bitcoin/). |