diff --git a/appdx-bips.asciidoc b/appdx-bips.asciidoc new file mode 100644 index 00000000..d150fa7f --- /dev/null +++ b/appdx-bips.asciidoc @@ -0,0 +1,4876 @@ +++++ + +++++ + += Appendix: Selected Bitcoin Improvement Proposals (BIPs) + +== Introduction + +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. + +++++ + +++++ + += 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=