diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/JSON-RPC-interface.md | 12 | ||||
| -rw-r--r-- | doc/README.md | 1 | ||||
| -rw-r--r-- | doc/bips.md | 8 | ||||
| -rw-r--r-- | doc/build-osx.md | 2 | ||||
| -rw-r--r-- | doc/dependencies.md | 2 | ||||
| -rw-r--r-- | doc/descriptors.md | 19 | ||||
| -rw-r--r-- | doc/developer-notes.md | 4 | ||||
| -rw-r--r-- | doc/psbt.md | 10 | ||||
| -rw-r--r-- | doc/release-notes.md | 32 | ||||
| -rw-r--r-- | doc/release-process.md | 15 | ||||
| -rw-r--r-- | doc/shared-libraries.md | 4 | ||||
| -rw-r--r-- | doc/tor.md | 7 | ||||
| -rw-r--r-- | doc/travis-ci.md | 42 |
13 files changed, 84 insertions, 74 deletions
diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md index 982afd5d56..a0cfe84a3e 100644 --- a/doc/JSON-RPC-interface.md +++ b/doc/JSON-RPC-interface.md @@ -5,6 +5,18 @@ The headless daemon `bitcoind` has the JSON-RPC API enabled by default, the GUI option. In the GUI it is possible to execute RPC methods in the Debug Console Dialog. +## Versioning + +The RPC interface might change from one major version of Bitcoin Core to the +next. This makes the RPC interface implicitly versioned on the major version. +The version tuple can be retrieved by e.g. the `getnetworkinfo` RPC in +`version`. + +Usually deprecated features can be re-enabled during the grace-period of one +major version via the `-deprecatedrpc=` command line option. The release notes +of a new major release come with detailed instructions on what RPC features +were deprecated and how to re-enable them temporarily. + ## Security The RPC interface allows other programs to control Bitcoin Core, diff --git a/doc/README.md b/doc/README.md index 8876ffdd72..b4fa933c8e 100644 --- a/doc/README.md +++ b/doc/README.md @@ -57,7 +57,6 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th - [Source Code Documentation (External Link)](https://dev.visucore.com/bitcoin/doxygen/) - [Translation Process](translation_process.md) - [Translation Strings Policy](translation_strings_policy.md) -- [Travis CI](travis-ci.md) - [JSON-RPC Interface](JSON-RPC-interface.md) - [Unauthenticated REST Interface](REST-interface.md) - [Shared Libraries](shared-libraries.md) diff --git a/doc/bips.md b/doc/bips.md index 76edc94c29..eb24ce6f66 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.17.0**): +BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.18.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)). @@ -15,11 +15,11 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.17.0**): * [`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 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 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, and support is deprecated as of **v0.18.0**. * [`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). * [`BIP 66`](https://github.com/bitcoin/bips/blob/master/bip-0066.mediawiki): The strict DER rules and associated version 3 blocks have been implemented since **v0.10.0** ([PR #5713](https://github.com/bitcoin/bitcoin/pull/5713)). * [`BIP 68`](https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki): Sequence locks have been implemented as of **v0.12.1** ([PR #7184](https://github.com/bitcoin/bitcoin/pull/7184)), and have been activated since *block 419328*. -* [`BIP 70`](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki) [`71`](https://github.com/bitcoin/bips/blob/master/bip-0071.mediawiki) [`72`](https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki): Payment Protocol support has been available in Bitcoin Core GUI since **v0.9.0** ([PR #5216](https://github.com/bitcoin/bitcoin/pull/5216)). +* [`BIP 70`](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki) [`71`](https://github.com/bitcoin/bips/blob/master/bip-0071.mediawiki) [`72`](https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki): Payment Protocol support has been available in Bitcoin Core GUI since **v0.9.0** ([PR #5216](https://github.com/bitcoin/bitcoin/pull/5216)). Support can be optionally disabled at build time since **v0.18.0** ([PR 14451](https://github.com/bitcoin/bitcoin/pull/14451)). * [`BIP 90`](https://github.com/bitcoin/bips/blob/master/bip-0090.mediawiki): Trigger mechanism for activation of BIPs 34, 65, and 66 has been simplified to block height checks since **v0.14.0** ([PR #8391](https://github.com/bitcoin/bitcoin/pull/8391)). * [`BIP 111`](https://github.com/bitcoin/bips/blob/master/bip-0111.mediawiki): `NODE_BLOOM` service bit added, and enforced for all peer versions as of **v0.13.0** ([PR #6579](https://github.com/bitcoin/bitcoin/pull/6579) and [PR #6641](https://github.com/bitcoin/bitcoin/pull/6641)). * [`BIP 112`](https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki): The CHECKSEQUENCEVERIFY opcode has been implemented since **v0.12.1** ([PR #7524](https://github.com/bitcoin/bitcoin/pull/7524)) and has been activated since *block 419328*. @@ -33,7 +33,7 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.17.0**): * [`BIP 145`](https://github.com/bitcoin/bips/blob/master/bip-0145.mediawiki): getblocktemplate updates for Segregated Witness as of **v0.13.0** ([PR 8149](https://github.com/bitcoin/bitcoin/pull/8149)). * [`BIP 147`](https://github.com/bitcoin/bips/blob/master/bip-0147.mediawiki): NULLDUMMY softfork as of **v0.13.1** ([PR 8636](https://github.com/bitcoin/bitcoin/pull/8636) and [PR 8937](https://github.com/bitcoin/bitcoin/pull/8937)). * [`BIP 152`](https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki): Compact block transfer and related optimizations are used as of **v0.13.0** ([PR 8068](https://github.com/bitcoin/bitcoin/pull/8068)). -* [`BIP 159`](https://github.com/bitcoin/bips/blob/master/bip-0159.mediawiki): NODE_NETWORK_LIMITED service bit [signaling only] is supported as of **v0.16.0** ([PR 11740](https://github.com/bitcoin/bitcoin/pull/11740)). +* [`BIP 159`](https://github.com/bitcoin/bips/blob/master/bip-0159.mediawiki): The NODE_NETWORK_LIMITED service bit is signalled as of **v0.16.0** ([PR 11740](https://github.com/bitcoin/bitcoin/pull/11740)), and such nodes are connected to as of **v0.17.0** ([PR 10387](https://github.com/bitcoin/bitcoin/pull/10387)). * [`BIP 173`](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki): Bech32 addresses for native Segregated Witness outputs are supported as of **v0.16.0** ([PR 11167](https://github.com/bitcoin/bitcoin/pull/11167)). * [`BIP 174`](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki): RPCs to operate on Partially Signed Bitcoin Transactions (PSBT) are present as of **v0.17.0** ([PR 13557](https://github.com/bitcoin/bitcoin/pull/13557)). * [`BIP 176`](https://github.com/bitcoin/bips/blob/master/bip-0176.mediawiki): Bits Denomination [QT only] is supported as of **v0.16.0** ([PR 12035](https://github.com/bitcoin/bitcoin/pull/12035)). diff --git a/doc/build-osx.md b/doc/build-osx.md index 119896dc67..d28a3d97aa 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -82,6 +82,8 @@ Bitcoin Core is now available at `./src/bitcoind` Before running, you may create an empty configuration file: + mkdir -p "/Users/${USER}/Library/Application Support/Bitcoin" + touch "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" diff --git a/doc/dependencies.md b/doc/dependencies.md index c445e2e23f..1b3df62867 100644 --- a/doc/dependencies.md +++ b/doc/dependencies.md @@ -43,4 +43,4 @@ Some dependencies are not needed in all configurations. The following are some f * ZeroMQ is needed only with the `--with-zmq` option. #### Other -* librsvg is only needed if you need to run `make deploy` on (cross-compliation to) macOS. +* librsvg is only needed if you need to run `make deploy` on (cross-compilation to) macOS. diff --git a/doc/descriptors.md b/doc/descriptors.md index 5dbcd95e1d..dbdac2c5b6 100644 --- a/doc/descriptors.md +++ b/doc/descriptors.md @@ -1,11 +1,18 @@ # Support for Output Descriptors in Bitcoin Core -Since Bitcoin Core v0.17, there is support for Output Descriptors in the -`scantxoutset` RPC call. This is a simple language which can be used to -describe collections of output scripts. - -This document describes the language. For the specifics on usage for scanning -the UTXO set, see the `scantxoutset` RPC help. +Since Bitcoin Core v0.17, there is support for Output Descriptors. This is a +simple language which can be used to describe collections of output scripts. +Supporting RPCs are: +- `scantxoutset` takes as input descriptors to scan for, and also reports + specialized descriptors for the matching UTXOs. +- `getdescriptorinfo` analyzes a descriptor, and reports a canonicalized version + with checksum added. +- `deriveaddresses` takes as input a descriptor and computes the corresponding + addresses. +- `listunspent` outputs a specialized descriptor for the reported unspent outputs. + +This document describes the language. For the specifics on usage, see the RPC +documentation for the functions mentioned above. ## Features diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 62c764bb31..cf071167c4 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -620,8 +620,8 @@ class AddressBookPage Mode m_mode; } -AddressBookPage::AddressBookPage(Mode _mode) : - m_mode(_mode) +AddressBookPage::AddressBookPage(Mode _mode) + : m_mode(_mode) ... ``` diff --git a/doc/psbt.md b/doc/psbt.md index 560b45ef31..9d85af0348 100644 --- a/doc/psbt.md +++ b/doc/psbt.md @@ -67,6 +67,9 @@ hardware implementations will typically implement multiple roles simultaneously. input a PSBT, adds UTXO, key, and script data to inputs and outputs that miss it, and optionally signs inputs. Where possible it also finalizes the partial signatures. +- **`utxoupdatepsbt` (Updater)** is a node RPC that takes a PSBT and updates it + to include information available from the UTXO set (works only for SegWit + inputs). - **`finalizepsbt` (Finalizer, Extractor)** is a utility RPC that finalizes any partial signatures, and if all inputs are finalized, converts the result to a fully signed transaction which can be broadcast with `sendrawtransaction`. @@ -74,8 +77,15 @@ hardware implementations will typically implement multiple roles simultaneously. can be used at any point in the workflow to merge information added to different versions of the same PSBT. In particular it is useful to combine the output of multiple Updaters or Signers. +- **`joinpsbts`** (Creator) is a utility RPC that joins multiple PSBTs together, + concatenating the inputs and outputs. This can be used to construct CoinJoin + transactions. - **`decodepsbt`** is a diagnostic utility RPC which will show all information in a PSBT in human-readable form, as well as compute its eventual fee if known. +- **`analyzepsbt`** is a utility RPC that examines an RPC and reports the + next steps in the workflow if known, computes the fee of the resulting + transaction, and estimates the weight and feerate if possible. + ### Workflows diff --git a/doc/release-notes.md b/doc/release-notes.md index ebcdcda306..0de0f563b1 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -24,14 +24,9 @@ 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). -The first time you run version 0.15.0, your chainstate database will be converted to a -new format, which will take anywhere from a few minutes to half an hour, -depending on the speed of your machine. - -Note that the block database format also changed in version 0.8.0 and there is no -automatic upgrade code from before version 0.8 to version 0.15.0. Upgrading -directly from 0.7.x and earlier without redownloading the blockchain is not supported. -However, as usual, old wallet versions are still supported. +Upgrading directly from a version of Bitcoin Core that has reached its EOL is +possible, but might take some time if the datadir needs to be migrated. Old +wallet versions of Bitcoin Core are generally supported. Downgrading warning ------------------- @@ -66,16 +61,33 @@ platform. Notable changes =============== -Example item +Updated RPCs ------------ +Note: some low-level RPC changes mainly useful for testing are described in the +Low-level Changes section below. + +* The `sendmany` RPC had an argument `minconf` that was not well specified and + would lead to RPC errors even when the wallet's coin selection would succeed. + The `sendtoaddress` RPC never had this check, so to normalize the behavior, + `minconf` is now ignored in `sendmany`. If the coin selection does not + succeed due to missing coins, it will still throw an RPC error. Be reminded + that coin selection is influenced by the `-spendzeroconfchange`, + `-limitancestorcount`, `-limitdescendantcount` and `-walletrejectlongchains` + command line arguments. + Low-level changes ================= -Example item +Configuration ------------ +* An error is issued where previously a warning was issued when a setting in + the config file was specified in the default section, but not overridden for + the selected network. This change takes only effect if the selected network + is not mainnet. + Credits ======= diff --git a/doc/release-process.md b/doc/release-process.md index eb1f5ad222..7522310ce2 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -4,15 +4,14 @@ Release Process Before every release candidate: * Update translations (ping wumpus on IRC) see [translation_process.md](https://github.com/bitcoin/bitcoin/blob/master/doc/translation_process.md#synchronising-translations). - * Update manpages, see [gen-manpages.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagessh). -* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`) +* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`). Before every minor and major release: * Update [bips.md](bips.md) to account for changes since the last release. -* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_IS_RELEASE` to `true`) (don't forget to set `CLIENT_VERSION_RC` to `0`) -* Write release notes (see below) +* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_RC` to `0`). +* Write release notes (see below). * Update `src/chainparams.cpp` nMinimumChainWork with information from the getblockchaininfo rpc. * Update `src/chainparams.cpp` defaultAssumeValid with information from the getblockhash rpc. - The selected value must not be orphaned so it may be useful to set the value two blocks back from the tip. @@ -26,7 +25,13 @@ Before every major release: * Update [`src/chainparams.cpp`](/src/chainparams.cpp) m_assumed_blockchain_size and m_assumed_chain_state_size with the current size plus some overhead. * Update `src/chainparams.cpp` chainTxData with statistics about the transaction count and rate. Use the output of the RPC `getchaintxstats`, see [this pull request](https://github.com/bitcoin/bitcoin/pull/12270) for an example. Reviewers can verify the results by running `getchaintxstats <window_block_count> <window_last_block_hash>` with the `window_block_count` and `window_last_block_hash` from your output. -* Update version of `contrib/gitian-descriptors/*.yml`: usually one'd want to do this on master after branching off the release - but be sure to at least do it before a new major release +* Update version of `contrib/gitian-descriptors/*.yml`: usually one'd want to do this on master after branching off the release - but be sure to at least do it before a new major release. +* In `configure.ac` and `build_msvc/bitcoin_config.h` on _the master branch_: + - update `CLIENT_VERSION_MINOR` version +* In `configure.ac` and `build_msvc/bitcoin_config.h` on _a new release branch_ (see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd972fca3dd4a33cfff90bf901b71a687e7)): + - update `CLIENT_VERSION_MINOR` version + - set `CLIENT_VERSION_REVISION` to `0` + - set `CLIENT_VERSION_IS_RELEASE` to `true` ### First time / New builders diff --git a/doc/shared-libraries.md b/doc/shared-libraries.md index dc363582cc..e960863a80 100644 --- a/doc/shared-libraries.md +++ b/doc/shared-libraries.md @@ -7,11 +7,11 @@ The purpose of this library is to make the verification functionality that is cr ### API -The interface is defined in the C header `bitcoinconsensus.h` located in `src/script/bitcoinconsensus.h`. +The interface is defined in the C header `bitcoinconsensus.h` located in `src/script/bitcoinconsensus.h`. #### Version -`bitcoinconsensus_version` returns an `unsigned int` with the API version *(currently at an experimental `0`)*. +`bitcoinconsensus_version` returns an `unsigned int` with the API version *(currently `1`)*. #### Script Validation diff --git a/doc/tor.md b/doc/tor.md index c46b7e9f60..cfb7f16666 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -16,7 +16,7 @@ outgoing connections, but more is possible. -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. + to explicitly disable access to hidden services. -listen When using -proxy, listening is disabled by default. If you want to run a hidden service (see next section), you'll need to enable @@ -27,6 +27,11 @@ outgoing connections, but more is possible. -seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with other P2P nodes. + -onlynet=onion Make outgoing connections only to .onion addresses. Incoming + connections are not affected by this option. This option can be + specified multiple times to allow multiple network types, e.g. + ipv4, ipv6, or onion. + In a typical situation, this suffices to run behind a Tor proxy: ./bitcoind -proxy=127.0.0.1:9050 diff --git a/doc/travis-ci.md b/doc/travis-ci.md deleted file mode 100644 index 38085cec35..0000000000 --- a/doc/travis-ci.md +++ /dev/null @@ -1,42 +0,0 @@ -Travis CI -========= - -Support for using travis-ci has been added in order to automate pull-testing. -See [travis-ci.org](https://travis-ci.org/) for more info - -This procedure is different than the pull-tester that came before it in a few -ways. - -There is nothing to administer. This is a major feature as it means -that builds have no local state. Because there is no ability to login to the -builders to install packages (tools, dependencies, etc), the entire build -procedure must instead be controlled by a declarative script `.travis.yml`. -This script declares each build configuration, creates virtual machines as -necessary, builds, then discards the virtual machines. - -A build matrix is constructed to test a wide range of configurations, rather -than a single pass/fail. This helps to catch build failures and logic errors -that present on platforms other than the ones the author has tested. This -matrix is defined in the build script and can be changed at any time. - -All builders use the dependency-generator in the [depends dir](/depends), rather than -using apt-get to install build dependencies. This guarantees that the tester -is using the same versions as Gitian, so the build results are nearly identical -to what would be found in a final release. However, this also means that builds -will fail if new dependencies are introduced without being added to the -dependency generator. - -In order to avoid rebuilding all dependencies for each build, the binaries are -cached and re-used when possible. Changes in the dependency-generator will -trigger cache-invalidation and rebuilds as necessary. - -These caches can be manually removed if necessary. This is one of the very few -manual operations that is possible with Travis, and it can be done by the -Bitcoin Core committer via the Travis web interface. - -In some cases, secure strings may be needed for hiding sensitive info such as -private keys or URLs. The travis client may be used to create these strings: -http://docs.travis-ci.com/user/encryption-keys/ - -For the details of the build descriptor, see the official docs: -http://docs.travis-ci.com/user/build-configuration/ |