++++ ++++ = 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=