Merge branch 'master' of https://github.com/bitcoin/bitcoin

Conflicts:
	src/main.cpp

5 files changed, 125 insertions, 42 deletions

diff --git a/doc/README b/doc/README
index f72bca01f7..763fc415bc 100644
--- a/doc/README
+++ b/doc/README
@@ -36,7 +36,7 @@ every time you wish to send Bitcoins.  If you lose this passphrase,
 you will lose access to spend all of the bitcoins in your wallet,
 no one, not even the Bitcoin developers can recover your Bitcoins.
 This means you are responsible for your own security, store your
-password in a secure location and do not forget it.
+passphrase in a secure location and do not forget it.
 
 Remember that the encryption built into bitcoin only encrypts the
 actual keys which are required to send your bitcoins, not the full
@@ -57,7 +57,7 @@ If everything goes fine, delete the backup and enjoy your encrypted
 wallet.  Note that once you encrypt your wallet, you will never be
 able to go back to a version of the Bitcoin client older than 0.4.
 
-Keep in mind that you are always responsible for you own security.
+Keep in mind that you are always responsible for your own security.
 All it takes is a slightly more advanced wallet-stealing trojan which
 installs a keylogger to steal your wallet passphrase as you enter it
 in addition to your wallet file and you have lost all your Bitcoins.
@@ -67,6 +67,50 @@ entering your wallet passphrase in the Bitcoin client and using the
 same passphrase only as your wallet passphrase.
 
 
+Technical details of wallet encryption
+--------------------------------------
+Wallet encryption uses AES-256-CBC to encrypt only the private keys
+that are held in a wallet.  The keys are encrypted with a master key
+which is entirely random.  This master key is then encrypted with
+AES-256-CBC with a key derived from the passphrase using SHA512 and
+OpenSSL's EVP_BytesToKey and a dynamic number of rounds determined by
+the speed of the machine which does the initial encryption (and is
+updated based on the speed of a computer which does a subsequent
+passphrase change).  Although the underlying code supports multiple
+encrypted copies of the same master key (and thus multiple passphrases)
+the client does not yet have a method to add additional passphrases.
+
+At runtime, the client loads the wallet as it normally would, however
+the keystore stores the keys in encrypted form.  When the passphrase
+is required (to top up keypool or send coins) it will either be queried
+by a GUI prompt, or must first be entered with the walletpassphrase
+RPC command.  This will change the wallet to "unlocked" state where the
+unencrypted master key is stored in memory (in the case of GUI, only for
+long enough to complete the requested operation, in RPC, for as long as
+is specified by the second parameter to walletpassphrase).  The wallet is
+then locked (or can be manually locked using the walletlock RPC command)
+and the unencrypted master key is removed from memory.
+
+Implementation details of wallet encryption
+-------------------------------------------
+When the wallet is locked, calls to sendtoaddress, sendfrom, sendmany,
+and keypoolrefill will return Error -13: "Error: Please enter the wallet 
+passphrase with walletpassphrase first."
+
+When the wallet is unlocked, calls to walletpassphrase will fail.
+
+When a wallet is encrypted, the passphrase is required to top up the
+keypool, thus, if the passphrase is rarely entered, it is possible that
+keypool might run out.  In this case, the default key will be used as the
+target for payouts for mining, and calls to getnewaddress and getaccount
+address will return an error.  In order to prevent such cases, the keypool
+is automatically refilled when walletpassphrase is called with a correct
+passphrase and when topupkeypool is called (while the wallet is unlocked).
+Note that the keypool continues to be topped up on various occasions when
+a new key from pool is used and the wallet is unlocked (or unencrypted).
+
+
+
 See the documentation at the bitcoin wiki:
   https://en.bitcoin.it/wiki/Main_Page
 
diff --git a/doc/build-msw.txt b/doc/build-msw.txt
index 1911008d1f..d08e3a23b7 100644
--- a/doc/build-msw.txt
+++ b/doc/build-msw.txt
@@ -27,11 +27,11 @@ Dependencies
 Libraries you need to download separately and build:
 
                 default path               download
-wxWidgets       \wxwidgets-2.9.1-mgw       http://www.wxwidgets.org/downloads/
+wxWidgets       \wxwidgets-2.9.2-mgw       http://www.wxwidgets.org/downloads/
 OpenSSL         \openssl-1.0.0d-mgw        http://www.openssl.org/source/
-Berkeley DB     \db-4.7.25.NC-mgw          http://www.oracle.com/technology/software/products/berkeley-db/index.html
-Boost           \boost-1.43.0-mgw          http://www.boost.org/users/download/
-miniupnpc       \upnpc-exe-win32-20110215  http://miniupnp.tuxfamily.org/files/
+Berkeley DB     \db-4.8.30.NC-mgw          http://www.oracle.com/technology/software/products/berkeley-db/index.html
+Boost           \boost-1.47.0-mgw          http://www.boost.org/users/download/
+miniupnpc       \miniupnpc-1.6-mgw         http://miniupnp.tuxfamily.org/files/
 
 Their licenses:
 wxWidgets      LGPL 2.1 with very liberal exceptions
@@ -41,11 +41,11 @@ Boost          MIT-like license
 miniupnpc      New (3-clause) BSD license
 
 Versions used in this release:
-wxWidgets    2.9.1
+wxWidgets    2.9.2
 OpenSSL      1.0.0d
-Berkeley DB  4.7.25.NC
-Boost        1.43.0
-miniupnpc    1.5-20110215
+Berkeley DB  4.8.30.NC
+Boost        1.47.0
+miniupnpc    1.6
 
 
 Notes
@@ -57,7 +57,7 @@ classes that do the rote work of constructing all the UI elements.
 wxWidgets
 ---------
 DOS shell:
-cd \wxWidgets-2.9.1-mgw\build\msw
+cd \wxWidgets-2.9.2-mgw\build\msw
 mingw32-make -f makefile.gcc
 
 OpenSSL
@@ -73,30 +73,26 @@ make
 Berkeley DB
 -----------
 MSYS shell:
-cd /c/db-4.7.25.NC-mgw/build_unix
+cd /c/db-4.8.30.NC-mgw/build_unix
 sh ../dist/configure --enable-mingw --enable-cxx
 make
 
-
 Boost
 -----
 DOS prompt:
 downloaded boost jam 3.1.18
-cd \boost-1.43.0-mgw
+cd \boost-1.47.0-mgw
 bjam toolset=gcc --build-type=complete stage
 
-Note:
-building with boost 1.45.0 failed because of boost ticket 4614, 4258
-builds fine with boost 1.43.0
-
 MiniUPnPc
 ---------
-Building miniupnpc failed on Windows Server 2003, thus it is expected that a binary copy will be used.
-See http://miniupnp.tuxfamily.org/forum/viewtopic.php?t=642
 UPnP support is optional, make with USE_UPNP= to disable it.
 
-Get upnpc-exe-win32-20110215.zip and unzip it to \upnpc-exe-win32-20110215
-Get miniupnpc-1.5.20110215.tar.gz and copy *.h to \upnpc-exe-win32-20110215\miniupnpc
+MSYS shell:
+cd /c/miniupnpc-1.6-mgw
+make -f Makefile.mingw
+mkdir miniupnpc
+cp *.h miniupnpc/
 
 Bitcoin
 -------
diff --git a/doc/build-osx.txt b/doc/build-osx.txt
index ddf025003b..52d876d82b 100644
--- a/doc/build-osx.txt
+++ b/doc/build-osx.txt
@@ -135,18 +135,18 @@ The process for miniupnpc (optional) is similar to that of OpenSSL.
 Download from http://miniupnp.tuxfamily.org/files/.
 
 cd ~/bitcoin/deps
-tar xvf ~/Downloads/miniupnpc-1.5.tar
-mv miniupnpc-1.5 miniupnpc-1.5-x86_64
-tar xvf ~/Downloads/miniupnpc-1.5.tar
-mv miniupnpc-1.5 miniupnpc-1.5-i386
+tar xvf ~/Downloads/miniupnpc-1.6.tar
+mv miniupnpc-1.6 miniupnpc-1.6-x86_64
+tar xvf ~/Downloads/miniupnpc-1.6.tar
+mv miniupnpc-1.6 miniupnpc-1.6-i386
 # build x86_64 (64 bit intel) binary
-cd miniupnpc-1.5-x86_64
+cd miniupnpc-1.6-x86_64
 export CFLAGS="-arch x86_64"
 export LDFLAGS="-arch x86_64"
 export PREFIX="/Users/macuser/bitcoin/deps"
 make && make install
 # build i386 (32 bit intel) binary
-cd miniupnpc-1.5-i386
+cd miniupnpc-1.6-i386
 export CFLAGS="-arch i386"
 export LDFLAGS="-arch i386"
 export PREFIX="/Users/macuser/bitcoin/deps"
@@ -154,7 +154,7 @@ make
 
 # combine the libs
 cd ~/bitcoin/deps
-lipo -arch i386 miniupnpc-1.5-i386/libminiupnpc.a -arch x86_64 miniupnpc-1.5-x86_64/libminiupnpc.a -o lib/libminiupnpc.a -create
+lipo -arch i386 miniupnpc-1.6-i386/libminiupnpc.a -arch x86_64 miniupnpc-1.6-x86_64/libminiupnpc.a -o lib/libminiupnpc.a -create
 
 Verify your binaries
 
@@ -175,8 +175,8 @@ Berkeley DB
 Download from http://freshmeat.net/projects/berkeleydb/
 
 cd ~/bitcoin/deps
-tar xvf ~/Downloads/db-4.8.26.tar
-cd db-4.8.26/build_unix
+tar xvf ~/Downloads/db-4.8.30.tar
+cd db-4.8.30/build_unix
 ../dist/configure --prefix=/Users/macosuser/bitcoin/deps --enable-cxx && make && make install
 
 
diff --git a/doc/build-unix.txt b/doc/build-unix.txt
index 0c4e88e523..8f0c568eda 100644
--- a/doc/build-unix.txt
+++ b/doc/build-unix.txt
@@ -25,8 +25,8 @@ Dependencies
 sudo apt-get install build-essential
 sudo apt-get install libgtk2.0-dev
 sudo apt-get install libssl-dev
-sudo apt-get install libdb4.7-dev
-sudo apt-get install libdb4.7++-dev
+sudo apt-get install libdb4.8-dev
+sudo apt-get install libdb4.8++-dev
 Boost 1.40+: sudo apt-get install libboost-all-dev
 or Boost 1.37: sudo apt-get install libboost1.37-dev
 
@@ -55,10 +55,10 @@ miniupnpc      New (3-clause) BSD license
 Versions used in this release:
 GCC          4.3.3
 OpenSSL      0.9.8g
-wxWidgets    2.9.0
-Berkeley DB  4.7.25.NC
+wxWidgets    2.9.2
+Berkeley DB  4.8.30.NC
 Boost        1.37
-miniupnpc    1.5
+miniupnpc    1.6
 
 
 Notes
@@ -74,8 +74,8 @@ symbols, which reduces the executable size by about 90%.
 wxWidgets
 ---------
 cd /usr/local
-tar -xzvf wxWidgets-2.9.0.tar.gz
-cd wxWidgets-2.9.0
+tar -xzvf wxWidgets-2.9.2.tar.gz
+cd wxWidgets-2.9.2
 mkdir buildgtk
 cd buildgtk
 ../configure --with-gtk --enable-debug --disable-shared --enable-monolithic --without-libpng --disable-svg
@@ -87,8 +87,8 @@ ldconfig
 
 miniupnpc
 ---------
-tar -xzvf miniupnpc-1.5.tar.gz
-cd miniupnpc-1.5
+tar -xzvf miniupnpc-1.6.tar.gz
+cd miniupnpc-1.6
 make
 sudo su
 make install
@@ -96,8 +96,7 @@ make install
 
 Berkeley DB
 -----------
-You need Berkeley DB 4.7.  Don't use 4.8, the database/log0000* files
-are incompatible.  If you have to build Berkeley DB yourself:
+You need Berkeley DB 4.8.  If you have to build Berkeley DB yourself:
 ../dist/configure --enable-cxx
 make
 
diff --git a/doc/coding.txt b/doc/coding.txt
index 4707476697..ec31ccded2 100644
--- a/doc/coding.txt
+++ b/doc/coding.txt
@@ -39,3 +39,47 @@ v       vector or similar list objects
 map     map or multimap

 set     set or multiset

 bn      CBigNum

+

+-------------------------

+Locking/mutex usage notes

+

+The code is multi-threaded, and uses mutexes and the CRITICAL_BLOCK/TRY_CRITICAL_BLOCK macros to protect data structures.

+

+Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main and then cs_wallet, while thread 2 locks them in the opposite order: result, deadlock as each waits for the other to release its lock) are a problem. Compile with -DDEBUG_LOCKORDER to get lock order inconsistencies reported in the debug.log file.

+

+Re-architecting the core code so there are better-defined interfaces between the various components is a goal, with any necessary locking done by the components (e.g. see the self-contained CKeyStore class and its cs_KeyStore lock for example).

+

+-------

+Threads

+

+StartNode : Starts other threads.

+

+ThreadGetMyExternalIP : Determines outside-the-firewall IP address, sends addr message to connected peers when it determines it.

+

+ThreadIRCSeed : Joins IRC bootstrapping channel, watching for new peers and advertising this node's IP address.

+

+ThreadSocketHandler : Sends/Receives data from peers on port 8333.

+

+ThreadMessageHandler : Higher-level message handling (sending and receiving).

+

+ThreadOpenConnections : Initiates new connections to peers.

+

+ThreadTopUpKeyPool : replenishes the keystore's keypool.

+

+ThreadCleanWalletPassphrase : re-locks an encrypted wallet after user has unlocked it for a period of time.

+

+SendingDialogStartTransfer : used by pay-via-ip-address code (obsolete)

+

+ThreadDelayedRepaint : repaint the gui 

+

+ThreadFlushWalletDB : Close the wallet.dat file if it hasn't been used in 500ms.

+

+ThreadRPCServer : Remote procedure call handler, listens on port 8332 for connections and services them.

+

+ThreadBitcoinMiner : Generates bitcoins

+

+ThreadMapPort : Universal plug-and-play startup/shutdown

+

+Shutdown : Does an orderly shutdown of everything

+

+ExitTimeout : Windows-only, sleeps 5 seconds then exits application