diff --git a/doc/README.md b/doc/README.md index 45762b237..5ffff825b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -9,7 +9,7 @@ To download Bitcoin Core, visit [bitcoincore.org](https://bitcoincore.org/en/rel Running --------------------- -The following are some helpful notes on how to run Bitcoin on your native platform. +The following are some helpful notes on how to run Bitcoin Core on your native platform. ### Unix @@ -24,7 +24,7 @@ Unpack the files into a directory, and then run bitcoin-qt.exe. ### macOS -Drag Bitcoin-Core to your applications folder, and then run Bitcoin-Core. +Drag Bitcoin Core to your applications folder, and then run Bitcoin Core. ### Need Help? @@ -35,7 +35,7 @@ for help and more information. Building --------------------- -The following are developer notes on how to build Bitcoin on your native platform. They are not complete guides, but include notes on the necessary libraries, compile flags, etc. +The following are developer notes on how to build Bitcoin Core on your native platform. They are not complete guides, but include notes on the necessary libraries, compile flags, etc. - [Dependencies](dependencies.md) - [macOS Build Notes](build-osx.md) diff --git a/doc/benchmarking.md b/doc/benchmarking.md index 99d36cb22..48f81cf6c 100644 --- a/doc/benchmarking.md +++ b/doc/benchmarking.md @@ -2,7 +2,7 @@ Benchmarking ============ Bitcoin Core has an internal benchmarking framework, with benchmarks -for cryptographic algorithms such as SHA1, SHA256, SHA512 and RIPEMD160. As well as the rolling bloom filter. +for cryptographic algorithms (e.g. SHA1, SHA256, SHA512, RIPEMD160), as well as the rolling bloom filter. Running --------------------- diff --git a/doc/bips.md b/doc/bips.md index eb29b036c..76edc94c2 100644 --- a/doc/bips.md +++ b/doc/bips.md @@ -13,7 +13,7 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.17.0**): * [`BIP 32`](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki): Hierarchical Deterministic Wallets has been implemented since **v0.13.0** ([PR #8035](https://github.com/bitcoin/bitcoin/pull/8035)). * [`BIP 34`](https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki): The rule that requires blocks to contain their height (number) in the coinbase input, and the introduction of version 2 blocks has been implemented since **v0.7.0**. The rule took effect for version 2 blocks as of *block 224413* (March 5th 2013), and version 1 blocks are no longer allowed since *block 227931* (March 25th 2013) ([PR #1526](https://github.com/bitcoin/bitcoin/pull/1526)). * [`BIP 35`](https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki): The 'mempool' protocol message (and the protocol version bump to 60002) has been implemented since **v0.7.0** ([PR #1641](https://github.com/bitcoin/bitcoin/pull/1641)). -* [`BIP 37`](https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki): The bloom filtering for transaction relaying, partial merkle trees for blocks, and the protocol version bump to 70001 (enabling low-bandwidth SPV clients) has been implemented since **v0.8.0** ([PR #1795](https://github.com/bitcoin/bitcoin/pull/1795)). +* [`BIP 37`](https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki): The bloom filtering for transaction relaying, partial Merkle trees for blocks, and the protocol version bump to 70001 (enabling low-bandwidth SPV clients) has been implemented since **v0.8.0** ([PR #1795](https://github.com/bitcoin/bitcoin/pull/1795)). * [`BIP 42`](https://github.com/bitcoin/bips/blob/master/bip-0042.mediawiki): The bug that would have caused the subsidy schedule to resume after block 13440000 was fixed in **v0.9.2** ([PR #3842](https://github.com/bitcoin/bitcoin/pull/3842)). * [`BIP 61`](https://github.com/bitcoin/bips/blob/master/bip-0061.mediawiki): The 'reject' protocol message (and the protocol version bump to 70002) was added in **v0.9.0** ([PR #3185](https://github.com/bitcoin/bitcoin/pull/3185)). Starting *v0.17.0*, whether to send reject messages can be configured with the `-enablebip61` option. * [`BIP 65`](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki): The CHECKLOCKTIMEVERIFY softfork was merged in **v0.12.0** ([PR #6351](https://github.com/bitcoin/bitcoin/pull/6351)), and backported to **v0.11.2** and **v0.10.4**. Mempool-only CLTV was added in [PR #6124](https://github.com/bitcoin/bitcoin/pull/6124). diff --git a/doc/build-osx.md b/doc/build-osx.md index 486a505b6..448918e8c 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -41,14 +41,14 @@ from the root of the repository. Build Bitcoin Core ------------------------ -1. Clone the bitcoin source code and cd into `bitcoin` +1. Clone the Bitcoin Core source code and cd into `bitcoin` git clone https://github.com/bitcoin/bitcoin cd bitcoin -2. Build bitcoin-core: +2. Build Bitcoin Core: - Configure and build the headless bitcoin binaries as well as the GUI (if Qt is found). + Configure and build the headless Bitcoin Core binaries as well as the GUI (if Qt is found). You can disable the GUI build by passing `--without-gui` to configure. @@ -69,7 +69,7 @@ Running Bitcoin Core is now available at `./src/bitcoind` -Before running, it's recommended you create an RPC configuration file. +Before running, it's recommended that you create an RPC configuration file. echo -e "rpcuser=bitcoinrpc\nrpcpassword=$(xxd -l 16 -p /dev/urandom)" > "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" diff --git a/doc/build-unix.md b/doc/build-unix.md index d9208fed5..a01ff59fa 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -6,7 +6,7 @@ Some notes on how to build Bitcoin Core in Unix. Note --------------------- -Always use absolute paths to configure and compile bitcoin and the dependencies, +Always use absolute paths to configure and compile Bitcoin Core and the dependencies, for example, when specifying the path of the dependency: ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX @@ -99,7 +99,7 @@ ZMQ dependencies (provides ZMQ API 4.x): #### Dependencies for the GUI -If you want to build Bitcoin-Qt, make sure that the required packages for Qt development +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`. @@ -178,7 +178,7 @@ If you need to build Boost yourself: Security -------- -To help make your bitcoin installation more secure by making certain attacks impossible to +To help make your Bitcoin Core installation more secure by making certain attacks impossible to exploit even if a vulnerability is found, binaries are hardened by default. This can be disabled with: @@ -194,7 +194,7 @@ Hardening enables the following features: Build position independent code to take advantage of Address Space Layout Randomization offered by some kernels. Attackers who can cause execution of code at an arbitrary memory location are thwarted if they don't know where anything useful is located. - The stack and heap are randomly located by default but this allows the code section to be + The stack and heap are randomly located by default, but this allows the code section to be randomly located as well. On an AMD64 processor where a library was not compiled with -fPIC, this will cause an error @@ -210,8 +210,8 @@ Hardening enables the following features: ET_DYN * Non-executable Stack - If the stack is executable then trivial stack based buffer overflow exploits are possible if - vulnerable buffers are found. By default, bitcoin should be built with a non-executable stack + If the stack is executable then trivial stack-based buffer overflow exploits are possible if + vulnerable buffers are found. By default, Bitcoin Core should be built with a non-executable stack, but if one of the libraries it uses asks for an executable stack or someone makes a mistake and uses a compiler extension which requires an executable stack, it will silently build an executable without the non-executable stack protection. @@ -219,7 +219,7 @@ Hardening enables the following features: To verify that the stack is non-executable after compiling use: `scanelf -e ./bitcoin` - the output should contain: + The output should contain: STK/REL/PTL RW- R-- RW- @@ -227,7 +227,7 @@ Hardening enables the following features: Disable-wallet mode -------------------- -When the intention is to run only a P2P node without a wallet, bitcoin may be compiled in +When the intention is to run only a P2P node without a wallet, Bitcoin Core may be compiled in disable-wallet mode with: ./configure --disable-wallet diff --git a/doc/build-windows.md b/doc/build-windows.md index 935e29ce1..12adadacd 100644 --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -10,7 +10,7 @@ and is the platform used to build the Bitcoin Core Windows release binaries. * On Windows using [Windows Subsystem for Linux (WSL)](https://msdn.microsoft.com/commandline/wsl/about) and the Mingw-w64 cross compiler tool chain. -Other options which may work but which have not been extensively tested are (please contribute instructions): +Other options which may work, but which have not been extensively tested are (please contribute instructions): * On Windows using a POSIX compatibility layer application such as [cygwin](http://www.cygwin.com/) or [msys2](http://www.msys2.org/). * On Windows using a native compiler tool chain such as [Visual Studio](https://www.visualstudio.com). @@ -46,7 +46,7 @@ To install WSL on Windows 10 with Fall Creators Update installed (version >= 162 After the bash shell is active, you can follow the instructions below, starting with the "Cross-compilation" section. Compiling the 64-bit version is -recommended but it is possible to compile the 32-bit version. +recommended, but it is possible to compile the 32-bit version. Cross-compilation for Ubuntu and Windows Subsystem for Linux ------------------------------------------------------------ @@ -77,7 +77,7 @@ Ubuntu Bionic 18.04 [1](#footnote1): sudo update-alternatives --config x86_64-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. -Once the tool chain is installed the build steps are common: +Once the toolchain is installed the build steps are common: Note that for WSL the Bitcoin Core source path MUST be somewhere in the default mount file system, for example /usr/src/bitcoin, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. @@ -146,5 +146,5 @@ Footnotes compiler options to allow a choice between either posix or win32 threads. The default option is win32 threads which is the more efficient since it will result in binary code that links directly with the Windows kernel32.lib. Unfortunately, the headers required to support win32 threads conflict with some of the classes in the C++11 standard library in particular std::mutex. -It's not possible to build the bitcoin code using the win32 version of the Mingw-w64 cross compilers (at least not without -modifying headers in the bitcoin source code). +It's not possible to build the Bitcoin Core code using the win32 version of the Mingw-w64 cross compilers (at least not without +modifying headers in the Bitcoin Core source code). diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 2fa91ecb0..70070fa24 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -247,7 +247,7 @@ make cov **Sanitizers** -Bitcoin can be compiled with various "sanitizers" enabled, which add +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 diff --git a/doc/reduce-traffic.md b/doc/reduce-traffic.md index 697099bea..dd1469f56 100644 --- a/doc/reduce-traffic.md +++ b/doc/reduce-traffic.md @@ -3,7 +3,7 @@ Reduce Traffic Some node operators need to deal with bandwidth caps imposed by their ISPs. -By default, bitcoin-core allows up to 125 connections to different peers, 8 of +By default, Bitcoin Core allows up to 125 connections to different peers, 8 of which are outbound. You can therefore, have at most 117 inbound connections. The default settings can result in relatively significant traffic consumption. diff --git a/doc/tor.md b/doc/tor.md index f0f98b7d1..2d0676c89 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -1,20 +1,20 @@ # TOR SUPPORT IN BITCOIN -It is possible to run Bitcoin as a Tor hidden service, and connect to such services. +It is possible to run Bitcoin Core as a Tor hidden service, and connect to such services. The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly configure Tor. -## 1. Run bitcoin behind a Tor proxy +## 1. Run Bitcoin Core behind a Tor proxy -The first step is running Bitcoin behind a Tor proxy. This will already make all -outgoing connections be anonymized, but more is possible. +The first step is running Bitcoin Core behind a Tor proxy. This will already anonymize all +outgoing connections, but more is possible. -proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy server will be used to try to reach .onion addresses as well. - -onion=ip:port Set the proxy server to use for tor hidden services. You do not + -onion=ip:port Set the proxy server to use for Tor hidden services. You do not need to set this if it's the same as -proxy. You can use -noonion to explicitly disable access to hidden service. @@ -32,7 +32,7 @@ In a typical situation, this suffices to run behind a Tor proxy: ./bitcoind -proxy=127.0.0.1:9050 -## 2. Run a bitcoin hidden server +## 2. Run a Bitcoin Core hidden server If you configure your Tor system accordingly, it is possible to make your node also reachable from the Tor network. Add these lines to your /etc/tor/torrc (or equivalent @@ -48,11 +48,11 @@ your bitcoind's P2P listen port (8333 by default). -externalip=X You can tell bitcoin about its publicly reachable address using this option, and this can be a .onion address. Given the above - configuration, you can find your onion address in - /var/lib/tor/bitcoin-service/hostname. Onion addresses are given - preference for your node to advertise itself with, for connections + configuration, you can find your .onion address in + /var/lib/tor/bitcoin-service/hostname. For connections coming from unroutable addresses (such as 127.0.0.1, where the - Tor proxy typically runs). + Tor proxy typically runs), .onion addresses are given + preference for your node to advertise itself with. -listen You'll need to enable listening for incoming connections, as this is off by default behind a proxy. @@ -68,7 +68,7 @@ In a typical situation, where you're only reachable via Tor, this should suffice ./bitcoind -proxy=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -listen -(obviously, replace the Onion address with your own). It should be noted that you still +(obviously, replace the .onion address with your own). It should be noted that you still listen on all devices and another node could establish a clearnet connection, when knowing your address. To mitigate this, additionally bind the address of your Tor proxy: @@ -81,7 +81,7 @@ as well, use `discover` instead: and open port 8333 on your firewall (or use -upnp). -If you only want to use Tor to reach onion addresses, but not use it as a proxy +If you only want to use Tor to reach .onion addresses, but not use it as a proxy for normal IPv4/IPv6 communication, use: ./bitcoind -onion=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover @@ -101,20 +101,20 @@ requires a Tor connection to work. It can be explicitly disabled with `-listenon and, if not disabled, configured using the `-torcontrol` and `-torpassword` settings. To show verbose debugging information, pass `-debug=tor`. -Connecting to Tor's control socket API requires one of two authentication methods to be -configured. For cookie authentication the user running bitcoind must have write access -to the `CookieAuthFile` specified in Tor configuration. In some cases this is -preconfigured and the creation of a hidden service is automatic. If permission problems -are seen with `-debug=tor` they can be resolved by adding both the user running tor and -the user running bitcoind to the same group and setting permissions appropriately. On -Debian-based systems the user running bitcoind can be added to the debian-tor group, -which has the appropriate permissions. An alternative authentication method is the use -of the `-torpassword` flag and a `hash-password` which can be enabled and specified in +Connecting to Tor's control socket API requires one of two authentication methods to be +configured. For cookie authentication the user running bitcoind must have write access +to the `CookieAuthFile` specified in Tor configuration. In some cases, this is +preconfigured and the creation of a hidden service is automatic. If permission problems +are seen with `-debug=tor` they can be resolved by adding both the user running Tor and +the user running bitcoind to the same group and setting permissions appropriately. On +Debian-based systems the user running bitcoind can be added to the debian-tor group, +which has the appropriate permissions. An alternative authentication method is the use +of the `-torpassword` flag and a `hash-password` which can be enabled and specified in Tor configuration. ## 4. Privacy recommendations -- Do not add anything but bitcoin ports to the hidden service created in section 2. +- Do not add anything but Bitcoin Core ports to the hidden service created in section 2. If you run a web service too, create a new hidden service for that. Otherwise it is trivial to link them, which may reduce privacy. Hidden services created automatically (as in section 3) always have only one port