9 files changed, 302 insertions, 28 deletions
diff --git a/doc/README.md b/doc/README.md
index 0594d20dd..f6df28a89 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -28,7 +28,7 @@ Unpack the files into a directory, and then run bitcoin-qt.exe.
 
 ### OS X
 
-Drag Bitcoin-Qt to your applications folder, and then run Bitcoin-Qt.
+Drag Bitcoin-Core to your applications folder, and then run Bitcoin-Core.
 
 ### Need Help?
 
diff --git a/doc/build-osx.md b/doc/build-osx.md
index 69c401b75..02498e5c4 100644
--- a/doc/build-osx.md
+++ b/doc/build-osx.md
@@ -32,7 +32,7 @@ Instructions: Homebrew
 
 #### Install dependencies using Homebrew
 
-        brew install autoconf automake berkeley-db4 libtool boost miniupnpc openssl pkg-config protobuf 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. As such, building with Qt5 is recommended.
 
diff --git a/doc/build-unix.md b/doc/build-unix.md
index 2102bbc83..159a14060 100644
--- a/doc/build-unix.md
+++ b/doc/build-unix.md
@@ -61,24 +61,24 @@ Dependency Build Instructions: Ubuntu & Debian
 ----------------------------------------------
 Build requirements:
 
-        sudo apt-get install build-essential libtool autotools-dev autoconf pkg-config libssl-dev libevent-dev
+    sudo apt-get install build-essential libtool autotools-dev autoconf pkg-config libssl-dev libevent-dev bsdmainutils
 
-On Ubuntu 15.10+ there are generic names for the individual boost development
-packages, so the following can be used to only install necessary parts of
-boost:
+On at least Ubuntu 14.04+ and Debian 7+ there are generic names for the
+individual boost development packages, so the following can be used to only
+install necessary parts of boost:
 
-        apt-get install libboost-system-dev libboost-filesystem-dev libboost-chrono-dev libboost-program-options-dev libboost-test-dev libboost-thread-dev libboost-base-dev
+    sudo apt-get install libboost-system-dev libboost-filesystem-dev libboost-chrono-dev libboost-program-options-dev libboost-test-dev libboost-thread-dev
 
-For Ubuntu before 15.10, or Debian 7 and later libboost-all-dev has to be installed:
+If that doesn't work, you can install all boost development packages with:
 
-        sudo apt-get install libboost-all-dev
+    sudo apt-get install libboost-all-dev
 
 BerkeleyDB is required for the wallet. db4.8 packages are available [here](https://launchpad.net/~bitcoin/+archive/bitcoin).
 You can add the repository and install using the following commands:
 
-        sudo add-apt-repository ppa:bitcoin/bitcoin
-        sudo apt-get update
-        sudo apt-get install libdb4.8-dev libdb4.8++-dev
+    sudo add-apt-repository ppa:bitcoin/bitcoin
+    sudo apt-get update
+    sudo apt-get install libdb4.8-dev libdb4.8++-dev
 
 Ubuntu and Debian have their own libdb-dev and libdb++-dev packages, but these will install
 BerkeleyDB 5.1 or later, which break binary wallet compatibility with the distributed executables which
@@ -89,11 +89,11 @@ See the section "Disable-wallet mode" to build Bitcoin Core without wallet.
 
 Optional:
 
-        sudo apt-get install libminiupnpc-dev (see --with-miniupnpc and --enable-upnp-default)
+    sudo apt-get install libminiupnpc-dev (see --with-miniupnpc and --enable-upnp-default)
 
 ZMQ dependencies:
 
-        sudo apt-get install libzmq3-dev (provides ZMQ API 4.x)
+    sudo apt-get install libzmq3-dev (provides ZMQ API 4.x)
 
 Dependencies for the GUI: Ubuntu & Debian
 -----------------------------------------
@@ -135,14 +135,6 @@ turned off by default.  See the configure options for upnp behavior desired:
 	--disable-upnp-default   (the default) UPnP support turned off by default at runtime
 	--enable-upnp-default    UPnP support turned on by default at runtime
 
-To build:
-
-	tar -xzvf miniupnpc-1.6.tar.gz
-	cd miniupnpc-1.6
-	make
-	sudo su
-	make install
-
 
 Berkeley DB
 -----------
@@ -213,6 +205,7 @@ Hardening enables the following features:
     	scanelf -e ./bitcoin
 
     The output should contain:
+
      TYPE
     ET_DYN
 
diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index 7fe292f1f..01eea931a 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -204,3 +204,172 @@ If a set of tools is used by the build system or scripts the repository (for
 example, lcov) it is perfectly acceptable to add its files to `.gitignore`
 and commit them.
 
+Development guidelines
+============================
+
+A few non-style-related recommendations for developers, as well as points to
+pay attention to for reviewers of Bitcoin Core code.
+
+General Bitcoin Core
+----------------------
+
+- New features should be exposed on RPC first, then can be made available in the GUI
+
+  - *Rationale*: RPC allows for better automatic testing. The test suite for
+    the GUI is very limited
+
+- Make sure pulls pass Travis CI before merging
+
+  - *Rationale*: Makes sure that they pass thorough testing, and that the tester will keep passing
+     on the master branch. Otherwise all new pull requests will start failing the tests, resulting in
+     confusion and mayhem
+ 
+  - *Explanation*: If the test suite is to be updated for a change, this has to
+    be done first 
+
+Wallet
+-------
+
+- Make sure that that no crashes happen with run-time option `-disablewallet`.
+
+  - *Rationale*: In RPC code that conditionally use the wallet (such as
+    `validateaddress`) it is easy to forget that global pointer `pwalletMain`
+    can be NULL. See `qa/rpc-tests/disablewallet.py` for functional tests
+    exercising the API with `-disablewallet`
+
+- Include `db_cxx.h` (BerkeleyDB header) only when `ENABLE_WALLET` is set
+
+  - *Rationale*: Otherwise compilation of the disable-wallet build will fail in environments without BerkeleyDB
+
+General C++
+-------------
+
+- Assertions should not have side-effects
+
+  - *Rationale*: Even though the source code is set to to refuse to compile
+    with assertions disabled, having side-effects in assertions is unexpected and
+    makes the code harder to understand
+
+- If you use the .h, you must link the .cpp
+
+  - *Rationale*: Include files are the interface for the implementation file. Including one but
+      not linking the other is confusing. Please avoid that. Moving functions from
+      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.
+
+  - *Rationale*: This avoids memory and resource leaks, and ensures exception safety
+
+C++ data structures
+--------------------
+
+- Never use the std::map [] syntax when reading from a map, but instead use .find()
+
+  - *Rationale*: [] does an insert (of the default element) if the item doesn't
+    exist in the map yet. This has resulted in memory leaks in the past, as well as
+    race conditions (expecting read-read behavior). Using [] is fine for *writing* to a map
+
+- Do not compare an iterator from one data structure with an iterator of
+  another data structure (even if of the same type)
+
+  - *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`)
+
+- Vector bounds checking is only enabled in debug mode. Do not rely on it
+
+- Make sure that constructors initialize all fields. If this is skipped for a
+  good reason (i.e., optimization on the critical path), add an explicit
+  comment about this
+
+  - *Rationale*: Ensure determinism by avoiding accidental use of uninitialized
+    values. Also, static analyzers balk about this.
+
+- Use explicitly signed or unsigned `char`s, or even better `uint8_t` and
+  `int8_t`. Do not use bare `char` unless it is to pass to a third-party API.
+  This type can be signed or unsigned depending on the architecture, which can
+  lead to interoperability problems or dangerous conditions such as
+  out-of-bounds array accesses
+
+- Prefer explicit constructions over implicit ones that rely on 'magical' C++ behavior
+
+  - *Rationale*: Easier to understand what is happening, thus easier to spot mistakes, even for those
+  that are not language lawyers
+
+Strings and formatting
+------------------------
+
+- Be careful of LogPrint versus LogPrintf. LogPrint takes a 'category' argument, LogPrintf does not.
+
+  - *Rationale*: Confusion of these can result in runtime exceptions due to
+    formatting mismatch, and it is easy to get wrong because of subtly similar naming
+
+- Use std::string, avoid C string manipulation functions
+
+  - *Rationale*: C++ string handling is marginally safer, less scope for
+    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
+
+  - *Rationale*: These functions do overflow checking, and avoid pesky locale issues
+
+- For `strprintf`, `LogPrint`, `LogPrintf` formatting characters don't need size specifiers
+
+  - *Rationale*: Bitcoin Core uses tinyformat, which is type safe. Leave them out to avoid confusion
+
+Threads and synchronization
+----------------------------
+
+- Build and run tests with `-DDEBUG_LOCKORDER` to verify that no potential
+  deadlocks are introduced. As of 0.12, this is defined by default when
+  configuring with `--enable-debug`
+
+- When using `LOCK`/`TRY_LOCK` be aware that the lock exists in the context of
+  the current scope, so surround the statement and the code that needs the lock
+  with braces
+
+  OK:
+
+```c++
+{
+    TRY_LOCK(cs_vNodes, lockNodes);
+    ...
+}
+```
+
+  Wrong:
+
+```c++
+TRY_LOCK(cs_vNodes, lockNodes);
+{
+    ...
+}
+```
+
+Source code organization
+--------------------------
+
+- Implementation code should go into the `.cpp` file and not the `.h`, unless necessary due to template usage or
+  when performance due to inlining is critical
+
+  - *Rationale*: Shorter and simpler header files are easier to read, and reduce compile time
+
+- Don't import anything into the global namespace (`using namespace ...`). Use
+  fully specified types such as `std::string`.
+
+  - *Rationale*: Avoids symbol conflicts
+
+GUI
+-----
+
+- Do not display or manipulate dialogs in model code (classes `*Model`)
+
+  - *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.
diff --git a/doc/files.md b/doc/files.md
index c083bcb03..f7eca57dc 100644
--- a/doc/files.md
+++ b/doc/files.md
@@ -12,6 +12,8 @@
 * fee_estimates.dat: stores statistics used to estimate minimum transaction fees and priorities required for confirmation; since 0.10.0
 * peers.dat: peer IP address database (custom format); since 0.7.0
 * wallet.dat: personal wallet (BDB) with keys and transactions
+* .cookie: session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0
+* onion_private_key: cached Tor hidden service private key for `-listenonion`: since 0.12.0
 
 Only used in pre-0.8.0
 ---------------------
diff --git a/doc/gitian-building.md b/doc/gitian-building.md
index 00fdce82e..019e85169 100644
--- a/doc/gitian-building.md
+++ b/doc/gitian-building.md
@@ -289,11 +289,11 @@ The rest of the steps in this guide will be performed as that user.
 There is no `python-vm-builder` package in Debian, so we need to install it from source ourselves,
 
 ```bash
-wget http://archive.ubuntu.com/ubuntu/pool/universe/v/vm-builder/vm-builder_0.12.4+bzr489.orig.tar.gz
-echo "ec12e0070a007989561bfee5862c89a32c301992dd2771c4d5078ef1b3014f03  vm-builder_0.12.4+bzr489.orig.tar.gz" | sha256sum -c
+wget http://archive.ubuntu.com/ubuntu/pool/universe/v/vm-builder/vm-builder_0.12.4+bzr494.orig.tar.gz
+echo "76cbf8c52c391160b2641e7120dbade5afded713afaa6032f733a261f13e6a8e  vm-builder_0.12.4+bzr494.orig.tar.gz" | sha256sum -c
 # (verification -- must return OK)
-tar -zxvf vm-builder_0.12.4+bzr489.orig.tar.gz
-cd vm-builder-0.12.4+bzr489
+tar -zxvf vm-builder_0.12.4+bzr494.orig.tar.gz
+cd vm-builder-0.12.4+bzr494
 sudo python setup.py install
 cd ..
 ```
@@ -320,7 +320,7 @@ Execute the following as user `debian`:
 
 ```bash
 cd gitian-builder
-bin/make-base-vm --lxc --arch amd64 --suite precise
+bin/make-base-vm --lxc --arch amd64 --suite trusty
 ```
 
 There will be a lot of warnings printed during the build of the image. These can be ignored.
diff --git a/doc/reduce-traffic.md b/doc/reduce-traffic.md
new file mode 100644
index 000000000..2d86588eb
--- /dev/null
+++ b/doc/reduce-traffic.md
@@ -0,0 +1,38 @@
+Reduce Traffic
+==============
+
+Some node operators need to deal with bandwidth caps imposed by their ISPs.
+
+By default, bitcoin-core 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.
+
+Ways to reduce traffic:
+
+## 1. Use `-maxuploadtarget=<MiB per day>`
+
+A major component of the traffic is caused by serving historic blocks to other nodes
+during the initial blocks download phase (syncing up a new node).
+This option can be specified in MiB per day and is turned off by default.
+This is *not* a hard limit; only a threshold to minimize the outbound
+traffic. When the limit is about to be reached, the uploaded data is cut by no
+longer serving historic blocks (blocks older than one week).
+Keep in mind that new nodes require other nodes that are willing to serve
+historic blocks. **The recommended minimum is 144 blocks per day (max. 144MB
+per day)**
+
+Whitelisted peers will never be disconnected, although their traffic counts for
+calculating the target.
+
+## 2. Disable "listening" (`-listen=0`)
+
+Disabling listening will result in fewer nodes connected (remember the maximum of 8
+outbound peers). Fewer nodes will result in less traffic usage as you are relaying
+blocks and transactions to fewer nodes.
+
+## 3. Reduce maximum connections (`-maxconnections=<num>`)
+
+Reducing the maximum connected nodes to a minimum could be desirable if traffic
+limits are tiny. Keep in mind that bitcoin's trustless model works best if you are
+connected to a handful of nodes.
diff --git a/doc/release-notes.md b/doc/release-notes.md
index fd034743e..009baaed5 100644
--- a/doc/release-notes.md
+++ b/doc/release-notes.md
@@ -143,7 +143,7 @@ higher, it becomes mandatory for all blocks and blocks with versions less than
 
 Bitcoin Core's block templates are now for version 4 blocks only, and any
 mining software relying on its `getblocktemplate` must be updated in parallel
-to use either libblkmaker version FIXME or any version from 0.5.1 onward. If
+to use either libblkmaker version 0.4.3 or any version from 0.5.2 onward. If
 you are solo mining, this will affect you the moment you upgrade Bitcoin Core,
 which must be done prior to BIP65 achieving its 951/1001 status.  If you are
 mining with the stratum mining protocol: this does not affect you.  If you are
@@ -151,6 +151,61 @@ mining with the getblocktemplate protocol to a pool: this will affect you at
 the pool operator's discretion, which must be no later than BIP65 achieving its
 951/1001 status.
 
+Automatically use Tor hidden services
+-------------------------------------
+
+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. Bitcoin Core will also use Tor automatically to connect
+to other .onion nodes if the control socket can be successfully opened. This
+will positively affect the number of available .onion nodes and their usage.
+
+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`.
+
+Reduce upload traffic
+---------------------
+
+A major part of the outbound traffic is caused by serving historic blocks to
+other nodes in initial block download state.
+
+It is now possible to reduce the total upload traffic via the `-maxuploadtarget`
+parameter. This is *not* a hard limit but a threshold to minimize the outbound
+traffic. When the limit is about to be reached, the uploaded data is cut by not
+serving historic blocks (blocks older than one week).
+Moreover, any SPV peer is disconnected when they request a filtered block.
+
+This option can be specified in MiB per day and is turned off by default
+(`-maxuploadtarget=0`).
+The recommended minimum is 144 * MAX_BLOCK_SIZE (currently 144MB) per day.
+
+Whitelisted peers will never be disconnected, although their traffic counts for
+calculating the target.
+
+A more detailed documentation about keeping traffic low can be found in
+[/doc/reducetraffic.md](/doc/reducetraffic.md).
+
+Signature validation using libsecp256k1
+---------------------------------------
+
+ECDSA signatures inside Bitcoin transactions now use validation using
+[https://github.com/bitcoin/secp256k1](libsecp256k1) instead of OpenSSL.
+
+Depending on the platform, this means a significant speedup for raw signature
+validation speed. The advantage is largest on x86_64, where validation is over
+five times faster. In practice, this translates to a raw reindexing and new
+block validation times that are less than half of what it was before.
+
+Libsecp256k1 has undergone very extensive testing and validation.
+
+A side effect of this change is that libconsensus no longer depends on OpenSSL.
+
 0.12.0 Change log
 =================
 
diff --git a/doc/tor.md b/doc/tor.md
index 594897f89..1d35a658b 100644
--- a/doc/tor.md
+++ b/doc/tor.md
@@ -87,3 +87,20 @@ If you only want to use Tor to reach onion addresses, but not use it as a proxy
 for normal IPv4/IPv6 communication, use:
 
 	./bitcoin -onion=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover
+
+3. Automatically listen on Tor
+--------------------------------
+
+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 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`.