Commit d37df03f authored by freetrader's avatar freetrader
Browse files

Merge branch 'master' into 'master'

Re-brand various build and other docs

See merge request !32
parents 4ce13ab9 e391ebf4
Pipeline #121210357 passed with stages
in 20 minutes and 27 seconds
Bitcoin ABC
Bitcoin Cash Node
=====================
Setup
---------------------
Bitcoin ABC is a fork of Bitcoin Core, which is the original Bitcoin client and builds the backbone of the network. It downloads and, by default, stores the entire history of Bitcoin transactions, which requires a few hundred gigabytes of disk space. Depending on the speed of your computer and network connection, the synchronization process can take anywhere from a few hours to a day or more.
Bitcoin Cash Node is a fork of Bitcoin ABC, which is an original Bitcoin Cash client and builds the backbone of the network. It downloads and, by default, stores the entire history of Bitcoin transactions, which requires a few hundred gigabytes of disk space. Depending on the speed of your computer and network connection, the synchronization process can take anywhere from a few hours to a day or more.
To download Bitcoin ABC, visit [bitcoinabc.org](https://download.bitcoinabc.org/).
To download Bitcoin Cash Node, (visit [bitcoincashnode.org](https://bitcoincashnode.org/)).
Verify
---------------------
......@@ -44,7 +44,7 @@ the presence of those warnings should be heeded with extreme caution.
Running
---------------------
The following are some helpful notes on how to run Bitcoin ABC on your native platform.
The following are some helpful notes on how to run Bitcoin Cash Node on your native platform.
### Unix
......@@ -59,17 +59,17 @@ Unpack the files into a directory, and then run bitcoin-qt.exe.
### macOS
Drag bitcoin-abc to your applications folder, and then run bitcoin-abc.
Drag bitcoin-cash-node to your applications folder, and then run bitcoin-cash-node.
### Need Help?
* See the documentation at the [Bitcoin Wiki](https://en.bitcoin.it/wiki/Main_Page)
for help and more information.
* Ask for help on the [Bitcoin ABC Subreddit](https://www.reddit.com/r/BitcoinABC/).
* Ask for help on the [Bitcoin Cash Node Subreddit](https://www.reddit.com/r/bitcoincashnode/).
Building
---------------------
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.
The following are developer notes on how to build Bitcoin Cash Node 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)
......@@ -79,7 +79,7 @@ The following are developer notes on how to build Bitcoin ABC on your native pla
Development
---------------------
The Bitcoin ABC repo's [root README](/README.md) contains relevant information on the development process and automated testing.
The Bitcoin Cash Node repo's [root README](/README.md) contains relevant information on the development process and automated testing.
- [Developer Notes](developer-notes.md)
- [Release Notes](release-notes.md)
......
Bitcoin ABC
Bitcoin Cash Node
=====================
Intro
-----
Bitcoin is a free open source peer-to-peer electronic cash system that is
Bitcoin Cash is a free open source peer-to-peer electronic cash system that is
completely decentralized, without the need for a central server or trusted
parties. Users hold the crypto keys to their own money and transact directly
with each other, with the help of a P2P network to check for double-spending.
......@@ -13,7 +13,7 @@ Setup
-----
Unpack the files into a directory and run bitcoin-qt.exe.
Bitcoin ABC is based on Bitcoin Core, which is the original Bitcoin client and
Bitcoin Cash Node is based on Bitcoin ABC, which is an original Bitcoin Cash client and
builds the backbone of the network. It downloads and stores the entire history
of Bitcoin transactions; depending on the speed of your computer and network
connection, the synchronization process can take anywhere from a few hours to
......
......@@ -46,9 +46,9 @@ pkg install db5
```
Download the source code:
refer to [CONTRIBUTING](../CONTRIBUTING.md) for instructions on how to clone the Bitcoin ABC repository
refer to [CONTRIBUTING](../CONTRIBUTING.md) for instructions on how to clone the Bitcoin Cash Node repository
## Building Bitcoin ABC
## Building Bitcoin Cash Node
With wallet:
......
......@@ -29,19 +29,19 @@ If you want to build the disk image with `ninja osx-dmg` (.dmg / optional), you
brew install librsvg
Build Bitcoin ABC
-----------------
Build Bitcoin Cash Node
------------------------
Before you start building, please make sure that your compiler supports C++14.
1. Clone the Bitcoin ABC source code and cd into `bitcoin-abc`
1. Clone the Bitcoin Cash Node source code and cd into `bitcoin-cash-node`
git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git
cd bitcoin-abc
git clone https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node.git
cd bitcoin-cash-node
2. Build Bitcoin ABC:
2. Build Bitcoin Cash Node:
Configure and build the headless Bitcoin ABC binaries as well as the GUI.
Configure and build the headless Bitcoin Cash Node binaries as well as the GUI.
You can disable the GUI build by passing `-DBUILD_BITCOIN_QT=OFF` to cmake.
......@@ -62,7 +62,7 @@ Before you start building, please make sure that your compiler supports C++14.
Disable-wallet mode
--------------------
When the intention is to run only a P2P node without a wallet, Bitcoin ABC may be compiled in
When the intention is to run only a P2P node without a wallet, Bitcoin Cash Node may be compiled in
disable-wallet mode with:
cmake -GNinja .. -DBUILD_BITCOIN_WALLET=OFF
......@@ -72,7 +72,7 @@ Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC
Running
-------
Bitcoin ABC is now available at `./src/bitcoind`
Bitcoin Cash Node is now available at `./src/bitcoind`
Before running, it's recommended that you create an RPC configuration file:
......
UNIX BUILD NOTES
====================
Some notes on how to build Bitcoin ABC in Unix.
Some notes on how to build Bitcoin Cash Node in Unix.
(For FreeBSD specific instructions, see `build-freebsd.md` in this directory.)
......@@ -50,7 +50,7 @@ Memory Requirements
--------------------
C++ compilers are memory-hungry. It is recommended to have at least 1.5 GB of
memory available when compiling Bitcoin ABC. On systems with less, gcc can be
memory available when compiling Bitcoin Cash Node. On systems with less, gcc can be
tuned to conserve memory with additional CXXFLAGS:
cmake -GNinja .. -DCXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768"
......@@ -95,7 +95,7 @@ BerkeleyDB 5.3 or later is required for the wallet. This can be installed with:
sudo apt-get install libdb-dev libdb++-dev
See the section "Disable-wallet mode" to build Bitcoin ABC without wallet.
See the section "Disable-wallet mode" to build Bitcoin Cash Node without wallet.
Minipupnc dependencies (can be disabled by passing `-DENABLE_UPNP=OFF` on the cmake command line):
......@@ -164,7 +164,7 @@ For documentation on building Boost look at their official documentation: http:/
Security
--------
To help make your Bitcoin ABC installation more secure by making certain attacks impossible to
To help make your Bitcoin Cash Node 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 by passing `-DENABLE_HARDENING=OFF`.
......@@ -188,7 +188,7 @@ 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 ABC should be built with a non-executable stack,
vulnerable buffers are found. By default, Bitcoin Cash Node 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.
......@@ -206,7 +206,7 @@ Hardening enables the following features:
Disable-wallet mode
--------------------
When the intention is to run only a P2P node without a wallet, Bitcoin ABC may be compiled in
When the intention is to run only a P2P node without a wallet, Bitcoin Cash Node may be compiled in
disable-wallet mode by passing `-DBUILD_BITCOIN_WALLET=OFF` on the cmake command line.
Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call.
......@@ -221,8 +221,8 @@ Setup and Build Example: Arch Linux
This example lists the steps necessary to setup and build a command line only, non-wallet distribution of the latest changes on Arch Linux:
pacman -S boost cmake git libevent ninja python
git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git
cd bitcoin-abc/
git clone https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node.git
cd bitcoin-cash-node/
mkdir build
cd build
cmake -GNinja .. -DBUILD_BITCOIN_WALLET=OFF -DBUILD_BITCOIN_QT=OFF -DENABLE_UPNP=OFF -DBUILD_BITCOIN_ZMQ=OFF
......
WINDOWS BUILD NOTES
====================
Below are some notes on how to build Bitcoin ABC for Windows.
Below are some notes on how to build Bitcoin Cash Node for Windows.
The options known to work for building Bitcoin ABC on Windows are:
The options known to work for building Bitcoin Cash Node on Windows are:
* On Linux, using the [Mingw-w64](https://mingw-w64.org/doku.php) cross compiler tool chain. Debian Buster is recommended
and is the platform used to build the Bitcoin ABC Windows release binaries.
and is the platform used to build the Bitcoin Cash Node 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.
......@@ -64,7 +64,7 @@ First, install the general dependencies:
sudo apt upgrade
sudo apt install autoconf automake build-essential bsdmainutils curl git libboost-all-dev libevent-dec libssl-dev libtool ninja-build pkg-config python3
The cmake version packaged with Ubuntu Bionic is too old for building Building Bitcoin ABC.
The cmake version packaged with Ubuntu Bionic is too old for building Building Bitcoin Cash Node.
To install the latest version:
sudo apt-get install apt-transport-https ca-certificates gnupg software-properties-common wget
......@@ -104,13 +104,13 @@ Ubuntu Artful 17.10 <sup>[2](#footnote2)</sup> and later, including Ubuntu Bioni
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/.
Note that for WSL the Bitcoin Cash Node source path MUST be somewhere in the default mount file system, for
example /usr/src/bitcoin-cash-node, AND not under /mnt/d/.
This means you cannot use a directory that is located directly on the host Windows file system to perform the build.
Acquire the source in the usual way:
git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git
git clone https://gitlab.com/bitcoin-cash-node/bitcoin-cahs-node.git
Once the source code is ready the build steps are below:
......@@ -134,13 +134,13 @@ For Ubuntu Xenial 16.04 and later, including Ubuntu Bionic on the Windows Subsys
sudo update-alternatives --config i686-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix.
sudo update-alternatives --config i686-w64-mingw32-gcc # Set the default mingw32 gcc compiler option to posix.
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/.
Note that for WSL the Bitcoin Cash Node source path MUST be somewhere in the default mount file system, for
example /usr/src/bitcoin-cash-node, AND not under /mnt/d/.
This means you cannot use a directory that located directly on the host Windows file system to perform the build.
Acquire the source in the usual way:
git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git
git clone https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node.git
Then build using:
......@@ -163,9 +163,9 @@ Installation
After building using the Windows subsystem it can be useful to copy the compiled
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-abc`, for example:
way. This will install to `c:\workspace\bitcoin-cash-node`, for example:
cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/Win32.cmake -DBUILD_BITCOIN_SEEDER=OFF -DCMAKE_INSTALL_PREFIX=/mnt/c/workspace/bitcoin-abc
cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/Win32.cmake -DBUILD_BITCOIN_SEEDER=OFF -DCMAKE_INSTALL_PREFIX=/mnt/c/workspace/bitcoin-cash-node
ninja install
Footnotes
......@@ -182,5 +182,5 @@ something break.
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 ABC code using the win32 version of the Mingw-w64 cross compilers (at least not without
modifying headers in the Bitcoin ABC source code).
It's not possible to build the Bitcoin Cash Node code using the win32 version of the Mingw-w64 cross compilers (at least not without
modifying headers in the Bitcoin Cash Node source code).
# Support for Output Descriptors in Bitcoin ABC
# Support for Output Descriptors in Bitcoin Cash Node
Since Bitcoin ABC v0.20.7, there is support for Output Descriptors in the
`scantxoutset` RPC call. This is a simple language which can be used to
......
......@@ -260,7 +260,7 @@ that run in `-regtest` mode.
### DEBUG_LOCKORDER
Bitcoin ABC is a multi-threaded application, and deadlocks or other
Bitcoin Cash Node is a multi-threaded application, and deadlocks or other
multi-threading bugs can be very difficult to track down. The `--enable-debug`
configure option adds `-DDEBUG_LOCKORDER` to the compiler flags. This inserts
run-time checks to keep track of which locks are held, and adds warnings to the
......@@ -299,7 +299,7 @@ make cov
### Sanitizers
Bitcoin ABC can be compiled with various "sanitizers" enabled, which add
Bitcoin Cash Node 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
......
Bitcoin ABC UAHF-relevant DNS seed information
==============================================
Bitcoin Cash Node UAHF-relevant DNS seed information
====================================================
Bitcoin ABC uses special seeds under the control of the
Bitcoin Cash Node uses special seeds under the control of the
UAHF supporting operators, to increase the chance of a smooth
separation of the UAHF network from the non-UAHF-supporting
parts of the network.
The seeds used by ABC should distribute peers fairly but in a
manner which increases the likelihood that ABC nodes are able
The seeds used by Cash Node should distribute peers fairly but in a
manner which increases the likelihood that Bitcoin Cash Nodes are able
to connect to UAHF compatible peers.
This may mean that in the beginning, they might serve only
......
Fuzz-testing Bitcoin ABC
==========================
Fuzz-testing Bitcoin Cash Node
==============================
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
......@@ -20,7 +20,7 @@ export AFLPATH=$PWD
### Instrumentation
To build Bitcoin ABC using AFL instrumentation (this assumes that the
To build Bitcoin Cash Node using AFL instrumentation (this assumes that the
`AFLPATH` was set as above):
```
mkdir -p buildFuzzer
......
Gitian building
===============
*Setup instructions for a Gitian build of Bitcoin ABC using a VM or physical system.*
*Setup instructions for a Gitian build of Bitcoin Cash Node using a VM or physical system.*
Gitian is the deterministic build process that is used to build the Bitcoin
ABC executables. It provides a way to be reasonably sure that the
Cash Node executables. It provides a way to be reasonably sure that the
executables are really built from the source on GitHub. It also makes sure that
the same, tested dependencies are used and statically built into the executable.
Multiple developers build the source code by following a specific descriptor
("recipe"), cryptographically sign the result, and upload the resulting signature.
These results are compared and only if they match, the build is accepted and
uploaded to bitcoinabc.org.
uploaded to bitcoincashnode.org.
More independent Gitian builders are needed, which is why this guide exists.
It is preferred you follow these steps yourself instead of using someone else's
......@@ -57,7 +57,7 @@ You can check the version with `lxc-execute --version`.
Non-Debian / Ubuntu, Manual and Offline Building
------------------------------------------------
The instructions below use the automated script [gitian-build.py](https://github.com/Bitcoin-ABC/bitcoin-abc/blob/master/contrib/gitian-build.py) which only works in Debian/Ubuntu. For manual steps and instructions for fully offline signing, see [this guide](./gitian-building/gitian-building-manual.md).
The instructions below use the automated script [gitian-build.py](https://github.com/bitcoin-cash-node/bitcoin-cash-node/blob/master/contrib/gitian-build.py) which only works in Debian/Ubuntu. For manual steps and instructions for fully offline signing, see [this guide](./gitian-building/gitian-building-manual.md).
MacOS code signing
------------------
......@@ -80,16 +80,16 @@ Initial Gitian Setup
The `gitian-build.py` script will checkout different release tags, so it's best to copy it:
```bash
cp bitcoin-abc/contrib/gitian-build.py .
cp bitcoin-cash-node/contrib/gitian-build.py .
```
You only need to do this once:
```bash
./gitian-build.py --setup satoshi 0.18.5
./gitian-build.py --setup satoshi 0.21.0
```
Where `satoshi` is your Github name and `0.18.5` is the most recent tag (without `v`).
Where `satoshi` is your Gitlab name and `0.21.0` is the most recent tag (without `v`).
Build binaries
--------------
......@@ -98,7 +98,7 @@ Windows and macOS have code signed binaries, but those won't be available until
To build the most recent tag:
```bash
./gitian-build.py --detach-sign --no-commit -b satoshi 0.18.5
./gitian-build.py --detach-sign --no-commit -b satoshi 0.21.0
```
To speed up the build, use `-j 5 -m 5000` as the first arguments, where `5` is the number of CPU's you allocated to the VM plus one, and 5000 is a little bit less than then the MB's of RAM you allocated.
......@@ -109,7 +109,7 @@ You need to copy these uncommited changes to your host machine, where you can si
```bash
export NAME=satoshi
gpg --output $VERSION-linux/$NAME/bitcoin-abc-linux-0.18.5-build.assert.sig --detach-sign 0.18.5-linux/$NAME/bitcoin-abc-linux-0.18.5-build.assert
gpg --output $VERSION-osx-unsigned/$NAME/bitcoin-abc-osx-0.18.5-build.assert.sig --detach-sign 0.18.5-osx-unsigned/$NAME/bitcoin-abc-osx-0.18.5-build.assert
gpg --output $VERSION-win-unsigned/$NAME/bitcoin-abc-win-0.18.5-build.assert.sig --detach-sign 0.18.5-win-unsigned/$NAME/bitcoin-abc-win-0.18.5-build.assert
gpg --output $VERSION-linux/$NAME/bitcoin-cash-node-linux-0.21.0-build.assert.sig --detach-sign 0.21.0-linux/$NAME/bitcoin-cash-node-linux-0.21.0-build.assert
gpg --output $VERSION-osx-unsigned/$NAME/bitcoin-cash-node-osx-0.21.0-build.assert.sig --detach-sign 0.21.0-osx-unsigned/$NAME/bitcoin-cash-node-osx-0.21.0-build.assert
gpg --output $VERSION-win-unsigned/$NAME/bitcoin-cash-node-win-0.21.0-build.assert.sig --detach-sign 0.21.0-win-unsigned/$NAME/bitcoin-cash-node-win-0.21.0-build.assert
```
......@@ -3,7 +3,7 @@ Reduce Traffic
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 Cash Node 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.
......
# TOR SUPPORT IN BITCOIN
It is possible to run Bitcoin ABC as a Tor hidden service, and connect to such services.
It is possible to run Bitcoin Cash Node 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 ABC behind a Tor proxy
## 1. Run Bitcoin Cash Node behind a Tor proxy
The first step is running Bitcoin ABC behind a Tor proxy. This will already anonymize all
The first step is running Bitcoin Cash Node 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
......@@ -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 ABC hidden server
## 2. Run a Bitcoin Cash Node 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
......@@ -96,7 +96,7 @@ This means that if Tor is running (and proper authentication has been configured
Bitcoin Core automatically creates a hidden service to listen on. This will positively
affect the number of available .onion nodes.
This new feature is enabled by default if Bitcoin ABC is listening (`-listen`), and
This new feature is enabled by default if Bitcoin Cash Node is listening (`-listen`), and
requires a Tor connection to work. It can be explicitly disabled with `-listenonion=0`
and, if not disabled, configured using the `-torcontrol` and `-torpassword` settings.
To show verbose debugging information, pass `-debug=tor`.
......@@ -114,7 +114,7 @@ Tor configuration.
## 4. Privacy recommendations
- Do not add anything but Bitcoin ABC ports to the hidden service created in section 2.
- Do not add anything but Bitcoin Cash Node 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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment