diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/REST-interface.md | 12 | ||||
| -rw-r--r-- | doc/build-openbsd.md | 14 | ||||
| -rw-r--r-- | doc/developer-notes.md | 16 | ||||
| -rw-r--r-- | doc/gitian-building.md | 6 | ||||
| -rw-r--r-- | doc/gitian-building/system_settings.png | bin | 0 -> 76448 bytes | |||
| -rw-r--r-- | doc/init.md | 28 | ||||
| -rw-r--r-- | doc/release-notes.md | 99 | ||||
| -rw-r--r-- | doc/release-process.md | 6 |
8 files changed, 73 insertions, 108 deletions
diff --git a/doc/REST-interface.md b/doc/REST-interface.md index caf6782886..7a17c175bd 100644 --- a/doc/REST-interface.md +++ b/doc/REST-interface.md @@ -8,14 +8,14 @@ The interface runs on the same port as the JSON-RPC interface, by default port 8 Supported API ------------- -####Transactions +#### Transactions `GET /rest/tx/<TX-HASH>.<bin|hex|json>` Given a transaction hash: returns a transaction in binary, hex-encoded binary, or JSON formats. For full TX query capability, one must enable the transaction index via "txindex=1" command line / configuration option. -####Blocks +#### Blocks `GET /rest/block/<BLOCK-HASH>.<bin|hex|json>` `GET /rest/block/notxdetails/<BLOCK-HASH>.<bin|hex|json>` @@ -25,12 +25,12 @@ The HTTP request and response are both handled entirely in-memory, thus making m With the /notxdetails/ option JSON response will only contain the transaction hash instead of the complete transaction details. The option only affects the JSON response. -####Blockheaders +#### Blockheaders `GET /rest/headers/<COUNT>/<BLOCK-HASH>.<bin|hex|json>` Given a block hash: returns <COUNT> amount of blockheaders in upward direction. -####Chaininfos +#### Chaininfos `GET /rest/chaininfo.json` Returns various state info regarding block chain processing. @@ -48,7 +48,7 @@ Only supports JSON as output format. * softforks : (array) status of softforks in progress * bip9_softforks : (object) status of BIP9 softforks in progress -####Query UTXO set +#### Query UTXO set `GET /rest/getutxos/<checkmempool>/<txid>-<n>/<txid>-<n>/.../<txid>-<n>.<bin|hex|json>` The getutxo command allows querying of the UTXO set given a set of outpoints. @@ -81,7 +81,7 @@ $ curl localhost:18332/rest/getutxos/checkmempool/b2cdfd7b89def827ff8af7cd9bff76 } ``` -####Memory pool +#### Memory pool `GET /rest/mempool/info.json` Returns various information about the TX mempool. diff --git a/doc/build-openbsd.md b/doc/build-openbsd.md index f4a9826d80..cd800464b4 100644 --- a/doc/build-openbsd.md +++ b/doc/build-openbsd.md @@ -1,6 +1,6 @@ OpenBSD build guide ====================== -(updated for OpenBSD 6.0) +(updated for OpenBSD 6.1) This guide describes how to build bitcoind and command-line utilities on OpenBSD. @@ -48,13 +48,13 @@ BOOST_PREFIX="${BITCOIN_ROOT}/boost" mkdir -p $BOOST_PREFIX # Fetch the source and verify that it is not tampered with -curl -o boost_1_61_0.tar.bz2 http://heanet.dl.sourceforge.net/project/boost/boost/1.61.0/boost_1_61_0.tar.bz2 -echo 'a547bd06c2fd9a71ba1d169d9cf0339da7ebf4753849a8f7d6fdb8feee99b640 boost_1_61_0.tar.bz2' | sha256 -c -# MUST output: (SHA256) boost_1_61_0.tar.bz2: OK -tar -xjf boost_1_61_0.tar.bz2 +curl -o boost_1_64_0.tar.bz2 https://netcologne.dl.sourceforge.net/project/boost/boost/1.64.0/boost_1_64_0.tar.bz2 +echo '7bcc5caace97baa948931d712ea5f37038dbb1c5d89b43ad4def4ed7cb683332 boost_1_64_0.tar.bz2' | sha256 -c +# MUST output: (SHA256) boost_1_64_0.tar.bz2: OK +tar -xjf boost_1_64_0.tar.bz2 -# Boost 1.61 needs one small patch for OpenBSD -cd boost_1_61_0 +# Boost 1.64 needs one small patch for OpenBSD +cd boost_1_64_0 # Also here: https://gist.githubusercontent.com/laanwj/bf359281dc319b8ff2e1/raw/92250de8404b97bb99d72ab898f4a8cb35ae1ea3/patch-boost_test_impl_execution_monitor_ipp.patch patch -p0 < /usr/ports/devel/boost/patches/patch-boost_test_impl_execution_monitor_ipp diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 81bdcc9fdb..9b85600ccc 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -4,7 +4,7 @@ Developer Notes Various coding styles have been used during the history of the codebase, and the result is not very consistent. However, we're now trying to converge to a single style, which is specified below. When writing patches, favor the new -style over attempting to mimick the surrounding style, except for move-only +style over attempting to mimic the surrounding style, except for move-only commits. Do not submit patches solely to modify the style of existing code. @@ -28,15 +28,17 @@ tool to clean up patches automatically before submission. required when doing so would need changes to significant pieces of existing code. - Variable and namespace names are all lowercase, and may use `_` to - separate words. + separate words (snake_case). - Class member variables have a `m_` prefix. - Global variables have a `g_` prefix. - Constant names are all uppercase, and use `_` to separate words. - - Class names, function names and method names are CamelCase. Do not prefix - class names with `C`. + - Class names, function names and method names are UpperCamelCase + (PascalCase). Do not prefix class names with `C`. - **Miscellaneous** - `++i` is preferred over `i++`. + - `nullptr` is preferred over `NULL` or `(void*)0`. + - `static_assert` is preferred over `assert` where possible. Generally; compile-time checking is preferred over run-time checking. Block style example: ```c++ @@ -275,7 +277,7 @@ Wallet - *Rationale*: In RPC code that conditionally uses the wallet (such as `validateaddress`) it is easy to forget that global pointer `pwalletMain` - can be NULL. See `test/functional/disablewallet.py` for functional tests + can be nullptr. See `test/functional/disablewallet.py` for functional tests exercising the API with `-disablewallet` - Include `db_cxx.h` (BerkeleyDB header) only when `ENABLE_WALLET` is set @@ -561,10 +563,10 @@ A few guidelines for introducing and reviewing new RPC interfaces: which is error prone, and it is easy to get things such as escaping wrong. JSON already supports nested data structures, no need to re-invent the wheel. - - *Exception*: AmountToValue can parse amounts as string. This was introduced because many JSON + - *Exception*: AmountFromValue can parse amounts as string. This was introduced because many JSON parsers and formatters hard-code handling decimal numbers as floating point values, resulting in potential loss of precision. This is unacceptable for - monetary values. **Always** use `AmountToValue` and `ValueToAmount` when + monetary values. **Always** use `AmountFromValue` and `ValueFromAmount` when inputting or outputting monetary values. The only exceptions to this are `prioritisetransaction` and `getblocktemplate` because their interface is specified as-is in BIP22. diff --git a/doc/gitian-building.md b/doc/gitian-building.md index 9f9afaf04f..636686b391 100644 --- a/doc/gitian-building.md +++ b/doc/gitian-building.md @@ -76,7 +76,11 @@ In the VirtualBox GUI click "New" and choose the following parameters in the wiz After creating the VM, we need to configure it. -- Click the `Settings` button, then go to the `Network` tab. Adapter 1 should be attached to `NAT`. +- Click the `Settings` button, then go to `System` tab and `Processor` sub-tab. Increase the number of processors to the number of cores on your machine if you want builds to be faster. + + + +- Go to the `Network` tab. Adapter 1 should be attached to `NAT`.  diff --git a/doc/gitian-building/system_settings.png b/doc/gitian-building/system_settings.png Binary files differnew file mode 100644 index 0000000000..a5720ef3a3 --- /dev/null +++ b/doc/gitian-building/system_settings.png diff --git a/doc/init.md b/doc/init.md index e3db5b05ef..75f9013f29 100644 --- a/doc/init.md +++ b/doc/init.md @@ -10,14 +10,14 @@ can be found in the contrib/init folder. contrib/init/bitcoind.conf: Upstart service configuration file contrib/init/bitcoind.init: CentOS compatible SysV style init script -1. Service User +Service User --------------------------------- All three Linux startup configurations assume the existence of a "bitcoin" user and group. They must be created before attempting to use these scripts. The OS X configuration assumes bitcoind will be set up for the current user. -2. Configuration +Configuration --------------------------------- At a bare minimum, bitcoind requires that the rpcpassword setting be set @@ -46,10 +46,10 @@ relative to the data directory. `wallet` *only* supports relative paths. For an example configuration file that describes the configuration settings, see `contrib/debian/examples/bitcoin.conf`. -3. Paths +Paths --------------------------------- -3a) Linux +### Linux All three configurations assume several paths that might need to be adjusted. @@ -65,17 +65,17 @@ reasons to make the configuration file and data directory only readable by the bitcoin user and group. Access to bitcoin-cli and other bitcoind rpc clients can then be controlled by group membership. -3b) Mac OS X +### Mac OS X Binary: `/usr/local/bin/bitcoind` Configuration file: `~/Library/Application Support/Bitcoin/bitcoin.conf` -Data directory: `~/Library/Application Support/Bitcoin` -Lock file: `~/Library/Application Support/Bitcoin/.lock` +Data directory: `~/Library/Application Support/Bitcoin` +Lock file: `~/Library/Application Support/Bitcoin/.lock` -4. Installing Service Configuration +Installing Service Configuration ----------------------------------- -4a) systemd +### systemd Installing this .service file consists of just copying it to /usr/lib/systemd/system directory, followed by the command @@ -84,14 +84,14 @@ Installing this .service file consists of just copying it to To test, run `systemctl start bitcoind` and to enable for system startup run `systemctl enable bitcoind` -4b) OpenRC +### OpenRC Rename bitcoind.openrc to bitcoind and drop it in /etc/init.d. Double check ownership and permissions and make it executable. Test it with `/etc/init.d/bitcoind start` and configure it to run on startup with `rc-update add bitcoind` -4c) Upstart (for Debian/Ubuntu based distributions) +### Upstart (for Debian/Ubuntu based distributions) Drop bitcoind.conf in /etc/init. Test by running `service bitcoind start` it will automatically start on reboot. @@ -99,7 +99,7 @@ it will automatically start on reboot. NOTE: This script is incompatible with CentOS 5 and Amazon Linux 2014 as they use old versions of Upstart and do not supply the start-stop-daemon utility. -4d) CentOS +### CentOS Copy bitcoind.init to /etc/init.d/bitcoind. Test by running `service bitcoind start`. @@ -107,7 +107,7 @@ Using this script, you can adjust the path and flags to the bitcoind program by setting the BITCOIND and FLAGS environment variables in the file /etc/sysconfig/bitcoind. You can also use the DAEMONOPTS environment variable here. -4e) Mac OS X +### Mac OS X Copy org.bitcoin.bitcoind.plist into ~/Library/LaunchAgents. Load the launch agent by running `launchctl load ~/Library/LaunchAgents/org.bitcoin.bitcoind.plist`. @@ -118,7 +118,7 @@ NOTE: This approach is intended for those wanting to run bitcoind as the current You will need to modify org.bitcoin.bitcoind.plist if you intend to use it as a Launch Daemon with a dedicated bitcoin user. -5. Auto-respawn +Auto-respawn ----------------------------------- Auto respawning is currently only configured for Upstart and systemd. diff --git a/doc/release-notes.md b/doc/release-notes.md index a13ede2dd5..aa1d1bea14 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -16,16 +16,39 @@ To receive security and update notifications, please subscribe to: <https://bitcoincore.org/en/list/announcements/join/> +How to Upgrade +============== + +If you are running an older version, shut it down. Wait until it has completely +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. + +Downgrading warning +------------------- + +The chainstate database for this release is not compatible with previous +releases, so if you run 0.15 and then decide to switch back to any +older version, you will need to run the old release with the `-reindex-chainstate` +option to rebuild the chainstate data structures in the old format. + +If your node has pruning enabled, this will entail re-downloading and +processing the entire blockchain. + Compatibility ============== Bitcoin Core is extensively tested on multiple operating systems using -the Linux kernel, macOS 10.8+, and Windows Vista and later. - -Microsoft ended support for Windows XP on [April 8th, 2014](https://www.microsoft.com/en-us/WindowsForBusiness/end-of-xp-support). -No attempt is made to prevent installing or running the software on Windows XP, you -can still do so at your own risk but be aware that there are known instabilities. -Please do not report issues about Windows XP to the issue tracker. +the Linux kernel, macOS 10.8+, and Windows Vista and later. Windows XP is not supported. Bitcoin Core should also work on most other Unix-like systems but is not frequently tested on them. @@ -33,70 +56,6 @@ frequently tested on them. Notable changes =============== -Low-level RPC changes ---------------------- - -- The new database model no longer stores information about transaction - versions of unspent outputs. This means that: - - The `gettxout` RPC no longer has a `version` field in the response. - - The `gettxoutsetinfo` RPC reports `hash_serialized_2` instead of `hash_serialized`, - which does not commit to the transaction versions of unspent outputs, but does - commit to the height and coinbase information. - - The `gettxoutsetinfo` response now contains `disk_size` and `bogosize` instead of - `bytes_serialized`. The first is a more accurate estimate of actual disk usage, but - is not deterministic. The second is unrelated to disk usage, but is a - database-independent metric of UTXO set size: it counts every UTXO entry as 50 + the - length of its scriptPubKey. - - The `getutxos` REST path no longer reports the `txvers` field in JSON format, - and always reports 0 for transaction versions in the binary format - - -- Error codes have been updated to be more accurate for the following error cases: - - `getblock` now returns RPC_MISC_ERROR if the block can't be found on disk (for - example if the block has been pruned). Previously returned RPC_INTERNAL_ERROR. - - `pruneblockchain` now returns RPC_MISC_ERROR if the blocks cannot be pruned - because the node is not in pruned mode. Previously returned RPC_METHOD_NOT_FOUND. - - `pruneblockchain` now returns RPC_INVALID_PARAMETER if the blocks cannot be pruned - because the supplied timestamp is too late. Previously returned RPC_INTERNAL_ERROR. - - `pruneblockchain` now returns RPC_MISC_ERROR if the blocks cannot be pruned - because the blockchain is too short. Previously returned RPC_INTERNAL_ERROR. - - `setban` now returns RPC_CLIENT_INVALID_IP_OR_SUBNET if the supplied IP address - or subnet is invalid. Previously returned RPC_CLIENT_NODE_ALREADY_ADDED. - - `setban` now returns RPC_CLIENT_INVALID_IP_OR_SUBNET if the user tries to unban - a node that has not previously been banned. Previously returned RPC_MISC_ERROR. - - `removeprunedfunds` now returns RPC_WALLET_ERROR if bitcoind is unable to remove - the transaction. Previously returned RPC_INTERNAL_ERROR. - - `removeprunedfunds` now returns RPC_INVALID_PARAMETER if the transaction does not - exist in the wallet. Previously returned RPC_INTERNAL_ERROR. - - `fundrawtransaction` now returns RPC_INVALID_ADDRESS_OR_KEY if an invalid change - address is provided. Previously returned RPC_INVALID_PARAMETER. - - `fundrawtransaction` now returns RPC_WALLET_ERROR if bitcoind is unable to create - the transaction. The error message provides further details. Previously returned - RPC_INTERNAL_ERROR. - - `bumpfee` now returns RPC_INVALID_PARAMETER if the provided transaction has - descendants in the wallet. Previously returned RPC_MISC_ERROR. - - `bumpfee` now returns RPC_INVALID_PARAMETER if the provided transaction has - descendants in the mempool. Previously returned RPC_MISC_ERROR. - - `bumpfee` now returns RPC_WALLET_ERROR if the provided transaction has - has been mined or conflicts with a mined transaction. Previously returned - RPC_INVALID_ADDRESS_OR_KEY. - - `bumpfee` now returns RPC_WALLET_ERROR if the provided transaction is not - BIP 125 replaceable. Previously returned RPC_INVALID_ADDRESS_OR_KEY. - - `bumpfee` now returns RPC_WALLET_ERROR if the provided transaction has already - been bumped by a different transaction. Previously returned RPC_INVALID_REQUEST. - - `bumpfee` now returns RPC_WALLET_ERROR if the provided transaction contains - inputs which don't belong to this wallet. Previously returned RPC_INVALID_ADDRESS_OR_KEY. - - `bumpfee` now returns RPC_WALLET_ERROR if the provided transaction has multiple change - outputs. Previously returned RPC_MISC_ERROR. - - `bumpfee` now returns RPC_WALLET_ERROR if the provided transaction has no change - output. Previously returned RPC_MISC_ERROR. - - `bumpfee` now returns RPC_WALLET_ERROR if the fee is too high. Previously returned - RPC_MISC_ERROR. - - `bumpfee` now returns RPC_WALLET_ERROR if the fee is too low. Previously returned - RPC_MISC_ERROR. - - `bumpfee` now returns RPC_WALLET_ERROR if the change output is too small to bump the - fee. Previously returned RPC_MISC_ERROR. - Credits ======= diff --git a/doc/release-process.md b/doc/release-process.md index 5a99b726f1..f429b4bbdb 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -111,16 +111,16 @@ The gbuild invocations below <b>DO NOT DO THIS</b> by default. ### Build and sign Bitcoin Core for Linux, Windows, and OS X: pushd ./gitian-builder - ./bin/gbuild --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml + ./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml ./bin/gsign --signer $SIGNER --release ${VERSION}-linux --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml mv build/out/bitcoin-*.tar.gz build/out/src/bitcoin-*.tar.gz ../ - ./bin/gbuild --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml + ./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml ./bin/gsign --signer $SIGNER --release ${VERSION}-win-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-win.yml mv build/out/bitcoin-*-win-unsigned.tar.gz inputs/bitcoin-win-unsigned.tar.gz mv build/out/bitcoin-*.zip build/out/bitcoin-*.exe ../ - ./bin/gbuild --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml + ./bin/gbuild --num-make 2 --memory 3000 --commit bitcoin=v${VERSION} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml ./bin/gsign --signer $SIGNER --release ${VERSION}-osx-unsigned --destination ../gitian.sigs/ ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml mv build/out/bitcoin-*-osx-unsigned.tar.gz inputs/bitcoin-osx-unsigned.tar.gz mv build/out/bitcoin-*.tar.gz build/out/bitcoin-*.dmg ../ |
