diff options
| -rw-r--r-- | README.mediawiki | 13 | ||||
| -rw-r--r-- | bip-0001.mediawiki | 3 | ||||
| -rw-r--r-- | bip-0032.mediawiki | 2 | ||||
| -rw-r--r-- | bip-0038.mediawiki | 12 | ||||
| -rw-r--r-- | bip-0039.mediawiki | 4 | ||||
| -rw-r--r-- | bip-0043.mediawiki | 61 | ||||
| -rw-r--r-- | bip-0044.mediawiki | 262 | ||||
| -rw-r--r-- | bip-0061.mediawiki | 153 | ||||
| -rw-r--r-- | bip-0070.mediawiki | 58 | ||||
| -rw-r--r-- | bip-0070/extensions.mediawiki | 9 | ||||
| -rw-r--r-- | bip-0070/paymentrequest.proto | 6 | ||||
| -rw-r--r-- | bip-0071.mediawiki | 2 | ||||
| -rw-r--r-- | bip-0072.mediawiki | 14 |
13 files changed, 574 insertions, 25 deletions
diff --git a/README.mediawiki b/README.mediawiki index 816531b..3103d74 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -180,7 +180,18 @@ Those proposing changes should consider that ultimately consent may rest with th | Pieter Wuille | Standard | Draft -<!-- 43-49 reserved for stratum extensions --> +|- +| [[bip-0043.mediawiki|43]] +| Purpose Field for Deterministic Wallets +| Slush +| Standard +| Draft +|- +| [[bip-0044.mediawiki|44]] +| Multi-Account Hierarchy for Deterministic Wallets +| Slush +| Standard +| Draft |- | [[bip-0050.mediawiki|50]] | March 2013 Chain Fork Post-Mortem diff --git a/bip-0001.mediawiki b/bip-0001.mediawiki index c9857a8..5c8a544 100644 --- a/bip-0001.mediawiki +++ b/bip-0001.mediawiki @@ -12,8 +12,7 @@ BIP stands for Bitcoin Improvement Proposal. A BIP is a design document providin 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 -. +Because the BIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. ==BIP Types== There are three kinds of BIP: diff --git a/bip-0032.mediawiki b/bip-0032.mediawiki index fdc9613..0563d35 100644 --- a/bip-0032.mediawiki +++ b/bip-0032.mediawiki @@ -271,6 +271,8 @@ A JavaScript implementation is available at https://github.com/sarchar/brainwall A PHP implemetation is available at https://github.com/Bit-Wasp/bitcoin-lib-php +A C# implementation is available at https://github.com/NicolasDorier/NBitcoin (ExtKey, ExtPubKey) + ==Acknowledgements== * Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it. diff --git a/bip-0038.mediawiki b/bip-0038.mediawiki index 1fd9d91..29fe21e 100644 --- a/bip-0038.mediawiki +++ b/bip-0038.mediawiki @@ -78,7 +78,7 @@ To keep the size of the encrypted key down, no initialization vectors (IVs) are * Range in base58check encoding for EC-multiplied keys without compression (prefix 6Pf): ** Minimum value: 6PfKzduKZXAFXWMtJ19Vg9cSvbFg4va6U8p2VWzSjtHQCCLk3JSBpUvfpf (based on 01 43 00 plus thirty-six 00's) ** Maximum value: 6PfYiPy6Z7BQAwEHLxxrCEHrH9kasVQ95ST1NnuEnnYAJHGsgpNPQ9dTHc (based on 01 43 00 plus thirty-six FF's) -* Range in base58check encoding for non-EC-multiplied keys with compression (prefix 6Pn): +* Range in base58check encoding for EC-multiplied keys with compression (prefix 6Pn): ** Minimum value: 6PnM2wz9LHo2BEAbvoGpGjMLGXCom35XwsDQnJ7rLiRjYvCxjpLenmoBsR (based on 01 43 20 plus thirty-six 00's) ** Maximum value: 6PnZki3vKspApf2zym6Anp2jd5hiZbuaZArPfa2ePcgVf196PLGrQNyVUh (based on 01 43 20 plus thirty-six FF's) @@ -88,7 +88,7 @@ Encrypting a private key without the EC multiplication offers the advantage that Encryption steps: # Compute the Bitcoin address (ASCII), and take the first four bytes of SHA256(SHA256()) of it. Let's call this "addresshash". # Derive a key from the passphrase using scrypt -#*Parameters: ''passphrase'' is the passphrase itself encoded in UTF-8. ''addresshash'' came from the earlier step, n=16384, r=8, p=8, length=64 (n, r, p are provisional and subject to consensus) +#*Parameters: ''passphrase'' is the passphrase itself encoded in UTF-8. salt is ''addresshash'' from the earlier step, n=16384, r=8, p=8, length=64 (n, r, p are provisional and subject to consensus) #*Let's split the resulting 64 bytes in half, and call them ''derivedhalf1'' and ''derivedhalf2''. # Do AES256Encrypt(bitcoinprivkey[0...15] xor derivedhalf1[0...15], derivedhalf2), call the 16-byte result ''encryptedhalf1'' # Do AES256Encrypt(bitcoinprivkey[16...31] xor derivedhalf1[16...31], derivedhalf2), call the 16-byte result ''encryptedhalf2'' @@ -124,7 +124,7 @@ Steps performed by ''owner'' to generate a single intermediate code, if lot and #* Take SHA256(SHA256(''prefactor'' + ''ownerentropy'')) and call this ''passfactor''. The "+" operator is concatenation. # Compute the elliptic curve point G * ''passfactor'', and convert the result to compressed notation (33 bytes). Call this ''passpoint''. Compressed notation is used for this purpose regardless of whether the intent is to create Bitcoin addresses with or without compressed public keys. # Convey ''ownersalt'' and ''passpoint'' to the party generating the keys, along with a checksum to ensure integrity. -#* The following Base58Check-encoded format is recommended for this purpose: magic bytes "2C E9 B3 E1 FF 39 E2 51" followed by ''ownerentropy'', and then ''passpoint''. The resulting string will start with the word "passphrase" due to the constant bytes, will be 72 characters in length, and encodes 49 bytes (8 bytes constant + 8 bytes ''ownersalt'' + 33 bytes ''passpoint''). The checksum is handled in the Base58Check encoding. The resulting string is called ''intermediate_passphrase_string''. +#* The following Base58Check-encoded format is recommended for this purpose: magic bytes "2C E9 B3 E1 FF 39 E2 51" followed by ''ownerentropy'', and then ''passpoint''. The resulting string will start with the word "passphrase" due to the constant bytes, will be 72 characters in length, and encodes 49 bytes (8 bytes constant + 8 bytes ''ownerentropy'' + 33 bytes ''passpoint''). The checksum is handled in the Base58Check encoding. The resulting string is called ''intermediate_passphrase_string''. If lot and sequence numbers are not being included, then follow the same procedure with the following changes: * ''ownersalt'' is 8 random bytes instead of 4, and ''lotsequence'' is omitted. ''ownerentropy'' becomes an alias for ''ownersalt''. @@ -162,6 +162,12 @@ The result is a Base58Check-encoded concatenation of the following: A confirmation tool, given a passphrase and a confirmation code, can recalculate the address, verify the address hash, and then assert the following: "It is confirmed that Bitcoin address ''address'' depends on this passphrase". If applicable: "The lot number is ''lotnumber'' and the sequence number is ''sequencenumber''." +To recalculate the address: +# Derive ''passfactor'' using scrypt with ''ownerentropy'' and the user's passphrase and use it to recompute ''passpoint'' +# Derive decryption key for ''pointb'' using scrypt with ''passpoint'', ''addresshash'', and ''ownerentropy'' +# Decrypt ''encryptedpointb'' to yield ''pointb'' +# ECMultiply ''pointb'' by ''passfactor''. Use the resulting EC point as a public key and hash it into ''address'' using either compressed or uncompressed public key methodology as specifid in ''flagbyte''. + =====Decryption===== # Collect encrypted private key and passphrase from user. # Derive ''passfactor'' using scrypt with ''ownersalt'' and the user's passphrase and use it to recompute ''passpoint'' diff --git a/bip-0039.mediawiki b/bip-0039.mediawiki index cfa3bd5..2fd8ad0 100644 --- a/bip-0039.mediawiki +++ b/bip-0039.mediawiki @@ -123,3 +123,7 @@ Reference implementation including wordlists is available from http://github.com/trezor/python-mnemonic +==Other Implementations== + +Objective-C - https://github.com/nybex/NYMnemonic + diff --git a/bip-0043.mediawiki b/bip-0043.mediawiki new file mode 100644 index 0000000..14936f6 --- /dev/null +++ b/bip-0043.mediawiki @@ -0,0 +1,61 @@ +<pre> + BIP: BIP-0043 + Title: Purpose Field for Deterministic Wallets + Authors: Marek Palatinus <slush@satoshilabs.com> + Pavol Rusnak <stick@satoshilabs.com> + Status: Draft + Type: Standards Track + Created: 2014-04-24 +</pre> + +==Abstract== + +This BIP introduces a "Purpose Field" for use in deterministic wallets +based on algorithm described in BIP-0032 (BIP32 from now on). + +==Motivation== + +Although Hierarchical Deterministic Wallet structure as described by BIP32 +is an important step in user experience and security of the cryptocoin wallets, +the BIP32 specification offers implementors too many degrees of freedom. +Multiple implementations may claim they are BIP32 compatible, but in fact +they can produce wallets with different logical structures making them +non-interoperable. This situation unfortunately renders "BIP32 compatible" +statement rather useless. + + +==Purpose== + +We propose the first level of BIP32 tree structure to be used as "purpose". +This purpose determines the further structure beneath this node. + +<pre> +m / purpose' / * +</pre> + +Apostrophe indicates that BIP32 hardened derivation is used. + +We encourage different schemes to apply for assigning a separate BIP number +and use the same number for purpose field, so addresses won't be generated +from overlapping BIP32 spaces. + +Example: Scheme described in BIP44 should use 44' (or 0x8000002C) as purpose. + +Not all wallets may want to support the full range of features and possibilities +described in these BIPs. Instead of choosing arbitrary subset of defined features +and calling themselves BIPxx compatible, we suggest that software which needs +only a limited structure should describe such structure in another BIP and use +different "purpose" value. + + +==Node serialization== + +Because this scheme can be used to generate nodes for more cryptocurrencies +at once, or even something totally unrelated to cryptocurrencies, there's no +point in using a special version magic described in section "Serialization +format" of BIP32. We suggest to use always 0x0488B21E for public and 0x0488ADE4 +for private nodes (leading to prefixes "xpub" and "xprv" respectively). + +==Reference== + +* [[bip-0032.mediawiki|BIP32 - Hierarchical Deterministic Wallets]] diff --git a/bip-0044.mediawiki b/bip-0044.mediawiki new file mode 100644 index 0000000..df6f8e6 --- /dev/null +++ b/bip-0044.mediawiki @@ -0,0 +1,262 @@ +<pre> + BIP: BIP-0044 + Title: Multi-Account Hierarchy for Deterministic Wallets + Authors: Marek Palatinus <slush@satoshilabs.com> + Pavol Rusnak <stick@satoshilabs.com> + Status: Draft + Type: Standards Track + Created: 2014-04-24 +</pre> + +==Abstract== + +This BIP defines a logical hierarchy for deterministic wallets based on an algorithm +described in BIP-0032 (BIP32 from now on) and purpose scheme described in +BIP-0043 (BIP43 from now on). + +This BIP is a particular application of BIP43. + +==Motivation== + +The hierarchy proposed in this paper is quite comprehensive. It allows the handling of +multiple coins, multiple accounts, external and internal chains per account and +millions of addresses per chain. + +==Path levels== + +We define the following 5 levels in BIP32 path: + +<pre> +m / purpose' / coin_type' / account' / change / address_index +</pre> + +Apostrophe in the path indicates that BIP32 hardened derivation is used. + +Each level has a special meaning, described in the chapters below. + +===Purpose=== + +Purpose is a constant set to 44' (or 0x8000002C) following the BIP43 recommendation. +It indicates that the subtree of this node is used according to this specification. + +Hardened derivation is used at this level. + +===Coin type=== + +One master node (seed) can be used for unlimited number of independent +cryptocoins such as Bitcoin, Litecoin or Namecoin. However, sharing the same +space for various cryptocoins has some disadvantages. + +This level creates a separate subtree for every cryptocoin, avoiding +reusing addresses across cryptocoins and improving privacy issues. + +Coin type is a constant, set for each cryptocoin. Cryptocoin developers may ask +for registering unused number for their project. + +The list of already allocated coin types is in the chapter +"Registered coin types" below. + +Hardened derivation is used at this level. + +===Account=== + +This level splits the key space into independent user identities, +so the wallet never mixes the coins across different accounts. + +Users can use these accounts to organize the funds in the same +fashion as bank accounts; for donation purposes (where all +addresses are considered public), for saving purposes, +for common expenses etc. + +Accounts are numbered from index 0 in sequentially increasing manner. +This number is used as child index in BIP32 derivation. + +Hardened derivation is used at this level. + +Software should prevent a creation of an account if a previous account does not +have a transaction history (meaning none of its addresses have been used before). + +Software needs to discover all used accounts after importing the seed from +an external source. Such an algorithm is described in "Account discovery" chapter. + +===Change=== + +Constant 0 is used for external chain and constant 1 for internal chain (also +known as change addresses). External chain is used for addresses that are meant +to be visible outside of the wallet (e.g. for receiving payments). Internal +chain is used for addresses which are not meant to be visible outside of the +wallet and is used for return transaction change. + +Public derivation is used at this level. + +===Index=== + +Addresses are numbered from index 0 in sequentially increasing manner. +This number is used as child index in BIP32 derivation. + +Public derivation is used at this level. + +==Account discovery== + +When the master seed is imported from an external source the software should +start to discover the accounts in the following manner: + +# derive the first account's node (index = 0) +# derive the external chain node of this account +# scan addresses of the external chain; respect the gap limit described below +# if no transactions are found on the external chain, stop discovery +# if there are some transactions, increase the account index and go to step 1 + +This algorithm is successful because software should disallow creation of new +accounts if previous one has no transaction history, as described in chapter +"Account" above. + +Please note that the algorithm works with the transaction history, not account +balances, so you can have an account with 0 total coins and the algorithm will +still continue with discovery. + +===Address gap limit=== + +Address gap limit is currently set to 20. If the software hits 20 unused +addresses in a row, it expects there are no used addresses beyond this point +and stops searching the address chain. We scan just the external chains, because +internal chains receive only coins that come from the associated external chains. + +Wallet software should warn when the user is trying to exceed the gap limit on +an external chain by generating a new address. + +==Registered coin types== + +These are the registered coin types for usage in level 2 of BIP44 described in +chapter "Coin type" above. + +All these constants are used as hardened derivation. + +{| +!index +!hexa +!coin +|- +|0 +|0x80000000 +|Bitcoin +|- +|1 +|0x80000001 +|Bitcoin Testnet +|} + +==Examples== + +{| +!coin +!account +!chain +!address +!path +|- +|Bitcoin +|first +|external +|first +|m / 44' / 0' / 0' / 0 / 0 +|- +|Bitcoin +|first +|external +|second +|m / 44' / 0' / 0' / 0 / 1 +|- +|Bitcoin +|first +|change +|first +|m / 44' / 0' / 0' / 1 / 0 +|- +|Bitcoin +|first +|change +|second +|m / 44' / 0' / 0' / 1 / 1 +|- +|Bitcoin +|second +|external +|first +|m / 44' / 0' / 1' / 0 / 0 +|- +|Bitcoin +|second +|external +|second +|m / 44' / 0' / 1' / 0 / 1 +|- +|Bitcoin +|second +|change +|first +|m / 44' / 0' / 1' / 1 / 0 +|- +|Bitcoin +|second +|change +|second +|m / 44' / 0' / 1' / 1 / 1 +|- +|Bitcoin Testnet +|first +|external +|first +|m / 44' / 1' / 0' / 0 / 0 +|- +|Bitcoin Testnet +|first +|external +|second +|m / 44' / 1' / 0' / 0 / 1 +|- +|Bitcoin Testnet +|first +|change +|first +|m / 44' / 1' / 0' / 1 / 0 +|- +|Bitcoin Testnet +|first +|change +|second +|m / 44' / 1' / 0' / 1 / 1 +|- +|Bitcoin Testnet +|second +|external +|first +|m / 44' / 1' / 1' / 0 / 0 +|- +|Bitcoin Testnet +|second +|external +|second +|m / 44' / 1' / 1' / 0 / 1 +|- +|Bitcoin Testnet +|second +|change +|first +|m / 44' / 1' / 1' / 1 / 0 +|- +|Bitcoin Testnet +|second +|change +|second +|m / 44' / 1' / 1' / 1 / 1 +|} + +==Compatible wallets== + +* [[https://mytrezor.com|myTREZOR web wallet]] ([[https://github.com/trezor/webwallet|source]]) + +==Reference== + +* [[bip-0032.mediawiki|BIP32 - Hierarchical Deterministic Wallets]] +* [[bip-0043.mediawiki|BIP43 - Purpose Field for Deterministic Wallets]] diff --git a/bip-0061.mediawiki b/bip-0061.mediawiki new file mode 100644 index 0000000..a18a4e6 --- /dev/null +++ b/bip-0061.mediawiki @@ -0,0 +1,153 @@ +<pre> + BIP: 61 + Title: Reject P2P message + Author: Gavin Andresen <gavinandresen@gmail.com> + Status: Final + Type: Standards Track + Created: 2014-06-18 +</pre> + +==Abstract== + +This BIP describes a new message type for the Bitcoin peer-to-peer network. + +==Motivation== + +Giving peers feedback about why their blocks or transactions are rejected, or +why they are being banned for not following the protocol helps +interoperability between different implementations. + +It also gives SPV (simplified payment verification) clients a hint that something +may be wrong when their transactions are rejected due to insufficient priority +or fees. + +==Specification== + +Data types in this specification are as described at https://en.bitcoin.it/wiki/Protocol_specification + +===reject=== + +One new message type "reject" is introduced. It is sent directly to a peer in response to a "version", "tx" or "block" message. + +For example, the message flow between two peers for a relayed transaction that is rejected for some reason would be: + + --> inv + <-- getdata + --> tx + <-- reject + +All implementations of the P2P protocol version 70,002 and later should support the reject message. + +====common payload==== + + +Every reject message begins with the following fields. Some messages append extra, message-specific data. + +{| +| Field Size || Name || Data type || Comments +|- +| variable || response-to-msg || var_str || Message that triggered the reject +|- +| 1 || reject-code || uint8_t || 0x01 through 0x4f (see below) +|- +| variable || reason || var_string || Human-readable message for debugging +|} + +The human-readable string is intended only for debugging purposes; in particular, different implementations may +use different strings. The string should not be shown to users or used for anthing besides diagnosing +interoperability problems. + +The following reject code categories are used; in the descriptions below, "server" is the peer generating +the reject message, "client" is the peer that will receive the message. + +{| +| Range || Category +|- +| 0x01-0x0f || Protocol syntax errors +|- +| 0x10-0x1f || Protocol semantic errors +|- +| 0x40-0x4f || Server policy rule +|} + +==== rejection codes common to all message types ==== + +{| +| Code || Description +|- +| 0x01 || Message could not be decoded +|} + +==== reject version codes ==== + +Codes generated during the intial connection process in response to a "version" message: + +{| +| Code || Description +|- +| 0x11 || Client is an obsolete, unsupported version +|- +| 0x12 || Duplicate version message received +|} + +==== reject tx payload, codes ==== + +Transaction rejection messages extend the basic message with the transaction id hash: + +{| +| Field Size || Name || Data type || Comments +|- +| 32 || hash || char[32] || transaction that is rejected +|} + +The following codes are used: + +{| +| Code || Description +|- +| 0x10 || Transaction is invalid for some reason (invalid signature, output value greater than input, etc.) +|- +| 0x40 || Not mined/relayed because it is "non-standard" (type or version unknown by the server) +|- +| 0x41 || One or more output amounts are below the 'dust' threshold +|- +| 0x42 || Transaction does not have enough fee/priority to be relayed or mined +|} + +==== payload, reject block ==== + +Block rejection messages extend the basic message with the block header hash: + +{| +| Field Size || Name || Data type || Comments +|- +| 32 || hash || char[32] || block (hash of block header) that is rejected +|} + +Rejection codes: + +{| +| code || description +|- +| 0x10 || Block is invalid for some reason (invalid proof-of-work, invalid signature, etc) +|- +| 0x11 || Block's version is no longer supported +|- +| 0x43 || Inconsistent with a compiled-in checkpoint +|} + +Note: blocks that are not part of the server's idea of the current best chain, but are otherwise valid, should not trigger reject messages. + +== Compatibility == + +The reject message is backwards-compatible; older peers that do not recognize the reject message will ignore it. + +== Implementation notes == + +Implementors must consider what happens if an attacker either sends them +reject messages for valid transactions/blocks or sends them random +reject messages, and should beware of possible denial-of-service attacks. +For example, notifying the user of every reject message received +would make it trivial for an attacker to mount an annoy-the-user attack. +Even merely writing every reject message to a debugging log could make +an implementation vulnerable to a fill-up-the-users-disk attack. diff --git a/bip-0070.mediawiki b/bip-0070.mediawiki index 3e861db..03baf5b 100644 --- a/bip-0070.mediawiki +++ b/bip-0070.mediawiki @@ -1,8 +1,8 @@ <pre> BIP: 70 Title: Payment Protocol - Author: Gavin Andresen <gavinandresen@gmail.com> - Status: Draft + Authors: Gavin Andresen <gavinandresen@gmail.com>, Mike Hearn <mhearn@bitcoinfoundation.org> + Status: Final Type: Standards Track Created: 2013-07-29 </pre> @@ -25,7 +25,7 @@ The current, minimal Bitcoin payment protocol operates as follows: This BIP extends the above protocol to support several new features: -# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "website.com" instead of an inscrutable, 34-character bitcoin address. +# Human-readable, secure payment destinations-- customers will be asked to authorize payment to "example.com" instead of an inscrutable, 34-character bitcoin address. # Secure proof of payment, which the customer can use in case of a dispute with the merchant. # Resistance from man-in-the-middle attacks that replace a merchant's bitcoin address with an attacker's address before a transaction is authorized with a hardware wallet. # Payment received messages, so the customer knows immediately that the merchant has received, and has processed (or is processing) their payment. @@ -99,6 +99,12 @@ about the merchant and a digital signature. | merchant_data || Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address. |} +The payment_url specified in the PaymentDetails should remain valid at least until the PaymentDetails +expires (or as long as possible if the PaymentDetails does not expire). Note that this is irrespective of +any state change in the underlying payment request; for example cancellation of an order should not +invalidate the payment_url, as it is important that the merchant's server can record mis-payments +in order to refund the payment. + A PaymentRequest is PaymentDetails optionally tied to a merchant's identity: <pre> message PaymentRequest { @@ -118,7 +124,11 @@ A PaymentRequest is PaymentDetails optionally tied to a merchant's identity: |- | serialized_payment_details || A protocol-buffer serialized PaymentDetails message. |- -| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data. +| signature || digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, +with all serialized fields serialized in numerical order (all current protocol buffer implementations serialize +fields in numerical order) and signed using the public key in pki_data. Optional fields that are not set +are not serialized (however, setting a field to its default value will cause it to be serialized and will affect +the signature). Before serialization, the signature field must be set to an empty value so that the field is included in the signed PaymentRequest hash but contains no data. |} When a Bitcoin wallet application receives a PaymentRequest, it must authorize payment by doing the following: @@ -145,17 +155,26 @@ Payment messages are sent after the customer has authorized payment: |- | transactions || One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest |- -| refund_to || One or more outputs where the merchant may return funds, if necessary. +| refund_to || One or more outputs where the merchant may return funds, if necessary. The merchant may return funds using these outputs for up to 2 months +after the time of the payment request. After that time has expired, parties must negotiate if returning of funds becomes necessary. |- | memo || UTF-8 encoded, plain-text note from the customer to the merchant. |} If the customer authorizes payment, then the Bitcoin client: # Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs +# Validate that customer's system unix time (UTC) is still before PaymentDetails.expires. If it is not, the payment should be cancelled. # Broadcast the transactions on the Bitcoin p2p network. # If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request. Errors communicating with the payment_url server should be communicated to the user. +In the scenario where the merchant's server receives multiple identical Payment +messages for an individual PaymentRequest, it must acknowledge each. The second +and further PaymentACK messages sent from the merchant's server may vary by memo +field to indicate current state of the Payment (for example number of confirmations +seen on the network). This is required in order to ensure that in case of a transport +level failure during transmission, recovery is possible by the Bitcoin client +re-sending the Payment message. PaymentDetails.payment_url should be secure against man-in-the-middle attacks that might alter Payment.refund_to (if using HTTP, it must be @@ -172,6 +191,9 @@ determine whether or not the transactions satisfy conditions of payment. If and only if they do, if should broadcast the transaction(s) on the Bitcoin p2p network. +Payment messages larger than 50,000 bytes should be rejected by +the merchant's server, to mitigate denial-of-service attacks. + ===PaymentACK=== PaymentACK is the final message in the payment protocol; it is sent @@ -189,6 +211,11 @@ Payment message: | memo || UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.") |} +PaymentACK messages larger than 60,000 bytes should be rejected by +the wallet application, to mitigate denial-of-service attacks. This +is larger than the limits on Payment and PaymentRequest messages +as PaymentACK contains a full Payment message within it. + ==Localization== Merchants that support multiple languages should generate @@ -221,10 +248,11 @@ used. Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The certificate containing the public key of the entity that digitally -signed the PaymentRequest must be the first certificate. This MAY be +signed the PaymentRequest must be the first certificate. This MUST be followed by additional certificates, with each subsequent certificate -being the one used to certify the previous one, up to a trusted root -authority. The recipient must verify the certificate chain according to +being the one used to certify the previous one, up to (but not +including) a trusted root authority. The trusted root authority MAY be +included. The recipient must verify the certificate chain according to [RFC5280] and reject the PaymentRequest if any validation failure occurs. @@ -252,10 +280,10 @@ message with version=2. Old implementations should let the user know that they need to upgrade their software when they get an up-version PaymentDetails message. -Implementations that need to extend messages in this specification -shall use tags starting at 1000, and shall update the wiki page at -https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with -other extensions. +Implementations that need to extend messages in this specification shall use +tags starting at 1000, and shall update the +[[bip-0070/extensions.mediawiki|extensions page]] via pull-req to avoid +conflicts with other extensions. ==References== @@ -268,6 +296,12 @@ http://datatracker.ietf.org/wg/pkix/charter/ Protocol Buffers : https://developers.google.com/protocol-buffers/ +==Reference implementation== + +Create Payment Request generator : https://bitcoincore.org/~gavin/createpaymentrequest.php ([[https://github.com/gavinandresen/paymentrequest|source]]) + +BitcoinJ : https://bitcoinj.github.io/payment-protocol#introduction + ==See Also== Javascript Object Signing and Encryption working group : diff --git a/bip-0070/extensions.mediawiki b/bip-0070/extensions.mediawiki new file mode 100644 index 0000000..51400d8 --- /dev/null +++ b/bip-0070/extensions.mediawiki @@ -0,0 +1,9 @@ +==BIP70 Extensions== + +Add your extension below using tags starting at 1000 and submit a pull-req. + +{| +| Field Number || Extension Name || Field Name || Description +|- +| 1000 || [[https://example.com|(unassigned)]] || (unassigned) || (unassigned) +|} diff --git a/bip-0070/paymentrequest.proto b/bip-0070/paymentrequest.proto index f83b110..6680810 100644 --- a/bip-0070/paymentrequest.proto +++ b/bip-0070/paymentrequest.proto @@ -1,9 +1,9 @@ // // Simple Bitcoin Payment Protocol messages // -// Use fields 100+ for extensions; -// to avoid conflicts, register extensions via pull-req at: -// https://github.com/bitcoin/bips +// Use fields 1000+ for extensions; +// to avoid conflicts, register extensions via pull-req at +// https://github.com/bitcoin/bips/bip-0070/extensions.mediawiki // package payments; diff --git a/bip-0071.mediawiki b/bip-0071.mediawiki index 44b4d3d..1fc8489 100644 --- a/bip-0071.mediawiki +++ b/bip-0071.mediawiki @@ -2,7 +2,7 @@ BIP: 71 Title: Payment Protocol MIME types Author: Gavin Andresen <gavinandresen@gmail.com> - Status: Draft + Status: Final Type: Standards Track Created: 2013-07-29 </pre> diff --git a/bip-0072.mediawiki b/bip-0072.mediawiki index dae53f4..4dcc48b 100644 --- a/bip-0072.mediawiki +++ b/bip-0072.mediawiki @@ -2,7 +2,7 @@ BIP: 72 Title: bitcoin: uri extensions for Payment Protocol Author: Gavin Andresen <gavinandresen@gmail.com> - Status: Draft + Status: Final Type: Standards Track Created: 2013-07-29 </pre> @@ -38,12 +38,16 @@ described in BIP 70. Bitcoin wallets must support fetching PaymentRequests via http and https protocols; they may support other protocols. Wallets must -include an Accept HTTP header in HTTP(s) requests: +include an "Accept" HTTP header in HTTP(s) requests (as defined +in RFC 2616): + <pre>Accept: application/bitcoin-paymentrequest</pre> If a PaymentRequest cannot be obtained (perhaps the server is unavailable), then the customer should be informed that the merchant's -payment processing system is unavailable. +payment processing system is unavailable. In the case of an HTTP +request, status codes which are neither success nor error (such as +redirect) should be handled as outlined in RFC 2616. ==Compatibility== @@ -59,3 +63,7 @@ Non-backwards-compatible equivalent: <pre> bitcoin:?r=https://merchant.com/pay.php?h%3D2a8628fc2fbe </pre> + +==References== + +[[http://www.w3.org/Protocols/rfc2616/rfc2616.html|RFC 2616]] : Hypertext Transfer Protocol -- HTTP/1.1 |