arno/bitcoinbook
1
0
Fork 0
mirror of https://github.com/bitcoinbook/bitcoinbook synced 2024-12-23 07:08:13 +00:00
Code Issues Releases Wiki Activity

fixup BIP notation and files. Removed old and unecessary files too

Browse Source
This commit is contained in:
Andreas M. Antonopoulos 2016-10-07 10:22:34 +02:00
parent 49d8e40d01
commit f2732cda25
51 changed files with 77 additions and 12792 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
appdx-bips.asciidoc
View File

@ -4,7 +4,7 @@
((("Bitcoin improvement proposals", id="ix_appdx-bips-asciidoc0", range="startofrange")))Bitcoin improvement proposals are design documents providing information to the bitcoin community, or describing a new feature for bitcoin or its processes or environment.
As per BIP0001 _BIP Purpose and Guidelines_, there are three kinds of BIP:
As per BIP-01 _BIP Purpose and Guidelines_, there are three kinds of BIP:
_Standard_ BIP:: Describes any change that affects most or all bitcoin implementations, such as a change to the network protocol, a change in block or transaction validity rules, or any change or addition that affects the interoperability of applications using bitcoin.
_Informational_ BIP:: Describes a bitcoin design issue, or provides general guidelines or information to the bitcoin community, but does not propose a new feature. Informational BIPs do not necessarily represent a bitcoin community consensus or recommendation, so users and implementors may ignore informational BIPs or follow their advice.
@ -17,120 +17,120 @@ Bitcoin improvement proposals are recorded in a versioned repository on https://
[options="header"]
|=======================================================================
|BIP# | Link | Title |Owner |Type |Status
|[[bip0001]]1|https://github.com/bitcoin/bips/blob/master/bip-0001.mediawiki|BIP Purpose and Guidelines |Amir Taaki
|[[bip-01]]1|https://github.com/bitcoin/bips/blob/master/bip-0001.mediawiki|BIP Purpose and Guidelines |Amir Taaki
|Standard |Active
|[[bip0010]]10|https://github.com/bitcoin/bips/blob/master/bip-0010.mediawiki|Multi-Sig Transaction Distribution |Alan
|[[bip-10]]10|https://github.com/bitcoin/bips/blob/master/bip-0010.mediawiki|Multi-Sig Transaction Distribution |Alan
Reiner |Informational |Draft
|[[bip0011]]11|https://github.com/bitcoin/bips/blob/master/bip-0011.mediawiki|M-of-N Standard Transactions |Gavin
|[[bip-11]]11|https://github.com/bitcoin/bips/blob/master/bip-0011.mediawiki|M-of-N Standard Transactions |Gavin
Andresen |Standard |Accepted
|[[bip0012]]12|https://github.com/bitcoin/bips/blob/master/bip-0012.mediawiki|OP_EVAL |Gavin Andresen |Standard
|[[bip-12]]12|https://github.com/bitcoin/bips/blob/master/bip-0012.mediawiki|OP_EVAL |Gavin Andresen |Standard
|Withdrawn
|[[bip0013]]13|https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki|Address Format for pay-to-script-hash
|[[bip-13]]13|https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki|Address Format for pay-to-script-hash
|Gavin Andresen |Standard |Final
|[[bip0014]]14|https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki|Protocol Version and User Agent |Amir
|[[bip-14]]14|https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki|Protocol Version and User Agent |Amir
Taaki, Patrick Strateman |Standard |Accepted
|[[bip0015]]15|https://github.com/bitcoin/bips/blob/master/bip-0015.mediawiki|Aliases |Amir Taaki |Standard |Withdrawn
|[[bip-15]]15|https://github.com/bitcoin/bips/blob/master/bip-0015.mediawiki|Aliases |Amir Taaki |Standard |Withdrawn
|[[bip0016]]16|https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki|Pay To Script Hash |Gavin Andresen
|[[bip-16]]16|https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki|Pay To Script Hash |Gavin Andresen
|Standard |Accepted
|[[bip0017]]17|https://github.com/bitcoin/bips/blob/master/bip-0017.mediawiki|OP_CHECKHASHVERIFY (CHV) |Luke Dashjr
|[[bip-17]]17|https://github.com/bitcoin/bips/blob/master/bip-0017.mediawiki|OP_CHECKHASHVERIFY (CHV) |Luke Dashjr
|Withdrawn |Draft
|[[bip0018]]18|https://github.com/bitcoin/bips/blob/master/bip-0018.mediawikilink:|hashScriptCheck |Luke Dashjr |Standard
|[[bip-18]]18|https://github.com/bitcoin/bips/blob/master/bip-0018.mediawikilink:|hashScriptCheck |Luke Dashjr |Standard
|Draft
|[[bip0019]]19|https://github.com/bitcoin/bips/blob/master/bip-0019.mediawiki|M-of-N Standard Transactions (Low SigOp)
|[[bip-19]]19|https://github.com/bitcoin/bips/blob/master/bip-0019.mediawiki|M-of-N Standard Transactions (Low SigOp)
|Luke Dashjr |Standard |Draft
|[[bip0020]]20|https://github.com/bitcoin/bips/blob/master/bip-0020.mediawiki|URI Scheme |Luke Dashjr |Standard
|[[bip-20]]20|https://github.com/bitcoin/bips/blob/master/bip-0020.mediawiki|URI Scheme |Luke Dashjr |Standard
|Replaced
|[[bip0021]]21|https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki|URI Scheme |Nils Schneider, Matt Corallo
|[[bip-21]]21|https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki|URI Scheme |Nils Schneider, Matt Corallo
|Standard |Accepted
|[[bip0022]]22|https://github.com/bitcoin/bips/blob/master/bip-0022.mediawiki|getblocktemplate - Fundamentals |Luke
|[[bip-22]]22|https://github.com/bitcoin/bips/blob/master/bip-0022.mediawiki|getblocktemplate - Fundamentals |Luke
Dashjr |Standard |Accepted
|[[bip0023]]23|https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki|getblocktemplate - Pooled Mining |Luke
|[[bip-23]]23|https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki|getblocktemplate - Pooled Mining |Luke
Dashjr |Standard |Accepted
|[[bip0030]]30|https://github.com/bitcoin/bips/blob/master/bip-0030.mediawiki|Duplicate transactions |Pieter Wuille
|[[bip-30]]30|https://github.com/bitcoin/bips/blob/master/bip-0030.mediawiki|Duplicate transactions |Pieter Wuille
|Standard |Accepted
|[[bip0031]]31|https://github.com/bitcoin/bips/blob/master/bip-0031.mediawiki|Pong message |Mike Hearn |Standard
|[[bip-31]]31|https://github.com/bitcoin/bips/blob/master/bip-0031.mediawiki|Pong message |Mike Hearn |Standard
|Accepted
|[[bip0032]]32|https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki|Hierarchical Deterministic Wallets |Pieter
|[[bip-32]]32|https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki|Hierarchical Deterministic Wallets |Pieter
Wuille |Informational |Accepted
|[[bip0033]]33|https://github.com/bitcoin/bips/blob/master/bip-0033.mediawiki|Stratized Nodes |Amir Taaki |Standard
|[[bip-33]]33|https://github.com/bitcoin/bips/blob/master/bip-0033.mediawiki|Stratized Nodes |Amir Taaki |Standard
|Draft
|[[bip0034]]34|https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki|Block v2, Height in coinbase |Gavin
|[[bip-34]]34|https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki|Block v2, Height in coinbase |Gavin
Andresen |Standard |Accepted
|[[bip0035]]35|https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki|mempool message |Jeff Garzik |Standard
|[[bip-35]]35|https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki|mempool message |Jeff Garzik |Standard
|Accepted
|[[bip0036]]36|https://github.com/bitcoin/bips/blob/master/bip-0036.mediawiki|Custom Services |Stefan Thomas |Standard
|[[bip-36]]36|https://github.com/bitcoin/bips/blob/master/bip-0036.mediawiki|Custom Services |Stefan Thomas |Standard
|Draft
|[[bip0037]]37|https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki|Bloom filtering |Mike Hearn and Matt
|[[bip-37]]37|https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki|Bloom filtering |Mike Hearn and Matt
Corallo |Standard |Accepted
|[[bip0038]]38|https://github.com/bitcoin/bips/blob/master/bip-0038.mediawiki|Passphrase-protected private key |Mike
|[[bip-38]]38|https://github.com/bitcoin/bips/blob/master/bip-0038.mediawiki|Passphrase-protected private key |Mike
Caldwell |Standard |Draft
|[[bip0039]]39|https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki|Mnemonic code for generating deterministic
|[[bip-39]]39|https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki|Mnemonic code for generating deterministic
keys |Slush |Standard |Draft
|[[bip0040]]40||Stratum wire protocol |Slush |Standard |BIP number allocated
|[[bip-40]]40||Stratum wire protocol |Slush |Standard |BIP number allocated
|[[bip0041]]41||Stratum mining protocol |Slush |Standard |BIP number allocated
|[[bip-41]]41||Stratum mining protocol |Slush |Standard |BIP number allocated
|[[bip0042]]42|https://github.com/bitcoin/bips/blob/master/bip-0042.mediawiki|A finite monetary supply for bitcoin
|[[bip-42]]42|https://github.com/bitcoin/bips/blob/master/bip-0042.mediawiki|A finite monetary supply for bitcoin
|Pieter Wuille |Standard |Draft
|[[bip0043]]43|https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki|Purpose Field for Deterministic Wallets
|[[bip-43]]43|https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki|Purpose Field for Deterministic Wallets
|Slush |Standard |Draft
|[[bip0044]]44|https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki|Multi-Account Hierarchy for Deterministic
|[[bip-44]]44|https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki|Multi-Account Hierarchy for Deterministic
Wallets |Slush |Standard |Draft
|[[bip0050]]50|https://github.com/bitcoin/bips/blob/master/bip-0050.mediawiki|March 2013 Chain Fork Post-Mortem |Gavin
|[[bip-50]]50|https://github.com/bitcoin/bips/blob/master/bip-0050.mediawiki|March 2013 Chain Fork Post-Mortem |Gavin
Andresen |Informational |Draft
|[[bip0060]]60|https://github.com/bitcoin/bips/blob/master/bip-0060.mediawiki|Fixed Length "version" Message
|[[bip-60]]60|https://github.com/bitcoin/bips/blob/master/bip-0060.mediawiki|Fixed Length "version" Message
(Relay-Transactions Field) |Amir Taaki |Standard |Draft
|[[bip0061]]61|https://github.com/bitcoin/bips/blob/master/bip-0061.mediawiki|"reject" P2P message |Gavin Andresen
|[[bip-61]]61|https://github.com/bitcoin/bips/blob/master/bip-0061.mediawiki|"reject" P2P message |Gavin Andresen
|Standard |Draft
|[[bip0062]]62|https://github.com/bitcoin/bips/blob/master/bip-0062.mediawiki|Dealing with malleability |Pieter Wuille
|[[bip-62]]62|https://github.com/bitcoin/bips/blob/master/bip-0062.mediawiki|Dealing with malleability |Pieter Wuille
|Standard |Draft
|[[bip0063]]63||Stealth Addresses |Peter Todd |Standard |BIP number allocated
|[[bip-63]]63||Stealth Addresses |Peter Todd |Standard |BIP number allocated
|[[bip0064]]64|https://github.com/bitcoin/bips/blob/master/bip-0064.mediawiki|getutxos message |Mike Hearn |Standard
|[[bip-64]]64|https://github.com/bitcoin/bips/blob/master/bip-0064.mediawiki|getutxos message |Mike Hearn |Standard
|Draft
|[[bip0070]]70|https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki|Payment protocol |Gavin Andresen |Standard
|[[bip-70]]70|https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki|Payment protocol |Gavin Andresen |Standard
|Draft
|[[bip0071]]71|https://github.com/bitcoin/bips/blob/master/bip-0071.mediawiki|Payment protocol MIME types |Gavin
|[[bip-71]]71|https://github.com/bitcoin/bips/blob/master/bip-0071.mediawiki|Payment protocol MIME types |Gavin
Andresen |Standard |Draft
|[[bip0072]]72|https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki|Payment protocol URIs |Gavin Andresen
|[[bip-72]]72|https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki|Payment protocol URIs |Gavin Andresen
|Standard |Draft
|[[bip0073]]73|https://github.com/bitcoin/bips/blob/master/bip-0073.mediawiki|Use "Accept" header with Payment Request
|[[bip-73]]73|https://github.com/bitcoin/bips/blob/master/bip-0073.mediawiki|Use "Accept" header with Payment Request
URLs |Stephen Pair |Standard |Draft(((range="endofrange", startref="ix_appdx-bips-asciidoc0")))
|=======================================================================

2
appdx-bx.asciidoc
View File

@ -114,7 +114,7 @@ $ bx ec-to-address < public_key
17re1S4Q8ZHyCP8Kw7xQad1Lr6XUzWUnkG
----
Keys generated in this manner produce a type-0 nondeterministic wallet. That means that each key is generated from an independent seed. Bitcoin Explorer commands can also generate keys deterministically, in accordance with BIP0032. In this case, a "master" key is created from a seed and then extended deterministically to produce a tree of subkeys, resulting in a type-2 deterministic wallet.
Keys generated in this manner produce a type-0 nondeterministic wallet. That means that each key is generated from an independent seed. Bitcoin Explorer commands can also generate keys deterministically, in accordance with BIP-32. In this case, a "master" key is created from a seed and then extended deterministically to produce a tree of subkeys, resulting in a type-2 deterministic wallet.
First, we we use the((("Bitcoin Explorer","seed command")))((("seed command (bx)"))) +seed+ and((("Bitcoin Explorer","hd-new command")))((("hd-new command (bx)"))) +hd-new+ commands to generate a master key that will be used as the basis to derive a hierarchy of keys.

81
appdx01.asciidoc
View File

@ -1,81 +0,0 @@
[[appdx01]]
[appendix]
== Bitcoin financial services
This appendix describes the main financial services offered in the bitcoin economy, comparing them to traditional financial services that are already familiar to consumers. It's not a list of sites or companies, as that would go stale immediately. Instead it is a list of service primitives with examples of existing implementations. For example, an escrow
service would be described as an archetype, by analogy to a real-estate escrow, showing the unique characteristics, use case and need for escrow in the bitcoin world. The escrow service archetype would be followed by two or three examples of well implemented actual escrow services, each demonstrating a capability unique to bitcoin.
=== Currency Exchanges
=== Bitcoin market data services
=== Bitcoin ticker, order book, chart and analysis services
=== Peer-to-peer exchange
=== OTC and Web-of-Trust (WoT)
=== Escrow services
=== Monitoring services
=== Alert and notification services
=== Lending
=== P2P Lending
=== Securities
=== Mutual Funds
=== Angel investing
== Appendix: Bitcoin markets and applications
As above, this appendix describes services offered in the bitcoin economy. Each service is described a a service archetype which is compared to a real-world example familiar to anyone. The description of such a service is followed by real-world examples that express
these bitcoin features.
=== Currency transfer
=== US domestic
=== Other in-country
=== International
=== Retail commerce
=== Physical (tangible) goods
=== Intangible products
=== Services
=== Technology services
=== Re-selling and Cross-selling
=== Wholesale commerce
== Appendix: Bitcoin Protocol Structure and Conventions
Reference index of main protocol primitives, packet structure, opcodes, state enumerations, protocol mechanics, time diagrams and protocol validation mechanisms.
== Appendix: Bitcoin Transaction Script Operands and Tokens
More reference material as above
== Appendix: Bitcoin Cryptography Algorithms, Conventions and Conversions.
More reference material as above
== Appendix: Bitcoin Meta-protocols: Mining Pool Protocols, Lightweight Client Protocols
More reference material as above

2
ch02.asciidoc
View File

@ -57,7 +57,7 @@ image::images/msbt_0202.png["payment-request"]
Try to scan this with your wallet!
====
[[payment-request-URL]]
.The payment request QR code encodes the following URL, defined in BIP0021:
.The payment request QR code encodes the following URL, defined in BIP-21:
----
bitcoin:1GdK9UzpHBzqzX2A9JFP3Di4weBwqgmoQA?
amount=0.015&

18
ch04.asciidoc
View File

@ -595,24 +595,24 @@ BTC public key: 029ade3effb0a67d5c8609850d797366af428f4a0d5194cb221d807770a15228
In the following sections we will look at advanced forms of keys and addresses, such as encrypted private keys, script and multisignature addresses, vanity addresses, and paper wallets.
==== Encrypted Private Keys (BIP0038)
==== Encrypted Private Keys (BIP-38)
((("BIP0038")))((("encrypted private keys")))((("private keys","encrypted")))((("security","encrypted private keys")))((("security","of private keys")))Private keys must remain secret. The need for _confidentiality_ of the private keys is a truism that is quite difficult to achieve in practice, because it conflicts with the equally important security objective of _availability_. ((("security","of wallet backups")))Keeping the private key private is much harder when you need to store backups of the private key to avoid losing it. A private key stored in a wallet that is encrypted by a password might be secure, but that wallet needs to be backed up. At times, users need to move keys from one wallet to another—to upgrade or replace the wallet software, for example. Private key backups might also be stored on paper (see <<paper_wallets>>) or on external storage media, such as a USB flash drive. But what if the backup itself is stolen or lost? These conflicting security goals led to the introduction of a portable and convenient standard for encrypting private keys in a way that can be understood by many different wallets and bitcoin clients, standardized by Bitcoin Improvement Proposal 38 or BIP0038 (see <<bip0038>>).
((("BIP-38")))((("encrypted private keys")))((("private keys","encrypted")))((("security","encrypted private keys")))((("security","of private keys")))Private keys must remain secret. The need for _confidentiality_ of the private keys is a truism that is quite difficult to achieve in practice, because it conflicts with the equally important security objective of _availability_. ((("security","of wallet backups")))Keeping the private key private is much harder when you need to store backups of the private key to avoid losing it. A private key stored in a wallet that is encrypted by a password might be secure, but that wallet needs to be backed up. At times, users need to move keys from one wallet to another—to upgrade or replace the wallet software, for example. Private key backups might also be stored on paper (see <<paper_wallets>>) or on external storage media, such as a USB flash drive. But what if the backup itself is stolen or lost? These conflicting security goals led to the introduction of a portable and convenient standard for encrypting private keys in a way that can be understood by many different wallets and bitcoin clients, standardized by Bitcoin Improvement Proposal 38 or BIP-38 (see <<bip-38>>).
BIP0038 proposes a common standard for encrypting private keys with a passphrase and encoding them with Base58Check so that they can be stored securely on backup media, transported securely between wallets, or kept in any other conditions where the key might be exposed. The standard for encryption uses the((("Advanced Encryption Standard (AES)"))) Advanced Encryption Standard (AES), a standard established by the National Institute of Standards and Technology (NIST) and used broadly in data encryption implementations for commercial and military applications.
BIP-38 proposes a common standard for encrypting private keys with a passphrase and encoding them with Base58Check so that they can be stored securely on backup media, transported securely between wallets, or kept in any other conditions where the key might be exposed. The standard for encryption uses the((("Advanced Encryption Standard (AES)"))) Advanced Encryption Standard (AES), a standard established by the National Institute of Standards and Technology (NIST) and used broadly in data encryption implementations for commercial and military applications.
((("Wallet Import Format (WIF)","from BIP0038 encryption")))A BIP0038 encryption scheme takes as input a bitcoin private key, usually encoded in the Wallet Import Format (WIF), as a Base58Check string with a prefix of "5". Additionally, the BIP0038 encryption scheme takes a passphrase—a long password—usually composed of several words or a complex string of alphanumeric characters. The result of the BIP0038 encryption scheme is a Base58Check-encoded encrypted private key that begins with the prefix +6P+. If you see a key that starts with +6P+, that means it is encrypted and requires a passphrase in order to convert (decrypt) it back into a WIF-formatted private key (prefix +5+) that can be used in any wallet. Many wallet applications now recognize BIP0038-encrypted private keys and will prompt the user for a passphrase to decrypt and import the key. Third-party applications, such as the incredibly useful browser-based http://bitaddress.org[Bit Address] (Wallet Details tab), can be used to decrypt BIP0038 keys.
((("Wallet Import Format (WIF)","from BIP-38 encryption")))A BIP-38 encryption scheme takes as input a bitcoin private key, usually encoded in the Wallet Import Format (WIF), as a Base58Check string with a prefix of "5". Additionally, the BIP-38 encryption scheme takes a passphrase—a long password—usually composed of several words or a complex string of alphanumeric characters. The result of the BIP-38 encryption scheme is a Base58Check-encoded encrypted private key that begins with the prefix +6P+. If you see a key that starts with +6P+, that means it is encrypted and requires a passphrase in order to convert (decrypt) it back into a WIF-formatted private key (prefix +5+) that can be used in any wallet. Many wallet applications now recognize BIP-38-encrypted private keys and will prompt the user for a passphrase to decrypt and import the key. Third-party applications, such as the incredibly useful browser-based http://bitaddress.org[Bit Address] (Wallet Details tab), can be used to decrypt BIP-38 keys.
((("paper wallets","BIP0038 encryption and")))The most common use case for BIP0038 encrypted keys is for paper wallets that can be used to back up private keys on a piece of paper. As long as the user selects a strong passphrase, a paper wallet with BIP0038 encrypted private keys is incredibly secure and a great way to create offline bitcoin storage (also known as "cold storage").
((("paper wallets","BIP-38 encryption and")))The most common use case for BIP-38 encrypted keys is for paper wallets that can be used to back up private keys on a piece of paper. As long as the user selects a strong passphrase, a paper wallet with BIP-38 encrypted private keys is incredibly secure and a great way to create offline bitcoin storage (also known as "cold storage").
Test the encrypted keys in <<table_4-10>> using((("bitaddress.org"))) bitaddress.org to see how you can get the decrypted key by entering the passphrase.
[[table_4-10]]
.Example of BIP0038 encrypted private key
.Example of BIP-38 encrypted private key
|=======
| *Private Key (WIF)* | 5J3mBbAH58CpQ3Y5RNJpUKPE62SQ5tfcvU2JpbnkeyhfsYB1Jcn
| *Passphrase* | MyTestPassphrase
| *Encrypted Key (BIP0038)* | 6PRTHL6mWa48xSopbU1cKrVjpKbBZxcLRRCdctLJ3z5yxE87MobKoXdTsJ
| *Encrypted Key (BIP-38)* | 6PRTHL6mWa48xSopbU1cKrVjpKbBZxcLRRCdctLJ3z5yxE87MobKoXdTsJ
|=======
@ -621,7 +621,7 @@ Test the encrypted keys in <<table_4-10>> using((("bitaddress.org"))) bitaddress
((("addresses, bitcoin","multi-signature addresses")))((("addresses, bitcoin","Pay-to-Script Hash (P2SH)")))((("multi-signature addresses")))((("Pay-to-Script Hash (P2SH)")))As we know, traditional bitcoin addresses begin with the number “1” and are derived from the public key, which is derived from the private key. Although anyone can send bitcoin to a “1” address, that bitcoin can only be spent by presenting the corresponding private key signature and public key hash.
Bitcoin addresses that begin with the number “3” are pay-to-script hash (P2SH) addresses, sometimes erroneously called multi-signature or multi-sig addresses. They designate the beneficiary of a bitcoin transaction as the hash of a script, instead of the owner of a public key. The feature was introduced in January 2012 with Bitcoin Improvement Proposal 16, or BIP0016 (see <<bip0016>>), and is being widely adopted because it provides the opportunity to add functionality to the address itself. Unlike transactions that "send" funds to traditional “1” bitcoin addresses, also known as((("BIP0016")))((("Pay-to-Public-Key-Hash (P2PKH)"))) pay-to-public-key-hash (P2PKH), funds sent to “3” addresses require something more than the presentation of one public key hash and one private key signature as proof of ownership. The requirements are designated at the time the address is created, within the script, and all inputs to this address will be encumbered with the same requirements.
Bitcoin addresses that begin with the number “3” are pay-to-script hash (P2SH) addresses, sometimes erroneously called multi-signature or multi-sig addresses. They designate the beneficiary of a bitcoin transaction as the hash of a script, instead of the owner of a public key. The feature was introduced in January 2012 with Bitcoin Improvement Proposal 16, or BIP-16 (see <<bip-16>>), and is being widely adopted because it provides the opportunity to add functionality to the address itself. Unlike transactions that "send" funds to traditional “1” bitcoin addresses, also known as((("BIP-16")))((("Pay-to-Public-Key-Hash (P2PKH)"))) pay-to-public-key-hash (P2PKH), funds sent to “3” addresses require something more than the presentation of one public key hash and one private key signature as proof of ownership. The requirements are designated at the time the address is created, within the script, and all inputs to this address will be encumbered with the same requirements.
A pay-to-script hash address is created from a transaction script, which defines who can spend a transaction output (for more detail, see <<p2sh>>). Encoding a pay-to-script hash address involves using the same double-hash function as used during creation of a bitcoin address, only applied on the script instead of the public key:
@ -782,7 +782,7 @@ Paper wallets come in many shapes, sizes, and designs, but at a very basic level
.An example of a simple paper wallet from bitaddress.org
image::images/msbt_0414.png[]
The disadvantage of the simple paper wallet system is that the printed keys are vulnerable to theft. A thief who is able to gain access to the paper can either steal it or photograph the keys and take control of the bitcoins locked with those keys. A more sophisticated paper wallet storage system uses BIP0038 encrypted private keys. The keys printed on the paper wallet are protected by a passphrase that the owner has memorized. Without the passphrase, the encrypted keys are useless. Yet, they still are superior to a passphrase-protected wallet because the keys have never been online and must be physically retrieved from a safe or other physically secured storage. <<paper_wallet_encrypted>> shows a paper wallet with an encrypted private key (BIP0038) created on the bitaddress.org site.
The disadvantage of the simple paper wallet system is that the printed keys are vulnerable to theft. A thief who is able to gain access to the paper can either steal it or photograph the keys and take control of the bitcoins locked with those keys. A more sophisticated paper wallet storage system uses BIP-38 encrypted private keys. The keys printed on the paper wallet are protected by a passphrase that the owner has memorized. Without the passphrase, the encrypted keys are useless. Yet, they still are superior to a passphrase-protected wallet because the keys have never been online and must be physically retrieved from a safe or other physically secured storage. <<paper_wallet_encrypted>> shows a paper wallet with an encrypted private key (BIP-38) created on the bitaddress.org site.
[[paper_wallet_encrypted]]
.An example of an encrypted paper wallet from bitaddress.org. The passphrase is "test."

2
ch05-orig.asciidoc
View File

@ -561,7 +561,7 @@ If the redeem script hash matches, the unlocking script is executed on its own,
===== Pay-to-script-hash addresses
((("addresses, bitcoin","Pay-to-Script-Hash (P2SH)")))((("Pay-to-script-hash (P2SH)","addresses")))Another important part of the P2SH feature is the ability to encode a script hash as an address, as defined in BIP0013. P2SH addresses are Base58Check encodings of the 20-byte hash of a script, just like bitcoin addresses are Base58Check encodings of the 20-byte hash of a public key. P2SH addresses use the version prefix "5", which results in Base58Check-encoded addresses that start with a "3". For example, Mohammed's complex script, hashed and Base58Check-encoded as a P2SH address becomes +39RF6JqABiHdYHkfChV6USGMe6Nsr66Gzw+. Now, Mohammed can give this "address" to his customers and they can use almost any bitcoin wallet to make a simple payment, as if it were a bitcoin address. The 3 prefix gives them a hint that this is a special type of address, one corresponding to a script instead of a public key, but otherwise it works in exactly the same way as a payment to a bitcoin address.
((("addresses, bitcoin","Pay-to-Script-Hash (P2SH)")))((("Pay-to-script-hash (P2SH)","addresses")))Another important part of the P2SH feature is the ability to encode a script hash as an address, as defined in BIP-13. P2SH addresses are Base58Check encodings of the 20-byte hash of a script, just like bitcoin addresses are Base58Check encodings of the 20-byte hash of a public key. P2SH addresses use the version prefix "5", which results in Base58Check-encoded addresses that start with a "3". For example, Mohammed's complex script, hashed and Base58Check-encoded as a P2SH address becomes +39RF6JqABiHdYHkfChV6USGMe6Nsr66Gzw+. Now, Mohammed can give this "address" to his customers and they can use almost any bitcoin wallet to make a simple payment, as if it were a bitcoin address. The 3 prefix gives them a hint that this is a special type of address, one corresponding to a script instead of a public key, but otherwise it works in exactly the same way as a payment to a bitcoin address.
P2SH addresses hide all of the complexity, so that the person making a payment does not see the script.

38
ch05.asciidoc
View File

@ -46,7 +46,7 @@ image::images/deterministic_wallet.png["Deterministic Wallet"]
==== Seeds and Mnemonic Code Words
Deterministic wallets are a very powerful model for managing many keys and addresses. They are even more useful if they are combined with a standardized way of creating seeds from a sequence of english words that are easy to transcribe, export and import across wallets. This is known as a _mnemonic_ and the standard is defined by BIP0039. Today, most bitcoin wallets (as well as wallets for other crypto-currencies) use this standard and can import and export seeds for backup and recovery using interoperable mnemonics.
Deterministic wallets are a very powerful model for managing many keys and addresses. They are even more useful if they are combined with a standardized way of creating seeds from a sequence of english words that are easy to transcribe, export and import across wallets. This is known as a _mnemonic_ and the standard is defined by BIP-39. Today, most bitcoin wallets (as well as wallets for other crypto-currencies) use this standard and can import and export seeds for backup and recovery using interoperable mnemonics.
Let's look at this from a practical perspective. Which of the following seeds is easier to transcribe, record on paper, read without error, export and import into another wallet?
@ -72,7 +72,7 @@ garbage claim echo media make crunch
|===
[[mnemonic_code_words]]
===== Mnemonic Code Words (BIP0039)
===== Mnemonic Code Words (BIP-39)
((("deterministic wallets","mnemonic code words")))((("mnemonic code words")))((("seeded wallets","mnemonic code words")))Mnemonic code words are word sequences that represent (encode) a random number used as a seed to derive a deterministic wallet. The sequence of words is sufficient to re-create the seed and from there re-create the wallet and all the derived keys. A wallet application that implements deterministic wallets with mnemonic words will show the user a sequence of 12 to 24 words when first creating a wallet. That sequence of words is the wallet backup and can be used to recover and re-create all the keys in the same or any compatible wallet application. Mnemonic words make it easier for users to back up wallets because they are easy to read and correctly transcribe, as compared to a random sequence of numbers.
@ -81,14 +81,14 @@ garbage claim echo media make crunch
Mnemonic words are often confused with "brainwallets". They are not the same. The primary difference is that a brainwallet consists of words chosen by the user, whereas menmonic words are created randomly by the wallet and presented to the user. This important difference makes mnemonic words much more secure, because humans are very poor sources of randomness.
====
Mnemonic codes are defined in((("BIP0039"))) Bitcoin Improvement Proposal 39 (see <<bip0039>>). Note that BIP0039 is one implementation of a mnemonic code standard. Specifically, there is a different standard, with a different set of words, used by the((("Electrum wallet")))((("mnemonic code words","Electrum wallet and"))) Electrum wallet and predating BIP0039. BIP0039 was proposed by the((("mnemonic code words","Trezor wallet and")))((("Trezor wallet"))) company behind the Trezor hardware wallet and is incompatible with Electrum's implementation. However, BIP0039 has now achieved broad industry support across dozens of interoperable implementations and should be considered the de-facto industry standard.
Mnemonic codes are defined in((("BIP-39"))) Bitcoin Improvement Proposal 39 (see <<bip-39>>). Note that BIP-39 is one implementation of a mnemonic code standard. Specifically, there is a different standard, with a different set of words, used by the((("Electrum wallet")))((("mnemonic code words","Electrum wallet and"))) Electrum wallet and predating BIP-39. BIP-39 was proposed by the((("mnemonic code words","Trezor wallet and")))((("Trezor wallet"))) company behind the Trezor hardware wallet and is incompatible with Electrum's implementation. However, BIP-39 has now achieved broad industry support across dozens of interoperable implementations and should be considered the de-facto industry standard.
BIP0039 defines the creation of a mnemonic code and seed, which we describe here in 9 steps. For clarity, the process is split in two parts: Steps 1 through 6 are shown in <<generating_mnemonic_words>> and steps 7 through 9 are shown in <<mnemonic_to_seed>>.
BIP-39 defines the creation of a mnemonic code and seed, which we describe here in 9 steps. For clarity, the process is split in two parts: Steps 1 through 6 are shown in <<generating_mnemonic_words>> and steps 7 through 9 are shown in <<mnemonic_to_seed>>.
[[generating_mnemonic_words]]
===== Generating Mnemonic Words
Mnemonic words are generated automatically by the wallet, using a standardized process defined in BIP0039. The wallet starts from a source of entropy, adds a checksum and then maps the entropy to a word list:
Mnemonic words are generated automatically by the wallet, using a standardized process defined in BIP-39. The wallet starts from a source of entropy, adds a checksum and then maps the entropy to a word list:
1. Create a random sequence (entropy) of 128 to 256 bits.
2. Create a checksum of the random sequence by taking the first four bits of its SHA256 hash.
@ -119,7 +119,7 @@ The table <<table_4-5>>, shows the relationship between the size of entropy data
The mnemonic words represent entropy with a length of 128 to 256 bits. The entropy is then used to derive a longer (512-bit) seed through the use of the key-stretching function PBKDF2. The seed produced is then used to build a deterministic wallet and derive its keys.
The key-stretching function takes two parameters: the mnemonic and a _salt_. The purpose of a salt in a key-stretching function is to make it difficult to build a lookup table enabling a brute force attack. In the BIP0039 standard, the salt has another purpose - it allows the introduction of a passphrase which serves as an additional security factor protecting the seed, as we will describe in more detail in <<mnemonic_passphrase>>.
The key-stretching function takes two parameters: the mnemonic and a _salt_. The purpose of a salt in a key-stretching function is to make it difficult to build a lookup table enabling a brute force attack. In the BIP-39 standard, the salt has another purpose - it allows the introduction of a passphrase which serves as an additional security factor protecting the seed, as we will describe in more detail in <<mnemonic_passphrase>>.
The process described in steps 7 through 9 below continues from the process described previously in <<generating_mnemonic_words>>.
@ -172,13 +172,13 @@ luggage oxygen faint major edit measure invite love trap field dilemma oblige+
|=======
[[mnemonic_passphrase]]
===== Optional Passphrase in BIP0039
===== Optional Passphrase in BIP-39
The BIP0039 standard allows the use of an optional passphrase in the derivation of the seed. If no passphrase is used, the mnemonic is stretched with a salt consisting of the constant string "+mnemonic+", producing a specific 512-bit seed from any given mnemonic. If a passphrase is used, the stretching function produces a _different_ seed from that same mnemonic. In fact, given a single mnemonic, every possible passphrase leads to a different seed. Essentially, there is no "wrong" passphrase. All passphrases are valid and they all lead to different seeds, forming a vast set of possible uninitialized wallets. The set of possible wallets is so large (2^512^) that there is no practical possibility of brute-forcing or accidentally guessing one that is in use.
The BIP-39 standard allows the use of an optional passphrase in the derivation of the seed. If no passphrase is used, the mnemonic is stretched with a salt consisting of the constant string "+mnemonic+", producing a specific 512-bit seed from any given mnemonic. If a passphrase is used, the stretching function produces a _different_ seed from that same mnemonic. In fact, given a single mnemonic, every possible passphrase leads to a different seed. Essentially, there is no "wrong" passphrase. All passphrases are valid and they all lead to different seeds, forming a vast set of possible uninitialized wallets. The set of possible wallets is so large (2^512^) that there is no practical possibility of brute-forcing or accidentally guessing one that is in use.
[TIP]
====
There are no "wrong" passphrases in BIP0039. Every passphrase leads to some wallet, which unless previously used will be empty.
There are no "wrong" passphrases in BIP-39. Every passphrase leads to some wallet, which unless previously used will be empty.
====
The optional passphrase creates two important features:
@ -196,9 +196,9 @@ However, it is important to note that the use of a passphrase also introduces th
While passphrases are very useful, they should only be used in combination with a carefully planned process for backup and recovery, considering the possibility of surviving the owner and allowing their family to recover their crypto-currency estate.
[[hd_wallets]]
==== Hierarchical Deterministic Wallets (BIP0032/BIP0044)
==== Hierarchical Deterministic Wallets (BIP-32/BIP-44)
((("deterministic wallets","hierarchical", id="ix_ch04-asciidoc24", range="startofrange")))((("hierarchical deterministic wallets (HD wallets)", id="ix_ch04-asciidoc25", range="startofrange")))((("BIP0032", id="ix_ch04-asciidoc25a", range="startofrange")))((("BIP0044", id="ix_ch04-asciidoc25b", range="startofrange")))Deterministic wallets were developed to make it easy to derive many keys from a single "seed." The most advanced form of deterministic wallets is the _hierarchical deterministic wallet_ or _HD wallet_ defined by the BIP0032 standard. Hierarchical deterministic wallets contain keys derived in a tree structure, such that a parent key can derive a sequence of children keys, each of which can derive a sequence of grandchildren keys, and so on, to an infinite depth. This tree structure is illustrated in <<Type2_wallet>>.((("hierarchical deterministic wallets (HD wallets)","tree structure for")))
((("deterministic wallets","hierarchical", id="ix_ch04-asciidoc24", range="startofrange")))((("hierarchical deterministic wallets (HD wallets)", id="ix_ch04-asciidoc25", range="startofrange")))((("BIP-32", id="ix_ch04-asciidoc25a", range="startofrange")))((("BIP-44", id="ix_ch04-asciidoc25b", range="startofrange")))Deterministic wallets were developed to make it easy to derive many keys from a single "seed." The most advanced form of deterministic wallets is the _hierarchical deterministic wallet_ or _HD wallet_ defined by the BIP-32 standard. Hierarchical deterministic wallets contain keys derived in a tree structure, such that a parent key can derive a sequence of children keys, each of which can derive a sequence of grandchildren keys, and so on, to an infinite depth. This tree structure is illustrated in <<Type2_wallet>>.((("hierarchical deterministic wallets (HD wallets)","tree structure for")))
[[Type2_wallet]]
.Type-2 hierarchical deterministic wallet: a tree of keys generated from a single seed
@ -206,7 +206,7 @@ image::images/msbt_0409.png["HD wallet"]
[TIP]
====
If you are implementing a bitcoin wallet, it should be built as an HD wallet following the BIP0032 and BIP0044 standards.
If you are implementing a bitcoin wallet, it should be built as an HD wallet following the BIP-32 and BIP-44 standards.
====
HD wallets offer two major advantages over random (nondeterministic) keys. First, the tree structure can be used to express additional organizational meaning, such as when a specific branch of subkeys is used to receive incoming payments and a different branch is used to receive change from outgoing payments. Branches of keys can also be used in a corporate setting, allocating different branches to departments, subsidiaries, specific functions, or accounting categories.
@ -273,7 +273,7 @@ Think of an extended key as the root of a branch in the tree structure of the HD
An extended key consists of a private or public key and chain code. An extended key can create children, generating its own branch in the tree structure. Sharing an extended key gives access to the entire branch.
====
((("Base58Check encoding","extended keys and")))Extended keys are encoded using Base58Check, to easily export and import between different BIP0032-compatible wallets. The Base58Check coding for extended keys uses a special version number that results in the prefix "xprv" and "xpub" when encoded in Base58 characters, to make them easily recognizable. Because the extended key is 512 or 513 bits, it is also much longer than other Base58Check-encoded strings we have seen previously.
((("Base58Check encoding","extended keys and")))Extended keys are encoded using Base58Check, to easily export and import between different BIP-32-compatible wallets. The Base58Check coding for extended keys uses a special version number that results in the prefix "xprv" and "xpub" when encoded in Base58 characters, to make them easily recognizable. Because the extended key is 512 or 513 bits, it is also much longer than other Base58Check-encoded strings we have seen previously.
Here's an example of an extended private key, encoded in Base58Check:
@ -345,13 +345,13 @@ The "ancestry" of a key is read from right to left, until you reach the master k
===== Navigating the HD wallet tree structure
((("BIP0043")))((("hierarchical deterministic wallets (HD wallets)","navigating")))((("hierarchical deterministic wallets (HD wallets)","tree structure for")))The HD wallet tree structure offers tremendous flexibility. Each parent extended key can have 4 billion children: 2 billion normal children and 2 billion hardened children. Each of those children can have another 4 billion children, and so on. The tree can be as deep as you want, with an infinite number of generations. With all that flexibility, however, it becomes quite difficult to navigate this infinite tree. It is especially difficult to transfer HD wallets between implementations, because the possibilities for internal organization into branches and subbranches are endless.
((("BIP-43")))((("hierarchical deterministic wallets (HD wallets)","navigating")))((("hierarchical deterministic wallets (HD wallets)","tree structure for")))The HD wallet tree structure offers tremendous flexibility. Each parent extended key can have 4 billion children: 2 billion normal children and 2 billion hardened children. Each of those children can have another 4 billion children, and so on. The tree can be as deep as you want, with an infinite number of generations. With all that flexibility, however, it becomes quite difficult to navigate this infinite tree. It is especially difficult to transfer HD wallets between implementations, because the possibilities for internal organization into branches and subbranches are endless.
Two Bitcoin Improvement Proposals (BIPs) offer a solution to this complexity, by creating some proposed standards for the structure of HD wallet trees. BIP0043 proposes the use of the first hardened child index as a special identifier that signifies the "purpose" of the tree structure. Based on BIP0043, an HD wallet should use only one level-1 branch of the tree, with the index number identifying the structure and namespace of the rest of the tree by defining its purpose. For example, an HD wallet using only branch m/i'/ is intended to signify a specific purpose and that purpose is identified by index number "i".
Two Bitcoin Improvement Proposals (BIPs) offer a solution to this complexity, by creating some proposed standards for the structure of HD wallet trees. BIP-43 proposes the use of the first hardened child index as a special identifier that signifies the "purpose" of the tree structure. Based on BIP-43, an HD wallet should use only one level-1 branch of the tree, with the index number identifying the structure and namespace of the rest of the tree by defining its purpose. For example, an HD wallet using only branch m/i'/ is intended to signify a specific purpose and that purpose is identified by index number "i".
((("multiaccount structure")))Extending that specification, BIP0044 proposes a multiaccount structure as "purpose" number +44'+ under BIP0043. All HD wallets following the BIP0044 structure are identified by the fact that they only used one branch of the tree: m/44'/.
((("multiaccount structure")))Extending that specification, BIP-44 proposes a multiaccount structure as "purpose" number +44'+ under BIP-43. All HD wallets following the BIP-44 structure are identified by the fact that they only used one branch of the tree: m/44'/.
BIP0044 specifies the structure as consisting of five predefined tree levels:
BIP-44 specifies the structure as consisting of five predefined tree levels:
+m / purpose' / coin_type' / account' / change / address_index+
@ -362,7 +362,7 @@ BIP0044 specifies the structure as consisting of five predefined tree levels:
((("change level (multiaccount structure)")))On the fourth level, "change," an HD wallet has two subtrees, one for creating receiving addresses and one for creating change addresses. Note that whereas the previous levels used hardened derivation, this level uses normal derivation. This is to allow this level of the tree to export extended public keys for use in a nonsecured environment. Usable addresses are derived by the HD wallet as children of the fourth level, making the fifth level of the tree the "address_index." For example, the third receiving address for bitcoin payments in the primary account would be M/44'/0'/0'/0/2. <<table_4-9>> shows a few more examples.
[[table_4-9]]
.BIP0044 HD wallet structure examples
.BIP-44 HD wallet structure examples
[options="header"]
|=======
|HD path | Key described
@ -375,7 +375,7 @@ BIP0044 specifies the structure as consisting of five predefined tree levels:
===== Experimenting with HD wallets using Bitcoin Explorer
((("hierarchical deterministic wallets (HD wallets)","Bitcoin Explorer and")))((("Bitcoin Explorer","HD wallets and")))Using the Bitcoin Explorer command-line tool introduced in <<ch03_bitcoin_client>>, you can experiment with generating and extending BIP0032 deterministic keys, as well as displaying them in different formats((("Bitcoin Explorer","seed command")))((("seed command (bx)")))((("Bitcoin Explorer","hd-seed command")))((("hd-seed command (bx)")))((("Bitcoin Explorer","hd-public command")))((("hd-public command (bx)")))((("Bitcoin Explorer","hd-private command")))((("hd-private command (bx)")))((("Bitcoin Explorer","hd-to-address command")))((("hd-to-address command (bx)")))((("Bitcoin Explorer","hd-to-wif command")))((("hd-to-wif command (bx)"))): (((range="endofrange", startref="ix_ch04-asciidoc25b")))(((range="endofrange", startref="ix_ch04-asciidoc25a")))(((range="endofrange", startref="ix_ch04-asciidoc25")))(((range="endofrange", startref="ix_ch04-asciidoc24")))(((range="endofrange", startref="ix_ch04-asciidoc23")))
((("hierarchical deterministic wallets (HD wallets)","Bitcoin Explorer and")))((("Bitcoin Explorer","HD wallets and")))Using the Bitcoin Explorer command-line tool introduced in <<ch03_bitcoin_client>>, you can experiment with generating and extending BIP-32 deterministic keys, as well as displaying them in different formats((("Bitcoin Explorer","seed command")))((("seed command (bx)")))((("Bitcoin Explorer","hd-seed command")))((("hd-seed command (bx)")))((("Bitcoin Explorer","hd-public command")))((("hd-public command (bx)")))((("Bitcoin Explorer","hd-private command")))((("hd-private command (bx)")))((("Bitcoin Explorer","hd-to-address command")))((("hd-to-address command (bx)")))((("Bitcoin Explorer","hd-to-wif command")))((("hd-to-wif command (bx)"))): (((range="endofrange", startref="ix_ch04-asciidoc25b")))(((range="endofrange", startref="ix_ch04-asciidoc25a")))(((range="endofrange", startref="ix_ch04-asciidoc25")))(((range="endofrange", startref="ix_ch04-asciidoc24")))(((range="endofrange", startref="ix_ch04-asciidoc23")))
====
[source, bash]

2
ch06-orig.asciidoc
View File

@ -238,7 +238,7 @@ On the contrary, if a pattern is tested against the bloom filter and any one of
.Testing the existence of pattern "Y" in the bloom filter. The result is a definitive negative match, meaning "Definitely Not!"
image::images/msbt_0612.png[]
Bitcoin's implementation of bloom filters is described in Bitcoin Improvement Proposal 37 (BIP0037). See <<appdxbitcoinimpproposals>> or visit http://bit.ly/1x6qCiO[GitHub].
Bitcoin's implementation of bloom filters is described in Bitcoin Improvement Proposal 37 (BIP-37). See <<appdxbitcoinimpproposals>> or visit http://bit.ly/1x6qCiO[GitHub].
=== Bloom Filters and Inventory Updates

4
ch08-orig.asciidoc
View File

@ -341,7 +341,7 @@ In a generation transaction, the first two fields are set to values that do not
In the genesis block, for example, Satoshi Nakamoto added the text "The Times 03/Jan/2009 Chancellor on brink of second bailout for banks" in the coinbase data, using it as a proof of the date and to convey a message. Currently, miners use the coinbase data to include extra nonce values and strings identifying the mining pool, as we will see in the following sections.
The first few bytes of the coinbase used to be arbitrary, but that is no longer the case. As per Bitcoin Improvement Proposal 34 (BIP0034), version-2 blocks (blocks with the version field set to 2) must contain the block height index as a script "push" operation in the beginning of the coinbase field.
The first few bytes of the coinbase used to be arbitrary, but that is no longer the case. As per Bitcoin Improvement Proposal 34 (BIP-34), version-2 blocks (blocks with the version field set to 2) must contain the block height index as a script "push" operation in the beginning of the coinbase field.
In block 277,316 we see that the coinbase (see <<generation_tx_example>>), which is in the "Unlocking Script" or +scriptSig+ field of the transaction input, contains the hexadecimal value +03443b0403858402062f503253482f+. Let's decode this value.
@ -349,7 +349,7 @@ The first byte, +03+, instructs the script execution engine to push the next thr
The next few hexadecimal digits (+03858402062+) are used to encode an extra _nonce_ (see <<extra_nonce>>), or random value, used to find a suitable proof of work solution.
The final part of the coinbase data (+2f503253482f+) is the ASCII-encoded string +/P2SH/+, which indicates that the mining node that mined this block supports the((("pay-to-script-hash (P2SH)","coinbase data and"))) pay-to-script-hash (P2SH) improvement defined in BIP0016. The introduction of the P2SH capability required a "vote" by miners to endorse either BIP0016 or BIP0017. Those endorsing the BIP0016 implementation were to include +/P2SH/+ in their coinbase data. Those endorsing the BIP0017 implementation of P2SH were to include the string +p2sh/CHV+ in their coinbase data. The BIP0016 was elected as the winner, and many miners continued including the string +/P2SH/+ in their coinbase to indicate support for this feature.
The final part of the coinbase data (+2f503253482f+) is the ASCII-encoded string +/P2SH/+, which indicates that the mining node that mined this block supports the((("pay-to-script-hash (P2SH)","coinbase data and"))) pay-to-script-hash (P2SH) improvement defined in BIP-16. The introduction of the P2SH capability required a "vote" by miners to endorse either BIP-16 or BIP-17. Those endorsing the BIP-16 implementation were to include +/P2SH/+ in their coinbase data. Those endorsing the BIP-17 implementation of P2SH were to include the string +p2sh/CHV+ in their coinbase data. The BIP-16 was elected as the winner, and many miners continued including the string +/P2SH/+ in their coinbase to indicate support for this feature.
<<satoshi_words>> uses the libbitcoin library introduced in <<alt_libraries>> to extract the coinbase data from the genesis block, displaying Satoshi's message. Note that the libbitcoin library contains a static copy of the genesis block, so the example code can retrieve the genesis block directly from the library.

2
ch10-orig.asciidoc
View File

@ -49,7 +49,7 @@ Over the past three years, as a direct result of bitcoin adoption, we have seen
==== Physical Bitcoin Storage
((("backups","cold-storage wallets")))((("bitcoin","storage, physical")))((("cold-storage wallets")))((("paper wallets")))((("user security","physical bitcoin storage")))Because most users are far more comfortable with physical security than information security, a very effective method for protecting bitcoins is to convert them into physical form. Bitcoin keys are nothing more than long numbers. This means that they can be stored in a physical form, such as printed on paper or etched on a metal coin. Securing the keys then becomes as simple as physically securing the printed copy of the bitcoin keys. A set of bitcoin keys that is printed on paper is called a "paper wallet," and there are many free tools that can be used to create them. I personally keep the vast majority of my bitcoins (99% or more) stored on paper wallets, encrypted with BIP0038, with multiple copies locked in safes. Keeping bitcoin offline is called _cold storage_ and it is one of the most effective security techniques. A cold storage system is one where the keys are generated on an offline system (one never connected to the Internet) and stored offline either on paper or on digital media, such as a USB memory stick.
((("backups","cold-storage wallets")))((("bitcoin","storage, physical")))((("cold-storage wallets")))((("paper wallets")))((("user security","physical bitcoin storage")))Because most users are far more comfortable with physical security than information security, a very effective method for protecting bitcoins is to convert them into physical form. Bitcoin keys are nothing more than long numbers. This means that they can be stored in a physical form, such as printed on paper or etched on a metal coin. Securing the keys then becomes as simple as physically securing the printed copy of the bitcoin keys. A set of bitcoin keys that is printed on paper is called a "paper wallet," and there are many free tools that can be used to create them. I personally keep the vast majority of my bitcoins (99% or more) stored on paper wallets, encrypted with BIP-38, with multiple copies locked in safes. Keeping bitcoin offline is called _cold storage_ and it is one of the most effective security techniques. A cold storage system is one where the keys are generated on an offline system (one never connected to the Internet) and stored offline either on paper or on digital media, such as a USB memory stick.
==== Hardware Wallets

2
glossary.asciidoc
View File

@ -7,7 +7,7 @@ address::
A bitcoin address looks like +1DSrfJdB2AnWaFNgSbv3MZC2m74996JafV+. It consists of a string of letters and numbers starting with the digit 1 or 3. Just like you ask others to send an email to your email address, you would ask others to send you bitcoin to your bitcoin address.((("bitcoin address")))((("address", see="bitcoin address")))((("public key", see="bitcoin address")))
bip::
Bitcoin Improvement Proposals. A set of proposals that members of the bitcoin community have submitted to improve bitcoin. For example, BIP0021 is a proposal to improve the bitcoin uniform resource identifier (URI) scheme.((("bip")))
Bitcoin Improvement Proposals. A set of proposals that members of the bitcoin community have submitted to improve bitcoin. For example, BIP-21 is a proposal to improve the bitcoin uniform resource identifier (URI) scheme.((("bip")))
bitcoin::
The name of the currency unit (the coin), the network, and the software.((("bitcoin")))

80
planned_toc.asciidoc
View File

@ -1,80 +0,0 @@
= Planned Chapters
= Chapter 4 - Wallets, Keys and Addresses
== Introduction
== Wallets & Keys
=== Public Key Cryptography
=== Elliptic Curves
=== Key Generation
==== Non-Deterministic (Random)
==== Deterministic (Seeded)
==== Seed Words (BIP0039)
==== Deterministic Chains (Electrum Key Chains)
==== Deterministic Trees (BIP0032)
=== Keys Formats and Addresses
==== Base58 and Base58Check Encoding
==== Compressed Keys
==== Encrypted Keys (BIP0038)
==== Addresses
==== Pay To Script Hash Addresses (P2SH)
==== Multi-Signature Addresses
==== Vanity Addresses
= Chapter 5 - Transactions
== Introduction
== ScriptPubKey and ScriptSig
== Transaction Script Language
== Stack-Based Script Evaluation
== Common Transaction Scripts
== Complex Transaction Scripts
== P2SH Scripts
== Multi-Signature Scripts
== Transaction Malleability
= Chapter 6 - The Blockchain & Mining
== Introduction
== The Blockchain
== Genesis Block
== Proof-of-Work (Mining) and Consensus
=== Consensus Mechanism
=== Proof-of-Work Algorithm
=== Difficulty Target and Re-Targetting
=== Highest Difficulty Chain Selection
=== Competition and Coinbase
=== Mining Pools
==== Managed Pools
==== P2Pool
=== Mining Economics
=== Consensus Attacks
==== 51% Attack
==== Selfish Mining Attack
== Chain Forking
=== Normal Forks
=== Soft Forks
=== Hard Forks
=== Unusual Forks
= Chapter 7 - The Bitcoin Network
== Introduction
== Peer-to-Peer Network Architecture
== Nodes and Roles
== Network Discovery
== Network Protocol Messages
== Bitcoin Core Node
== Alternative Node Implementations
= Chapter 8 - Altcoins
== Alternative Currency Chains (Alt-Coins)
=== Alternative Consensus Algorithms
==== Proof-of-Work
===== Scrypt
===== Dagger/Slasher
===== "Useful" Work (Prime, Protein etc)
==== Proof-of-Stake
==== Proof-of-Resource and Proof-of-Publishing
== Alternative Chains Beyond Currency
=== Decentralized Naming (Namecoin)
=== Decentralized Contract Platform (Ethereum)

370
selected BIPs/bip-0001.asciidoc
View File

@ -1,370 +0,0 @@
-----------------------------------
BIP: 1
Title: BIP Purpose and Guidelines
Status: Accepted
Type: Standards Track
Created: 2011-08-19
-----------------------------------
[[what-is-a-bip]]
What is a BIP?
~~~~~~~~~~~~~~
BIP stands for Bitcoin Improvement Proposal. A BIP is a design document
providing information to the Bitcoin community, or describing a new
feature for Bitcoin or its processes or environment. The BIP should
provide a concise technical specification of the feature and a rationale
for the feature.
We intend BIPs to be the primary mechanisms for proposing new features,
for collecting community input on an issue, and for documenting the
design decisions that have gone into Bitcoin. The BIP author is
responsible for building consensus within the community and documenting
dissenting opinions.
Because the BIPs are maintained as text files in a versioned repository,
their revision history is the historical record of the feature proposal
.
[[bip-types]]
BIP Types
~~~~~~~~~
There are three kinds of BIP:
* A Standards Track BIP describes any change that affects most or all
Bitcoin implementations, such as a change to the network protocol, a
change in block or transaction validity rules, or any change or addition
that affects the interoperability of applications using Bitcoin.
* An Informational BIP describes a Bitcoin design issue, or provides
general guidelines or information to the Bitcoin community, but does not
propose a new feature. Informational BIPs do not necessarily represent a
Bitcoin community consensus or recommendation, so users and implementors
are free to ignore Informational BIPs or follow their advice.
* A Process BIP describes a process surrounding Bitcoin, or proposes a
change to (or an event in) a process. Process BIPs are like Standards
Track BIPs but apply to areas other than the Bitcoin protocol itself.
They may propose an implementation, but not to Bitcoin's codebase; they
often require community consensus; unlike Informational BIPs, they are
more than recommendations, and users are typically not free to ignore
them. Examples include procedures, guidelines, changes to the
decision-making process, and changes to the tools or environment used in
Bitcoin development. Any meta-BIP is also considered a Process BIP.
[[bip-work-flow]]
BIP Work Flow
~~~~~~~~~~~~~
The BIP editors assign BIP numbers and change their status. Please send
all BIP-related email to the BIP editor, which is listed under
link:#BIP_Editors[BIP Editors] below. Also see
link:#BIP_Editor_Responsibilities__Workflow[BIP Editor Responsibilities
& Workflow].
The BIP process begins with a new idea for Bitcoin. It is highly
recommended that a single BIP contain a single key proposal or new idea.
Small enhancements or patches often don't need a BIP and can be injected
into the Bitcoin development work flow with a patch submission to the
Bitcoin issue tracker. The more focused the BIP, the more successful it
tends to be. The BIP editor reserves the right to reject BIP proposals
if they appear too unfocused or too broad. If in doubt, split your BIP
into several well-focused ones.
Each BIP must have a champion -- someone who writes the BIP using the
style and format described below, shepherds the discussions in the
appropriate forums, and attempts to build community consensus around the
idea. The BIP champion (a.k.a. Author) should first attempt to ascertain
whether the idea is BIP-able. Posting to the
http://sourceforge.net/mailarchive/forum.php?forum_name=bitcoin-development[bitcoin-development@lists.sourceforge.net]
mailing list (and maybe the
https://bitcointalk.org/index.php?board=6.0[Development&Technical
Discussion] forum) is the best way to go about this.
Vetting an idea publicly before going as far as writing a BIP is meant
to save the potential author time. Many ideas have been brought forward
for changing Bitcoin that have been rejected for various reasons. Asking
the Bitcoin community first if an idea is original helps prevent too
much time being spent on something that is guaranteed to be rejected
based on prior discussions (searching the internet does not always do
the trick). It also helps to make sure the idea is applicable to the
entire community and not just the author. Just because an idea sounds
good to the author does not mean it will work for most people in most
areas where Bitcoin is used.
Once the champion has asked the Bitcoin community as to whether an idea
has any chance of acceptance, a draft BIP should be presented to
http://sourceforge.net/mailarchive/forum.php?forum_name=bitcoin-development[bitcoin-development@lists.sourceforge.net].
This gives the author a chance to flesh out the draft BIP to make
properly formatted, of high quality, and to address initial concerns
about the proposal.
Following a discussion, the proposal should be sent to the Bitcoin-dev
list and the BIP editor with the draft BIP. This draft must be written
in BIP style as described below, else it will be sent back without
further regard until proper formatting rules are followed.
If the BIP editor approves, he will assign the BIP a number, label it as
Standards Track, Informational, or Process, give it status "Draft", and
add it to the git repository. The BIP editor will not unreasonably deny
a BIP. Reasons for denying BIP status include duplication of effort,
being technically unsound, not providing proper motivation or addressing
backwards compatibility, or not in keeping with the Bitcoin philosophy.
The BIP author may update the Draft as necessary in the git repository.
Updates to drafts may also be submitted by the author as pull requests.
Standards Track BIPs consist of two parts, a design document and a
reference implementation. The BIP should be reviewed and accepted before
a reference implementation is begun, unless a reference implementation
will aid people in studying the BIP. Standards Track BIPs must include
an implementation -- in the form of code, a patch, or a URL to same --
before it can be considered Final.
BIP authors are responsible for collecting community feedback on a BIP
before submitting it for review. However, wherever possible, long
open-ended discussions on public mailing lists should be avoided.
Strategies to keep the discussions efficient include: setting up a
separate SIG mailing list for the topic, having the BIP author accept
private comments in the early design phases, setting up a wiki page or
git repository, etc. BIP authors should use their discretion here.
For a BIP to be accepted it must meet certain minimum criteria. It must
be a clear and complete description of the proposed enhancement. The
enhancement must represent a net improvement. The proposed
implementation, if applicable, must be solid and must not complicate the
protocol unduly.
Once a BIP has been accepted, the reference implementation must be
completed. When the reference implementation is complete and accepted by
the community, the status will be changed to "Final".
A BIP can also be assigned status "Deferred". The BIP author or editor
can assign the BIP this status when no progress is being made on the
BIP. Once a BIP is deferred, the BIP editor can re-assign it to draft
status.
A BIP can also be "Rejected". Perhaps after all is said and done it was
not a good idea. It is still important to have a record of this fact.
BIPs can also be superseded by a different BIP, rendering the original
obsolete. This is intended for Informational BIPs, where version 2 of an
API can replace version 1.
The possible paths of the status of BIPs are as follows:
Some Informational and Process BIPs may also have a status of "Active"
if they are never meant to be completed. E.g. BIP 1 (this BIP).
[[what-belongs-in-a-successful-bip]]
What belongs in a successful BIP?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each BIP should have the following parts:
* Preamble -- RFC 822 style headers containing meta-data about the BIP,
including the BIP number, a short descriptive title (limited to a
maximum of 44 characters), the names, and optionally the contact info
for each author, etc.
* Abstract -- a short (~200 word) description of the technical issue
being addressed.
* Copyright/public domain -- Each BIP must either be explicitly labelled
as placed in the public domain (see this BIP as an example) or licensed
under the Open Publication License.
* Specification -- The technical specification should describe the
syntax and semantics of any new feature. The specification should be
detailed enough to allow competing, interoperable implementations for
any of the current Bitcoin platforms (Satoshi, BitcoinJ, bitcoin-js,
libbitcoin).
* Motivation -- The motivation is critical for BIPs that want to change
the Bitcoin protocol. It should clearly explain why the existing
protocol specification is inadequate to address the problem that the BIP
solves. BIP submissions without sufficient motivation may be rejected
outright.
* Rationale -- The rationale fleshes out the specification by describing
what motivated the design and why particular design decisions were made.
It should describe alternate designs that were considered and related
work, e.g. how the feature is supported in other languages.
* The rationale should provide evidence of consensus within the
community and discuss important objections or concerns raised during
discussion.
* Backwards Compatibility -- All BIPs that introduce backwards
incompatibilities must include a section describing these
incompatibilities and their severity. The BIP must explain how the
author proposes to deal with these incompatibilities. BIP submissions
without a sufficient backwards compatibility treatise may be rejected
outright.
* Reference Implementation -- The reference implementation must be
completed before any BIP is given status "Final", but it need not be
completed before the BIP is accepted. It is better to finish the
specification and rationale first and reach consensus on it before
writing code.
* The final implementation must include test code and documentation
appropriate for the Bitcoin protocol.
[[bip-formats-and-templates]]
BIP Formats and Templates
~~~~~~~~~~~~~~~~~~~~~~~~~
BIPs should be written in mediawiki or markdown format. Image files
should be included in a subdirectory for that BIP.
[[bip-header-preamble]]
BIP Header Preamble
~~~~~~~~~~~~~~~~~~~
Each BIP must begin with an RFC 822 style header preamble. The headers
must appear in the following order. Headers marked with "*" are optional
and are described below. All other headers are required.
-------------------------------------------------------------------
BIP: <BIP number>
Title: <BIP title>
Author: <list of authors' real names and optionally, email addrs>
* Discussions-To: <email address>
Status: <Draft | Active | Accepted | Deferred | Rejected |
Withdrawn | Final | Superseded>
Type: <Standards Track | Informational | Process>
Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
* Post-History: <dates of postings to bitcoin mailing list>
* Replaces: <BIP number>
* Superseded-By: <BIP number>
* Resolution: <url>
-------------------------------------------------------------------
The Author header lists the names, and optionally the email addresses of
all the authors/owners of the BIP. The format of the Author header value
must be
` Random J. User `
if the email address is included, and just
` Random J. User`
if the address is not given.
If there are multiple authors, each should be on a separate line
following RFC 2822 continuation line conventions.
Note: The Resolution header is required for Standards Track BIPs only.
It contains a URL that should point to an email message or other web
resource where the pronouncement about the BIP is made.
While a BIP is in private discussions (usually during the initial Draft
phase), a Discussions-To header will indicate the mailing list or URL
where the BIP is being discussed. No Discussions-To header is necessary
if the BIP is being discussed privately with the author, or on the
bitcoin email mailing lists.
The Type header specifies the type of BIP: Standards Track,
Informational, or Process.
The Created header records the date that the BIP was assigned a number,
while Post-History is used to record the dates of when new versions of
the BIP are posted to bitcoin mailing lists. Both headers should be in
yyyy-mm-dd format, e.g. 2001-08-14.
BIPs may have a Requires header, indicating the BIP numbers that this
BIP depends on.
BIPs may also have a Superseded-By header indicating that a BIP has been
rendered obsolete by a later document; the value is the number of the
BIP that replaces the current document. The newer BIP must have a
Replaces header containing the number of the BIP that it rendered
obsolete. Auxiliary Files
BIPs may include auxiliary files such as diagrams. Such files must be
named BIP-XXXX-Y.ext, where "XXXX" is the BIP number, "Y" is a serial
number (starting at 1), and "ext" is replaced by the actual file
extension (e.g. "png").
[[transferring-bip-ownership]]
Transferring BIP Ownership
~~~~~~~~~~~~~~~~~~~~~~~~~~
It occasionally becomes necessary to transfer ownership of BIPs to a new
champion. In general, we'd like to retain the original author as a
co-author of the transferred BIP, but that's really up to the original
author. A good reason to transfer ownership is because the original
author no longer has the time or interest in updating it or following
through with the BIP process, or has fallen off the face of the 'net
(i.e. is unreachable or not responding to email). A bad reason to
transfer ownership is because you don't agree with the direction of the
BIP. We try to build consensus around a BIP, but if that's not possible,
you can always submit a competing BIP.
If you are interested in assuming ownership of a BIP, send a message
asking to take over, addressed to both the original author and the BIP
editor. If the original author doesn't respond to email in a timely
manner, the BIP editor will make a unilateral decision (it's not like
such decisions can't be reversed :).
[[bip-editors]]
BIP Editors
~~~~~~~~~~~
The current BIP editor is Gregory Maxwell who can be contacted at
gmaxwell@gmail.com.
[[bip-editor-responsibilities-workflow]]
BIP Editor Responsibilities & Workflow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A BIP editor must subscribe to the Bitcoin development mailing list. All
BIP-related correspondence should be sent (or CC'd) to
gmaxwell@gmail.com.
For each new BIP that comes in an editor does the following:
* Read the BIP to check if it is ready: sound and complete. The ideas
must make technical sense, even if they don't seem likely to be
accepted.
* The title should accurately describe the content.
* Edit the BIP for language (spelling, grammar, sentence structure,
etc.), markup (for reST BIPs), code style (examples should match BIP 8 &
7).
If the BIP isn't ready, the editor will send it back to the author for
revision, with specific instructions.
Once the BIP is ready for the repository, the BIP editor will:
* Assign a BIP number (almost always just the next available number, but
sometimes it's a special/joke number, like 666 or 3141).
* Add the BIP to the https://github.com/bitcoin/bips[bitcoin/bips]
repository on GitHub.
* List the BIP in README.mediawiki
* Send email back to the BIP author with next steps (post to bitcoin
mailing list).
Many BIPs are written and maintained by developers with write access to
the Bitcoin codebase. The BIP editors monitor BIP changes, and correct
any structure, grammar, spelling, or markup mistakes we see.
The editors don't pass judgement on BIPs. We merely do the
administrative & editorial part. Except for times like this, there's
relatively low volume.
[[history]]
History
~~~~~~~
This document was derived heavily from Python's PEP-0001. In many places
text was simply copied and modified. Although the PEP-0001 text was
written by Barry Warsaw, Jeremy Hylton, and David Goodger, they are not
responsible for its use in the Bitcoin Improvement Process, and should
not be bothered with technical questions specific to Bitcoin or the BIP
process. Please direct all comments to the BIP editors or the Bitcoin
development mailing list.

175
selected BIPs/bip-0001.mediawiki
View File

@ -1,175 +0,0 @@
<pre>
BIP: 1
Title: BIP Purpose and Guidelines
Status: Accepted
Type: Standards Track
Created: 2011-08-19
</pre>
==What is a BIP?==
BIP stands for Bitcoin Improvement Proposal. A BIP is a design document providing information to the Bitcoin community, or describing a new feature for Bitcoin or its processes or environment. The BIP should provide a concise technical specification of the feature and a rationale for the feature.
We intend BIPs to be the primary mechanisms for proposing new features, for collecting community input on an issue, and for documenting the design decisions that have gone into Bitcoin. The BIP author is responsible for building consensus within the community and documenting dissenting opinions.
Because the BIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal
.
==BIP Types==
There are three kinds of BIP:
* A Standards Track BIP describes any change that affects most or all Bitcoin implementations, such as a change to the network protocol, a change in block or transaction validity rules, or any change or addition that affects the interoperability of applications using Bitcoin.
* An Informational BIP describes a Bitcoin design issue, or provides general guidelines or information to the Bitcoin community, but does not propose a new feature. Informational BIPs do not necessarily represent a Bitcoin community consensus or recommendation, so users and implementors are free to ignore Informational BIPs or follow their advice.
* A Process BIP describes a process surrounding Bitcoin, or proposes a change to (or an event in) a process. Process BIPs are like Standards Track BIPs but apply to areas other than the Bitcoin protocol itself. They may propose an implementation, but not to Bitcoin's codebase; they often require community consensus; unlike Informational BIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Bitcoin development. Any meta-BIP is also considered a Process BIP.
==BIP Work Flow==
The BIP editors assign BIP numbers and change their status. Please send all BIP-related email to the BIP editor, which is listed under [[#BIP_Editors|BIP Editors]] below. Also see [[#BIP_Editor_Responsibilities__Workflow|BIP Editor Responsibilities & Workflow]].
The BIP process begins with a new idea for Bitcoin. It is highly recommended that a single BIP contain a single key proposal or new idea. Small enhancements or patches often don't need a BIP and can be injected into the Bitcoin development work flow with a patch submission to the Bitcoin issue tracker. The more focused the BIP, the more successful it tends to be. The BIP editor reserves the right to reject BIP proposals if they appear too unfocused or too broad. If in doubt, split your BIP into several well-focused ones.
Each BIP must have a champion -- someone who writes the BIP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The BIP champion (a.k.a. Author) should first attempt to ascertain whether the idea is BIP-able. Posting to the [http://sourceforge.net/mailarchive/forum.php?forum_name=bitcoin-development bitcoin-development@lists.sourceforge.net] mailing list (and maybe the [https://bitcointalk.org/index.php?board=6.0 Development&Technical Discussion] forum) is the best way to go about this.
Vetting an idea publicly before going as far as writing a BIP is meant to save the potential author time. Many ideas have been brought forward for changing Bitcoin that have been rejected for various reasons. Asking the Bitcoin community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where Bitcoin is used.
Once the champion has asked the Bitcoin community as to whether an idea has any chance of acceptance, a draft BIP should be presented to [http://sourceforge.net/mailarchive/forum.php?forum_name=bitcoin-development bitcoin-development@lists.sourceforge.net]. This gives the author a chance to flesh out the draft BIP to make properly formatted, of high quality, and to address initial concerns about the proposal.
Following a discussion, the proposal should be sent to the Bitcoin-dev list and the BIP editor with the draft BIP. This draft must be written in BIP style as described below, else it will be sent back without further regard until proper formatting rules are followed.
If the BIP editor approves, he will assign the BIP a number, label it as Standards Track, Informational, or Process, give it status "Draft", and add it to the git repository. The BIP editor will not unreasonably deny a BIP. Reasons for denying BIP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the Bitcoin philosophy.
The BIP author may update the Draft as necessary in the git repository. Updates to drafts may also be submitted by the author as pull requests.
Standards Track BIPs consist of two parts, a design document and a reference implementation. The BIP should be reviewed and accepted before a reference implementation is begun, unless a reference implementation will aid people in studying the BIP. Standards Track BIPs must include an implementation -- in the form of code, a patch, or a URL to same -- before it can be considered Final.
BIP authors are responsible for collecting community feedback on a BIP before submitting it for review. However, wherever possible, long open-ended discussions on public mailing lists should be avoided. Strategies to keep the discussions efficient include: setting up a separate SIG mailing list for the topic, having the BIP author accept private comments in the early design phases, setting up a wiki page or git repository, etc. BIP authors should use their discretion here.
For a BIP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the protocol unduly.
Once a BIP has been accepted, the reference implementation must be completed. When the reference implementation is complete and accepted by the community, the status will be changed to "Final".
A BIP can also be assigned status "Deferred". The BIP author or editor can assign the BIP this status when no progress is being made on the BIP. Once a BIP is deferred, the BIP editor can re-assign it to draft status.
A BIP can also be "Rejected". Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact.
BIPs can also be superseded by a different BIP, rendering the original obsolete. This is intended for Informational BIPs, where version 2 of an API can replace version 1.
The possible paths of the status of BIPs are as follows:
<img src=bip-0001/process.png></img>
Some Informational and Process BIPs may also have a status of "Active" if they are never meant to be completed. E.g. BIP 1 (this BIP).
==What belongs in a successful BIP?==
Each BIP should have the following parts:
* Preamble -- RFC 822 style headers containing meta-data about the BIP, including the BIP number, a short descriptive title (limited to a maximum of 44 characters), the names, and optionally the contact info for each author, etc.
* Abstract -- a short (~200 word) description of the technical issue being addressed.
* Copyright/public domain -- Each BIP must either be explicitly labelled as placed in the public domain (see this BIP as an example) or licensed under the Open Publication License.
* Specification -- The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Bitcoin platforms (Satoshi, BitcoinJ, bitcoin-js, libbitcoin).
* Motivation -- The motivation is critical for BIPs that want to change the Bitcoin protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the BIP solves. BIP submissions without sufficient motivation may be rejected outright.
* Rationale -- The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages.
* The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
* Backwards Compatibility -- All BIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The BIP must explain how the author proposes to deal with these incompatibilities. BIP submissions without a sufficient backwards compatibility treatise may be rejected outright.
* Reference Implementation -- The reference implementation must be completed before any BIP is given status "Final", but it need not be completed before the BIP is accepted. It is better to finish the specification and rationale first and reach consensus on it before writing code.
* The final implementation must include test code and documentation appropriate for the Bitcoin protocol.
==BIP Formats and Templates==
BIPs should be written in mediawiki or markdown format. Image files should be included in a subdirectory for that BIP.
==BIP Header Preamble==
Each BIP must begin with an RFC 822 style header preamble. The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required.
<pre>
BIP: <BIP number>
Title: <BIP title>
Author: <list of authors' real names and optionally, email addrs>
* Discussions-To: <email address>
Status: <Draft | Active | Accepted | Deferred | Rejected |
Withdrawn | Final | Superseded>
Type: <Standards Track | Informational | Process>
Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
* Post-History: <dates of postings to bitcoin mailing list>
* Replaces: <BIP number>
* Superseded-By: <BIP number>
* Resolution: <url>
</pre>
The Author header lists the names, and optionally the email addresses of all the authors/owners of the BIP. The format of the Author header value must be
Random J. User <address@dom.ain>
if the email address is included, and just
Random J. User
if the address is not given.
If there are multiple authors, each should be on a separate line following RFC 2822 continuation line conventions.
Note: The Resolution header is required for Standards Track BIPs only. It contains a URL that should point to an email message or other web resource where the pronouncement about the BIP is made.
While a BIP is in private discussions (usually during the initial Draft phase), a Discussions-To header will indicate the mailing list or URL where the BIP is being discussed. No Discussions-To header is necessary if the BIP is being discussed privately with the author, or on the bitcoin email mailing lists.
The Type header specifies the type of BIP: Standards Track, Informational, or Process.
The Created header records the date that the BIP was assigned a number, while Post-History is used to record the dates of when new versions of the BIP are posted to bitcoin mailing lists. Both headers should be in yyyy-mm-dd format, e.g. 2001-08-14.
BIPs may have a Requires header, indicating the BIP numbers that this BIP depends on.
BIPs may also have a Superseded-By header indicating that a BIP has been rendered obsolete by a later document; the value is the number of the BIP that replaces the current document. The newer BIP must have a Replaces header containing the number of the BIP that it rendered obsolete.
Auxiliary Files
BIPs may include auxiliary files such as diagrams. Such files must be named BIP-XXXX-Y.ext, where "XXXX" is the BIP number, "Y" is a serial number (starting at 1), and "ext" is replaced by the actual file extension (e.g. "png").
==Transferring BIP Ownership==
It occasionally becomes necessary to transfer ownership of BIPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred BIP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the BIP process, or has fallen off the face of the 'net (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the BIP. We try to build consensus around a BIP, but if that's not possible, you can always submit a competing BIP.
If you are interested in assuming ownership of a BIP, send a message asking to take over, addressed to both the original author and the BIP editor. If the original author doesn't respond to email in a timely manner, the BIP editor will make a unilateral decision (it's not like such decisions can't be reversed :).
==BIP Editors==
The current BIP editor is Gregory Maxwell who can be contacted at [[mailto:gmaxwell@gmail.com|gmaxwell@gmail.com]].
==BIP Editor Responsibilities & Workflow==
A BIP editor must subscribe to the Bitcoin development mailing list. All BIP-related correspondence should be sent (or CC'd) to gmaxwell@gmail.com.
For each new BIP that comes in an editor does the following:
* Read the BIP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to be accepted.
* The title should accurately describe the content.
* Edit the BIP for language (spelling, grammar, sentence structure, etc.), markup (for reST BIPs), code style (examples should match BIP 8 & 7).
If the BIP isn't ready, the editor will send it back to the author for revision, with specific instructions.
Once the BIP is ready for the repository, the BIP editor will:
* Assign a BIP number (almost always just the next available number, but sometimes it's a special/joke number, like 666 or 3141).
* Add the BIP to the [https://github.com/bitcoin/bips bitcoin/bips] repository on GitHub.
* List the BIP in [[README.mediawiki]]
* Send email back to the BIP author with next steps (post to bitcoin mailing list).
Many BIPs are written and maintained by developers with write access to the Bitcoin codebase. The BIP editors monitor BIP changes, and correct any structure, grammar, spelling, or markup mistakes we see.
The editors don't pass judgement on BIPs. We merely do the administrative & editorial part. Except for times like this, there's relatively low volume.
==History==
This document was derived heavily from Python's PEP-0001. In many places text was simply copied and modified. Although the PEP-0001 text was written by Barry Warsaw, Jeremy Hylton, and David Goodger, they are not responsible for its use in the Bitcoin Improvement Process, and should not be bothered with technical questions specific to Bitcoin or the BIP process. Please direct all comments to the BIP editors or the Bitcoin development mailing list.

116
selected BIPs/bip-0011.asciidoc
View File

@ -1,116 +0,0 @@
--------------------------------------------------
BIP: 11
Title: M-of-N Standard Transactions
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Accepted
Type: Standards Track
Created: 2011-10-18
Post-History: 2011-10-02
--------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP proposes M-of-N-signatures required transactions as a new
'standard' transaction type.
[[motivation]]
Motivation
~~~~~~~~~~
Enable secured wallets, escrow transactions, and other use cases where
redeeming funds requires more than a single signature.
A couple of motivating use cases:
* A wallet secured by a "wallet protection service" (WPS). 2-of-2
signatures required transactions will be used, with one signature coming
from the (possibly compromised) computer with the wallet and the second
signature coming from the WPS. When sending protected bitcoins, the
user's bitcoin client will contact the WPS with the proposed transaction
and it can then contact the user for confirmation that they initiated
the transaction and that the transaction details are correct. Details
for how clients and WPS's communicate are outside the scope of this BIP.
Side note: customers should insist that their wallet protection service
provide them with copies of the private key(s) used to secure their
wallets that they can safely store off-line, so that their coins can be
spent even if the WPS goes out of business.
* Three-party escrow (buyer, seller and trusted dispute agent). 2-of-3
signatures required transactions will be used. The buyer and seller and
agent will each provide a public key, and the buyer will then send coins
into a 2-of-3 CHECKMULTISIG transaction and send the seller and the
agent the transaction id. The seller will fulfill their obligation and
then ask the buyer to co-sign a transaction ( already signed by seller )
that sends the tied-up coins to him (seller). +
If the buyer and seller cannot agree, then the agent can, with the
cooperation of either buyer or seller, decide what happens to the
tied-up coins. Details of how buyer, seller, and agent communicate to
gather signatures or public keys are outside the scope of this BIP.
[[specification]]
Specification
~~~~~~~~~~~~~
A new standard transaction type (scriptPubKey) that is relayed by
clients and included in mined blocks:
`   m {pubkey}...{pubkey} n OP_CHECKMULTISIG`
But only for n less than or equal to 3.
OP_CHECKMULTISIG transactions are redeemed using a standard scriptSig:
`   OP_0 ...signatures...`
(OP_0 is required because of a bug in OP_CHECKMULTISIG; it pops one too
many items off the execution stack, so a dummy value must be placed on
the stack).
The current Satoshi bitcoin client does not relay or mine transactions
with scriptSigs larger than 200 bytes; to accomodate 3-signature
transactions, this will be increased to 500 bytes.
[[rationale]]
Rationale
~~~~~~~~~
OP_CHECKMULTISIG is already an enabled opcode, and is the most
straightforward way to support several important use cases.
One argument against using OP_CHECKMULTISIG is that old clients and
miners count it as "20 sigops" for purposes of computing how many
signature operations are in a block, and there is a hard limit of 20,000
sigops per block-- meaning a maximum of 1,000 multisig transactions per
block. Creating multisig transactions using multiple OP_CHECKSIG
operations allows more of them per block.
The counter-argument is that these new multi-signature transactions will
be used in combination with OP_EVAL (see the OP_EVAL BIP), and *will* be
counted accurately. And in any case, as transaction volume rises the
hard-coded maximum block size will have to be addressed, and the rules
for counting number-of-signature-operations-in-a-block can be addressed
at that time.
A weaker argument is OP_CHECKMULTISIG should not be used because it pops
one too many items off the stack during validation. Adding an extra OP_0
placeholder to the scriptSig adds only 1 byte to the transaction, and
any alternative that avoids OP_CHECKMULTISIG adds at least several bytes
of opcodes.
[[implementation]]
Implementation
~~~~~~~~~~~~~~
OP_CHECKMULTISIG is already supported by old clients and miners as a
non-standard transaction type.
https://github.com/gavinandresen/bitcoin-git/tree/op_eval
[[post-history]]
Post History
~~~~~~~~~~~~
* https://bitcointalk.org/index.php?topic=46538[OP_EVAL proposal]

58
selected BIPs/bip-0011.mediawiki
View File

@ -1,58 +0,0 @@
<pre>
BIP: 11
Title: M-of-N Standard Transactions
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Accepted
Type: Standards Track
Created: 2011-10-18
Post-History: 2011-10-02
</pre>
==Abstract==
This BIP proposes M-of-N-signatures required transactions as a new 'standard' transaction type.
==Motivation==
Enable secured wallets, escrow transactions, and other use cases where redeeming funds requires more than a single signature.
A couple of motivating use cases:
* A wallet secured by a "wallet protection service" (WPS). 2-of-2 signatures required transactions will be used, with one signature coming from the (possibly compromised) computer with the wallet and the second signature coming from the WPS. When sending protected bitcoins, the user's bitcoin client will contact the WPS with the proposed transaction and it can then contact the user for confirmation that they initiated the transaction and that the transaction details are correct. Details for how clients and WPS's communicate are outside the scope of this BIP. Side note: customers should insist that their wallet protection service provide them with copies of the private key(s) used to secure their wallets that they can safely store off-line, so that their coins can be spent even if the WPS goes out of business.
* Three-party escrow (buyer, seller and trusted dispute agent). 2-of-3 signatures required transactions will be used. The buyer and seller and agent will each provide a public key, and the buyer will then send coins into a 2-of-3 CHECKMULTISIG transaction and send the seller and the agent the transaction id. The seller will fulfill their obligation and then ask the buyer to co-sign a transaction ( already signed by seller ) that sends the tied-up coins to him (seller).<br />If the buyer and seller cannot agree, then the agent can, with the cooperation of either buyer or seller, decide what happens to the tied-up coins. Details of how buyer, seller, and agent communicate to gather signatures or public keys are outside the scope of this BIP.
==Specification==
A new standard transaction type (scriptPubKey) that is relayed by clients and included in mined blocks:
m {pubkey}...{pubkey} n OP_CHECKMULTISIG
But only for n less than or equal to 3.
OP_CHECKMULTISIG transactions are redeemed using a standard scriptSig:
OP_0 ...signatures...
(OP_0 is required because of a bug in OP_CHECKMULTISIG; it pops one too many items off the execution stack, so a dummy value must be placed on the stack).
The current Satoshi bitcoin client does not relay or mine transactions with scriptSigs larger than 200 bytes; to accomodate 3-signature transactions, this will be increased to 500 bytes.
==Rationale==
OP_CHECKMULTISIG is already an enabled opcode, and is the most straightforward way to support several important use cases.
One argument against using OP_CHECKMULTISIG is that old clients and miners count it as "20 sigops" for purposes of computing how many signature operations are in a block, and there is a hard limit of 20,000 sigops per block-- meaning a maximum of 1,000 multisig transactions per block. Creating multisig transactions using multiple OP_CHECKSIG operations allows more of them per block.
The counter-argument is that these new multi-signature transactions will be used in combination with OP_EVAL (see the OP_EVAL BIP), and '''will''' be counted accurately. And in any case, as transaction volume rises the hard-coded maximum block size will have to be addressed, and the rules for counting number-of-signature-operations-in-a-block can be addressed at that time.
A weaker argument is OP_CHECKMULTISIG should not be used because it pops one too many items off the stack during validation. Adding an extra OP_0 placeholder to the scriptSig adds only 1 byte to the transaction, and any alternative that avoids OP_CHECKMULTISIG adds at least several bytes of opcodes.
==Implementation==
OP_CHECKMULTISIG is already supported by old clients and miners as a non-standard transaction type.
https://github.com/gavinandresen/bitcoin-git/tree/op_eval
== Post History ==
* [https://bitcointalk.org/index.php?topic=46538 OP_EVAL proposal]

104
selected BIPs/bip-0013.asciidoc
View File

@ -1,104 +0,0 @@
--------------------------------------------------
BIP: 13
Title: Address Format for pay-to-script-hash
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Final
Type: Standards Track
Created: 2011-10-18
--------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP describes a new type of Bitcoin address to support arbitrarily
complex transactions. Complexity in this context is defined as what
information is needed by the recipient to respend the received coins, in
contrast to needing a single ECDSA private key as in current
implementations of Bitcoin.
In essence, an address encoded under this proposal represents the
encoded hash of a script, rather than the encoded hash of an ECDSA
public key.
[[motivation]]
Motivation
~~~~~~~~~~
Enable "end-to-end" secure wallets and payments to fund escrow
transactions or other complex transactions. Enable third-party wallet
security services.
[[specification]]
Specification
~~~~~~~~~~~~~
The new bitcoin address type is constructed in the same manner as
existing bitcoin addresses (see link:Base58Check encoding[Base58Check
encoding]):
`   base58-encode: [one-byte version][20-byte hash][4-byte checksum]`
Version byte is 5 for a main-network address, 196 for a testnet address.
The 20-byte hash is the hash of the script that will be used to redeem
the coins. And the 4-byte checksum is the first four bytes of the double
SHA256 hash of the version and hash.
[[rationale]]
Rationale
~~~~~~~~~
One criticism is that bitcoin addresses should be deprecated in favor of
a more user-friendly mechanism for payments, and that this will just
encourage continued use of a poorly designed mechanism.
Another criticism is that bitcoin addresses are inherently insecure
because there is no identity information tied to them; if you only have
a bitcoin address, how can you be certain that you're paying who or what
you think you're paying?
Furthermore, truncating SHA256 is not an optimal checksum; there are
much better error-detecting algorithms. If we are introducing a new form
of Bitcoin address, then perhaps a better algorithm should be used.
This is one piece of the simplest path to a more secure bitcoin
infrastructure. It is not intended to solve all of bitcoin's usability
or security issues, but to be an incremental improvement over what
exists today. A future BIP or BIPs should propose more user-friendly
mechanisms for making payments, or for verifying that you're sending a
payment to the Free Software Foundation and not Joe Random Hacker.
Assuming that typing in bitcoin addresses manually will become
increasingly rare in the future, and given that the existing checksum
method for bitcoin addresses seems to work "well enough" in practice and
has already been implemented multiple times, the Author believes no
change to the checksum algorithm is necessary.
The leading version bytes are chosen so that, after base58 encoding, the
leading character is consistent: for the main network, byte 5 becomes
the character '3'. For the testnet, byte 196 is encoded into '2'.
[[backwards-compatibility]]
Backwards Compatibility
~~~~~~~~~~~~~~~~~~~~~~~
This proposal is not backwards compatible, but it fails gracefully-- if
an older implementation is given one of these new bitcoin addresses, it
will report the address as invalid and will refuse to create a
transaction.
[[reference-implementation]]
Reference Implementation
~~~~~~~~~~~~~~~~~~~~~~~~
See base58.cpp1/base58.h at https://github.com/bitcoin/bitcoin/src
[[see-also]]
See Also
~~~~~~~~
* link:bip-0012.mediawiki[BIP 12: OP_EVAL, the original P2SH design]
* link:bip-0016.mediawiki[BIP 16: Pay to Script Hash (aka "/P2SH/")]
* link:bip-0017.mediawiki[BIP 17: OP_CHECKHASHVERIFY, another P2SH
design]

56
selected BIPs/bip-0013.mediawiki
View File

@ -1,56 +0,0 @@
<pre>
BIP: 13
Title: Address Format for pay-to-script-hash
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Final
Type: Standards Track
Created: 2011-10-18
</pre>
==Abstract==
This BIP describes a new type of Bitcoin address to support arbitrarily complex transactions. Complexity in this context is defined as what information is needed by the recipient to respend the received coins, in contrast to needing a single ECDSA private key as in current implementations of Bitcoin.
In essence, an address encoded under this proposal represents the encoded hash of a [[script]], rather than the encoded hash of an ECDSA public key.
==Motivation==
Enable "end-to-end" secure wallets and payments to fund escrow transactions or other complex transactions. Enable third-party wallet security services.
==Specification==
The new bitcoin address type is constructed in the same manner as existing bitcoin addresses (see [[Base58Check encoding]]):
base58-encode: [one-byte version][20-byte hash][4-byte checksum]
Version byte is 5 for a main-network address, 196 for a testnet address.
The 20-byte hash is the hash of the script that will be used to redeem the coins.
And the 4-byte checksum is the first four bytes of the double SHA256 hash of the version and hash.
==Rationale==
One criticism is that bitcoin addresses should be deprecated in favor of a more user-friendly mechanism for payments, and that this will just encourage continued use of a poorly designed mechanism.
Another criticism is that bitcoin addresses are inherently insecure because there is no identity information tied to them; if you only have a bitcoin address, how can you be certain that you're paying who or what you think you're paying?
Furthermore, truncating SHA256 is not an optimal checksum; there are much better error-detecting algorithms. If we are introducing a new form of Bitcoin address, then perhaps a better algorithm should be used.
This is one piece of the simplest path to a more secure bitcoin infrastructure. It is not intended to solve all of bitcoin's usability or security issues, but to be an incremental improvement over what exists today. A future BIP or BIPs should propose more user-friendly mechanisms for making payments, or for verifying that you're sending a payment to the Free Software Foundation and not Joe Random Hacker.
Assuming that typing in bitcoin addresses manually will become increasingly rare in the future, and given that the existing checksum method for bitcoin addresses seems to work "well enough" in practice and has already been implemented multiple times, the Author believes no change to the checksum algorithm is necessary.
The leading version bytes are chosen so that, after base58 encoding, the leading character is consistent: for the main network, byte 5 becomes the character '3'. For the testnet, byte 196 is encoded into '2'.
==Backwards Compatibility==
This proposal is not backwards compatible, but it fails gracefully-- if an older implementation is given one of these new bitcoin addresses, it will report the address as invalid and will refuse to create a transaction.
==Reference Implementation==
See base58.cpp1/base58.h at https://github.com/bitcoin/bitcoin/src
==See Also==
* [[bip-0012.mediawiki|BIP 12: OP_EVAL, the original P2SH design]]
* [[bip-0016.mediawiki|BIP 16: Pay to Script Hash (aka "/P2SH/")]]
* [[bip-0017.mediawiki|BIP 17: OP_CHECKHASHVERIFY, another P2SH design]]

173
selected BIPs/bip-0014.asciidoc
View File

@ -1,173 +0,0 @@
------------------------------------------------------------
BIP: 14
Title: BIP Protocol Version and User Agent
Author: Amir Taaki <genjix@riseup.net>
Patrick Strateman <bitcoin-bips@covertinferno.org>
Status: Accepted
Type: Standards Track
Created: 2011-11-10
Post-History: 2011-11-02
------------------------------------------------------------
In this document, bitcoin will be used to refer to the protocol while
Satoshi will refer to the current client in order to prevent confusion.
[[past-situation]]
Past Situation
~~~~~~~~~~~~~~
Bitcoin as a protocol began life with the Satoshi client. Now that the
community is diversifying, a number of alternative clients with their
own codebases written in a variety of languages (Java, Python,
Javascript, C++) are rapidly developing their own feature-sets.
Embedded in the protocol is a version number. Primarily this version
number is in the "version" and "getblocks" messages, but is also in the
"block" message to indicate the software version that created that
block. Currently this version number is the same version number as that
of the client. This document is a proposal to separate the protocol
version from the client version, together with a proposed method to do
so.
[[rationale]]
Rationale
~~~~~~~~~
With non-separated version numbers, every release of the Satoshi client
will increase its internal version number. Primarily this holds every
other client hostage to a game of catch-up with Satoshi version number
schemes. This plays against the decentralised nature of bitcoin, by
forcing every software release to remain in step with the release
schedule of one group of bitcoin developers.
Version bumping can also introduce incompatibilities and fracture the
network. In order that the health of the network is maintained, the
development of the protocol as a shared common collaborative process
requires being split off from the implementation of that protocol.
Neutral third entities to guide the protocol with representatives from
all groups, present the chance for bitcoin to grow in a positive manner
with minimal risks.
By using a protocol version, we set all implementations on the network
to a common standard. Everybody is able to agree within their confines
what is protocol and what is implementation-dependent. A user agent
string is offered as a 'vanity-plate' for clients to distinguish
themselves in the network.
Separation of the network protocol from the implemention, and forming
development of said protocol by means of a mutual consensus among
participants, has the democratic disadvantage when agreement is hard to
reach on contentious issues. To mitigate this issue, strong
communication channels and fast release schedules are needed, and are
outside the scope of this document (concerning a process-BIP type).
User agents provide extra tracking information that is useful for
keeping tabs on network data such as client implementations used or
common architectures/operating-systems. In the rare case they may even
provide an emergency method of shunning faulty clients that threaten
network health- although this is strongly unrecommended and extremely
bad form. The user agent does not provide a method for clients to work
around and behave differently to different implementations, as this will
lead to protocol fracturing.
In short:
* Protocol version: way to distinguish between nodes and behave
different accordingly.
* User agent: simple informational tool. Protocol should not be modified
depending on user agent.
[[browser-user-agents]]
Browser User-Agents
~~~~~~~~~~~~~~~~~~~
http://tools.ietf.org/html/rfc1945[RFC 1945] vaguely specifies a user
agent to be a string of the product with optional comments.
` Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1.6) Gecko/20100127 Gentoo Shiretoko/3.5.6`
User agents are most often parsed by computers more than humans. The
space delimited format, does not provide an easy, fast or efficient way
for parsing. The data contains no structure indicating hierarchy in this
placement.
The most immediate pieces of information there are the browser product,
rendering engine and the build (Gentoo Shiretoko) together with version
number. Various other pieces of information as included as comments such
as desktop environment, platform, language and revision number of the
build.
[[proposal]]
Proposal
~~~~~~~~
The version field in "version" and "getblocks" packets will become the
protocol version number. The version number in the "blocks" reflects the
protocol version from when that block was created.
The currently unused sub_version_num field in "version" packets will
become the new user-agent string.
Bitcoin user agents are a modified browser user agent with more
structure to aid parsers and provide some coherence. In bitcoin, the
software usually works like a stack starting from the core code-base up
to the end graphical interface. Therefore the user agent strings codify
this relationship.
Basic format:
` /Name:Version/Name:Version/.../`
Example:
` /Satoshi:5.64/bitcoin-qt:0.4/` +
` /Satoshi:5.12/Spesmilo:0.8/`
Here bitcoin-qt and Spesmilo may use protocol version 5.0, however the
internal codebase they use are different versions of the same software.
The version numbers are not defined to any strict format, although this
guide recommends:
* Version numbers in the form of Major.Minor.Revision (2.6.41)
* Repository builds using a date in the format of YYYYMMDD (20110128)
For git repository builds, implementations are free to use the git
commitish. However the issue lies in that it is not immediately obvious
without the repository which version precedes another. For this reason,
we lightly recommend dates in the format specified above, although this
is by no means a requirement.
Optional -r1, -r2, ... can be appended to user agent version numbers.
This is another light recommendation, but not a requirement.
Implementations are free to specify version numbers in whatever format
needed insofar as it does not include (, ), : or / to interfere with the
user agent syntax.
An optional comments field after the version number is also allowed.
Comments should be delimited by brackets (...). The contents of comments
is entirely implementation defined although this BIP recommends the use
of semi-colons ; as a delimiter between pieces of information.
Example:
` /BitcoinJ:0.2(iPad; U; CPU OS 3_2_1)/AndroidBuild:0.8/`
Reserved symbols are therefore: / : ( )
They should not be misused beyond what is specified in this section.
* / separates the code-stack
* ::
specifies the implementation version of the particular stack
* ( and ) delimits a comment which optionally separates data using ;
[[timeline]]
Timeline
~~~~~~~~
When this document was published, the bitcoin protocol and Satoshi
client versions were currently at 0.5 and undergoing changes. In order
to minimise disruption and allow the undergoing changes to be completed,
the next protocol version at 0.6 became peeled from the client version
(also at 0.6). As of that time (January 2012), protocol and
implementation version numbers are distinct from each other.

89
selected BIPs/bip-0014.mediawiki
View File

@ -1,89 +0,0 @@
<pre>
BIP: 14
Title: BIP Protocol Version and User Agent
Author: Amir Taaki <genjix@riseup.net>
Patrick Strateman <bitcoin-bips@covertinferno.org>
Status: Accepted
Type: Standards Track
Created: 2011-11-10
Post-History: 2011-11-02
</pre>
In this document, bitcoin will be used to refer to the protocol while Satoshi will refer to the current client in order to prevent confusion.
== Past Situation ==
Bitcoin as a protocol began life with the Satoshi client. Now that the community is diversifying, a number of alternative clients with their own codebases written in a variety of languages (Java, Python, Javascript, C++) are rapidly developing their own feature-sets.
Embedded in the protocol is a version number. Primarily this version number is in the "version" and "getblocks" messages, but is also in the "block" message to indicate the software version that created that block. Currently this version number is the same version number as that of the client. This document is a proposal to separate the protocol version from the client version, together with a proposed method to do so.
== Rationale ==
With non-separated version numbers, every release of the Satoshi client will increase its internal version number. Primarily this holds every other client hostage to a game of catch-up with Satoshi version number schemes. This plays against the decentralised nature of bitcoin, by forcing every software release to remain in step with the release schedule of one group of bitcoin developers.
Version bumping can also introduce incompatibilities and fracture the network. In order that the health of the network is maintained, the development of the protocol as a shared common collaborative process requires being split off from the implementation of that protocol. Neutral third entities to guide the protocol with representatives from all groups, present the chance for bitcoin to grow in a positive manner with minimal risks.
By using a protocol version, we set all implementations on the network to a common standard. Everybody is able to agree within their confines what is protocol and what is implementation-dependent. A user agent string is offered as a 'vanity-plate' for clients to distinguish themselves in the network.
Separation of the network protocol from the implemention, and forming development of said protocol by means of a mutual consensus among participants, has the democratic disadvantage when agreement is hard to reach on contentious issues. To mitigate this issue, strong communication channels and fast release schedules are needed, and are outside the scope of this document (concerning a process-BIP type).
User agents provide extra tracking information that is useful for keeping tabs on network data such as client implementations used or common architectures/operating-systems. In the rare case they may even provide an emergency method of shunning faulty clients that threaten network health- although this is strongly unrecommended and extremely bad form. The user agent does not provide a method for clients to work around and behave differently to different implementations, as this will lead to protocol fracturing.
In short:
* Protocol version: way to distinguish between nodes and behave different accordingly.
* User agent: simple informational tool. Protocol should not be modified depending on user agent.
== Browser User-Agents ==
[http://tools.ietf.org/html/rfc1945 RFC 1945] vaguely specifies a user agent to be a string of the product with optional comments.
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1.6) Gecko/20100127 Gentoo Shiretoko/3.5.6
User agents are most often parsed by computers more than humans. The space delimited format, does not provide an easy, fast or efficient way for parsing. The data contains no structure indicating hierarchy in this placement.
The most immediate pieces of information there are the browser product, rendering engine and the build (Gentoo Shiretoko) together with version number. Various other pieces of information as included as comments such as desktop environment, platform, language and revision number of the build.
== Proposal ==
The version field in "version" and "getblocks" packets will become the protocol version number. The version number in the "blocks" reflects the protocol version from when that block was created.
The currently unused sub_version_num field in "version" packets will become the new user-agent string.
Bitcoin user agents are a modified browser user agent with more structure to aid parsers and provide some coherence. In bitcoin, the software usually works like a stack starting from the core code-base up to the end graphical interface. Therefore the user agent strings codify this relationship.
Basic format:
/Name:Version/Name:Version/.../
Example:
/Satoshi:5.64/bitcoin-qt:0.4/
/Satoshi:5.12/Spesmilo:0.8/
Here bitcoin-qt and Spesmilo may use protocol version 5.0, however the internal codebase they use are different versions of the same software. The version numbers are not defined to any strict format, although this guide recommends:
* Version numbers in the form of Major.Minor.Revision (2.6.41)
* Repository builds using a date in the format of YYYYMMDD (20110128)
For git repository builds, implementations are free to use the git commitish. However the issue lies in that it is not immediately obvious without the repository which version precedes another. For this reason, we lightly recommend dates in the format specified above, although this is by no means a requirement.
Optional -r1, -r2, ... can be appended to user agent version numbers. This is another light recommendation, but not a requirement. Implementations are free to specify version numbers in whatever format needed insofar as it does not include (, ), : or / to interfere with the user agent syntax.
An optional comments field after the version number is also allowed. Comments should be delimited by brackets (...). The contents of comments is entirely implementation defined although this BIP recommends the use of semi-colons ; as a delimiter between pieces of information.
Example:
/BitcoinJ:0.2(iPad; U; CPU OS 3_2_1)/AndroidBuild:0.8/
Reserved symbols are therefore: / : ( )
They should not be misused beyond what is specified in this section.
* / separates the code-stack
* : specifies the implementation version of the particular stack
* ( and ) delimits a comment which optionally separates data using ;
== Timeline ==
When this document was published, the bitcoin protocol and Satoshi client versions were currently at 0.5 and undergoing changes. In order to minimise disruption and allow the undergoing changes to be completed, the next protocol version at 0.6 became peeled from the client version (also at 0.6). As of that time (January 2012), protocol and implementation version numbers are distinct from each other.

223
selected BIPs/bip-0016.asciidoc
View File

@ -1,223 +0,0 @@
--------------------------------------------------
BIP: 16
Title: Pay to Script Hash
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Final
Type: Standards Track
Created: 2012-01-03
--------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP describes a new "standard" transaction type for the Bitcoin
scripting system, and defines additional validation rules that apply
only to the new transactions.
[[motivation]]
Motivation
~~~~~~~~~~
The purpose of pay-to-script-hash is to move the responsibility for
supplying the conditions to redeem a transaction from the sender of the
funds to the redeemer.
The benefit is allowing a sender to fund any arbitrary transaction, no
matter how complicated, using a fixed-length 20-byte hash that is short
enough to scan from a QR code or easily copied and pasted.
[[specification]]
Specification
~~~~~~~~~~~~~
A new standard transaction type that is relayed and included in mined
blocks is defined:
`   OP_HASH160 [20-byte-hash-value] OP_EQUAL`
[20-byte-hash-value] shall be the push-20-bytes-onto-the-stack opcode
(0x14) followed by exactly 20 bytes.
This new transaction type is redeemed by a standard scriptSig:
`   ...signatures... {serialized script}`
Transactions that redeem these pay-to-script outpoints are only
considered standard if the _serialized script_ - also referred to as the
_redeemScript_ - is, itself, one of the other standard transaction
types.
The rules for validating these outpoints when relaying transactions or
considering them for inclusion in a new block are as follows:
1. Validation fails if there are any operations other than "push data"
operations in the scriptSig.
2. Normal validation is done: an initial stack is created from the
signatures and \{serialized script}, and the hash of the script is
computed and validation fails immediately if it does not match the hash
in the outpoint.
3. \{serialized script} is popped off the initial stack, and the
transaction is validated again using the popped stack and the
deserialized script as the scriptPubKey.
These new rules should only be applied when validating transactions in
blocks with timestamps >= 1333238400 (Apr 1 2012)
footnote:[https://github.com/bitcoin/bitcoin/commit/8f188ece3c82c4cf5d52a3363e7643c23169c0ff[Remove
-bip16 and -paytoscripthashtime command-line arguments]]. There are
transaction earlier than 13333238400 in the block chain that fail these
new validation rules.
footnote:[http://blockexplorer.com/tx/6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192[Transaction
6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192]].
Older transactions must be validated under the old rules. (see the
Backwards Compatibility section for details).
For example, the scriptPubKey and corresponding scriptSig for a
one-signature-required transaction is:
`   scriptSig: [signature] {[pubkey] OP_CHECKSIG}` +
`   scriptPubKey: OP_HASH160 [20-byte-hash of {[pubkey] OP_CHECKSIG} ] OP_EQUAL`
Signature operations in the \{serialized script} shall contribute to the
maximum number allowed per block (20,000) as follows:
1. OP_CHECKSIG and OP_CHECKSIGVERIFY count as 1 signature operation,
whether or not they are evaluated.
2. OP_CHECKMULTISIG and OP_CHECKMULTISIGVERIFY immediately preceded by
OP_1 through OP_16 are counted as 1 to 16 signature operation, whether
or not they are evaluated.
3. All other OP_CHECKMULTISIG and OP_CHECKMULTISIGVERIFY are counted as
20 signature operations.
Examples:
+3 signature operations:
`   {2 [pubkey1] [pubkey2] [pubkey3] 3 OP_CHECKMULTISIG}`
+22 signature operations
`   {OP_CHECKSIG OP_IF OP_CHECKSIGVERIFY OP_ELSE OP_CHECKMULTISIGVERIFY OP_ENDIF}`
[[rationale]]
Rationale
~~~~~~~~~
This BIP replaces BIP 12, which proposed a new Script opcode ("OP_EVAL")
to accomplish everything in this BIP and more.
The Motivation for this BIP (and BIP 13, the pay-to-script-hash address
type) is somewhat controversial; several people feel that it is
unnecessary, and complex/multisignature transaction types should be
supported by simply giving the sender the complete \{serialized script}.
The author believes that this BIP will minimize the changes needed to
all of the supporting infrastructure that has already been created to
send funds to a base58-encoded-20-byte bitcoin addresses, allowing
merchants and exchanges and other software to start supporting
multisignature transactions sooner.
Recognizing one 'special' form of scriptPubKey and performing extra
validation when it is detected is ugly. However, the consensus is that
the alternatives are either uglier, are more complex to implement,
and/or expand the power of the expression language in dangerous ways.
The signature operation counting rules are intended to be easy and quick
to implement by statically scanning the \{serialized script}. Bitcoin
imposes a maximum-number-of-signature-operations per block to prevent
denial-of-service attacks on miners. If there was no limit, a rogue
miner might broadcast a block that required hundreds of thousands of
ECDSA signature operations to validate, and it might be able to get a
head start computing the next block while the rest of the network worked
to validate the current one.
There is a 1-confirmation attack on old implementations, but it is
expensive and difficult in practice. The attack is:
1. Attacker creates a pay-to-script-hash transaction that is valid as
seen by old software, but invalid for new implementation, and sends
themselves some coins using it.
2. Attacker also creates a standard transaction that spends the
pay-to-script transaction, and pays the victim who is running old
software.
3. Attacker mines a block that contains both transactions.
If the victim accepts the 1-confirmation payment, then the attacker wins
because both transactions will be invalidated when the rest of the
network overwrites the attacker's invalid block.
The attack is expensive because it requires the attacker create a block
that they know will be invalidated by the rest of the network. It is
difficult because creating blocks is difficult and users should not
accept 1-confirmation transactions for higher-value transactions.
[[backwards-compatibility]]
Backwards Compatibility
~~~~~~~~~~~~~~~~~~~~~~~
These transactions are non-standard to old implementations, which will
(typically) not relay them or include them in blocks.
Old implementations will validate that the \{serialize script}'s hash
value matches when they validate blocks created by software that fully
support this BIP, but will do no other validation.
Avoiding a block-chain split by malicious pay-to-script transactions
requires careful handling of one case:
* A pay-to-script-hash transaction that is invalid for new
clients/miners but valid for old clients/miners.
To gracefully upgrade and ensure no long-lasting block-chain split
occurs, more than 50% of miners must support full validation of the new
transaction type and must switch from the old validation rules to the
new rules at the same time.
To judge whether or not more than 50% of hashing power supports this
BIP, miners are asked to upgrade their software and put the string
"/P2SH/" in the input of the coinbase transaction for blocks that they
create.
On February 1, 2012, the block-chain will be examined to determine the
number of blocks supporting pay-to-script-hash for the previous 7 days.
If 550 or more contain "/P2SH/" in their coinbase, then all blocks with
timestamps after 15 Feb 2012, 00:00:00 GMT shall have their
pay-to-script-hash transactions fully validated. Approximately 1,000
blocks are created in a week; 550 should, therefore, be approximately
55% of the network supporting the new feature.
If a majority of hashing power does not support the new validation
rules, then rollout will be postponed (or rejected if it becomes clear
that a majority will never be achieved).
[[byte-limitation-on-serialized-script-size]]
520-byte limitation on serialized script size
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As a consequence of the requirement for backwards compatiblity the
serialized script is itself subject to the same rules as any other
PUSHDATA operation, including the rule that no data greater than 520
bytes may be pushed to the stack. Thus is it not possible to spend a
P2SH output if the redemption script it refers to is >520 bytes in
length. For instance while the OP_CHECKMULTISIG opcode can itself accept
up to 20 pubkeys, with 33-byte compressed pubkeys it is only possible to
spend a P2SH output requiring a maximum of 15 pubkeys to redeem: 3 bytes
+ 15 pubkeys * 34 bytes/pubkey = 513 bytes.
[[reference-implementation]]
Reference Implementation
~~~~~~~~~~~~~~~~~~~~~~~~
https://gist.github.com/gavinandresen/3966071
[[see-also]]
See Also
~~~~~~~~
* https://bitcointalk.org/index.php?topic=46538
* The link:bip-0013.mediawiki[Address format for Pay to Script Hash BIP]
* M-of-N Multisignature Transactions link:bip-0011.mediawiki[BIP 11]
* link:bip-0016/qa.mediawiki[Quality Assurance test checklist]
[[references]]
References
~~~~~~~~~~

116
selected BIPs/bip-0016.mediawiki
View File

@ -1,116 +0,0 @@
<pre>
BIP: 16
Title: Pay to Script Hash
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Final
Type: Standards Track
Created: 2012-01-03
</pre>
==Abstract==
This BIP describes a new "standard" transaction type for the Bitcoin scripting system, and defines additional validation rules that apply only to the new transactions.
==Motivation==
The purpose of pay-to-script-hash is to move the responsibility for supplying the conditions to redeem a transaction from the sender of the funds to the redeemer.
The benefit is allowing a sender to fund any arbitrary transaction, no matter how complicated, using a fixed-length 20-byte hash that is short enough to scan from a QR code or easily copied and pasted.
==Specification==
A new standard transaction type that is relayed and included in mined blocks is defined:
OP_HASH160 [20-byte-hash-value] OP_EQUAL
[20-byte-hash-value] shall be the push-20-bytes-onto-the-stack opcode (0x14) followed by exactly 20 bytes.
This new transaction type is redeemed by a standard scriptSig:
...signatures... {serialized script}
Transactions that redeem these pay-to-script outpoints are only considered standard if the ''serialized script'' - also referred to as the ''redeemScript'' - is, itself, one of the other standard transaction types.
The rules for validating these outpoints when relaying transactions or considering them for inclusion in a new block are as follows:
# Validation fails if there are any operations other than "push data" operations in the scriptSig.
# Normal validation is done: an initial stack is created from the signatures and {serialized script}, and the hash of the script is computed and validation fails immediately if it does not match the hash in the outpoint.
# {serialized script} is popped off the initial stack, and the transaction is validated again using the popped stack and the deserialized script as the scriptPubKey.
These new rules should only be applied when validating transactions in blocks with timestamps >= 1333238400 (Apr 1 2012) <ref>[https://github.com/bitcoin/bitcoin/commit/8f188ece3c82c4cf5d52a3363e7643c23169c0ff Remove -bip16 and -paytoscripthashtime command-line arguments]</ref>. There are transaction earlier than 13333238400 in the block chain that fail these new validation rules. <ref>[http://blockexplorer.com/tx/6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192 Transaction 6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192]</ref>. Older transactions must be validated under the old rules. (see the Backwards Compatibility section for details).
For example, the scriptPubKey and corresponding scriptSig for a one-signature-required transaction is:
scriptSig: [signature] {[pubkey] OP_CHECKSIG}
scriptPubKey: OP_HASH160 [20-byte-hash of {[pubkey] OP_CHECKSIG} ] OP_EQUAL
Signature operations in the {serialized script} shall contribute to the maximum number allowed per block (20,000) as follows:
# OP_CHECKSIG and OP_CHECKSIGVERIFY count as 1 signature operation, whether or not they are evaluated.
# OP_CHECKMULTISIG and OP_CHECKMULTISIGVERIFY immediately preceded by OP_1 through OP_16 are counted as 1 to 16 signature operation, whether or not they are evaluated.
# All other OP_CHECKMULTISIG and OP_CHECKMULTISIGVERIFY are counted as 20 signature operations.
Examples:
+3 signature operations:
{2 [pubkey1] [pubkey2] [pubkey3] 3 OP_CHECKMULTISIG}
+22 signature operations
{OP_CHECKSIG OP_IF OP_CHECKSIGVERIFY OP_ELSE OP_CHECKMULTISIGVERIFY OP_ENDIF}
==Rationale==
This BIP replaces BIP 12, which proposed a new Script opcode ("OP_EVAL") to accomplish everything in this BIP and more.
The Motivation for this BIP (and BIP 13, the pay-to-script-hash address type) is somewhat controversial; several people feel that it is unnecessary, and complex/multisignature transaction types should be supported by simply giving the sender the complete {serialized script}. The author believes that this BIP will minimize the changes needed to all of the supporting infrastructure that has already been created to send funds to a base58-encoded-20-byte bitcoin addresses, allowing merchants and exchanges and other software to start supporting multisignature transactions sooner.
Recognizing one 'special' form of scriptPubKey and performing extra validation when it is detected is ugly. However, the consensus is that the alternatives are either uglier, are more complex to implement, and/or expand the power of the expression language in dangerous ways.
The signature operation counting rules are intended to be easy and quick to implement by statically scanning the {serialized script}. Bitcoin imposes a maximum-number-of-signature-operations per block to prevent denial-of-service attacks on miners. If there was no limit, a rogue miner might broadcast a block that required hundreds of thousands of ECDSA signature operations to validate, and it might be able to get a head start computing the next block while the rest of the network worked to validate the current one.
There is a 1-confirmation attack on old implementations, but it is expensive and difficult in practice. The attack is:
# Attacker creates a pay-to-script-hash transaction that is valid as seen by old software, but invalid for new implementation, and sends themselves some coins using it.
# Attacker also creates a standard transaction that spends the pay-to-script transaction, and pays the victim who is running old software.
# Attacker mines a block that contains both transactions.
If the victim accepts the 1-confirmation payment, then the attacker wins because both transactions will be invalidated when the rest of the network overwrites the attacker's invalid block.
The attack is expensive because it requires the attacker create a block that they know will be invalidated by the rest of the network. It is difficult because creating blocks is difficult and users should not accept 1-confirmation transactions for higher-value transactions.
==Backwards Compatibility==
These transactions are non-standard to old implementations, which will (typically) not relay them or include them in blocks.
Old implementations will validate that the {serialize script}'s hash value matches when they validate blocks created by software that fully support this BIP, but will do no other validation.
Avoiding a block-chain split by malicious pay-to-script transactions requires careful handling of one case:
* A pay-to-script-hash transaction that is invalid for new clients/miners but valid for old clients/miners.
To gracefully upgrade and ensure no long-lasting block-chain split occurs, more than 50% of miners must support full validation of the new transaction type and must switch from the old validation rules to the new rules at the same time.
To judge whether or not more than 50% of hashing power supports this BIP, miners are asked to upgrade their software and put the string "/P2SH/" in the input of the coinbase transaction for blocks that they create.
On February 1, 2012, the block-chain will be examined to determine the number of blocks supporting pay-to-script-hash for the previous 7 days. If 550 or more contain "/P2SH/" in their coinbase, then all blocks with timestamps after 15 Feb 2012, 00:00:00 GMT shall have their pay-to-script-hash transactions fully validated. Approximately 1,000 blocks are created in a week; 550 should, therefore, be approximately 55% of the network supporting the new feature.
If a majority of hashing power does not support the new validation rules, then rollout will be postponed (or rejected if it becomes clear that a majority will never be achieved).
===520-byte limitation on serialized script size===
As a consequence of the requirement for backwards compatiblity the serialized script is itself subject to the same rules as any other PUSHDATA operation, including the rule that no data greater than 520 bytes may be pushed to the stack. Thus is it not possible to spend a P2SH output if the redemption script it refers to is >520 bytes in length. For instance while the OP_CHECKMULTISIG opcode can itself accept up to 20 pubkeys, with 33-byte compressed pubkeys it is only possible to spend a P2SH output requiring a maximum of 15 pubkeys to redeem: 3 bytes + 15 pubkeys * 34 bytes/pubkey = 513 bytes.
==Reference Implementation==
https://gist.github.com/gavinandresen/3966071
==See Also==
* https://bitcointalk.org/index.php?topic=46538
* The [[bip-0013.mediawiki|Address format for Pay to Script Hash BIP]]
* M-of-N Multisignature Transactions [[bip-0011.mediawiki|BIP 11]]
* [[bip-0016/qa.mediawiki|Quality Assurance test checklist]]
== References ==
<references>

223
selected BIPs/bip-0021.asciidoc
View File

@ -1,223 +0,0 @@
---------------------------------------------------
BIP: 21
Title: URI Scheme
Author: Nils Schneider <nils.schneider@gmail.com>
Matt Corallo <bip21@bluematt.me>
Status: Accepted
Type: Standards Track
Created: 2012-01-29
---------------------------------------------------
This BIP is a modification of an earlier link:bip-0020.mediawiki[BIP
0020] by Luke Dashjr. BIP 0020 was based off an earlier document by Nils
Schneider. The alternative payment amounts in BIP 0020 have been
removed.
[[abstract]]
Abstract
~~~~~~~~
This BIP proposes a URI scheme for making Bitcoin payments.
[[motivation]]
Motivation
~~~~~~~~~~
The purpose of this URI scheme is to enable users to easily make
payments by simply clicking links on webpages or scanning QR Codes.
[[specification]]
Specification
~~~~~~~~~~~~~
[[general-rules-for-handling-important]]
General rules for handling (important!)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Bitcoin clients MUST NOT act on URIs without getting the user's
authorization. They SHOULD require the user to manually approve each
payment individually, though in some cases they MAY allow the user to
automatically make this decision.
[[operating-system-integration]]
Operating system integration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Graphical bitcoin clients SHOULD register themselves as the handler for
the "bitcoin:" URI scheme by default, if no other handler is already
registered. If there is already a registered handler, they MAY prompt
the user to change it once when they first run the client.
[[general-format]]
General Format
^^^^^^^^^^^^^^
Bitcoin URIs follow the general format for URIs as set forth in RFC
3986. The path component consists of a bitcoin address, and the query
component provides additional payment options.
Elements of the query component may contain characters outside the valid
range. These must first be encoded according to UTF-8, and then each
octet of the corresponding UTF-8 sequence must be percent-encoded as
described in RFC 3986.
[[abnf-grammar]]
ABNF grammar
^^^^^^^^^^^^
(See also link:#Simpler_syntax[a simpler representation of syntax])
`bitcoinurn     = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]` +
`bitcoinaddress = *base58` +
`bitcoinparams  = bitcoinparam [ "&" bitcoinparams ]` +
`bitcoinparam   = [ amountparam / labelparam / messageparam / otherparam / reqparam ]` +
`amountparam    = "amount=" *digit [ "." *digit ]` +
`labelparam     = "label=" *qchar` +
`messageparam   = "message=" *qchar` +
`otherparam     = qchar *qchar [ "=" *qchar ]` +
`reqparam       = "req-" qchar *qchar [ "=" *qchar ]`
Here, "qchar" corresponds to valid characters of an RFC 3986 URI query
component, excluding the "=" and "&" characters, which this BIP takes as
separators.
The scheme component ("bitcoin:") is case-insensitive, and
implementations must accept any combination of uppercase and lowercase
letters. The rest of the URI is case-sensitive, including the query
parameter keys.
[[query-keys]]
Query Keys
^^^^^^^^^^
* label: Label for that address (e.g. name of receiver)
* address: bitcoin address
* message: message that describes the transaction to the user
(link:#Examples[see examples below])
* size: amount of base bitcoin units (link:#Transfer_amount/size[see
below])
* (others): optional, for future extensions
[[transfer-amountsize]]
Transfer amount/size
++++++++++++++++++++
If an amount is provided, it MUST be specified in decimal BTC. All
amounts MUST contain no commas and use a period (.) as the separating
character to separate whole numbers and decimal fractions. I.e.
amount=50.00 or amount=50 is treated as 50 BTC, and amount=50,000.00 is
invalid.
Bitcoin clients MAY display the amount in any format that is not
intended to deceive the user. They SHOULD choose a format that is
foremost least confusing, and only after that most reasonable given the
amount requested. For example, so long as the majority of users work in
BTC units, values should always be displayed in BTC by default, even if
mBTC or TBC would otherwise be a more logical interpretation of the
amount.
[[rationale]]
Rationale
~~~~~~~~~
[[payment-identifiers-not-person-identifiers]]
Payment identifiers, not person identifiers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Current best practices are that a unique address should be used for
every transaction. Therefore, a URI scheme should not represent an
exchange of personal information, but a one-time payment.
[[accessibility-uri-scheme-name]]
Accessibility (URI scheme name)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Should someone from the outside happen to see such a URI, the URI scheme
name already gives a description. A quick search should then do the rest
to help them find the resources needed to make their payment. Other
proposed names sound much more cryptic; the chance that someone googles
that out of curiosity are much slimmer. Also, very likely, what he will
find are mostly technical specifications - not the best introduction to
bitcoin.
[[forward-compatibility]]
Forward compatibility
~~~~~~~~~~~~~~~~~~~~~
Variables which are prefixed with a req- are considered required. If a
client does not implement any variables which are prefixed with req-, it
MUST consider the entire URI invalid. Any other variables which are not
implemented, but which are not prefixed with a req-, can be safely
ignored.
[[backward-compatibility]]
Backward compatibility
~~~~~~~~~~~~~~~~~~~~~~
As this BIP is written, several clients already implement a bitcoin: URI
scheme similar to this one, however usually without the additional
"req-" prefix requirement. Thus, it is recommended that additional
variables prefixed with req- not be used in a mission-critical way until
a grace period of 6 months from the finalization of this BIP has passed
in order to allow client developers to release new versions, and users
of old clients to upgrade.
[[appendix]]
Appendix
~~~~~~~~
[[simpler-syntax]]
Simpler syntax
^^^^^^^^^^^^^^
This section is non-normative and does not cover all possible syntax.
Please see the BNF grammar above for the normative syntax.
[foo] means optional, <bar> are placeholders
`bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]`
[[examples]]
Examples
^^^^^^^^
Just the address:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W`]
Address with name:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr`]
Request 20.30 BTC to "Luke-Jr":
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr`]
Request 50 BTC with message:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz`]
Some future version that has variables which are (currently) not
understood and required and thus invalid:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999`]
Some future version that has variables which are (currently) not
understood but not required and thus valid:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999`]
Characters must be URI encoded properly.
[[reference-implementations]]
Reference Implementations
~~~~~~~~~~~~~~~~~~~~~~~~~
[[bitcoin-clients]]
Bitcoin clients
^^^^^^^^^^^^^^^
* Bitcoin-Qt supports the old version of Bitcoin URIs (ie without the
req- prefix), with Windows and KDE integration as of commit
70f55355e29c8e45b607e782c5d76609d23cc858.

124
selected BIPs/bip-0021.mediawiki
View File

@ -1,124 +0,0 @@
<pre>
BIP: 21
Title: URI Scheme
Author: Nils Schneider <nils.schneider@gmail.com>
Matt Corallo <bip21@bluematt.me>
Status: Accepted
Type: Standards Track
Created: 2012-01-29
</pre>
This BIP is a modification of an earlier [[bip-0020.mediawiki|BIP 0020]] by Luke Dashjr. BIP 0020 was based off an earlier document by Nils Schneider. The alternative payment amounts in BIP 0020 have been removed.
==Abstract==
This BIP proposes a URI scheme for making Bitcoin payments.
==Motivation==
The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.
==Specification==
=== General rules for handling (important!) ===
Bitcoin clients MUST NOT act on URIs without getting the user's authorization.
They SHOULD require the user to manually approve each payment individually, though in some cases they MAY allow the user to automatically make this decision.
=== Operating system integration ===
Graphical bitcoin clients SHOULD register themselves as the handler for the "bitcoin:" URI scheme by default, if no other handler is already registered. If there is already a registered handler, they MAY prompt the user to change it once when they first run the client.
=== General Format ===
Bitcoin URIs follow the general format for URIs as set forth in RFC 3986. The path component consists of a bitcoin address, and the query component provides additional payment options.
Elements of the query component may contain characters outside the valid range. These must first be encoded according to UTF-8, and then each octet of the corresponding UTF-8 sequence must be percent-encoded as described in RFC 3986.
=== ABNF grammar ===
(See also [[#Simpler syntax|a simpler representation of syntax]])
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]
bitcoinaddress = *base58
bitcoinparams = bitcoinparam [ "&" bitcoinparams ]
bitcoinparam = [ amountparam / labelparam / messageparam / otherparam / reqparam ]
amountparam = "amount=" *digit [ "." *digit ]
labelparam = "label=" *qchar
messageparam = "message=" *qchar
otherparam = qchar *qchar [ "=" *qchar ]
reqparam = "req-" qchar *qchar [ "=" *qchar ]
Here, "qchar" corresponds to valid characters of an RFC 3986 URI query component, excluding the "=" and "&" characters, which this BIP takes as separators.
The scheme component ("bitcoin:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The rest of the URI is case-sensitive, including the query parameter keys.
=== Query Keys ===
*label: Label for that address (e.g. name of receiver)
*address: bitcoin address
*message: message that describes the transaction to the user ([[#Examples|see examples below]])
*size: amount of base bitcoin units ([[#Transfer amount/size|see below]])
*(others): optional, for future extensions
==== Transfer amount/size ====
If an amount is provided, it MUST be specified in decimal BTC.
All amounts MUST contain no commas and use a period (.) as the separating character to separate whole numbers and decimal fractions.
I.e. amount=50.00 or amount=50 is treated as 50 BTC, and amount=50,000.00 is invalid.
Bitcoin clients MAY display the amount in any format that is not intended to deceive the user.
They SHOULD choose a format that is foremost least confusing, and only after that most reasonable given the amount requested.
For example, so long as the majority of users work in BTC units, values should always be displayed in BTC by default, even if mBTC or TBC would otherwise be a more logical interpretation of the amount.
== Rationale ==
===Payment identifiers, not person identifiers===
Current best practices are that a unique address should be used for every transaction.
Therefore, a URI scheme should not represent an exchange of personal information, but a one-time payment.
===Accessibility (URI scheme name)===
Should someone from the outside happen to see such a URI, the URI scheme name already gives a description.
A quick search should then do the rest to help them find the resources needed to make their payment.
Other proposed names sound much more cryptic; the chance that someone googles that out of curiosity are much slimmer.
Also, very likely, what he will find are mostly technical specifications - not the best introduction to bitcoin.
==Forward compatibility==
Variables which are prefixed with a req- are considered required. If a client does not implement any variables which are prefixed with req-, it MUST consider the entire URI invalid. Any other variables which are not implemented, but which are not prefixed with a req-, can be safely ignored.
==Backward compatibility==
As this BIP is written, several clients already implement a bitcoin: URI scheme similar to this one, however usually without the additional "req-" prefix requirement. Thus, it is recommended that additional variables prefixed with req- not be used in a mission-critical way until a grace period of 6 months from the finalization of this BIP has passed in order to allow client developers to release new versions, and users of old clients to upgrade.
== Appendix ==
=== Simpler syntax ===
This section is non-normative and does not cover all possible syntax.
Please see the BNF grammar above for the normative syntax.
[foo] means optional, &lt;bar&gt; are placeholders
<nowiki>bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]</nowiki>
=== Examples ===
Just the address:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W
Address with name:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr
Request 20.30 BTC to "Luke-Jr":
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr
Request 50 BTC with message:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz
Some future version that has variables which are (currently) not understood and required and thus invalid:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999
Some future version that has variables which are (currently) not understood but not required and thus valid:
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999
Characters must be URI encoded properly.
== Reference Implementations ==
=== Bitcoin clients ===
* Bitcoin-Qt supports the old version of Bitcoin URIs (ie without the req- prefix), with Windows and KDE integration as of commit 70f55355e29c8e45b607e782c5d76609d23cc858.

369
selected BIPs/bip-0022.asciidoc
View File

@ -1,369 +0,0 @@
---------------------------------------------
BIP: 22
Title: getblocktemplate - Fundamentals
Author: Luke Dashjr <luke+bip22@dashjr.org>
Status: Accepted
Type: Standards Track
Created: 2012-02-28
---------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP describes a new JSON-RPC method for "smart" Bitcoin miners and
proxies. Instead of sending a simple block header for hashing, the
entire block structure is sent, and left to the miner to (optionally)
customize and assemble.
[[specification]]
Specification
~~~~~~~~~~~~~
[[block-template-request]]
Block Template Request
^^^^^^^^^^^^^^^^^^^^^^
A JSON-RPC method is defined, called "getblocktemplate". It accepts
exactly one argument, which MUST be an Object of request parameters. If
the request parameters include a "mode" key, that is used to explicitly
select between the default "template" request or a
link:bip-0023.mediawiki#Block_Proposal["proposal"].
Block template creation can be influenced by various parameters:
[cols="",options="header",]
|=======================================================================
|colspan=4|template request
|Key |Required |Type |Description
|capabilities a| |Array of Strings |SHOULD contain a list of the
following, to indicate client-side support:
#Optional:_Long_Polling["longpoll"], "coinbasetxn", "coinbasevalue",
link:bip-0023.mediawiki#Block_Proposal["proposal"],
link:bip-0023.mediawiki#Logical_Services["serverlist"], "workid", and
any of the link:bip-0023.mediawiki#Mutations[mutations]
|mode a| |String |MUST be "template" or omitted
|=======================================================================
getblocktemplate MUST return a JSON Object containing the following
keys:
[cols="",options="header",]
|=======================================================================
|colspan=4| template
|Key |Required |Type |Description
|bits a| |String |the compressed difficulty in hexadecimal
|curtime a| |Number |the current time as seen by the server (recommended
for block time) - note this is not necessarily the system clock, and
must fall within the mintime/maxtime rules
|height a| |Number |the height of the block we are looking for
|previousblockhash a| |String |the hash of the previous block, in
big-endian hexadecimal
|sigoplimit a| |Number |number of sigops allowed in blocks
|sizelimit a| |Number |number of bytes allowed in blocks
|transactions a| |Array of Objects |Objects containing
link:#Transactions_Object_Format[information for Bitcoin transactions]
(excluding coinbase)
|version a| |Number |always 1 or 2 (at least for bitcoin) - clients MUST
understand the implications of the version they use (eg, comply with
link:bip-0034.mediawiki[BIP 0034] for version 2)
|coinbaseaux a| |Object |data that SHOULD be included in the coinbase's
scriptSig content. Only the values (hexadecimal byte-for-byte) in this
Object should be included, not the keys. This does not include the block
height, which is required to be included in the scriptSig by
link:bip-0034.mediawiki[BIP 0034]. It is advisable to encode values
inside "PUSH" opcodes, so as to not inadvertantly expend SIGOPs (which
are counted toward limits, despite not being executed).
|coinbasetxn a| |Object |link:#Transactions_Object_Format[information
for coinbase transaction]
|coinbasevalue a| |Number |total funds available for the coinbase (in
Satoshis)
|workid a| |String |if provided, this value must be returned with
results (see link:#Block_Submission[Block Submission])
|=======================================================================
[[transactions-object-format]]
Transactions Object Format
++++++++++++++++++++++++++
The Objects listed in the response's "transactions" key contains these
keys:
[cols="",options="header",]
|=======================================================================
|colspan=3|template "transactions" element
|Key |Type |Description
|data |String |transaction data encoded in hexadecimal (byte-for-byte)
|depends |Array of Numbers |other transactions before this one (by
1-based index in "transactions" list) that must be present in the final
block if this one is; if key is not present, dependencies are unknown
and clients MUST NOT assume there aren't any
|fee |Number |difference in value between transaction inputs and outputs
(in Satoshis); for coinbase transactions, this is a negative Number of
the total collected block fees (ie, not including the block subsidy); if
key is not present, fee is unknown and clients MUST NOT assume there
isn't one
|hash |String |hash/id encoded in little-endian hexadecimal
|required |Boolean |if provided and true, this transaction must be in
the final block
|sigops |Number |total number of SigOps, as counted for purposes of
block limits; if key is not present, sigop count is unknown and clients
MUST NOT assume there aren't any
|=======================================================================
Only the "data" key is required, but servers should provide the others
if they are known.
[[block-submission]]
Block Submission
^^^^^^^^^^^^^^^^
A JSON-RPC method is defined, called "submitblock", to submit potential
blocks (or shares). It accepts two arguments: the first is always a
String of the hex-encoded block data to submit; the second is an Object
of parameters, and is optional if parameters are not needed.
[cols="",options="header",]
|=======================================================================
|colspan=3|submitblock parameters (2nd argument)
|Key |Type |Description
|workid |String |if the server provided a workid, it MUST be included
with submissions
|=======================================================================
This method MUST return either null (when a share is accepted), a String
describing briefly the reason the share was rejected, or an Object of
these with a key for each merged-mining chain the share was submitted
to.
[[optional-long-polling]]
Optional: Long Polling
^^^^^^^^^^^^^^^^^^^^^^
[cols="",options="header",]
|=======================================================================
|template request
|Key |Type |Description
|capabilities |Array of Strings |miners which support long polling
SHOULD provide a list including the String "longpoll"
|longpollid |String |"longpollid" of job to monitor for expiration;
required and valid only for long poll requests
|=======================================================================
[cols="",options="header",]
|=======================================================================
|template
|Key |Type |Description
|longpollid |String |identifier for long poll request; MUST be omitted
if the server does not support long polling
|longpolluri |String |if provided, an alternate URI to use for long poll
requests
|submitold |Boolean |only relevant for long poll responses: indicates if
work received prior to this response remains potentially valid (default)
and should have its shares submitted; if false, the miner may wish to
discard its share queue
|=======================================================================
If the server supports long polling, it MUST include a "longpollid" key
in block templates, and it MUST be unique for each event: any given
"longpollid" should check for only one condition and not be reused. For
example, a server which has a long poll wakeup only for new blocks might
use the previous block hash. However, clients should not assume the
"longpollid" has any specific meaning. It MAY supply the "longpolluri"
key with a relative or absolute URI, which MAY specify a completely
different resource than the original connection, including port number.
If "longpolluri" is provided by the server, clients MUST only attempt to
use that URI for longpoll requests.
Clients MAY start a longpoll request with a standard JSON-RPC request
(in the case of HTTP transport, POST with data) and same authorization,
setting the "longpollid" parameter in the request to the value provided
by the server.
This request SHOULD NOT be processed nor answered by the server until it
wishes to replace the current block data as identified by the
"longpollid". Clients SHOULD make this request with a very long request
timeout and MUST accept servers sending a partial response in advance
(such as HTTP headers with "chunked" Transfer-Encoding), and only
delaying the completion of the final JSON response until processing.
Upon receiving a completed response:
* Only if "submitold" is provided and false, the client MAY discard the
results of past operations and MUST begin working on the new work
immediately.
* The client SHOULD begin working on the new work received as soon as
possible, if not immediately.
* The client SHOULD make a new request to the same long polling URI.
If a client receives an incomplete or invalid response, it SHOULD retry
the request with an exponential backoff. Clients MAY implement this
backoff with limitations (such as maximum backoff time) or any algorithm
as deemed suitable. It is, however, forbidden to simply retry
immediately with no delay after more than one failure. In the case of a
"Forbidden" response (for example, HTTP 403), a client SHOULD NOT
attempt to retry without user intervention.
[[optional-template-tweaking]]
Optional: Template Tweaking
^^^^^^^^^^^^^^^^^^^^^^^^^^^
[cols="",options="header",]
|=======================================================================
|template request
|Key |Type |Description
|sigoplimit |Number or Boolean |maximum number of sigops to include in
template
|sizelimit |Number or Boolean |maximum number of bytes to use for the
entire block
|maxversion |Number |highest block version number supported
|=======================================================================
For "sigoplimit" and "sizelimit", negative values and zero are offset
from the server-determined block maximum. If a Boolean is provided and
true, the default limit is used; if false, the server is instructed not
to use any limits on returned template. Servers SHOULD respect these
desired maximums, but are NOT required to: clients SHOULD check that the
returned template satisfies their requirements appropriately.
[[appendix-example-rejection-reasons]]
Appendix: Example Rejection Reasons
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Possible reasons a share may be rejected include, but are not limited
to:
[cols="",options="header",]
|=======================================================================
|colspan=2| share rejection reasons
|Reason |Description
|bad-cb-flag |the server detected a feature-signifying flag that it does
not allow
|bad-cb-length |the coinbase was too long (bitcoin limit is 100 bytes)
|bad-cb-prefix |the server only allows appending to the coinbase, but it
was modified beyond that
|bad-diffbits |"bits" were changed
|bad-prevblk |the previous-block is not the one the server intends to
build on
|bad-txnmrklroot |the block header's merkle root did not match the
transaction merkle tree
|bad-txns |the server didn't like something about the transactions in
the block
|bad-version |the version was wrong
|duplicate |the server already processed this block data
|high-hash |the block header did not hash to a value lower than the
specified target
|rejected |a generic rejection without details
|stale-prevblk |the previous-block is no longer the one the server
intends to build on
|stale-work |the work this block was based on is no longer accepted
|time-invalid |the time was not acceptable
|time-too-new |the time was too far in the future
|time-too-old |the time was too far in the past
|unknown-user |the user submitting the block was not recognized
|unknown-work |the template or workid could not be identified
|=======================================================================
[[motivation]]
Motivation
~~~~~~~~~~
bitcoind's JSON-RPC server can no longer support the load of generating
the work required to productively mine Bitcoin, and external software
specializing in work generation has become necessary. At the same time,
new independent node implementations are maturing to the point where
they will also be able to support miners.
A common standard for communicating block construction details is
necessary to ensure compatibility between the full nodes and work
generation software.
[[rationale]]
Rationale
~~~~~~~~~
Why not just deal with transactions as hashes (txids)?
* Servers might not have access to the transaction database, or miners
may wish to include transactions not broadcast to the network as a
whole.
* Miners may opt not to do full transaction verification, and may not
have access to the transaction database on their end.
What is the purpose of "workid"?
* If servers allow all mutations, it may be hard to identify which job
it is based on. While it may be possible to verify the submission by its
content, it is much easier to compare it to the job issued. It is very
easy for the miner to keep track of this. Therefore, using a "workid" is
a very cheap solution to enable more mutations.
Why should "sigops" be provided for transactions?
* Due to the link:bip-0016.mediawiki[BIP 0016] changes regarding rules
on block sigops, it is impossible to count sigops from the transactions
themselves (the sigops in the scriptCheck must also be included in the
count).
[[reference-implementation]]
Reference Implementation
~~~~~~~~~~~~~~~~~~~~~~~~
* https://gitorious.org/bitcoin/eloipool[Eloipool (server)]
* http://gitorious.org/bitcoin/libblkmaker[libblkmaker (client)]
* https://github.com/bitcoin/bitcoin/pull/936/files[bitcoind (minimal
server)]
[[see-also]]
See Also
~~~~~~~~
* link:bip-0023.mediawiki[BIP 23: getblocktemplate - Pooled Mining]

240
selected BIPs/bip-0022.mediawiki
View File

@ -1,240 +0,0 @@
<pre>
BIP: 22
Title: getblocktemplate - Fundamentals
Author: Luke Dashjr <luke+bip22@dashjr.org>
Status: Accepted
Type: Standards Track
Created: 2012-02-28
</pre>
==Abstract==
This BIP describes a new JSON-RPC method for "smart" Bitcoin miners and proxies.
Instead of sending a simple block header for hashing, the entire block structure is sent, and left to the miner to (optionally) customize and assemble.
==Specification==
===Block Template Request===
A JSON-RPC method is defined, called "getblocktemplate".
It accepts exactly one argument, which MUST be an Object of request parameters.
If the request parameters include a "mode" key, that is used to explicitly select between the default "template" request or a [[bip-0023.mediawiki#Block Proposal|"proposal"]].
Block template creation can be influenced by various parameters:
{| class="wikitable"
!colspan=4|template request
|-
! Key !! Required !! Type !! Description
|-
| capabilities || {{No}} || Array of Strings || SHOULD contain a list of the following, to indicate client-side support: [[#Optional: Long Polling|"longpoll"]], "coinbasetxn", "coinbasevalue", [[bip-0023.mediawiki#Block Proposal|"proposal"]], [[bip-0023.mediawiki#Logical Services|"serverlist"]], "workid", and any of the [[bip-0023.mediawiki#Mutations|mutations]]
|-
| mode || {{No}} || String || MUST be "template" or omitted
|}
getblocktemplate MUST return a JSON Object containing the following keys:
{| class="wikitable"
!colspan=4| template
|-
! Key !! Required !! Type !! Description
|-
| bits || {{Yes}} || String || the compressed difficulty in hexadecimal
|-
| curtime || {{Yes}} || Number || the current time as seen by the server (recommended for block time) - note this is not necessarily the system clock, and must fall within the mintime/maxtime rules
|-
| height || {{Yes}} || Number || the height of the block we are looking for
|-
| previousblockhash || {{Yes}} || String || the hash of the previous block, in big-endian hexadecimal
|-
| sigoplimit || {{No}} || Number || number of sigops allowed in blocks
|-
| sizelimit || {{No}} || Number || number of bytes allowed in blocks
|-
| transactions || {{Yes|Should}} || Array of Objects || Objects containing [[#Transactions Object Format|information for Bitcoin transactions]] (excluding coinbase)
|-
| version || {{Yes}} || Number || always 1 or 2 (at least for bitcoin) - clients MUST understand the implications of the version they use (eg, comply with [[bip-0034.mediawiki|BIP 0034]] for version 2)
|-
| coinbaseaux || {{No}} || Object || data that SHOULD be included in the coinbase's scriptSig content. Only the values (hexadecimal byte-for-byte) in this Object should be included, not the keys. This does not include the block height, which is required to be included in the scriptSig by [[bip-0034.mediawiki|BIP 0034]]. It is advisable to encode values inside "PUSH" opcodes, so as to not inadvertantly expend SIGOPs (which are counted toward limits, despite not being executed).
|-
| coinbasetxn || {{Patch|this or ↓}} || Object || [[#Transactions Object Format|information for coinbase transaction]]
|-
| coinbasevalue || {{Patch|this or ↑}} || Number || total funds available for the coinbase (in Satoshis)
|-
| workid || {{No}} || String || if provided, this value must be returned with results (see [[#Block Submission|Block Submission]])
|}
==== Transactions Object Format ====
The Objects listed in the response's "transactions" key contains these keys:
{| class="wikitable"
!colspan=3|template "transactions" element
|-
! Key !! Type !! Description
|-
| data || String || transaction data encoded in hexadecimal (byte-for-byte)
|-
| depends || Array of Numbers || other transactions before this one (by 1-based index in "transactions" list) that must be present in the final block if this one is; if key is not present, dependencies are unknown and clients MUST NOT assume there aren't any
|-
| fee || Number || difference in value between transaction inputs and outputs (in Satoshis); for coinbase transactions, this is a negative Number of the total collected block fees (ie, not including the block subsidy); if key is not present, fee is unknown and clients MUST NOT assume there isn't one
|-
| hash || String || hash/id encoded in little-endian hexadecimal
|-
| required || Boolean || if provided and true, this transaction must be in the final block
|-
| sigops || Number || total number of SigOps, as counted for purposes of block limits; if key is not present, sigop count is unknown and clients MUST NOT assume there aren't any
|}
Only the "data" key is required, but servers should provide the others if they are known.
===Block Submission===
A JSON-RPC method is defined, called "submitblock", to submit potential blocks (or shares).
It accepts two arguments:
the first is always a String of the hex-encoded block data to submit;
the second is an Object of parameters, and is optional if parameters are not needed.
{| class="wikitable"
!colspan=3|submitblock parameters (2nd argument)
|-
! Key !! Type !! Description
|-
| workid || String || if the server provided a workid, it MUST be included with submissions
|}
This method MUST return either null (when a share is accepted), a String describing briefly the reason the share was rejected, or an Object of these with a key for each merged-mining chain the share was submitted to.
===Optional: Long Polling===
{| class="wikitable"
! colspan="3" | template request
|-
! Key !! Type !! Description
|-
| capabilities || Array of Strings || miners which support long polling SHOULD provide a list including the String "longpoll"
|-
| longpollid || String || "longpollid" of job to monitor for expiration; required and valid only for long poll requests
|}
{| class="wikitable"
! colspan="3" | template
|-
! Key !! Type !! Description
|-
| longpollid || String || identifier for long poll request; MUST be omitted if the server does not support long polling
|-
| longpolluri || String || if provided, an alternate URI to use for long poll requests
|-
| submitold || Boolean || only relevant for long poll responses: indicates if work received prior to this response remains potentially valid (default) and should have its shares submitted; if false, the miner may wish to discard its share queue
|}
If the server supports long polling, it MUST include a "longpollid" key in block templates, and it MUST be unique for each event:
any given "longpollid" should check for only one condition and not be reused.
For example, a server which has a long poll wakeup only for new blocks might use the previous block hash.
However, clients should not assume the "longpollid" has any specific meaning.
It MAY supply the "longpolluri" key with a relative or absolute URI, which MAY specify a completely different resource than the original connection, including port number.
If "longpolluri" is provided by the server, clients MUST only attempt to use that URI for longpoll requests.
Clients MAY start a longpoll request with a standard JSON-RPC request (in the case of HTTP transport, POST with data) and same authorization, setting the "longpollid" parameter in the request to the value provided by the server.
This request SHOULD NOT be processed nor answered by the server until it wishes to replace the current block data as identified by the "longpollid".
Clients SHOULD make this request with a very long request timeout and MUST accept servers sending a partial response in advance (such as HTTP headers with "chunked" Transfer-Encoding), and only delaying the completion of the final JSON response until processing.
Upon receiving a completed response:
* Only if "submitold" is provided and false, the client MAY discard the results of past operations and MUST begin working on the new work immediately.
* The client SHOULD begin working on the new work received as soon as possible, if not immediately.
* The client SHOULD make a new request to the same long polling URI.
If a client receives an incomplete or invalid response, it SHOULD retry the request with an exponential backoff.
Clients MAY implement this backoff with limitations (such as maximum backoff time) or any algorithm as deemed suitable.
It is, however, forbidden to simply retry immediately with no delay after more than one failure.
In the case of a "Forbidden" response (for example, HTTP 403), a client SHOULD NOT attempt to retry without user intervention.
===Optional: Template Tweaking===
{| class="wikitable"
! colspan="3" | template request
|-
! Key !! Type !! Description
|-
| sigoplimit || Number or Boolean || maximum number of sigops to include in template
|-
| sizelimit || Number or Boolean || maximum number of bytes to use for the entire block
|-
| maxversion || Number || highest block version number supported
|}
For "sigoplimit" and "sizelimit", negative values and zero are offset from the server-determined block maximum.
If a Boolean is provided and true, the default limit is used; if false, the server is instructed not to use any limits on returned template.
Servers SHOULD respect these desired maximums, but are NOT required to:
clients SHOULD check that the returned template satisfies their requirements appropriately.
===Appendix: Example Rejection Reasons===
Possible reasons a share may be rejected include, but are not limited to:
{| class="wikitable"
!colspan=2| share rejection reasons
|-
! Reason !! Description
|-
| bad-cb-flag || the server detected a feature-signifying flag that it does not allow
|-
| bad-cb-length || the coinbase was too long (bitcoin limit is 100 bytes)
|-
| bad-cb-prefix || the server only allows appending to the coinbase, but it was modified beyond that
|-
| bad-diffbits || "bits" were changed
|-
| bad-prevblk || the previous-block is not the one the server intends to build on
|-
| bad-txnmrklroot || the block header's merkle root did not match the transaction merkle tree
|-
| bad-txns || the server didn't like something about the transactions in the block
|-
| bad-version || the version was wrong
|-
| duplicate || the server already processed this block data
|-
| high-hash || the block header did not hash to a value lower than the specified target
|-
| rejected || a generic rejection without details
|-
| stale-prevblk || the previous-block is no longer the one the server intends to build on
|-
| stale-work || the work this block was based on is no longer accepted
|-
| time-invalid || the time was not acceptable
|-
| time-too-new || the time was too far in the future
|-
| time-too-old || the time was too far in the past
|-
| unknown-user || the user submitting the block was not recognized
|-
| unknown-work || the template or workid could not be identified
|}
==Motivation==
bitcoind's JSON-RPC server can no longer support the load of generating the work required to productively mine Bitcoin, and external software specializing in work generation has become necessary.
At the same time, new independent node implementations are maturing to the point where they will also be able to support miners.
A common standard for communicating block construction details is necessary to ensure compatibility between the full nodes and work generation software.
==Rationale==
Why not just deal with transactions as hashes (txids)?
* Servers might not have access to the transaction database, or miners may wish to include transactions not broadcast to the network as a whole.
* Miners may opt not to do full transaction verification, and may not have access to the transaction database on their end.
What is the purpose of "workid"?
* If servers allow all mutations, it may be hard to identify which job it is based on. While it may be possible to verify the submission by its content, it is much easier to compare it to the job issued. It is very easy for the miner to keep track of this. Therefore, using a "workid" is a very cheap solution to enable more mutations.
Why should "sigops" be provided for transactions?
* Due to the [[bip-0016.mediawiki|BIP 0016]] changes regarding rules on block sigops, it is impossible to count sigops from the transactions themselves (the sigops in the scriptCheck must also be included in the count).
==Reference Implementation==
* [https://gitorious.org/bitcoin/eloipool Eloipool (server)]
* [http://gitorious.org/bitcoin/libblkmaker libblkmaker (client)]
* [https://github.com/bitcoin/bitcoin/pull/936/files bitcoind (minimal server)]
==See Also==
* [[bip-0023.mediawiki|BIP 23: getblocktemplate - Pooled Mining]]

429
selected BIPs/bip-0023.asciidoc
View File

@ -1,429 +0,0 @@
---------------------------------------------
BIP: 23
Title: getblocktemplate - Pooled Mining
Author: Luke Dashjr <luke+bip22@dashjr.org>
Status: Accepted
Type: Standards Track
Created: 2012-02-28
---------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP describes extensions to the getblocktemplate JSON-RPC call to
enhance pooled mining.
[[specification]]
Specification
~~~~~~~~~~~~~
Note that all sections of this specification are optional extensions on
top of link:BIP 0022[BIP 22].
[[summary-support-levels]]
Summary Support Levels
^^^^^^^^^^^^^^^^^^^^^^
Something can be said to have BIP 23 Level 1 support if it implements at
least:
* http://www.ietf.org/rfc/rfc1945.txt[RFC 1945]
* http://json-rpc.org/wiki/specification[JSON-RPC 1.0]
* link:bip-0022.mediawiki[BIP 22 (non-optional sections)]
* bip-0022.mediawiki#Optional:_Long_Polling[BIP 22 Long Polling]
* link:#Basic_Pool_Extensions[BIP 23 Basic Pool Extensions]
* link:#Mutations[BIP 23 Mutation "coinbase/append"]
* link:#Submission_Abbreviation[BIP 23 Submission Abbreviation
"submit/coinbase"]
* link:#Mutations[BIP 23 Mutation "time/increment"] (only required for
servers)
It can be said to have BIP 23 Level 2 support if it also implements:
* link:#Mutations[BIP 23 Mutation "transactions/add"]
* link:#Block_Proposals[BIP 23 Block Proposals]
[[basic-pool-extensions]]
Basic Pool Extensions
^^^^^^^^^^^^^^^^^^^^^
[cols="",options="header",]
|==================================================================
|template request
|Key |Type |Description
|target |String |desired target for block template (may be ignored)
|==================================================================
[cols="",options="header",]
|=======================================================================
|template
|Key |Type |Description
|expires |Number |how many seconds (beginning from when the server sent
the response) this work is valid for, at most
|target |String |the number which valid results must be less than, in
big-endian hexadecimal
|=======================================================================
[[block-proposal]]
Block Proposal
^^^^^^^^^^^^^^
Servers may indicate support for proposing blocks by including a
capability string in their original template:
[cols="",options="header",]
|=======================================================================
|template
|Key |Type |Description
|capabilities |Array of Strings |MAY contain "proposal" to indicate
support for block proposal
|reject-reason |String |Reason the proposal was invalid as-is (only
applicable in response to proposals)
|=======================================================================
If supported, a miner MAY propose a block to the server for general
validation at any point before the job expires. This is accomplished by
calling getblocktemplate with two keys:
[cols="",options="header",]
|=======================================================================
|colspan=3| getblocktemplate parameters
|Key |Type |Description
|data |String |MUST be hex-encoded block data
|mode |String |MUST be "proposal"
|workid |String |if the server provided a workid, it MUST be included
with proposals
|=======================================================================
The block data MUST be validated and checked against the server's usual
acceptance rules (excluding the check for a valid proof-of-work). If it
is found to be in violation of any of these rules, the server MUST
return one of the following:
* Null if it is acceptable as-is, with the same workid (if any) as
provided. Note that this SHOULD NOT invalidate the old template's claim
to the same workid.
* A String giving the reason for the rejection (see
link:bip-0022.mediawiki#appendix-example-rejection-reasons[example
rejection reasons]).
* A "delta" block template (with changes needed); in this case, any
missing keys are assumed to default to those in the proposed block or,
if not applicable, the original block template it was based on. This
template MAY also include a "reject-reason" key with a String of the
reason for rejection.
It is RECOMMENDED that servers which merely need to track the proposed
block for later share/* submissions, return a simple Object of the form:
`{"workid":"new workid"}`
Clients SHOULD assume their proposed block will remain valid if the only
changes they make are to the portion of the coinbase scriptSig they
themselves provided (if any) and the time header. Servers SHOULD NOT
break this assumption without good cause.
[[mutations]]
Mutations
^^^^^^^^^
[cols="",options="header",]
|=======================================================================
|template request
|Key |Type |Description
|nonces |Number |size of nonce range the miner needs; if not provided,
the server SHOULD assume the client requires 2^32^
|=======================================================================
[cols="",options="header",]
|=======================================================================
|colspan=3| template
|Key |Type |Description
|maxtime |Number |the maximum time allowed
|maxtimeoff |Number |the maximum time allowed (as a moving offset from
"curtime" - every second, the actual maxtime is incremented by 1; for
example, "maxtimeoff":0 means "time" may be incremented by 1 every
second)
|mintime |Number |the minimum time allowed
|mintimeoff |Number |the minimum time allowed (as a moving offset from
"curtime")
|mutable |Array of Strings |different manipulations that the server
explicitly allows to be made
|noncerange |String |two 32-bit integers, concatenated in big-endian
hexadecimal, which represent the valid ranges of nonces the miner may
scan
|=======================================================================
If the block template contains a "mutable" key, it is a list of these to
signify modifications the miner is allowed to make:
[cols="",options="header",]
|=======================================================================
|colspan=2| mutations
|Value |Significance
|coinbase/append |append the provided coinbase scriptSig
|coinbase |provide their own coinbase; if one is provided, it may be
replaced or modified (implied if "coinbasetxn" omitted)
|generation |add or remove outputs from the coinbase/generation
transaction (implied if "coinbasetxn" omitted)
|time/increment |change the time header to a value after "time" (implied
if "maxtime" or "maxtimeoff" are provided)
|time/decrement |change the time header to a value before "time"
(implied if "mintime" is provided)
|time |modify the time header of the block
|transactions/add (or "transactions") |add other valid transactions to
the block (implied if "transactions" omitted from result)
|prevblock |use the work with other previous-blocks; this implicitly
allows removing transactions that are no longer valid (but clients
SHOULD attempt to propose removal of any required transactions); it also
implies adjusting "height" as necessary
|version/force |encode the provide block version, even if the miner
doesn't understand it
|version/reduce |use an older block version than the one provided (for
example, if the client does not support the version provided)
|=======================================================================
[[submission-abbreviation]]
Submission Abbreviation
^^^^^^^^^^^^^^^^^^^^^^^
[cols="",options="header",]
|=======================================================================
|colspan=3| template
|Key |Type |Description
|fulltarget |String |the number which full results should be less than,
in big-endian hexadecimal (see "share/*" mutations)
|mutable |Array of Strings |different manipulations that the server
explicitly allows to be made, including abbreviations
|=======================================================================
If the block template contains a "mutable" key, it is a list of these to
signify modifications the miner is allowed to make:
[cols="",options="header",]
|=======================================================================
|colspan=2| abbreviation mutations
|Value |Significance
|submit/hash |each transaction being sent in a request, that the client
is certain the server knows about, may be replaced by its hash in
little-endian hexadecimal, prepended by a ":" character
|submit/coinbase |if the "transactions" provided by the server are used
as-is with no changes, submissions may omit transactions after the
coinbase (transaction count varint remains included with the full number
of transactions)
|submit/truncate |if the "coinbasetxn" and "transactions" provided by
the server are used as-is with no changes, submissions may contain only
the block header; if only the scriptSig of "coinbasetxn" is modified,
the params Object MUST contain a "coinbasesig" key with the content, or
a "coinbaseadd" with appended data (if only appending)
|share/coinbase |same as "submit/coinbase", but only if the block hash
is greater than "fulltarget"
|share/merkle |if the block hash is greater than "fulltarget", the
non-coinbase transactions may be replaced with a merkle chain connecting
it to the root
|share/truncate |same as "submit/truncate", but only if the block hash
is greater than "fulltarget"
|=======================================================================
[[format-of-data-for-merkle-only-shares]]
Format of Data for Merkle-Only Shares
+++++++++++++++++++++++++++++++++++++
The format used for submitting shares with the "share/merkle" mutation
shall be the 80-byte block header, the total number of transactions
encoded in Bitcoin variable length number format, the coinbase
transaction, and then finally the little-endian SHA256 hashes of each
link in the merkle chain connecting it to the merkle root.
[[logical-services]]
Logical Services
^^^^^^^^^^^^^^^^
[cols="",options="header",]
|=======================================================================
|template request
|Key |Type |Description
|capabilities |Array of Strings |miners which support this SHOULD
provide a list including the String "serverlist"
|=======================================================================
[cols="",options="header",]
|=======================================================================
|colspan=3| template
|Key |Type |Description
|serverlist |Array of Objects |list of servers in this single logical
service
|=======================================================================
If the "serverlist" parameter is provided, clients MAY choose to
intelligently treat the server as part of a larger single logical
service.
Each host Object in the Array is comprised of the following fields:
[cols="",options="header",]
|=======================================================================
|colspan=3| serverlist element
|Key |Type |Description
|uri |String |URI of the individual server; if authentication
information is omitted, the same authentication used for this request
MUST be assumed
|avoid |Number |number of seconds to avoid using this server
|priority |Number |an integer priority of this host (default: 0)
|sticky |Number |number of seconds to stick to this server when used
|update |Boolean |whether this server may update the serverlist
(default: true)
|weight |Number |a relative weight for hosts with the same priority
(default: 1)
|=======================================================================
When choosing which actual server to get the next job from, URIs MUST be
tried in order of their "priority" key, lowest Number first. Where the
priority of URIs is the same, they should be chosen from in random
order, weighed by their "weight" key. Work proposals and submissions
MUST be made to the same server that issued the job. Clients MAY attempt
to submit to other servers if, and only if, the original server cannot
be reached. If cross-server share submissions are desired, services
SHOULD instead use the equivalent domain name system (DNS) features
(RFCs http://tools.ietf.org/html/rfc1794[1794] and
http://tools.ietf.org/html/rfc2782[2782]).
Updates to the Logical Service server list may only be made by the
original server, or servers listed with the "update" key missing or
true. Clients MAY choose to advertise serverlist capability to servers
with a false "update" key, but if so, MUST treat the server list
provided as a subset of the current one, only considered in the context
of this server. At least one server with "update" privilege MUST be
attempted at least once daily.
If the "sticky" key is provided, then when that server is used, it
should be used consistently for at least that many seconds, if possible.
A permanent change in server URI MAY be indicated with a simple
"serverlist" parameter:
`"serverlist":[{"uri": "`http://newserver[`http://newserver`]`"}]`
A temporary delegation to another server for 5 minutes MAY be indicated
likewise:
`"serverlist":[{"uri": "", avoid: 300}, {"uri": "`http://newserver[`http://newserver`]`", "update": false}]`
[[motivation]]
Motivation
~~~~~~~~~~
There is reasonable concerns about mining currently being too
centralized on pools, and the amount of control these pools hold. By
exposing the details of the block proposals to the miners, they are
enabled to audit and possibly modify the block before hashing it.
To encourage widespread adoption, this BIP should be a complete superset
of the existing centralized getwork protocol, so pools are not required
to make substantial changes to adopt it.
[[rationale]]
Rationale
~~~~~~~~~
Why allow servers to restrict the complete coinbase and nonce range?
* This is necessary to provide a complete superset of JSON-RPC getwork
functionality, so that pools may opt to enable auditing without
significantly changing or increasing the complexity of their share
validation or mining policies.
* Since noncerange is optional (both for getwork and this BIP), neither
clients nor servers are required to support it.
Why specify "time/*" mutations at all?
* In most cases, these are implied by the
mintime/mintimecur/maxtime/maxtimecur keys, but there may be cases that
there are no applicable minimums/maximums.
What is the purpose of the "prevblock" mutation?
* There are often cases where a miner has processed a new block before
the server. If the server allows "prevblock" mutation, the miner may
begin mining on the new block immediately, without waiting for a new
template.
Why must both "mintime"/"maxtime" and "mintimeoff"/"maxtimeoff" keys be
defined?
* In some cases, the limits may be unrelated to the current time (such
as the Bitcoin network itself; the minimum is always a fixed median
time)
* In other cases, the limits may be bounded by other rules (many pools
limit the time header to within 5 minutes of when the share is submitted
to them).
Is "target" really needed?
* Some pools work with lower targets, and should not be expected to
waste bandwidth ignoring shares that don't meet it.
* Required to be a proper superset of getwork.
* As mining hashrates grow, some miners may need the ability to request
a lower target from their pools to be able to manage their bandwidth
use.
What is the purpose of the "hash" transaction list format?
* Non-mining tools may wish to simply get a list of memory pool
transactions.
* Humans may wish to view their current memory pool.
[[reference-implementation]]
Reference Implementation
~~~~~~~~~~~~~~~~~~~~~~~~
* http://gitorious.org/bitcoin/libblkmaker[libblkmaker]
* https://gitorious.org/bitcoin/eloipool[Eloipool]
* https://github.com/bitcoin/bitcoin/pull/936/files[bitcoind]
[[see-also]]
See Also
~~~~~~~~
* link:bip-0022.mediawiki[BIP 22: getblocktemplate - Fundamentals]

296
selected BIPs/bip-0023.mediawiki
View File

@ -1,296 +0,0 @@
<pre>
BIP: 23
Title: getblocktemplate - Pooled Mining
Author: Luke Dashjr <luke+bip22@dashjr.org>
Status: Accepted
Type: Standards Track
Created: 2012-02-28
</pre>
==Abstract==
This BIP describes extensions to the getblocktemplate JSON-RPC call to enhance pooled mining.
==Specification==
Note that all sections of this specification are optional extensions on top of [[BIP 0022|BIP 22]].
===Summary Support Levels===
Something can be said to have BIP 23 Level 1 support if it implements at least:
* [http://www.ietf.org/rfc/rfc1945.txt RFC 1945]
* [http://json-rpc.org/wiki/specification JSON-RPC 1.0]
* [[bip-0022.mediawiki|BIP 22 (non-optional sections)]]
* [[bip-0022.mediawiki#Optional: Long Polling|BIP 22 Long Polling]]
* [[#Basic Pool Extensions|BIP 23 Basic Pool Extensions]]
* [[#Mutations|BIP 23 Mutation "coinbase/append"]]
* [[#Submission Abbreviation|BIP 23 Submission Abbreviation "submit/coinbase"]]
* [[#Mutations|BIP 23 Mutation "time/increment"]] (only required for servers)
It can be said to have BIP 23 Level 2 support if it also implements:
* [[#Mutations|BIP 23 Mutation "transactions/add"]]
* [[#Block Proposals|BIP 23 Block Proposals]]
===Basic Pool Extensions===
{| class="wikitable"
! colspan="3" | template request
|-
! Key !! Type !! Description
|-
| target || String || desired target for block template (may be ignored)
|}
{| class="wikitable"
!colspan="3"| template
|-
! Key !! Type !! Description
|-
| expires || Number || how many seconds (beginning from when the server sent the response) this work is valid for, at most
|-
| target || String || the number which valid results must be less than, in big-endian hexadecimal
|}
===Block Proposal===
Servers may indicate support for proposing blocks by including a capability string in their original template:
{| class="wikitable"
!colspan="3"| template
|-
! Key !! Type !! Description
|-
| capabilities || Array of Strings || MAY contain "proposal" to indicate support for block proposal
|-
| reject-reason || String || Reason the proposal was invalid as-is (only applicable in response to proposals)
|}
If supported, a miner MAY propose a block to the server for general validation at any point before the job expires.
This is accomplished by calling getblocktemplate with two keys:
{| class="wikitable"
!colspan=3| getblocktemplate parameters
|-
! Key !! Type !! Description
|-
| data || String || MUST be hex-encoded block data
|-
| mode || String || MUST be "proposal"
|-
| workid || String || if the server provided a workid, it MUST be included with proposals
|}
The block data MUST be validated and checked against the server's usual acceptance rules (excluding the check for a valid proof-of-work).
If it is found to be in violation of any of these rules, the server MUST return one of the following:
* Null if it is acceptable as-is, with the same workid (if any) as provided. Note that this SHOULD NOT invalidate the old template's claim to the same workid.
* A String giving the reason for the rejection (see [[bip-0022.mediawiki#appendix-example-rejection-reasons|example rejection reasons]]).
* A "delta" block template (with changes needed); in this case, any missing keys are assumed to default to those in the proposed block or, if not applicable, the original block template it was based on. This template MAY also include a "reject-reason" key with a String of the reason for rejection.
It is RECOMMENDED that servers which merely need to track the proposed block for later share/* submissions, return a simple Object of the form:
{"workid":"new workid"}
Clients SHOULD assume their proposed block will remain valid if the only changes they make are to the portion of the coinbase scriptSig they themselves provided (if any) and the time header.
Servers SHOULD NOT break this assumption without good cause.
===Mutations===
{| class="wikitable"
! colspan="3" | template request
|-
! Key !! Type !! Description
|-
| nonces || Number || size of nonce range the miner needs; if not provided, the server SHOULD assume the client requires 2<sup>32</sup>
|}
{| class="wikitable"
!colspan=3| template
|-
! Key !! Type !! Description
|-
| maxtime || Number || the maximum time allowed
|-
| maxtimeoff || Number || the maximum time allowed (as a moving offset from "curtime" - every second, the actual maxtime is incremented by 1; for example, "maxtimeoff":0 means "time" may be incremented by 1 every second)
|-
| mintime || Number || the minimum time allowed
|-
| mintimeoff || Number || the minimum time allowed (as a moving offset from "curtime")
|-
| mutable || Array of Strings || different manipulations that the server explicitly allows to be made
|-
| noncerange || String || two 32-bit integers, concatenated in big-endian hexadecimal, which represent the valid ranges of nonces the miner may scan
|}
If the block template contains a "mutable" key, it is a list of these to signify modifications the miner is allowed to make:
{| class="wikitable"
!colspan=2| mutations
|-
! Value !! Significance
|-
| coinbase/append
| append the provided coinbase scriptSig
|-
| coinbase
| provide their own coinbase; if one is provided, it may be replaced or modified (implied if "coinbasetxn" omitted)
|-
| generation
| add or remove outputs from the coinbase/generation transaction (implied if "coinbasetxn" omitted)
|-
| time/increment
| change the time header to a value after "time" (implied if "maxtime" or "maxtimeoff" are provided)
|-
| time/decrement
| change the time header to a value before "time" (implied if "mintime" is provided)
|-
| time
| modify the time header of the block
|-
| transactions/add (or "transactions")
| add other valid transactions to the block (implied if "transactions" omitted from result)
|-
| prevblock
| use the work with other previous-blocks; this implicitly allows removing transactions that are no longer valid (but clients SHOULD attempt to propose removal of any required transactions); it also implies adjusting "height" as necessary
|-
| version/force
| encode the provide block version, even if the miner doesn't understand it
|-
| version/reduce
| use an older block version than the one provided (for example, if the client does not support the version provided)
|}
===Submission Abbreviation===
{| class="wikitable"
!colspan=3| template
|-
! Key !! Type !! Description
|-
| fulltarget || String || the number which full results should be less than, in big-endian hexadecimal (see "share/*" mutations)
|-
| mutable || Array of Strings || different manipulations that the server explicitly allows to be made, including abbreviations
|}
If the block template contains a "mutable" key, it is a list of these to signify modifications the miner is allowed to make:
{| class="wikitable"
!colspan=2| abbreviation mutations
|-
! Value !! Significance
|-
| submit/hash
| each transaction being sent in a request, that the client is certain the server knows about, may be replaced by its hash in little-endian hexadecimal, prepended by a ":" character
|-
| submit/coinbase
| if the "transactions" provided by the server are used as-is with no changes, submissions may omit transactions after the coinbase (transaction count varint remains included with the full number of transactions)
|-
| submit/truncate
| if the "coinbasetxn" and "transactions" provided by the server are used as-is with no changes, submissions may contain only the block header; if only the scriptSig of "coinbasetxn" is modified, the params Object MUST contain a "coinbasesig" key with the content, or a "coinbaseadd" with appended data (if only appending)
|-
| share/coinbase
| same as "submit/coinbase", but only if the block hash is greater than "fulltarget"
|-
| share/merkle
| if the block hash is greater than "fulltarget", the non-coinbase transactions may be replaced with a merkle chain connecting it to the root
|-
| share/truncate
| same as "submit/truncate", but only if the block hash is greater than "fulltarget"
|}
==== Format of Data for Merkle-Only Shares ====
The format used for submitting shares with the "share/merkle" mutation shall be the 80-byte block header, the total number of transactions encoded in Bitcoin variable length number format, the coinbase transaction, and then finally the little-endian SHA256 hashes of each link in the merkle chain connecting it to the merkle root.
===Logical Services===
{| class="wikitable"
! colspan="3" | template request
|-
! Key !! Type !! Description
|-
| capabilities || Array of Strings || miners which support this SHOULD provide a list including the String "serverlist"
|}
{| class="wikitable"
!colspan=3| template
|-
! Key !! Type !! Description
|-
| serverlist || Array of Objects || list of servers in this single logical service
|}
If the "serverlist" parameter is provided, clients MAY choose to intelligently treat the server as part of a larger single logical service.
Each host Object in the Array is comprised of the following fields:
{| class="wikitable"
!colspan=3| serverlist element
|-
! Key !! Type !! Description
|-
| uri || String || URI of the individual server; if authentication information is omitted, the same authentication used for this request MUST be assumed
|-
| avoid || Number || number of seconds to avoid using this server
|-
| priority || Number || an integer priority of this host (default: 0)
|-
| sticky || Number || number of seconds to stick to this server when used
|-
| update || Boolean || whether this server may update the serverlist (default: true)
|-
| weight || Number || a relative weight for hosts with the same priority (default: 1)
|}
When choosing which actual server to get the next job from, URIs MUST be tried in order of their "priority" key, lowest Number first.
Where the priority of URIs is the same, they should be chosen from in random order, weighed by their "weight" key.
Work proposals and submissions MUST be made to the same server that issued the job.
Clients MAY attempt to submit to other servers if, and only if, the original server cannot be reached.
If cross-server share submissions are desired, services SHOULD instead use the equivalent domain name system (DNS) features (RFCs [http://tools.ietf.org/html/rfc1794 1794] and [http://tools.ietf.org/html/rfc2782 2782]).
Updates to the Logical Service server list may only be made by the original server, or servers listed with the "update" key missing or true.
Clients MAY choose to advertise serverlist capability to servers with a false "update" key, but if so, MUST treat the server list provided as a subset of the current one, only considered in the context of this server.
At least one server with "update" privilege MUST be attempted at least once daily.
If the "sticky" key is provided, then when that server is used, it should be used consistently for at least that many seconds, if possible.
A permanent change in server URI MAY be indicated with a simple "serverlist" parameter:
"serverlist":[{"uri": "http://newserver"}]
A temporary delegation to another server for 5 minutes MAY be indicated likewise:
"serverlist":[{"uri": "", avoid: 300}, {"uri": "http://newserver", "update": false}]
==Motivation==
There is reasonable concerns about mining currently being too centralized on pools, and the amount of control these pools hold.
By exposing the details of the block proposals to the miners, they are enabled to audit and possibly modify the block before hashing it.
To encourage widespread adoption, this BIP should be a complete superset of the existing centralized getwork protocol, so pools are not required to make substantial changes to adopt it.
==Rationale==
Why allow servers to restrict the complete coinbase and nonce range?
* This is necessary to provide a complete superset of JSON-RPC getwork functionality, so that pools may opt to enable auditing without significantly changing or increasing the complexity of their share validation or mining policies.
* Since noncerange is optional (both for getwork and this BIP), neither clients nor servers are required to support it.
Why specify "time/*" mutations at all?
* In most cases, these are implied by the mintime/mintimecur/maxtime/maxtimecur keys, but there may be cases that there are no applicable minimums/maximums.
What is the purpose of the "prevblock" mutation?
* There are often cases where a miner has processed a new block before the server. If the server allows "prevblock" mutation, the miner may begin mining on the new block immediately, without waiting for a new template.
Why must both "mintime"/"maxtime" and "mintimeoff"/"maxtimeoff" keys be defined?
* In some cases, the limits may be unrelated to the current time (such as the Bitcoin network itself; the minimum is always a fixed median time)
* In other cases, the limits may be bounded by other rules (many pools limit the time header to within 5 minutes of when the share is submitted to them).
Is "target" really needed?
* Some pools work with lower targets, and should not be expected to waste bandwidth ignoring shares that don't meet it.
* Required to be a proper superset of getwork.
* As mining hashrates grow, some miners may need the ability to request a lower target from their pools to be able to manage their bandwidth use.
What is the purpose of the "hash" transaction list format?
* Non-mining tools may wish to simply get a list of memory pool transactions.
* Humans may wish to view their current memory pool.
==Reference Implementation==
* [http://gitorious.org/bitcoin/libblkmaker libblkmaker]
* [https://gitorious.org/bitcoin/eloipool Eloipool]
* [https://github.com/bitcoin/bitcoin/pull/936/files bitcoind]
==See Also==
* [[bip-0022.mediawiki|BIP 22: getblocktemplate - Fundamentals]]

113
selected BIPs/bip-0030.asciidoc
View File

@ -1,113 +0,0 @@
-------------------------------------------------
BIP: 30
Title: Duplicate transactions
Author: Pieter Wuille <pieter.wuille@gmail.com>
Status: Final
Type: Standards Track
Created: 2012-02-22
-------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This document gives a specification for dealing with duplicate
transactions in the block chain, in an attempt to solve certain problems
the reference implementations has with them.
[[motivation]]
Motivation
~~~~~~~~~~
So far, the Bitcoin reference implementation always assumed duplicate
transactions (transactions with the same identifier) didn't exist. This
is not true; in particular coinbases are easy to duplicate, and by
building on duplicate coinbases, duplicate normal transactions are
possible as well. Recently, an attack that exploits the reference
implementation's dealing with duplicate transactions was described and
demonstrated. It allows reverting fully-confirmed transactions to a
single confirmation, making them vulnerable to become unspendable
entirely. Another attack is possible that allows forking the block chain
for a subset of the network.
[[specification]]
Specification
~~~~~~~~~~~~~
To counter this problem, the following network rule is introduced:
* Blocks are not allowed to contain a transaction whose identifier
matches that of an earlier, not-fully-spent transaction in the same
chain.
This rule initially applied to all blocks whose timestamp is after March
15, 2012, 00:00 UTC (testnet: February 20, 2012 00:00 UTC). It was later
extended by Commit
https://github.com/bitcoin/bitcoin/commit/ab91bf39b7c11e9c86bb2043c24f0f377f1cf514[Apply
BIP30 checks to all blocks except the two historic violations.] to apply
to all blocks except the two historic blocks at heights 91842 and 91880
on the main chain that had to be grandfathered in.
[[rationale]]
Rationale
~~~~~~~~~
Whatever solution is used, the following law must be obeyed to guarantee
sane behaviour: the set of usable transactions outputs must not be
modified by adding blocks to the chain and removing them again. This
happens during a reorganisation, and the current Bitcoin reference
implementation does not obey this law in case the temporarily added
blocks contain a duplicate transaction.
There are several potential solutions to this problem:
1. Guarantee that all coinbases are unique, making duplicate
transactions very hard to create.
2. Remember previous remaining outputs of a given transaction
identifier, in case a new transaction with the same identifier is added.
3. Only allow duplicate transactions in case the previous instance of
the transaction had no spendable outputs left. Removing a block from the
chain can then safely reset the removed transaction's outputs to
nothing.
The first option is probably the most complete one, as it also
guarantees transaction identifiers are unique. However, implementing it
requires several changes that need to be accepted throughout the
network. Furthermore, it does not prevent duplicate transactions based
on earlier duplicate coinbases. The second option is impossible to
implement in a forward-compatible way, as it potentially renders
currently-invalid blocks valid. In this document we choose for the third
option, because it only requires a trivial change.
Fully-spent transactions are allowed to be duplicated in order not to
hinder pruning at some point in the future. Not allowing any transaction
to be duplicated would require evidence to be kept for each transaction
ever made.
[[backward-compatibility]]
Backward compatibility
~~~~~~~~~~~~~~~~~~~~~~
The addition of this rule only makes some previously-valid blocks
invalid. This implies that if the rule is implemented by a supermajority
of miners, it is not possible to fork the block chain in a permanent way
between nodes with and without the new rule.
[[implementation]]
Implementation
~~~~~~~~~~~~~~
A patch for the reference client can be found on
https://github.com/sipa/bitcoin/tree/nooverwritetx
This BIP was implemented in Commit
https://github.com/bitcoin/bitcoin/commit/a206b0ea12eb4606b93323268fc81a4f1f952531[Do
not allow overwriting unspent transactions (BIP 30)] There have been
additional commits to refine the implementation of this BIP.
[[acknowledgements]]
Acknowledgements
~~~~~~~~~~~~~~~~
Thanks to Russell O'Connor for finding and demonstrating this problem,
and helping test the patch.

47
selected BIPs/bip-0030.mediawiki
View File

@ -1,47 +0,0 @@
<pre>
BIP: 30
Title: Duplicate transactions
Author: Pieter Wuille <pieter.wuille@gmail.com>
Status: Final
Type: Standards Track
Created: 2012-02-22
</pre>
==Abstract==
This document gives a specification for dealing with duplicate transactions in the block chain, in an attempt to solve certain problems the reference implementations has with them.
==Motivation==
So far, the Bitcoin reference implementation always assumed duplicate transactions (transactions with the same identifier) didn't exist. This is not true; in particular coinbases are easy to duplicate, and by building on duplicate coinbases, duplicate normal transactions are possible as well. Recently, an attack that exploits the reference implementation's dealing with duplicate transactions was described and demonstrated. It allows reverting fully-confirmed transactions to a single confirmation, making them vulnerable to become unspendable entirely. Another attack is possible that allows forking the block chain for a subset of the network.
==Specification==
To counter this problem, the following network rule is introduced:
*Blocks are not allowed to contain a transaction whose identifier matches that of an earlier, not-fully-spent transaction in the same chain.
This rule initially applied to all blocks whose timestamp is after March 15, 2012, 00:00 UTC (testnet: February 20, 2012 00:00 UTC). It was later extended by Commit [https://github.com/bitcoin/bitcoin/commit/ab91bf39b7c11e9c86bb2043c24f0f377f1cf514 Apply BIP30 checks to all blocks except the two historic violations.] to apply to all blocks except the two historic blocks at heights 91842 and 91880 on the main chain that had to be grandfathered in.
==Rationale==
Whatever solution is used, the following law must be obeyed to guarantee sane behaviour: the set of usable
transactions outputs must not be modified by adding blocks to the chain and removing them again. This happens during
a reorganisation, and the current Bitcoin reference implementation does not obey this law in case the temporarily
added blocks contain a duplicate transaction.
There are several potential solutions to this problem:
#Guarantee that all coinbases are unique, making duplicate transactions very hard to create.
#Remember previous remaining outputs of a given transaction identifier, in case a new transaction with the same identifier is added.
#Only allow duplicate transactions in case the previous instance of the transaction had no spendable outputs left. Removing a block from the chain can then safely reset the removed transaction's outputs to nothing.
The first option is probably the most complete one, as it also guarantees transaction identifiers are unique. However, implementing it requires several changes that need to be accepted throughout the network. Furthermore, it does not prevent duplicate transactions based on earlier duplicate coinbases. The second option is impossible to implement in a forward-compatible way, as it potentially renders currently-invalid blocks valid. In this document we choose for the third option, because it only requires a trivial change.
Fully-spent transactions are allowed to be duplicated in order not to hinder pruning at some point in the future. Not allowing any transaction to be duplicated would require evidence to be kept for each transaction ever made.
==Backward compatibility==
The addition of this rule only makes some previously-valid blocks invalid. This implies that if the rule is implemented by a supermajority of miners, it is not possible to fork the block chain in a permanent way between nodes with and without the new rule.
==Implementation==
A patch for the reference client can be found on https://github.com/sipa/bitcoin/tree/nooverwritetx
This BIP was implemented in Commit [https://github.com/bitcoin/bitcoin/commit/a206b0ea12eb4606b93323268fc81a4f1f952531 Do not allow overwriting unspent transactions (BIP 30)]
There have been additional commits to refine the implementation of this BIP.
==Acknowledgements==
Thanks to Russell O'Connor for finding and demonstrating this problem, and helping test the patch.

578
selected BIPs/bip-0032.asciidoc
View File

@ -1,578 +0,0 @@
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
* (15 Jan 2014) Rename keys with index ≥ 0x8000000 to hardened keys, and
add explicit conversion functions.
-------------------------------------------
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Accepted
Type: Informational
Created: 2012-02-11
-------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This document describes 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]]
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]]
Specification: Key derivation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[[conventions]]
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).
* Coordinates of points on the curve.
* Byte sequences.
Addition (+) of two coordinate pair is defined as application of the EC
group operation. Concatenation (||) is the operation of appending one
byte sequence onto another.
As standard conversion functions, we assume:
* point(p): returns the coordinate pair resulting from EC point
multiplication (repeated application of the EC group operation) of the
secp256k1 base point with the integer p.
* ser~32~(i): serialize a 32-bit unsigned integer i as a 4-byte
sequence, most significant byte first.
* ser~256~(p): serializes the integer p as a 32-byte sequence, most
significant byte first.
* ser~P~(P): serializes the coordinate pair P = (x,y) as a byte sequence
using SEC1's compressed form: (0x02 or 0x03) || ser~256~(x), where the
header byte depends on the parity of the omitted y coordinate.
* parse~256~(p): interprets a 32-byte sequence as a 256-bit number, most
significant byte first.
[[extended-keys]]
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 = point(k) and c the chain code.
Each extended key has 2^31^ normal child keys, and 2^31^ hardened child
keys. Each of these child keys has an index. The normal child keys use
indices 0 through 2^31^-1. The hardened child keys use indices 2^31^
through 2^32^-1. To ease notation for hardened key indices, a number
i~H~ represents i+2^31^.
[[child-key-derivation-ckd-functions]]
Child key derivation (CKD) functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Given a parent extended key and an index i, it is possible to compute
the corresponding child extended key. The algorithm to do so depends on
whether the child is a hardened key or not (or, equivalently, whether i
≥ 2^31^), and whether we're talking about private or public keys.
[[private-parent-key-private-child-key]]
Private parent key → private child key
++++++++++++++++++++++++++++++++++++++
The function CKDpriv((k~par~, c~par~), i) → (k~i~, c~i~) computes a
child extended private key from the parent extended private key:
* Check whether i ≥ 2^31^ (whether the child is a hardened key).
** If so (hardened child): let I = HMAC-SHA512(Key = c~par~, Data = 0x00
|| ser~256~(k~par~) || ser~32~(i)). (Note: The 0x00 pads the private key
to make it 33 bytes long.)
** If not (normal child): let I = HMAC-SHA512(Key = c~par~, Data =
ser~P~(point(k~par~)) || ser~32~(i)).
* Split I into two 32-byte sequences, I~L~ and I~R~.
* The returned child key k~i~ is parse~256~(I~L~) + k~par~ (mod n).
* The returned chain code c~i~ is I~R~.
* In case parse~256~(I~L~) ≥ n or k~i~ = 0, the resulting key is
invalid, and one should proceed with the next value for i. (Note: this
has probability lower than 1 in 2^127^.)
The HMAC-SHA512 function is specified in
http://tools.ietf.org/html/rfc4231[RFC 4231].
[[public-parent-key-public-child-key]]
Public parent key → public child key
++++++++++++++++++++++++++++++++++++
The function CKDpub((K~par~, c~par~), i) → (K~i~, c~i~) computes a child
extended public key from the parent extended public key. It is only
defined for non-hardened child keys.
* Check whether i ≥ 2^31^ (whether the child is a hardened key).
** If so (hardened child): return failure
** If not (normal child): let I = HMAC-SHA512(Key = c~par~, Data =
ser~P~(K~par~) || ser~32~(i)).
* Split I into two 32-byte sequences, I~L~ and I~R~.
* The returned child key K~i~ is point(parse~256~(I~L~)) + K~par~.
* The returned chain code c~i~ is I~R~.
* In case parse~256~(I~L~) ≥ n or K~i~ is the point at infinity, the
resulting key is invalid, and one should proceed with the next value for
i.
[[private-parent-key-public-child-key]]
Private parent key → public child key
+++++++++++++++++++++++++++++++++++++
The function N((k, c)) → (K, c) computes the extended public key
corresponding to an extended private key (the "neutered" version, as it
removes the ability to sign transactions).
* The returned key K is point(k).
* The returned chain code c is just the passed chain code.
To compute the public child key of a parent private key:
* N(CKDpriv((k~par~, c~par~), i)) (works always).
* CKDpub(N(k~par~, c~par~), i) (works only for non-hardened child keys).
The fact that they are equivalent is what makes non-hardened keys useful
(one can derive child public keys of a given parent key without knowing
any private key), and also what distinguishes them from hardened keys.
The reason for not always using non-hardened keys (which are more
useful) is security; see further for more information.
[[public-parent-key-private-child-key]]
Public parent key → private child key
+++++++++++++++++++++++++++++++++++++
This is not possible.
[[the-key-tree]]
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
CKDpriv(m,i) for several values of i, we get a number of level-1 derived
nodes. As each of these is again an extended key, CKDpriv can be applied
to those as well.
To shorten notation, we will write CKDpriv(CKDpriv(CKDpriv(m,3~H~),2),5)
as m/3~H~/2/5. Equivalently for public keys, we write
CKDpub(CKDpub(CKDpub(M,3),2,5) as M/3/2/5. This results in the following
identities:
* N(m/a/b/c) = N(m/a/b)/c = N(m/a)/b/c = N(m)/a/b/c = M/a/b/c.
* N(m/a~H~/b/c) = N(m/a~H~/b)/c = N(m/a~H~)/b/c.
However, N(m/a~H~) cannot be rewritten as N(m)/a~H~, as the latter is
not possible.
Each leaf node in the tree corresponds to an actual key, while the
internal nodes correspond to the collections of keys that descend from
them. The chain codes of the leaf nodes are ignored, and only their
embedded private or public key is relevant. 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 non-hardened public
keys.
[[key-identifiers]]
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 key fingerprint.
[[serialization-format]]
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 derived keys,
....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master
key)
* 4 bytes: child number. This is ser~32~(i) for i in x~i~ = x~par~/i,
with x~i~ the key being serialized. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (ser~P~(K) for public
keys, 0x00 || ser~256~(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]]
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 byte sequence S of a chosen length (between 128 and
512 bits; 256 bits is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(Key = "Bitcoin seed", Data = S)
* Split I into two 32-byte sequences, I~L~ and I~R~.
* Use parse~256~(I~L~) as master secret key, and I~R~ as master chain
code.
In case I~L~ is 0 or ≥n, the master key is invalid.
[[specification-wallet-structure]]
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.
[[the-default-wallet-layout]]
The default wallet layout
^^^^^^^^^^^^^^^^^^^^^^^^^
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~H~/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~H~/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]]
Use cases
^^^^^^^^^
[[full-wallet-sharing-m]]
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-nm]]
Audits: N(m/*)
++++++++++++++
In case an auditor needs full access to the list of incoming and
outgoing payments, one can share all account public extended keys. 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-mih]]
Per-office balances: m/i~H~
+++++++++++++++++++++++++++
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-nmih0]]
Recurrent business-to-business transactions: N(m/i~H~/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
h/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-nmih0]]
Unsecure money receiver: N(m/i~H~/0)
++++++++++++++++++++++++++++++++++++
When an unsecure webserver is used to run an e-commerce site, it needs
to know public addresses that are 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]]
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]]
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 2^128^ group operations).
the intended security properties of this standard are:
* Given a child extended private key (k~i~,c~i~) and the integer i, an
attacker cannot find the parent private key k~par~ more efficiently than
a 2^256^ brute force of HMAC-SHA512.
* Given any number (2 ≤ N ≤ 2^32^-1) of (index, extended private key)
tuples (i~j~,(k~i~j~~,c~i~j~~)), with distinct i~j~'s, determining
whether they are derived from a common parent extended private key
(i.e., whether there exists a (k~par~,c~par~) such that for each j in
(0..N-1) CKDpriv((k~par~,c~par~),i~j~)=(k~i~j~~,c~i~j~~)), cannot be
done more efficiently than a 2^256^ brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (K~par~,c~par~) and a child public
key (K~i~), it is hard to find i.
* Given a parent extended public key (K~par~,c~par~) and a non-hardened
child private key (k~i~), it is hard to find k~par~.
[[implications]]
Implications
^^^^^^^^^^^^
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 + any non-hardened private key descending from
it is equivalent to knowing the extended private key (and thus every
private and public key descending from it). This means that extended
public keys must be treated more carefully than regular public keys. It
is also the reason for the existence of hardened keys, and why they are
used for the account level in the tree. This way, a leak of
account-specific (or below) private key never risks compromising the
master or other accounts.
[[test-vectors]]
Test Vectors
~~~~~~~~~~~~
[[test-vector-1]]
Test vector 1
^^^^^^^^^^^^^
Master (hex): 000102030405060708090a0b0c0d0e0f
* Chain m
** ext pub:
xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8
** ext prv:
xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi
* Chain m/0~H~
** ext pub:
xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
** ext prv:
xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
* Chain m/0~H~/1
** ext pub:
xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47sSikHjJf3UFHKkNAWbWMiGj7Wf5uMash7SyYq527Hqck2AxYysAA7xmALppuCkwQ
** ext prv:
xprv9wTYmMFdV23N2TdNG573QoEsfRrWKQgWeibmLntzniatZvR9BmLnvSxqu53Kw1UmYPxLgboyZQaXwTCg8MSY3H2EU4pWcQDnRnrVA1xe8fs
* Chain m/0~H~/1/2~H~
** ext pub:
xpub6D4BDPcP2GT577Vvch3R8wDkScZWzQzMMUm3PWbmWvVJrZwQY4VUNgqFJPMM3No2dFDFGTsxxpG5uJh7n7epu4trkrX7x7DogT5Uv6fcLW5
** ext prv:
xprv9z4pot5VBttmtdRTWfWQmoH1taj2axGVzFqSb8C9xaxKymcFzXBDptWmT7FwuEzG3ryjH4ktypQSAewRiNMjANTtpgP4mLTj34bhnZX7UiM
* Chain m/0~H~/1/2~H~/2
** ext pub:
xpub6FHa3pjLCk84BayeJxFW2SP4XRrFd1JYnxeLeU8EqN3vDfZmbqBqaGJAyiLjTAwm6ZLRQUMv1ZACTj37sR62cfN7fe5JnJ7dh8zL4fiyLHV
** ext prv:
xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334
* Chain m/0~H~/1/2~H~/2/1000000000
** ext pub:
xpub6H1LXWLaKsWFhvm6RVpEL9P4KfRZSW7abD2ttkWP3SSQvnyA8FSVqNTEcYFgJS2UaFcxupHiYkro49S8yGasTvXEYBVPamhGW6cFJodrTHy
** ext prv:
xprvA41z7zogVVwxVSgdKUHDy1SKmdb533PjDz7J6N6mV6uS3ze1ai8FHa8kmHScGpWmj4WggLyQjgPie1rFSruoUihUZREPSL39UNdE3BBDu76
[[test-vector-2]]
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~H~
** ext pub:
xpub6ASAVgeehLbnwdqV6UKMHVzgqAG8Gr6riv3Fxxpj8ksbH9ebxaEyBLZ85ySDhKiLDBrQSARLq1uNRts8RuJiHjaDMBU4Zn9h8LZNnBC5y4a
** ext prv:
xprv9wSp6B7kry3Vj9m1zSnLvN3xH8RdsPP1Mh7fAaR7aRLcQMKTR2vidYEeEg2mUCTAwCd6vnxVrcjfy2kRgVsFawNzmjuHc2YmYRmagcEPdU9
* Chain m/0/2147483647~H~/1
** ext pub:
xpub6DF8uhdarytz3FWdA8TvFSvvAh8dP3283MY7p2V4SeE2wyWmG5mg5EwVvmdMVCQcoNJxGoWaU9DCWh89LojfZ537wTfunKau47EL2dhHKon
** ext prv:
xprv9zFnWC6h2cLgpmSA46vutJzBcfJ8yaJGg8cX1e5StJh45BBciYTRXSd25UEPVuesF9yog62tGAQtHjXajPPdbRCHuWS6T8XA2ECKADdw4Ef
* Chain m/0/2147483647~H~/1/2147483646~H~
** ext pub:
xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL
** ext prv:
xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc
* Chain m/0/2147483647~H~/1/2147483646~H~/2
** ext pub:
xpub6FnCn6nSzZAw5Tw7cgR9bi15UV96gLZhjDstkXXxvCLsUXBGXPdSnLFbdpq8p9HmGsApME5hQTZ3emM2rnY5agb9rXpVGyy3bdW6EEgAtqt
** ext prv:
xprvA2nrNbFZABcdryreWet9Ea4LvTJcGsqrMzxHx98MMrotbir7yrKCEXw7nadnHM8Dq38EGfSh6dqA9QWTyefMLEcBYJUuekgW4BYPJcr9E7j
[[implementations]]
Implementations
~~~~~~~~~~~~~~~
Two Python implementations exist:
PyCoin (https://github.com/richardkiss/pycoin) is a suite of utilities
for dealing with Bitcoin that includes BIP0032 wallet features.
BIP32Utils (https://github.com/jmcorgan/bip32utils) is a library and
command line interface specifically focused on BIP0032 wallets and
scripting.
A Java implementation is available at
https://github.com/bitsofproof/supernode/blob/1.1/api/src/main/java/com/bitsofproof/supernode/api/ExtendedKey.java
A C++ implementation is available at
https://github.com/CodeShark/CoinClasses/tree/master/tests/hdwallets
An Objective-C implementation is available at
https://github.com/oleganza/CoreBitcoin/blob/master/CoreBitcoin/BTCKeychain.h
A Ruby implementation is available at https://github.com/wink/money-tree
A Go implementation is available at
https://github.com/WeMeetAgain/go-hdwallet
A JavaScript implementation is available at
https://github.com/sarchar/brainwallet.github.com/tree/bip32
A PHP implemetation is available at
https://github.com/Bit-Wasp/bitcoin-lib-php
A C# implementation is available at
https://github.com/NicolasDorier/NBitcoin (ExtKey, ExtPubKey)
[[acknowledgements]]
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.

280
selected BIPs/bip-0032.mediawiki
View File

@ -1,280 +0,0 @@
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<sub>L</sub> to addition of I<sub>L</sub> (faster, easier implementation)
* (25 May 2013) Added test vectors
* (15 Jan 2014) Rename keys with index ≥ 0x8000000 to hardened keys, and add explicit conversion functions.
<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Accepted
Type: Informational
Created: 2012-02-11
</pre>
==Abstract==
This document describes 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).
* Coordinates of points on the curve.
* Byte sequences.
Addition (+) of two coordinate pair is defined as application of the EC group operation.
Concatenation (||) is the operation of appending one byte sequence onto another.
As standard conversion functions, we assume:
* point(p): returns the coordinate pair resulting from EC point multiplication (repeated application of the EC group operation) of the secp256k1 base point with the integer p.
* ser<sub>32</sub>(i): serialize a 32-bit unsigned integer i as a 4-byte sequence, most significant byte first.
* ser<sub>256</sub>(p): serializes the integer p as a 32-byte sequence, most significant byte first.
* ser<sub>P</sub>(P): serializes the coordinate pair P = (x,y) as a byte sequence using SEC1's compressed form: (0x02 or 0x03) || ser<sub>256</sub>(x), where the header byte depends on the parity of the omitted y coordinate.
* parse<sub>256</sub>(p): interprets a 32-byte sequence as a 256-bit number, most significant byte first.
===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 = point(k) and c the chain code.
Each extended key has 2<sup>31</sup> normal child keys, and 2<sup>31</sup> hardened child keys. Each of these child keys has an index. The normal child keys use indices 0 through 2<sup>31</sup>-1. The hardened child keys use indices 2<sup>31</sup> through 2<sup>32</sup>-1. To ease notation for hardened key indices, a number i<sub>H</sub> represents i+2<sup>31</sup>.
===Child key derivation (CKD) functions===
Given a parent extended key and an index i, it is possible to compute the corresponding child extended key. The algorithm to do so depends on whether the child is a hardened key or not (or, equivalently, whether i ≥ 2<sup>31</sup>), and whether we're talking about private or public keys.
====Private parent key &rarr; private child key====
The function CKDpriv((k<sub>par</sub>, c<sub>par</sub>), i) &rarr; (k<sub>i</sub>, c<sub>i</sub>) computes a child extended private key from the parent extended private key:
* Check whether i ≥ 2<sup>31</sup> (whether the child is a hardened key).
** If so (hardened child): let I = HMAC-SHA512(Key = c<sub>par</sub>, Data = 0x00 || ser<sub>256</sub>(k<sub>par</sub>) || ser<sub>32</sub>(i)). (Note: The 0x00 pads the private key to make it 33 bytes long.)
** If not (normal child): let I = HMAC-SHA512(Key = c<sub>par</sub>, Data = ser<sub>P</sub>(point(k<sub>par</sub>)) || ser<sub>32</sub>(i)).
* Split I into two 32-byte sequences, I<sub>L</sub> and I<sub>R</sub>.
* The returned child key k<sub>i</sub> is parse<sub>256</sub>(I<sub>L</sub>) + k<sub>par</sub> (mod n).
* The returned chain code c<sub>i</sub> is I<sub>R</sub>.
* In case parse<sub>256</sub>(I<sub>L</sub>) ≥ n or k<sub>i</sub> = 0, the resulting key is invalid, and one should proceed with the next value for i. (Note: this has probability lower than 1 in 2<sup>127</sup>.)
The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].
====Public parent key &rarr; public child key====
The function CKDpub((K<sub>par</sub>, c<sub>par</sub>), i) &rarr; (K<sub>i</sub>, c<sub>i</sub>) computes a child extended public key from the parent extended public key. It is only defined for non-hardened child keys.
* Check whether i ≥ 2<sup>31</sup> (whether the child is a hardened key).
** If so (hardened child): return failure
** If not (normal child): let I = HMAC-SHA512(Key = c<sub>par</sub>, Data = ser<sub>P</sub>(K<sub>par</sub>) || ser<sub>32</sub>(i)).
* Split I into two 32-byte sequences, I<sub>L</sub> and I<sub>R</sub>.
* The returned child key K<sub>i</sub> is point(parse<sub>256</sub>(I<sub>L</sub>)) + K<sub>par</sub>.
* The returned chain code c<sub>i</sub> is I<sub>R</sub>.
* In case parse<sub>256</sub>(I<sub>L</sub>) ≥ n or K<sub>i</sub> is the point at infinity, the resulting key is invalid, and one should proceed with the next value for i.
====Private parent key &rarr; public child key====
The function N((k, c)) &rarr; (K, c) computes the extended public key corresponding to an extended private key (the "neutered" version, as it removes the ability to sign transactions).
* The returned key K is point(k).
* The returned chain code c is just the passed chain code.
To compute the public child key of a parent private key:
* N(CKDpriv((k<sub>par</sub>, c<sub>par</sub>), i)) (works always).
* CKDpub(N(k<sub>par</sub>, c<sub>par</sub>), i) (works only for non-hardened child keys).
The fact that they are equivalent is what makes non-hardened keys useful (one can derive child public keys of a given parent key without knowing any private key), and also what distinguishes them from hardened keys. The reason for not always using non-hardened keys (which are more useful) is security; see further for more information.
====Public parent key &rarr; private child key====
This is not possible.
===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 CKDpriv(m,i) for several values of i, we get a number of level-1 derived nodes. As each of these is again an extended key, CKDpriv can be applied to those as well.
To shorten notation, we will write CKDpriv(CKDpriv(CKDpriv(m,3<sub>H</sub>),2),5) as m/3<sub>H</sub>/2/5. Equivalently for public keys, we write CKDpub(CKDpub(CKDpub(M,3),2,5) as M/3/2/5. This results in the following identities:
* N(m/a/b/c) = N(m/a/b)/c = N(m/a)/b/c = N(m)/a/b/c = M/a/b/c.
* N(m/a<sub>H</sub>/b/c) = N(m/a<sub>H</sub>/b)/c = N(m/a<sub>H</sub>)/b/c.
However, N(m/a<sub>H</sub>) cannot be rewritten as N(m)/a<sub>H</sub>, as the latter is not possible.
Each leaf node in the tree corresponds to an actual key, while the internal nodes correspond to the collections of keys that descend from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is relevant. 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 non-hardened public keys.
===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 key 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 derived keys, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is ser<sub>32</sub>(i) for i in x<sub>i</sub> = x<sub>par</sub>/i, with x<sub>i</sub> the key being serialized. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (ser<sub>P</sub>(K) for public keys, 0x00 || ser<sub>256</sub>(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<sup>512</sup>, 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 byte sequence S of a chosen length (between 128 and 512 bits; 256 bits is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(Key = "Bitcoin seed", Data = S)
* Split I into two 32-byte sequences, I<sub>L</sub> and I<sub>R</sub>.
* Use parse<sub>256</sub>(I<sub>L</sub>) as master secret key, and I<sub>R</sub> as master chain code.
In case I<sub>L</sub> is 0 or ≥n, the master key is invalid.
<img src=bip-0032/derivation.png></img>
==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.
===The default wallet layout===
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<sub>H</sub>/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<sub>H</sub>/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: N(m/*)====
In case an auditor needs full access to the list of incoming and outgoing payments, one can share all account public extended keys. 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<sub>H</sub>====
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: N(m/i<sub>H</sub>/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 h/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: N(m/i<sub>H</sub>/0)====
When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that are 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 2<sup>128</sup> group operations).
the intended security properties of this standard are:
* Given a child extended private key (k<sub>i</sub>,c<sub>i</sub>) and the integer i, an attacker cannot find the parent private key k<sub>par</sub> more efficiently than a 2<sup>256</sup> brute force of HMAC-SHA512.
* Given any number (2 ≤ N ≤ 2<sup>32</sup>-1) of (index, extended private key) tuples (i<sub>j</sub>,(k<sub>i<sub>j</sub></sub>,c<sub>i<sub>j</sub></sub>)), with distinct i<sub>j</sub>'s, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (k<sub>par</sub>,c<sub>par</sub>) such that for each j in (0..N-1) CKDpriv((k<sub>par</sub>,c<sub>par</sub>),i<sub>j</sub>)=(k<sub>i<sub>j</sub></sub>,c<sub>i<sub>j</sub></sub>)), cannot be done more efficiently than a 2<sup>256</sup> brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (K<sub>par</sub>,c<sub>par</sub>) and a child public key (K<sub>i</sub>), it is hard to find i.
* Given a parent extended public key (K<sub>par</sub>,c<sub>par</sub>) and a non-hardened child private key (k<sub>i</sub>), it is hard to find k<sub>par</sub>.
===Implications===
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 + any non-hardened private key descending from it is equivalent to knowing the extended private key (and thus every private and public key descending from it). This means that extended public keys must be treated more carefully than regular public keys.
It is also the reason for the existence of hardened keys, and why they are used for the account level in the tree. This way, a leak of account-specific (or below) private key never risks compromising the master or other accounts.
==Test Vectors==
===Test vector 1===
Master (hex): 000102030405060708090a0b0c0d0e0f
* Chain m
** ext pub: xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8
** ext prv: xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi
* Chain m/0<sub>H</sub>
** ext pub: xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
** ext prv: xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
* Chain m/0<sub>H</sub>/1
** ext pub: xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47sSikHjJf3UFHKkNAWbWMiGj7Wf5uMash7SyYq527Hqck2AxYysAA7xmALppuCkwQ
** ext prv: xprv9wTYmMFdV23N2TdNG573QoEsfRrWKQgWeibmLntzniatZvR9BmLnvSxqu53Kw1UmYPxLgboyZQaXwTCg8MSY3H2EU4pWcQDnRnrVA1xe8fs
* Chain m/0<sub>H</sub>/1/2<sub>H</sub>
** ext pub: xpub6D4BDPcP2GT577Vvch3R8wDkScZWzQzMMUm3PWbmWvVJrZwQY4VUNgqFJPMM3No2dFDFGTsxxpG5uJh7n7epu4trkrX7x7DogT5Uv6fcLW5
** ext prv: xprv9z4pot5VBttmtdRTWfWQmoH1taj2axGVzFqSb8C9xaxKymcFzXBDptWmT7FwuEzG3ryjH4ktypQSAewRiNMjANTtpgP4mLTj34bhnZX7UiM
* Chain m/0<sub>H</sub>/1/2<sub>H</sub>/2
** ext pub: xpub6FHa3pjLCk84BayeJxFW2SP4XRrFd1JYnxeLeU8EqN3vDfZmbqBqaGJAyiLjTAwm6ZLRQUMv1ZACTj37sR62cfN7fe5JnJ7dh8zL4fiyLHV
** ext prv: xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334
* Chain m/0<sub>H</sub>/1/2<sub>H</sub>/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<sub>H</sub>
** ext pub: xpub6ASAVgeehLbnwdqV6UKMHVzgqAG8Gr6riv3Fxxpj8ksbH9ebxaEyBLZ85ySDhKiLDBrQSARLq1uNRts8RuJiHjaDMBU4Zn9h8LZNnBC5y4a
** ext prv: xprv9wSp6B7kry3Vj9m1zSnLvN3xH8RdsPP1Mh7fAaR7aRLcQMKTR2vidYEeEg2mUCTAwCd6vnxVrcjfy2kRgVsFawNzmjuHc2YmYRmagcEPdU9
* Chain m/0/2147483647<sub>H</sub>/1
** ext pub: xpub6DF8uhdarytz3FWdA8TvFSvvAh8dP3283MY7p2V4SeE2wyWmG5mg5EwVvmdMVCQcoNJxGoWaU9DCWh89LojfZ537wTfunKau47EL2dhHKon
** ext prv: xprv9zFnWC6h2cLgpmSA46vutJzBcfJ8yaJGg8cX1e5StJh45BBciYTRXSd25UEPVuesF9yog62tGAQtHjXajPPdbRCHuWS6T8XA2ECKADdw4Ef
* Chain m/0/2147483647<sub>H</sub>/1/2147483646<sub>H</sub>
** ext pub: xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL
** ext prv: xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc
* Chain m/0/2147483647<sub>H</sub>/1/2147483646<sub>H</sub>/2
** ext pub: xpub6FnCn6nSzZAw5Tw7cgR9bi15UV96gLZhjDstkXXxvCLsUXBGXPdSnLFbdpq8p9HmGsApME5hQTZ3emM2rnY5agb9rXpVGyy3bdW6EEgAtqt
** ext prv: xprvA2nrNbFZABcdryreWet9Ea4LvTJcGsqrMzxHx98MMrotbir7yrKCEXw7nadnHM8Dq38EGfSh6dqA9QWTyefMLEcBYJUuekgW4BYPJcr9E7j
==Implementations==
Two Python implementations exist:
PyCoin (https://github.com/richardkiss/pycoin) is a suite of utilities for dealing with Bitcoin that includes BIP0032 wallet features. BIP32Utils (https://github.com/jmcorgan/bip32utils) is a library and command line interface specifically focused on BIP0032 wallets and scripting.
A Java implementation is available at https://github.com/bitsofproof/supernode/blob/1.1/api/src/main/java/com/bitsofproof/supernode/api/ExtendedKey.java
A C++ implementation is available at https://github.com/CodeShark/CoinClasses/tree/master/tests/hdwallets
An Objective-C implementation is available at https://github.com/oleganza/CoreBitcoin/blob/master/CoreBitcoin/BTCKeychain.h
A Ruby implementation is available at https://github.com/wink/money-tree
A Go implementation is available at https://github.com/WeMeetAgain/go-hdwallet
A JavaScript implementation is available at https://github.com/sarchar/brainwallet.github.com/tree/bip32
A PHP implemetation is available at https://github.com/Bit-Wasp/bitcoin-lib-php
A C# implementation is available at https://github.com/NicolasDorier/NBitcoin (ExtKey, ExtPubKey)
==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.

61
selected BIPs/bip-0034.asciidoc
View File

@ -1,61 +0,0 @@
--------------------------------------------------
BIP: 34
Title: Block v2, Height in Coinbase
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Accepted
Type: Standards Track
Created: 2012-07-06
--------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
Bitcoin blocks and transactions are versioned binary structures. Both
currently use version 1. This BIP introduces an upgrade path for
versioned transactions and blocks. A unique value is added to newly
produced coinbase transactions, and blocks are updated to version 2.
[[motivation]]
Motivation
~~~~~~~~~~
1. Clarify and exercise the mechanism whereby the bitcoin network
collectively consents to upgrade transaction or block binary structures,
rules and behaviors.
2. Enforce block and transaction uniqueness, and assist unconnected
block validation.
[[specification]]
Specification
~~~~~~~~~~~~~
1. Treat transactions with a version greater than 1 as non-standard
(official Satoshi client will not mine or relay them).
2. Add height as the first item in the coinbase transaction's
scriptSig, and increase block version to 2. The format of the height is
"serialized CScript" -- first byte is number of bytes in the number
(will be 0x03 on main net for the next 300 or so years), following bytes
are little-endian representation of the number. Height is the height of
the mined block in the block chain, where the genesis block is height
zero (0).
3. 75% rule: If 750 of the last 1,000 blocks are version 2 or greater,
reject invalid version 2 blocks. (testnet3: 51 of last 100)
4. 95% rule ("Point of no return"): If 950 of the last 1,000 blocks are
version 2 or greater, reject all version 1 blocks. (testnet3: 75 of last
100)
[[backward-compatibility]]
Backward compatibility
~~~~~~~~~~~~~~~~~~~~~~
All older clients are compatible with this change. Users and merchants
should not be impacted. Miners are strongly recommended to upgrade to
version 2 blocks. Once 95% of the miners have upgraded to version 2, the
remainder will be orphaned if they fail to upgrade.
[[implementation]]
Implementation
~~~~~~~~~~~~~~
https://github.com/bitcoin/bitcoin/pull/1526

32
selected BIPs/bip-0034.mediawiki
View File

@ -1,32 +0,0 @@
<pre>
BIP: 34
Title: Block v2, Height in Coinbase
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Accepted
Type: Standards Track
Created: 2012-07-06
</pre>
==Abstract==
Bitcoin blocks and transactions are versioned binary structures. Both currently use version 1. This BIP introduces an upgrade path for versioned transactions and blocks. A unique value is added to newly produced coinbase transactions, and blocks are updated to version 2.
==Motivation==
# Clarify and exercise the mechanism whereby the bitcoin network collectively consents to upgrade transaction or block binary structures, rules and behaviors.
# Enforce block and transaction uniqueness, and assist unconnected block validation.
==Specification==
# Treat transactions with a version greater than 1 as non-standard (official Satoshi client will not mine or relay them).
# Add height as the first item in the coinbase transaction's scriptSig, and increase block version to 2. The format of the height is "serialized CScript" -- first byte is number of bytes in the number (will be 0x03 on main net for the next 300 or so years), following bytes are little-endian representation of the number. Height is the height of the mined block in the block chain, where the genesis block is height zero (0).
# 75% rule: If 750 of the last 1,000 blocks are version 2 or greater, reject invalid version 2 blocks. (testnet3: 51 of last 100)
# 95% rule ("Point of no return"): If 950 of the last 1,000 blocks are version 2 or greater, reject all version 1 blocks. (testnet3: 75 of last 100)
==Backward compatibility==
All older clients are compatible with this change. Users and merchants should not be impacted. Miners are strongly recommended to upgrade to version 2 blocks. Once 95% of the miners have upgraded to version 2, the remainder will be orphaned if they fail to upgrade.
==Implementation==
https://github.com/bitcoin/bitcoin/pull/1526

64
selected BIPs/bip-0035.asciidoc
View File

@ -1,64 +0,0 @@
-------------------------------------------
BIP: 35
Title: mempool message
Author: Jeff Garzik <jgarzik@exmulti.com>
Status: Accepted
Type: Standards Track
Created: 2012-08-16
-------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
Make a network node's transaction memory pool accessible via a new
"mempool" message. Extend the existing "getdata" message behavior to
permit accessing the transaction memory pool.
[[motivation]]
Motivation
~~~~~~~~~~
Several use cases make it desireable to expose a network node's
transaction memory pool:
1. SPV clients, wishing to obtain zero-confirmation transactions sent
or received.
2. Miners, to avoid missing lucrative fees, downloading existing
network transactions after a restart.
3. Remote network diagnostics.
[[specification]]
Specification
~~~~~~~~~~~~~
1. The mempool message is defined as an empty message where pchCommand
== "mempool"
2. Upon receipt of a "mempool" message, the node will respond with an
"inv" message containing MSG_TX hashes of all the transactions in the
node's transaction memory pool, if any.
3. The typical node behavior in response to an "inv" is "getdata".
However, the reference Satoshi implementation ignores requests for
transaction hashes outside that which is recently relayed. To support
"mempool", an implementation must extend its "getdata" message support
to querying the memory pool.
4. Feature discovery is enabled by checking two "version" message
attributes:
1. Protocol version >= 60002
2. NODE_NETWORK bit set in nServices
Note that existing implementations drop "inv" messages with a vector
size > 50000.
[[backward-compatibility]]
Backward compatibility
~~~~~~~~~~~~~~~~~~~~~~
Older clients remain 100% compatible and interoperable after this
change.
[[implementation]]
Implementation
~~~~~~~~~~~~~~
https://github.com/bitcoin/bitcoin/pull/1641

38
selected BIPs/bip-0035.mediawiki
View File

@ -1,38 +0,0 @@
<pre>
BIP: 35
Title: mempool message
Author: Jeff Garzik <jgarzik@exmulti.com>
Status: Accepted
Type: Standards Track
Created: 2012-08-16
</pre>
==Abstract==
Make a network node's transaction memory pool accessible via a new "mempool" message. Extend the existing "getdata" message behavior to permit accessing the transaction memory pool.
==Motivation==
Several use cases make it desireable to expose a network node's transaction memory pool:
# SPV clients, wishing to obtain zero-confirmation transactions sent or received.
# Miners, to avoid missing lucrative fees, downloading existing network transactions after a restart.
# Remote network diagnostics.
==Specification==
# The mempool message is defined as an empty message where pchCommand == "mempool"
# Upon receipt of a "mempool" message, the node will respond with an "inv" message containing MSG_TX hashes of all the transactions in the node's transaction memory pool, if any.
# The typical node behavior in response to an "inv" is "getdata". However, the reference Satoshi implementation ignores requests for transaction hashes outside that which is recently relayed. To support "mempool", an implementation must extend its "getdata" message support to querying the memory pool.
# Feature discovery is enabled by checking two "version" message attributes:
## Protocol version >= 60002
## NODE_NETWORK bit set in nServices
Note that existing implementations drop "inv" messages with a vector size > 50000.
==Backward compatibility==
Older clients remain 100% compatible and interoperable after this change.
==Implementation==
https://github.com/bitcoin/bitcoin/pull/1641

404
selected BIPs/bip-0037.asciidoc
View File

@ -1,404 +0,0 @@
-----------------------------------------------------------------------
BIP: 37
Title: Connection Bloom filtering
Author: Mike Hearn <hearn@google.com>, Matt Corallo <bip@bluematt.me>
Status: Accepted
Type: Standards Track
Created: 2012-10-24
-----------------------------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP adds new support to the peer-to-peer protocol that allows peers
to reduce the amount of transaction data they are sent. Peers have the
option of setting _filters_ on each connection they make after the
version handshake has completed. A filter is defined as a
http://en.wikipedia.org/wiki/Bloom_filter[Bloom filter] on data derived
from transactions. A Bloom filter is a probabilistic data structure
which allows for testing set membership - they can have false positives
but not false negatives.
This document will not go into the details of how Bloom filters work and
the reader is referred to Wikipedia for an introduction to the topic.
[[motivation]]
Motivation
~~~~~~~~~~
As Bitcoin grows in usage the amount of bandwidth needed to download
blocks and transaction broadcasts increases. Clients implementing
_simplified payment verification_ do not attempt to fully verify the
block chain, instead just checking that block headers connect together
correctly and trusting that the transactions in a chain of high
difficulty are in fact valid. See the Bitcoin paper for more detail on
this mode.
Today, link:Simplified_Payment_Verification[SPV] clients have to
download the entire contents of blocks and all broadcast transactions,
only to throw away the vast majority of the transactions that are not
relevant to their wallets. This slows down their synchronization
process, wastes users bandwidth (which on phones is often metered) and
increases memory usage. All three problems are triggering real user
complaints for the Android "Bitcoin Wallet" app which implements SPV
mode. In order to make chain synchronization fast, cheap and able to run
on older phones with limited memory we want to have remote peers throw
away irrelevant transactions before sending them across the network.
[[design-rationale]]
Design rationale
~~~~~~~~~~~~~~~~
The most obvious way to implement the stated goal would be for clients
to upload lists of their keys to the remote node. We take a more complex
approach for the following reasons:
* Privacy: Because Bloom filters are probabilistic, with the false
positive rate chosen by the client, nodes can trade off precision vs
bandwidth usage. A node with access to lots of bandwidth may choose to
have a high FP rate, meaning the remote peer cannot accurately know
which transactions belong to the client and which don't. A node with
very little bandwidth may choose to use a very accurate filter meaning
that they only get sent transactions actually relevant to their wallet,
but remote peers may be able to correlate transactions with IP addresses
(and each other).
* Bloom filters are compact and testing membership in them is fast. This
results in satisfying performance characteristics with minimal risk of
opening up potential for DoS attacks.
[[specification]]
Specification
~~~~~~~~~~~~~
[[new-messages]]
New messages
^^^^^^^^^^^^
We start by adding three new messages to the protocol:
* `filterload`, which sets the current Bloom filter on the connection
* `filteradd`, which adds the given data element to the connections
current filter without requiring a completely new one to be set
* `filterclear`, which deletes the current filter and goes back to
regular pre-BIP37 usage.
Note that there is no filterremove command because by their nature,
Bloom filters are append-only data structures. Once an element is added
it cannot be removed again without rebuilding the entire structure from
scratch.
The `filterload` command is defined as follows:
[cols=",,,",options="header",]
|=======================================================================
|Field Size |Description |Data type |Comments
|? |filter |uint8_t[] |The filter itself is simply a bit field of
arbitrary byte-aligned size. The maximum size is 36,000 bytes.
|4 |nHashFuncs |uint32_t |The number of hash functions to use in this
filter. The maximum value allowed in this field is 50.
|4 |nTweak |uint32_t |A random value to add to the seed value in the
hash function used by the bloom filter.
|1 |nFlags |uint8_t |A set of flags that control how matched items are
added to the filter.
|=======================================================================
See below for a description of the Bloom filter algorithm and how to
select nHashFuncs and filter size for a desired false positive rate.
Upon receiving a `filterload` command, the remote peer will immediately
restrict the broadcast transactions it announces (in inv packets) to
transactions matching the filter, where the matching algorithm is
specified below. The flags control the update behaviour of the matching
algorithm.
The `filteradd` command is defined as follows:
[cols=",,,",options="header",]
|==================================================================
|Field Size |Description |Data type |Comments
|? |data |uint8_t[] |The data element to add to the current filter.
|==================================================================
The data field must be smaller than or equal to 520 bytes in size (the
maximum size of any potentially matched object).
The given data element will be added to the Bloom filter. A filter must
have been previously provided using `filterload`. This command is useful
if a new key or script is added to a clients wallet whilst it has
connections to the network open, it avoids the need to re-calculate and
send an entirely new filter to every peer (though doing so is usually
advisable to maintain anonymity).
The `filterclear` command has no arguments at all.
After a filter has been set, nodes don't merely stop announcing
non-matching transactions, they can also serve filtered blocks. A
filtered block is defined by the `merkleblock` message and is defined
like this:
[cols=",,,",options="header",]
|=======================================================================
|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
|4 |total_transactions |uint32_t |Number of transactions in the block
(including unmatched ones)
|? |hashes |uint256[] |hashes in depth-first order (including standard
varint size prefix)
|? |flags |byte[] |flag bits, packed per 8 in a byte, least significant
bit first (including standard varint size prefix)
|=======================================================================
See below for the format of the partial merkle tree hashes and flags.
Thus, a `merkleblock` message is a block header, plus a part of a merkle
tree which can be used to extract identifying information for
transactions that matched the filter and prove that the matching
transaction data really did appear in the solved block. Clients can use
this data to be sure that the remote node is not feeding them fake
transactions that never appeared in a real block, although lying through
omission is still possible.
[[extensions-to-existing-messages]]
Extensions to existing messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `version` command is extended with a new field:
[cols=",,,",options="header",]
|=======================================================================
|Field Size |Description |Data type |Comments
|1 byte |fRelay |bool |If false then broadcast transactions will not be
announced until a filter\{load,add,clear} command is received. If
missing or true, no change in protocol behaviour occurs.
|=======================================================================
SPV clients that wish to use Bloom filtering would normally set fRelay
to false in the version message, then set a filter based on their wallet
(or a subset of it, if they are overlapping different peers). Being able
to opt-out of inv messages until the filter is set prevents a client
being flooded with traffic in the brief window of time between finishing
version handshaking and setting the filter.
The `getdata` command is extended to allow a new type in the `inv`
submessage. The type field can now be `MSG_FILTERED_BLOCK (== 3)` rather
than `MSG_BLOCK`. If no filter has been set on the connection, a request
for filtered blocks is ignored. If a filter has been set, a
`merkleblock` message is returned for the requested block hash. In
addition, because a `merkleblock` message contains only a list of
transaction hashes, transactions matching the filter should also be sent
in separate tx messages after the merkleblock is sent. This avoids a
slow roundtrip that would otherwise be required (receive hashes, didn't
see some of these transactions yet, ask for them). Note that because
there is currently no way to request transactions which are already in a
block from a node (aside from requesting the full block), the set of
matching transactions that the requesting node hasn't either received or
announced with an inv must be sent and any additional transactions which
match the filter may also be sent. This allows for clients (such as the
reference client) to limit the number of invs it must remember a given
node to have announced while still providing nodes with, at a minimum,
all the transactions it needs.
[[filter-matching-algorithm]]
Filter matching algorithm
^^^^^^^^^^^^^^^^^^^^^^^^^
The filter can be tested against arbitrary pieces of data, to see if
that data was inserted by the client. Therefore the question arises of
what pieces of data should be inserted/tested.
To determine if a transaction matches the filter, the following
algorithm is used. Once a match is found the algorithm aborts.
1. Test the hash of the transaction itself.
2. For each output, test each data element of the output script. This
means each hash and key in the output script is tested independently.
*Important:* if an output matches whilst testing a transaction, the node
might need to update the filter by inserting the serialized COutPoint
structure. See below for more details.
3. For each input, test the serialized COutPoint structure.
4. For each input, test each data element of the input script (note:
input scripts only ever contain data elements).
5. Otherwise there is no match.
In this way addresses, keys and script hashes (for P2SH outputs) can all
be added to the filter. You can also match against classes of
transactions that are marked with well known data elements in either
inputs or outputs, for example, to implement various forms of
link:Smart property[Smart property].
The test for outpoints is there to ensure you can find transactions
spending outputs in your wallet, even though you don't know anything
about their form. As you can see, once set on a connection the filter is
*not static* and can change throughout the connections lifetime. This is
done to avoid the following race condition:
1. A client sets a filter matching a key in their wallet. They then
start downloading the block chain. The part of the chain that the client
is missing is requested using getblocks.
2. The first block is read from disk by the serving peer. It contains
TX 1 which sends money to the clients key. It matches the filter and is
thus sent to the client.
3. The second block is read from disk by the serving peer. It contains
TX 2 which spends TX 1. However TX 2 does not contain any of the clients
keys and is thus not sent. The client does not know the money they
received was already spent.
By updating the bloom filter atomically in step 2 with the discovered
outpoint, the filter will match against TX 2 in step 3 and the client
will learn about all relevant transactions, despite that there is no
pause between the node processing the first and second blocks.
The nFlags field of the filter controls the nodes precise update
behaviour and is a bit field.
* `BLOOM_UPDATE_NONE (0)` means the filter is not adjusted when a match
is found.
* `BLOOM_UPDATE_ALL (1)` means if the filter matches any data element in
a scriptPubKey the outpoint is serialized and inserted into the filter.
* `BLOOM_UPDATE_P2PUBKEY_ONLY (2)` means the outpoint is inserted into
the filter only if a data element in the scriptPubKey is matched, and
that script is of the standard "pay to pubkey" or "pay to multisig"
forms.
These distinctions are useful to avoid too-rapid degradation of the
filter due to an increasing false positive rate. We can observe that a
wallet which expects to receive only payments of the standard
pay-to-address form doesn't need automatic filter updates because any
transaction that spends one of its own outputs has a predictable data
element in the input (the pubkey that hashes to the address). If a
wallet might receive pay-to-address outputs and also pay-to-pubkey or
pay-to-multisig outputs then BLOOM_UPDATE_P2PUBKEY_ONLY is appropriate,
as it avoids unnecessary expansions of the filter for the most common
types of output but still ensures correct behaviour with payments that
explicitly specify keys.
Obviously, nFlags == 1 or nFlags == 2 mean that the filter will get
dirtier as more of the chain is scanned. Clients should monitor the
observed false positive rate and periodically refresh the filter with a
clean one.
[[partial-merkle-branch-format]]
Partial Merkle branch format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A _Merkle tree_ is a way of arranging a set of items as leaf nodes of
tree in which the interior nodes are hashes of the concatenations of
their child hashes. The root node is called the _Merkle root_. Every
Bitcoin block contains a Merkle root of the tree formed from the blocks
transactions. By providing some elements of the trees interior nodes
(called a _Merkle branch_) a proof is formed that the given transaction
was indeed in the block when it was being mined, but the size of the
proof is much smaller than the size of the original block.
[[constructing-a-partial-merkle-tree-object]]
Constructing a partial merkle tree object
+++++++++++++++++++++++++++++++++++++++++
* Traverse the merkle tree from the root down, and for each encountered
node:
** Check whether this node corresponds to a leaf node (transaction) that
is to be included OR any parent thereof:
*** If so, append a '1' bit to the flag bits
*** Otherwise, append a '0' bit.
** Check whether this node is a internal node (non-leaf) AND is the
parent of an included leaf node:
*** If so:
**** Descend into its left child node, and process the subtree beneath
it entirely (depth-first).
**** If this node has a right child node too, descend into it as well.
*** Otherwise: append this node's hash to the hash list.
[[parsing-a-partial-merkle-tree-object]]
Parsing a partial merkle tree object
++++++++++++++++++++++++++++++++++++
As the partial block message contains the number of transactions in the
entire block, the shape of the merkle tree is known before hand. Again,
traverse this tree, computing traversed node's hashes along the way:
* Read a bit from the flag bit list:
** If it is '0':
*** Read a hash from the hashes list, and return it as this node's hash.
** If it is '1' and this is a leaf node:
*** Read a hash from the hashes list, store it as a matched txid, and
return it as this node's hash.
** If it is '1' and this is an internal node:
*** Descend into its left child tree, and store its computed hash as L.
*** If this node has a right child as well:
**** Descend into its right child, and store its computed hash as R.
**** If L == R, the partial merkle tree object is invalid.
**** Return Hash(L || R).
*** If this node has no right child, return Hash(L || L).
The partial merkle tree object is only valid if:
* All hashes in the hash list were consumed and no more.
* All bits in the flag bits list were consumed (except padding to make
it into a full byte), and no more.
* The hash computed for the root node matches the block header's merkle
root.
* The block header is valid, and matches its claimed proof of work.
* In two-child nodes, the hash of the left and right branches was never
equal.
[[bloom-filter-format]]
Bloom filter format
^^^^^^^^^^^^^^^^^^^
A Bloom filter is a bit-field in which bits are set based on feeding the
data element to a set of different hash functions. The number of hash
functions used is a parameter of the filter. In Bitcoin we use version 3
of the 32-bit Murmur hash function. To get N "different" hash functions
we simply initialize the Murmur algorithm with the following formula:
`nHashNum * 0xFBA4C795 + nTweak`
i.e. if the filter is initialized with 4 hash functions and a tweak of
0x00000005, when the second function (index 1) is needed h1 would be
equal to 4221880218.
When loading a filter with the `filterload` command, there are two
parameters that can be chosen. One is the size of the filter in bytes.
The other is the number of hash functions to use. To select the
parameters you can use the following formulas:
Let N be the number of elements you wish to insert into the set and P be
the probability of a false positive, where 1.0 is "match everything" and
zero is unachievable.
The size S of the filter in bytes is given by
`(-1 / pow(log(2), 2) * N * log(P)) / 8`. Of course you must ensure it
does not go over the maximum size (36,000: selected as it represents a
filter of 20,000 items with false positive rate of < 0.1% or 10,000
items and a false positive rate of < 0.0001%).
The number of hash functions required is given by `S * 8 / N * log(2)`.
[[copyright]]
Copyright
~~~~~~~~~
This document is placed in the public domain.

204
selected BIPs/bip-0037.mediawiki
View File

@ -1,204 +0,0 @@
<pre>
BIP: 37
Title: Connection Bloom filtering
Author: Mike Hearn <hearn@google.com>, Matt Corallo <bip@bluematt.me>
Status: Accepted
Type: Standards Track
Created: 2012-10-24
</pre>
==Abstract==
This BIP adds new support to the peer-to-peer protocol that allows peers to reduce the amount of transaction data they are sent. Peers have the option of setting ''filters'' on each connection they make after the version handshake has completed. A filter is defined as a [http://en.wikipedia.org/wiki/Bloom_filter Bloom filter] on data derived from transactions. A Bloom filter is a probabilistic data structure which allows for testing set membership - they can have false positives but not false negatives.
This document will not go into the details of how Bloom filters work and the reader is referred to Wikipedia for an introduction to the topic.
==Motivation==
As Bitcoin grows in usage the amount of bandwidth needed to download blocks and transaction broadcasts increases. Clients implementing ''simplified payment verification'' do not attempt to fully verify the block chain, instead just checking that block headers connect together correctly and trusting that the transactions in a chain of high difficulty are in fact valid. See the Bitcoin paper for more detail on this mode.
Today, [[Simplified_Payment_Verification|SPV]] clients have to download the entire contents of blocks and all broadcast transactions, only to throw away the vast majority of the transactions that are not relevant to their wallets. This slows down their synchronization process, wastes users bandwidth (which on phones is often metered) and increases memory usage. All three problems are triggering real user complaints for the Android "Bitcoin Wallet" app which implements SPV mode. In order to make chain synchronization fast, cheap and able to run on older phones with limited memory we want to have remote peers throw away irrelevant transactions before sending them across the network.
==Design rationale==
The most obvious way to implement the stated goal would be for clients to upload lists of their keys to the remote node. We take a more complex approach for the following reasons:
* Privacy: Because Bloom filters are probabilistic, with the false positive rate chosen by the client, nodes can trade off precision vs bandwidth usage. A node with access to lots of bandwidth may choose to have a high FP rate, meaning the remote peer cannot accurately know which transactions belong to the client and which don't. A node with very little bandwidth may choose to use a very accurate filter meaning that they only get sent transactions actually relevant to their wallet, but remote peers may be able to correlate transactions with IP addresses (and each other).
* Bloom filters are compact and testing membership in them is fast. This results in satisfying performance characteristics with minimal risk of opening up potential for DoS attacks.
==Specification==
===New messages===
We start by adding three new messages to the protocol:
* <code>filterload</code>, which sets the current Bloom filter on the connection
* <code>filteradd</code>, which adds the given data element to the connections current filter without requiring a completely new one to be set
* <code>filterclear</code>, which deletes the current filter and goes back to regular pre-BIP37 usage.
Note that there is no filterremove command because by their nature, Bloom filters are append-only data structures. Once an element is added it cannot be removed again without rebuilding the entire structure from scratch.
The <code>filterload</code> command is defined as follows:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.
|-
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.
|-
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.
|-
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.
|}
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.
The <code>filteradd</code> command is defined as follows:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || data || uint8_t[] || The data element to add to the current filter.
|}
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).
The <code>filterclear</code> command has no arguments at all.
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:
{|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
|-
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)
|-
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)
|-
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)
|}
See below for the format of the partial merkle tree hashes and flags.
Thus, a <code>merkleblock</code> message is a block header, plus a part of a merkle tree which can be used to extract identifying information for transactions that matched the filter and prove that the matching transaction data really did appear in the solved block. Clients can use this data to be sure that the remote node is not feeding them fake transactions that never appeared in a real block, although lying through omission is still possible.
===Extensions to existing messages===
The <code>version</code> command is extended with a new field:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1 byte || fRelay || bool || If false then broadcast transactions will not be announced until a filter{load,add,clear} command is received. If missing or true, no change in protocol behaviour occurs.
|}
SPV clients that wish to use Bloom filtering would normally set fRelay to false in the version message, then set a filter based on their wallet (or a subset of it, if they are overlapping different peers). Being able to opt-out of inv messages until the filter is set prevents a client being flooded with traffic in the brief window of time between finishing version handshaking and setting the filter.
The <code>getdata</code> command is extended to allow a new type in the <code>inv</code> submessage. The type field can now be <code>MSG_FILTERED_BLOCK (== 3)</code> rather than <code>MSG_BLOCK</code>. If no filter has been set on the connection, a request for filtered blocks is ignored. If a filter has been set, a <code>merkleblock</code> message is returned for the requested block hash. In addition, because a <code>merkleblock</code> message contains only a list of transaction hashes, transactions matching the filter should also be sent in separate tx messages after the merkleblock is sent. This avoids a slow roundtrip that would otherwise be required (receive hashes, didn't see some of these transactions yet, ask for them). Note that because there is currently no way to request transactions which are already in a block from a node (aside from requesting the full block), the set of matching transactions that the requesting node hasn't either received or announced with an inv must be sent and any additional transactions which match the filter may also be sent. This allows for clients (such as the reference client) to limit the number of invs it must remember a given node to have announced while still providing nodes with, at a minimum, all the transactions it needs.
===Filter matching algorithm===
The filter can be tested against arbitrary pieces of data, to see if that data was inserted by the client. Therefore the question arises of what pieces of data should be inserted/tested.
To determine if a transaction matches the filter, the following algorithm is used. Once a match is found the algorithm aborts.
# Test the hash of the transaction itself.
# For each output, test each data element of the output script. This means each hash and key in the output script is tested independently. '''Important:''' if an output matches whilst testing a transaction, the node might need to update the filter by inserting the serialized COutPoint structure. See below for more details.
# For each input, test the serialized COutPoint structure.
# For each input, test each data element of the input script (note: input scripts only ever contain data elements).
# Otherwise there is no match.
In this way addresses, keys and script hashes (for P2SH outputs) can all be added to the filter. You can also match against classes of transactions that are marked with well known data elements in either inputs or outputs, for example, to implement various forms of [[Smart property]].
The test for outpoints is there to ensure you can find transactions spending outputs in your wallet, even though you don't know anything about their form. As you can see, once set on a connection the filter is '''not static''' and can change throughout the connections lifetime. This is done to avoid the following race condition:
# A client sets a filter matching a key in their wallet. They then start downloading the block chain. The part of the chain that the client is missing is requested using getblocks.
# The first block is read from disk by the serving peer. It contains TX 1 which sends money to the clients key. It matches the filter and is thus sent to the client.
# The second block is read from disk by the serving peer. It contains TX 2 which spends TX 1. However TX 2 does not contain any of the clients keys and is thus not sent. The client does not know the money they received was already spent.
By updating the bloom filter atomically in step 2 with the discovered outpoint, the filter will match against TX 2 in step 3 and the client will learn about all relevant transactions, despite that there is no pause between the node processing the first and second blocks.
The nFlags field of the filter controls the nodes precise update behaviour and is a bit field.
* <code>BLOOM_UPDATE_NONE (0)</code> means the filter is not adjusted when a match is found.
* <code>BLOOM_UPDATE_ALL (1)</code> means if the filter matches any data element in a scriptPubKey the outpoint is serialized and inserted into the filter.
* <code>BLOOM_UPDATE_P2PUBKEY_ONLY (2)</code> means the outpoint is inserted into the filter only if a data element in the scriptPubKey is matched, and that script is of the standard "pay to pubkey" or "pay to multisig" forms.
These distinctions are useful to avoid too-rapid degradation of the filter due to an increasing false positive rate. We can observe that a wallet which expects to receive only payments of the standard pay-to-address form doesn't need automatic filter updates because any transaction that spends one of its own outputs has a predictable data element in the input (the pubkey that hashes to the address). If a wallet might receive pay-to-address outputs and also pay-to-pubkey or pay-to-multisig outputs then BLOOM_UPDATE_P2PUBKEY_ONLY is appropriate, as it avoids unnecessary expansions of the filter for the most common types of output but still ensures correct behaviour with payments that explicitly specify keys.
Obviously, nFlags == 1 or nFlags == 2 mean that the filter will get dirtier as more of the chain is scanned. Clients should monitor the observed false positive rate and periodically refresh the filter with a clean one.
===Partial Merkle branch format===
A ''Merkle tree'' is a way of arranging a set of items as leaf nodes of tree in which the interior nodes are hashes of the concatenations of their child hashes. The root node is called the ''Merkle root''. Every Bitcoin block contains a Merkle root of the tree formed from the blocks transactions. By providing some elements of the trees interior nodes (called a ''Merkle branch'') a proof is formed that the given transaction was indeed in the block when it was being mined, but the size of the proof is much smaller than the size of the original block.
====Constructing a partial merkle tree object====
* Traverse the merkle tree from the root down, and for each encountered node:
** Check whether this node corresponds to a leaf node (transaction) that is to be included OR any parent thereof:
*** If so, append a '1' bit to the flag bits
*** Otherwise, append a '0' bit.
** Check whether this node is a internal node (non-leaf) AND is the parent of an included leaf node:
*** If so:
**** Descend into its left child node, and process the subtree beneath it entirely (depth-first).
**** If this node has a right child node too, descend into it as well.
*** Otherwise: append this node's hash to the hash list.
====Parsing a partial merkle tree object====
As the partial block message contains the number of transactions in the entire block, the shape of the merkle tree is known before hand. Again, traverse this tree, computing traversed node's hashes along the way:
* Read a bit from the flag bit list:
** If it is '0':
*** Read a hash from the hashes list, and return it as this node's hash.
** If it is '1' and this is a leaf node:
*** Read a hash from the hashes list, store it as a matched txid, and return it as this node's hash.
** If it is '1' and this is an internal node:
*** Descend into its left child tree, and store its computed hash as L.
*** If this node has a right child as well:
**** Descend into its right child, and store its computed hash as R.
**** If L == R, the partial merkle tree object is invalid.
**** Return Hash(L || R).
*** If this node has no right child, return Hash(L || L).
The partial merkle tree object is only valid if:
* All hashes in the hash list were consumed and no more.
* All bits in the flag bits list were consumed (except padding to make it into a full byte), and no more.
* The hash computed for the root node matches the block header's merkle root.
* The block header is valid, and matches its claimed proof of work.
* In two-child nodes, the hash of the left and right branches was never equal.
===Bloom filter format===
A Bloom filter is a bit-field in which bits are set based on feeding the data element to a set of different hash functions. The number of hash functions used is a parameter of the filter. In Bitcoin we use version 3 of the 32-bit Murmur hash function. To get N "different" hash functions we simply initialize the Murmur algorithm with the following formula:
<code>nHashNum * 0xFBA4C795 + nTweak</code>
i.e. if the filter is initialized with 4 hash functions and a tweak of 0x00000005, when the second function (index 1) is needed h1 would be equal to 4221880218.
When loading a filter with the <code>filterload</code> command, there are two parameters that can be chosen. One is the size of the filter in bytes. The other is the number of hash functions to use. To select the parameters you can use the following formulas:
Let N be the number of elements you wish to insert into the set and P be the probability of a false positive, where 1.0 is "match everything" and zero is unachievable.
The size S of the filter in bytes is given by <code>(-1 / pow(log(2), 2) * N * log(P)) / 8</code>. Of course you must ensure it does not go over the maximum size (36,000: selected as it represents a filter of 20,000 items with false positive rate of < 0.1% or 10,000 items and a false positive rate of < 0.0001%).
The number of hash functions required is given by <code>S * 8 / N * log(2)</code>.
==Copyright==
This document is placed in the public domain.

688
selected BIPs/bip-0038.asciidoc
View File

@ -1,688 +0,0 @@
----------------------------------------------------------------------------------------------------------------------------------
BIP: 38
Title: Passphrase-protected private key
Authors: Mike Caldwell
Aaron Voisine <voisine@gmail.com>
Status: Draft (Some confusion applies: The announcements for this never made it to the list, so it hasn't had public discussion)
Type: Standards Track
Created: 2012-11-20
----------------------------------------------------------------------------------------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
A method is proposed for encrypting and encoding a passphrase-protected
Bitcoin private key record in the form of a 58-character
Base58Check-encoded printable string. Encrypted private key records are
intended for use on paper wallets and physical Bitcoins. Each record
string contains all the information needed to reconstitute the private
key except for a passphrase, and the methodology uses salting and
_scrypt_ to resist brute-force attacks.
The method provides two encoding methodologies - one permitting any
known private key to be encrypted with any passphrase, and another
permitting a shared private key generation scheme where the party
generating the final key string and its associated Bitcoin address (such
as a physical bitcoin manufacturer) knows only a string derived from the
original passphrase, and where the original passphrase is needed in
order to actually redeem funds sent to the associated Bitcoin address.
A 32-bit hash of the resulting Bitcoin address is encoded in plaintext
within each encrypted key, so it can be correlated to a Bitcoin address
with reasonable probability by someone not knowing the passphrase. The
complete Bitcoin address can be derived through successful decryption of
the key record.
[[motivation]]
Motivation
~~~~~~~~~~
The motivation to make this proposal stems from observations of the way
physical bitcoins and paper wallets are used.
An issuer of physical bitcoins must be trustworthy and trusted. Even if
trustworthy, users are rightful to be skeptical about a third party with
theoretical access to take their funds. A physical bitcoin that cannot
be compromised by its issuer is always more intrinsically valuable than
one that can.
A two-factor physical bitcoin solution is highly useful to individuals
and organizations wishing to securely own bitcoins without any risk of
electronic theft and without the responsibility of climbing the
technological learning curve necessary to produce such an environment
themselves. Two-factor physical bitcoins allow a secure storage solution
to be put in a box and sold on the open market, greatly enlarging the
number of people who are able to securely store bitcoins.
Existing methodologies for creating two-factor physical bitcoins are
limited and cumbersome. At the time of this proposal, a user could
create their own private key, submit the public key to the physical
bitcoin issuer, and then receive a physical bitcoin that must be kept
together with some sort of record of the user-generated private key, and
finally, must be redeemed through a tool. The fact that the physical
bitcoin must be kept together with a user-produced private key negates
much of the benefit of the physical bitcoin - the user may as well just
print and maintain a private key.
A standardized password-protected private key format makes acquiring and
redeeming two-factor physical bitcoins simpler for the user. Instead of
maintaining a private key that cannot be memorized, the user may choose
a passphrase of their choice. The passphrase may be much shorter than
the length of a typical private key, short enough that they could use a
label or engraver to permanently commit their passphrase to their
physical Bitcoin piece once they have received it. By adopting a
standard way to encrypt a private key, we maximize the possibility that
they'll be able to redeem their funds in the venue of their choice,
rather than relying on an executable redemption tool they may not wish
to download.
Password and passphrase-protected private keys enable new practical use
cases for sending bitcoins from person to person. Someone wanting to
send bitcoins through postal mail could send a password-protected paper
wallet and give the recipient the passphrase over the phone or e-mail,
making the transfer safe from interception of either channel. A user of
paper wallets or Bitcoin banknote-style vouchers ("cash") could carry
funded encrypted private keys while leaving a copy at home as an element
of protection against accidental loss or theft. A user of paper wallets
who leaves bitcoins in a bank vault or safety deposit box could keep the
password at home or share it with trusted associates as protection
against someone at the bank gaining access to the paper wallets and
spending from them. The foreseeable and unforeseeable use cases for
password-protected private keys are numerous.
[[copyright]]
Copyright
~~~~~~~~~
This proposal is hereby placed in the public domain.
[[rationale]]
Rationale
~~~~~~~~~
::
_*User story:* As a Bitcoin user who uses paper wallets, I would like
the ability to add encryption, so that my Bitcoin paper storage can be
two factor: something I have plus something I know._
+
_*User story:* As a Bitcoin user who would like to pay a person or a
company with a private key, I do not want to worry that any part of
the communication path may result in the interception of the key and
theft of my funds. I would prefer to offer an encrypted private key,
and then follow it up with the password using a different
communication channel (e.g. a phone call or SMS)._
+
_*User story:* (EC-multiplied keys) As a user of physical bitcoins, I
would like a third party to be able to create password-protected
Bitcoin private keys for me, without them knowing the password, so I
can benefit from the physical bitcoin without the issuer having access
to the private key. I would like to be able to choose a password whose
minimum length and required format does not preclude me from
memorizing it or engraving it on my physical bitcoin, without exposing
me to an undue risk of password cracking and/or theft by the
manufacturer of the item._
+
'*'User story:* (EC multiplied keys) As a user of paper wallets, I
would like the ability to generate a large number of Bitcoin addresses
protected by the same password, while enjoying a high degree of
security (highly expensive scrypt parameters), but without having to
incur the scrypt delay for each address I generate.
[[specification]]
Specification
~~~~~~~~~~~~~
This proposal makes use of the following functions and definitions:
* *AES256Encrypt, AES256Decrypt*: the simple form of the well-known AES
block cipher without consideration for initialization vectors or block
chaining. Each of these functions takes a 256-bit key and 16 bytes of
input, and deterministically yields 16 bytes of output.
* *SHA256*, a well-known hashing algorithm that takes an arbitrary
number of bytes as input and deterministically yields a 32-byte hash.
* *scrypt*: A well-known key derivation algorithm. It takes the
following parameters: (string) password, (string) salt, (int) n, (int)
r, (int) p, (int) length, and deterministically yields an array of bytes
whose length is equal to the length parameter.
* *ECMultiply*: Multiplication of an elliptic curve point by a scalar
integer with respect to the secp256k1 elliptic curve.
* *G, N*: Constants defined as part of the secp256k1 elliptic curve. G
is an elliptic curve point, and N is a large positive integer.
* *Base58Check*: a method for encoding arrays of bytes using 58
alphanumeric characters commonly used in the Bitcoin ecosystem.
[[prefix]]
Prefix
^^^^^^
It is proposed that the resulting Base58Check-encoded string start with
a '6'. The number '6' is intended to represent, from the perspective of
the user, "a private key that needs something else to be usable" - an
umbrella definition that could be understood in the future to include
keys participating in multisig transactions, and was chosen with
deference to the existing prefix '5' most commonly observed in
link:Wallet Import Format[Wallet Import Format] which denotes an
unencrypted private key.
It is proposed that the second character ought to give a hint as to what
is needed as a second factor, and for an encrypted key requiring a
passphrase, the uppercase letter P is proposed.
To keep the size of the encrypted key down, no initialization vectors
(IVs) are used in the AES encryption. Rather, suitable values for
IV-like use are derived using scrypt from the passphrase and from using
a 32-bit hash of the resulting Bitcoin address as salt.
[[proposed-specification]]
Proposed specification
^^^^^^^^^^^^^^^^^^^^^^
* Object identifier prefix: 0x0142 (non-EC-multiplied) or 0x0143
(EC-multiplied). These are constant bytes that appear at the beginning
of the Base58Check-encoded record, and their presence causes the
resulting string to have a predictable prefix.
* How the user sees it: 58 characters always starting with '6P'
** Visual cues are present in the third character for visually
identifying the EC-multiply and compress flag.
* Count of payload bytes (beyond prefix): 37
** 1 byte (_flagbyte_):
*** the most significant two bits are set as follows to preserve the
visibility of the compression flag in the prefix, as well as to keep the
payload within the range of allowable values that keep the "6P" prefix
intact. For non-EC-multiplied keys, the bits are 11. For EC-multiplied
keys, the bits are 00.
*** the bit with value 0x20 when set indicates the key should be
converted to a bitcoin address using the compressed public key format.
*** the bits with values 0x10 and 0x08 are reserved for a future
specification that contemplates using multisig as a way to combine the
factors such that parties in possession of the separate factors can
independently sign a proposed transaction without requiring that any
party possess both factors. These bits must be 0 to comply with this
version of the specification.
*** the bit with value 0x04 indicates whether a lot and sequence number
are encoded into the first factor, and activates special behavior for
including them in the decryption process. This applies to EC-multiplied
keys only. Must be 0 for non-EC-multiplied keys.
*** remaining bits are reserved for future use and must all be 0 to
comply with this version of the specification.
** 4 bytes: SHA256(SHA256(expected_bitcoin_address))[0...3], used both
for typo checking and as salt
** 16 bytes: Contents depend on whether EC multiplication is used.
** 16 bytes: lasthalf: An AES-encrypted key material record (contents
depend on whether EC multiplication is used)
* Range in base58check encoding for non-EC-multiplied keys without
compression (prefix 6PR):
** Minimum value:
6PRHv1jg1ytiE4kT2QtrUz8gEjMQghZDWg1FuxjdYDzjUkcJeGdFj9q9Vi (based on 01
42 C0 plus thirty-six 00's)
** Maximum value:
6PRWdmoT1ZursVcr5NiD14p5bHrKVGPG7yeEoEeRb8FVaqYSHnZTLEbYsU (based on 01
42 C0 plus thirty-six FF's)
* Range in base58check encoding for non-EC-multiplied keys with
compression (prefix 6PY):
** Minimum value:
6PYJxKpVnkXUsnZAfD2B5ZsZafJYNp4ezQQeCjs39494qUUXLnXijLx6LG (based on 01
42 E0 plus thirty-six 00's)
** Maximum value:
6PYXg5tGnLYdXDRZiAqXbeYxwDoTBNthbi3d61mqBxPpwZQezJTvQHsCnk (based on 01
42 E0 plus thirty-six FF's)
* Range in base58check encoding for EC-multiplied keys without
compression (prefix 6Pf):
** Minimum value:
6PfKzduKZXAFXWMtJ19Vg9cSvbFg4va6U8p2VWzSjtHQCCLk3JSBpUvfpf (based on 01
43 00 plus thirty-six 00's)
** Maximum value:
6PfYiPy6Z7BQAwEHLxxrCEHrH9kasVQ95ST1NnuEnnYAJHGsgpNPQ9dTHc (based on 01
43 00 plus thirty-six FF's)
* Range in base58check encoding for non-EC-multiplied keys with
compression (prefix 6Pn):
** Minimum value:
6PnM2wz9LHo2BEAbvoGpGjMLGXCom35XwsDQnJ7rLiRjYvCxjpLenmoBsR (based on 01
43 20 plus thirty-six 00's)
** Maximum value:
6PnZki3vKspApf2zym6Anp2jd5hiZbuaZArPfa2ePcgVf196PLGrQNyVUh (based on 01
43 20 plus thirty-six FF's)
[[encryption-when-ec-multiply-flag-is-not-used]]
Encryption when EC multiply flag is not used
++++++++++++++++++++++++++++++++++++++++++++
Encrypting a private key without the EC multiplication offers the
advantage that any known private key can be encrypted. The party
performing the encryption must know the passphrase.
Encryption steps:
1. Compute the Bitcoin address (ASCII), and take the first four bytes
of SHA256(SHA256()) of it. Let's call this "addresshash".
2. Derive a key from the passphrase using scrypt
* Parameters: _passphrase_ is the passphrase itself encoded in UTF-8.
salt is _addresshash_ from the earlier step, n=16384, r=8, p=8,
length=64 (n, r, p are provisional and subject to consensus)
* Let's split the resulting 64 bytes in half, and call them
_derivedhalf1_ and _derivedhalf2_.
3. Do AES256Encrypt(bitcoinprivkey[0...15] xor derivedhalf1[0...15],
derivedhalf2), call the 16-byte result _encryptedhalf1_
4. Do AES256Encrypt(bitcoinprivkey[16...31] xor derivedhalf1[16...31],
derivedhalf2), call the 16-byte result _encryptedhalf2_
The encrypted private key is the Base58Check-encoded concatenation of
the following, which totals 39 bytes without Base58 checksum:
* 0x01 0x42 + _flagbyte_ + _salt_ + _encryptedhalf1_ + _encryptedhalf2_
Decryption steps:
1. Collect encrypted private key and passphrase from user.
2. Derive _derivedhalf1_ and _derivedhalf2_ by passing the passphrase
and _addresshash_ into scrypt function.
3. Decrypt _encryptedhalf1_ and _encryptedhalf2_ using AES256Decrypt,
merge them to form the encrypted private key.
4. Convert that private key into a Bitcoin address, honoring the
compression preference specified in _flagbyte_ of the encrypted key
record.
5. Hash the Bitcoin address, and verify that _addresshash_ from the
encrypted private key record matches the hash. If not, report that the
passphrase entry was incorrect.
[[encryption-when-ec-multiply-mode-is-used]]
Encryption when EC multiply mode is used
++++++++++++++++++++++++++++++++++++++++
Encrypting a private key with EC multiplication offers the ability for
someone to generate encrypted keys knowing only an EC point derived from
the original passphrase and some salt generated by the passphrase's
owner, and without knowing the passphrase itself. Only the person who
knows the original passphrase can decrypt the private key. A code known
as an _intermediate code_ conveys the information needed to generate
such a key without knowledge of the passphrase.
This methodology does not offer the ability to encrypt a known private
key - this means that the process of creating encrypted keys is also the
process of generating new addresses. On the other hand, this serves a
security benefit for someone possessing an address generated this way:
if the address can be recreated by decrypting its private key with a
passphrase, and it's a strong passphrase one can be certain only he
knows himself, then he can safely conclude that nobody could know the
private key to that address.
The person who knows the passphrase and who is the intended beneficiary
of the private keys is called the _owner_. He will generate one or more
"intermediate codes", which are the first factor of a two-factor
redemption system, and will give them to someone else we'll call
_printer_, who generates a key pair with an intermediate code can know
the address and encrypted private key, but cannot decrypt the private
key without the original passphrase.
An intermediate code should, but is not required to, embed a printable
"lot" and "sequence" number for the benefit of the user. The proposal
forces these lot and sequence numbers to be included in any valid
private keys generated from them. An owner who has requested multiple
private keys to be generated for him will be advised by applications to
ensure that each private key has a unique lot and sequence number
consistent with the intermediate codes he generated. These mainly help
protect _owner_ from potential mistakes and/or attacks that could be
made by _printer_.
The "lot" and "sequence" number are combined into a single 32 bit
number. 20 bits are used for the lot number and 12 bits are used for the
sequence number, such that the lot number can be any decimal number
between 0 and 1048575, and the sequence number can be any decimal number
between 0 and 4095. For programs that generate batches of intermediate
codes for an _owner_, it is recommended that lot numbers be chosen at
random within the range 100000-999999 and that sequence numbers are
assigned starting with 1.
Steps performed by _owner_ to generate a single intermediate code, if
lot and sequence numbers are being included:
1. Generate 4 random bytes, call them _ownersalt_.
2. Encode the lot and sequence numbers as a 4 byte quantity
(big-endian): lotnumber * 4096 + sequencenumber. Call these four bytes
_lotsequence_.
3. Concatenate _ownersalt_ + _lotsequence_ and call this
_ownerentropy_.
4. Derive a key from the passphrase using scrypt
* Parameters: _passphrase_ is the passphrase itself encoded in UTF-8.
salt is _ownersalt_. n=16384, r=8, p=8, length=32.
* Call the resulting 32 bytes _prefactor_.
* Take SHA256(SHA256(_prefactor_ + _ownerentropy_)) and call this
_passfactor_.
5. Compute the elliptic curve point G * _passfactor_, and convert the
result to compressed notation (33 bytes). Call this _passpoint_.
Compressed notation is used for this purpose regardless of whether the
intent is to create Bitcoin addresses with or without compressed public
keys.
6. Convey _ownersalt_ and _passpoint_ to the party generating the keys,
along with a checksum to ensure integrity.
* The following Base58Check-encoded format is recommended for this
purpose: magic bytes "2C E9 B3 E1 FF 39 E2 51" followed by
_ownerentropy_, and then _passpoint_. The resulting string will start
with the word "passphrase" due to the constant bytes, will be 72
characters in length, and encodes 49 bytes (8 bytes constant + 8 bytes
_ownerentropy_ + 33 bytes _passpoint_). The checksum is handled in the
Base58Check encoding. The resulting string is called
_intermediate_passphrase_string_.
If lot and sequence numbers are not being included, then follow the same
procedure with the following changes:
* _ownersalt_ is 8 random bytes instead of 4, and _lotsequence_ is
omitted. _ownerentropy_ becomes an alias for _ownersalt_.
* The SHA256 conversion of _prefactor_ to _passfactor_ is omitted.
Instead, the output of scrypt is used directly as _passfactor_.
* The magic bytes are "2C E9 B3 E1 FF 39 E2 53" instead (the last byte
is 0x53 instead of 0x51).
Steps to create new encrypted private keys given
_intermediate_passphrase_string_ from _owner_ (so we have
_ownerentropy_, and _passpoint_, but we do not have _passfactor_ or the
passphrase):
1. Set _flagbyte_.
* Turn on bit 0x20 if the Bitcoin address will be formed by hashing the
compressed public key (optional, saves space, but many Bitcoin
implementations aren't compatible with it)
* Turn on bit 0x04 if _ownerentropy_ contains a value for _lotsequence_.
(While it has no effect on the keypair generation process, the
decryption process needs this flag to know how to process
_ownerentropy_)
2. Generate 24 random bytes, call this _seedb_. Take
SHA256(SHA256(_seedb_)) to yield 32 bytes, call this _factorb_.
3. ECMultiply _passpoint_ by _factorb_. Use the resulting EC point as a
public key and hash it into a Bitcoin address using either compressed or
uncompressed public key methodology (specify which methodology is used
inside _flagbyte_). This is the generated Bitcoin address, call it
_generatedaddress_.
4. Take the first four bytes of SHA256(SHA256(_generatedaddress_)) and
call it _addresshash_.
5. Now we will encrypt _seedb_. Derive a second key from _passpoint_
using scrypt
* Parameters: _passphrase_ is _passpoint_ provided from the first party
(expressed in binary as 33 bytes). _salt_ is _addresshash_ +
_ownerentropy_, n=1024, r=1, p=1, length=64. The "+" operator is
concatenation.
* Split the result into two 32-byte halves and call them _derivedhalf1_
and _derivedhalf2_.
6. Do AES256Encrypt(seedb[0...15] xor derivedhalf1[0...15],
derivedhalf2), call the 16-byte result _encryptedpart1_
7. Do AES256Encrypt((encryptedpart1[8...15] + seedb[16...23]) xor
derivedhalf1[16...31], derivedhalf2), call the 16-byte result
_encryptedpart2_. The "+" operator is concatenation.
The encrypted private key is the Base58Check-encoded concatenation of
the following, which totals 39 bytes without Base58 checksum:
* 0x01 0x43 + _flagbyte_ + _addresshash_ + _ownerentropy_ +
_encryptedpart1_[0...7] + _encryptedpart2_
[[confirmation-code]]
Confirmation code
The party generating the Bitcoin address has the option to return a
_confirmation code_ back to _owner_ which allows _owner_ to
independently verify that he has been given a Bitcoin address that
actually depends on his passphrase, and to confirm the lot and sequence
numbers (if applicable). This protects _owner_ from being given a
Bitcoin address by the second party that is unrelated to the key
derivation and possibly spendable by the second party. If a Bitcoin
address given to _owner_ can be successfully regenerated through the
confirmation process, _owner_ can be reasonably assured that any
spending without the passphrase is infeasible. This confirmation code is
75 characters starting with "cfrm38".
To generate it, we need _flagbyte_, _ownerentropy_, _factorb_,
_derivedhalf1_ and _derivedhalf2_ from the original encryption
operation.
1. ECMultiply _factorb_ by G, call the result _pointb_. The result is
33 bytes.
2. The first byte is 0x02 or 0x03. XOR it by (derivedhalf2[31] & 0x01),
call the resulting byte _pointbprefix_.
3. Do AES256Encrypt(pointb[1...16] xor derivedhalf1[0...15],
derivedhalf2) and call the result _pointbx1_.
4. Do AES256Encrypt(pointb[17...32] xor derivedhalf1[16...31],
derivedhalf2) and call the result _pointbx2_.
5. Concatenate _pointbprefix_ + _pointbx1_ + _pointbx2_ (total 33
bytes) and call the result _encryptedpointb_.
The result is a Base58Check-encoded concatenation of the following:
* 0x64 0x3B 0xF6 0xA8 0x9A + _flagbyte_ + _addresshash_ + _ownerentropy_
+ _encryptedpointb_
A confirmation tool, given a passphrase and a confirmation code, can
recalculate the address, verify the address hash, and then assert the
following: "It is confirmed that Bitcoin address _address_ depends on
this passphrase". If applicable: "The lot number is _lotnumber_ and the
sequence number is _sequencenumber_."
To recalculate the address:
1. Derive _passfactor_ using scrypt with _ownerentropy_ and the user's
passphrase and use it to recompute _passpoint_
2. Derive decryption key for _pointb_ using scrypt with _passpoint_,
_addresshash_, and _ownerentropy_
3. Decrypt _encryptedpointb_ to yield _pointb_
4. ECMultiply _pointb_ by _passfactor_. Use the resulting EC point as a
public key and hash it into _address_ using either compressed or
uncompressed public key methodology as specifid in _flagbyte_.
[[decryption]]
Decryption
1. Collect encrypted private key and passphrase from user.
2. Derive _passfactor_ using scrypt with _ownerentropy_ and the user's
passphrase and use it to recompute _passpoint_
3. Derive decryption key for _seedb_ using scrypt with _passpoint_,
_addresshash_, and _ownersalt_
4. Decrypt _encryptedpart2_ using AES256Decrypt to yield the last 8
bytes of _seedb_ and the last 8 bytes of _encryptedpart1_.
5. Decrypt _encryptedpart1_ to yield the remainder of _seedb_.
6. Use _seedb_ to compute _factorb_.
7. Multiply _passfactor_ by _factorb_ mod N to yield the private key
associated with _generatedaddress_.
8. Convert that private key into a Bitcoin address, honoring the
compression preference specified in the encrypted key.
9. Hash the Bitcoin address, and verify that _addresshash_ from the
encrypted private key record matches the hash. If not, report that the
passphrase entry was incorrect.
[[backwards-compatibility]]
Backwards compatibility
~~~~~~~~~~~~~~~~~~~~~~~
Backwards compatibility is minimally applicable since this is a new
standard that at most extends link:Wallet Import Format[Wallet Import
Format]. It is assumed that an entry point for private key data may also
accept existing formats of private keys (such as hexadecimal and
link:Wallet Import Format[Wallet Import Format]); this draft uses a key
format that cannot be mistaken for any existing one and preserves
auto-detection capabilities.
[[suggestions-for-implementers-of-proposal-with-alt-chains]]
Suggestions for implementers of proposal with alt-chains
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If this proposal is accepted into alt-chains, it is requested that the
unused flag bytes not be used for denoting that the key belongs to an
alt-chain.
Alt-chain implementers should exploit the address hash for this purpose.
Since each operation in this proposal involves hashing a text
representation of a coin address which (for Bitcoin) includes the
leading '1', an alt-chain can easily be denoted simply by using the
alt-chain's preferred format for representing an address. Alt-chain
implementers may also change the prefix such that encrypted addresses do
not start with "6P".
[[discussion-item-scrypt-parameters]]
Discussion item: scrypt parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This proposal leaves the scrypt parameters up in the air. The following
items are proposed for consideration:
The main goal of scrypt is to reduce the feasibility of brute force
attacks. It must be assumed that an attacker will be able to use an
efficient implementation of scrypt. The parameters should force a highly
efficient implementation of scrypt to wait a decent amount of time to
slow attacks.
On the other hand, an unavoidably likely place where scrypt will be
implemented is using slow interpreted languages such as javascript. What
might take milliseconds on an efficient scrypt implementation may take
seconds in javascript.
It is believed, however, that someone using a javascript implementation
is probably dealing with codes by hand, one at a time, rather than
generating or processing large batches of codes. Thus, a wait time of
several seconds is acceptable to a user.
A private key redemption process that forces a server to consume several
seconds of CPU time would discourage implementation by the server owner,
because they would be opening up a denial of service avenue by inviting
users to make numerous attempts to invoke the redemption process.
However, it's also feasible for the server owner to implement his
redemption process in such a way that the decryption is done by the
user's browser, offloading the task from his own server (and providing
another reason why the chosen scrypt parameters should be tolerant of
javascript-based decryptors).
The preliminary values of 16384, 8, and 8 are hoped to offer the
following properties:
* Encryption/decryption in javascript requiring several seconds per
operation
* Use of the parallelization parameter provides a modest opportunity for
speedups in environments where concurrent threading is available - such
environments would be selected for processes that must handle bulk
quantities of encryption/decryption operations. Estimated time for an
operation is in the tens or hundreds of milliseconds.
[[reference-implementation]]
Reference implementation
~~~~~~~~~~~~~~~~~~~~~~~~
Added to alpha version of Casascius Bitcoin Address Utility for Windows
available at:
* via https: https://casascius.com/btcaddress-alpha.zip
* at github: https://github.com/casascius/Bitcoin-Address-Utility
Click "Tools" then "PPEC Keygen" (provisional name)
[[test-vectors]]
Test vectors
~~~~~~~~~~~~
[[no-compression-no-ec-multiply]]
No compression, no EC multiply
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Test 1:
* Passphrase: TestingOneTwoThree
* Encrypted: 6PRVWUbkzzsbcVac2qwfssoUJAN1Xhrg6bNk8J7Nzm5H7kxEbn2Nh2ZoGg
* Unencrypted (WIF): 5KN7MzqK5wt2TP1fQCYyHBtDrXdJuXbUzm4A9rKAteGu3Qi5CVR
* Unencrypted (hex):
CBF4B9F70470856BB4F40F80B87EDB90865997FFEE6DF315AB166D713AF433A5
Test 2:
* Passphrase: Satoshi
* Encrypted: 6PRNFFkZc2NZ6dJqFfhRoFNMR9Lnyj7dYGrzdgXXVMXcxoKTePPX1dWByq
* Unencrypted (WIF): 5HtasZ6ofTHP6HCwTqTkLDuLQisYPah7aUnSKfC7h4hMUVw2gi5
* Unencrypted (hex):
09C2686880095B1A4C249EE3AC4EEA8A014F11E6F986D0B5025AC1F39AFBD9AE
[[compression-no-ec-multiply]]
Compression, no EC multiply
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Test 1:
* Passphrase: TestingOneTwoThree
* Encrypted: 6PYNKZ1EAgYgmQfmNVamxyXVWHzK5s6DGhwP4J5o44cvXdoY7sRzhtpUeo
* Unencrypted (WIF):
L44B5gGEpqEDRS9vVPz7QT35jcBG2r3CZwSwQ4fCewXAhAhqGVpP
* Unencrypted (hex):
CBF4B9F70470856BB4F40F80B87EDB90865997FFEE6DF315AB166D713AF433A5
Test 2:
* Passphrase: Satoshi
* Encrypted: 6PYLtMnXvfG3oJde97zRyLYFZCYizPU5T3LwgdYJz1fRhh16bU7u6PPmY7
* Unencrypted (WIF):
KwYgW8gcxj1JWJXhPSu4Fqwzfhp5Yfi42mdYmMa4XqK7NJxXUSK7
* Unencrypted (hex):
09C2686880095B1A4C249EE3AC4EEA8A014F11E6F986D0B5025AC1F39AFBD9AE
[[ec-multiply-no-compression-no-lotsequence-numbers]]
EC multiply, no compression, no lot/sequence numbers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Test 1:
* Passphrase: TestingOneTwoThree
* Passphrase code:
passphrasepxFy57B9v8HtUsszJYKReoNDV6VHjUSGt8EVJmux9n1J3Ltf1gRxyDGXqnf9qm
* Encrypted key:
6PfQu77ygVyJLZjfvMLyhLMQbYnu5uguoJJ4kMCLqWwPEdfpwANVS76gTX
* Bitcoin address: 1PE6TQi6HTVNz5DLwB1LcpMBALubfuN2z2
* Unencrypted private key (WIF):
5K4caxezwjGCGfnoPTZ8tMcJBLB7Jvyjv4xxeacadhq8nLisLR2
* Unencrypted private key (hex):
A43A940577F4E97F5C4D39EB14FF083A98187C64EA7C99EF7CE460833959A519
Test 2:
* Passphrase: Satoshi
* Passphrase code:
passphraseoRDGAXTWzbp72eVbtUDdn1rwpgPUGjNZEc6CGBo8i5EC1FPW8wcnLdq4ThKzAS
* Encrypted key:
6PfLGnQs6VZnrNpmVKfjotbnQuaJK4KZoPFrAjx1JMJUa1Ft8gnf5WxfKd
* Bitcoin address: 1CqzrtZC6mXSAhoxtFwVjz8LtwLJjDYU3V
* Unencrypted private key (WIF):
5KJ51SgxWaAYR13zd9ReMhJpwrcX47xTJh2D3fGPG9CM8vkv5sH
* Unencrypted private key (hex):
C2C8036DF268F498099350718C4A3EF3984D2BE84618C2650F5171DCC5EB660A
[[ec-multiply-no-compression-lotsequence-numbers]]
EC multiply, no compression, lot/sequence numbers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Test 1:
* Passphrase: MOLON LABE
* Passphrase code:
passphraseaB8feaLQDENqCgr4gKZpmf4VoaT6qdjJNJiv7fsKvjqavcJxvuR1hy25aTu5sX
* Encrypted key:
6PgNBNNzDkKdhkT6uJntUXwwzQV8Rr2tZcbkDcuC9DZRsS6AtHts4Ypo1j
* Bitcoin address: 1Jscj8ALrYu2y9TD8NrpvDBugPedmbj4Yh
* Unencrypted private key (WIF):
5JLdxTtcTHcfYcmJsNVy1v2PMDx432JPoYcBTVVRHpPaxUrdtf8
* Unencrypted private key (hex):
44EA95AFBF138356A05EA32110DFD627232D0F2991AD221187BE356F19FA8190
* Confirmation code:
cfrm38V8aXBn7JWA1ESmFMUn6erxeBGZGAxJPY4e36S9QWkzZKtaVqLNMgnifETYw7BPwWC9aPD
* Lot/Sequence: 263183/1
Test 2:
* Passphrase (all letters are Greek - test UTF-8 compatibility with
this): ΜΟΛΩΝ ΛΑΒΕ
* Passphrase code:
passphrased3z9rQJHSyBkNBwTRPkUGNVEVrUAcfAXDyRU1V28ie6hNFbqDwbFBvsTK7yWVK
* Encrypted private key:
6PgGWtx25kUg8QWvwuJAgorN6k9FbE25rv5dMRwu5SKMnfpfVe5mar2ngH
* Bitcoin address: 1Lurmih3KruL4xDB5FmHof38yawNtP9oGf
* Unencrypted private key (WIF):
5KMKKuUmAkiNbA3DazMQiLfDq47qs8MAEThm4yL8R2PhV1ov33D
* Unencrypted private key (hex):
CA2759AA4ADB0F96C414F36ABEB8DB59342985BE9FA50FAAC228C8E7D90E3006
* Confirmation code:
cfrm38V8G4qq2ywYEFfWLD5Cc6msj9UwsG2Mj4Z6QdGJAFQpdatZLavkgRd1i4iBMdRngDqDs51
* Lot/Sequence: 806938/1

282
selected BIPs/bip-0038.mediawiki
View File

@ -1,282 +0,0 @@
<pre>
BIP: 38
Title: Passphrase-protected private key
Authors: Mike Caldwell
Aaron Voisine <voisine@gmail.com>
Status: Draft (Some confusion applies: The announcements for this never made it to the list, so it hasn't had public discussion)
Type: Standards Track
Created: 2012-11-20
</pre>
==Abstract==
A method is proposed for encrypting and encoding a passphrase-protected Bitcoin private key record in the form of a 58-character Base58Check-encoded printable string. Encrypted private key records are intended for use on paper wallets and physical Bitcoins. Each record string contains all the information needed to reconstitute the private key except for a passphrase, and the methodology uses salting and ''scrypt'' to resist brute-force attacks.
The method provides two encoding methodologies - one permitting any known private key to be encrypted with any passphrase, and another permitting a shared private key generation scheme where the party generating the final key string and its associated Bitcoin address (such as a physical bitcoin manufacturer) knows only a string derived from the original passphrase, and where the original passphrase is needed in order to actually redeem funds sent to the associated Bitcoin address.
A 32-bit hash of the resulting Bitcoin address is encoded in plaintext within each encrypted key, so it can be correlated to a Bitcoin address with reasonable probability by someone not knowing the passphrase. The complete Bitcoin address can be derived through successful decryption of the key record.
==Motivation==
The motivation to make this proposal stems from observations of the way physical bitcoins and paper wallets are used.
An issuer of physical bitcoins must be trustworthy and trusted. Even if trustworthy, users are rightful to be skeptical about a third party with theoretical access to take their funds. A physical bitcoin that cannot be compromised by its issuer is always more intrinsically valuable than one that can.
A two-factor physical bitcoin solution is highly useful to individuals and organizations wishing to securely own bitcoins without any risk of electronic theft and without the responsibility of climbing the technological learning curve necessary to produce such an environment themselves. Two-factor physical bitcoins allow a secure storage solution to be put in a box and sold on the open market, greatly enlarging the number of people who are able to securely store bitcoins.
Existing methodologies for creating two-factor physical bitcoins are limited and cumbersome. At the time of this proposal, a user could create their own private key, submit the public key to the physical bitcoin issuer, and then receive a physical bitcoin that must be kept together with some sort of record of the user-generated private key, and finally, must be redeemed through a tool. The fact that the physical bitcoin must be kept together with a user-produced private key negates much of the benefit of the physical bitcoin - the user may as well just print and maintain a private key.
A standardized password-protected private key format makes acquiring and redeeming two-factor physical bitcoins simpler for the user. Instead of maintaining a private key that cannot be memorized, the user may choose a passphrase of their choice. The passphrase may be much shorter than the length of a typical private key, short enough that they could use a label or engraver to permanently commit their passphrase to their physical Bitcoin piece once they have received it. By adopting a standard way to encrypt a private key, we maximize the possibility that they'll be able to redeem their funds in the venue of their choice, rather than relying on an executable redemption tool they may not wish to download.
Password and passphrase-protected private keys enable new practical use cases for sending bitcoins from person to person. Someone wanting to send bitcoins through postal mail could send a password-protected paper wallet and give the recipient the passphrase over the phone or e-mail, making the transfer safe from interception of either channel. A user of paper wallets or Bitcoin banknote-style vouchers ("cash") could carry funded encrypted private keys while leaving a copy at home as an element of protection against accidental loss or theft. A user of paper wallets who leaves bitcoins in a bank vault or safety deposit box could keep the password at home or share it with trusted associates as protection against someone at the bank gaining access to the paper wallets and spending from them. The foreseeable and unforeseeable use cases for password-protected private keys are numerous.
==Copyright==
This proposal is hereby placed in the public domain.
==Rationale==
:'''''User story:''' As a Bitcoin user who uses paper wallets, I would like the ability to add encryption, so that my Bitcoin paper storage can be two factor: something I have plus something I know.''
:'''''User story:''' As a Bitcoin user who would like to pay a person or a company with a private key, I do not want to worry that any part of the communication path may result in the interception of the key and theft of my funds. I would prefer to offer an encrypted private key, and then follow it up with the password using a different communication channel (e.g. a phone call or SMS).''
:'''''User story:''' (EC-multiplied keys) As a user of physical bitcoins, I would like a third party to be able to create password-protected Bitcoin private keys for me, without them knowing the password, so I can benefit from the physical bitcoin without the issuer having access to the private key. I would like to be able to choose a password whose minimum length and required format does not preclude me from memorizing it or engraving it on my physical bitcoin, without exposing me to an undue risk of password cracking and/or theft by the manufacturer of the item.''
:'''''User story:''' (EC multiplied keys) As a user of paper wallets, I would like the ability to generate a large number of Bitcoin addresses protected by the same password, while enjoying a high degree of security (highly expensive scrypt parameters), but without having to incur the scrypt delay for each address I generate.
==Specification==
This proposal makes use of the following functions and definitions:
*'''AES256Encrypt, AES256Decrypt''': the simple form of the well-known AES block cipher without consideration for initialization vectors or block chaining. Each of these functions takes a 256-bit key and 16 bytes of input, and deterministically yields 16 bytes of output.
*'''SHA256''', a well-known hashing algorithm that takes an arbitrary number of bytes as input and deterministically yields a 32-byte hash.
*'''scrypt''': A well-known key derivation algorithm. It takes the following parameters: (string) password, (string) salt, (int) n, (int) r, (int) p, (int) length, and deterministically yields an array of bytes whose length is equal to the length parameter.
*'''ECMultiply''': Multiplication of an elliptic curve point by a scalar integer with respect to the [[secp256k1]] elliptic curve.
*'''G, N''': Constants defined as part of the [[secp256k1]] elliptic curve. G is an elliptic curve point, and N is a large positive integer.
*'''[[Base58Check]]''': a method for encoding arrays of bytes using 58 alphanumeric characters commonly used in the Bitcoin ecosystem.
===Prefix===
It is proposed that the resulting Base58Check-encoded string start with a '6'. The number '6' is intended to represent, from the perspective of the user, "a private key that needs something else to be usable" - an umbrella definition that could be understood in the future to include keys participating in multisig transactions, and was chosen with deference to the existing prefix '5' most commonly observed in [[Wallet Import Format]] which denotes an unencrypted private key.
It is proposed that the second character ought to give a hint as to what is needed as a second factor, and for an encrypted key requiring a passphrase, the uppercase letter P is proposed.
To keep the size of the encrypted key down, no initialization vectors (IVs) are used in the AES encryption. Rather, suitable values for IV-like use are derived using scrypt from the passphrase and from using a 32-bit hash of the resulting Bitcoin address as salt.
===Proposed specification===
* Object identifier prefix: 0x0142 (non-EC-multiplied) or 0x0143 (EC-multiplied). These are constant bytes that appear at the beginning of the Base58Check-encoded record, and their presence causes the resulting string to have a predictable prefix.
* How the user sees it: 58 characters always starting with '6P'
** Visual cues are present in the third character for visually identifying the EC-multiply and compress flag.
* Count of payload bytes (beyond prefix): 37
** 1 byte (''flagbyte''):
*** the most significant two bits are set as follows to preserve the visibility of the compression flag in the prefix, as well as to keep the payload within the range of allowable values that keep the "6P" prefix intact. For non-EC-multiplied keys, the bits are 11. For EC-multiplied keys, the bits are 00.
*** the bit with value 0x20 when set indicates the key should be converted to a bitcoin address using the compressed public key format.
*** the bits with values 0x10 and 0x08 are reserved for a future specification that contemplates using multisig as a way to combine the factors such that parties in possession of the separate factors can independently sign a proposed transaction without requiring that any party possess both factors. These bits must be 0 to comply with this version of the specification.
*** the bit with value 0x04 indicates whether a lot and sequence number are encoded into the first factor, and activates special behavior for including them in the decryption process. This applies to EC-multiplied keys only. Must be 0 for non-EC-multiplied keys.
*** remaining bits are reserved for future use and must all be 0 to comply with this version of the specification.
** 4 bytes: SHA256(SHA256(expected_bitcoin_address))[0...3], used both for typo checking and as salt
**16 bytes: Contents depend on whether EC multiplication is used.
**16 bytes: lasthalf: An AES-encrypted key material record (contents depend on whether EC multiplication is used)
* Range in base58check encoding for non-EC-multiplied keys without compression (prefix 6PR):
** Minimum value: 6PRHv1jg1ytiE4kT2QtrUz8gEjMQghZDWg1FuxjdYDzjUkcJeGdFj9q9Vi (based on 01 42 C0 plus thirty-six 00's)
** Maximum value: 6PRWdmoT1ZursVcr5NiD14p5bHrKVGPG7yeEoEeRb8FVaqYSHnZTLEbYsU (based on 01 42 C0 plus thirty-six FF's)
* Range in base58check encoding for non-EC-multiplied keys with compression (prefix 6PY):
** Minimum value: 6PYJxKpVnkXUsnZAfD2B5ZsZafJYNp4ezQQeCjs39494qUUXLnXijLx6LG (based on 01 42 E0 plus thirty-six 00's)
** Maximum value: 6PYXg5tGnLYdXDRZiAqXbeYxwDoTBNthbi3d61mqBxPpwZQezJTvQHsCnk (based on 01 42 E0 plus thirty-six FF's)
* Range in base58check encoding for EC-multiplied keys without compression (prefix 6Pf):
** Minimum value: 6PfKzduKZXAFXWMtJ19Vg9cSvbFg4va6U8p2VWzSjtHQCCLk3JSBpUvfpf (based on 01 43 00 plus thirty-six 00's)
** Maximum value: 6PfYiPy6Z7BQAwEHLxxrCEHrH9kasVQ95ST1NnuEnnYAJHGsgpNPQ9dTHc (based on 01 43 00 plus thirty-six FF's)
* Range in base58check encoding for non-EC-multiplied keys with compression (prefix 6Pn):
** Minimum value: 6PnM2wz9LHo2BEAbvoGpGjMLGXCom35XwsDQnJ7rLiRjYvCxjpLenmoBsR (based on 01 43 20 plus thirty-six 00's)
** Maximum value: 6PnZki3vKspApf2zym6Anp2jd5hiZbuaZArPfa2ePcgVf196PLGrQNyVUh (based on 01 43 20 plus thirty-six FF's)
====Encryption when EC multiply flag is not used====
Encrypting a private key without the EC multiplication offers the advantage that any known private key can be encrypted. The party performing the encryption must know the passphrase.
Encryption steps:
# Compute the Bitcoin address (ASCII), and take the first four bytes of SHA256(SHA256()) of it. Let's call this "addresshash".
# Derive a key from the passphrase using scrypt
#*Parameters: ''passphrase'' is the passphrase itself encoded in UTF-8. salt is ''addresshash'' from the earlier step, n=16384, r=8, p=8, length=64 (n, r, p are provisional and subject to consensus)
#*Let's split the resulting 64 bytes in half, and call them ''derivedhalf1'' and ''derivedhalf2''.
# Do AES256Encrypt(bitcoinprivkey[0...15] xor derivedhalf1[0...15], derivedhalf2), call the 16-byte result ''encryptedhalf1''
# Do AES256Encrypt(bitcoinprivkey[16...31] xor derivedhalf1[16...31], derivedhalf2), call the 16-byte result ''encryptedhalf2''
The encrypted private key is the Base58Check-encoded concatenation of the following, which totals 39 bytes without Base58 checksum:
* 0x01 0x42 + ''flagbyte'' + ''salt'' + ''encryptedhalf1'' + ''encryptedhalf2''
Decryption steps:
# Collect encrypted private key and passphrase from user.
# Derive ''derivedhalf1'' and ''derivedhalf2'' by passing the passphrase and ''addresshash'' into scrypt function.
# Decrypt ''encryptedhalf1'' and ''encryptedhalf2'' using AES256Decrypt, merge them to form the encrypted private key.
# Convert that private key into a Bitcoin address, honoring the compression preference specified in ''flagbyte'' of the encrypted key record.
# Hash the Bitcoin address, and verify that ''addresshash'' from the encrypted private key record matches the hash. If not, report that the passphrase entry was incorrect.
====Encryption when EC multiply mode is used====
Encrypting a private key with EC multiplication offers the ability for someone to generate encrypted keys knowing only an EC point derived from the original passphrase and some salt generated by the passphrase's owner, and without knowing the passphrase itself. Only the person who knows the original passphrase can decrypt the private key. A code known as an ''intermediate code'' conveys the information needed to generate such a key without knowledge of the passphrase.
This methodology does not offer the ability to encrypt a known private key - this means that the process of creating encrypted keys is also the process of generating new addresses. On the other hand, this serves a security benefit for someone possessing an address generated this way: if the address can be recreated by decrypting its private key with a passphrase, and it's a strong passphrase one can be certain only he knows himself, then he can safely conclude that nobody could know the private key to that address.
The person who knows the passphrase and who is the intended beneficiary of the private keys is called the ''owner''. He will generate one or more "intermediate codes", which are the first factor of a two-factor redemption system, and will give them to someone else we'll call ''printer'', who generates a key pair with an intermediate code can know the address and encrypted private key, but cannot decrypt the private key without the original passphrase.
An intermediate code should, but is not required to, embed a printable "lot" and "sequence" number for the benefit of the user. The proposal forces these lot and sequence numbers to be included in any valid private keys generated from them. An owner who has requested multiple private keys to be generated for him will be advised by applications to ensure that each private key has a unique lot and sequence number consistent with the intermediate codes he generated. These mainly help protect ''owner'' from potential mistakes and/or attacks that could be made by ''printer''.
The "lot" and "sequence" number are combined into a single 32 bit number. 20 bits are used for the lot number and 12 bits are used for the sequence number, such that the lot number can be any decimal number between 0 and 1048575, and the sequence number can be any decimal number between 0 and 4095. For programs that generate batches of intermediate codes for an ''owner'', it is recommended that lot numbers be chosen at random within the range 100000-999999 and that sequence numbers are assigned starting with 1.
Steps performed by ''owner'' to generate a single intermediate code, if lot and sequence numbers are being included:
# Generate 4 random bytes, call them ''ownersalt''.
# Encode the lot and sequence numbers as a 4 byte quantity (big-endian): lotnumber * 4096 + sequencenumber. Call these four bytes ''lotsequence''.
# Concatenate ''ownersalt'' + ''lotsequence'' and call this ''ownerentropy''.
# Derive a key from the passphrase using scrypt
#* Parameters: ''passphrase'' is the passphrase itself encoded in UTF-8. salt is ''ownersalt''. n=16384, r=8, p=8, length=32.
#* Call the resulting 32 bytes ''prefactor''.
#* Take SHA256(SHA256(''prefactor'' + ''ownerentropy'')) and call this ''passfactor''.
# Compute the elliptic curve point G * ''passfactor'', and convert the result to compressed notation (33 bytes). Call this ''passpoint''. Compressed notation is used for this purpose regardless of whether the intent is to create Bitcoin addresses with or without compressed public keys.
# Convey ''ownersalt'' and ''passpoint'' to the party generating the keys, along with a checksum to ensure integrity.
#* The following Base58Check-encoded format is recommended for this purpose: magic bytes "2C E9 B3 E1 FF 39 E2 51" followed by ''ownerentropy'', and then ''passpoint''. The resulting string will start with the word "passphrase" due to the constant bytes, will be 72 characters in length, and encodes 49 bytes (8 bytes constant + 8 bytes ''ownerentropy'' + 33 bytes ''passpoint''). The checksum is handled in the Base58Check encoding. The resulting string is called ''intermediate_passphrase_string''.
If lot and sequence numbers are not being included, then follow the same procedure with the following changes:
* ''ownersalt'' is 8 random bytes instead of 4, and ''lotsequence'' is omitted. ''ownerentropy'' becomes an alias for ''ownersalt''.
* The SHA256 conversion of ''prefactor'' to ''passfactor'' is omitted. Instead, the output of scrypt is used directly as ''passfactor''.
* The magic bytes are "2C E9 B3 E1 FF 39 E2 53" instead (the last byte is 0x53 instead of 0x51).
Steps to create new encrypted private keys given ''intermediate_passphrase_string'' from ''owner'' (so we have ''ownerentropy'', and ''passpoint'', but we do not have ''passfactor'' or the passphrase):
# Set ''flagbyte''.
#* Turn on bit 0x20 if the Bitcoin address will be formed by hashing the compressed public key (optional, saves space, but many Bitcoin implementations aren't compatible with it)
#* Turn on bit 0x04 if ''ownerentropy'' contains a value for ''lotsequence''. (While it has no effect on the keypair generation process, the decryption process needs this flag to know how to process ''ownerentropy'')
# Generate 24 random bytes, call this ''seedb''. Take SHA256(SHA256(''seedb'')) to yield 32 bytes, call this ''factorb''.
# ECMultiply ''passpoint'' by ''factorb''. Use the resulting EC point as a public key and hash it into a Bitcoin address using either compressed or uncompressed public key methodology (specify which methodology is used inside ''flagbyte''). This is the generated Bitcoin address, call it ''generatedaddress''.
# Take the first four bytes of SHA256(SHA256(''generatedaddress'')) and call it ''addresshash''.
# Now we will encrypt ''seedb''. Derive a second key from ''passpoint'' using scrypt
#*Parameters: ''passphrase'' is ''passpoint'' provided from the first party (expressed in binary as 33 bytes). ''salt'' is ''addresshash'' + ''ownerentropy'', n=1024, r=1, p=1, length=64. The "+" operator is concatenation.
#*Split the result into two 32-byte halves and call them ''derivedhalf1'' and ''derivedhalf2''.
# Do AES256Encrypt(seedb[0...15] xor derivedhalf1[0...15], derivedhalf2), call the 16-byte result ''encryptedpart1''
# Do AES256Encrypt((encryptedpart1[8...15] + seedb[16...23]) xor derivedhalf1[16...31], derivedhalf2), call the 16-byte result ''encryptedpart2''. The "+" operator is concatenation.
The encrypted private key is the Base58Check-encoded concatenation of the following, which totals 39 bytes without Base58 checksum:
* 0x01 0x43 + ''flagbyte'' + ''addresshash'' + ''ownerentropy'' + ''encryptedpart1''[0...7] + ''encryptedpart2''
=====Confirmation code=====
The party generating the Bitcoin address has the option to return a ''confirmation code'' back to ''owner'' which allows ''owner'' to independently verify that he has been given a Bitcoin address that actually depends on his passphrase, and to confirm the lot and sequence numbers (if applicable). This protects ''owner'' from being given a Bitcoin address by the second party that is unrelated to the key derivation and possibly spendable by the second party. If a Bitcoin address given to ''owner'' can be successfully regenerated through the confirmation process, ''owner'' can be reasonably assured that any spending without the passphrase is infeasible. This confirmation code is 75 characters starting with "cfrm38".
To generate it, we need ''flagbyte'', ''ownerentropy'', ''factorb'', ''derivedhalf1'' and ''derivedhalf2'' from the original encryption operation.
# ECMultiply ''factorb'' by G, call the result ''pointb''. The result is 33 bytes.
# The first byte is 0x02 or 0x03. XOR it by (derivedhalf2[31] & 0x01), call the resulting byte ''pointbprefix''.
# Do AES256Encrypt(pointb[1...16] xor derivedhalf1[0...15], derivedhalf2) and call the result ''pointbx1''.
# Do AES256Encrypt(pointb[17...32] xor derivedhalf1[16...31], derivedhalf2) and call the result ''pointbx2''.
# Concatenate ''pointbprefix'' + ''pointbx1'' + ''pointbx2'' (total 33 bytes) and call the result ''encryptedpointb''.
The result is a Base58Check-encoded concatenation of the following:
* 0x64 0x3B 0xF6 0xA8 0x9A + ''flagbyte'' + ''addresshash'' + ''ownerentropy'' + ''encryptedpointb''
A confirmation tool, given a passphrase and a confirmation code, can recalculate the address, verify the address hash, and then assert the following: "It is confirmed that Bitcoin address ''address'' depends on this passphrase". If applicable: "The lot number is ''lotnumber'' and the sequence number is ''sequencenumber''."
To recalculate the address:
# Derive ''passfactor'' using scrypt with ''ownerentropy'' and the user's passphrase and use it to recompute ''passpoint''
# Derive decryption key for ''pointb'' using scrypt with ''passpoint'', ''addresshash'', and ''ownerentropy''
# Decrypt ''encryptedpointb'' to yield ''pointb''
# ECMultiply ''pointb'' by ''passfactor''. Use the resulting EC point as a public key and hash it into ''address'' using either compressed or uncompressed public key methodology as specifid in ''flagbyte''.
=====Decryption=====
# Collect encrypted private key and passphrase from user.
# Derive ''passfactor'' using scrypt with ''ownerentropy'' and the user's passphrase and use it to recompute ''passpoint''
# Derive decryption key for ''seedb'' using scrypt with ''passpoint'', ''addresshash'', and ''ownersalt''
# Decrypt ''encryptedpart2'' using AES256Decrypt to yield the last 8 bytes of ''seedb'' and the last 8 bytes of ''encryptedpart1''.
# Decrypt ''encryptedpart1'' to yield the remainder of ''seedb''.
# Use ''seedb'' to compute ''factorb''.
# Multiply ''passfactor'' by ''factorb'' mod N to yield the private key associated with ''generatedaddress''.
# Convert that private key into a Bitcoin address, honoring the compression preference specified in the encrypted key.
# Hash the Bitcoin address, and verify that ''addresshash'' from the encrypted private key record matches the hash. If not, report that the passphrase entry was incorrect.
==Backwards compatibility==
Backwards compatibility is minimally applicable since this is a new standard that at most extends [[Wallet Import Format]]. It is assumed that an entry point for private key data may also accept existing formats of private keys (such as hexadecimal and [[Wallet Import Format]]); this draft uses a key format that cannot be mistaken for any existing one and preserves auto-detection capabilities.
==Suggestions for implementers of proposal with alt-chains==
If this proposal is accepted into alt-chains, it is requested that the unused flag bytes not be used for denoting that the key belongs to an alt-chain.
Alt-chain implementers should exploit the address hash for this purpose. Since each operation in this proposal involves hashing a text representation of a coin address which (for Bitcoin) includes the leading '1', an alt-chain can easily be denoted simply by using the alt-chain's preferred format for representing an address. Alt-chain implementers may also change the prefix such that encrypted addresses do not start with "6P".
==Discussion item: scrypt parameters==
This proposal leaves the scrypt parameters up in the air. The following items are proposed for consideration:
The main goal of scrypt is to reduce the feasibility of brute force attacks. It must be assumed that an attacker will be able to use an efficient implementation of scrypt. The parameters should force a highly efficient implementation of scrypt to wait a decent amount of time to slow attacks.
On the other hand, an unavoidably likely place where scrypt will be implemented is using slow interpreted languages such as javascript. What might take milliseconds on an efficient scrypt implementation may take seconds in javascript.
It is believed, however, that someone using a javascript implementation is probably dealing with codes by hand, one at a time, rather than generating or processing large batches of codes. Thus, a wait time of several seconds is acceptable to a user.
A private key redemption process that forces a server to consume several seconds of CPU time would discourage implementation by the server owner, because they would be opening up a denial of service avenue by inviting users to make numerous attempts to invoke the redemption process. However, it's also feasible for the server owner to implement his redemption process in such a way that the decryption is done by the user's browser, offloading the task from his own server (and providing another reason why the chosen scrypt parameters should be tolerant of javascript-based decryptors).
The preliminary values of 16384, 8, and 8 are hoped to offer the following properties:
* Encryption/decryption in javascript requiring several seconds per operation
* Use of the parallelization parameter provides a modest opportunity for speedups in environments where concurrent threading is available - such environments would be selected for processes that must handle bulk quantities of encryption/decryption operations. Estimated time for an operation is in the tens or hundreds of milliseconds.
==Reference implementation==
Added to alpha version of Casascius Bitcoin Address Utility for Windows available at:
* via https: https://casascius.com/btcaddress-alpha.zip
* at github: https://github.com/casascius/Bitcoin-Address-Utility
Click "Tools" then "PPEC Keygen" (provisional name)
==Test vectors==
===No compression, no EC multiply===
Test 1:
*Passphrase: TestingOneTwoThree
*Encrypted: 6PRVWUbkzzsbcVac2qwfssoUJAN1Xhrg6bNk8J7Nzm5H7kxEbn2Nh2ZoGg
*Unencrypted (WIF): 5KN7MzqK5wt2TP1fQCYyHBtDrXdJuXbUzm4A9rKAteGu3Qi5CVR
*Unencrypted (hex): CBF4B9F70470856BB4F40F80B87EDB90865997FFEE6DF315AB166D713AF433A5
Test 2:
*Passphrase: Satoshi
*Encrypted: 6PRNFFkZc2NZ6dJqFfhRoFNMR9Lnyj7dYGrzdgXXVMXcxoKTePPX1dWByq
*Unencrypted (WIF): 5HtasZ6ofTHP6HCwTqTkLDuLQisYPah7aUnSKfC7h4hMUVw2gi5
*Unencrypted (hex): 09C2686880095B1A4C249EE3AC4EEA8A014F11E6F986D0B5025AC1F39AFBD9AE
===Compression, no EC multiply===
Test 1:
*Passphrase: TestingOneTwoThree
*Encrypted: 6PYNKZ1EAgYgmQfmNVamxyXVWHzK5s6DGhwP4J5o44cvXdoY7sRzhtpUeo
*Unencrypted (WIF): L44B5gGEpqEDRS9vVPz7QT35jcBG2r3CZwSwQ4fCewXAhAhqGVpP
*Unencrypted (hex): CBF4B9F70470856BB4F40F80B87EDB90865997FFEE6DF315AB166D713AF433A5
Test 2:
*Passphrase: Satoshi
*Encrypted: 6PYLtMnXvfG3oJde97zRyLYFZCYizPU5T3LwgdYJz1fRhh16bU7u6PPmY7
*Unencrypted (WIF): KwYgW8gcxj1JWJXhPSu4Fqwzfhp5Yfi42mdYmMa4XqK7NJxXUSK7
*Unencrypted (hex): 09C2686880095B1A4C249EE3AC4EEA8A014F11E6F986D0B5025AC1F39AFBD9AE
===EC multiply, no compression, no lot/sequence numbers===
Test 1:
*Passphrase: TestingOneTwoThree
*Passphrase code: passphrasepxFy57B9v8HtUsszJYKReoNDV6VHjUSGt8EVJmux9n1J3Ltf1gRxyDGXqnf9qm
*Encrypted key: 6PfQu77ygVyJLZjfvMLyhLMQbYnu5uguoJJ4kMCLqWwPEdfpwANVS76gTX
*Bitcoin address: 1PE6TQi6HTVNz5DLwB1LcpMBALubfuN2z2
*Unencrypted private key (WIF): 5K4caxezwjGCGfnoPTZ8tMcJBLB7Jvyjv4xxeacadhq8nLisLR2
*Unencrypted private key (hex): A43A940577F4E97F5C4D39EB14FF083A98187C64EA7C99EF7CE460833959A519
Test 2:
*Passphrase: Satoshi
*Passphrase code: passphraseoRDGAXTWzbp72eVbtUDdn1rwpgPUGjNZEc6CGBo8i5EC1FPW8wcnLdq4ThKzAS
*Encrypted key: 6PfLGnQs6VZnrNpmVKfjotbnQuaJK4KZoPFrAjx1JMJUa1Ft8gnf5WxfKd
*Bitcoin address: 1CqzrtZC6mXSAhoxtFwVjz8LtwLJjDYU3V
*Unencrypted private key (WIF): 5KJ51SgxWaAYR13zd9ReMhJpwrcX47xTJh2D3fGPG9CM8vkv5sH
*Unencrypted private key (hex): C2C8036DF268F498099350718C4A3EF3984D2BE84618C2650F5171DCC5EB660A
===EC multiply, no compression, lot/sequence numbers===
Test 1:
*Passphrase: MOLON LABE
*Passphrase code: passphraseaB8feaLQDENqCgr4gKZpmf4VoaT6qdjJNJiv7fsKvjqavcJxvuR1hy25aTu5sX
*Encrypted key: 6PgNBNNzDkKdhkT6uJntUXwwzQV8Rr2tZcbkDcuC9DZRsS6AtHts4Ypo1j
*Bitcoin address: 1Jscj8ALrYu2y9TD8NrpvDBugPedmbj4Yh
*Unencrypted private key (WIF): 5JLdxTtcTHcfYcmJsNVy1v2PMDx432JPoYcBTVVRHpPaxUrdtf8
*Unencrypted private key (hex): 44EA95AFBF138356A05EA32110DFD627232D0F2991AD221187BE356F19FA8190
*Confirmation code: cfrm38V8aXBn7JWA1ESmFMUn6erxeBGZGAxJPY4e36S9QWkzZKtaVqLNMgnifETYw7BPwWC9aPD
*Lot/Sequence: 263183/1
Test 2:
*Passphrase (all letters are Greek - test UTF-8 compatibility with this): ΜΟΛΩΝ ΛΑΒΕ
*Passphrase code: passphrased3z9rQJHSyBkNBwTRPkUGNVEVrUAcfAXDyRU1V28ie6hNFbqDwbFBvsTK7yWVK
*Encrypted private key: 6PgGWtx25kUg8QWvwuJAgorN6k9FbE25rv5dMRwu5SKMnfpfVe5mar2ngH
*Bitcoin address: 1Lurmih3KruL4xDB5FmHof38yawNtP9oGf
*Unencrypted private key (WIF): 5KMKKuUmAkiNbA3DazMQiLfDq47qs8MAEThm4yL8R2PhV1ov33D
*Unencrypted private key (hex): CA2759AA4ADB0F96C414F36ABEB8DB59342985BE9FA50FAAC228C8E7D90E3006
*Confirmation code: cfrm38V8G4qq2ywYEFfWLD5Cc6msj9UwsG2Mj4Z6QdGJAFQpdatZLavkgRd1i4iBMdRngDqDs51
*Lot/Sequence: 806938/1

161
selected BIPs/bip-0039.asciidoc
View File

@ -1,161 +0,0 @@
----------------------------------------------------------
BIP: BIP-0039
Title: Mnemonic code for generating deterministic keys
Authors: Marek Palatinus <slush@satoshilabs.com>
Pavol Rusnak <stick@satoshilabs.com>
ThomasV <thomasv@bitcointalk.org>
Aaron Voisine <voisine@gmail.com>
Sean Bowe <ewillbefull@gmail.com>
Status: Draft
Type: Standards Track
Created: 2013-09-10
----------------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP describes the implementation of a mnemonic code or mnemonic
sentence -- a group of easy to remember words -- for the generation of
deterministic wallets.
It consists of two parts: generating the mnenomic, and converting it
into a binary seed. This seed can be later used to generate
deterministic wallets using BIP-0032 or similar methods.
[[motivation]]
Motivation
~~~~~~~~~~
A mnenomic code or sentence is superior for human interaction compared
to the handling of raw binary or hexidecimal representations of a wallet
seed. The sentence could be written on paper or spoken over the
telephone.
This guide meant to be as a way to transport computer-generated
randomnes over human readable transcription. It's not a way how to
process user-created sentences (also known as brainwallet) to wallet
seed.
[[generating-the-mnemonic]]
Generating the mnemonic
~~~~~~~~~~~~~~~~~~~~~~~
The mnemonic must encode entropy in any multiple of 32 bits. With larger
entropy security is improved but the sentence length increases. We can
refer to the initial entropy length as ENT. The recommended size of ENT
is 128-256 bits.
First, an initial entropy of ENT bits is generated. A checksum is
generated by taking the first
--------
ENT / 32
--------
bits of its SHA256 hash. This checksum is appended to the end of the
initial entropy. Next, these concatenated bits are are split into groups
of 11 bits, each encoding a number from 0-2047, serving as an index to a
wordlist. Later, we will convert these numbers into words and use the
joined words as a mnemonic sentence.
The following table describes the relation between the initial entropy
length (ENT), the checksum length (CS) and length of the generated
mnemonic sentence (MS) in words.
------------------------------
CS = ENT / 32
MS = (ENT + CS) / 11
| ENT | CS | ENT+CS | MS |
+-------+----+--------+------+
| 128 | 4 | 132 | 12 |
| 160 | 5 | 165 | 15 |
| 192 | 6 | 198 | 18 |
| 224 | 7 | 231 | 21 |
| 256 | 8 | 264 | 24 |
------------------------------
[[wordlist]]
Wordlist
~~~~~~~~
An ideal wordlist has the following characteristics:
\a) smart selection of words
`  - wordlist is created in such way that it's enough to type the first four` +
`    letters to unambiguously identify the word`
\b) similar words avoided
`  - word pairs like "build" and "built", "woman" and "women", or "quick" and "quickly"` +
`    not only make remembering the sentence difficult, but are also more error` +
`    prone and more difficult to guess`
\c) sorted wordlists
`  - wordlist is sorted which allows for more efficient lookup of the code words` +
`    (i.e. implementation can use binary search instead of linear search)` +
`  - this also allows trie (prefix tree) to be used, e.g. for better compression`
The wordlist can contain native characters, but they have to be encoded
in UTF-8 using Normalization Form Compatibility Decomposition (NFKD).
[[from-mnemonic-to-seed]]
From mnemonic to seed
~~~~~~~~~~~~~~~~~~~~~
A user may decide to protect their mnemonic by passphrase. If a
passphrase is not present, an empty string "" is used instead.
To create a binary seed from the mnemonic, we use PBKDF2 function with a
mnemonic sentence (in UTF-8 NFKD) used as a password and string
"mnemonic" + passphrase (again in UTF-8 NFKD) used as a salt. Iteration
count is set to 2048 and HMAC-SHA512 is used as a pseudo-random
function. Desired length of the derived key is 512 bits (= 64 bytes).
This seed can be later used to generate deterministic wallets using
BIP-0032 or similar methods.
The conversion of the mnemonic sentence to binary seed is completely
independent from generating the sentence. This results in rather simple
code; there are no constraints on sentence structure and clients are
free to implement their own wordlists or even whole sentence generators,
allowing for flexibility in wordlists for typo detection or other
purposes.
Although using mnemonic not generated by algorithm described in
"Generating the mnemonic" section is possible, this is not advised and
software must compute checksum of the mnemonic sentence using wordlist
and issue a warning if it is invalid.
Described method also provides plausible deniability, because every
passphrase generates a valid seed (and thus deterministic wallet) but
only the correct one will make the desired wallet available.
[[wordlists]]
Wordlists
~~~~~~~~~
* link:bip-0039/english.txt[English]
[[test-vectors]]
Test vectors
~~~~~~~~~~~~
See https://github.com/trezor/python-mnemonic/blob/master/vectors.json
[[reference-implementation]]
Reference Implementation
~~~~~~~~~~~~~~~~~~~~~~~~
Reference implementation including wordlists is available from
http://github.com/trezor/python-mnemonic
[[other-implementations]]
Other Implementations
~~~~~~~~~~~~~~~~~~~~~
Objective-C - https://github.com/nybex/NYMnemonic

129
selected BIPs/bip-0039.mediawiki
View File

@ -1,129 +0,0 @@
<pre>
BIP: BIP-0039
Title: Mnemonic code for generating deterministic keys
Authors: Marek Palatinus <slush@satoshilabs.com>
Pavol Rusnak <stick@satoshilabs.com>
ThomasV <thomasv@bitcointalk.org>
Aaron Voisine <voisine@gmail.com>
Sean Bowe <ewillbefull@gmail.com>
Status: Draft
Type: Standards Track
Created: 2013-09-10
</pre>
==Abstract==
This BIP describes the implementation of a mnemonic code or mnemonic sentence --
a group of easy to remember words -- for the generation of deterministic wallets.
It consists of two parts: generating the mnenomic, and converting it into a
binary seed. This seed can be later used to generate deterministic wallets using
BIP-0032 or similar methods.
==Motivation==
A mnenomic code or sentence is superior for human interaction compared to the
handling of raw binary or hexidecimal representations of a wallet seed. The
sentence could be written on paper or spoken over the telephone.
This guide meant to be as a way to transport computer-generated randomnes over
human readable transcription. It's not a way how to process user-created
sentences (also known as brainwallet) to wallet seed.
==Generating the mnemonic==
The mnemonic must encode entropy in any multiple of 32 bits. With larger entropy
security is improved but the sentence length increases. We can refer to the
initial entropy length as ENT. The recommended size of ENT is 128-256 bits.
First, an initial entropy of ENT bits is generated. A checksum is generated by
taking the first <pre>ENT / 32</pre> bits of its SHA256 hash. This checksum is
appended to the end of the initial entropy. Next, these concatenated bits are
are split into groups of 11 bits, each encoding a number from 0-2047, serving
as an index to a wordlist. Later, we will convert these numbers into words and
use the joined words as a mnemonic sentence.
The following table describes the relation between the initial entropy
length (ENT), the checksum length (CS) and length of the generated mnemonic
sentence (MS) in words.
<pre>
CS = ENT / 32
MS = (ENT + CS) / 11
| ENT | CS | ENT+CS | MS |
+-------+----+--------+------+
| 128 | 4 | 132 | 12 |
| 160 | 5 | 165 | 15 |
| 192 | 6 | 198 | 18 |
| 224 | 7 | 231 | 21 |
| 256 | 8 | 264 | 24 |
</pre>
==Wordlist==
An ideal wordlist has the following characteristics:
a) smart selection of words
- wordlist is created in such way that it's enough to type the first four
letters to unambiguously identify the word
b) similar words avoided
- word pairs like "build" and "built", "woman" and "women", or "quick" and "quickly"
not only make remembering the sentence difficult, but are also more error
prone and more difficult to guess
c) sorted wordlists
- wordlist is sorted which allows for more efficient lookup of the code words
(i.e. implementation can use binary search instead of linear search)
- this also allows trie (prefix tree) to be used, e.g. for better compression
The wordlist can contain native characters, but they have to be encoded in UTF-8
using Normalization Form Compatibility Decomposition (NFKD).
==From mnemonic to seed==
A user may decide to protect their mnemonic by passphrase. If a passphrase is not
present, an empty string "" is used instead.
To create a binary seed from the mnemonic, we use PBKDF2 function with a mnemonic
sentence (in UTF-8 NFKD) used as a password and string "mnemonic" + passphrase (again
in UTF-8 NFKD) used as a salt. Iteration count is set to 2048 and HMAC-SHA512 is used as
a pseudo-random function. Desired length of the derived key is 512 bits (= 64 bytes).
This seed can be later used to generate deterministic wallets using BIP-0032 or
similar methods.
The conversion of the mnemonic sentence to binary seed is completely independent
from generating the sentence. This results in rather simple code; there are no
constraints on sentence structure and clients are free to implement their own
wordlists or even whole sentence generators, allowing for flexibility in wordlists
for typo detection or other purposes.
Although using mnemonic not generated by algorithm described in "Generating the
mnemonic" section is possible, this is not advised and software must compute
checksum of the mnemonic sentence using wordlist and issue a warning if it is
invalid.
Described method also provides plausible deniability, because every passphrase
generates a valid seed (and thus deterministic wallet) but only the correct one
will make the desired wallet available.
==Wordlists==
* [[bip-0039/english.txt|English]]
==Test vectors==
See https://github.com/trezor/python-mnemonic/blob/master/vectors.json
==Reference Implementation==
Reference implementation including wordlists is available from
http://github.com/trezor/python-mnemonic
==Other Implementations==
Objective-C - https://github.com/nybex/NYMnemonic

207
selected BIPs/bip-0044.asciidoc
View File

@ -1,207 +0,0 @@
------------------------------------------------------------
BIP: BIP-0044
Title: Multi-Account Hierarchy for Deterministic Wallets
Authors: Marek Palatinus <slush@satoshilabs.com>
Pavol Rusnak <stick@satoshilabs.com>
Status: Draft
Type: Standards Track
Created: 2014-04-24
------------------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP defines a logical hierarchy for deterministic wallets based on
an algorithm described in BIP-0032 (BIP32 from now on) and purpose
scheme described in BIP-0043 (BIP43 from now on).
This BIP is a particular application of BIP43.
[[motivation]]
Motivation
~~~~~~~~~~
The hierarchy proposed in this paper is quite comprehensive. It allows
the handling of multiple coins, multiple accounts, external and internal
chains per account and millions of addresses per chain.
[[path-levels]]
Path levels
~~~~~~~~~~~
We define the following 5 levels in BIP32 path:
-------------------------------------------------------------
m / purpose' / coin_type' / account' / change / address_index
-------------------------------------------------------------
Apostrophe in the path indicates that BIP32 hardened derivation is used.
Each level has a special meaning, described in the chapters below.
[[purpose]]
Purpose
^^^^^^^
Purpose is a constant set to 44' (or 0x8000002C) following the BIP43
recommendation. It indicates that the subtree of this node is used
according to this specification.
Hardened derivation is used at this level.
[[coin-type]]
Coin type
^^^^^^^^^
One master node (seed) can be used for unlimited number of independent
cryptocoins such as Bitcoin, Litecoin or Namecoin. However, sharing the
same space for various cryptocoins has some disadvantages.
This level creates a separate subtree for every cryptocoin, avoiding
reusing addresses across cryptocoins and improving privacy issues.
Coin type is a constant, set for each cryptocoin. Cryptocoin developers
may ask for registering unused number for their project.
The list of already allocated coin types is in the chapter "Registered
coin types" below.
Hardened derivation is used at this level.
[[account]]
Account
^^^^^^^
This level splits the key space into independent user identities, so the
wallet never mixes the coins across different accounts.
Users can use these accounts to organize the funds in the same fashion
as bank accounts; for donation purposes (where all addresses are
considered public), for saving purposes, for common expenses etc.
Accounts are numbered from index 0 in sequentially increasing manner.
This number is used as child index in BIP32 derivation.
Hardened derivation is used at this level.
Software should prevent a creation of an account if a previous account
does not have a transaction history (meaning none of its addresses have
been used before).
Software needs to discover all used accounts after importing the seed
from an external source. Such an algorithm is described in "Account
discovery" chapter.
[[change]]
Change
^^^^^^
Constant 0 is used for external chain and constant 1 for internal chain
(also known as change addresses). External chain is used for addresses
that are meant to be visible outside of the wallet (e.g. for receiving
payments). Internal chain is used for addresses which are not meant to
be visible outside of the wallet and is used for return transaction
change.
Public derivation is used at this level.
[[index]]
Index
^^^^^
Addresses are numbered from index 0 in sequentially increasing manner.
This number is used as child index in BIP32 derivation.
Public derivation is used at this level.
[[account-discovery]]
Account discovery
~~~~~~~~~~~~~~~~~
When the master seed is imported from an external source the software
should start to discover the accounts in the following manner:
1. derive the first account's node (index = 0)
2. derive the external chain node of this account
3. scan addresses of the external chain; respect the gap limit
described below
4. if no transactions are found on the external chain, stop discovery
5. if there are some transactions, increase the account index and go to
step 1
This algorithm is successful because software should disallow creation
of new accounts if previous one has no transaction history, as described
in chapter "Account" above.
Please note that the algorithm works with the transaction history, not
account balances, so you can have an account with 0 total coins and the
algorithm will still continue with discovery.
[[address-gap-limit]]
Address gap limit
^^^^^^^^^^^^^^^^^
Address gap limit is currently set to 20. If the software hits 20 unused
addresses in a row, it expects there are no used addresses beyond this
point and stops searching the address chain.
Wallet software should warn when the user is trying to exceed the gap
limit on an external chain by generating a new address.
[[registered-coin-types]]
Registered coin types
~~~~~~~~~~~~~~~~~~~~~
These are the registered coin types for usage in level 2 of BIP44
described in chapter "Coin type" above.
All these constants are used as hardened derivation.
[cols=",,",options="header",]
|==============================
|index |hexa |coin
|0 |0x80000000 |Bitcoin
|1 |0x80000001 |Bitcoin Testnet
|==============================
[[examples]]
Examples
~~~~~~~~
[cols=",,,,",options="header",]
|====================================================================
|coin |account |chain |address |path
|Bitcoin |first |external |first |m / 44' / 0' / 0' / 0 / 0
|Bitcoin |first |external |second |m / 44' / 0' / 0' / 0 / 1
|Bitcoin |first |change |first |m / 44' / 0' / 0' / 1 / 0
|Bitcoin |first |change |second |m / 44' / 0' / 0' / 1 / 1
|Bitcoin |second |external |first |m / 44' / 0' / 1' / 0 / 0
|Bitcoin |second |external |second |m / 44' / 0' / 1' / 0 / 1
|Bitcoin |second |change |first |m / 44' / 0' / 1' / 1 / 0
|Bitcoin |second |change |second |m / 44' / 0' / 1' / 1 / 1
|Bitcoin Testnet |first |external |first |m / 44' / 1' / 0' / 0 / 0
|Bitcoin Testnet |first |external |second |m / 44' / 1' / 0' / 0 / 1
|Bitcoin Testnet |first |change |first |m / 44' / 1' / 0' / 1 / 0
|Bitcoin Testnet |first |change |second |m / 44' / 1' / 0' / 1 / 1
|Bitcoin Testnet |second |external |first |m / 44' / 1' / 1' / 0 / 0
|Bitcoin Testnet |second |external |second |m / 44' / 1' / 1' / 0 / 1
|Bitcoin Testnet |second |change |first |m / 44' / 1' / 1' / 1 / 0
|Bitcoin Testnet |second |change |second |m / 44' / 1' / 1' / 1 / 1
|====================================================================
[[compatible-wallets]]
Compatible wallets
~~~~~~~~~~~~~~~~~~
* https://mytrezor.com[myTREZOR web wallet]
(https://github.com/trezor/webwallet[source])
[[reference]]
Reference
~~~~~~~~~
* link:bip-0032.mediawiki[BIP32 - Hierarchical Deterministic Wallets]
* link:bip-0043.mediawiki[BIP43 - Purpose Field for Deterministic
Wallets]

261
selected BIPs/bip-0044.mediawiki
View File

@ -1,261 +0,0 @@
<pre>
BIP: BIP-0044
Title: Multi-Account Hierarchy for Deterministic Wallets
Authors: Marek Palatinus <slush@satoshilabs.com>
Pavol Rusnak <stick@satoshilabs.com>
Status: Draft
Type: Standards Track
Created: 2014-04-24
</pre>
==Abstract==
This BIP defines a logical hierarchy for deterministic wallets based on an algorithm
described in BIP-0032 (BIP32 from now on) and purpose scheme described in
BIP-0043 (BIP43 from now on).
This BIP is a particular application of BIP43.
==Motivation==
The hierarchy proposed in this paper is quite comprehensive. It allows the handling of
multiple coins, multiple accounts, external and internal chains per account and
millions of addresses per chain.
==Path levels==
We define the following 5 levels in BIP32 path:
<pre>
m / purpose' / coin_type' / account' / change / address_index
</pre>
Apostrophe in the path indicates that BIP32 hardened derivation is used.
Each level has a special meaning, described in the chapters below.
===Purpose===
Purpose is a constant set to 44' (or 0x8000002C) following the BIP43 recommendation.
It indicates that the subtree of this node is used according to this specification.
Hardened derivation is used at this level.
===Coin type===
One master node (seed) can be used for unlimited number of independent
cryptocoins such as Bitcoin, Litecoin or Namecoin. However, sharing the same
space for various cryptocoins has some disadvantages.
This level creates a separate subtree for every cryptocoin, avoiding
reusing addresses across cryptocoins and improving privacy issues.
Coin type is a constant, set for each cryptocoin. Cryptocoin developers may ask
for registering unused number for their project.
The list of already allocated coin types is in the chapter
"Registered coin types" below.
Hardened derivation is used at this level.
===Account===
This level splits the key space into independent user identities,
so the wallet never mixes the coins across different accounts.
Users can use these accounts to organize the funds in the same
fashion as bank accounts; for donation purposes (where all
addresses are considered public), for saving purposes,
for common expenses etc.
Accounts are numbered from index 0 in sequentially increasing manner.
This number is used as child index in BIP32 derivation.
Hardened derivation is used at this level.
Software should prevent a creation of an account if a previous account does not
have a transaction history (meaning none of its addresses have been used before).
Software needs to discover all used accounts after importing the seed from
an external source. Such an algorithm is described in "Account discovery" chapter.
===Change===
Constant 0 is used for external chain and constant 1 for internal chain (also
known as change addresses). External chain is used for addresses that are meant
to be visible outside of the wallet (e.g. for receiving payments). Internal
chain is used for addresses which are not meant to be visible outside of the
wallet and is used for return transaction change.
Public derivation is used at this level.
===Index===
Addresses are numbered from index 0 in sequentially increasing manner.
This number is used as child index in BIP32 derivation.
Public derivation is used at this level.
==Account discovery==
When the master seed is imported from an external source the software should
start to discover the accounts in the following manner:
# derive the first account's node (index = 0)
# derive the external chain node of this account
# scan addresses of the external chain; respect the gap limit described below
# if no transactions are found on the external chain, stop discovery
# if there are some transactions, increase the account index and go to step 1
This algorithm is successful because software should disallow creation of new
accounts if previous one has no transaction history, as described in chapter
"Account" above.
Please note that the algorithm works with the transaction history, not account
balances, so you can have an account with 0 total coins and the algorithm will
still continue with discovery.
===Address gap limit===
Address gap limit is currently set to 20. If the software hits 20 unused
addresses in a row, it expects there are no used addresses beyond this point
and stops searching the address chain.
Wallet software should warn when the user is trying to exceed the gap limit on
an external chain by generating a new address.
==Registered coin types==
These are the registered coin types for usage in level 2 of BIP44 described in
chapter "Coin type" above.
All these constants are used as hardened derivation.
{|
!index
!hexa
!coin
|-
|0
|0x80000000
|Bitcoin
|-
|1
|0x80000001
|Bitcoin Testnet
|}
==Examples==
{|
!coin
!account
!chain
!address
!path
|-
|Bitcoin
|first
|external
|first
|m / 44' / 0' / 0' / 0 / 0
|-
|Bitcoin
|first
|external
|second
|m / 44' / 0' / 0' / 0 / 1
|-
|Bitcoin
|first
|change
|first
|m / 44' / 0' / 0' / 1 / 0
|-
|Bitcoin
|first
|change
|second
|m / 44' / 0' / 0' / 1 / 1
|-
|Bitcoin
|second
|external
|first
|m / 44' / 0' / 1' / 0 / 0
|-
|Bitcoin
|second
|external
|second
|m / 44' / 0' / 1' / 0 / 1
|-
|Bitcoin
|second
|change
|first
|m / 44' / 0' / 1' / 1 / 0
|-
|Bitcoin
|second
|change
|second
|m / 44' / 0' / 1' / 1 / 1
|-
|Bitcoin Testnet
|first
|external
|first
|m / 44' / 1' / 0' / 0 / 0
|-
|Bitcoin Testnet
|first
|external
|second
|m / 44' / 1' / 0' / 0 / 1
|-
|Bitcoin Testnet
|first
|change
|first
|m / 44' / 1' / 0' / 1 / 0
|-
|Bitcoin Testnet
|first
|change
|second
|m / 44' / 1' / 0' / 1 / 1
|-
|Bitcoin Testnet
|second
|external
|first
|m / 44' / 1' / 1' / 0 / 0
|-
|Bitcoin Testnet
|second
|external
|second
|m / 44' / 1' / 1' / 0 / 1
|-
|Bitcoin Testnet
|second
|change
|first
|m / 44' / 1' / 1' / 1 / 0
|-
|Bitcoin Testnet
|second
|change
|second
|m / 44' / 1' / 1' / 1 / 1
|}
==Compatible wallets==
* [[https://mytrezor.com|myTREZOR web wallet]] ([[https://github.com/trezor/webwallet|source]])
==Reference==
* [[bip-0032.mediawiki|BIP32 - Hierarchical Deterministic Wallets]]
* [[bip-0043.mediawiki|BIP43 - Purpose Field for Deterministic Wallets]]

429
selected BIPs/bip-0070.asciidoc
View File

@ -1,429 +0,0 @@
--------------------------------------------------
BIP: 70
Title: Payment Protocol
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Draft
Type: Standards Track
Created: 2013-07-29
--------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP describes a protocol for communication between a merchant and
their customer, enabling both a better customer experience and better
security against man-in-the-middle attacks on the payment process.
[[motivation]]
Motivation
~~~~~~~~~~
The current, minimal Bitcoin payment protocol operates as follows:
1. Customer adds items to an online shopping basket, and decides to pay
using Bitcoin.
2. Merchant generates a unique payment address, associates it with the
customer's order, and asks the customer to pay.
3. Customer copies the Bitcoin address from the merchant's web page and
pastes it into whatever wallet they are using OR follows a bitcoin: link
and their wallet is launched with the amount to be paid.
4. Customer authorizes payment to the merchant's address and broadcasts
the transaction through the Bitcoin p2p network.
5. Merchant's server detects payment and after sufficient transaction
confirmations considers the transaction final.
This BIP extends the above protocol to support several new features:
1. Human-readable, secure payment destinations-- customers will be
asked to authorize payment to "example.com" instead of an inscrutable,
34-character bitcoin address.
2. Secure proof of payment, which the customer can use in case of a
dispute with the merchant.
3. Resistance from man-in-the-middle attacks that replace a merchant's
bitcoin address with an attacker's address before a transaction is
authorized with a hardware wallet.
4. Payment received messages, so the customer knows immediately that
the merchant has received, and has processed (or is processing) their
payment.
5. Refund addresses, automatically given to the merchant by the
customer's wallet software, so merchants do not have to contact
customers before refunding overpayments or orders that cannot be
fulfilled for some reason.
[[protocol]]
Protocol
~~~~~~~~
This BIP describes payment protocol messages encoded using Google's
Protocol Buffers, authenticated using X.509 certificates, and
communicated over http/https. Future BIPs might extend this payment
protocol to other encodings, PKI systems, or transport protocols.
The payment protocol consists of three messages; PaymentRequest,
Payment, and PaymentACK, and begins with the customer somehow indicating
that they are ready to pay and the merchant's server responding with a
PaymentRequest message:
[[messages]]
Messages
~~~~~~~~
The Protocol Buffers messages are defined in
link:bip-0070/paymentrequest.proto[paymentrequest.proto].
[[output]]
Output
^^^^^^
Outputs are used in PaymentRequest messages to specify where a payment
(or part of a payment) should be sent. They are also used in Payment
messages to specify where a refund should be sent.
---------------------------------------------
message Output {
optional uint64 amount = 1 [default = 0];
optional bytes script = 2;
}
---------------------------------------------
[cols=",",]
|=======================================================================
|amount |Number of satoshis (0.00000001 BTC) to be paid
|script |a "TxOut" script where payment should be sent. This will
normally be one of the standard Bitcoin transaction scripts (e.g. pubkey
OP_CHECKSIG). This is optional to enable future extensions to this
protocol that derive Outputs from a master public key and the
PaymentRequest data itself.
|=======================================================================
[[paymentdetailspaymentrequest]]
PaymentDetails/PaymentRequest
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Payment requests are split into two messages to support future
extensibility. The bulk of the information is contained in the
PaymentDetails message. It is wrapped inside a PaymentRequest message,
which contains meta-information about the merchant and a digital
signature.
-------------------------------------------------------
message PaymentDetails {
optional string network = 1 [default = "main"];
repeated Output outputs = 2;
required uint64 time = 3;
optional uint64 expires = 4;
optional string memo = 5;
optional string payment_url = 6;
optional bytes merchant_data = 7;
}
-------------------------------------------------------
[cols=",",]
|=======================================================================
|network |either "main" for payments on the production Bitcoin network,
or "test" for payments on test network. If a client receives a
PaymentRequest for a network it does not support it must reject the
request.
|outputs |one or more outputs where Bitcoins are to be sent. If the sum
of outputs.amount is zero, the customer will be asked how much to pay,
and the bitcoin client may choose any or all of the Outputs (if there
are more than one) for payment. If the sum of outputs.amount is
non-zero, then the customer will be asked to pay the sum, and the
payment shall be split among the Outputs with non-zero amounts (if there
are more than one; Outputs with zero amounts shall be ignored).
|time |Unix timestamp (seconds since 1-Jan-1970 UTC) when the
PaymentRequest was created.
|expires |Unix timestamp (UTC) after which the PaymentRequest should be
considered invalid.
|memo |UTF-8 encoded, plain-text (no formatting) note that should be
displayed to the customer, explaining what this PaymentRequest is for.
|payment_url |Secure (usually https) location where a Payment message
(see below) may be sent to obtain a PaymentACK.
|merchant_data |Arbitrary data that may be used by the merchant to
identify the PaymentRequest. May be omitted if the merchant does not
need to associate Payments with PaymentRequest or if they associate each
PaymentRequest with a separate payment address.
|=======================================================================
The payment_url specified in the PaymentDetails should remain valid at
least until the PaymentDetails expires (or as long as possible if the
PaymentDetails does not expire). Note that this is irrespective of any
state change in the underlying payment request; for example cancellation
of an order should not invalidate the payment_url, as it is important
that the merchant's server can record mis-payments in order to refund
the payment.
A PaymentRequest is PaymentDetails optionally tied to a merchant's
identity:
------------------------------------------------------------------
message PaymentRequest {
optional uint32 payment_details_version = 1 [default = 1];
optional string pki_type = 2 [default = "none"];
optional bytes pki_data = 3;
required bytes serialized_payment_details = 4;
optional bytes signature = 5;
}
------------------------------------------------------------------
[cols=",",]
|=======================================================================
|payment_details_version |See below for a discussion of
versioning/upgrading.
|pki_type |public-key infrastructure (PKI) system being used to identify
the merchant. All implementation should support "none", "x509+sha256"
and "x509+sha1".
|pki_data |PKI-system data that identifies the merchant and can be used
to create a digital signature. In the case of X.509 certificates,
pki_data contains one or more X.509 certificates (see Certificates
section below).
|serialized_payment_details |A protocol-buffer serialized PaymentDetails
message.
|signature |digital signature over a hash of the protocol buffer
serialized variation of the PaymentRequest message, with all fields
serialized in numerical order (all current protocol buffer
implementations serialize fields in numerical order) and signed using
the public key in pki_data. Before serialization, the signature field
must be set to an empty value so that the field is included in the
signed PaymentRequest hash but contains no data.
|=======================================================================
When a Bitcoin wallet application receives a PaymentRequest, it must
authorize payment by doing the following:
1. Validate the merchant's identity and signature using the PKI system,
if the pki_type is not "none".
2. Validate that customer's system unix time (UTC) is before
PaymentDetails.expires. If it is not, then the payment request must be
rejected.
3. Display the merchant's identity and ask the customer if they would
like to submit payment (e.g. display the "Common Name" in the first
X.509 certificate).
PaymentRequest messages larger than 50,000 bytes should be rejected by
the wallet application, to mitigate denial-of-service attacks.
[[payment]]
Payment
^^^^^^^
Payment messages are sent after the customer has authorized payment:
-----------------------------------------
message Payment {
optional bytes merchant_data = 1;
repeated bytes transactions = 2;
repeated Output refund_to = 3;
optional string memo = 4;
}
-----------------------------------------
[cols=",",]
|=======================================================================
|merchant_data |copied from PaymentDetails.merchant_data. Merchants may
use invoice numbers or any other data they require to match Payments to
PaymentRequests. Note that malicious clients may modify the
merchant_data, so should be authenticated in some way (for example,
signed with a merchant-only key).
|transactions |One or more valid, signed Bitcoin transactions that fully
pay the PaymentRequest
|refund_to |One or more outputs where the merchant may return funds, if
necessary. The merchant may return funds using these outputs for up to 2
months after the time of the payment request. After that time has
expired, parties must negotiate if returning of funds becomes necessary.
|memo |UTF-8 encoded, plain-text note from the customer to the merchant.
|=======================================================================
If the customer authorizes payment, then the Bitcoin client:
1. Creates and signs one or more transactions that satisfy (pay in
full) PaymentDetails.outputs
2. Validate that customer's system unix time (UTC) is still before
PaymentDetails.expires. If it is not, the payment should be cancelled.
3. Broadcast the transactions on the Bitcoin p2p network.
4. If PaymentDetails.payment_url is specified, POST a Payment message
to that URL. The Payment message is serialized and sent as the body of
the POST request.
Errors communicating with the payment_url server should be communicated
to the user. In the scenario where the merchant's server receives
multiple identical Payment messages for an individual PaymentRequest, it
must acknowledge each. The second and further PaymentACK messages sent
from the merchant's server may vary by memo field to indicate current
state of the Payment (for example number of confirmations seen on the
network). This is required in order to ensure that in case of a
transport level failure during transmission, recovery is possible by the
Bitcoin client re-sending the Payment message.
PaymentDetails.payment_url should be secure against man-in-the-middle
attacks that might alter Payment.refund_to (if using HTTP, it must be
TLS-protected).
Wallet software sending Payment messages via HTTP must set appropriate
Content-Type and Accept headers, as specified in BIP 71:
-----------------------------------------
Content-Type: application/bitcoin-payment
Accept: application/bitcoin-paymentack
-----------------------------------------
When the merchant's server receives the Payment message, it must
determine whether or not the transactions satisfy conditions of payment.
If and only if they do, if should broadcast the transaction(s) on the
Bitcoin p2p network.
Payment messages larger than 50,000 bytes should be rejected by the
merchant's server, to mitigate denial-of-service attacks.
[[paymentack]]
PaymentACK
^^^^^^^^^^
PaymentACK is the final message in the payment protocol; it is sent from
the merchant's server to the bitcoin wallet in response to a Payment
message:
-------------------------------------
message PaymentACK {
required Payment payment = 1;
optional string memo = 2;
}
-------------------------------------
[cols=",",]
|=======================================================================
|payment |Copy of the Payment message that triggered this PaymentACK.
Clients may ignore this if they implement another way of associating
Payments with PaymentACKs.
|memo |UTF-8 encoded note that should be displayed to the customer
giving the status of the transaction (e.g. "Payment of 1 BTC for eleven
tribbles accepted for processing.")
|=======================================================================
PaymentACK messages larger than 60,000 bytes should be rejected by the
wallet application, to mitigate denial-of-service attacks. This is
larger than the limits on Payment and PaymentRequest messages as
PaymentACK contains a full Payment message within it.
[[localization]]
Localization
~~~~~~~~~~~~
Merchants that support multiple languages should generate
language-specific PaymentRequests, and either associate the language
with the request or embed a language tag in the request's merchant_data.
They should also generate a language-specific PaymentACK based on the
original request.
For example: A greek-speaking customer browsing the Greek version of a
merchant's website clicks on a "Αγορά τώρα" link, which generates a
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The
customer pays, their bitcoin client sends a Payment message, and the
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".
[[certificates]]
Certificates
~~~~~~~~~~~~
The default PKI system is X.509 certificates (the same system used to
authenticate web servers). The format of pki_data when pki_type is
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate
chain:
---------------------------------------
message X509Certificates {
repeated bytes certificate = 1;
}
---------------------------------------
If pki_type is "x509+sha256", then the PaymentRequest message is hashed
using the SHA256 algorithm to produce the message digest that is signed.
If pki_type is "x509+sha1", then the SHA1 algorithm is used.
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The
certificate containing the public key of the entity that digitally
signed the PaymentRequest must be the first certificate. This MUST be
followed by additional certificates, with each subsequent certificate
being the one used to certify the previous one, up to (but not
including) a trusted root authority. The trusted root authority MAY be
included. The recipient must verify the certificate chain according to
[RFC5280] and reject the PaymentRequest if any validation failure
occurs.
Trusted root certificates may be obtained from the operating system; if
validation is done on a device without an operating system, the
http://www.mozilla.org/projects/security/certs/included/index.html[Mozilla
root store] is recommended.
[[extensibility]]
Extensibility
~~~~~~~~~~~~~
The protocol buffers serialization format is designed to be extensible.
In particular, new, optional fields can be added to a message and will
be ignored (but saved/re-transmitted) by old implementations.
PaymentDetails messages may be extended with new optional fields and
still be considered "version 1." Old implementations will be able to
validate signatures against PaymentRequests containing the new fields,
but (obviously) will not be able to display whatever information is
contained in the new, optional fields to the user.
If it becomes necessary at some point in the future for merchants to
produce PaymentRequest messages that are accepted *only* by new
implementations, they can do so by defining a new PaymentDetails message
with version=2. Old implementations should let the user know that they
need to upgrade their software when they get an up-version
PaymentDetails message.
Implementations that need to extend messages in this specification shall
use tags starting at 1000, and shall update the
link:bip-0070/extensions.mediawiki[extensions page] via pull-req to
avoid conflicts with other extensions.
[[references]]
References
~~~~~~~~~~
link:bip-0071.mediawiki[BIP 0071] : Payment Protocol mime types
link:bip-0072.mediawiki[BIP 0072] : Payment Protocol bitcoin: URI
extensions
Public-Key Infrastructure (X.509) working group :
http://datatracker.ietf.org/wg/pkix/charter/
Protocol Buffers : https://developers.google.com/protocol-buffers/
[[see-also]]
See Also
~~~~~~~~
Javascript Object Signing and Encryption working group :
http://datatracker.ietf.org/wg/jose/
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice
especially the list of Electronic Invoice standards
sipa's payment protocol proposal: https://gist.github.com/1237788
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :
http://arxiv.org/abs/1212.3257

308
selected BIPs/bip-0070.mediawiki
View File

@ -1,308 +0,0 @@
<pre>
BIP: 70
Title: Payment Protocol
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Draft
Type: Standards Track
Created: 2013-07-29
</pre>
==Abstract==
This BIP describes a protocol for communication between a merchant and their customer, enabling
both a better customer experience and better security against man-in-the-middle attacks on
the payment process.
==Motivation==
The current, minimal Bitcoin payment protocol operates as follows:
# Customer adds items to an online shopping basket, and decides to pay using Bitcoin.
# Merchant generates a unique payment address, associates it with the customer's order, and asks the customer to pay.
# Customer copies the Bitcoin address from the merchant's web page and pastes it into whatever wallet they are using OR follows a bitcoin: link and their wallet is launched with the amount to be paid.
# Customer authorizes payment to the merchant's address and broadcasts the transaction through the Bitcoin p2p network.
# Merchant's server detects payment and after sufficient transaction confirmations considers the transaction final.
This BIP extends the above protocol to support several new features:
# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "example.com" instead of an inscrutable, 34-character bitcoin address.
# Secure proof of payment, which the customer can use in case of a dispute with the merchant.
# Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet.
# Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment.
# Refund addresses, automatically given to the merchant by the customer's wallet software, so merchants do not have to contact customers before refunding overpayments or orders that cannot be fulfilled for some reason.
==Protocol==
This BIP describes payment protocol messages encoded using Google's Protocol
Buffers, authenticated using X.509 certificates, and communicated over
http/https. Future BIPs might extend this payment protocol to other
encodings, PKI systems, or transport protocols.
The payment protocol consists of three messages; PaymentRequest, Payment,
and PaymentACK, and begins with the customer somehow indicating that
they are ready to pay and the merchant's server responding with a
PaymentRequest message:
<img src=bip-0070/Protocol_Sequence.png></img>
==Messages==
The Protocol Buffers messages are defined in [[bip-0070/paymentrequest.proto|paymentrequest.proto]].
===Output===
Outputs are used in PaymentRequest messages to specify where a payment (or
part of a payment) should be sent. They are also used in Payment messages
to specify where a refund should be sent.
<pre>
message Output {
optional uint64 amount = 1 [default = 0];
optional bytes script = 2;
}
</pre>
{|
| amount || Number of satoshis (0.00000001 BTC) to be paid
|-
| script || a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.
|}
===PaymentDetails/PaymentRequest===
Payment requests are split into two messages to support future extensibility.
The bulk of the information is contained in the PaymentDetails message. It is
wrapped inside a PaymentRequest message, which contains meta-information
about the merchant and a digital signature.
<pre>
message PaymentDetails {
optional string network = 1 [default = "main"];
repeated Output outputs = 2;
required uint64 time = 3;
optional uint64 expires = 4;
optional string memo = 5;
optional string payment_url = 6;
optional bytes merchant_data = 7;
}
</pre>
{|
| network || either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.
|-
| outputs || one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored).
|-
| time || Unix timestamp (seconds since 1-Jan-1970 UTC) when the PaymentRequest was created.
|-
| expires || Unix timestamp (UTC) after which the PaymentRequest should be considered invalid.
|-
| memo || UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.
|-
| payment_url || Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.
|-
| merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.
|}
The payment_url specified in the PaymentDetails should remain valid at least until the PaymentDetails
expires (or as long as possible if the PaymentDetails does not expire). Note that this is irrespective of
any state change in the underlying payment request; for example cancellation of an order should not
invalidate the payment_url, as it is important that the merchant's server can record mis-payments
in order to refund the payment.
A PaymentRequest is PaymentDetails optionally tied to a merchant's identity:
<pre>
message PaymentRequest {
optional uint32 payment_details_version = 1 [default = 1];
optional string pki_type = 2 [default = "none"];
optional bytes pki_data = 3;
required bytes serialized_payment_details = 4;
optional bytes signature = 5;
}
</pre>
{|
| payment_details_version || See below for a discussion of versioning/upgrading.
|-
| pki_type || public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".
|-
| pki_data || PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data contains one or more X.509 certificates (see Certificates section below).
|-
| serialized_payment_details || A protocol-buffer serialized PaymentDetails message.
|-
| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, with all fields serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order) and signed using the public key in pki_data. Before serialization, the signature field must be set to an empty value so that the field is included in the signed PaymentRequest hash but contains no data.
|}
When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following:
# Validate the merchant's identity and signature using the PKI system, if the pki_type is not "none".
# Validate that customer's system unix time (UTC) is before PaymentDetails.expires. If it is not, then the payment request must be rejected.
# Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).
PaymentRequest messages larger than 50,000 bytes should be rejected by
the wallet application, to mitigate denial-of-service attacks.
===Payment===
Payment messages are sent after the customer has authorized payment:
<pre>
message Payment {
optional bytes merchant_data = 1;
repeated bytes transactions = 2;
repeated Output refund_to = 3;
optional string memo = 4;
}
</pre>
{|
| merchant_data || copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests. Note that malicious clients may modify the merchant_data, so should be authenticated in some way (for example, signed with a merchant-only key).
|-
| transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest
|-
| refund_to || One or more outputs where the merchant may return funds, if necessary. The merchant may return funds using these outputs for up to 2 months
after the time of the payment request. After that time has expired, parties must negotiate if returning of funds becomes necessary.
|-
| memo || UTF-8 encoded, plain-text note from the customer to the merchant.
|}
If the customer authorizes payment, then the Bitcoin client:
# Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs
# Validate that customer's system unix time (UTC) is still before PaymentDetails.expires. If it is not, the payment should be cancelled.
# Broadcast the transactions on the Bitcoin p2p network.
# If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.
Errors communicating with the payment_url server should be communicated to the user.
In the scenario where the merchant's server receives multiple identical Payment
messages for an individual PaymentRequest, it must acknowledge each. The second
and further PaymentACK messages sent from the merchant's server may vary by memo
field to indicate current state of the Payment (for example number of confirmations
seen on the network). This is required in order to ensure that in case of a transport
level failure during transmission, recovery is possible by the Bitcoin client
re-sending the Payment message.
PaymentDetails.payment_url should be secure against man-in-the-middle
attacks that might alter Payment.refund_to (if using HTTP, it must be
TLS-protected).
Wallet software sending Payment messages via HTTP must set appropriate
Content-Type and Accept headers, as specified in BIP 71:
<pre>Content-Type: application/bitcoin-payment
Accept: application/bitcoin-paymentack
</pre>
When the merchant's server receives the Payment message, it must
determine whether or not the transactions satisfy conditions of
payment. If and only if they do, if should broadcast the
transaction(s) on the Bitcoin p2p network.
Payment messages larger than 50,000 bytes should be rejected by
the merchant's server, to mitigate denial-of-service attacks.
===PaymentACK===
PaymentACK is the final message in the payment protocol; it is sent
from the merchant's server to the bitcoin wallet in response to a
Payment message:
<pre>
message PaymentACK {
required Payment payment = 1;
optional string memo = 2;
}
</pre>
{|
| payment || Copy of the Payment message that triggered this PaymentACK. Clients may ignore this if they implement another way of associating Payments with PaymentACKs.
|-
| memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")
|}
PaymentACK messages larger than 60,000 bytes should be rejected by
the wallet application, to mitigate denial-of-service attacks. This
is larger than the limits on Payment and PaymentRequest messages
as PaymentACK contains a full Payment message within it.
==Localization==
Merchants that support multiple languages should generate
language-specific PaymentRequests, and either associate the language
with the request or embed a language tag in the request's
merchant_data. They should also generate a language-specific
PaymentACK based on the original request.
For example: A greek-speaking customer browsing the Greek version of a
merchant's website clicks on a "Αγορά τώρα" link, which generates a
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The
customer pays, their bitcoin client sends a Payment message, and the
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".
==Certificates==
The default PKI system is X.509 certificates (the same system used to
authenticate web servers). The format of pki_data when pki_type is
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate
chain:
<pre>
message X509Certificates {
repeated bytes certificate = 1;
}
</pre>
If pki_type is "x509+sha256", then the PaymentRequest message is hashed using
the SHA256 algorithm to produce the message digest that is
signed. If pki_type is "x509+sha1", then the SHA1 algorithm is
used.
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The
certificate containing the public key of the entity that digitally
signed the PaymentRequest must be the first certificate. This MUST be
followed by additional certificates, with each subsequent certificate
being the one used to certify the previous one, up to (but not
including) a trusted root authority. The trusted root authority MAY be
included. The recipient must verify the certificate chain according to
[RFC5280] and reject the PaymentRequest if any validation failure
occurs.
Trusted root certificates may be obtained from the operating system;
if validation is done on a device without an operating system, the
[http://www.mozilla.org/projects/security/certs/included/index.html Mozilla root store] is recommended.
==Extensibility==
The protocol buffers serialization format is designed to be
extensible. In particular, new, optional fields can be added to a
message and will be ignored (but saved/re-transmitted) by old
implementations.
PaymentDetails messages may be extended with new optional fields and
still be considered "version 1." Old implementations will be able to
validate signatures against PaymentRequests containing the new fields,
but (obviously) will not be able to display whatever information is
contained in the new, optional fields to the user.
If it becomes necessary at some point in the future for merchants to
produce PaymentRequest messages that are accepted *only* by new
implementations, they can do so by defining a new PaymentDetails
message with version=2. Old implementations should let the user know
that they need to upgrade their software when they get an up-version
PaymentDetails message.
Implementations that need to extend messages in this specification shall use
tags starting at 1000, and shall update the
[[bip-0070/extensions.mediawiki|extensions page]] via pull-req to avoid
conflicts with other extensions.
==References==
[[bip-0071.mediawiki|BIP 0071]] : Payment Protocol mime types
[[bip-0072.mediawiki|BIP 0072]] : Payment Protocol bitcoin: URI extensions
Public-Key Infrastructure (X.509) working group :
http://datatracker.ietf.org/wg/pkix/charter/
Protocol Buffers : https://developers.google.com/protocol-buffers/
==See Also==
Javascript Object Signing and Encryption working group :
http://datatracker.ietf.org/wg/jose/
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice
especially the list of Electronic Invoice standards
sipa's payment protocol proposal: https://gist.github.com/1237788
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :
http://arxiv.org/abs/1212.3257

53
selected BIPs/bip-0071.asciidoc
View File

@ -1,53 +0,0 @@
--------------------------------------------------
BIP: 71
Title: Payment Protocol MIME types
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Draft
Type: Standards Track
Created: 2013-07-29
--------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP defines a MIME (RFC 2046) Media Type for Bitcoin payment
request messages.
[[motivation]]
Motivation
~~~~~~~~~~
Wallet or server software that sends payment protocol messages over
email or http should follow Internet standards for properly
encapsulating the messages.
[[specification]]
Specification
~~~~~~~~~~~~~
The Media Type (Content-Type in HTML/email headers) for bitcoin protocol
messages shall be:
[cols=",",]
|==================================================
|Message |Type/Subtype
|PaymentRequest |application/bitcoin-paymentrequest
|Payment |application/bitcoin-payment
|PaymentACK |application/bitcoin-paymentack
|==================================================
Payment protocol messages are encoded in binary.
[[example]]
Example
~~~~~~~
A web server generating a PaymentRequest message to initiate the payment
protocol would precede the binary message data with the following
headers:
------------------------------------------------
Content-Type: application/bitcoin-paymentrequest
Content-Transfer-Encoding: binary
------------------------------------------------

46
selected BIPs/bip-0071.mediawiki
View File

@ -1,46 +0,0 @@
<pre>
BIP: 71
Title: Payment Protocol MIME types
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Draft
Type: Standards Track
Created: 2013-07-29
</pre>
==Abstract==
This BIP defines a MIME (RFC 2046) Media Type for Bitcoin payment
request messages.
==Motivation==
Wallet or server software that sends payment protocol messages over
email or http should follow Internet standards for properly
encapsulating the messages.
==Specification==
The Media Type (Content-Type in HTML/email headers) for bitcoin
protocol messages shall be:
{|
| Message || Type/Subtype
|-
| PaymentRequest || application/bitcoin-paymentrequest
|-
| Payment || application/bitcoin-payment
|-
| PaymentACK || application/bitcoin-paymentack
|}
Payment protocol messages are encoded in binary.
==Example==
A web server generating a PaymentRequest message to initiate the
payment protocol would precede the binary message data with the
following headers:
<pre>
Content-Type: application/bitcoin-paymentrequest
Content-Transfer-Encoding: binary
</pre>

87
selected BIPs/bip-0072.asciidoc
View File

@ -1,87 +0,0 @@
-----------------------------------------------------
BIP: 72
Title: bitcoin: uri extensions for Payment Protocol
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Draft
Type: Standards Track
Created: 2013-07-29
-----------------------------------------------------
[[abstract]]
Abstract
~~~~~~~~
This BIP describes an extension to the bitcoin: URI scheme (BIP 21) to
support the payment protocol (BIP 70).
[[motivation]]
Motivation
~~~~~~~~~~
Allow users to click on a link in a web page or email to initiate the
payment protocol, while being backwards-compatible with existing bitcoin
wallets.
[[specification]]
Specification
~~~~~~~~~~~~~
The bitcoin: URI scheme is extended with an additional, optional "r"
parameter, whose value is a URL from which a PaymentRequest message
should be fetched (characters not allowed within the scope of a query
parameter must be percent-encoded as described in RFC 3986 and
bip-0021).
If the "r" parameter is provided and backwards compatibility is not
required, then the bitcoin address portion of the URI may be omitted
(the URI will be of the form: bitcoin:?r=... ).
When Bitcoin wallet software that supports this BIP receives a bitcoin:
URI with a request parameter, it should ignore the bitcoin
address/amount/label/message in the URI and instead fetch a
PaymentRequest message and then follow the payment protocol, as
described in BIP 70.
Bitcoin wallets must support fetching PaymentRequests via http and https
protocols; they may support other protocols. Wallets must include an
"Accept" HTTP header in HTTP(s) requests (as defined in RFC 2616):
------------------------------------------
Accept: application/bitcoin-paymentrequest
------------------------------------------
If a PaymentRequest cannot be obtained (perhaps the server is
unavailable), then the customer should be informed that the merchant's
payment processing system is unavailable. In the case of an HTTP
request, status codes which are neither success nor error (such as
redirect) should be handled as outlined in RFC 2616.
[[compatibility]]
Compatibility
~~~~~~~~~~~~~
Wallet software that does not support this BIP will simply ignore the r
parameter and will initiate a payment to bitcoin address.
[[examples]]
Examples
~~~~~~~~
A backwards-compatible request:
------------------------------------------------------------------------------------------------------
bitcoin:mq7se9wy2egettFxPbmn99cK8v5AFq55Lx?amount=0.11&r=https://merchant.com/pay.php?h%3D2a8628fc2fbe
------------------------------------------------------------------------------------------------------
Non-backwards-compatible equivalent:
--------------------------------------------------------
bitcoin:?r=https://merchant.com/pay.php?h%3D2a8628fc2fbe
--------------------------------------------------------
[[references]]
References
~~~~~~~~~~
http://www.w3.org/Protocols/rfc2616/rfc2616.html[RFC 2616] : Hypertext
Transfer Protocol -- HTTP/1.1

69
selected BIPs/bip-0072.mediawiki
View File

@ -1,69 +0,0 @@
<pre>
BIP: 72
Title: bitcoin: uri extensions for Payment Protocol
Author: Gavin Andresen <gavinandresen@gmail.com>
Status: Draft
Type: Standards Track
Created: 2013-07-29
</pre>
==Abstract==
This BIP describes an extension to the bitcoin: URI scheme (BIP 21) to
support the payment protocol (BIP 70).
==Motivation==
Allow users to click on a link in a web page or email to initiate the
payment protocol, while being backwards-compatible with existing
bitcoin wallets.
==Specification==
The bitcoin: URI scheme is extended with an additional, optional
"r" parameter, whose value is a URL from which a PaymentRequest
message should be fetched (characters not allowed within the scope
of a query parameter must be percent-encoded as described in RFC 3986
and bip-0021).
If the "r" parameter is provided and backwards compatibility
is not required, then the bitcoin address portion of the URI may be
omitted (the URI will be of the form: bitcoin:?r=... ).
When Bitcoin wallet software that supports this BIP receives a
bitcoin: URI with a request parameter, it should ignore the bitcoin
address/amount/label/message in the URI and instead fetch a
PaymentRequest message and then follow the payment protocol, as
described in BIP 70.
Bitcoin wallets must support fetching PaymentRequests via http and
https protocols; they may support other protocols. Wallets must
include an "Accept" HTTP header in HTTP(s) requests (as defined
in RFC 2616):
<pre>Accept: application/bitcoin-paymentrequest</pre>
If a PaymentRequest cannot be obtained (perhaps the server is
unavailable), then the customer should be informed that the merchant's
payment processing system is unavailable. In the case of an HTTP
request, status codes which are neither success nor error (such as
redirect) should be handled as outlined in RFC 2616.
==Compatibility==
Wallet software that does not support this BIP will simply ignore the
r parameter and will initiate a payment to bitcoin address.
==Examples==
A backwards-compatible request:
<pre>
bitcoin:mq7se9wy2egettFxPbmn99cK8v5AFq55Lx?amount=0.11&r=https://merchant.com/pay.php?h%3D2a8628fc2fbe
</pre>
Non-backwards-compatible equivalent:
<pre>
bitcoin:?r=https://merchant.com/pay.php?h%3D2a8628fc2fbe
</pre>
==References==
[[http://www.w3.org/Protocols/rfc2616/rfc2616.html|RFC 2616]] : Hypertext Transfer Protocol -- HTTP/1.1

4852
selected BIPs/bips.asciidoc
View File

File diff suppressed because it is too large Load Diff