Bitcoin Wiki - User contributions [en]

BIP 0032

2013-07-05T17:26:34Z

Grau: /* Implementations */

{{bip}}

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)
* [25 May 2013] Added test vectors

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Accepted
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes [[Deterministic Wallet|hierarchical determinstic wallets]] (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall denote the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as (K, c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: private and public.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar, cpar), i) → (ki, ci), defined for both private and public derivation.
* CKD'((Kpar, cpar), i) → (Ki, ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n or ki = 0, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n or Ki is the point at infinity, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

==Test Vectors==

For more detailed information about these (such as intermediate values and other representations), see [[BIP_0032_TestVectors]]

Test vector 1

Master (hex): 000102030405060708090a0b0c0d0e0f
* [Chain m]
* ext pub: xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8
* ext prv: xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi
* [Chain m/0']
* ext pub: xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
* ext prv: xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
* [Chain m/0'/1]
* ext pub: xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47sSikHjJf3UFHKkNAWbWMiGj7Wf5uMash7SyYq527Hqck2AxYysAA7xmALppuCkwQ
* ext prv: xprv9wTYmMFdV23N2TdNG573QoEsfRrWKQgWeibmLntzniatZvR9BmLnvSxqu53Kw1UmYPxLgboyZQaXwTCg8MSY3H2EU4pWcQDnRnrVA1xe8fs
* [Chain m/0'/1/2']
* ext pub: xpub6D4BDPcP2GT577Vvch3R8wDkScZWzQzMMUm3PWbmWvVJrZwQY4VUNgqFJPMM3No2dFDFGTsxxpG5uJh7n7epu4trkrX7x7DogT5Uv6fcLW5
* ext prv: xprv9z4pot5VBttmtdRTWfWQmoH1taj2axGVzFqSb8C9xaxKymcFzXBDptWmT7FwuEzG3ryjH4ktypQSAewRiNMjANTtpgP4mLTj34bhnZX7UiM
* [Chain m/0'/1/2'/2]
* ext pub: xpub6FHa3pjLCk84BayeJxFW2SP4XRrFd1JYnxeLeU8EqN3vDfZmbqBqaGJAyiLjTAwm6ZLRQUMv1ZACTj37sR62cfN7fe5JnJ7dh8zL4fiyLHV
* ext prv: xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334
* [Chain m/0'/1/2'/2/1000000000]
* ext pub: xpub6H1LXWLaKsWFhvm6RVpEL9P4KfRZSW7abD2ttkWP3SSQvnyA8FSVqNTEcYFgJS2UaFcxupHiYkro49S8yGasTvXEYBVPamhGW6cFJodrTHy
* ext prv: xprvA41z7zogVVwxVSgdKUHDy1SKmdb533PjDz7J6N6mV6uS3ze1ai8FHa8kmHScGpWmj4WggLyQjgPie1rFSruoUihUZREPSL39UNdE3BBDu76

Test vector 2

Master (hex): fffcf9f6f3f0edeae7e4e1dedbd8d5d2cfccc9c6c3c0bdbab7b4b1aeaba8a5a29f9c999693908d8a8784817e7b7875726f6c696663605d5a5754514e4b484542
* [Chain m]
* ext pub: xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB
* ext prv: xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U
* [Chain m/0]
* ext pub: xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH
* ext prv: xprv9vHkqa6EV4sPZHYqZznhT2NPtPCjKuDKGY38FBWLvgaDx45zo9WQRUT3dKYnjwih2yJD9mkrocEZXo1ex8G81dwSM1fwqWpWkeS3v86pgKt
* [Chain m/0/2147483647']
* ext pub: xpub6ASAVgeehLbnwdqV6UKMHVzgqAG8Gr6riv3Fxxpj8ksbH9ebxaEyBLZ85ySDhKiLDBrQSARLq1uNRts8RuJiHjaDMBU4Zn9h8LZNnBC5y4a
* ext prv: xprv9wSp6B7kry3Vj9m1zSnLvN3xH8RdsPP1Mh7fAaR7aRLcQMKTR2vidYEeEg2mUCTAwCd6vnxVrcjfy2kRgVsFawNzmjuHc2YmYRmagcEPdU9
* [Chain m/0/2147483647'/1]
* ext pub: xpub6DF8uhdarytz3FWdA8TvFSvvAh8dP3283MY7p2V4SeE2wyWmG5mg5EwVvmdMVCQcoNJxGoWaU9DCWh89LojfZ537wTfunKau47EL2dhHKon
* ext prv: xprv9zFnWC6h2cLgpmSA46vutJzBcfJ8yaJGg8cX1e5StJh45BBciYTRXSd25UEPVuesF9yog62tGAQtHjXajPPdbRCHuWS6T8XA2ECKADdw4Ef
* [Chain m/0/2147483647'/1/2147483646']
* ext pub: xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL
* ext prv: xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc
* [Chain m/0/2147483647'/1/2147483646'/2]
* ext pub: xpub6FnCn6nSzZAw5Tw7cgR9bi15UV96gLZhjDstkXXxvCLsUXBGXPdSnLFbdpq8p9HmGsApME5hQTZ3emM2rnY5agb9rXpVGyy3bdW6EEgAtqt
* ext prv: xprvA2nrNbFZABcdryreWet9Ea4LvTJcGsqrMzxHx98MMrotbir7yrKCEXw7nadnHM8Dq38EGfSh6dqA9QWTyefMLEcBYJUuekgW4BYPJcr9E7j

==Implementations==

A Python implementation is available at https://github.com/richardkiss/pycoin

A Java implementation is available at https://github.com/bitsofproof/supernode/blob/1.1/api/src/main/java/com/bitsofproof/supernode/api/ExtendedKey.java

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-07-05T17:26:10Z

Grau: /* Implementations */

{{bip}}

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)
* [25 May 2013] Added test vectors

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Accepted
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes [[Deterministic Wallet|hierarchical determinstic wallets]] (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall denote the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as (K, c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: private and public.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar, cpar), i) → (ki, ci), defined for both private and public derivation.
* CKD'((Kpar, cpar), i) → (Ki, ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n or ki = 0, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n or Ki is the point at infinity, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

==Test Vectors==

For more detailed information about these (such as intermediate values and other representations), see [[BIP_0032_TestVectors]]

Test vector 1

Master (hex): 000102030405060708090a0b0c0d0e0f
* [Chain m]
* ext pub: xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8
* ext prv: xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi
* [Chain m/0']
* ext pub: xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
* ext prv: xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
* [Chain m/0'/1]
* ext pub: xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47sSikHjJf3UFHKkNAWbWMiGj7Wf5uMash7SyYq527Hqck2AxYysAA7xmALppuCkwQ
* ext prv: xprv9wTYmMFdV23N2TdNG573QoEsfRrWKQgWeibmLntzniatZvR9BmLnvSxqu53Kw1UmYPxLgboyZQaXwTCg8MSY3H2EU4pWcQDnRnrVA1xe8fs
* [Chain m/0'/1/2']
* ext pub: xpub6D4BDPcP2GT577Vvch3R8wDkScZWzQzMMUm3PWbmWvVJrZwQY4VUNgqFJPMM3No2dFDFGTsxxpG5uJh7n7epu4trkrX7x7DogT5Uv6fcLW5
* ext prv: xprv9z4pot5VBttmtdRTWfWQmoH1taj2axGVzFqSb8C9xaxKymcFzXBDptWmT7FwuEzG3ryjH4ktypQSAewRiNMjANTtpgP4mLTj34bhnZX7UiM
* [Chain m/0'/1/2'/2]
* ext pub: xpub6FHa3pjLCk84BayeJxFW2SP4XRrFd1JYnxeLeU8EqN3vDfZmbqBqaGJAyiLjTAwm6ZLRQUMv1ZACTj37sR62cfN7fe5JnJ7dh8zL4fiyLHV
* ext prv: xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334
* [Chain m/0'/1/2'/2/1000000000]
* ext pub: xpub6H1LXWLaKsWFhvm6RVpEL9P4KfRZSW7abD2ttkWP3SSQvnyA8FSVqNTEcYFgJS2UaFcxupHiYkro49S8yGasTvXEYBVPamhGW6cFJodrTHy
* ext prv: xprvA41z7zogVVwxVSgdKUHDy1SKmdb533PjDz7J6N6mV6uS3ze1ai8FHa8kmHScGpWmj4WggLyQjgPie1rFSruoUihUZREPSL39UNdE3BBDu76

Test vector 2

Master (hex): fffcf9f6f3f0edeae7e4e1dedbd8d5d2cfccc9c6c3c0bdbab7b4b1aeaba8a5a29f9c999693908d8a8784817e7b7875726f6c696663605d5a5754514e4b484542
* [Chain m]
* ext pub: xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB
* ext prv: xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U
* [Chain m/0]
* ext pub: xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH
* ext prv: xprv9vHkqa6EV4sPZHYqZznhT2NPtPCjKuDKGY38FBWLvgaDx45zo9WQRUT3dKYnjwih2yJD9mkrocEZXo1ex8G81dwSM1fwqWpWkeS3v86pgKt
* [Chain m/0/2147483647']
* ext pub: xpub6ASAVgeehLbnwdqV6UKMHVzgqAG8Gr6riv3Fxxpj8ksbH9ebxaEyBLZ85ySDhKiLDBrQSARLq1uNRts8RuJiHjaDMBU4Zn9h8LZNnBC5y4a
* ext prv: xprv9wSp6B7kry3Vj9m1zSnLvN3xH8RdsPP1Mh7fAaR7aRLcQMKTR2vidYEeEg2mUCTAwCd6vnxVrcjfy2kRgVsFawNzmjuHc2YmYRmagcEPdU9
* [Chain m/0/2147483647'/1]
* ext pub: xpub6DF8uhdarytz3FWdA8TvFSvvAh8dP3283MY7p2V4SeE2wyWmG5mg5EwVvmdMVCQcoNJxGoWaU9DCWh89LojfZ537wTfunKau47EL2dhHKon
* ext prv: xprv9zFnWC6h2cLgpmSA46vutJzBcfJ8yaJGg8cX1e5StJh45BBciYTRXSd25UEPVuesF9yog62tGAQtHjXajPPdbRCHuWS6T8XA2ECKADdw4Ef
* [Chain m/0/2147483647'/1/2147483646']
* ext pub: xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL
* ext prv: xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc
* [Chain m/0/2147483647'/1/2147483646'/2]
* ext pub: xpub6FnCn6nSzZAw5Tw7cgR9bi15UV96gLZhjDstkXXxvCLsUXBGXPdSnLFbdpq8p9HmGsApME5hQTZ3emM2rnY5agb9rXpVGyy3bdW6EEgAtqt
* ext prv: xprvA2nrNbFZABcdryreWet9Ea4LvTJcGsqrMzxHx98MMrotbir7yrKCEXw7nadnHM8Dq38EGfSh6dqA9QWTyefMLEcBYJUuekgW4BYPJcr9E7j

==Implementations==

A Python implementation is available at https://github.com/richardkiss/pycoin

A Java implementation is available at http https://github.com/bitsofproof/supernode/blob/1.1/api/src/main/java/com/bitsofproof/supernode/api/ExtendedKey.java

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-07-05T17:25:54Z

Grau: /* Implementations */

{{bip}}

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)
* [25 May 2013] Added test vectors

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Accepted
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes [[Deterministic Wallet|hierarchical determinstic wallets]] (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall denote the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as (K, c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: private and public.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar, cpar), i) → (ki, ci), defined for both private and public derivation.
* CKD'((Kpar, cpar), i) → (Ki, ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n or ki = 0, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n or Ki is the point at infinity, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

==Test Vectors==

For more detailed information about these (such as intermediate values and other representations), see [[BIP_0032_TestVectors]]

Test vector 1

Master (hex): 000102030405060708090a0b0c0d0e0f
* [Chain m]
* ext pub: xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8
* ext prv: xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi
* [Chain m/0']
* ext pub: xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
* ext prv: xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
* [Chain m/0'/1]
* ext pub: xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47sSikHjJf3UFHKkNAWbWMiGj7Wf5uMash7SyYq527Hqck2AxYysAA7xmALppuCkwQ
* ext prv: xprv9wTYmMFdV23N2TdNG573QoEsfRrWKQgWeibmLntzniatZvR9BmLnvSxqu53Kw1UmYPxLgboyZQaXwTCg8MSY3H2EU4pWcQDnRnrVA1xe8fs
* [Chain m/0'/1/2']
* ext pub: xpub6D4BDPcP2GT577Vvch3R8wDkScZWzQzMMUm3PWbmWvVJrZwQY4VUNgqFJPMM3No2dFDFGTsxxpG5uJh7n7epu4trkrX7x7DogT5Uv6fcLW5
* ext prv: xprv9z4pot5VBttmtdRTWfWQmoH1taj2axGVzFqSb8C9xaxKymcFzXBDptWmT7FwuEzG3ryjH4ktypQSAewRiNMjANTtpgP4mLTj34bhnZX7UiM
* [Chain m/0'/1/2'/2]
* ext pub: xpub6FHa3pjLCk84BayeJxFW2SP4XRrFd1JYnxeLeU8EqN3vDfZmbqBqaGJAyiLjTAwm6ZLRQUMv1ZACTj37sR62cfN7fe5JnJ7dh8zL4fiyLHV
* ext prv: xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334
* [Chain m/0'/1/2'/2/1000000000]
* ext pub: xpub6H1LXWLaKsWFhvm6RVpEL9P4KfRZSW7abD2ttkWP3SSQvnyA8FSVqNTEcYFgJS2UaFcxupHiYkro49S8yGasTvXEYBVPamhGW6cFJodrTHy
* ext prv: xprvA41z7zogVVwxVSgdKUHDy1SKmdb533PjDz7J6N6mV6uS3ze1ai8FHa8kmHScGpWmj4WggLyQjgPie1rFSruoUihUZREPSL39UNdE3BBDu76

Test vector 2

Master (hex): fffcf9f6f3f0edeae7e4e1dedbd8d5d2cfccc9c6c3c0bdbab7b4b1aeaba8a5a29f9c999693908d8a8784817e7b7875726f6c696663605d5a5754514e4b484542
* [Chain m]
* ext pub: xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB
* ext prv: xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U
* [Chain m/0]
* ext pub: xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH
* ext prv: xprv9vHkqa6EV4sPZHYqZznhT2NPtPCjKuDKGY38FBWLvgaDx45zo9WQRUT3dKYnjwih2yJD9mkrocEZXo1ex8G81dwSM1fwqWpWkeS3v86pgKt
* [Chain m/0/2147483647']
* ext pub: xpub6ASAVgeehLbnwdqV6UKMHVzgqAG8Gr6riv3Fxxpj8ksbH9ebxaEyBLZ85ySDhKiLDBrQSARLq1uNRts8RuJiHjaDMBU4Zn9h8LZNnBC5y4a
* ext prv: xprv9wSp6B7kry3Vj9m1zSnLvN3xH8RdsPP1Mh7fAaR7aRLcQMKTR2vidYEeEg2mUCTAwCd6vnxVrcjfy2kRgVsFawNzmjuHc2YmYRmagcEPdU9
* [Chain m/0/2147483647'/1]
* ext pub: xpub6DF8uhdarytz3FWdA8TvFSvvAh8dP3283MY7p2V4SeE2wyWmG5mg5EwVvmdMVCQcoNJxGoWaU9DCWh89LojfZ537wTfunKau47EL2dhHKon
* ext prv: xprv9zFnWC6h2cLgpmSA46vutJzBcfJ8yaJGg8cX1e5StJh45BBciYTRXSd25UEPVuesF9yog62tGAQtHjXajPPdbRCHuWS6T8XA2ECKADdw4Ef
* [Chain m/0/2147483647'/1/2147483646']
* ext pub: xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL
* ext prv: xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc
* [Chain m/0/2147483647'/1/2147483646'/2]
* ext pub: xpub6FnCn6nSzZAw5Tw7cgR9bi15UV96gLZhjDstkXXxvCLsUXBGXPdSnLFbdpq8p9HmGsApME5hQTZ3emM2rnY5agb9rXpVGyy3bdW6EEgAtqt
* ext prv: xprvA2nrNbFZABcdryreWet9Ea4LvTJcGsqrMzxHx98MMrotbir7yrKCEXw7nadnHM8Dq38EGfSh6dqA9QWTyefMLEcBYJUuekgW4BYPJcr9E7j

==Implementations==

A Python implementation is available at https://github.com/richardkiss/pycoin
A Java implementation is available at http https://github.com/bitsofproof/supernode/blob/1.1/api/src/main/java/com/bitsofproof/supernode/api/ExtendedKey.java

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

Software versions

2013-05-28T06:27:07Z

Grau:

{| class="wikitable"
! Software !! Vulnerable !! Old !! Current
|-
| Bitcoin-Qt bitcoind || * - 0.4.9rc1 0.5.0rc1 - 0.5.8rc1 0.6.0rc1 - 0.6.5rc1 0.7.0rc1 - 0.7.3rc1 0.8.0rc1 - 0.8.0 || 0.4.9rc2 0.5.8rc2 0.6.5rc2 0.7.3rc2   || 0.4.9rc2 0.5.8rc3 0.6.5rc3 0.7.3rc3 0.8.1
|-
| Bits of Proof || || 0.9|| 1.0
|}

Software

2013-05-28T06:22:53Z

Grau: /* Enterprise server */

List of Bitcoin-related software. See also [[:Category:Software|Category:Software]].

Be sure to keep on top of the latest [[CVEs|security vulnerabilities]]!

==Bitcoin clients==
===Bitcoin clients===
::''Main article and feature comparison: [[Clients]]''
*[[Bitcoin-Qt]] - C++/Qt based tabbed UI. Linux/MacOSX/Windows. Full-featured [[Thin Client Security|thick client]] that downloads the entire [[block chain]], using code from the original Bitcoin client.
*[[bitcoind]] - GUI-less version of the original Bitcoin client, providing a [[API reference (JSON-RPC)|JSON-RPC]] interface
*[[MultiBit]] - lightweight [[Thin Client Security|thin client]] for Windows, MacOS and Linux with support for opening multiple wallets simultaneously
*[[Electrum]] - a "blazing fast, open-source, multi-OS Bitcoin client/wallet with a very active community" - also a [[Thin Client Security|thin client]].
*[[Bitcoin-js-remote]] - JavaScript RPC client, support for QR codes
*[https://github.com/TheSeven/Bitcoin-WebUI Bitcoin WebUI] - JavaScript RPC client
*[https://github.com/zamgo/bitcoin-webskin Bitcoin Webskin] - PHP web interface to bitcoind and namecoind
*[https://bitcointalk.org/index.php?topic=50721.0 subvertx] - command line bitcoin tools
*[[Bitcoiner]] - Java RPC client (Android)
*[[Armory]] - Python-based client currently an alpha-level release, the beta version is being crowdfunded
*[[Spesmilo]] - Python/PySide RPC client (abandoned)
*[[Gocoin]] - GUI-less client node written in Go language, with a separate cold deterministic wallet app.

====Frontends to eWallet====
*[[BitPay]] - Android application
*[https://blockchain.info/wallet Blockchain] - Javascript bitcoin client with client side encryption.

====Experimental====
*[[Freecoin]] - C++ client, supports alternative currencies like [[Beertoken]]
*[[BitDroid]] - Java client
*[[Bitdollar]] - C++/Qt client, unstable beta version

===Libraries===
*[https://bitcointalk.org/index.php?topic=30646.0 libbitcoin]
*[[BitCoinJ]] - Java client library, early development stage but used in live projects already
*[[BCCAPI]] (Bitcoin Client API) - a java library designed for making secure light-weight bitcoin clients.

==Bitcoin Trade Data==
*[[Bitcoin Charts]] – Prices, volume, and extensive charting on virtually all Bitcoin markets.
*[[MtGox Live]] - An innovative chart showing a live feed of [[MtGox]] trades and market depth. (Must Use Chrome)
*[http://btccharts.com BTCCharts] - An innovative chart showing a live feed of multiple markets, currencies and timeframes.
*[http://BitcoinExchangeRate.org BitcoinExchangeRate.org] - Bitcoin and USD converter with convenient URL scheme and Auto-updating Portfolio Spreadsheet.
*[[Bitcoin Sentiment Index]] - A financial index that collects and disseminates sentiment data about bitcoin.
*[[Preev]] - Bitcoin converter with live exchange rates.
*[[Skami]] - Bitcoin Market Exchange comparison charts.
*[[BitcoinSentiment]] - Crowdvoting site offering means of voting and viewing voters sentiment towards bitcoin.

==Bitcoin software==

===Web interfaces for merchants===
*[[Bitcoin Evolution]] - Non wallet-based Buy Now button to insert into websites (handles sales tracking; client must be used for actual transaction)
*[[BitPay]] - Buy Now buttons, Checkout posts/callbacks, Mobile Checkout, JSON API
*[[Btceconomy]] - a JavaScript widget listing items for sale
*[[Javascript Bitcoin Converter]] - currency conversion
*[[WalletBit]] - Easy JavaScript Buy Now buttons, Instant Payment Notification, Application Programming Interface (JSON API), Mobile Checkout, QR-Code
*[[BitUtils Merchant]] - Customizable Buy Now buttons with hosted checkout interface. No programming skills required to set up.

===Shopping Cart Integration in eCommerce-Systems===
*[[Zen Cart Bitcoin Payment Module]] - a payment module that interacts with bitcoind for the Zen Cart eCommerce shopping chart.
*[[Karsha Shopping Cart Interface]] - is a mobile payment-interface which enables its users to accept payments.
*[[Bitcoin-Cash]] - an easy to use payment module for xt:Commerce
*[[BitPay]] - bitcoin plugins for Magento, Opencart, Zencart, PHP, JSON API
*[[WalletBit]] - Plugins for PrestaShop, OpenCart, PHP, JSON API
*[[OpenCart Bitcoin]] - An OpenCart payment module that communicates with a bitcoin client using JSON RPC.
*[[OsCommerce_Bitcoin_Payment_Module|OsCommerce Bitcoin Payment Module]] - a payment module that uses a python monitoring script to interact with bitcoind for OsCommerce
* [http://drupal.org/project/uc_bitcoin Drupal Ubercart Bitcoin payment method] enables you to accept Bitcoin as payment for your Drupal/Ubercart enabled website product/services.

=== Enterprise server ===
*[http://bitsofproof.com Bits of Proof] - a modular enterprise-ready implementation of the Bitcoin protocol.

===Web apps (opensource)===
*[[Bitcoin Central]] - currency exchange
*[[Bitcoin Poker Room]] - poker site
*[[Abe]] - block chain viewer
*[[Simplecoin]] - PHP web frontend for a pool
*[[bitcoin_simple_php_tools]] simple php tools for webmasters

===Browser extensions===
*[[Bitcoin Extension]] - check balance and send bitcoins (Chrome)
*[[Bitcoin Prices (extension)]] - monitoring price (Firefox)
*[[Bitcoin Ticker]] - monitoring price (Chrome)
*[[Biticker]] - Bitcoin ticker, currency converter and history price graph (Chrome)
*[https://chrome.google.com/webstore/detail/bitcoin-microformats/bkanicejfbhlidgjkpenmddnacjengld?hl=en Bitcoin Microformats] Show bitcoin address metadata embedded in a page (Chrome)
*[https://chrome.google.com/webstore/detail/bitcoin-address-lookup/pmlblkdmadbidammhjiponepngbfcpge?hl=en Bitcoin Address Lookup] Right click an address to view its value. (Chrome)

===PC apps===
*[[http://www.mybtc-trader.com MyBTC-Trader.com]] - a MtGox Bitcoin trading client for windows with GUI
*[[Mining Explorer]] - monitoring tool for bitcoin mining
*[[Bitcoin SMS Alert]] - sends SMS text alerts to a user's phone based on BTC price / percent thresholds.
*[[BTConvert]] - currency conversion
*[[Sierra Chart MtGox Bridge]] - real-time charting
*[[BitTicker]] - monitoring price (Mac OS X)
*[[ToyTrader]] - a command line trading tool for [[MtGox]]
*[[goxsh]] - a command-line frontend to the [[MtGox|Mt. Gox Bitcoin Exchange]] (Python)
*[[MyBitcoins gadget]] - monitoring pool earnings / price (Windows gadget)
*[[Bitcoin QR Popup]] - streamlined interface to bitcoin for POS systems (Windows)
*[http://gnome-help.org/content/show.php/Bitcoin+Rate?content=138572 Bitcoin Rate] - Desktop widget with BTC exchange rate (KDE)
*[http://kde-apps.org/content/show.php?content=142344 Bitcoin Monitor] - Desktop widget to monitor status of your Bitcoin miners on mining pools (KDE)

===Mobile apps===
==== iPhone / iPad ====
*[https://blockchain.info/wallet/iphone-app Blockchain] - Fully featured iphone bitcoin app.
*[[Bitcoin Ticker (iPhone)]] - monitoring price w/push notifications
*[[BitCoins Mobile]] - First iPad native app! Live market data, news feeds, mining pool statistics, full screen exchange price charts, bitcoin network statistical charts. (iPad only, iPhone/iPod Touch coming soon!)
*[https://github.com/teeman/BitcoinTrader BitcoinTrader] - Spend/receive BTC via QR codes, trade, deposit/withdraw, etc. Supports Mt. Gox, TradeHill, ExchB, CampBX, and InstaWallet.
*[[Bit-pay]] - Mobile Checkout, set prices in any currency and receive mobile-to-mobile payment
*[[Easywallet.org]] - Web based wallet, works with QR Code scanner on iPhone/iPad/iPod touch

==== Android ====
* Direct link to Android Market bitcoin apps. https://play.google.com/store/search?q=bitcoin
*[[BitCare]] - Track bitcoin wallet balance, trade on Mt.Gox, monitor mining pool hashrate, balance, worker status.
*[[BtcMobile]] - monitoring price and mining pool statistics (iPhone/iPad, Android)
*[[Bitcoin Alert]] - monitoring price (Android)
*[[Bitcoin-android]] - Does not appear to be being maitained anymore. https://market.android.com/details?id=com.bitcoinandroid
*[[Bitcoin Wallet Balance]] - view your balance in real time on your android phone
*[[Bitcoin Wallet]] - This is the most functional Android bitcoin wallet application. https://market.android.com/details?id=de.schildbach.wallet
*[[BitcoinSpinner]] - Single address, easy to use, lightweight and open source client. Keys stored on device.
*[[BitcoinX]] - monitoring price (Android)
*[[BitPay]] - https://market.android.com/details?id=com.bitcoin.bitpay (Is not related to the bit-pay.com online payment processor.)
*[https://blockchain.info/wallet/android-app Blockchain] - Lightweight Android Bitcoin Client - Also works with blockchain.info web interface and iphone app.
*[[BtcMobile]] - monitoring price and mining pool statistics (iPhone/iPad, Android)
*[[http://coincliff.com CoinCliff]] - Monitors price and fires alarms to wake you up, or notifications, as in text messages (Android)
*[[Easywallet.org]] - Web based wallet, works with QR Code scanner on Android devices
*[[Miner Status]] - monitoring miner status (Android)
*[[SMS Bitcoins]] - transactions by SMS

==== Windows Phone 7 ====
*Direct link to Windows Phone Marketplace Bitcoin apps: [http://www.windowsphone.com/en-us/store/search?q=bitcoin]

see also [[Bitcoin Payment Apps]]

===Operating systems===
*[[MinePeon]] - Bitcoin mining on the Raspberry PI
*[[BAMT]] (not maintained)
*[[LinuxCoin]] - a lightweight Debian-based OS, with the Bitcoin client and GPU mining software (not maintained)

===Mining apps===
Main page: [[Mining software]]
*[[50Miner]] - A GUI frontend for Windows(Poclbm, Phoenix, DiabloMiner, cgminer)
*[[BFGMiner]] - Modular ASIC/FPGA/GPU miner in C
*[[BTCMiner]] - Bitcoin Miner for ZTEX FPGA Boards
*[[Bit Moose]] - Run Miners as a Windows Service.
*[[Poclbm]] - Python/OpenCL GPU miner ([[Poclbm-gui|GUI(Windows & MacOS X)]])
*[[Poclbm-mod]] - more efficient version of [[Poclbm]] ([[Poclbm-mod-gui|GUI]])
*[[DiabloMiner]] - Java/OpenCL GPU miner ([[DiabloMiner.app|MAC OS X GUI]])
*[[RPC Miner]] - remote RPC miner ([[RPCminer.app|MAC OS X GUI]])
*[[Phoenix miner]] - miner
*[[Cpu Miner]] - miner
*[[Ufasoft miner]] - miner
*[[Pyminer]] - Python miner, reference implementation
*[[Remote miner]] - mining pool software
*[[Open Source FGPA Bitcoin Miner]] - a miner that makes use of an FPGA Board
*[https://github.com/mkburza/Flash-Player-Bitcoin-Miner Flash Player Bitcoin Miner] - A proof of concept Adobe Flash Player miner

===Mining Pool Servers (backend)===
Main page: [[Poolservers]]

*[[ecoinpool]] - Erlang poolserver (not maintained)
*[[Eloipool]] - Fast Python3 poolserver
*[[Pushpoold]] - Old mining poolserver in C (not maintained)
*[[Poold]] - Old Python mining poolserver (not maintained)
*[[PoolServerJ]] - Java mining poolserver (not maintained)

===Utilities, libraries, and interfaces:===
*[[BitcoinCrypto]] - a lightweight Bitcoin crypto library for Java/Android
*[[Bitcoin Dissector]] - a wireshark dissector for the bitcoin protocol
*[[Bitcointools]] - a set of Python tools accessing the transaction database and the wallet
*[[Finance::MtGox]] - a Perl module which interfaces with the Mt. Gox API
*[[libblkmaker]] - C library implementation of [[getblocktemplate]] decentralized mining protocol
*[[python-blkmaker]] - Python module implementation of [[getblocktemplate]] decentralized mining protocol

===Lists of software===
*[[BitGit]] - list of Bitcoin-related opensource projects hosted at Git

===Developer resources===
*[[:Category:Developer|Category:Developer]]
*[[:Category:Technical|Category:Technical]]
*[[Original Bitcoin client/API calls list]]
*[[API reference (JSON-RPC)]]
*[[PHP_developer_intro|PHP Developer Introduction]]

===Other===
*[[Namecoin]] - a distributed naming system based on Bitcoin technology
*[[Bitcoin Consultancy]] - an organization providing open source software and Bitcoin-related consulting
*[[Open Transactions]] - a financial crypto and digital cash software library, complementary to Bitcoin
*[[Moneychanger]] - Java-based GUI for [[Open Transactions]]
*[http://btcnames.org/ BTCnames] - a webbased aliasing service which allows to handle unlimited names for your BTC deposit hashes
*[[Devcoin]] - the open source developer coin

People

2013-05-28T06:18:49Z

Grau:

A list of active contributors to Bitcoin, ordered by first name.

[[Andreas Schildbach]] ([https://profiles.google.com/andreas.schildbach Profile]) - original developer of [https://market.android.com/details?id=de.schildbach.wallet Bitcoin Wallet for Android] ([http://code.google.com/p/bitcoin-wallet/ Google Code Project]).

[[Amir Taaki]] aka genjix- creator of the [[Britcoin]] and [[Intersango]] exchanges, [[libbitcoin]] library for Bitcoin, [[Spesmilo]], [[Bitcoin Consultancy]], [[Vibanko]], [[GLBSE]] client, Bitcoin poker client, [https://gitorious.org/freecoin/freecoin Python bindings] for Bitcoin, [[Pastecoin]] and others.

[[ArtForz|Art Forz]]- developed the first GUI miner and at one time his GPU mining farm (the ArtFarm) was mining over a third of all blocks.

[[Gary Rowe]] [https://plus.google.com/u/0/115295932487523951663/about (Profile)] - Contributor to the [[MultiBit]] (http://multibit.org) and [[BitCoinJ]] (http://code.google.com/p/bitcoinj/) projects. Working on various Bitcoin based businesses.

[[Gavin Andresen]]- [https://profiles.google.com/u/0/gavinandresen/about (Profile)] [[Satoshi client]] maintainer. He previously worked at Silicon Graphics and now runs his own company.

[[Hal Finney]]- one of the creators of [http://en.wikipedia.org/wiki/Pretty_Good_Privacy PGP] and one of the earliest contributors to the Bitcoin project. First to identify a type of double-spending attack that now bears his name -- the [[Double-spending#Finney_attack|Finney attack]].

James McCarthy aka Nefario- creator of the first bitcoin stock exchange [[GLBSE]]

[[Jed McCaleb]], original developer of MtGox. Previously created eDonkey2000.

[[Jeff Garzik]]- [http://en.wikipedia.org/wiki/Jeff_Garzik (Wikipedia Entry)] [[Satoshi client]] core developer, GPU poold software and the founder of [[Bitcoin Watch]]. Works as a Linux kernel developer at Red Hat,

[[Luke Dashjr]] aka Luke-Jr- [[Eligius]] owner/admin, maintains [[BFGMiner]] and maintainer of [[bitcoind]]/[[Bitcoin-Qt]] stable branches.

[[Mark Karpeles]] aka MagicalTux- Owner of the largest Bitcoin exchange, [[MtGox]], this Bitcoin Wiki, and [https://www.kalyhost.com/ Kalyhost]

[[Sirius|Martti Malmi]] aka Sirius- Operates the host for bitcoin.org and is an administrator of the [[Bitcoin Forum]].

[[Matt Corallo]] aka BlueMatt- [[Satoshi client]] developer.

[[Michael Hendrix]] aka mndrix- creator of the now defunct CoinPal and CoinCard services

[[Michael Marquardt]] aka theymos- creator of the widely used blockexplorer.com site, and BitcoinTalk Forum

[[Mike Hearn]] [https://profiles.google.com/mh.in.england/about (Profile)]- Google engineer who works on Gmail and developed [[BitCoinJ]] (http://code.google.com/p/bitcoinj/)

[[User:Tcatm|Nils Schneider]] aka tcatm - Bitcoin developer, owner of BitcoinWatch, creator and owner of BitcoinCharts, GPU mining software and JS web interface.

[[Patrick McFarland]] aka Diablo-D3 - DiabloMiner author, and BitcoinTalk forum moderator.

[[Patrick Strateman]] aka phantomcircuit - Bitcoin developer, creator of [[Intersango]], member of [[Bitcoin Consultancy]] and creator of Python Bitcoin implementation.

[[Pieter Wuille]] aka sipa- [[Satoshi client]] developer and maintainer of the network graphs http://bitcoin.sipa.be

[[Stefan Thomas]] aka justmoon- creator of the WeUseCoins.com site/video and WebCoin.

[[Tamas Blummer]] aka grau - author of Bits of Proof, the enterprise-ready implementation of the Bitcoin protocol. http://bitsofproof.com

[[Vladimir Marchenko]]- [https://profiles.google.com/u/0/vmartchenko/about?hl=en Profile], runs [[Marchenko Ltd]] which sells mining contracts, previously developed the figator.org search engine.

==See Also==
* [[Original client developers]]
* [[Developers]]
* Wiki list of [[:Special:ListUsers|users]]
* [[Bitcoin:Community_portal|Community portal]]
* [[:Category:People]]

BCCAPI

2013-05-07T15:46:13Z

Grau: /* See Also */

The BCCAPI (Bitcoin Client API) is a java library designed for making secure light-weight bitcoin clients. The BCCAPI connects to a server that holds the block chain, and which tracks the client’s wallet balance. The server only has knowledge of the clients public keys, and is in no position to spend funds owned by the client’s wallet.

Features include:
* Deterministic private keys, based on seed file.
* Only the seed file needs to get backed up, or generated from a passphrase.
* Send/receive Bitcoins
* Low bandwidth
* Low CPU usage
* Server does not have your private keys and is in no position to spend your coins
* Allows spending of unconfirmed-change-sent-back-to-self like the Satoshi Client
* Open source
* Free service, running on donations

Simply put the API is designed for making it easy to create light-weight secure Bitcoin wallets for handheld devices.
[https://market.android.com/details?id=com.miracleas.bitcoin_spinner BitcoinSpinner] is an Android app implemented on top of the BCCAPI and available on the Android Market.

The sources include a very simple console based client, that shows how to use it.

The donation address for BCCAPI is 143SikKpjzwhBy5Z7Qg5knu5nKXWExSqQi

== Security ==

See [[Thin Client Security]]

==See Also==

The first Android wallet based on the BCCAPI: [[BitcoinSpinner]]

More information and the source code: http://code.google.com/p/bccapi/wiki/WhatIsTheBCCAPI

Forum thread about BCCAPI: https://bitcointalk.org/index.php?topic=36892.0

BCCAPI Adapter for bits of proof Enterprise Bitcoin Server https://github.com/bitsofproof/bop-bccapi

[[Category:Clients]]

Protocol documentation

2013-04-16T09:16:19Z

Grau: /* version */

Sources:
* [[Original Bitcoin client]] source

Type names used in this documentation are from the C99 standard.

For protocol used in mining, see [[Getwork]].

==Common standards==

=== Hashes ===

Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).

Example of double-SHA-256 encoding of string "hello":

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)

For bitcoin addresses (RIPEMD-160) this would give:

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)

=== Merkle Trees ===

Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.

If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.

First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.

Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.

This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''merkle root''' of the tree.

For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The merkle tree is:

d6=dhash(d4 concat d5)
d4=dhash(d1 concat d2) d5=dhash(d3 concat d3)
d1=dhash(a) d2=dhash(b) d3=dhash(c) d3=dhash(c)

where

dhash(a) = sha256(sha256(a))

''d6'' is the merkle root of the 3 transactions in this block.

Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.

=== Signatures ===

Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions.

For ECDSA the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.

Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.

Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).

=== Transaction Verification ===
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.

Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.

Each ''output'' determines which Bitcoin address (or other criteria, see [[Scripting]]) is the recipient of the funds.

In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.

A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totaling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.

The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.

Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.

=== Addresses ===

A bitcoin address is in fact the hash of a ECDSA public key, computed this way:

Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)

The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.

== Common structures ==

Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes
|-
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))
|-
| ? || payload || uchar[] || The actual data
|}

Known magic values:

{|class="wikitable"
! Network !! Magic value !! Sent over wire as
|-
| main || 0xD9B4BEF9 || F9 BE B4 D9
|-
| testnet || 0xDAB5BFFA || FA BF B5 DA
|-
| testnet3 || 0x0709110B || 0B 11 09 07
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space.
Variable length integers always precede an array/vector of a type of data that may vary in length.
Longer numbers are encoded in little endian.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the length as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the length as uint32_t
|-
| - || 9 || 0xff followed by the length as uint64_t
|}

Footnote - if you're reading the Satoshi client code it refers to this as a "CompactSize" - VarInt's are something entirely different to the Satoshi code.

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. This protocol and structure supports IPv6, '''but note that the original client currently only supports IPv4 networking'''. Network addresses are not prefixed with a timestamp in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || time || uint32 || the Time (version >= 31402)
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

<pre>
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .

Network address:
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:10.0.0.1 or IPv4: 10.0.0.1
20 8D - Port 8333
</pre>

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || type || uint32_t || Identifies the object type linked to this inventory
|-
| 32 || hash || char[32] || Hash of the object
|}

The object type is currently defined as one of the following possibilities:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || ERROR || Any data of with this number may be ignored
|-
| 1 || MSG_TX || Hash is related to a transaction
|-
| 2 || MSG_BLOCK || Hash is related to a data block
|}

Other Data Type values are considered reserved for future implementations.

=== Block Headers ===

Block headers are sent in a headers packet in response to a getheaders message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)
|-
| 4 || bits || uint32_t || The calculated difficulty target being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| 1 || txn_count || uint8_t || Number of transaction entries, this value is always 0
|}

== Message types ==

=== version ===

When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message
|-
|colspan="4"| version >= 106
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message
|-
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.
|-
| ? || user_agent || [[#Variable length string|var_str]] || [[BIP_0014|User Agent]] (0x00 if string is 0 bytes long)
|-
| 4 || start_height || int32_t || The last block received by the emitting node
|-
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [[BIP 0037]], since version >= 70001
|}

A "verack" packet shall be sent if the version packet was accepted.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.
|}

Hexdump example of version message (OBSOLETE EXAMPLE. This example lacks a checksum and user-agent):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
55 00 00 00 - Payload is 85 bytes long
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0
Version message:
9C 7C 00 00 - 31900 (version 0.3.19)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address
DD 9D 20 2C 3A B4 57 13 - Node random unique ID
00 - "" sub-version string (string is 0 bytes long)
55 81 01 00 - Last block sending node has is block #98645
</pre>

And here's a modern (60002) protocol version client advertising itself to a local peer...

Newer protocol includes the checksum now, this is from a mainline (satoshi) client during
an outgoing connection to another local client, notice that it does not fill out the
address information at all when the source or destination is "unroutable".

<pre>

0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..

Message Header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
64 00 00 00 - Payload is 100 bytes long
35 8D 49 32 - payload checksum

Version message:
62 EA 00 00 - 60002 (protocol version 60002)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address
3B 2E B3 5D 8C E6 17 65 - Node ID
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)
C0 3E 03 00 - Last block sending node has is block #212672
</pre>

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|message header]] with the command string "verack".

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 5D F6 E0 E2 ........

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command
00 00 00 00 - Payload is 0 bytes long
5D F6 E0 E2 - Checksum
</pre>

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 30x? || addr_list || (uint32_t + net_addr)[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).
|}

'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.

Hexdump example of ''addr'' message:
<pre>
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................
0030 FF 0A 00 00 01 20 8D ..... .

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
ED 52 39 9B - checksum of payload

Payload:
01 - 1 address in this message

Address:
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)
20 8D - port 8333
</pre>

=== inv ===

Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getdata ===

getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== notfound ===

notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getblocks ===

Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients (specifically the Satoshi client) will gladly provide blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)
|}

To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:

<pre>
// From libbitcoin which is under AGPL
std::vector<size_t> block_locator_indices(int top_depth)
{
// Start at max_depth
std::vector<size_t> indices;
// Push last 10 indices first
size_t step = 1, start = 0;
for (int i = top_depth; i > 0; i -= step, ++start)
{
if (start >= 10)
step *= 2;
indices.push_back(i);
}
indices.push_back(0);
return indices;
}
</pre>

Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.

=== getheaders ===

Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the blockchain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients (specifically the Satoshi client) will gladly provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)
|}

For the block locator object in this packet, the same rules apply as for the [[Protocol_specification#getblocks|getblocks]] packet.

=== tx ===

''tx'' describes a bitcoin transaction, in reply to ''getdata''

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Transaction data format version
|-
| 1+ || tx_in count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction outputs
|-
| 8+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins
|-
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:
{|class="wikitable"
! Value !! Description
|-
| 0 || Always locked
|-
| < 500000000 || Block number at which this transaction is locked
|-
| >= 500000000 || UNIX timestamp at which this transaction is locked
|}
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time.

|}

TxIn consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure
|-
| 1+ || script length || [[Protocol_specification#Variable_length_integer|var_int]] || The length of the signature script
|-
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization
|-
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.
|}

The OutPoint structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || The hash of the referenced transaction.
|-
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.
|}

The Script structure consists of a series of pieces of information and operations related to the value of the transaction.

(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)

The TxOut structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || value || int64_t || Transaction Value
|-
| 1+ || pk_script length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the pk_script
|-
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

Example ''tx'' message:
<pre>
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......

Message header:
F9 BE B4 D9 - main network magic bytes
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command
02 01 00 00 - payload is 258 bytes long
E2 93 CD BE - checksum of payload

Transaction:
01 00 00 00 - version

Inputs:
01 - number of transaction inputs

Input 1:
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29
00 00 00 00

8B - script is 139 bytes long

48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04
2F 46 61 4A 4C 70 C0 F1 4B EF F5

FF FF FF FF - sequence

Outputs:
02 - 2 Output Transactions

Output 1:
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)
19 - pk_script is 25 bytes long

76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script
A9 D9 EA 1A FB 22 5E 88 AC

Output 2:
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)
19 - pk_script is 25 bytes long

76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script
FD A0 B7 8B 4E CC 52 88 AC

Locktime:
00 00 00 00 - lock time
</pre>

=== block ===

The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)
|-
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| ? || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries
|-
| ? || txns || tx[] || Block transactions, in format of "tx" command
|}

The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.
See [[Block hashing algorithm]] for details and an example.

=== headers ===

The ''headers'' packet returns block headers in response to a ''getheaders'' packet.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of block headers
|-
| 81x? || headers || [[Protocol_specification#Block_Headers|block_header]][] || [[Protocol_specification#Block_Headers|Block headers]]
|}

Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers which are sent to miners.

=== getaddr ===

The getaddr message sends a request to a node asking for information about known active peers to help with identifying potential nodes in the network. The response to receiving this message is to transmit an addr message with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.

No additional data is transmitted with this message.

=== checkorder ===

This message is used for [[IP Transactions]], to ask the peer if it accepts such transactions and allow it to look at the content of the order.

It contains a CWalletTx object

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|colspan="4"| Fields from CMerkleTx
|-
| ? || hashBlock
|-
| ? || vMerkleBranch
|-
| ? || nIndex
|-
|colspan="4"| Fields from CWalletTx
|-
| ? || vtxPrev
|-
| ? || mapValue
|-
| ? || vOrderForm
|-
| ? || fTimeReceivedIsTxTime
|-
| ? || nTimeReceived
|-
| ? || fFromMe
|-
| ? || fSpent
|}

=== submitorder ===

Confirms an order has been submitted.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the transaction
|-
| ? || wallet_entry || CWalletTx || Same payload as checkorder
|}

=== reply ===

Generic reply for [[IP Transactions]]

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || reply || uint32_t || reply code
|}

Possible values:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || SUCCESS || The IP Transaction can proceed (''checkorder''), or has been accepted (''submitorder'')
|-
| 1 || WALLET_ERROR || AcceptWalletTransaction() failed
|-
| 2 || DENIED || IP Transactions are not accepted by this node
|}

=== ping ===

The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.

=== filterload, filteradd, filterclear, merkleblock ===

These messages are related to Bloom filtering of connections and are defined in [[BIP 0037]].

=== alert ===

An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.

Alert format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || payload || var_str || Serialized alert payload
|-
| ? || signature || var_str || An ECDSA signature of the message
|}

The developers of Satoshi's client use this public key for signing alerts:
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

The payload is serialized into a var_str to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || Version || int32_t || Alert format version
|-
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert
|-
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored
|-
| 4 || ID || int32_t || A unique ID number for this alert
|-
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be canceled: deleted and not accepted in the future
|-
| ? || setCancel || set<int> || All alert IDs contained in this set should be canceled as above
|-
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.
|-
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.
|-
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.
|-
| 4 || Priority || int32_t || Relative priority compared to other alerts
|-
| ? || Comment || string || A comment on the alert that is not displayed
|-
| ? || StatusBar || string || The alert message that is displayed to the user
|-
| ? || Reserved || string || Reserved
|}

Sample alert (no message header):
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1

Version: 1
RelayUntil: 1329620535
Expiration: 1329792435
ID: 1010
Cancel: 1009
setCancel: <empty>
MinVer: 10000
MaxVer: 61000
setSubVer: <empty>
Priority: 100
Comment: <empty>
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"
Reserved: <empty>

== Scripting ==

See [[script]].

== Wireshark dissector ==
A dissector for wireshark is being developed at https://github.com/blueCommand/bitcoin-dissector

==See Also==

* [[Network]]
* [[Protocol rules]]
* [[Hardfork Wishlist]]

==References==
<references />

[[zh-cn:协议说明]]
[[Category:Technical]]
[[Category:Developer]]

Software versions

2013-04-13T20:13:56Z

Grau:

{| class="wikitable"
! Software !! Vulnerable !! Old !! Current
|-
| Bitcoin-Qt bitcoind || * - 0.4.9rc1 0.5.0rc1 - 0.5.8rc1 0.6.0rc1 - 0.6.5rc1 0.7.0rc1 - 0.7.3rc1 0.8.0rc1 - 0.8.0 || || 0.4.9rc2 0.5.8rc2 0.6.5rc2 0.7.3rc2 0.8.1
|-
| bits of proof || || 0.8|| 0.9
|}

Clients

2013-04-06T21:28:31Z

Grau: /* For developers */

==Overview==

This table compares the features of the different clients. All of the listed clients are open-source.

===Feature key===

; Wallet Security : How well the client protects your [[private key]]s from people with access to the machine the wallet is stored on. The private keys can be encrypted, for example. The private keys can also be either stored on your device or on a remote server.
; Network Security : Clients which more fully implement the Bitcoin network protocol are safer -- they can't be as easily tricked by powerful attackers. A client which ''fully'' implements the protocol will always use the correct [[block chain]] and will never allow [[double-spending|double-spends]] or invalid transactions to exist in the block chain under any circumstances. Clients which only ''partially'' implement the protocol typically trust that 50% or more of the network's mining power is honest. Some clients trust one or more ''remote servers'' to protect them from double-spends and other network attacks.
; Setup Time : Some clients require that you download and verify a large amount of data before you can send or receive BTC.
; Maturity : When the project was started.

===Table===


{| class='wikitable' style='text-align: center'
! Client !! Get Started !! Audience !! Wallet Security !! Network Security !! Backups !! Setup Time !! Disk Space !! Maturity !! Multi-user !! Available for
|-
! Armory
|| [http://bitcoinarmory.com/index.php/get-armory Download] || Power users || {{CLGood|Encrypted, on-device}} || Addon || {{CLBest|One-time}} || Varies || {{CLBad|6+ GB}} || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLWin}}
|-
! Bitcoin Wallet
|| [https://play.google.com/store/apps/details?id=de.schildbach.wallet Google Play] [https://appworld.blackberry.com/webstore/content/23952882/ BlackBerry World] || {{CLBest|Everyone}} || {{CLGood|Isolated, on-device}} || Partial || Manual || 1 hour || 30 MB || {{CLGood|Mar 2011}} || on JB tablets || {{CLAndroid}} [[file:ico-blackberry.png]]
|-
! {{CLGood|Bitcoin-Qt}}
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || {{CLGood|End-users}} || {{CLGood|Encrypted, on-device}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|6+ GB}} || {{CLGood|May 2011}} || No || {{CLLinux}}{{CLMac}}{{CLWin}}
|-
! bitcoind
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || Programmers || {{CLGood|Encrypted, on-device}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|6+ GB}} || {{CLBest|Aug 2009}} || {{CLGood|Virtual accounts}} || {{CLLinux}}{{CLWin}}
|-
! Electrum
|| [http://ecdsa.org/electrum/ Download] || Power users || {{CLGood|Encrypted, on-device}} || Minimal || {{CLBest|Memorized}} || {{CLGood|Minutes}} || {{CLGood|5 MB}} || Nov 2011 || No || {{CLLinux}}{{CLMac}}{{CLWin}}
|-
! MultiBit
|| [http://multibit.org/releases.html Download] || {{CLGood|End-users}} || {{CLBad|None, on-device}} || Partial || {{CLBad|No}} || {{CLBest|Seconds}} || 50 MB || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLMac}}{{CLWin}}
|-
! My Wallet
|| [https://blockchain.info/wallet/new Web-based] || {{CLBest|Everyone}} || Encrypted, on a server || {{CLBad|Remote}} || {{CLGood|Automatic}} || {{CLGood|Minutes}} || {{CLBest|None}} || Dec 2011 || {{CLBest|Yes}} || {{CLAndroid}}{{CLiOS}}{{CLLinux}}{{CLMac}}{{CLWin}}
|}



==For developers==

This table shows additional information about various Bitcoin clients that may be relevant to developers.

{| class='wikitable' style='text-align: center'
! Client !! Website !! Source Code !! License !! Discussion !! Architecture
|-
! Armory
|| [http://bitcoinarmory.com/ Link] ||[https://github.com/etotheipi/BitcoinArmory/ Github] || AGPLv3 || [https://bitcointalk.org/index.php?board=97.0 Bitcointalk] || Integrated
|-
! Bitcoin Wallet
|| [https://code.google.com/p/bitcoin-wallet/ Link] || [https://code.google.com/p/bitcoin-wallet/source/checkout Google Code] [https://github.com/schildbach/bitcoin-wallet Github] || GPLv3 || [https://bitcointalk.org/index.php?board=100.0 Bitcointalk] / [https://groups.google.com/forum/?fromgroups#!forum/bitcoinj Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]
|-
! Bitcoin-Qt / bitcoind
|| [http://bitcoin.org/ Link] || [https://github.com/bitcoin/bitcoin Github] || MIT || [https://lists.sourceforge.net/lists/listinfo/bitcoin-development Sourceforge] || Integrated
|-
! Electrum
|| [http://ecdsa.org/electrum/ Link] || [https://gitorious.org/electrum Gitorious] || GPLv3 || [https://lists.sourceforge.net/lists/listinfo/electrum-discuss Sourceforge] || [[Thin Client Security#Server-Trusting Clients|Server-Client]]
|-
! MultiBit
|| [http://multibit.org/ Link] || [https://github.com/jim618/multibit Github] || MIT || [https://groups.google.com/forum/?fromgroups#!forum/bitcoin-multibit Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]
|-
! My Wallet
|| [https://blockchain.info/wallet/ Link] || [https://github.com/blockchain/My-Wallet/ Github] || BSD* || None || [[Thin Client Security#Server-Trusting Clients|Server-Client]]
|-
! bits of proof
|| [http://bitsofproof.com Link] || [https://github.com/bitsofproof/supernode Github] || Apache 2.0 || [https://bitcointalk.org/index.php?topic=122013.0 Bitcointalk] || [[Thin Client Security#Server-Trusting Clients|Server-Client]]
|}

==See Also==
* [[Software#Bitcoin_clients|List of clients]]
* [[Bitcoin Ladder]]

<references/>

Clients

2013-04-06T21:27:40Z

Grau: /* For developers */

==Overview==

This table compares the features of the different clients. All of the listed clients are open-source.

===Feature key===

; Wallet Security : How well the client protects your [[private key]]s from people with access to the machine the wallet is stored on. The private keys can be encrypted, for example. The private keys can also be either stored on your device or on a remote server.
; Network Security : Clients which more fully implement the Bitcoin network protocol are safer -- they can't be as easily tricked by powerful attackers. A client which ''fully'' implements the protocol will always use the correct [[block chain]] and will never allow [[double-spending|double-spends]] or invalid transactions to exist in the block chain under any circumstances. Clients which only ''partially'' implement the protocol typically trust that 50% or more of the network's mining power is honest. Some clients trust one or more ''remote servers'' to protect them from double-spends and other network attacks.
; Setup Time : Some clients require that you download and verify a large amount of data before you can send or receive BTC.
; Maturity : When the project was started.

===Table===


{| class='wikitable' style='text-align: center'
! Client !! Get Started !! Audience !! Wallet Security !! Network Security !! Backups !! Setup Time !! Disk Space !! Maturity !! Multi-user !! Available for
|-
! Armory
|| [http://bitcoinarmory.com/index.php/get-armory Download] || Power users || {{CLGood|Encrypted, on-device}} || Addon || {{CLBest|One-time}} || Varies || {{CLBad|6+ GB}} || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLWin}}
|-
! Bitcoin Wallet
|| [https://play.google.com/store/apps/details?id=de.schildbach.wallet Google Play] [https://appworld.blackberry.com/webstore/content/23952882/ BlackBerry World] || {{CLBest|Everyone}} || {{CLGood|Isolated, on-device}} || Partial || Manual || 1 hour || 30 MB || {{CLGood|Mar 2011}} || on JB tablets || {{CLAndroid}} [[file:ico-blackberry.png]]
|-
! {{CLGood|Bitcoin-Qt}}
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || {{CLGood|End-users}} || {{CLGood|Encrypted, on-device}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|6+ GB}} || {{CLGood|May 2011}} || No || {{CLLinux}}{{CLMac}}{{CLWin}}
|-
! bitcoind
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || Programmers || {{CLGood|Encrypted, on-device}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|6+ GB}} || {{CLBest|Aug 2009}} || {{CLGood|Virtual accounts}} || {{CLLinux}}{{CLWin}}
|-
! Electrum
|| [http://ecdsa.org/electrum/ Download] || Power users || {{CLGood|Encrypted, on-device}} || Minimal || {{CLBest|Memorized}} || {{CLGood|Minutes}} || {{CLGood|5 MB}} || Nov 2011 || No || {{CLLinux}}{{CLMac}}{{CLWin}}
|-
! MultiBit
|| [http://multibit.org/releases.html Download] || {{CLGood|End-users}} || {{CLBad|None, on-device}} || Partial || {{CLBad|No}} || {{CLBest|Seconds}} || 50 MB || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLMac}}{{CLWin}}
|-
! My Wallet
|| [https://blockchain.info/wallet/new Web-based] || {{CLBest|Everyone}} || Encrypted, on a server || {{CLBad|Remote}} || {{CLGood|Automatic}} || {{CLGood|Minutes}} || {{CLBest|None}} || Dec 2011 || {{CLBest|Yes}} || {{CLAndroid}}{{CLiOS}}{{CLLinux}}{{CLMac}}{{CLWin}}
|}



==For developers==

This table shows additional information about various Bitcoin clients that may be relevant to developers.

{| class='wikitable' style='text-align: center'
! Client !! Website !! Source Code !! License !! Discussion !! Architecture
|-
! Armory
|| [http://bitcoinarmory.com/ Link] ||[https://github.com/etotheipi/BitcoinArmory/ Github] || AGPLv3 || [https://bitcointalk.org/index.php?board=97.0 Bitcointalk] || Integrated
|-
! Bitcoin Wallet
|| [https://code.google.com/p/bitcoin-wallet/ Link] || [https://code.google.com/p/bitcoin-wallet/source/checkout Google Code] [https://github.com/schildbach/bitcoin-wallet Github] || GPLv3 || [https://bitcointalk.org/index.php?board=100.0 Bitcointalk] / [https://groups.google.com/forum/?fromgroups#!forum/bitcoinj Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]
|-
! Bitcoin-Qt / bitcoind
|| [http://bitcoin.org/ Link] || [https://github.com/bitcoin/bitcoin Github] || MIT || [https://lists.sourceforge.net/lists/listinfo/bitcoin-development Sourceforge] || Integrated
|-
! Electrum
|| [http://ecdsa.org/electrum/ Link] || [https://gitorious.org/electrum Gitorious] || GPLv3 || [https://lists.sourceforge.net/lists/listinfo/electrum-discuss Sourceforge] || [[Thin Client Security#Server-Trusting Clients|Server-Client]]
|-
! MultiBit
|| [http://multibit.org/ Link] || [https://github.com/jim618/multibit Github] || MIT || [https://groups.google.com/forum/?fromgroups#!forum/bitcoin-multibit Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]
|-
! My Wallet
|| [https://blockchain.info/wallet/ Link] || [https://github.com/blockchain/My-Wallet/ Github] || BSD* || None || [[Thin Client Security#Server-Trusting Clients|Server-Client]]
|-
! bits of proof
|| [https://bitsofproof.com Link] || [https://github.com/bitsofproof/supernode Github] || Apache 2.0 || [https://bitcointalk.org/index.php?topic=122013.0 Bitcointalk] || [[Thin Client Security#Server-Trusting Clients|Server-Client]]
|}

==See Also==
* [[Software#Bitcoin_clients|List of clients]]
* [[Bitcoin Ladder]]

<references/>

Software

2013-04-06T21:22:51Z

Grau: /* Bitcoin software */

List of Bitcoin-related software. See also [[:Category:Software|Category:Software]].

Be sure to keep on top of the latest [[CVEs|security vulnerabilities]]!

==Bitcoin clients==
===Bitcoin clients===
::''Main article and feature comparison: [[Clients]]''
*[[Bitcoin-Qt]] - C++/Qt based tabbed UI. Linux/MacOSX/Windows. Full-featured [[Thin Client Security|thick client]] that downloads the entire [[block chain]], using code from the original Bitcoin client.
*[[bitcoind]] - GUI-less version of the original Bitcoin client, providing a [[API reference (JSON-RPC)|JSON-RPC]] interface
*[[MultiBit]] - lightweight [[Thin Client Security|thin client]] for Windows, MacOS and Linux with support for opening multiple wallets simultaneously
*[[Electrum]] - a "blazing fast, open-source, multi-OS Bitcoin client/wallet with a very active community"
*[[Bitcoin-js-remote]] - JavaScript RPC client, support for QR codes
*[https://github.com/TheSeven/Bitcoin-WebUI Bitcoin WebUI] - JavaScript RPC client
*[https://github.com/zamgo/bitcoin-webskin Bitcoin Webskin] - PHP web interface to bitcoind and namecoind
*[https://bitcointalk.org/index.php?topic=50721.0 subvertx] - command line bitcoin tools
*[[Bitcoiner]] - Java RPC client (Android)
*[[Armory]] - Python-based client currently an alpha-level release, the beta version is being crowdfunded
*[[Spesmilo]] - Python/PySide RPC client (abandoned)

====Frontends to eWallet====
*[[BitPay]] - Android application
*[https://blockchain.info/wallet Blockchain] - Javascript bitcoin client with client side encryption.

====Experimental====
*[[Freecoin]] - C++ client, supports alternative currencies like [[Beertoken]]
*[[BitDroid]] - Java client
*[[Bitdollar]] - C++/Qt client, unstable beta version

===Libraries===
*[https://bitcointalk.org/index.php?topic=30646.0 libbitcoin]
*[[BitCoinJ]] - Java client library, early development stage but used in live projects already
*[[BCCAPI]] (Bitcoin Client API) - a java library designed for making secure light-weight bitcoin clients.

==Bitcoin Trade Data==
*[[Bitcoin Charts]] – Prices, volume, and extensive charting on virtually all Bitcoin markets.
*[[MtGox Live]] - An innovative chart showing a live feed of [[MtGox]] trades and market depth. (Must Use Chrome)
*[http://btccharts.com BTCCharts] - An innovative chart showing a live feed of multiple markets, currencies and timeframes.
*[http://BitcoinExchangeRate.org BitcoinExchangeRate.org] - Bitcoin and USD converter with convenient URL scheme and Auto-updating Portfolio Spreadsheet.
*[[Bitcoin Sentiment Index]] - A financial index that collects and disseminates sentiment data about bitcoin.
*[[Preev]] - Bitcoin converter with live exchange rates.
*[[Skami]] - Bitcoin Market Exchange comparison charts.
*[[BitcoinSentiment]] - Crowdvoting site offering means of voting and viewing voters sentiment towards bitcoin.

==Bitcoin software==

===Web interfaces for merchants===
*[[Bitcoin Evolution]] - Non wallet-based Buy Now button to insert into websites (handles sales tracking; client must be used for actual transaction)
*[[BitPay]] - Buy Now buttons, Checkout posts/callbacks, Mobile Checkout, JSON API
*[[Btceconomy]] - a JavaScript widget listing items for sale
*[[Javascript Bitcoin Converter]] - currency conversion
*[[WalletBit]] - Easy JavaScript Buy Now buttons, Instant Payment Notification, Application Programming Interface (JSON API), Mobile Checkout, QR-Code
*[[BitUtils Merchant]] - Customizable Buy Now buttons with hosted checkout interface. No programming skills required to set up.

===Shopping Cart Integration in eCommerce-Systems===
*[[Zen Cart Bitcoin Payment Module]] - a payment module that interacts with bitcoind for the Zen Cart eCommerce shopping chart.
*[[Karsha Shopping Cart Interface]] - is a mobile payment-interface which enables its users to accept payments.
*[[Bitcoin-Cash]] - an easy to use payment module for xt:Commerce
*[[BitPay]] - bitcoin plugins for Magento, Opencart, Zencart, PHP, JSON API
*[[WalletBit]] - Plugins for PrestaShop, OpenCart, PHP, JSON API
*[[OpenCart Bitcoin]] - An OpenCart payment module that communicates with a bitcoin client using JSON RPC.
*[[OsCommerce_Bitcoin_Payment_Module|OsCommerce Bitcoin Payment Module]] - a payment module that uses a python monitoring script to interact with bitcoind for OsCommerce
* [http://drupal.org/project/uc_bitcoin Drupal Ubercart Bitcoin payment method] enables you to accept Bitcoin as payment for your Drupal/Ubercart enabled website product/services.

=== Enterprise server ===
*[http://bitsofproof.com bits of proof] - a modular Java implementation of the Bitcoin protocol server with a message bus and API for custom extensions.

===Web apps (opensource)===
*[[Bitcoin Central]] - currency exchange
*[[Bitcoin Poker Room]] - poker site
*[[Abe]] - block chain viewer
*[[Simplecoin]] - PHP web frontend for a pool
*[[bitcoin_simple_php_tools]] simple php tools for webmasters

===Browser extensions===
*[[Bitcoin Extension]] - check balance and send bitcoins (Chrome)
*[[Bitcoin Prices (extension)]] - monitoring price (Firefox)
*[[Bitcoin Ticker]] - monitoring price (Chrome)
*[[Biticker]] - Bitcoin ticker, currency converter and history price graph (Chrome)
*[https://chrome.google.com/webstore/detail/bitcoin-microformats/bkanicejfbhlidgjkpenmddnacjengld?hl=en Bitcoin Microformats] Show bitcoin address metadata embedded in a page (Chrome)
*[https://chrome.google.com/webstore/detail/bitcoin-address-lookup/pmlblkdmadbidammhjiponepngbfcpge?hl=en Bitcoin Address Lookup] Right click an address to view its value. (Chrome)

===PC apps===
*[[http://www.mybtc-trader.com MyBTC-Trader.com]] - a MtGox Bitcoin trading client for windows with GUI
*[[Mining Explorer]] - monitoring tool for bitcoin mining
*[[Bitcoin SMS Alert]] - sends SMS text alerts to a user's phone based on BTC price / percent thresholds.
*[[BTConvert]] - currency conversion
*[[Sierra Chart MtGox Bridge]] - real-time charting
*[[BitTicker]] - monitoring price (Mac OS X)
*[[ToyTrader]] - a command line trading tool for [[MtGox]]
*[[goxsh]] - a command-line frontend to the [[MtGox|Mt. Gox Bitcoin Exchange]] (Python)
*[[MyBitcoins gadget]] - monitoring pool earnings / price (Windows gadget)
*[[Bitcoin QR Popup]] - streamlined interface to bitcoin for POS systems (Windows)
*[http://gnome-help.org/content/show.php/Bitcoin+Rate?content=138572 Bitcoin Rate] - Desktop widget with BTC exchange rate (KDE)
*[http://kde-apps.org/content/show.php?content=142344 Bitcoin Monitor] - Desktop widget to monitor status of your Bitcoin miners on mining pools (KDE)

===Mobile apps===
==== iPhone / iPad ====
*[https://blockchain.info/wallet/iphone-app Blockchain] - Fully featured iphone bitcoin app.
*[[Bitcoin Ticker (iPhone)]] - monitoring price w/push notifications
*[[BitCoins Mobile]] - First iPad native app! Live market data, news feeds, mining pool statistics, full screen exchange price charts, bitcoin network statistical charts. (iPad only, iPhone/iPod Touch coming soon!)
*[https://github.com/teeman/BitcoinTrader BitcoinTrader] - Spend/receive BTC via QR codes, trade, deposit/withdraw, etc. Supports Mt. Gox, TradeHill, ExchB, CampBX, and InstaWallet.
*[[Bit-pay]] - Mobile Checkout, set prices in any currency and receive mobile-to-mobile payment
*[[Easywallet.org]] - Web based wallet, works with QR Code scanner on iPhone/iPad/iPod touch

==== Android ====
* Direct link to Android Market bitcoin apps. https://play.google.com/store/search?q=bitcoin
*[[BitCare]] - Track bitcoin wallet balance, trade on Mt.Gox, monitor mining pool hashrate, balance, worker status.
*[[BtcMobile]] - monitoring price and mining pool statistics (iPhone/iPad, Android)
*[[Bitcoin Alert]] - monitoring price (Android)
*[[Bitcoin-android]] - Does not appear to be being maitained anymore. https://market.android.com/details?id=com.bitcoinandroid
*[[Bitcoin Wallet Balance]] - view your balance in real time on your android phone
*[[Bitcoin Wallet]] - This is the most functional Android bitcoin wallet application. https://market.android.com/details?id=de.schildbach.wallet
*[[BitcoinSpinner]] - Single address, easy to use, lightweight and open source client. Keys stored on device.
*[[BitcoinX]] - monitoring price (Android)
*[[BitPay]] - https://market.android.com/details?id=com.bitcoin.bitpay (Is not related to the bit-pay.com online payment processor.)
*[https://blockchain.info/wallet/android-app Blockchain] - Lightweight Android Bitcoin Client - Also works with blockchain.info web interface and iphone app.
*[[BtcMobile]] - monitoring price and mining pool statistics (iPhone/iPad, Android)
*[[Easywallet.org]] - Web based wallet, works with QR Code scanner on Android devices
*[[Miner Status]] - monitoring miner status (Android)
*[[SMS Bitcoins]] - transactions by SMS

==== Windows Phone 7 ====
*Direct link to Windows Phone Marketplace Bitcoin apps: [http://www.windowsphone.com/en-us/store/search?q=bitcoin]

see also [[Bitcoin Payment Apps]]

===Operating systems===
*[[BAMT]]
*[[LinuxCoin]] - a lightweight Debian-based OS, with the Bitcoin client and GPU mining software

===Mining apps===
Main page: [[Mining software]]
*[[50Miner]] - A GUI frontend for Windows(Poclbm, Phoenix, DiabloMiner, cgminer)
*[[BFGMiner]] - Modular FPGA/GPU miner in C
*[[BTCMiner]] - Bitcoin Miner for ZTEX FPGA Boards
*[[Bit Moose]] - Run Miners as a Windows Service.
*[[Poclbm]] - Python/OpenCL GPU miner ([[Poclbm-gui|GUI(Windows & MacOS X)]])
*[[Poclbm-mod]] - more efficient version of [[Poclbm]] ([[Poclbm-mod-gui|GUI]])
*[[DiabloMiner]] - Java/OpenCL GPU miner ([[DiabloMiner.app|MAC OS X GUI]])
*[[RPC Miner]] - remote RPC miner ([[RPCminer.app|MAC OS X GUI]])
*[[Phoenix miner]] - miner
*[[Cpu Miner]] - miner
*[[Ufasoft miner]] - miner
*[[Pyminer]] - Python miner, reference implementation
*[[Remote miner]] - mining pool software
*[[Open Source FGPA Bitcoin Miner]] - a miner that makes use of an FPGA Board
*[https://github.com/mkburza/Flash-Player-Bitcoin-Miner Flash Player Bitcoin Miner] - A proof of concept Adobe Flash Player miner

===Mining Pool Servers (backend)===
Main page: [[Poolservers]]

*[[ecoinpool]] - Erlang poolserver
*[[Eloipool]] - Fast Python3 poolserver
*[[Pushpoold]] - Old mining poolserver in C (not maintained)
*[[Poold]] - Old Python mining poolserver (not maintained)
*[[PoolServerJ]] - Java mining poolserver (not maintained)

===Utilities, libraries, and interfaces:===
*[[BitcoinCrypto]] - a lightweight Bitcoin crypto library for Java/Android
*[[Bitcoin Dissector]] - a wireshark dissector for the bitcoin protocol
*[[Bitcointools]] - a set of Python tools accessing the transaction database and the wallet
*[[Finance::MtGox]] - a Perl module which interfaces with the Mt. Gox API
*[[libblkmaker]] - C library implementation of [[getblocktemplate]] decentralized mining protocol
*[[python-blkmaker]] - Python module implementation of [[getblocktemplate]] decentralized mining protocol

===Lists of software===
*[[BitGit]] - list of Bitcoin-related opensource projects hosted at Git

===Developer resources===
*[[:Category:Developer|Category:Developer]]
*[[:Category:Technical|Category:Technical]]
*[[Original Bitcoin client/API calls list]]
*[[API reference (JSON-RPC)]]
*[[PHP_developer_intro|PHP Developer Introduction]]

===Other===
*[[Namecoin]] - a distributed naming system based on Bitcoin technology
*[[Bitcoin Consultancy]] - an organization providing open source software and Bitcoin-related consulting
*[[Open Transactions]] - a financial crypto and digital cash software library, complementary to Bitcoin
*[[Moneychanger]] - Java-based GUI for [[Open Transactions]]
*[http://btcnames.org/ BTCnames] - a webbased aliasing service which allows to handle unlimited names for your BTC deposit hashes
*[[Devcoin]] - the open source developer coin

Clients

2013-04-06T21:11:59Z

Grau: /* For developers */

==Overview==

This table compares the features of the different clients. All of the listed clients are open-source.

===Feature key===

; Wallet Security : How well the client protects your [[private key]]s from people with access to the machine the wallet is stored on. The private keys can be encrypted, for example. The private keys can also be either stored on your device or on a remote server.
; Network Security : Clients which more fully implement the Bitcoin network protocol are safer -- they can't be as easily tricked by powerful attackers. A client which ''fully'' implements the protocol will always use the correct [[block chain]] and will never allow [[double-spending|double-spends]] or invalid transactions to exist in the block chain under any circumstances. Clients which only ''partially'' implement the protocol typically trust that 50% or more of the network's mining power is honest. Some clients trust one or more ''remote servers'' to protect them from double-spends and other network attacks.
; Setup Time : Some clients require that you download and verify a large amount of data before you can send or receive BTC.
; Maturity : When the project was started.

===Table===


{| class='wikitable' style='text-align: center'
! Client !! Get Started !! Audience !! Wallet Security !! Network Security !! Backups !! Setup Time !! Disk Space !! Maturity !! Multi-user !! Available for
|-
! Armory
|| [http://bitcoinarmory.com/index.php/get-armory Download] || Power users || {{CLGood|Encrypted, on-device}} || Addon || {{CLBest|One-time}} || Varies || {{CLBad|6+ GB}} || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLWin}}
|-
! Bitcoin Wallet
|| [https://play.google.com/store/apps/details?id=de.schildbach.wallet Google Play] [https://appworld.blackberry.com/webstore/content/23952882/ BlackBerry World] || {{CLBest|Everyone}} || {{CLGood|Isolated, on-device}} || Partial || Manual || 1 hour || 30 MB || {{CLGood|Mar 2011}} || on JB tablets || {{CLAndroid}} [[file:ico-blackberry.png]]
|-
! {{CLGood|Bitcoin-Qt}}
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || {{CLGood|End-users}} || {{CLGood|Encrypted, on-device}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|6+ GB}} || {{CLGood|May 2011}} || No || {{CLLinux}}{{CLMac}}{{CLWin}}
|-
! bitcoind
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || Programmers || {{CLGood|Encrypted, on-device}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|6+ GB}} || {{CLBest|Aug 2009}} || {{CLGood|Virtual accounts}} || {{CLLinux}}{{CLWin}}
|-
! Electrum
|| [http://ecdsa.org/electrum/ Download] || Power users || {{CLGood|Encrypted, on-device}} || Minimal || {{CLBest|Memorized}} || {{CLGood|Minutes}} || {{CLGood|5 MB}} || Nov 2011 || No || {{CLLinux}}{{CLMac}}{{CLWin}}
|-
! MultiBit
|| [http://multibit.org/releases.html Download] || {{CLGood|End-users}} || {{CLBad|None, on-device}} || Partial || {{CLBad|No}} || {{CLBest|Seconds}} || 50 MB || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLMac}}{{CLWin}}
|-
! My Wallet
|| [https://blockchain.info/wallet/new Web-based] || {{CLBest|Everyone}} || Encrypted, on a server || {{CLBad|Remote}} || {{CLGood|Automatic}} || {{CLGood|Minutes}} || {{CLBest|None}} || Dec 2011 || {{CLBest|Yes}} || {{CLAndroid}}{{CLiOS}}{{CLLinux}}{{CLMac}}{{CLWin}}
|}



==For developers==

This table shows additional information about various Bitcoin clients that may be relevant to developers.

{| class='wikitable' style='text-align: center'
! Client !! Website !! Source Code !! License !! Discussion !! Architecture
|-
! Armory
|| [http://bitcoinarmory.com/ Link] ||[https://github.com/etotheipi/BitcoinArmory/ Github] || AGPLv3 || [https://bitcointalk.org/index.php?board=97.0 Bitcointalk] || Integrated
|-
! Bitcoin Wallet
|| [https://code.google.com/p/bitcoin-wallet/ Link] || [https://code.google.com/p/bitcoin-wallet/source/checkout Google Code] [https://github.com/schildbach/bitcoin-wallet Github] || GPLv3 || [https://bitcointalk.org/index.php?board=100.0 Bitcointalk] / [https://groups.google.com/forum/?fromgroups#!forum/bitcoinj Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]
|-
! Bitcoin-Qt / bitcoind
|| [http://bitcoin.org/ Link] || [https://github.com/bitcoin/bitcoin Github] || MIT || [https://lists.sourceforge.net/lists/listinfo/bitcoin-development Sourceforge] || Integrated
|-
! Electrum
|| [http://ecdsa.org/electrum/ Link] || [https://gitorious.org/electrum Gitorious] || GPLv3 || [https://lists.sourceforge.net/lists/listinfo/electrum-discuss Sourceforge] || [[Thin Client Security#Server-Trusting Clients|Server-Client]]
|-
! MultiBit
|| [http://multibit.org/ Link] || [https://github.com/jim618/multibit Github] || MIT || [https://groups.google.com/forum/?fromgroups#!forum/bitcoin-multibit Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]
|-
! My Wallet
|| [https://blockchain.info/wallet/ Link] || [https://github.com/blockchain/My-Wallet/ Github] || BSD* || None || [[Thin Client Security#Server-Trusting Clients|Server-Client]]
|-
! bits of proof
|| [https://bitsofproof Link] || [https://github.com/bitsofproof/supernode Github] || Apache 2.0 || [https://bitcointalk.org/index.php?topic=122013.0 Bitcointalk] || [[Thin Client Security#Server-Trusting Clients|Server-Client]]
|}

==See Also==
* [[Software#Bitcoin_clients|List of clients]]
* [[Bitcoin Ladder]]

<references/>

Protocol rules

2012-10-22T05:24:51Z

Grau: /* Block creation fee */

'''Rules''' for [[:Category:Clients|clients]].

The wiki substantially documents the [[Protocol_specification|Bitcoin protocol]], but equally important are the rules used by the client to process messages. It's crucial that clients follow certain rules in order to maintain consistency across the network, and to protect the Bitcoin security guarantees.

Here, the focus is on handling tx and block messages, because that is the tricky logic. This will skip over the method of requesting and forwarding these messages for now, and describe what to do when they are received. Also, this will describe the minimal data structures in rather abstract terms, ignoring the client's various indexes, maps and hash tables used for efficiency. This will be a conceptual description. This is all based on a fairly literal reading of the source code.

Mining (block generation) rules are not yet presented.

== Data structures ==

The main data structures are [[transactions]] and [[blocks]]. Blocks are composed of the ''block header'' followed by transactions in the block. Transactions are identified by their hash; blocks by the hash of their header. Blocks have prev pointers that link them into a graph.

Conceptually, the client has the following data structures:

=== Transactions ===

There are two collections of transactions:

;transaction pool
: an unordered collection of transactions that are not in blocks in the main chain, but for which we have input transactions

;orphan transactions
: transactions that can't go into the pool due to one or more missing input transactions

=== Blocks ===

There are 3 categories of blocks:

;blocks in the main branch
: the transactions in these blocks are considered at least tentatively confirmed

;blocks on side branches off the main branch
: these blocks have at least tentatively lost the race to be in the main branch

;orphan blocks
: these are blocks which don't link into the main branch, normally because of a missing predecessor or nth-level predecessor

Blocks in the first two categories form a tree rooted at the [[genesis block]], linked by the prev pointer, which points toward the root. (It is a very linear tree with few and short branches off the main branch.) The main branch is defined as the branch with highest total difficulty, summing the difficulties for each block in the branch.

See also [[Block Status]].

== Difficulty change ==

The difficulty changes every 2016 blocks. This choice is designed to occur approximately every two weeks.

: 2 weeks / 10 minutes = 14 * 24 * 60 / 10 = 2016

Once 2016 blocks has been reached we loop back until we hit the 2016th block before the current one. We find the difference in time between the current block and that one. This difference (called the actual timespan) is limited in bounds between [2 weeks/4, 2 weeks*4].

Then we get the last target for this old 2 week window and multiply it by the ratio of the actual timespan / the target timespan (2 weeks in secs).

: new target = old target * time for 2016 blocks / 2 weeks.

If the old set of blocks completed too fast then the target is lowered (difficulty goes up) ensuring it takes longer to solve these new blocks... and vice versa. This way the difficulty oscillates around the ideal of 2 weeks (and 10 mins per block).

== Block creation fee ==

The block creation fee changes at every 210000 blocks.
The block creation fee is a function of block height on the chain (genesis=0), and is calculated using 64 bit integer operations
(in satoshis) as:

(50 * 100000000) >> (height / 210000)

The block creation fee started with 50 BTC, will fall to 25 BTC at block 210000, 12.5 BTC at block 420000, finally down to 0 satoshi with block 6930000.
The block creation fee of all coinbase transactions will sum up to 2099999997690000 satoshis, practically 21million BTC.

== [[Protocol_specification#tx|"tx"]] messages ==

These messages hold a single transaction.

# Check syntactic correctness
# Make sure neither in or out lists are empty
# Size in bytes < MAX_BLOCK_SIZE
# Each output value, as well as the total, must be in legal money range
# Make sure none of the inputs have hash=0, n=-1 (''coinbase'' transactions)
# Check that nLockTime <= INT_MAX<ref>nLockTime must not exceed 31 bits, as some clients will interpret it incorrectly</ref>, size in bytes >= 100<ref>A valid transaction requires at least 100 bytes. If it's any less, the transaction is not valid</ref>, and sig opcount <= 2<ref>The number of signature operands in the signature (no, that is not redundant) for standard transactions will never exceed two</ref>
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms<ref>Note that this is not a hard requirement on clients.</ref>
# Reject if we already have matching tx in the pool, or in a block in the main branch
# Reject if any other tx in the pool uses the same transaction output as one used by this tx.<ref>Note that this is not a hard requirement on clients. The network-enforced rule is that only one transaction spending a particular output can be in the blockchain, thus preventing double-spending. Technically miners can choose which one they want to put into the block they're working on as long as no other transaction has spent that output either previously in the blockchain, or in the same block. The in-memory transaction pool can technically be managed in whatever way the miner is willing to implement.</ref>
# For each input, look in the main branch and the transaction pool to find the referenced output transaction. If the output transaction is missing for any input, this will be an orphan transaction. Add to the orphan transactions, if a matching transaction is not in there already.
# For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
# For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject this transaction
# Verify crypto signatures for each input; reject if any are bad
# For each input, if the referenced output has already been spent by a transaction in the main branch, reject this transaction<ref>This is the protection against double-spending</ref>
# Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
# Reject if the sum of input values < sum of output values
# Reject if transaction fee (defined as sum of input values minus sum of output values) would be too low to get into an empty block
# Add to transaction pool<ref>Note that when the transaction is accepted into the memory pool, an additional check is made to ensure that the coinbase value does not exceed the transaction fees plus the expected BTC value (50BTC as of this writing).</ref>
# "Add to wallet if mine"
# Relay transaction to peers
# For each orphan transaction that uses this one as one of its inputs, run all these steps (including this one) recursively on that orphan

===Explanation of Some Rules===
Most rules are self-explanatory. This section explains why some of the less obvious rules are in place.

== [[Protocol_specification#block|"block"]] messages ==

These messages hold a single block.

# Check syntactic correctness
# Reject if duplicate of block we have in any of the three categories
# Transaction list must be non-empty
# Block hash must satisfy claimed ''nBits'' proof of work
# Block timestamp must not be more than two hours in the future
# First transaction must be coinbase (i.e. only 1 input, with hash=0, n=-1), the rest must not be
# For each transaction, apply "tx" checks 2-4
# For the coinbase (first) transaction, scriptSig length must be 2-100
# Reject if sum of transaction sig opcounts > MAX_BLOCK_SIGOPS
# Verify Merkle hash
# Check if prev block (matching ''prev'' hash) is in main branch or side branches. If not, add this to orphan blocks, then query peer we got this from for 1st missing orphan block in ''prev'' chain; done with block
# Check that ''nBits'' value matches the difficulty rules
# Reject if timestamp is before the median time of the last 11 blocks
# For certain old blocks (i.e. on initial block download) check that hash matches known values
# Add block into the tree. There are three cases: 1. block further extends the main branch; 2. block extends a side branch but does not add enough difficulty to make it become the new main branch; 3. block extends a side branch and makes it the new main branch.
# For case 1, adding to main branch:
## For all but the coinbase transaction, apply the following:
### For each input, look in the main branch to find the referenced output transaction. Reject if the output transaction is missing for any input.
### For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject.
### For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject.
### Verify crypto signatures for each input; reject if any are bad
### For each input, if the referenced output has already been spent by a transaction in the main branch, reject
### Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
### Reject if the sum of input values < sum of output values
## Reject if coinbase value > sum of block creation fee and transaction fees
## (If we have not rejected):
## For each transaction, "Add to wallet if mine"
## For each transaction in the block, delete any matching transaction from the transaction pool
## Relay block to our peers
## If we rejected, the block is not counted as part of the main branch
# For case 2, adding to a side branch, we don't do anything.
# For case 3, a side branch becoming the main branch:
## Find the ''fork'' block on the main branch which this side branch forks off of
## Redefine the main branch to only go up to this ''fork'' block
## For each block on the side branch, from the child of the ''fork'' block to the leaf, add to the main branch:
### Do "branch" checks 3-11
### For all but the coinbase transaction, apply the following:
#### For each input, look in the main branch to find the referenced output transaction. Reject if the output transaction is missing for any input.
#### For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject.
#### For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject.
#### Verify crypto signatures for each input; reject if any are bad
#### For each input, if the referenced output has already been spent by a transaction in the main branch, reject
#### Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
#### Reject if the sum of input values < sum of output values
### Reject if coinbase value > sum of block creation fee and transaction fees
### (If we have not rejected):
### For each transaction, "Add to wallet if mine"
## If we reject at any point, leave the main branch as what it was originally, done with block
## For each block in the old main branch, from the leaf down to the child of the ''fork'' block:
### For each non-coinbase transaction in the block:
#### Apply "tx" checks 2-9, except in step 8, only look in the transaction pool for duplicates, not the main branch
#### Add to transaction pool if accepted, else go on to next transaction
## For each block in the new main branch, from the child of the ''fork'' node to the leaf:
### For each transaction in the block, delete any matching transaction from the transaction pool
## Relay block to our peers
# For each orphan block for which this block is its ''prev'', run all these steps (including this one) recursively on that orphan

== See Also ==

* [[Protocol specification]]
* [[Bitcoin Improvement Proposals]]

==References==
<references />

[[Category:Technical]][[Category:Developer]]

Protocol rules

2012-10-21T18:27:38Z

Grau: Used the term block creation fee as in other rules. Reverted change to rule 6 of block.

'''Rules''' for [[:Category:Clients|clients]].

The wiki substantially documents the [[Protocol_specification|Bitcoin protocol]], but equally important are the rules used by the client to process messages. It's crucial that clients follow certain rules in order to maintain consistency across the network, and to protect the Bitcoin security guarantees.

Here, the focus is on handling tx and block messages, because that is the tricky logic. This will skip over the method of requesting and forwarding these messages for now, and describe what to do when they are received. Also, this will describe the minimal data structures in rather abstract terms, ignoring the client's various indexes, maps and hash tables used for efficiency. This will be a conceptual description. This is all based on a fairly literal reading of the source code.

Mining (block generation) rules are not yet presented.

== Data structures ==

The main data structures are [[transactions]] and [[blocks]]. Blocks are composed of the ''block header'' followed by transactions in the block. Transactions are identified by their hash; blocks by the hash of their header. Blocks have prev pointers that link them into a graph.

Conceptually, the client has the following data structures:

=== Transactions ===

There are two collections of transactions:

;transaction pool
: an unordered collection of transactions that are not in blocks in the main chain, but for which we have input transactions

;orphan transactions
: transactions that can't go into the pool due to one or more missing input transactions

=== Blocks ===

There are 3 categories of blocks:

;blocks in the main branch
: the transactions in these blocks are considered at least tentatively confirmed

;blocks on side branches off the main branch
: these blocks have at least tentatively lost the race to be in the main branch

;orphan blocks
: these are blocks which don't link into the main branch, normally because of a missing predecessor or nth-level predecessor

Blocks in the first two categories form a tree rooted at the [[genesis block]], linked by the prev pointer, which points toward the root. (It is a very linear tree with few and short branches off the main branch.) The main branch is defined as the branch with highest total difficulty, summing the difficulties for each block in the branch.

See also [[Block Status]].

== Difficulty change ==

The difficulty changes every 2016 blocks. This choice is designed to occur approximately every two weeks.

: 2 weeks / 10 minutes = 14 * 24 * 60 / 10 = 2016

Once 2016 blocks has been reached we loop back until we hit the 2016th block before the current one. We find the difference in time between the current block and that one. This difference (called the actual timespan) is limited in bounds between [2 weeks/4, 2 weeks*4].

Then we get the last target for this old 2 week window and multiply it by the ratio of the actual timespan / the target timespan (2 weeks in secs).

: new target = old target * time for 2016 blocks / 2 weeks.

If the old set of blocks completed too fast then the target is lowered (difficulty goes up) ensuring it takes longer to solve these new blocks... and vice versa. This way the difficulty oscillates around the ideal of 2 weeks (and 10 mins per block).

== Block creation fee ==

The block creation fee changes at every 210000 blocks.
The block creation fee is a function of block height on the chain (genesis=0), and is calculated using 64 bit integer operations
(in satoshis) as:

(50 * 100000000) >> (height / 210000)

The block creation fee started with 50 BTC, will fall to 25 BTC at block 210000, 12 BTC at block 420000, finally down to 0 satoshi with block 6930000.
The block creation fee of all coinbase transactions will sum up to 2099999997690000 satoshis, practically 21million BTC.

== [[Protocol_specification#tx|"tx"]] messages ==

These messages hold a single transaction.

# Check syntactic correctness
# Make sure neither in or out lists are empty
# Size in bytes < MAX_BLOCK_SIZE
# Each output value, as well as the total, must be in legal money range
# Make sure none of the inputs have hash=0, n=-1 (''coinbase'' transactions)
# Check that nLockTime <= INT_MAX<ref>nLockTime must not exceed 31 bits, as some clients will interpret it incorrectly</ref>, size in bytes >= 100<ref>A valid transaction requires at least 100 bytes. If it's any less, the transaction is not valid</ref>, and sig opcount <= 2<ref>The number of signature operands in the signature (no, that is not redundant) for standard transactions will never exceed two</ref>
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms<ref>Note that this is not a hard requirement on clients.</ref>
# Reject if we already have matching tx in the pool, or in a block in the main branch
# Reject if any other tx in the pool uses the same transaction output as one used by this tx.<ref>Note that this is not a hard requirement on clients. The network-enforced rule is that only one transaction spending a particular output can be in the blockchain, thus preventing double-spending. Technically miners can choose which one they want to put into the block they're working on as long as no other transaction has spent that output either previously in the blockchain, or in the same block. The in-memory transaction pool can technically be managed in whatever way the miner is willing to implement.</ref>
# For each input, look in the main branch and the transaction pool to find the referenced output transaction. If the output transaction is missing for any input, this will be an orphan transaction. Add to the orphan transactions, if a matching transaction is not in there already.
# For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
# For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject this transaction
# Verify crypto signatures for each input; reject if any are bad
# For each input, if the referenced output has already been spent by a transaction in the main branch, reject this transaction<ref>This is the protection against double-spending</ref>
# Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
# Reject if the sum of input values < sum of output values
# Reject if transaction fee (defined as sum of input values minus sum of output values) would be too low to get into an empty block
# Add to transaction pool<ref>Note that when the transaction is accepted into the memory pool, an additional check is made to ensure that the coinbase value does not exceed the transaction fees plus the expected BTC value (50BTC as of this writing).</ref>
# "Add to wallet if mine"
# Relay transaction to peers
# For each orphan transaction that uses this one as one of its inputs, run all these steps (including this one) recursively on that orphan

===Explanation of Some Rules===
Most rules are self-explanatory. This section explains why some of the less obvious rules are in place.

== [[Protocol_specification#block|"block"]] messages ==

These messages hold a single block.

# Check syntactic correctness
# Reject if duplicate of block we have in any of the three categories
# Transaction list must be non-empty
# Block hash must satisfy claimed ''nBits'' proof of work
# Block timestamp must not be more than two hours in the future
# First transaction must be coinbase (i.e. only 1 input, with hash=0, n=-1), the rest must not be
# For each transaction, apply "tx" checks 2-4
# For the coinbase (first) transaction, scriptSig length must be 2-100
# Reject if sum of transaction sig opcounts > MAX_BLOCK_SIGOPS
# Verify Merkle hash
# Check if prev block (matching ''prev'' hash) is in main branch or side branches. If not, add this to orphan blocks, then query peer we got this from for 1st missing orphan block in ''prev'' chain; done with block
# Check that ''nBits'' value matches the difficulty rules
# Reject if timestamp is before the median time of the last 11 blocks
# For certain old blocks (i.e. on initial block download) check that hash matches known values
# Add block into the tree. There are three cases: 1. block further extends the main branch; 2. block extends a side branch but does not add enough difficulty to make it become the new main branch; 3. block extends a side branch and makes it the new main branch.
# For case 1, adding to main branch:
## For all but the coinbase transaction, apply the following:
### For each input, look in the main branch to find the referenced output transaction. Reject if the output transaction is missing for any input.
### For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject.
### For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject.
### Verify crypto signatures for each input; reject if any are bad
### For each input, if the referenced output has already been spent by a transaction in the main branch, reject
### Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
### Reject if the sum of input values < sum of output values
## Reject if coinbase value > sum of block creation fee and transaction fees
## (If we have not rejected):
## For each transaction, "Add to wallet if mine"
## For each transaction in the block, delete any matching transaction from the transaction pool
## Relay block to our peers
## If we rejected, the block is not counted as part of the main branch
# For case 2, adding to a side branch, we don't do anything.
# For case 3, a side branch becoming the main branch:
## Find the ''fork'' block on the main branch which this side branch forks off of
## Redefine the main branch to only go up to this ''fork'' block
## For each block on the side branch, from the child of the ''fork'' block to the leaf, add to the main branch:
### Do "branch" checks 3-11
### For all but the coinbase transaction, apply the following:
#### For each input, look in the main branch to find the referenced output transaction. Reject if the output transaction is missing for any input.
#### For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject.
#### For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject.
#### Verify crypto signatures for each input; reject if any are bad
#### For each input, if the referenced output has already been spent by a transaction in the main branch, reject
#### Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
#### Reject if the sum of input values < sum of output values
### Reject if coinbase value > sum of block creation fee and transaction fees
### (If we have not rejected):
### For each transaction, "Add to wallet if mine"
## If we reject at any point, leave the main branch as what it was originally, done with block
## For each block in the old main branch, from the leaf down to the child of the ''fork'' block:
### For each non-coinbase transaction in the block:
#### Apply "tx" checks 2-9, except in step 8, only look in the transaction pool for duplicates, not the main branch
#### Add to transaction pool if accepted, else go on to next transaction
## For each block in the new main branch, from the child of the ''fork'' node to the leaf:
### For each transaction in the block, delete any matching transaction from the transaction pool
## Relay block to our peers
# For each orphan block for which this block is its ''prev'', run all these steps (including this one) recursively on that orphan

== See Also ==

* [[Protocol specification]]
* [[Bitcoin Improvement Proposals]]

==References==
<references />

[[Category:Technical]][[Category:Developer]]

Protocol rules

2012-10-21T18:01:07Z

Grau: Added coinbase value rule in a new section. Added coinbase output value check in block rule 6.

'''Rules''' for [[:Category:Clients|clients]].

The wiki substantially documents the [[Protocol_specification|Bitcoin protocol]], but equally important are the rules used by the client to process messages. It's crucial that clients follow certain rules in order to maintain consistency across the network, and to protect the Bitcoin security guarantees.

Here, the focus is on handling tx and block messages, because that is the tricky logic. This will skip over the method of requesting and forwarding these messages for now, and describe what to do when they are received. Also, this will describe the minimal data structures in rather abstract terms, ignoring the client's various indexes, maps and hash tables used for efficiency. This will be a conceptual description. This is all based on a fairly literal reading of the source code.

Mining (block generation) rules are not yet presented.

== Data structures ==

The main data structures are [[transactions]] and [[blocks]]. Blocks are composed of the ''block header'' followed by transactions in the block. Transactions are identified by their hash; blocks by the hash of their header. Blocks have prev pointers that link them into a graph.

Conceptually, the client has the following data structures:

=== Transactions ===

There are two collections of transactions:

;transaction pool
: an unordered collection of transactions that are not in blocks in the main chain, but for which we have input transactions

;orphan transactions
: transactions that can't go into the pool due to one or more missing input transactions

=== Blocks ===

There are 3 categories of blocks:

;blocks in the main branch
: the transactions in these blocks are considered at least tentatively confirmed

;blocks on side branches off the main branch
: these blocks have at least tentatively lost the race to be in the main branch

;orphan blocks
: these are blocks which don't link into the main branch, normally because of a missing predecessor or nth-level predecessor

Blocks in the first two categories form a tree rooted at the [[genesis block]], linked by the prev pointer, which points toward the root. (It is a very linear tree with few and short branches off the main branch.) The main branch is defined as the branch with highest total difficulty, summing the difficulties for each block in the branch.

See also [[Block Status]].

== Difficulty change ==

The difficulty changes every 2016 blocks. This choice is designed to occur approximately every two weeks.

: 2 weeks / 10 minutes = 14 * 24 * 60 / 10 = 2016

Once 2016 blocks has been reached we loop back until we hit the 2016th block before the current one. We find the difference in time between the current block and that one. This difference (called the actual timespan) is limited in bounds between [2 weeks/4, 2 weeks*4].

Then we get the last target for this old 2 week window and multiply it by the ratio of the actual timespan / the target timespan (2 weeks in secs).

: new target = old target * time for 2016 blocks / 2 weeks.

If the old set of blocks completed too fast then the target is lowered (difficulty goes up) ensuring it takes longer to solve these new blocks... and vice versa. This way the difficulty oscillates around the ideal of 2 weeks (and 10 mins per block).

== Coinbase value change ==

The output value of the coinbase transaction of a block, changes at every 210000 blocks.
The output value is a function of block height on the chain (genesis=0), and is calculated using 64 bit integer operations
(in satoshis) as:

(50 * 100000000) >> (height / 210000)

The output value started with 50 BTC, will fall to 25 BTC at block 210000, 12 BTC at block 420000, finally down to 0 satoshi with block 6930000.
The output value of all coinbase transactions will sum up to 2099999997690000 satoshis, practically 21million BTC.

== [[Protocol_specification#tx|"tx"]] messages ==

These messages hold a single transaction.

# Check syntactic correctness
# Make sure neither in or out lists are empty
# Size in bytes < MAX_BLOCK_SIZE
# Each output value, as well as the total, must be in legal money range
# Make sure none of the inputs have hash=0, n=-1 (''coinbase'' transactions)
# Check that nLockTime <= INT_MAX<ref>nLockTime must not exceed 31 bits, as some clients will interpret it incorrectly</ref>, size in bytes >= 100<ref>A valid transaction requires at least 100 bytes. If it's any less, the transaction is not valid</ref>, and sig opcount <= 2<ref>The number of signature operands in the signature (no, that is not redundant) for standard transactions will never exceed two</ref>
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms<ref>Note that this is not a hard requirement on clients.</ref>
# Reject if we already have matching tx in the pool, or in a block in the main branch
# Reject if any other tx in the pool uses the same transaction output as one used by this tx.<ref>Note that this is not a hard requirement on clients. The network-enforced rule is that only one transaction spending a particular output can be in the blockchain, thus preventing double-spending. Technically miners can choose which one they want to put into the block they're working on as long as no other transaction has spent that output either previously in the blockchain, or in the same block. The in-memory transaction pool can technically be managed in whatever way the miner is willing to implement.</ref>
# For each input, look in the main branch and the transaction pool to find the referenced output transaction. If the output transaction is missing for any input, this will be an orphan transaction. Add to the orphan transactions, if a matching transaction is not in there already.
# For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
# For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject this transaction
# Verify crypto signatures for each input; reject if any are bad
# For each input, if the referenced output has already been spent by a transaction in the main branch, reject this transaction<ref>This is the protection against double-spending</ref>
# Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
# Reject if the sum of input values < sum of output values
# Reject if transaction fee (defined as sum of input values minus sum of output values) would be too low to get into an empty block
# Add to transaction pool<ref>Note that when the transaction is accepted into the memory pool, an additional check is made to ensure that the coinbase value does not exceed the transaction fees plus the expected BTC value (50BTC as of this writing).</ref>
# "Add to wallet if mine"
# Relay transaction to peers
# For each orphan transaction that uses this one as one of its inputs, run all these steps (including this one) recursively on that orphan

===Explanation of Some Rules===
Most rules are self-explanatory. This section explains why some of the less obvious rules are in place.

== [[Protocol_specification#block|"block"]] messages ==

These messages hold a single block.

# Check syntactic correctness
# Reject if duplicate of block we have in any of the three categories
# Transaction list must be non-empty
# Block hash must satisfy claimed ''nBits'' proof of work
# Block timestamp must not be more than two hours in the future
# First transaction must be coinbase with the right output value for the height (i.e. only 1 input, with hash=0, n=-1), the rest must not be
# For each transaction, apply "tx" checks 2-4
# For the coinbase (first) transaction, scriptSig length must be 2-100
# Reject if sum of transaction sig opcounts > MAX_BLOCK_SIGOPS
# Verify Merkle hash
# Check if prev block (matching ''prev'' hash) is in main branch or side branches. If not, add this to orphan blocks, then query peer we got this from for 1st missing orphan block in ''prev'' chain; done with block
# Check that ''nBits'' value matches the difficulty rules
# Reject if timestamp is before the median time of the last 11 blocks
# For certain old blocks (i.e. on initial block download) check that hash matches known values
# Add block into the tree. There are three cases: 1. block further extends the main branch; 2. block extends a side branch but does not add enough difficulty to make it become the new main branch; 3. block extends a side branch and makes it the new main branch.
# For case 1, adding to main branch:
## For all but the coinbase transaction, apply the following:
### For each input, look in the main branch to find the referenced output transaction. Reject if the output transaction is missing for any input.
### For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject.
### For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject.
### Verify crypto signatures for each input; reject if any are bad
### For each input, if the referenced output has already been spent by a transaction in the main branch, reject
### Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
### Reject if the sum of input values < sum of output values
## Reject if coinbase value > sum of block creation fee and transaction fees
## (If we have not rejected):
## For each transaction, "Add to wallet if mine"
## For each transaction in the block, delete any matching transaction from the transaction pool
## Relay block to our peers
## If we rejected, the block is not counted as part of the main branch
# For case 2, adding to a side branch, we don't do anything.
# For case 3, a side branch becoming the main branch:
## Find the ''fork'' block on the main branch which this side branch forks off of
## Redefine the main branch to only go up to this ''fork'' block
## For each block on the side branch, from the child of the ''fork'' block to the leaf, add to the main branch:
### Do "branch" checks 3-11
### For all but the coinbase transaction, apply the following:
#### For each input, look in the main branch to find the referenced output transaction. Reject if the output transaction is missing for any input.
#### For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject.
#### For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject.
#### Verify crypto signatures for each input; reject if any are bad
#### For each input, if the referenced output has already been spent by a transaction in the main branch, reject
#### Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
#### Reject if the sum of input values < sum of output values
### Reject if coinbase value > sum of block creation fee and transaction fees
### (If we have not rejected):
### For each transaction, "Add to wallet if mine"
## If we reject at any point, leave the main branch as what it was originally, done with block
## For each block in the old main branch, from the leaf down to the child of the ''fork'' block:
### For each non-coinbase transaction in the block:
#### Apply "tx" checks 2-9, except in step 8, only look in the transaction pool for duplicates, not the main branch
#### Add to transaction pool if accepted, else go on to next transaction
## For each block in the new main branch, from the child of the ''fork'' node to the leaf:
### For each transaction in the block, delete any matching transaction from the transaction pool
## Relay block to our peers
# For each orphan block for which this block is its ''prev'', run all these steps (including this one) recursively on that orphan

== See Also ==

* [[Protocol specification]]
* [[Bitcoin Improvement Proposals]]

==References==
<references />

[[Category:Technical]][[Category:Developer]]