diff --git a/doc/README.md b/doc/README.md --- a/doc/README.md +++ b/doc/README.md @@ -9,7 +9,7 @@ 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 ABC on your native platform. ### Unix @@ -34,7 +34,7 @@ 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 ABC 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 --- a/doc/benchmarking.md +++ b/doc/benchmarking.md @@ -2,9 +2,9 @@ ============ Bitcoin ABC has an internal benchmarking framework, with benchmarks -for cryptographic algorithms such as SHA1, SHA256, SHA512, RIPEMD160, -the rolling bloom filter, address encoding and decoding, CCoinsCaching, -memory pool eviction, and wallet coin selection. +for cryptographic algorithms (e.g. SHA1, SHA256, SHA512, RIPEMD160), +as well as the rolling bloom filter, address encoding and decoding, +CCoinsCaching, memory pool eviction, and wallet coin selection. After compiling bitcoin-abc, the benchmarks can be run with: `src/bench/bench_bitcoin` diff --git a/doc/bips.md b/doc/bips.md --- a/doc/bips.md +++ b/doc/bips.md @@ -13,7 +13,7 @@ * [`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 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -41,9 +41,9 @@ git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git cd bitcoin-abc -2. Build bitcoin-abc: +2. Build Bitcoin ABC: - Configure and build the headless bitcoin binaries as well as the GUI (if Qt is found). + Configure and build the headless Bitcoin ABC binaries as well as the GUI (if Qt is found). You can disable the GUI build by passing `--without-gui` to configure. @@ -68,7 +68,7 @@ Bitcoin ABC 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 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -6,7 +6,7 @@ Note --------------------- -Always use absolute paths to configure and compile bitcoin and the dependencies, +Always use absolute paths to configure and compile Bitcoin ABC and the dependencies, for example, when specifying the path of the dependency: ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX @@ -102,7 +102,7 @@ Dependencies for the GUI: Ubuntu & Debian ----------------------------------------- -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`. @@ -158,7 +158,7 @@ Security -------- -To help make your bitcoin installation more secure by making certain attacks impossible to +To help make your Bitcoin ABC 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: @@ -174,7 +174,7 @@ 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 @@ -190,8 +190,8 @@ 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 ABC 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. @@ -199,7 +199,7 @@ 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- @@ -207,7 +207,7 @@ 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 ABC may be compiled in disable-wallet mode with: ./configure --disable-wallet diff --git a/doc/build-windows.md b/doc/build-windows.md --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -10,7 +10,7 @@ * 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). @@ -48,7 +48,7 @@ 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 ------------------------------------------------------------ @@ -99,7 +99,7 @@ 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 ABC source path MUST be somewhere in the default mount file system, for example /usr/src/bitcoin-abc, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. @@ -175,5 +175,5 @@ 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 ABC code using the win32 version of the Mingw-w64 cross compilers (at least not without +modifying headers in the Bitcoin ABC source code). diff --git a/doc/developer-notes.md b/doc/developer-notes.md --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -217,7 +217,7 @@ **Sanitizers** -Bitcoin can be compiled with various "sanitizers" enabled, which add +Bitcoin ABC 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 --- a/doc/reduce-traffic.md +++ b/doc/reduce-traffic.md @@ -3,7 +3,7 @@ Some node operators need to deal with bandwidth caps imposed by their ISPs. -By default, bitcoin-abc allows up to 125 connections to different peers, 8 of +By default, Bitcoin ABC 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 --- 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 ABC 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 ABC 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 ABC 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 @@ ./bitcoind -proxy=127.0.0.1:9050 -## 2. Run a bitcoin hidden server +## 2. Run a Bitcoin ABC 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 @@ -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 @@ ./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 @@ 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 @@ 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 ABC 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