diff --git a/appdx-bips.asciidoc b/appdx-bips.asciidoc index d150fa7f..01dd7e66 100644 --- a/appdx-bips.asciidoc +++ b/appdx-bips.asciidoc @@ -1,4876 +1,133 @@ -++++ - -++++ +== Appendix - Bitcoin Improvement Proposals -= Appendix: Selected Bitcoin Improvement Proposals (BIPs) +Bitcoin Improvement Proposals are design documents providing information to the Bitcoin community, or describing a new feature for Bitcoin or its processes or environment. -== Introduction +As per BIP0001 _BIP Purpose and Guidelines_, there are three kinds of BIP: -A Bitcoin Improvement Proposal, or "BIP" is a design document that, through a process of comment, review and community consensus can become an influential standard for the improvement of the bitcoin system. This appendix contains a number of selected BIPs that are important in the history and future of bitcoin. The original BIPs can be found on github at https://github.com/bitcoin/bips, which is considered the authoritative source for BIPs. They are included here as a handy reference. +* 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. -++++ - -++++ +Bitcoin Improvement Proposals are recorded in a versioned repository on Github at https://github.com/bitcoin/bips. The list below is a snapshot of BIPs in the Fall of 2014. Consult the authoritative repository for up-to-date information on existing BIPs and their contents. -= BIP 1: BIP Purpose and Guidelines ------------------------------------ - 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: - Title: - Author: -* Discussions-To: - Status: - Type: - Created: -* Post-History: -* Replaces: -* Superseded-By: -* Resolution: -------------------------------------------------------------------- - -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. - -++++ - -++++ - -= BIP 11: M-of-N Standard Transactions - --------------------------------------------------- - BIP: 11 - Title: M-of-N Standard Transactions - Author: Gavin Andresen - 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] - --------------------------------------------------- - BIP: 13 - Title: Address Format for pay-to-script-hash - Author: Gavin Andresen - 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] - ------------------------------------------------------------- - BIP: 14 - Title: BIP Protocol Version and User Agent - Author: Amir Taaki - Patrick Strateman - 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. --------------------------------------------------- --------------------------------------------------- - BIP: 16 - Title: Pay to Script Hash - Author: Gavin Andresen - 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 -~~~~~~~~~~ - ---------------------------------------------------- - BIP: 21 - Title: URI Scheme - Author: Nils Schneider - Matt Corallo - 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, are placeholders - -`bitcoin:
[?amount=][?label=