diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 2 | ||||
| -rw-r--r-- | doc/bips.md | 1 | ||||
| -rw-r--r-- | doc/build-unix.md | 8 | ||||
| -rw-r--r-- | doc/developer-notes.md | 169 | ||||
| -rw-r--r-- | doc/gitian-building.md | 2 | ||||
| -rw-r--r-- | doc/reduce-traffic.md (renamed from doc/reducetraffic.md) | 7 | ||||
| -rw-r--r-- | doc/release-notes.md | 54 |
7 files changed, 227 insertions, 16 deletions
diff --git a/doc/README.md b/doc/README.md index 0594d20dd4..f6df28a89b 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/bips.md b/doc/bips.md index c780e2dde0..962b216123 100644 --- a/doc/bips.md +++ b/doc/bips.md @@ -18,3 +18,4 @@ BIPs that are implemented by Bitcoin Core (up-to-date up to **v0.12.0**): * [`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 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 111`](https://github.com/bitcoin/bips/blob/master/bip-0111.mediawiki): `NODE_BLOOM` service bit added, but only enforced for peer versions `>=70011` as of **v0.12.0** ([PR #6579](https://github.com/bitcoin/bitcoin/pull/6579)). +* [`BIP 130`](https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki): direct headers announcement is negotiated with peer versions `>=70012` as of **v0.12.0** ([PR 6494](https://github.com/bitcoin/bitcoin/pull/6494)). diff --git a/doc/build-unix.md b/doc/build-unix.md index e1f2ce54d3..159a140608 100644 --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -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 ----------- diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 7fe292f1f8..01eea931ad 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/gitian-building.md b/doc/gitian-building.md index 43de87d4ba..019e851696 100644 --- a/doc/gitian-building.md +++ b/doc/gitian-building.md @@ -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/reducetraffic.md b/doc/reduce-traffic.md index a79571913a..2d86588eb2 100644 --- a/doc/reducetraffic.md +++ b/doc/reduce-traffic.md @@ -1,7 +1,7 @@ Reduce Traffic ============== -Some node operators need to deal with bandwith caps imposed by their ISPs. +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. @@ -22,6 +22,9 @@ 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 @@ -30,6 +33,6 @@ blocks and transactions to fewer nodes. ## 3. Reduce maximum connections (`-maxconnections=<num>`) -Reducing the maximum connected nodes to a miniumum could be desirable if traffic +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 2e9cc16940..96c830d177 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -151,8 +151,8 @@ 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 listen on Tor ----------------------------- +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. @@ -160,8 +160,9 @@ 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. +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`, @@ -184,9 +185,54 @@ 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. + +Direct headers announcement (BIP 130) +------------------------------------- + +Between compatible peers, BIP 130 direct headers announcement is used. This +means that blocks are advertized by announcing their headers directly, instead +of just announcing the hash. In a reorganization, all new headers are sent, +instead of just the new tip. This can often prevent an extra roundtrip before +the actual block is downloaded. + +Negative confirmations and conflict detection +--------------------------------------------- + +The wallet will now report a negative number for confirmations that indicates +how deep in the block chain the conflict is found. For example, if a transaction +A has 5 confirmations and spends the same input as a wallet transaction B, B +will be reported as having -5 confirmations. If another wallet transaction C +spends an output from B, it will also be reported as having -5 confirmations. +To detect conflicts with historical transactions in the chain a one-time +`-rescan` may be needed. + +Unlike earlier versions, unconfirmed but non-conflicting transactions will never +get a negative confirmation count. They are not treated as spendable unless +they're coming from ourself (change) and accepted into our local mempool, +however. The new "trusted" field in the `listtransactions` RPC output +indicates whether outputs of an unconfirmed transaction are considered +spendable. + 0.12.0 Change log ================= |