diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 1 | ||||
| -rw-r--r-- | doc/REST-interface.md | 5 | ||||
| -rw-r--r-- | doc/bips.md | 3 | ||||
| -rw-r--r-- | doc/build-android.md | 12 | ||||
| -rw-r--r-- | doc/build-osx.md | 330 | ||||
| -rw-r--r-- | doc/dependencies.md | 9 | ||||
| -rw-r--r-- | doc/release-notes-20861.md | 13 | ||||
| -rw-r--r-- | doc/release-notes.md | 23 |
8 files changed, 310 insertions, 86 deletions
diff --git a/doc/README.md b/doc/README.md index 19d8204d83..f32600d009 100644 --- a/doc/README.md +++ b/doc/README.md @@ -44,6 +44,7 @@ The following are developer notes on how to build Bitcoin Core on your native pl - [FreeBSD Build Notes](build-freebsd.md) - [OpenBSD Build Notes](build-openbsd.md) - [NetBSD Build Notes](build-netbsd.md) +- [Android Build Notes](build-android.md) - [Gitian Building Guide (External Link)](https://github.com/bitcoin-core/docs/blob/master/gitian-building.md) Development diff --git a/doc/REST-interface.md b/doc/REST-interface.md index ea06952af4..8b281acca7 100644 --- a/doc/REST-interface.md +++ b/doc/REST-interface.md @@ -95,11 +95,8 @@ $ curl localhost:18332/rest/getutxos/checkmempool/b2cdfd7b89def827ff8af7cd9bff76 "scriptPubKey" : { "asm" : "OP_DUP OP_HASH160 1c7cebb529b86a04c683dfa87be49de35bcf589e OP_EQUALVERIFY OP_CHECKSIG", "hex" : "76a9141c7cebb529b86a04c683dfa87be49de35bcf589e88ac", - "reqSigs" : 1, "type" : "pubkeyhash", - "addresses" : [ - "mi7as51dvLJsizWnTMurtRmrP8hG2m1XvD" - ] + "address" : "mi7as51dvLJsizWnTMurtRmrP8hG2m1XvD" } } ] diff --git a/doc/bips.md b/doc/bips.md index a5e9a6c020..f72dbead9d 100644 --- a/doc/bips.md +++ b/doc/bips.md @@ -1,4 +1,4 @@ -BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.21.0**): +BIPs that are implemented by Bitcoin Core (up-to-date up to **v22.0**): * [`BIP 9`](https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki): The changes allowing multiple soft-forks to be deployed in parallel have been implemented since **v0.12.1** ([PR #7575](https://github.com/bitcoin/bitcoin/pull/7575)) * [`BIP 11`](https://github.com/bitcoin/bips/blob/master/bip-0011.mediawiki): Multisig outputs are standard since **v0.6.0** ([PR #669](https://github.com/bitcoin/bitcoin/pull/669)). @@ -50,3 +50,4 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.21.0**): * [`BIP 325`](https://github.com/bitcoin/bips/blob/master/bip-0325.mediawiki): Signet test network is supported as of **v0.21.0** ([PR 18267](https://github.com/bitcoin/bitcoin/pull/18267)). * [`BIP 339`](https://github.com/bitcoin/bips/blob/master/bip-0339.mediawiki): Relay of transactions by wtxid is supported as of **v0.21.0** ([PR 18044](https://github.com/bitcoin/bitcoin/pull/18044)). * [`BIP 340`](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki) [`341`](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) [`342`](https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki): Validation rules for Taproot (including Schnorr signatures and Tapscript leaves) are implemented as of **v0.21.0** ([PR 19953](https://github.com/bitcoin/bitcoin/pull/19953)), without mainnet activation. +* [`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)). diff --git a/doc/build-android.md b/doc/build-android.md new file mode 100644 index 0000000000..7a8a9e6a65 --- /dev/null +++ b/doc/build-android.md @@ -0,0 +1,12 @@ +ANDROID BUILD NOTES +====================== + +This guide describes how to build and package the `bitcoin-qt` GUI for Android on Linux and macOS. + +## Preparation + +You will need to get the Android NDK and build dependencies for Android as described in [depends/README.md](../depends/README.md). + +## Building and packaging + +After the depends are built configure with one of the resulting prefixes and run `make && make apk` in `src/qt`.
\ No newline at end of file diff --git a/doc/build-osx.md b/doc/build-osx.md index 52a734c80a..16c6da66d5 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,116 +1,303 @@ -# macOS Build Instructions and Notes +# macOS Build Guide + +**Updated for MacOS [11.2](https://www.apple.com/macos/big-sur/)** + +This guide describes how to build bitcoind, command-line utilities, and GUI on macOS + +**Note:** The following is for Intel Macs only! + +## Dependencies + +The following dependencies are **required**: + +Library | Purpose | Description +-----------------------------------------------------------|------------|---------------------- +[automake](https://formulae.brew.sh/formula/automake) | Build | Generate makefile +[libtool](https://formulae.brew.sh/formula/libtool) | Build | Shared library support +[pkg-config](https://formulae.brew.sh/formula/pkg-config) | Build | Configure compiler and linker flags +[boost](https://formulae.brew.sh/formula/boost) | Utility | Library for threading, data structures, etc +[libevent](https://formulae.brew.sh/formula/libevent) | Networking | OS independent asynchronous networking + +The following dependencies are **optional**: + +Library | Purpose | Description +--------------------------------------------------------------- |------------------|---------------------- +[berkeley-db@4](https://formulae.brew.sh/formula/berkeley-db@4) | Berkeley DB | Wallet storage (only needed when wallet enabled) +[qt@5](https://formulae.brew.sh/formula/qt@5) | GUI | GUI toolkit (only needed when GUI enabled) +[qrencode](https://formulae.brew.sh/formula/qrencode) | QR codes in GUI | Generating QR codes (only needed when GUI enabled) +[zeromq](https://formulae.brew.sh/formula/zeromq) | ZMQ notification | Allows generating ZMQ notifications (requires ZMQ version >= 4.0.0) +[sqlite](https://formulae.brew.sh/formula/sqlite) | SQLite DB | Wallet storage (only needed when wallet enabled) +[miniupnpc](https://formulae.brew.sh/formula/miniupnpc) | UPnP Support | Firewall-jumping support (needed for port mapping support) +[libnatpmp](https://formulae.brew.sh/formula/libnatpmp) | NAT-PMP Support | Firewall-jumping support (needed for port mapping support) +[python3](https://formulae.brew.sh/formula/python@3.9) | Testing | Python Interpreter (only needed when running the test suite) + +The following dependencies are **optional** packages required for deploying: + +Library | Purpose | Description +----------------------------------------------------|------------------|---------------------- +[librsvg](https://formulae.brew.sh/formula/librsvg) | Deploy Dependency| Library to render SVG files +[ds_store](https://pypi.org/project/ds-store/) | Deploy Dependency| Examine and modify .DS_Store files +[mac_alias](https://pypi.org/project/mac-alias/) | Deploy Dependency| Generate/Read binary alias and bookmark records + +See [dependencies.md](dependencies.md) for a complete overview. + +## Preparation The commands in this guide should be executed in a Terminal application. -The built-in one is located in +macOS comes with a built-in Terminal located in: + ``` /Applications/Utilities/Terminal.app ``` -## Preparation -Install the macOS command line tools: +### 1. Xcode Command Line Tools -```shell +The Xcode Command Line Tools are a collection of build tools for macOS. +These tools must be installed in order to build Bitcoin Core from source. + +To install, run the following command from your terminal: + +``` bash xcode-select --install ``` -When the popup appears, click `Install`. +Upon running the command, you should see a popup appear. +Click on `Install` to continue the installation process. -Then install [Homebrew](https://brew.sh). +### 2. Homebrew Package Manager -## Dependencies -```shell -brew install automake libtool boost miniupnpc libnatpmp pkg-config python qt@5 libevent qrencode +Homebrew is a package manager for macOS that allows one to install packages from the command line easily. +While several package managers are available for macOS, this guide will focus on Homebrew as it is the most popular. +Since the examples in this guide which walk through the installation of a package will use Homebrew, it is recommended that you install it to follow along. +Otherwise, you can adapt the commands to your package manager of choice. + +To install the Homebrew package manager, see: https://brew.sh + +Note: If you run into issues while installing Homebrew or pulling packages, refer to [Homebrew's troubleshooting page](https://docs.brew.sh/Troubleshooting). + +### 3. Install Required Dependencies + +The first step is to download the required dependencies. +These dependencies represent the packages required to get a barebones installation up and running. +To install, run the following from your terminal: + +``` bash +brew install automake libtool boost pkg-config libevent ``` -If you run into issues, check [Homebrew's troubleshooting page](https://docs.brew.sh/Troubleshooting). -See [dependencies.md](dependencies.md) for a complete overview. +### 4. Clone Bitcoin repository -If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG: -```shell -brew install librsvg +`git` should already be installed by default on your system. +Now that 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 +git clone https://github.com/bitcoin/bitcoin.git ``` -and [`macdeployqtplus`](../contrib/macdeploy/README.md) dependencies: -```shell -pip3 install ds_store mac_alias +### 5. Install Optional Dependencies + +#### Wallet Dependencies + +It is not necessary to build wallet functionality to run `bitcoind` or `bitcoin-qt`. +To enable legacy wallets, you must install `berkeley-db@4`. +To enable [descriptor wallets](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md), `sqlite` is required. +Skip `berkeley-db@4` if you intend to *exclusively* use descriptor wallets. + +###### Legacy Wallet Support + +`berkeley-db@4` is required to enable support for legacy wallets. +Skip if you don't intend to use legacy wallets. + +``` bash +brew install berkeley-db@4 ``` -The wallet support requires one or both of the dependencies ([*SQLite*](#sqlite) and [*Berkeley DB*](#berkeley-db)) in the sections below. -To build Bitcoin Core without wallet, see [*Disable-wallet mode*](#disable-wallet-mode). +###### Descriptor Wallet Support -#### SQLite +Note: Apple has included a useable `sqlite` package since macOS 10.14. +You may not need to install this package. -Usually, macOS installation already has a suitable SQLite installation. -Also, the Homebrew package could be installed: +`sqlite` is required to enable support for descriptor wallets. +Skip if you don't intend to use descriptor wallets. -```shell +``` bash brew install sqlite ``` +--- -In that case the Homebrew package will prevail. +#### GUI Dependencies -#### Berkeley DB +###### Qt -It is recommended to use Berkeley DB 4.8. If you have to build it yourself, -you can use [this](/contrib/install_db4.sh) script to install it -like so: +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. -```shell -./contrib/install_db4.sh . +``` bash +brew install qt@5 ``` -from the root of the repository. +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). -Also, the Homebrew package could be installed: +###### qrencode -```shell -brew install berkeley-db4 +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. + +``` bash +brew install qrencode ``` +--- + +#### Port Mapping Dependencies + +###### miniupnpc -## Build Bitcoin Core +miniupnpc may be used for UPnP port mapping. +Skip if you do not need this functionality. -1. Clone the Bitcoin Core source code: - ```shell - git clone https://github.com/bitcoin/bitcoin - cd bitcoin - ``` +``` bash +brew install miniupnpc +``` -2. Build Bitcoin Core: +###### libnatpmp - Configure and build the headless Bitcoin Core binaries as well as the GUI (if Qt is found). +libnatpmp may be used for NAT-PMP port mapping. +Skip if you do not need this functionality. - You can disable the GUI build by passing `--without-gui` to configure. - ```shell - ./autogen.sh - ./configure - make - ``` +``` bash +brew install libnatpmp +``` -3. It is recommended to build and run the unit tests: - ```shell - make check - ``` +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. -4. You can also create a `.dmg` that contains the `.app` bundle (optional): - ```shell - make deploy - ``` +--- -## Disable-wallet mode -When the intention is to run only a P2P node without a wallet, Bitcoin Core may be -compiled in disable-wallet mode with: -```shell -./configure --disable-wallet +#### ZMQ Dependencies + +Support for ZMQ notifications requires the following dependency. +Skip if you do not need ZMQ functionality. + +``` bash +brew install zeromq ``` -In this case there is no dependency on [*Berkeley DB*](#berkeley-db) and [*SQLite*](#sqlite). +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) -Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call. +--- -## Running -Bitcoin Core is now available at `./src/bitcoind` +#### 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: + +``` bash +brew install python +``` + +--- + +#### Deploy Dependencies + +You can deploy a `.dmg` containing the Bitcoin Core application using `make deploy`. +This command depends on a couple of python packages, so it is required that you have `python` installed. + +Ensuring that `python` is installed, you can install the deploy dependencies by running the following commands in your terminal: + +``` bash +brew install librsvg +``` + +``` bash +pip3 install ds_store mac_alias +``` + +## Building Bitcoin Core + +### 1. Configuration + +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 `berkeley-db@4` is not installed, then this will throw an error. +If `sqlite` is installed, then descriptor wallet support will also be built. +Additionally, this explicitly disables the GUI. + +``` bash +./autogen.sh +./configure --with-gui=no +``` + +##### 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. + +``` bash +./autogen.sh +./configure --without-bdb --with-gui=yes +``` + +##### No Wallet or GUI + +``` bash +./autogen.sh +./configure --without-wallet --with-gui=no +``` + +##### Further Configuration + +You may want to dig deeper into the configuration options to achieve your desired behavior. +Examine the output of the following command for a full list of configuration options: + +``` bash +./configure -help +``` + +### 2. Compile + +After configuration, you are ready to compile. +Run the following in your terminal to compile Bitcoin Core: + +``` bash +make -jx # use -jX here for parallelism +make check # Run tests if Python 3 is available +``` + +### 3. Deploy (optional) + +You can also create a `.dmg` containing the `.app` bundle by running the following command: + +``` bash +make 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`. + +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. + +By default, blockchain and wallet data files will be stored in: + +``` bash +/Users/${USER}/Library/Application Support/Bitcoin/ +``` Before running, you may create an empty configuration file: + ```shell mkdir -p "/Users/${USER}/Library/Application Support/Bitcoin" @@ -119,22 +306,17 @@ touch "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" ``` -The first time you run bitcoind, it will start downloading the blockchain. This process could -take many hours, or even days on slower than average systems. - You can monitor the download process by looking at the debug.log file: + ```shell 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 ``` - -## Notes -* Tested on OS X 10.14 Mojave through macOS 11 Big Sur on 64-bit Intel -processors only. -* Building with downloaded Qt binaries is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714). diff --git a/doc/dependencies.md b/doc/dependencies.md index 159c6bcc28..22161856ce 100644 --- a/doc/dependencies.md +++ b/doc/dependencies.md @@ -14,19 +14,19 @@ These are the dependencies currently used by Bitcoin Core. You can find instruct | GCC | | [7+](https://gcc.gnu.org/) (C++17 support) | | | | | HarfBuzz-NG | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | | libevent | [2.1.11-stable](https://github.com/libevent/libevent/releases) | [2.0.21](https://github.com/bitcoin/bitcoin/pull/18676) | No | | | -| libnatpmp | [20150609](https://miniupnp.tuxfamily.org/files) | | No | | | +| libnatpmp | git commit [4536032...](https://github.com/miniupnp/libnatpmp/tree/4536032ae32268a45c073a4d5e91bbab4534773a) | | No | | | | libpng | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | | librsvg | | | | | | -| MiniUPnPc | [2.0.20180203](https://miniupnp.tuxfamily.org/files) | | No | | | +| MiniUPnPc | [2.2.2](https://miniupnp.tuxfamily.org/files) | | No | | | | PCRE | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | | Python (tests) | | [3.6](https://www.python.org/downloads) | | | | | qrencode | [3.4.4](https://fukuchi.org/works/qrencode) | | No | | | -| Qt | [5.9.8](https://download.qt.io/official_releases/qt/) | [5.9.5](https://github.com/bitcoin/bitcoin/issues/20104) | No | | | +| Qt | [5.12.10](https://download.qt.io/official_releases/qt/) | [5.9.5](https://github.com/bitcoin/bitcoin/issues/20104) | No | | | | SQLite | [3.32.1](https://sqlite.org/download.html) | [3.7.17](https://github.com/bitcoin/bitcoin/pull/19077) | | | | | XCB | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) (Linux only) | | xkbcommon | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) (Linux only) | | ZeroMQ | [4.3.1](https://github.com/zeromq/libzmq/releases) | 4.0.0 | No | | | -| zlib | [1.2.11](https://zlib.net/) | | | | No | +| zlib | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk) | Controlling dependencies ------------------------ @@ -43,3 +43,4 @@ Some dependencies are not needed in all configurations. The following are some f #### Other * librsvg is only needed if you need to run `make deploy` on (cross-compilation to) macOS. +* Not-Qt-bundled zlib is required to build the [DMG tool](../contrib/macdeploy/README.md#deterministic-macos-dmg-notes) from the libdmg-hfsplus project. diff --git a/doc/release-notes-20861.md b/doc/release-notes-20861.md new file mode 100644 index 0000000000..5c68e4ab0c --- /dev/null +++ b/doc/release-notes-20861.md @@ -0,0 +1,13 @@ +Updated RPCs +------------ + +- Due to [BIP 350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) + being implemented, behavior for all RPCs that accept addresses is changed when + a native witness version 1 (or higher) is passed. These now require a Bech32m + encoding instead of a Bech32 one, and Bech32m encoding will be used for such + addresses in RPC output as well. No version 1 addresses should be created + for mainnet until consensus rules are adopted that give them meaning + (e.g. through [BIP 341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki)). + Once that happens, Bech32m is expected to be used for them, so this shouldn't + affect any production systems, but may be observed on other networks where such + addresses already have meaning (like signet). diff --git a/doc/release-notes.md b/doc/release-notes.md index 0f248494c7..e46380b38f 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -51,9 +51,7 @@ 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. -From Bitcoin Core 0.22.0 onwards, macOS versions earlier than 10.14 are no -longer supported. Additionally, Bitcoin Core does not yet change appearance -when macOS "dark mode" is activated. +From Bitcoin Core 22.0 onwards, macOS versions earlier than 10.14 are no longer supported. Notable changes =============== @@ -69,6 +67,21 @@ Updated RPCs `whitelisted`, the `permissions` field indicates if the peer has special privileges. The `banscore` field has simply been removed. (#20755) +- The following RPCs: `gettxout`, `getrawtransaction`, `decoderawtransaction`, + `decodescript`, `gettransaction`, and REST endpoints: `/rest/tx`, + `/rest/getutxos`, `/rest/block` deprecated the following fields (which are no + longer returned in the responses by default): `addresses`, `reqSigs`. + The `-deprecatedrpc=addresses` flag must be passed for these fields to be + included in the RPC response. This flag/option will be available until v23, at which + point the deprecation will be removed entirely. Note that these fields are attributes of + the `scriptPubKey` object returned in the RPC response. However, in the response + of `decodescript` these fields are top-level attributes, and included again as attributes + of the `scriptPubKey` object. (#20286) + +- When creating a hex-encoded bitcoin transaction using the `bitcoin-tx` utility + with the `-json` option set, the following fields: `addresses`, `reqSigs` are no longer + returned in the tx output of the response. (#20286) + Changes to Wallet or GUI related RPCs can be found in the GUI or Wallet section below. New RPCs @@ -105,6 +118,10 @@ Low-level changes RPC --- +- The RPC server can process a limited number of simultaneous RPC requests. + Previously, if this limit was exceeded, `bitcoind` would respond with + [status code 500 (`HTTP_INTERNAL_SERVER_ERROR`)](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#5xx_server_errors). + Now it returns status code 503 (`HTTP_SERVICE_UNAVAILABLE`). (#18335) Tests ----- |