diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/bips.md | 1 | ||||
| -rw-r--r-- | doc/build-osx.md | 136 | ||||
| -rw-r--r-- | doc/developer-notes.md | 59 | ||||
| -rw-r--r-- | doc/gitian-building.md | 12 | ||||
| -rw-r--r-- | doc/release-notes.md | 30 | ||||
| -rw-r--r-- | doc/tor.md | 18 |
6 files changed, 154 insertions, 102 deletions
diff --git a/doc/bips.md b/doc/bips.md index b4b62e781e..1ec03d2fb1 100644 --- a/doc/bips.md +++ b/doc/bips.md @@ -10,6 +10,7 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.13.0**): * [`BIP 23`](https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki): Some extensions to GBT have been implemented since **v0.10.0rc1**, including longpolling and block proposals ([PR #1816](https://github.com/bitcoin/bitcoin/pull/1816)). * [`BIP 30`](https://github.com/bitcoin/bips/blob/master/bip-0030.mediawiki): The evaluation rules to forbid creating new transactions with the same txid as previous not-fully-spent transactions were implemented since **v0.6.0**, and the rule took effect on *March 15th 2012* ([PR #915](https://github.com/bitcoin/bitcoin/pull/915)). * [`BIP 31`](https://github.com/bitcoin/bips/blob/master/bip-0031.mediawiki): The 'pong' protocol message (and the protocol version bump to 60001) has been implemented since **v0.6.1** ([PR #1081](https://github.com/bitcoin/bitcoin/pull/1081)). +* [`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)). diff --git a/doc/build-osx.md b/doc/build-osx.md index 296e0aa1f0..89d7816c9a 100644 --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -1,129 +1,93 @@ Mac OS X Build Instructions and Notes ==================================== -This guide will show you how to build Bitcoin Core for OS X. - -Notes ------ - -* Tested on OS X 10.7 through 10.11 on 64-bit Intel processors only. - -* All of the commands should be executed in a Terminal application. The -built-in one is located in `/Applications/Utilities`. +The commands in this guide should be executed in a Terminal application. +The built-in one is located in `/Applications/Utilities/Terminal.app`. Preparation ----------- +Download and install [Xcode](https://developer.apple.com/xcode/download). -You need to install Xcode with all the options checked so that the compiler -and everything is available in /usr not just /Developer. Xcode should be -available on your OS X installation media, but if not, you can get the -current version from https://developer.apple.com/xcode/. If you install -Xcode 4.3 or later, you'll need to install its command line tools. This can -be done in `Xcode > Preferences > Downloads > Components` and generally must -be re-done or updated every time Xcode is updated. - -You will also need to install [Homebrew](http://brew.sh) in order to install library -dependencies. +Once installed, run `xcode-select --install` to install the OS X command line tools. -The installation of the actual dependencies is covered in the instructions -sections below. +Install [Homebrew](http://brew.sh). -Instructions: Homebrew +Dependencies ---------------------- -#### Install dependencies using Homebrew + brew install automake berkeley-db4 libtool boost --c++11 miniupnpc openssl pkg-config protobuf --c++11 qt5 libevent - brew install autoconf automake berkeley-db4 libtool boost miniupnpc openssl pkg-config protobuf qt5 libevent +NOTE: Building with Qt4 is still supported, however, could result in a broken UI. Building with Qt5 is recommended. -NOTE: Building with Qt4 is still supported, however, could result in a broken UI. As such, building with Qt5 is recommended. - -### Building `bitcoin` +Build Bitcoin Core +------------------------ -1. Clone the GitHub tree to get the source code and go into the directory. +1. Clone the bitcoin source code and cd into `bitcoin` - git clone https://github.com/bitcoin/bitcoin.git + git clone https://github.com/bitcoin/bitcoin cd bitcoin 2. Build bitcoin-core: - This will configure and build the headless bitcoin binaries as well as the gui (if Qt is found). - You can disable the gui build by passing `--without-gui` to configure. + + Configure and build the headless bitcoin binaries as well as the GUI (if Qt is found). + + You can disable the GUI build by passing `--without-gui` to configure. ./autogen.sh ./configure make -3. It is also a good idea to build and run the unit tests: +3. It is recommended to build and run the unit tests: make check -4. (Optional) You can also install bitcoind to your path: - - make install - -Use Qt Creator as IDE ------------------------- -You can use Qt Creator as IDE, for debugging and for manipulating forms, etc. -Download Qt Creator from https://www.qt.io/download/. Download the "community edition" and only install Qt Creator (uncheck the rest during the installation process). - -1. Make sure you installed everything through Homebrew mentioned above -2. Do a proper ./configure --enable-debug -3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project -4. Enter "bitcoin-qt" as project name, enter src/qt as location -5. Leave the file selection as it is -6. Confirm the "summary page" -7. In the "Projects" tab select "Manage Kits..." -8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler -9. Select LLDB as debugger (you might need to set the path to your installation) -10. Start debugging with Qt Creator - -Creating a release build ------------------------- -You can ignore this section if you are building `bitcoind` for your own use. - -bitcoind/bitcoin-cli binaries are not included in the Bitcoin-Qt.app bundle. - -If you are building `bitcoind` or `Bitcoin Core` for others, your build machine should be set up -as follows for maximum compatibility: +4. You can also create a .dmg that contains the .app bundle (optional): -All dependencies should be compiled with these flags: - - -mmacosx-version-min=10.7 - -arch x86_64 - -isysroot $(xcode-select --print-path)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk - -Once dependencies are compiled, see [doc/release-process.md](release-process.md) for how the Bitcoin Core -bundle is packaged and signed to create the .dmg disk image that is distributed. + make deploy Running ------- -It's now available at `./bitcoind`, provided that you are still in the `src` -directory. We have to first create the RPC configuration file, though. +Bitcoin Core is now available at `./src/bitcoind` -Run `./bitcoind` to get the filename where it should be put, or just try these -commands: +Before running, it's recommended 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" + chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf" -The next time you run it, it will start downloading the blockchain, but it won't -output anything while it's doing this. This process may take several hours; -you can monitor its process by looking at the debug.log file, like this: +The first time you run bitcoind, it will start downloading the blockchain. This process could take several hours. + +You can monitor the download process by looking at the debug.log file: tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log Other commands: ------- - ./bitcoind -daemon # to start the bitcoin daemon. - ./bitcoin-cli --help # for a list of command-line options. - ./bitcoin-cli help # When the daemon is running, to get a list of RPC commands + ./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. + +Using Qt Creator as IDE +------------------------ +You can use Qt Creator as an IDE, for bitcoin development. +Download and install the community edition of [Qt Creator](https://www.qt.io/download/). +Uncheck everything except Qt Creator during the installation process. -Using Qt official installer while building ------------------------------------------- +1. Make sure you installed everything through Homebrew mentioned above +2. Do a proper ./configure --enable-debug +3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project +4. Enter "bitcoin-qt" as project name, enter src/qt as location +5. Leave the file selection as it is +6. Confirm the "summary page" +7. In the "Projects" tab select "Manage Kits..." +8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler +9. Select LLDB as debugger (you might need to set the path to your installation) +10. Start debugging with Qt Creator + +Notes +----- + +* Tested on OS X 10.7 through 10.11 on 64-bit Intel processors only. -If you prefer to use the latest Qt installed from the official binary -installer over the brew version, you have to make several changes to -the installed tree and its binaries (all these changes are contained -in the brew version already). The changes needed are described in -[#7714](https://github.com/bitcoin/bitcoin/issues/7714). We do not -support building Bitcoin Core this way though. +* 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/developer-notes.md b/doc/developer-notes.md index add2fb5004..95c46b05fe 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -265,7 +265,7 @@ General C++ the `.h` to the `.cpp` should not result in build errors - Use the RAII (Resource Acquisition Is Initialization) paradigm where possible. For example by using - `scoped_pointer` for allocations in a function. + `unique_ptr` for allocations in a function. - *Rationale*: This avoids memory and resource leaks, and ensures exception safety @@ -284,10 +284,9 @@ C++ data structures - *Rationale*: Behavior is undefined. In C++ parlor this means "may reformat the universe", in practice this has resulted in at least one hard-to-debug crash bug -- Watch out for vector out-of-bounds exceptions. `&vch[0]` is illegal for an - empty vector, `&vch[vch.size()]` is always illegal. Use `begin_ptr(vch)` and - `end_ptr(vch)` to get the begin and end pointer instead (defined in - `serialize.h`) +- Watch out for out-of-bounds vector access. `&vch[vch.size()]` is illegal, + including `&vch[0]` for an empty vector. Use `vch.data()` and `vch.data() + + vch.size()` instead. - Vector bounds checking is only enabled in debug mode. Do not rely on it @@ -323,7 +322,7 @@ Strings and formatting buffer overflows and surprises with `\0` characters. Also some C string manipulations tend to act differently depending on platform, or even the user locale -- Use `ParseInt32`, `ParseInt64`, `ParseDouble` from `utilstrencodings.h` for number parsing +- Use `ParseInt32`, `ParseInt64`, `ParseUInt32`, `ParseUInt64`, `ParseDouble` from `utilstrencodings.h` for number parsing - *Rationale*: These functions do overflow checking, and avoid pesky locale issues @@ -381,3 +380,51 @@ GUI - *Rationale*: Model classes pass through events and data from the core, they should not interact with the user. That's where View classes come in. The converse also holds: try to not directly access core data structures from Views. + +Git and github tips +--------------------- + +- For resolving merge/rebase conflicts, it can be useful to enable diff3 style using + `git config merge.conflictstyle diff3`. Instead of + + <<< + yours + === + theirs + >>> + + you will see + + <<< + yours + ||| + original + === + theirs + >>> + + This may make it much clearer what caused the conflict. In this style, you can often just look + at what changed between *original* and *theirs*, and mechanically apply that to *yours* (or the other way around). + +- When reviewing patches which change indentation in C++ files, use `git diff -w` and `git show -w`. This makes + the diff algorithm ignore whitespace changes. This feature is also available on github.com, by adding `?w=1` + at the end of any URL which shows a diff. + +- When reviewing patches that change symbol names in many places, use `git diff --word-diff`. This will instead + of showing the patch as deleted/added *lines*, show deleted/added *words*. + +- When reviewing patches that move code around, try using + `git diff --patience commit~:old/file.cpp commit:new/file/name.cpp`, and ignoring everything except the + moved body of code which should show up as neither `+` or `-` lines. In case it was not a pure move, this may + even work when combined with the `-w` or `--word-diff` options described above. + +- When looking at other's pull requests, it may make sense to add the following section to your `.git/config` + file: + + [remote "upstream-pull"] + fetch = +refs/pull/*:refs/remotes/upstream-pull/* + url = git@github.com:bitcoin/bitcoin.git + + This will add an `upstream-pull` remote to your git repository, which can be fetched using `git fetch --all` + or `git fetch upstream-pull`. Afterwards, you can use `upstream-pull/NUMBER/head` in arguments to `git show`, + `git checkout` and anywhere a commit id would be acceptable to see the changes from pull request NUMBER. diff --git a/doc/gitian-building.md b/doc/gitian-building.md index 791f209bb1..7796a5fc9c 100644 --- a/doc/gitian-building.md +++ b/doc/gitian-building.md @@ -1,7 +1,7 @@ Gitian building ================ -*Setup instructions for a Gitian build of Bitcoin using a Debian VM or physical system.* +*Setup instructions for a Gitian build of Bitcoin Core using a Debian VM or physical system.* Gitian is the deterministic build process that is used to build the Bitcoin Core executables. It provides a way to be reasonably sure that the @@ -26,7 +26,7 @@ Table of Contents - [Installing Gitian](#installing-gitian) - [Setting up the Gitian image](#setting-up-the-gitian-image) - [Getting and building the inputs](#getting-and-building-the-inputs) -- [Building Bitcoin](#building-bitcoin) +- [Building Bitcoin Core](#building-bitcoin-core) - [Building an alternative repository](#building-an-alternative-repository) - [Signing externally](#signing-externally) - [Uploading signatures](#uploading-signatures) @@ -95,11 +95,11 @@ After creating the VM, we need to configure it. - Click `Ok` twice to save. -Get the [Debian 8.x net installer](http://cdimage.debian.org/debian-cd/8.4.0/amd64/iso-cd/debian-8.4.0-amd64-netinst.iso) (a more recent minor version should also work, see also [Debian Network installation](https://www.debian.org/CD/netinst/)). +Get the [Debian 8.x net installer](http://cdimage.debian.org/debian-cd/8.5.0/amd64/iso-cd/debian-8.5.0-amd64-netinst.iso) (a more recent minor version should also work, see also [Debian Network installation](https://www.debian.org/CD/netinst/)). This DVD image can be validated using a SHA256 hashing tool, for example on Unixy OSes by entering the following in a terminal: - echo "7a6b418e6a4ee3ca75dda04d79ed96c9e2c33bb0c703ca7e40c6374ab4590748 debian-8.4.0-amd64-netinst.iso" | sha256sum -c + echo "ad4e8c27c561ad8248d5ebc1d36eb172f884057bfeb2c22ead823f59fa8c3dff debian-8.5.0-amd64-netinst.iso" | sha256sum -c # (must return OK) Then start the VM. On the first launch you will be asked for a CD or DVD image. Choose the downloaded iso. @@ -342,10 +342,10 @@ manual intervention. Also optionally follow the next step: 'Seed the Gitian sour and offline git repositories' which will fetch the remaining files required for building offline. -Building Bitcoin +Building Bitcoin Core ---------------- -To build Bitcoin (for Linux, OS X and Windows) just follow the steps under 'perform +To build Bitcoin Core (for Linux, OS X and Windows) just follow the steps under 'perform Gitian builds' in [doc/release-process.md](release-process.md#perform-gitian-builds) in the bitcoin repository. This may take some time as it will build all the dependencies needed for each descriptor. diff --git a/doc/release-notes.md b/doc/release-notes.md index 7d44b8cda9..6cc05989db 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -43,6 +43,11 @@ RPC low-level changes 32-bit and 64-bit platforms, and the txids were missing in the hashed data. This has been fixed, but this means that the output will be different than from previous versions. +- Full UTF-8 support in the RPC API. Non-ASCII characters in, for example, + wallet labels have always been malformed because they weren't taken into account + properly in JSON RPC processing. This is no longer the case. This also affects + the GUI debug console. + C++11 and Python 3 ------------------- @@ -80,6 +85,13 @@ The following outputs are affected by this change: - REST `/rest/block/` (JSON format when including extended tx details) - `bitcoin-tx -json` +New mempool information RPC calls +--------------------------------- + +RPC calls have been added to output detailed statistics for individual mempool +entries, as well as to calculate the in-mempool ancestors or descendants of a +transaction: see `getmempoolentry`, `getmempoolancestors`, `getmempooldescendants`. + ### ZMQ Each ZMQ notification now contains an up-counting sequence number that allows @@ -112,6 +124,24 @@ feerate. [BIP 133](https://github.com/bitcoin/bips/blob/master/bip-0133.mediawik ### Wallet +Hierarchical Deterministic Key Generation +----------------------------------------- +Newly created wallets will use hierarchical deterministic key generation +according to BIP32 (keypath m/0'/0'/k'). +Existing wallets will still use traditional key generation. + +Backups of HD wallets, regardless of when they have been created, can +therefore be used to re-generate all possible private keys, even the +ones which haven't already been generated during the time of the backup. + +HD key generation for new wallets can be disabled by `-usehd=0`. Keep in +mind that this flag only has affect on newly created wallets. +You can't disable HD key generation once you have created a HD wallet. + +There is no distinction between internal (change) and external keys. + +[Pull request](https://github.com/bitcoin/bitcoin/pull/8035/files), [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) + ### GUI ### Tests diff --git a/doc/tor.md b/doc/tor.md index 43e922718b..79f1563021 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -95,12 +95,22 @@ Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket API, to create and destroy 'ephemeral' hidden services programmatically. Bitcoin Core has been updated to make use of this. -This means that if Tor is running (and proper authorization is available), -Bitcoin Core automatically creates a hidden service to listen on, without -manual configuration. This will positively affect the number of available -.onion nodes. +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 Core is listening, and a connection to Tor can be made. It can be configured with the `-listenonion`, `-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 +Tor configuration.
\ No newline at end of file |