mirror of
https://github.com/bitcoinbook/bitcoinbook
synced 2024-12-24 07:28:08 +00:00
4853 lines
190 KiB
Plaintext
4853 lines
190 KiB
Plaintext
-----------------------------------
|
||
BIP: 1
|
||
Title: BIP Purpose and Guidelines
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2011-08-19
|
||
-----------------------------------
|
||
|
||
[[what-is-a-bip]]
|
||
What is a BIP?
|
||
~~~~~~~~~~~~~~
|
||
|
||
BIP stands for Bitcoin Improvement Proposal. A BIP is a design document
|
||
providing information to the Bitcoin community, or describing a new
|
||
feature for Bitcoin or its processes or environment. The BIP should
|
||
provide a concise technical specification of the feature and a rationale
|
||
for the feature.
|
||
|
||
We intend BIPs to be the primary mechanisms for proposing new features,
|
||
for collecting community input on an issue, and for documenting the
|
||
design decisions that have gone into Bitcoin. The BIP author is
|
||
responsible for building consensus within the community and documenting
|
||
dissenting opinions.
|
||
|
||
Because the BIPs are maintained as text files in a versioned repository,
|
||
their revision history is the historical record of the feature proposal
|
||
.
|
||
|
||
[[bip-types]]
|
||
BIP Types
|
||
~~~~~~~~~
|
||
|
||
There are three kinds of BIP:
|
||
|
||
* A Standards Track BIP describes any change that affects most or all
|
||
Bitcoin implementations, such as a change to the network protocol, a
|
||
change in block or transaction validity rules, or any change or addition
|
||
that affects the interoperability of applications using Bitcoin.
|
||
* An Informational BIP describes a Bitcoin design issue, or provides
|
||
general guidelines or information to the Bitcoin community, but does not
|
||
propose a new feature. Informational BIPs do not necessarily represent a
|
||
Bitcoin community consensus or recommendation, so users and implementors
|
||
are free to ignore Informational BIPs or follow their advice.
|
||
* A Process BIP describes a process surrounding Bitcoin, or proposes a
|
||
change to (or an event in) a process. Process BIPs are like Standards
|
||
Track BIPs but apply to areas other than the Bitcoin protocol itself.
|
||
They may propose an implementation, but not to Bitcoin's codebase; they
|
||
often require community consensus; unlike Informational BIPs, they are
|
||
more than recommendations, and users are typically not free to ignore
|
||
them. Examples include procedures, guidelines, changes to the
|
||
decision-making process, and changes to the tools or environment used in
|
||
Bitcoin development. Any meta-BIP is also considered a Process BIP.
|
||
|
||
[[bip-work-flow]]
|
||
BIP Work Flow
|
||
~~~~~~~~~~~~~
|
||
|
||
The BIP editors assign BIP numbers and change their status. Please send
|
||
all BIP-related email to the BIP editor, which is listed under
|
||
link:#BIP_Editors[BIP Editors] below. Also see
|
||
link:#BIP_Editor_Responsibilities__Workflow[BIP Editor Responsibilities
|
||
& Workflow].
|
||
|
||
The BIP process begins with a new idea for Bitcoin. It is highly
|
||
recommended that a single BIP contain a single key proposal or new idea.
|
||
Small enhancements or patches often don't need a BIP and can be injected
|
||
into the Bitcoin development work flow with a patch submission to the
|
||
Bitcoin issue tracker. The more focused the BIP, the more successful it
|
||
tends to be. The BIP editor reserves the right to reject BIP proposals
|
||
if they appear too unfocused or too broad. If in doubt, split your BIP
|
||
into several well-focused ones.
|
||
|
||
Each BIP must have a champion -- someone who writes the BIP using the
|
||
style and format described below, shepherds the discussions in the
|
||
appropriate forums, and attempts to build community consensus around the
|
||
idea. The BIP champion (a.k.a. Author) should first attempt to ascertain
|
||
whether the idea is BIP-able. Posting to the
|
||
http://sourceforge.net/mailarchive/forum.php?forum_name=bitcoin-development[bitcoin-development@lists.sourceforge.net]
|
||
mailing list (and maybe the
|
||
https://bitcointalk.org/index.php?board=6.0[Development&Technical
|
||
Discussion] forum) is the best way to go about this.
|
||
|
||
Vetting an idea publicly before going as far as writing a BIP is meant
|
||
to save the potential author time. Many ideas have been brought forward
|
||
for changing Bitcoin that have been rejected for various reasons. Asking
|
||
the Bitcoin community first if an idea is original helps prevent too
|
||
much time being spent on something that is guaranteed to be rejected
|
||
based on prior discussions (searching the internet does not always do
|
||
the trick). It also helps to make sure the idea is applicable to the
|
||
entire community and not just the author. Just because an idea sounds
|
||
good to the author does not mean it will work for most people in most
|
||
areas where Bitcoin is used.
|
||
|
||
Once the champion has asked the Bitcoin community as to whether an idea
|
||
has any chance of acceptance, a draft BIP should be presented to
|
||
http://sourceforge.net/mailarchive/forum.php?forum_name=bitcoin-development[bitcoin-development@lists.sourceforge.net].
|
||
This gives the author a chance to flesh out the draft BIP to make
|
||
properly formatted, of high quality, and to address initial concerns
|
||
about the proposal.
|
||
|
||
Following a discussion, the proposal should be sent to the Bitcoin-dev
|
||
list and the BIP editor with the draft BIP. This draft must be written
|
||
in BIP style as described below, else it will be sent back without
|
||
further regard until proper formatting rules are followed.
|
||
|
||
If the BIP editor approves, he will assign the BIP a number, label it as
|
||
Standards Track, Informational, or Process, give it status "Draft", and
|
||
add it to the git repository. The BIP editor will not unreasonably deny
|
||
a BIP. Reasons for denying BIP status include duplication of effort,
|
||
being technically unsound, not providing proper motivation or addressing
|
||
backwards compatibility, or not in keeping with the Bitcoin philosophy.
|
||
|
||
The BIP author may update the Draft as necessary in the git repository.
|
||
Updates to drafts may also be submitted by the author as pull requests.
|
||
|
||
Standards Track BIPs consist of two parts, a design document and a
|
||
reference implementation. The BIP should be reviewed and accepted before
|
||
a reference implementation is begun, unless a reference implementation
|
||
will aid people in studying the BIP. Standards Track BIPs must include
|
||
an implementation -- in the form of code, a patch, or a URL to same --
|
||
before it can be considered Final.
|
||
|
||
BIP authors are responsible for collecting community feedback on a BIP
|
||
before submitting it for review. However, wherever possible, long
|
||
open-ended discussions on public mailing lists should be avoided.
|
||
Strategies to keep the discussions efficient include: setting up a
|
||
separate SIG mailing list for the topic, having the BIP author accept
|
||
private comments in the early design phases, setting up a wiki page or
|
||
git repository, etc. BIP authors should use their discretion here.
|
||
|
||
For a BIP to be accepted it must meet certain minimum criteria. It must
|
||
be a clear and complete description of the proposed enhancement. The
|
||
enhancement must represent a net improvement. The proposed
|
||
implementation, if applicable, must be solid and must not complicate the
|
||
protocol unduly.
|
||
|
||
Once a BIP has been accepted, the reference implementation must be
|
||
completed. When the reference implementation is complete and accepted by
|
||
the community, the status will be changed to "Final".
|
||
|
||
A BIP can also be assigned status "Deferred". The BIP author or editor
|
||
can assign the BIP this status when no progress is being made on the
|
||
BIP. Once a BIP is deferred, the BIP editor can re-assign it to draft
|
||
status.
|
||
|
||
A BIP can also be "Rejected". Perhaps after all is said and done it was
|
||
not a good idea. It is still important to have a record of this fact.
|
||
|
||
BIPs can also be superseded by a different BIP, rendering the original
|
||
obsolete. This is intended for Informational BIPs, where version 2 of an
|
||
API can replace version 1.
|
||
|
||
The possible paths of the status of BIPs are as follows:
|
||
|
||
Some Informational and Process BIPs may also have a status of "Active"
|
||
if they are never meant to be completed. E.g. BIP 1 (this BIP).
|
||
|
||
[[what-belongs-in-a-successful-bip]]
|
||
What belongs in a successful BIP?
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Each BIP should have the following parts:
|
||
|
||
* Preamble -- RFC 822 style headers containing meta-data about the BIP,
|
||
including the BIP number, a short descriptive title (limited to a
|
||
maximum of 44 characters), the names, and optionally the contact info
|
||
for each author, etc.
|
||
|
||
* Abstract -- a short (~200 word) description of the technical issue
|
||
being addressed.
|
||
|
||
* Copyright/public domain -- Each BIP must either be explicitly labelled
|
||
as placed in the public domain (see this BIP as an example) or licensed
|
||
under the Open Publication License.
|
||
|
||
* Specification -- The technical specification should describe the
|
||
syntax and semantics of any new feature. The specification should be
|
||
detailed enough to allow competing, interoperable implementations for
|
||
any of the current Bitcoin platforms (Satoshi, BitcoinJ, bitcoin-js,
|
||
libbitcoin).
|
||
|
||
* Motivation -- The motivation is critical for BIPs that want to change
|
||
the Bitcoin protocol. It should clearly explain why the existing
|
||
protocol specification is inadequate to address the problem that the BIP
|
||
solves. BIP submissions without sufficient motivation may be rejected
|
||
outright.
|
||
|
||
* Rationale -- The rationale fleshes out the specification by describing
|
||
what motivated the design and why particular design decisions were made.
|
||
It should describe alternate designs that were considered and related
|
||
work, e.g. how the feature is supported in other languages.
|
||
|
||
* The rationale should provide evidence of consensus within the
|
||
community and discuss important objections or concerns raised during
|
||
discussion.
|
||
|
||
* Backwards Compatibility -- All BIPs that introduce backwards
|
||
incompatibilities must include a section describing these
|
||
incompatibilities and their severity. The BIP must explain how the
|
||
author proposes to deal with these incompatibilities. BIP submissions
|
||
without a sufficient backwards compatibility treatise may be rejected
|
||
outright.
|
||
|
||
* Reference Implementation -- The reference implementation must be
|
||
completed before any BIP is given status "Final", but it need not be
|
||
completed before the BIP is accepted. It is better to finish the
|
||
specification and rationale first and reach consensus on it before
|
||
writing code.
|
||
|
||
* The final implementation must include test code and documentation
|
||
appropriate for the Bitcoin protocol.
|
||
|
||
[[bip-formats-and-templates]]
|
||
BIP Formats and Templates
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
BIPs should be written in mediawiki or markdown format. Image files
|
||
should be included in a subdirectory for that BIP.
|
||
|
||
[[bip-header-preamble]]
|
||
BIP Header Preamble
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
Each BIP must begin with an RFC 822 style header preamble. The headers
|
||
must appear in the following order. Headers marked with "*" are optional
|
||
and are described below. All other headers are required.
|
||
|
||
-------------------------------------------------------------------
|
||
BIP: <BIP number>
|
||
Title: <BIP title>
|
||
Author: <list of authors' real names and optionally, email addrs>
|
||
* Discussions-To: <email address>
|
||
Status: <Draft | Active | Accepted | Deferred | Rejected |
|
||
Withdrawn | Final | Superseded>
|
||
Type: <Standards Track | Informational | Process>
|
||
Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
|
||
* Post-History: <dates of postings to bitcoin mailing list>
|
||
* Replaces: <BIP number>
|
||
* Superseded-By: <BIP number>
|
||
* Resolution: <url>
|
||
-------------------------------------------------------------------
|
||
|
||
The Author header lists the names, and optionally the email addresses of
|
||
all the authors/owners of the BIP. The format of the Author header value
|
||
must be
|
||
|
||
` Random J. User `
|
||
|
||
if the email address is included, and just
|
||
|
||
` Random J. User`
|
||
|
||
if the address is not given.
|
||
|
||
If there are multiple authors, each should be on a separate line
|
||
following RFC 2822 continuation line conventions.
|
||
|
||
Note: The Resolution header is required for Standards Track BIPs only.
|
||
It contains a URL that should point to an email message or other web
|
||
resource where the pronouncement about the BIP is made.
|
||
|
||
While a BIP is in private discussions (usually during the initial Draft
|
||
phase), a Discussions-To header will indicate the mailing list or URL
|
||
where the BIP is being discussed. No Discussions-To header is necessary
|
||
if the BIP is being discussed privately with the author, or on the
|
||
bitcoin email mailing lists.
|
||
|
||
The Type header specifies the type of BIP: Standards Track,
|
||
Informational, or Process.
|
||
|
||
The Created header records the date that the BIP was assigned a number,
|
||
while Post-History is used to record the dates of when new versions of
|
||
the BIP are posted to bitcoin mailing lists. Both headers should be in
|
||
yyyy-mm-dd format, e.g. 2001-08-14.
|
||
|
||
BIPs may have a Requires header, indicating the BIP numbers that this
|
||
BIP depends on.
|
||
|
||
BIPs may also have a Superseded-By header indicating that a BIP has been
|
||
rendered obsolete by a later document; the value is the number of the
|
||
BIP that replaces the current document. The newer BIP must have a
|
||
Replaces header containing the number of the BIP that it rendered
|
||
obsolete. Auxiliary Files
|
||
|
||
BIPs may include auxiliary files such as diagrams. Such files must be
|
||
named BIP-XXXX-Y.ext, where "XXXX" is the BIP number, "Y" is a serial
|
||
number (starting at 1), and "ext" is replaced by the actual file
|
||
extension (e.g. "png").
|
||
|
||
[[transferring-bip-ownership]]
|
||
Transferring BIP Ownership
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
It occasionally becomes necessary to transfer ownership of BIPs to a new
|
||
champion. In general, we'd like to retain the original author as a
|
||
co-author of the transferred BIP, but that's really up to the original
|
||
author. A good reason to transfer ownership is because the original
|
||
author no longer has the time or interest in updating it or following
|
||
through with the BIP process, or has fallen off the face of the 'net
|
||
(i.e. is unreachable or not responding to email). A bad reason to
|
||
transfer ownership is because you don't agree with the direction of the
|
||
BIP. We try to build consensus around a BIP, but if that's not possible,
|
||
you can always submit a competing BIP.
|
||
|
||
If you are interested in assuming ownership of a BIP, send a message
|
||
asking to take over, addressed to both the original author and the BIP
|
||
editor. If the original author doesn't respond to email in a timely
|
||
manner, the BIP editor will make a unilateral decision (it's not like
|
||
such decisions can't be reversed :).
|
||
|
||
[[bip-editors]]
|
||
BIP Editors
|
||
~~~~~~~~~~~
|
||
|
||
The current BIP editor is Gregory Maxwell who can be contacted at
|
||
gmaxwell@gmail.com.
|
||
|
||
[[bip-editor-responsibilities-workflow]]
|
||
BIP Editor Responsibilities & Workflow
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
A BIP editor must subscribe to the Bitcoin development mailing list. All
|
||
BIP-related correspondence should be sent (or CC'd) to
|
||
gmaxwell@gmail.com.
|
||
|
||
For each new BIP that comes in an editor does the following:
|
||
|
||
* Read the BIP to check if it is ready: sound and complete. The ideas
|
||
must make technical sense, even if they don't seem likely to be
|
||
accepted.
|
||
* The title should accurately describe the content.
|
||
* Edit the BIP for language (spelling, grammar, sentence structure,
|
||
etc.), markup (for reST BIPs), code style (examples should match BIP 8 &
|
||
7).
|
||
|
||
If the BIP isn't ready, the editor will send it back to the author for
|
||
revision, with specific instructions.
|
||
|
||
Once the BIP is ready for the repository, the BIP editor will:
|
||
|
||
* Assign a BIP number (almost always just the next available number, but
|
||
sometimes it's a special/joke number, like 666 or 3141).
|
||
|
||
* Add the BIP to the https://github.com/bitcoin/bips[bitcoin/bips]
|
||
repository on GitHub.
|
||
|
||
* List the BIP in README.mediawiki
|
||
|
||
* Send email back to the BIP author with next steps (post to bitcoin
|
||
mailing list).
|
||
|
||
Many BIPs are written and maintained by developers with write access to
|
||
the Bitcoin codebase. The BIP editors monitor BIP changes, and correct
|
||
any structure, grammar, spelling, or markup mistakes we see.
|
||
|
||
The editors don't pass judgement on BIPs. We merely do the
|
||
administrative & editorial part. Except for times like this, there's
|
||
relatively low volume.
|
||
|
||
[[history]]
|
||
History
|
||
~~~~~~~
|
||
|
||
This document was derived heavily from Python's PEP-0001. In many places
|
||
text was simply copied and modified. Although the PEP-0001 text was
|
||
written by Barry Warsaw, Jeremy Hylton, and David Goodger, they are not
|
||
responsible for its use in the Bitcoin Improvement Process, and should
|
||
not be bothered with technical questions specific to Bitcoin or the BIP
|
||
process. Please direct all comments to the BIP editors or the Bitcoin
|
||
development mailing list.
|
||
--------------------------------------------------
|
||
BIP: 11
|
||
Title: M-of-N Standard Transactions
|
||
Author: Gavin Andresen <gavinandresen@gmail.com>
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2011-10-18
|
||
Post-History: 2011-10-02
|
||
--------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP proposes M-of-N-signatures required transactions as a new
|
||
'standard' transaction type.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
Enable secured wallets, escrow transactions, and other use cases where
|
||
redeeming funds requires more than a single signature.
|
||
|
||
A couple of motivating use cases:
|
||
|
||
* A wallet secured by a "wallet protection service" (WPS). 2-of-2
|
||
signatures required transactions will be used, with one signature coming
|
||
from the (possibly compromised) computer with the wallet and the second
|
||
signature coming from the WPS. When sending protected bitcoins, the
|
||
user's bitcoin client will contact the WPS with the proposed transaction
|
||
and it can then contact the user for confirmation that they initiated
|
||
the transaction and that the transaction details are correct. Details
|
||
for how clients and WPS's communicate are outside the scope of this BIP.
|
||
Side note: customers should insist that their wallet protection service
|
||
provide them with copies of the private key(s) used to secure their
|
||
wallets that they can safely store off-line, so that their coins can be
|
||
spent even if the WPS goes out of business.
|
||
|
||
* Three-party escrow (buyer, seller and trusted dispute agent). 2-of-3
|
||
signatures required transactions will be used. The buyer and seller and
|
||
agent will each provide a public key, and the buyer will then send coins
|
||
into a 2-of-3 CHECKMULTISIG transaction and send the seller and the
|
||
agent the transaction id. The seller will fulfill their obligation and
|
||
then ask the buyer to co-sign a transaction ( already signed by seller )
|
||
that sends the tied-up coins to him (seller). +
|
||
If the buyer and seller cannot agree, then the agent can, with the
|
||
cooperation of either buyer or seller, decide what happens to the
|
||
tied-up coins. Details of how buyer, seller, and agent communicate to
|
||
gather signatures or public keys are outside the scope of this BIP.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
A new standard transaction type (scriptPubKey) that is relayed by
|
||
clients and included in mined blocks:
|
||
|
||
` m {pubkey}...{pubkey} n OP_CHECKMULTISIG`
|
||
|
||
But only for n less than or equal to 3.
|
||
|
||
OP_CHECKMULTISIG transactions are redeemed using a standard scriptSig:
|
||
|
||
` OP_0 ...signatures...`
|
||
|
||
(OP_0 is required because of a bug in OP_CHECKMULTISIG; it pops one too
|
||
many items off the execution stack, so a dummy value must be placed on
|
||
the stack).
|
||
|
||
The current Satoshi bitcoin client does not relay or mine transactions
|
||
with scriptSigs larger than 200 bytes; to accomodate 3-signature
|
||
transactions, this will be increased to 500 bytes.
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
OP_CHECKMULTISIG is already an enabled opcode, and is the most
|
||
straightforward way to support several important use cases.
|
||
|
||
One argument against using OP_CHECKMULTISIG is that old clients and
|
||
miners count it as "20 sigops" for purposes of computing how many
|
||
signature operations are in a block, and there is a hard limit of 20,000
|
||
sigops per block-- meaning a maximum of 1,000 multisig transactions per
|
||
block. Creating multisig transactions using multiple OP_CHECKSIG
|
||
operations allows more of them per block.
|
||
|
||
The counter-argument is that these new multi-signature transactions will
|
||
be used in combination with OP_EVAL (see the OP_EVAL BIP), and *will* be
|
||
counted accurately. And in any case, as transaction volume rises the
|
||
hard-coded maximum block size will have to be addressed, and the rules
|
||
for counting number-of-signature-operations-in-a-block can be addressed
|
||
at that time.
|
||
|
||
A weaker argument is OP_CHECKMULTISIG should not be used because it pops
|
||
one too many items off the stack during validation. Adding an extra OP_0
|
||
placeholder to the scriptSig adds only 1 byte to the transaction, and
|
||
any alternative that avoids OP_CHECKMULTISIG adds at least several bytes
|
||
of opcodes.
|
||
|
||
[[implementation]]
|
||
Implementation
|
||
~~~~~~~~~~~~~~
|
||
|
||
OP_CHECKMULTISIG is already supported by old clients and miners as a
|
||
non-standard transaction type.
|
||
|
||
https://github.com/gavinandresen/bitcoin-git/tree/op_eval
|
||
|
||
[[post-history]]
|
||
Post History
|
||
~~~~~~~~~~~~
|
||
|
||
* https://bitcointalk.org/index.php?topic=46538[OP_EVAL proposal]
|
||
|
||
--------------------------------------------------
|
||
BIP: 13
|
||
Title: Address Format for pay-to-script-hash
|
||
Author: Gavin Andresen <gavinandresen@gmail.com>
|
||
Status: Final
|
||
Type: Standards Track
|
||
Created: 2011-10-18
|
||
--------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP describes a new type of Bitcoin address to support arbitrarily
|
||
complex transactions. Complexity in this context is defined as what
|
||
information is needed by the recipient to respend the received coins, in
|
||
contrast to needing a single ECDSA private key as in current
|
||
implementations of Bitcoin.
|
||
|
||
In essence, an address encoded under this proposal represents the
|
||
encoded hash of a script, rather than the encoded hash of an ECDSA
|
||
public key.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
Enable "end-to-end" secure wallets and payments to fund escrow
|
||
transactions or other complex transactions. Enable third-party wallet
|
||
security services.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
The new bitcoin address type is constructed in the same manner as
|
||
existing bitcoin addresses (see link:Base58Check encoding[Base58Check
|
||
encoding]):
|
||
|
||
` base58-encode: [one-byte version][20-byte hash][4-byte checksum]`
|
||
|
||
Version byte is 5 for a main-network address, 196 for a testnet address.
|
||
The 20-byte hash is the hash of the script that will be used to redeem
|
||
the coins. And the 4-byte checksum is the first four bytes of the double
|
||
SHA256 hash of the version and hash.
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
One criticism is that bitcoin addresses should be deprecated in favor of
|
||
a more user-friendly mechanism for payments, and that this will just
|
||
encourage continued use of a poorly designed mechanism.
|
||
|
||
Another criticism is that bitcoin addresses are inherently insecure
|
||
because there is no identity information tied to them; if you only have
|
||
a bitcoin address, how can you be certain that you're paying who or what
|
||
you think you're paying?
|
||
|
||
Furthermore, truncating SHA256 is not an optimal checksum; there are
|
||
much better error-detecting algorithms. If we are introducing a new form
|
||
of Bitcoin address, then perhaps a better algorithm should be used.
|
||
|
||
This is one piece of the simplest path to a more secure bitcoin
|
||
infrastructure. It is not intended to solve all of bitcoin's usability
|
||
or security issues, but to be an incremental improvement over what
|
||
exists today. A future BIP or BIPs should propose more user-friendly
|
||
mechanisms for making payments, or for verifying that you're sending a
|
||
payment to the Free Software Foundation and not Joe Random Hacker.
|
||
|
||
Assuming that typing in bitcoin addresses manually will become
|
||
increasingly rare in the future, and given that the existing checksum
|
||
method for bitcoin addresses seems to work "well enough" in practice and
|
||
has already been implemented multiple times, the Author believes no
|
||
change to the checksum algorithm is necessary.
|
||
|
||
The leading version bytes are chosen so that, after base58 encoding, the
|
||
leading character is consistent: for the main network, byte 5 becomes
|
||
the character '3'. For the testnet, byte 196 is encoded into '2'.
|
||
|
||
[[backwards-compatibility]]
|
||
Backwards Compatibility
|
||
~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
This proposal is not backwards compatible, but it fails gracefully-- if
|
||
an older implementation is given one of these new bitcoin addresses, it
|
||
will report the address as invalid and will refuse to create a
|
||
transaction.
|
||
|
||
[[reference-implementation]]
|
||
Reference Implementation
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
See base58.cpp1/base58.h at https://github.com/bitcoin/bitcoin/src
|
||
|
||
[[see-also]]
|
||
See Also
|
||
~~~~~~~~
|
||
|
||
* link:bip-0012.mediawiki[BIP 12: OP_EVAL, the original P2SH design]
|
||
* link:bip-0016.mediawiki[BIP 16: Pay to Script Hash (aka "/P2SH/")]
|
||
* link:bip-0017.mediawiki[BIP 17: OP_CHECKHASHVERIFY, another P2SH
|
||
design]
|
||
|
||
------------------------------------------------------------
|
||
BIP: 14
|
||
Title: BIP Protocol Version and User Agent
|
||
Author: Amir Taaki <genjix@riseup.net>
|
||
Patrick Strateman <bitcoin-bips@covertinferno.org>
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2011-11-10
|
||
Post-History: 2011-11-02
|
||
------------------------------------------------------------
|
||
|
||
In this document, bitcoin will be used to refer to the protocol while
|
||
Satoshi will refer to the current client in order to prevent confusion.
|
||
|
||
[[past-situation]]
|
||
Past Situation
|
||
~~~~~~~~~~~~~~
|
||
|
||
Bitcoin as a protocol began life with the Satoshi client. Now that the
|
||
community is diversifying, a number of alternative clients with their
|
||
own codebases written in a variety of languages (Java, Python,
|
||
Javascript, C++) are rapidly developing their own feature-sets.
|
||
|
||
Embedded in the protocol is a version number. Primarily this version
|
||
number is in the "version" and "getblocks" messages, but is also in the
|
||
"block" message to indicate the software version that created that
|
||
block. Currently this version number is the same version number as that
|
||
of the client. This document is a proposal to separate the protocol
|
||
version from the client version, together with a proposed method to do
|
||
so.
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
With non-separated version numbers, every release of the Satoshi client
|
||
will increase its internal version number. Primarily this holds every
|
||
other client hostage to a game of catch-up with Satoshi version number
|
||
schemes. This plays against the decentralised nature of bitcoin, by
|
||
forcing every software release to remain in step with the release
|
||
schedule of one group of bitcoin developers.
|
||
|
||
Version bumping can also introduce incompatibilities and fracture the
|
||
network. In order that the health of the network is maintained, the
|
||
development of the protocol as a shared common collaborative process
|
||
requires being split off from the implementation of that protocol.
|
||
Neutral third entities to guide the protocol with representatives from
|
||
all groups, present the chance for bitcoin to grow in a positive manner
|
||
with minimal risks.
|
||
|
||
By using a protocol version, we set all implementations on the network
|
||
to a common standard. Everybody is able to agree within their confines
|
||
what is protocol and what is implementation-dependent. A user agent
|
||
string is offered as a 'vanity-plate' for clients to distinguish
|
||
themselves in the network.
|
||
|
||
Separation of the network protocol from the implemention, and forming
|
||
development of said protocol by means of a mutual consensus among
|
||
participants, has the democratic disadvantage when agreement is hard to
|
||
reach on contentious issues. To mitigate this issue, strong
|
||
communication channels and fast release schedules are needed, and are
|
||
outside the scope of this document (concerning a process-BIP type).
|
||
|
||
User agents provide extra tracking information that is useful for
|
||
keeping tabs on network data such as client implementations used or
|
||
common architectures/operating-systems. In the rare case they may even
|
||
provide an emergency method of shunning faulty clients that threaten
|
||
network health- although this is strongly unrecommended and extremely
|
||
bad form. The user agent does not provide a method for clients to work
|
||
around and behave differently to different implementations, as this will
|
||
lead to protocol fracturing.
|
||
|
||
In short:
|
||
|
||
* Protocol version: way to distinguish between nodes and behave
|
||
different accordingly.
|
||
* User agent: simple informational tool. Protocol should not be modified
|
||
depending on user agent.
|
||
|
||
[[browser-user-agents]]
|
||
Browser User-Agents
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
http://tools.ietf.org/html/rfc1945[RFC 1945] vaguely specifies a user
|
||
agent to be a string of the product with optional comments.
|
||
|
||
` Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1.6) Gecko/20100127 Gentoo Shiretoko/3.5.6`
|
||
|
||
User agents are most often parsed by computers more than humans. The
|
||
space delimited format, does not provide an easy, fast or efficient way
|
||
for parsing. The data contains no structure indicating hierarchy in this
|
||
placement.
|
||
|
||
The most immediate pieces of information there are the browser product,
|
||
rendering engine and the build (Gentoo Shiretoko) together with version
|
||
number. Various other pieces of information as included as comments such
|
||
as desktop environment, platform, language and revision number of the
|
||
build.
|
||
|
||
[[proposal]]
|
||
Proposal
|
||
~~~~~~~~
|
||
|
||
The version field in "version" and "getblocks" packets will become the
|
||
protocol version number. The version number in the "blocks" reflects the
|
||
protocol version from when that block was created.
|
||
|
||
The currently unused sub_version_num field in "version" packets will
|
||
become the new user-agent string.
|
||
|
||
Bitcoin user agents are a modified browser user agent with more
|
||
structure to aid parsers and provide some coherence. In bitcoin, the
|
||
software usually works like a stack starting from the core code-base up
|
||
to the end graphical interface. Therefore the user agent strings codify
|
||
this relationship.
|
||
|
||
Basic format:
|
||
|
||
` /Name:Version/Name:Version/.../`
|
||
|
||
Example:
|
||
|
||
` /Satoshi:5.64/bitcoin-qt:0.4/` +
|
||
` /Satoshi:5.12/Spesmilo:0.8/`
|
||
|
||
Here bitcoin-qt and Spesmilo may use protocol version 5.0, however the
|
||
internal codebase they use are different versions of the same software.
|
||
The version numbers are not defined to any strict format, although this
|
||
guide recommends:
|
||
|
||
* Version numbers in the form of Major.Minor.Revision (2.6.41)
|
||
* Repository builds using a date in the format of YYYYMMDD (20110128)
|
||
|
||
For git repository builds, implementations are free to use the git
|
||
commitish. However the issue lies in that it is not immediately obvious
|
||
without the repository which version precedes another. For this reason,
|
||
we lightly recommend dates in the format specified above, although this
|
||
is by no means a requirement.
|
||
|
||
Optional -r1, -r2, ... can be appended to user agent version numbers.
|
||
This is another light recommendation, but not a requirement.
|
||
Implementations are free to specify version numbers in whatever format
|
||
needed insofar as it does not include (, ), : or / to interfere with the
|
||
user agent syntax.
|
||
|
||
An optional comments field after the version number is also allowed.
|
||
Comments should be delimited by brackets (...). The contents of comments
|
||
is entirely implementation defined although this BIP recommends the use
|
||
of semi-colons ; as a delimiter between pieces of information.
|
||
|
||
Example:
|
||
|
||
` /BitcoinJ:0.2(iPad; U; CPU OS 3_2_1)/AndroidBuild:0.8/`
|
||
|
||
Reserved symbols are therefore: / : ( )
|
||
|
||
They should not be misused beyond what is specified in this section.
|
||
|
||
* / separates the code-stack
|
||
* ::
|
||
specifies the implementation version of the particular stack
|
||
* ( and ) delimits a comment which optionally separates data using ;
|
||
|
||
[[timeline]]
|
||
Timeline
|
||
~~~~~~~~
|
||
|
||
When this document was published, the bitcoin protocol and Satoshi
|
||
client versions were currently at 0.5 and undergoing changes. In order
|
||
to minimise disruption and allow the undergoing changes to be completed,
|
||
the next protocol version at 0.6 became peeled from the client version
|
||
(also at 0.6). As of that time (January 2012), protocol and
|
||
implementation version numbers are distinct from each other.
|
||
--------------------------------------------------
|
||
BIP: 16
|
||
Title: Pay to Script Hash
|
||
Author: Gavin Andresen <gavinandresen@gmail.com>
|
||
Status: Final
|
||
Type: Standards Track
|
||
Created: 2012-01-03
|
||
--------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP describes a new "standard" transaction type for the Bitcoin
|
||
scripting system, and defines additional validation rules that apply
|
||
only to the new transactions.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
The purpose of pay-to-script-hash is to move the responsibility for
|
||
supplying the conditions to redeem a transaction from the sender of the
|
||
funds to the redeemer.
|
||
|
||
The benefit is allowing a sender to fund any arbitrary transaction, no
|
||
matter how complicated, using a fixed-length 20-byte hash that is short
|
||
enough to scan from a QR code or easily copied and pasted.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
A new standard transaction type that is relayed and included in mined
|
||
blocks is defined:
|
||
|
||
` OP_HASH160 [20-byte-hash-value] OP_EQUAL`
|
||
|
||
[20-byte-hash-value] shall be the push-20-bytes-onto-the-stack opcode
|
||
(0x14) followed by exactly 20 bytes.
|
||
|
||
This new transaction type is redeemed by a standard scriptSig:
|
||
|
||
` ...signatures... {serialized script}`
|
||
|
||
Transactions that redeem these pay-to-script outpoints are only
|
||
considered standard if the _serialized script_ - also referred to as the
|
||
_redeemScript_ - is, itself, one of the other standard transaction
|
||
types.
|
||
|
||
The rules for validating these outpoints when relaying transactions or
|
||
considering them for inclusion in a new block are as follows:
|
||
|
||
1. Validation fails if there are any operations other than "push data"
|
||
operations in the scriptSig.
|
||
2. Normal validation is done: an initial stack is created from the
|
||
signatures and \{serialized script}, and the hash of the script is
|
||
computed and validation fails immediately if it does not match the hash
|
||
in the outpoint.
|
||
3. \{serialized script} is popped off the initial stack, and the
|
||
transaction is validated again using the popped stack and the
|
||
deserialized script as the scriptPubKey.
|
||
|
||
These new rules should only be applied when validating transactions in
|
||
blocks with timestamps >= 1333238400 (Apr 1 2012)
|
||
footnote:[https://github.com/bitcoin/bitcoin/commit/8f188ece3c82c4cf5d52a3363e7643c23169c0ff[Remove
|
||
-bip16 and -paytoscripthashtime command-line arguments]]. There are
|
||
transaction earlier than 13333238400 in the block chain that fail these
|
||
new validation rules.
|
||
footnote:[http://blockexplorer.com/tx/6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192[Transaction
|
||
6a26d2ecb67f27d1fa5524763b49029d7106e91e3cc05743073461a719776192]].
|
||
Older transactions must be validated under the old rules. (see the
|
||
Backwards Compatibility section for details).
|
||
|
||
For example, the scriptPubKey and corresponding scriptSig for a
|
||
one-signature-required transaction is:
|
||
|
||
` scriptSig: [signature] {[pubkey] OP_CHECKSIG}` +
|
||
` scriptPubKey: OP_HASH160 [20-byte-hash of {[pubkey] OP_CHECKSIG} ] OP_EQUAL`
|
||
|
||
Signature operations in the \{serialized script} shall contribute to the
|
||
maximum number allowed per block (20,000) as follows:
|
||
|
||
1. OP_CHECKSIG and OP_CHECKSIGVERIFY count as 1 signature operation,
|
||
whether or not they are evaluated.
|
||
2. OP_CHECKMULTISIG and OP_CHECKMULTISIGVERIFY immediately preceded by
|
||
OP_1 through OP_16 are counted as 1 to 16 signature operation, whether
|
||
or not they are evaluated.
|
||
3. All other OP_CHECKMULTISIG and OP_CHECKMULTISIGVERIFY are counted as
|
||
20 signature operations.
|
||
|
||
Examples:
|
||
|
||
+3 signature operations:
|
||
|
||
` {2 [pubkey1] [pubkey2] [pubkey3] 3 OP_CHECKMULTISIG}`
|
||
|
||
+22 signature operations
|
||
|
||
` {OP_CHECKSIG OP_IF OP_CHECKSIGVERIFY OP_ELSE OP_CHECKMULTISIGVERIFY OP_ENDIF}`
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
This BIP replaces BIP 12, which proposed a new Script opcode ("OP_EVAL")
|
||
to accomplish everything in this BIP and more.
|
||
|
||
The Motivation for this BIP (and BIP 13, the pay-to-script-hash address
|
||
type) is somewhat controversial; several people feel that it is
|
||
unnecessary, and complex/multisignature transaction types should be
|
||
supported by simply giving the sender the complete \{serialized script}.
|
||
The author believes that this BIP will minimize the changes needed to
|
||
all of the supporting infrastructure that has already been created to
|
||
send funds to a base58-encoded-20-byte bitcoin addresses, allowing
|
||
merchants and exchanges and other software to start supporting
|
||
multisignature transactions sooner.
|
||
|
||
Recognizing one 'special' form of scriptPubKey and performing extra
|
||
validation when it is detected is ugly. However, the consensus is that
|
||
the alternatives are either uglier, are more complex to implement,
|
||
and/or expand the power of the expression language in dangerous ways.
|
||
|
||
The signature operation counting rules are intended to be easy and quick
|
||
to implement by statically scanning the \{serialized script}. Bitcoin
|
||
imposes a maximum-number-of-signature-operations per block to prevent
|
||
denial-of-service attacks on miners. If there was no limit, a rogue
|
||
miner might broadcast a block that required hundreds of thousands of
|
||
ECDSA signature operations to validate, and it might be able to get a
|
||
head start computing the next block while the rest of the network worked
|
||
to validate the current one.
|
||
|
||
There is a 1-confirmation attack on old implementations, but it is
|
||
expensive and difficult in practice. The attack is:
|
||
|
||
1. Attacker creates a pay-to-script-hash transaction that is valid as
|
||
seen by old software, but invalid for new implementation, and sends
|
||
themselves some coins using it.
|
||
2. Attacker also creates a standard transaction that spends the
|
||
pay-to-script transaction, and pays the victim who is running old
|
||
software.
|
||
3. Attacker mines a block that contains both transactions.
|
||
|
||
If the victim accepts the 1-confirmation payment, then the attacker wins
|
||
because both transactions will be invalidated when the rest of the
|
||
network overwrites the attacker's invalid block.
|
||
|
||
The attack is expensive because it requires the attacker create a block
|
||
that they know will be invalidated by the rest of the network. It is
|
||
difficult because creating blocks is difficult and users should not
|
||
accept 1-confirmation transactions for higher-value transactions.
|
||
|
||
[[backwards-compatibility]]
|
||
Backwards Compatibility
|
||
~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
These transactions are non-standard to old implementations, which will
|
||
(typically) not relay them or include them in blocks.
|
||
|
||
Old implementations will validate that the \{serialize script}'s hash
|
||
value matches when they validate blocks created by software that fully
|
||
support this BIP, but will do no other validation.
|
||
|
||
Avoiding a block-chain split by malicious pay-to-script transactions
|
||
requires careful handling of one case:
|
||
|
||
* A pay-to-script-hash transaction that is invalid for new
|
||
clients/miners but valid for old clients/miners.
|
||
|
||
To gracefully upgrade and ensure no long-lasting block-chain split
|
||
occurs, more than 50% of miners must support full validation of the new
|
||
transaction type and must switch from the old validation rules to the
|
||
new rules at the same time.
|
||
|
||
To judge whether or not more than 50% of hashing power supports this
|
||
BIP, miners are asked to upgrade their software and put the string
|
||
"/P2SH/" in the input of the coinbase transaction for blocks that they
|
||
create.
|
||
|
||
On February 1, 2012, the block-chain will be examined to determine the
|
||
number of blocks supporting pay-to-script-hash for the previous 7 days.
|
||
If 550 or more contain "/P2SH/" in their coinbase, then all blocks with
|
||
timestamps after 15 Feb 2012, 00:00:00 GMT shall have their
|
||
pay-to-script-hash transactions fully validated. Approximately 1,000
|
||
blocks are created in a week; 550 should, therefore, be approximately
|
||
55% of the network supporting the new feature.
|
||
|
||
If a majority of hashing power does not support the new validation
|
||
rules, then rollout will be postponed (or rejected if it becomes clear
|
||
that a majority will never be achieved).
|
||
|
||
[[byte-limitation-on-serialized-script-size]]
|
||
520-byte limitation on serialized script size
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
As a consequence of the requirement for backwards compatiblity the
|
||
serialized script is itself subject to the same rules as any other
|
||
PUSHDATA operation, including the rule that no data greater than 520
|
||
bytes may be pushed to the stack. Thus is it not possible to spend a
|
||
P2SH output if the redemption script it refers to is >520 bytes in
|
||
length. For instance while the OP_CHECKMULTISIG opcode can itself accept
|
||
up to 20 pubkeys, with 33-byte compressed pubkeys it is only possible to
|
||
spend a P2SH output requiring a maximum of 15 pubkeys to redeem: 3 bytes
|
||
+ 15 pubkeys * 34 bytes/pubkey = 513 bytes.
|
||
|
||
[[reference-implementation]]
|
||
Reference Implementation
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
https://gist.github.com/gavinandresen/3966071
|
||
|
||
[[see-also]]
|
||
See Also
|
||
~~~~~~~~
|
||
|
||
* https://bitcointalk.org/index.php?topic=46538
|
||
* The link:bip-0013.mediawiki[Address format for Pay to Script Hash BIP]
|
||
* M-of-N Multisignature Transactions link:bip-0011.mediawiki[BIP 11]
|
||
* link:bip-0016/qa.mediawiki[Quality Assurance test checklist]
|
||
|
||
[[references]]
|
||
References
|
||
~~~~~~~~~~
|
||
---------------------------------------------------
|
||
BIP: 21
|
||
Title: URI Scheme
|
||
Author: Nils Schneider <nils.schneider@gmail.com>
|
||
Matt Corallo <bip21@bluematt.me>
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2012-01-29
|
||
---------------------------------------------------
|
||
|
||
This BIP is a modification of an earlier link:bip-0020.mediawiki[BIP
|
||
0020] by Luke Dashjr. BIP 0020 was based off an earlier document by Nils
|
||
Schneider. The alternative payment amounts in BIP 0020 have been
|
||
removed.
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP proposes a URI scheme for making Bitcoin payments.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
The purpose of this URI scheme is to enable users to easily make
|
||
payments by simply clicking links on webpages or scanning QR Codes.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
[[general-rules-for-handling-important]]
|
||
General rules for handling (important!)
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Bitcoin clients MUST NOT act on URIs without getting the user's
|
||
authorization. They SHOULD require the user to manually approve each
|
||
payment individually, though in some cases they MAY allow the user to
|
||
automatically make this decision.
|
||
|
||
[[operating-system-integration]]
|
||
Operating system integration
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Graphical bitcoin clients SHOULD register themselves as the handler for
|
||
the "bitcoin:" URI scheme by default, if no other handler is already
|
||
registered. If there is already a registered handler, they MAY prompt
|
||
the user to change it once when they first run the client.
|
||
|
||
[[general-format]]
|
||
General Format
|
||
^^^^^^^^^^^^^^
|
||
|
||
Bitcoin URIs follow the general format for URIs as set forth in RFC
|
||
3986. The path component consists of a bitcoin address, and the query
|
||
component provides additional payment options.
|
||
|
||
Elements of the query component may contain characters outside the valid
|
||
range. These must first be encoded according to UTF-8, and then each
|
||
octet of the corresponding UTF-8 sequence must be percent-encoded as
|
||
described in RFC 3986.
|
||
|
||
[[abnf-grammar]]
|
||
ABNF grammar
|
||
^^^^^^^^^^^^
|
||
|
||
(See also link:#Simpler_syntax[a simpler representation of syntax])
|
||
|
||
`bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]` +
|
||
`bitcoinaddress = *base58` +
|
||
`bitcoinparams = bitcoinparam [ "&" bitcoinparams ]` +
|
||
`bitcoinparam = [ amountparam / labelparam / messageparam / otherparam / reqparam ]` +
|
||
`amountparam = "amount=" *digit [ "." *digit ]` +
|
||
`labelparam = "label=" *qchar` +
|
||
`messageparam = "message=" *qchar` +
|
||
`otherparam = qchar *qchar [ "=" *qchar ]` +
|
||
`reqparam = "req-" qchar *qchar [ "=" *qchar ]`
|
||
|
||
Here, "qchar" corresponds to valid characters of an RFC 3986 URI query
|
||
component, excluding the "=" and "&" characters, which this BIP takes as
|
||
separators.
|
||
|
||
The scheme component ("bitcoin:") is case-insensitive, and
|
||
implementations must accept any combination of uppercase and lowercase
|
||
letters. The rest of the URI is case-sensitive, including the query
|
||
parameter keys.
|
||
|
||
[[query-keys]]
|
||
Query Keys
|
||
^^^^^^^^^^
|
||
|
||
* label: Label for that address (e.g. name of receiver)
|
||
* address: bitcoin address
|
||
* message: message that describes the transaction to the user
|
||
(link:#Examples[see examples below])
|
||
* size: amount of base bitcoin units (link:#Transfer_amount/size[see
|
||
below])
|
||
* (others): optional, for future extensions
|
||
|
||
[[transfer-amountsize]]
|
||
Transfer amount/size
|
||
++++++++++++++++++++
|
||
|
||
If an amount is provided, it MUST be specified in decimal BTC. All
|
||
amounts MUST contain no commas and use a period (.) as the separating
|
||
character to separate whole numbers and decimal fractions. I.e.
|
||
amount=50.00 or amount=50 is treated as 50 BTC, and amount=50,000.00 is
|
||
invalid.
|
||
|
||
Bitcoin clients MAY display the amount in any format that is not
|
||
intended to deceive the user. They SHOULD choose a format that is
|
||
foremost least confusing, and only after that most reasonable given the
|
||
amount requested. For example, so long as the majority of users work in
|
||
BTC units, values should always be displayed in BTC by default, even if
|
||
mBTC or TBC would otherwise be a more logical interpretation of the
|
||
amount.
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
[[payment-identifiers-not-person-identifiers]]
|
||
Payment identifiers, not person identifiers
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Current best practices are that a unique address should be used for
|
||
every transaction. Therefore, a URI scheme should not represent an
|
||
exchange of personal information, but a one-time payment.
|
||
|
||
[[accessibility-uri-scheme-name]]
|
||
Accessibility (URI scheme name)
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Should someone from the outside happen to see such a URI, the URI scheme
|
||
name already gives a description. A quick search should then do the rest
|
||
to help them find the resources needed to make their payment. Other
|
||
proposed names sound much more cryptic; the chance that someone googles
|
||
that out of curiosity are much slimmer. Also, very likely, what he will
|
||
find are mostly technical specifications - not the best introduction to
|
||
bitcoin.
|
||
|
||
[[forward-compatibility]]
|
||
Forward compatibility
|
||
~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Variables which are prefixed with a req- are considered required. If a
|
||
client does not implement any variables which are prefixed with req-, it
|
||
MUST consider the entire URI invalid. Any other variables which are not
|
||
implemented, but which are not prefixed with a req-, can be safely
|
||
ignored.
|
||
|
||
[[backward-compatibility]]
|
||
Backward compatibility
|
||
~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
As this BIP is written, several clients already implement a bitcoin: URI
|
||
scheme similar to this one, however usually without the additional
|
||
"req-" prefix requirement. Thus, it is recommended that additional
|
||
variables prefixed with req- not be used in a mission-critical way until
|
||
a grace period of 6 months from the finalization of this BIP has passed
|
||
in order to allow client developers to release new versions, and users
|
||
of old clients to upgrade.
|
||
|
||
[[appendix]]
|
||
Appendix
|
||
~~~~~~~~
|
||
|
||
[[simpler-syntax]]
|
||
Simpler syntax
|
||
^^^^^^^^^^^^^^
|
||
|
||
This section is non-normative and does not cover all possible syntax.
|
||
Please see the BNF grammar above for the normative syntax.
|
||
|
||
[foo] means optional, <bar> are placeholders
|
||
|
||
`bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]`
|
||
|
||
[[examples]]
|
||
Examples
|
||
^^^^^^^^
|
||
|
||
Just the address:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W`]
|
||
|
||
Address with name:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr`]
|
||
|
||
Request 20.30 BTC to "Luke-Jr":
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr`]
|
||
|
||
Request 50 BTC with message:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz`]
|
||
|
||
Some future version that has variables which are (currently) not
|
||
understood and required and thus invalid:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999`]
|
||
|
||
Some future version that has variables which are (currently) not
|
||
understood but not required and thus valid:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999`]
|
||
|
||
Characters must be URI encoded properly.
|
||
|
||
[[reference-implementations]]
|
||
Reference Implementations
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
[[bitcoin-clients]]
|
||
Bitcoin clients
|
||
^^^^^^^^^^^^^^^
|
||
|
||
* Bitcoin-Qt supports the old version of Bitcoin URIs (ie without the
|
||
req- prefix), with Windows and KDE integration as of commit
|
||
70f55355e29c8e45b607e782c5d76609d23cc858.
|
||
|
||
---------------------------------------------
|
||
BIP: 22
|
||
Title: getblocktemplate - Fundamentals
|
||
Author: Luke Dashjr <luke+bip22@dashjr.org>
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2012-02-28
|
||
---------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP describes a new JSON-RPC method for "smart" Bitcoin miners and
|
||
proxies. Instead of sending a simple block header for hashing, the
|
||
entire block structure is sent, and left to the miner to (optionally)
|
||
customize and assemble.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
[[block-template-request]]
|
||
Block Template Request
|
||
^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
A JSON-RPC method is defined, called "getblocktemplate". It accepts
|
||
exactly one argument, which MUST be an Object of request parameters. If
|
||
the request parameters include a "mode" key, that is used to explicitly
|
||
select between the default "template" request or a
|
||
link:bip-0023.mediawiki#Block_Proposal["proposal"].
|
||
|
||
Block template creation can be influenced by various parameters:
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=4|template request
|
||
|Key |Required |Type |Description
|
||
|
||
|capabilities a| |Array of Strings |SHOULD contain a list of the
|
||
following, to indicate client-side support:
|
||
#Optional:_Long_Polling["longpoll"], "coinbasetxn", "coinbasevalue",
|
||
link:bip-0023.mediawiki#Block_Proposal["proposal"],
|
||
link:bip-0023.mediawiki#Logical_Services["serverlist"], "workid", and
|
||
any of the link:bip-0023.mediawiki#Mutations[mutations]
|
||
|
||
|mode a| |String |MUST be "template" or omitted
|
||
|=======================================================================
|
||
|
||
getblocktemplate MUST return a JSON Object containing the following
|
||
keys:
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=4| template
|
||
|Key |Required |Type |Description
|
||
|
||
|bits a| |String |the compressed difficulty in hexadecimal
|
||
|
||
|curtime a| |Number |the current time as seen by the server (recommended
|
||
for block time) - note this is not necessarily the system clock, and
|
||
must fall within the mintime/maxtime rules
|
||
|
||
|height a| |Number |the height of the block we are looking for
|
||
|
||
|previousblockhash a| |String |the hash of the previous block, in
|
||
big-endian hexadecimal
|
||
|
||
|sigoplimit a| |Number |number of sigops allowed in blocks
|
||
|
||
|sizelimit a| |Number |number of bytes allowed in blocks
|
||
|
||
|transactions a| |Array of Objects |Objects containing
|
||
link:#Transactions_Object_Format[information for Bitcoin transactions]
|
||
(excluding coinbase)
|
||
|
||
|version a| |Number |always 1 or 2 (at least for bitcoin) - clients MUST
|
||
understand the implications of the version they use (eg, comply with
|
||
link:bip-0034.mediawiki[BIP 0034] for version 2)
|
||
|
||
|coinbaseaux a| |Object |data that SHOULD be included in the coinbase's
|
||
scriptSig content. Only the values (hexadecimal byte-for-byte) in this
|
||
Object should be included, not the keys. This does not include the block
|
||
height, which is required to be included in the scriptSig by
|
||
link:bip-0034.mediawiki[BIP 0034]. It is advisable to encode values
|
||
inside "PUSH" opcodes, so as to not inadvertantly expend SIGOPs (which
|
||
are counted toward limits, despite not being executed).
|
||
|
||
|coinbasetxn a| |Object |link:#Transactions_Object_Format[information
|
||
for coinbase transaction]
|
||
|
||
|coinbasevalue a| |Number |total funds available for the coinbase (in
|
||
Satoshis)
|
||
|
||
|workid a| |String |if provided, this value must be returned with
|
||
results (see link:#Block_Submission[Block Submission])
|
||
|=======================================================================
|
||
|
||
[[transactions-object-format]]
|
||
Transactions Object Format
|
||
++++++++++++++++++++++++++
|
||
|
||
The Objects listed in the response's "transactions" key contains these
|
||
keys:
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=3|template "transactions" element
|
||
|Key |Type |Description
|
||
|
||
|data |String |transaction data encoded in hexadecimal (byte-for-byte)
|
||
|
||
|depends |Array of Numbers |other transactions before this one (by
|
||
1-based index in "transactions" list) that must be present in the final
|
||
block if this one is; if key is not present, dependencies are unknown
|
||
and clients MUST NOT assume there aren't any
|
||
|
||
|fee |Number |difference in value between transaction inputs and outputs
|
||
(in Satoshis); for coinbase transactions, this is a negative Number of
|
||
the total collected block fees (ie, not including the block subsidy); if
|
||
key is not present, fee is unknown and clients MUST NOT assume there
|
||
isn't one
|
||
|
||
|hash |String |hash/id encoded in little-endian hexadecimal
|
||
|
||
|required |Boolean |if provided and true, this transaction must be in
|
||
the final block
|
||
|
||
|sigops |Number |total number of SigOps, as counted for purposes of
|
||
block limits; if key is not present, sigop count is unknown and clients
|
||
MUST NOT assume there aren't any
|
||
|=======================================================================
|
||
|
||
Only the "data" key is required, but servers should provide the others
|
||
if they are known.
|
||
|
||
[[block-submission]]
|
||
Block Submission
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
A JSON-RPC method is defined, called "submitblock", to submit potential
|
||
blocks (or shares). It accepts two arguments: the first is always a
|
||
String of the hex-encoded block data to submit; the second is an Object
|
||
of parameters, and is optional if parameters are not needed.
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=3|submitblock parameters (2nd argument)
|
||
|Key |Type |Description
|
||
|
||
|workid |String |if the server provided a workid, it MUST be included
|
||
with submissions
|
||
|=======================================================================
|
||
|
||
This method MUST return either null (when a share is accepted), a String
|
||
describing briefly the reason the share was rejected, or an Object of
|
||
these with a key for each merged-mining chain the share was submitted
|
||
to.
|
||
|
||
[[optional-long-polling]]
|
||
Optional: Long Polling
|
||
^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|template request
|
||
|Key |Type |Description
|
||
|
||
|capabilities |Array of Strings |miners which support long polling
|
||
SHOULD provide a list including the String "longpoll"
|
||
|
||
|longpollid |String |"longpollid" of job to monitor for expiration;
|
||
required and valid only for long poll requests
|
||
|=======================================================================
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|template
|
||
|Key |Type |Description
|
||
|
||
|longpollid |String |identifier for long poll request; MUST be omitted
|
||
if the server does not support long polling
|
||
|
||
|longpolluri |String |if provided, an alternate URI to use for long poll
|
||
requests
|
||
|
||
|submitold |Boolean |only relevant for long poll responses: indicates if
|
||
work received prior to this response remains potentially valid (default)
|
||
and should have its shares submitted; if false, the miner may wish to
|
||
discard its share queue
|
||
|=======================================================================
|
||
|
||
If the server supports long polling, it MUST include a "longpollid" key
|
||
in block templates, and it MUST be unique for each event: any given
|
||
"longpollid" should check for only one condition and not be reused. For
|
||
example, a server which has a long poll wakeup only for new blocks might
|
||
use the previous block hash. However, clients should not assume the
|
||
"longpollid" has any specific meaning. It MAY supply the "longpolluri"
|
||
key with a relative or absolute URI, which MAY specify a completely
|
||
different resource than the original connection, including port number.
|
||
If "longpolluri" is provided by the server, clients MUST only attempt to
|
||
use that URI for longpoll requests.
|
||
|
||
Clients MAY start a longpoll request with a standard JSON-RPC request
|
||
(in the case of HTTP transport, POST with data) and same authorization,
|
||
setting the "longpollid" parameter in the request to the value provided
|
||
by the server.
|
||
|
||
This request SHOULD NOT be processed nor answered by the server until it
|
||
wishes to replace the current block data as identified by the
|
||
"longpollid". Clients SHOULD make this request with a very long request
|
||
timeout and MUST accept servers sending a partial response in advance
|
||
(such as HTTP headers with "chunked" Transfer-Encoding), and only
|
||
delaying the completion of the final JSON response until processing.
|
||
|
||
Upon receiving a completed response:
|
||
|
||
* Only if "submitold" is provided and false, the client MAY discard the
|
||
results of past operations and MUST begin working on the new work
|
||
immediately.
|
||
* The client SHOULD begin working on the new work received as soon as
|
||
possible, if not immediately.
|
||
* The client SHOULD make a new request to the same long polling URI.
|
||
|
||
If a client receives an incomplete or invalid response, it SHOULD retry
|
||
the request with an exponential backoff. Clients MAY implement this
|
||
backoff with limitations (such as maximum backoff time) or any algorithm
|
||
as deemed suitable. It is, however, forbidden to simply retry
|
||
immediately with no delay after more than one failure. In the case of a
|
||
"Forbidden" response (for example, HTTP 403), a client SHOULD NOT
|
||
attempt to retry without user intervention.
|
||
|
||
[[optional-template-tweaking]]
|
||
Optional: Template Tweaking
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|template request
|
||
|Key |Type |Description
|
||
|
||
|sigoplimit |Number or Boolean |maximum number of sigops to include in
|
||
template
|
||
|
||
|sizelimit |Number or Boolean |maximum number of bytes to use for the
|
||
entire block
|
||
|
||
|maxversion |Number |highest block version number supported
|
||
|=======================================================================
|
||
|
||
For "sigoplimit" and "sizelimit", negative values and zero are offset
|
||
from the server-determined block maximum. If a Boolean is provided and
|
||
true, the default limit is used; if false, the server is instructed not
|
||
to use any limits on returned template. Servers SHOULD respect these
|
||
desired maximums, but are NOT required to: clients SHOULD check that the
|
||
returned template satisfies their requirements appropriately.
|
||
|
||
[[appendix-example-rejection-reasons]]
|
||
Appendix: Example Rejection Reasons
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Possible reasons a share may be rejected include, but are not limited
|
||
to:
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=2| share rejection reasons
|
||
|Reason |Description
|
||
|
||
|bad-cb-flag |the server detected a feature-signifying flag that it does
|
||
not allow
|
||
|
||
|bad-cb-length |the coinbase was too long (bitcoin limit is 100 bytes)
|
||
|
||
|bad-cb-prefix |the server only allows appending to the coinbase, but it
|
||
was modified beyond that
|
||
|
||
|bad-diffbits |"bits" were changed
|
||
|
||
|bad-prevblk |the previous-block is not the one the server intends to
|
||
build on
|
||
|
||
|bad-txnmrklroot |the block header's merkle root did not match the
|
||
transaction merkle tree
|
||
|
||
|bad-txns |the server didn't like something about the transactions in
|
||
the block
|
||
|
||
|bad-version |the version was wrong
|
||
|
||
|duplicate |the server already processed this block data
|
||
|
||
|high-hash |the block header did not hash to a value lower than the
|
||
specified target
|
||
|
||
|rejected |a generic rejection without details
|
||
|
||
|stale-prevblk |the previous-block is no longer the one the server
|
||
intends to build on
|
||
|
||
|stale-work |the work this block was based on is no longer accepted
|
||
|
||
|time-invalid |the time was not acceptable
|
||
|
||
|time-too-new |the time was too far in the future
|
||
|
||
|time-too-old |the time was too far in the past
|
||
|
||
|unknown-user |the user submitting the block was not recognized
|
||
|
||
|unknown-work |the template or workid could not be identified
|
||
|=======================================================================
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
bitcoind's JSON-RPC server can no longer support the load of generating
|
||
the work required to productively mine Bitcoin, and external software
|
||
specializing in work generation has become necessary. At the same time,
|
||
new independent node implementations are maturing to the point where
|
||
they will also be able to support miners.
|
||
|
||
A common standard for communicating block construction details is
|
||
necessary to ensure compatibility between the full nodes and work
|
||
generation software.
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
Why not just deal with transactions as hashes (txids)?
|
||
|
||
* Servers might not have access to the transaction database, or miners
|
||
may wish to include transactions not broadcast to the network as a
|
||
whole.
|
||
* Miners may opt not to do full transaction verification, and may not
|
||
have access to the transaction database on their end.
|
||
|
||
What is the purpose of "workid"?
|
||
|
||
* If servers allow all mutations, it may be hard to identify which job
|
||
it is based on. While it may be possible to verify the submission by its
|
||
content, it is much easier to compare it to the job issued. It is very
|
||
easy for the miner to keep track of this. Therefore, using a "workid" is
|
||
a very cheap solution to enable more mutations.
|
||
|
||
Why should "sigops" be provided for transactions?
|
||
|
||
* Due to the link:bip-0016.mediawiki[BIP 0016] changes regarding rules
|
||
on block sigops, it is impossible to count sigops from the transactions
|
||
themselves (the sigops in the scriptCheck must also be included in the
|
||
count).
|
||
|
||
[[reference-implementation]]
|
||
Reference Implementation
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
* https://gitorious.org/bitcoin/eloipool[Eloipool (server)]
|
||
* http://gitorious.org/bitcoin/libblkmaker[libblkmaker (client)]
|
||
* https://github.com/bitcoin/bitcoin/pull/936/files[bitcoind (minimal
|
||
server)]
|
||
|
||
[[see-also]]
|
||
See Also
|
||
~~~~~~~~
|
||
|
||
* link:bip-0023.mediawiki[BIP 23: getblocktemplate - Pooled Mining]
|
||
|
||
---------------------------------------------
|
||
BIP: 23
|
||
Title: getblocktemplate - Pooled Mining
|
||
Author: Luke Dashjr <luke+bip22@dashjr.org>
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2012-02-28
|
||
---------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP describes extensions to the getblocktemplate JSON-RPC call to
|
||
enhance pooled mining.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
Note that all sections of this specification are optional extensions on
|
||
top of link:BIP 0022[BIP 22].
|
||
|
||
[[summary-support-levels]]
|
||
Summary Support Levels
|
||
^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Something can be said to have BIP 23 Level 1 support if it implements at
|
||
least:
|
||
|
||
* http://www.ietf.org/rfc/rfc1945.txt[RFC 1945]
|
||
* http://json-rpc.org/wiki/specification[JSON-RPC 1.0]
|
||
* link:bip-0022.mediawiki[BIP 22 (non-optional sections)]
|
||
* bip-0022.mediawiki#Optional:_Long_Polling[BIP 22 Long Polling]
|
||
* link:#Basic_Pool_Extensions[BIP 23 Basic Pool Extensions]
|
||
* link:#Mutations[BIP 23 Mutation "coinbase/append"]
|
||
* link:#Submission_Abbreviation[BIP 23 Submission Abbreviation
|
||
"submit/coinbase"]
|
||
* link:#Mutations[BIP 23 Mutation "time/increment"] (only required for
|
||
servers)
|
||
|
||
It can be said to have BIP 23 Level 2 support if it also implements:
|
||
|
||
* link:#Mutations[BIP 23 Mutation "transactions/add"]
|
||
* link:#Block_Proposals[BIP 23 Block Proposals]
|
||
|
||
[[basic-pool-extensions]]
|
||
Basic Pool Extensions
|
||
^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
[cols="",options="header",]
|
||
|==================================================================
|
||
|template request
|
||
|Key |Type |Description
|
||
|target |String |desired target for block template (may be ignored)
|
||
|==================================================================
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|template
|
||
|Key |Type |Description
|
||
|
||
|expires |Number |how many seconds (beginning from when the server sent
|
||
the response) this work is valid for, at most
|
||
|
||
|target |String |the number which valid results must be less than, in
|
||
big-endian hexadecimal
|
||
|=======================================================================
|
||
|
||
[[block-proposal]]
|
||
Block Proposal
|
||
^^^^^^^^^^^^^^
|
||
|
||
Servers may indicate support for proposing blocks by including a
|
||
capability string in their original template:
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|template
|
||
|Key |Type |Description
|
||
|
||
|capabilities |Array of Strings |MAY contain "proposal" to indicate
|
||
support for block proposal
|
||
|
||
|reject-reason |String |Reason the proposal was invalid as-is (only
|
||
applicable in response to proposals)
|
||
|=======================================================================
|
||
|
||
If supported, a miner MAY propose a block to the server for general
|
||
validation at any point before the job expires. This is accomplished by
|
||
calling getblocktemplate with two keys:
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=3| getblocktemplate parameters
|
||
|Key |Type |Description
|
||
|
||
|data |String |MUST be hex-encoded block data
|
||
|
||
|mode |String |MUST be "proposal"
|
||
|
||
|workid |String |if the server provided a workid, it MUST be included
|
||
with proposals
|
||
|=======================================================================
|
||
|
||
The block data MUST be validated and checked against the server's usual
|
||
acceptance rules (excluding the check for a valid proof-of-work). If it
|
||
is found to be in violation of any of these rules, the server MUST
|
||
return one of the following:
|
||
|
||
* Null if it is acceptable as-is, with the same workid (if any) as
|
||
provided. Note that this SHOULD NOT invalidate the old template's claim
|
||
to the same workid.
|
||
* A String giving the reason for the rejection (see
|
||
link:bip-0022.mediawiki#appendix-example-rejection-reasons[example
|
||
rejection reasons]).
|
||
* A "delta" block template (with changes needed); in this case, any
|
||
missing keys are assumed to default to those in the proposed block or,
|
||
if not applicable, the original block template it was based on. This
|
||
template MAY also include a "reject-reason" key with a String of the
|
||
reason for rejection.
|
||
|
||
It is RECOMMENDED that servers which merely need to track the proposed
|
||
block for later share/* submissions, return a simple Object of the form:
|
||
|
||
`{"workid":"new workid"}`
|
||
|
||
Clients SHOULD assume their proposed block will remain valid if the only
|
||
changes they make are to the portion of the coinbase scriptSig they
|
||
themselves provided (if any) and the time header. Servers SHOULD NOT
|
||
break this assumption without good cause.
|
||
|
||
[[mutations]]
|
||
Mutations
|
||
^^^^^^^^^
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|template request
|
||
|Key |Type |Description
|
||
|
||
|nonces |Number |size of nonce range the miner needs; if not provided,
|
||
the server SHOULD assume the client requires 2^32^
|
||
|=======================================================================
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=3| template
|
||
|Key |Type |Description
|
||
|
||
|maxtime |Number |the maximum time allowed
|
||
|
||
|maxtimeoff |Number |the maximum time allowed (as a moving offset from
|
||
"curtime" - every second, the actual maxtime is incremented by 1; for
|
||
example, "maxtimeoff":0 means "time" may be incremented by 1 every
|
||
second)
|
||
|
||
|mintime |Number |the minimum time allowed
|
||
|
||
|mintimeoff |Number |the minimum time allowed (as a moving offset from
|
||
"curtime")
|
||
|
||
|mutable |Array of Strings |different manipulations that the server
|
||
explicitly allows to be made
|
||
|
||
|noncerange |String |two 32-bit integers, concatenated in big-endian
|
||
hexadecimal, which represent the valid ranges of nonces the miner may
|
||
scan
|
||
|=======================================================================
|
||
|
||
If the block template contains a "mutable" key, it is a list of these to
|
||
signify modifications the miner is allowed to make:
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=2| mutations
|
||
|Value |Significance
|
||
|
||
|coinbase/append |append the provided coinbase scriptSig
|
||
|
||
|coinbase |provide their own coinbase; if one is provided, it may be
|
||
replaced or modified (implied if "coinbasetxn" omitted)
|
||
|
||
|generation |add or remove outputs from the coinbase/generation
|
||
transaction (implied if "coinbasetxn" omitted)
|
||
|
||
|time/increment |change the time header to a value after "time" (implied
|
||
if "maxtime" or "maxtimeoff" are provided)
|
||
|
||
|time/decrement |change the time header to a value before "time"
|
||
(implied if "mintime" is provided)
|
||
|
||
|time |modify the time header of the block
|
||
|
||
|transactions/add (or "transactions") |add other valid transactions to
|
||
the block (implied if "transactions" omitted from result)
|
||
|
||
|prevblock |use the work with other previous-blocks; this implicitly
|
||
allows removing transactions that are no longer valid (but clients
|
||
SHOULD attempt to propose removal of any required transactions); it also
|
||
implies adjusting "height" as necessary
|
||
|
||
|version/force |encode the provide block version, even if the miner
|
||
doesn't understand it
|
||
|
||
|version/reduce |use an older block version than the one provided (for
|
||
example, if the client does not support the version provided)
|
||
|=======================================================================
|
||
|
||
[[submission-abbreviation]]
|
||
Submission Abbreviation
|
||
^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=3| template
|
||
|Key |Type |Description
|
||
|
||
|fulltarget |String |the number which full results should be less than,
|
||
in big-endian hexadecimal (see "share/*" mutations)
|
||
|
||
|mutable |Array of Strings |different manipulations that the server
|
||
explicitly allows to be made, including abbreviations
|
||
|=======================================================================
|
||
|
||
If the block template contains a "mutable" key, it is a list of these to
|
||
signify modifications the miner is allowed to make:
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=2| abbreviation mutations
|
||
|Value |Significance
|
||
|
||
|submit/hash |each transaction being sent in a request, that the client
|
||
is certain the server knows about, may be replaced by its hash in
|
||
little-endian hexadecimal, prepended by a ":" character
|
||
|
||
|submit/coinbase |if the "transactions" provided by the server are used
|
||
as-is with no changes, submissions may omit transactions after the
|
||
coinbase (transaction count varint remains included with the full number
|
||
of transactions)
|
||
|
||
|submit/truncate |if the "coinbasetxn" and "transactions" provided by
|
||
the server are used as-is with no changes, submissions may contain only
|
||
the block header; if only the scriptSig of "coinbasetxn" is modified,
|
||
the params Object MUST contain a "coinbasesig" key with the content, or
|
||
a "coinbaseadd" with appended data (if only appending)
|
||
|
||
|share/coinbase |same as "submit/coinbase", but only if the block hash
|
||
is greater than "fulltarget"
|
||
|
||
|share/merkle |if the block hash is greater than "fulltarget", the
|
||
non-coinbase transactions may be replaced with a merkle chain connecting
|
||
it to the root
|
||
|
||
|share/truncate |same as "submit/truncate", but only if the block hash
|
||
is greater than "fulltarget"
|
||
|=======================================================================
|
||
|
||
[[format-of-data-for-merkle-only-shares]]
|
||
Format of Data for Merkle-Only Shares
|
||
+++++++++++++++++++++++++++++++++++++
|
||
|
||
The format used for submitting shares with the "share/merkle" mutation
|
||
shall be the 80-byte block header, the total number of transactions
|
||
encoded in Bitcoin variable length number format, the coinbase
|
||
transaction, and then finally the little-endian SHA256 hashes of each
|
||
link in the merkle chain connecting it to the merkle root.
|
||
|
||
[[logical-services]]
|
||
Logical Services
|
||
^^^^^^^^^^^^^^^^
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|template request
|
||
|Key |Type |Description
|
||
|
||
|capabilities |Array of Strings |miners which support this SHOULD
|
||
provide a list including the String "serverlist"
|
||
|=======================================================================
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=3| template
|
||
|Key |Type |Description
|
||
|
||
|serverlist |Array of Objects |list of servers in this single logical
|
||
service
|
||
|=======================================================================
|
||
|
||
If the "serverlist" parameter is provided, clients MAY choose to
|
||
intelligently treat the server as part of a larger single logical
|
||
service.
|
||
|
||
Each host Object in the Array is comprised of the following fields:
|
||
|
||
[cols="",options="header",]
|
||
|=======================================================================
|
||
|colspan=3| serverlist element
|
||
|Key |Type |Description
|
||
|
||
|uri |String |URI of the individual server; if authentication
|
||
information is omitted, the same authentication used for this request
|
||
MUST be assumed
|
||
|
||
|avoid |Number |number of seconds to avoid using this server
|
||
|
||
|priority |Number |an integer priority of this host (default: 0)
|
||
|
||
|sticky |Number |number of seconds to stick to this server when used
|
||
|
||
|update |Boolean |whether this server may update the serverlist
|
||
(default: true)
|
||
|
||
|weight |Number |a relative weight for hosts with the same priority
|
||
(default: 1)
|
||
|=======================================================================
|
||
|
||
When choosing which actual server to get the next job from, URIs MUST be
|
||
tried in order of their "priority" key, lowest Number first. Where the
|
||
priority of URIs is the same, they should be chosen from in random
|
||
order, weighed by their "weight" key. Work proposals and submissions
|
||
MUST be made to the same server that issued the job. Clients MAY attempt
|
||
to submit to other servers if, and only if, the original server cannot
|
||
be reached. If cross-server share submissions are desired, services
|
||
SHOULD instead use the equivalent domain name system (DNS) features
|
||
(RFCs http://tools.ietf.org/html/rfc1794[1794] and
|
||
http://tools.ietf.org/html/rfc2782[2782]).
|
||
|
||
Updates to the Logical Service server list may only be made by the
|
||
original server, or servers listed with the "update" key missing or
|
||
true. Clients MAY choose to advertise serverlist capability to servers
|
||
with a false "update" key, but if so, MUST treat the server list
|
||
provided as a subset of the current one, only considered in the context
|
||
of this server. At least one server with "update" privilege MUST be
|
||
attempted at least once daily.
|
||
|
||
If the "sticky" key is provided, then when that server is used, it
|
||
should be used consistently for at least that many seconds, if possible.
|
||
|
||
A permanent change in server URI MAY be indicated with a simple
|
||
"serverlist" parameter:
|
||
|
||
`"serverlist":[{"uri": "`http://newserver[`http://newserver`]`"}]`
|
||
|
||
A temporary delegation to another server for 5 minutes MAY be indicated
|
||
likewise:
|
||
|
||
`"serverlist":[{"uri": "", avoid: 300}, {"uri": "`http://newserver[`http://newserver`]`", "update": false}]`
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
There is reasonable concerns about mining currently being too
|
||
centralized on pools, and the amount of control these pools hold. By
|
||
exposing the details of the block proposals to the miners, they are
|
||
enabled to audit and possibly modify the block before hashing it.
|
||
|
||
To encourage widespread adoption, this BIP should be a complete superset
|
||
of the existing centralized getwork protocol, so pools are not required
|
||
to make substantial changes to adopt it.
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
Why allow servers to restrict the complete coinbase and nonce range?
|
||
|
||
* This is necessary to provide a complete superset of JSON-RPC getwork
|
||
functionality, so that pools may opt to enable auditing without
|
||
significantly changing or increasing the complexity of their share
|
||
validation or mining policies.
|
||
* Since noncerange is optional (both for getwork and this BIP), neither
|
||
clients nor servers are required to support it.
|
||
|
||
Why specify "time/*" mutations at all?
|
||
|
||
* In most cases, these are implied by the
|
||
mintime/mintimecur/maxtime/maxtimecur keys, but there may be cases that
|
||
there are no applicable minimums/maximums.
|
||
|
||
What is the purpose of the "prevblock" mutation?
|
||
|
||
* There are often cases where a miner has processed a new block before
|
||
the server. If the server allows "prevblock" mutation, the miner may
|
||
begin mining on the new block immediately, without waiting for a new
|
||
template.
|
||
|
||
Why must both "mintime"/"maxtime" and "mintimeoff"/"maxtimeoff" keys be
|
||
defined?
|
||
|
||
* In some cases, the limits may be unrelated to the current time (such
|
||
as the Bitcoin network itself; the minimum is always a fixed median
|
||
time)
|
||
* In other cases, the limits may be bounded by other rules (many pools
|
||
limit the time header to within 5 minutes of when the share is submitted
|
||
to them).
|
||
|
||
Is "target" really needed?
|
||
|
||
* Some pools work with lower targets, and should not be expected to
|
||
waste bandwidth ignoring shares that don't meet it.
|
||
* Required to be a proper superset of getwork.
|
||
* As mining hashrates grow, some miners may need the ability to request
|
||
a lower target from their pools to be able to manage their bandwidth
|
||
use.
|
||
|
||
What is the purpose of the "hash" transaction list format?
|
||
|
||
* Non-mining tools may wish to simply get a list of memory pool
|
||
transactions.
|
||
* Humans may wish to view their current memory pool.
|
||
|
||
[[reference-implementation]]
|
||
Reference Implementation
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
* http://gitorious.org/bitcoin/libblkmaker[libblkmaker]
|
||
* https://gitorious.org/bitcoin/eloipool[Eloipool]
|
||
* https://github.com/bitcoin/bitcoin/pull/936/files[bitcoind]
|
||
|
||
[[see-also]]
|
||
See Also
|
||
~~~~~~~~
|
||
|
||
* link:bip-0022.mediawiki[BIP 22: getblocktemplate - Fundamentals]
|
||
|
||
-------------------------------------------------
|
||
BIP: 30
|
||
Title: Duplicate transactions
|
||
Author: Pieter Wuille <pieter.wuille@gmail.com>
|
||
Status: Final
|
||
Type: Standards Track
|
||
Created: 2012-02-22
|
||
-------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This document gives a specification for dealing with duplicate
|
||
transactions in the block chain, in an attempt to solve certain problems
|
||
the reference implementations has with them.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
So far, the Bitcoin reference implementation always assumed duplicate
|
||
transactions (transactions with the same identifier) didn't exist. This
|
||
is not true; in particular coinbases are easy to duplicate, and by
|
||
building on duplicate coinbases, duplicate normal transactions are
|
||
possible as well. Recently, an attack that exploits the reference
|
||
implementation's dealing with duplicate transactions was described and
|
||
demonstrated. It allows reverting fully-confirmed transactions to a
|
||
single confirmation, making them vulnerable to become unspendable
|
||
entirely. Another attack is possible that allows forking the block chain
|
||
for a subset of the network.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
To counter this problem, the following network rule is introduced:
|
||
|
||
* Blocks are not allowed to contain a transaction whose identifier
|
||
matches that of an earlier, not-fully-spent transaction in the same
|
||
chain.
|
||
|
||
This rule initially applied to all blocks whose timestamp is after March
|
||
15, 2012, 00:00 UTC (testnet: February 20, 2012 00:00 UTC). It was later
|
||
extended by Commit
|
||
https://github.com/bitcoin/bitcoin/commit/ab91bf39b7c11e9c86bb2043c24f0f377f1cf514[Apply
|
||
BIP30 checks to all blocks except the two historic violations.] to apply
|
||
to all blocks except the two historic blocks at heights 91842 and 91880
|
||
on the main chain that had to be grandfathered in.
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
Whatever solution is used, the following law must be obeyed to guarantee
|
||
sane behaviour: the set of usable transactions outputs must not be
|
||
modified by adding blocks to the chain and removing them again. This
|
||
happens during a reorganisation, and the current Bitcoin reference
|
||
implementation does not obey this law in case the temporarily added
|
||
blocks contain a duplicate transaction.
|
||
|
||
There are several potential solutions to this problem:
|
||
|
||
1. Guarantee that all coinbases are unique, making duplicate
|
||
transactions very hard to create.
|
||
2. Remember previous remaining outputs of a given transaction
|
||
identifier, in case a new transaction with the same identifier is added.
|
||
3. Only allow duplicate transactions in case the previous instance of
|
||
the transaction had no spendable outputs left. Removing a block from the
|
||
chain can then safely reset the removed transaction's outputs to
|
||
nothing.
|
||
|
||
The first option is probably the most complete one, as it also
|
||
guarantees transaction identifiers are unique. However, implementing it
|
||
requires several changes that need to be accepted throughout the
|
||
network. Furthermore, it does not prevent duplicate transactions based
|
||
on earlier duplicate coinbases. The second option is impossible to
|
||
implement in a forward-compatible way, as it potentially renders
|
||
currently-invalid blocks valid. In this document we choose for the third
|
||
option, because it only requires a trivial change.
|
||
|
||
Fully-spent transactions are allowed to be duplicated in order not to
|
||
hinder pruning at some point in the future. Not allowing any transaction
|
||
to be duplicated would require evidence to be kept for each transaction
|
||
ever made.
|
||
|
||
[[backward-compatibility]]
|
||
Backward compatibility
|
||
~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The addition of this rule only makes some previously-valid blocks
|
||
invalid. This implies that if the rule is implemented by a supermajority
|
||
of miners, it is not possible to fork the block chain in a permanent way
|
||
between nodes with and without the new rule.
|
||
|
||
[[implementation]]
|
||
Implementation
|
||
~~~~~~~~~~~~~~
|
||
|
||
A patch for the reference client can be found on
|
||
https://github.com/sipa/bitcoin/tree/nooverwritetx
|
||
|
||
This BIP was implemented in Commit
|
||
https://github.com/bitcoin/bitcoin/commit/a206b0ea12eb4606b93323268fc81a4f1f952531[Do
|
||
not allow overwriting unspent transactions (BIP 30)] There have been
|
||
additional commits to refine the implementation of this BIP.
|
||
|
||
[[acknowledgements]]
|
||
Acknowledgements
|
||
~~~~~~~~~~~~~~~~
|
||
|
||
Thanks to Russell O'Connor for finding and demonstrating this problem,
|
||
and helping test the patch.
|
||
RECENT CHANGES:
|
||
|
||
* (16 Apr 2013) Added private derivation for i ≥ 0x80000000 (less risk
|
||
of parent private key leakage)
|
||
* (30 Apr 2013) Switched from multiplication by I~L~ to addition of I~L~
|
||
(faster, easier implementation)
|
||
* (25 May 2013) Added test vectors
|
||
* (15 Jan 2014) Rename keys with index ≥ 0x8000000 to hardened keys, and
|
||
add explicit conversion functions.
|
||
|
||
-------------------------------------------
|
||
BIP: 32
|
||
Title: Hierarchical Deterministic Wallets
|
||
Author: Pieter Wuille
|
||
Status: Accepted
|
||
Type: Informational
|
||
Created: 2012-02-11
|
||
-------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This document describes hierarchical determinstic wallets (or "HD
|
||
Wallets"): wallets which can be shared partially or entirely with
|
||
different systems, each with or without the ability to spend coins.
|
||
|
||
The specification is intended to set a standard for deterministic
|
||
wallets that can be interchanged between different clients. Although the
|
||
wallets described here have many features, not all are required by
|
||
supporting clients.
|
||
|
||
The specification consists of two parts. In a first part, a system for
|
||
deriving a tree of keypairs from a single seed is presented. The second
|
||
part demonstrates how to build a wallet structure on top of such a tree.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
The Bitcoin reference client uses randomly generated keys. In order to
|
||
avoid the necessity for a backup after every transaction, (by default)
|
||
100 keys are cached in a pool of reserve keys. Still, these wallets are
|
||
not intended to be shared and used on several systems simultaneously.
|
||
They support hiding their private keys by using the wallet encrypt
|
||
feature and not sharing the password, but such "neutered" wallets lose
|
||
the power to generate public keys as well.
|
||
|
||
Deterministic wallets do not require such frequent backups, and elliptic
|
||
curve mathematics permit schemes where one can calculate the public keys
|
||
without revealing the private keys. This permits for example a webshop
|
||
business to let its webserver generate fresh addresses (public key
|
||
hashes) for each order or for each customer, without giving the
|
||
webserver access to the corresponding private keys (which are required
|
||
for spending the received funds).
|
||
|
||
However, deterministic wallets typically consist of a single "chain" of
|
||
keypairs. The fact that there is only one chain means that sharing a
|
||
wallet happens on an all-or-nothing basis. However, in some cases one
|
||
only wants some (public) keys to be shared and recoverable. In the
|
||
example of a webshop, the webserver does not need access to all public
|
||
keys of the merchant's wallet; only to those addresses which are used to
|
||
receive customer's payments, and not for example the change addresses
|
||
that are generated when the merchant spends money. Hierarchical
|
||
deterministic wallets allow such selective sharing by supporting
|
||
multiple keypair chains, derived from a single root.
|
||
|
||
[[specification-key-derivation]]
|
||
Specification: Key derivation
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
[[conventions]]
|
||
Conventions
|
||
^^^^^^^^^^^
|
||
|
||
In the rest of this text we will assume the public key cryptography used
|
||
in Bitcoin, namely elliptic curve cryptography using the field and curve
|
||
parameters defined by secp256k1
|
||
(http://www.secg.org/index.php?action=secg,docs_secg). Variables below
|
||
are either:
|
||
|
||
* Integers modulo the order of the curve (referred to as n).
|
||
* Coordinates of points on the curve.
|
||
* Byte sequences.
|
||
|
||
Addition (+) of two coordinate pair is defined as application of the EC
|
||
group operation. Concatenation (||) is the operation of appending one
|
||
byte sequence onto another.
|
||
|
||
As standard conversion functions, we assume:
|
||
|
||
* point(p): returns the coordinate pair resulting from EC point
|
||
multiplication (repeated application of the EC group operation) of the
|
||
secp256k1 base point with the integer p.
|
||
* ser~32~(i): serialize a 32-bit unsigned integer i as a 4-byte
|
||
sequence, most significant byte first.
|
||
* ser~256~(p): serializes the integer p as a 32-byte sequence, most
|
||
significant byte first.
|
||
* ser~P~(P): serializes the coordinate pair P = (x,y) as a byte sequence
|
||
using SEC1's compressed form: (0x02 or 0x03) || ser~256~(x), where the
|
||
header byte depends on the parity of the omitted y coordinate.
|
||
* parse~256~(p): interprets a 32-byte sequence as a 256-bit number, most
|
||
significant byte first.
|
||
|
||
[[extended-keys]]
|
||
Extended keys
|
||
^^^^^^^^^^^^^
|
||
|
||
In what follows, we will define a function that derives a number of
|
||
child keys from a parent key. In order to prevent these from depending
|
||
solely on the key itself, we extend both private and public keys first
|
||
with an extra 256 bits of entropy. This extension, called the chain
|
||
code, is identical for corresponding private and public keys, and
|
||
consists of 32 bytes.
|
||
|
||
We represent an extended private key as (k, c), with k the normal
|
||
private key, and c the chain code. An extended public key is represented
|
||
as (K, c), with K = point(k) and c the chain code.
|
||
|
||
Each extended key has 2^31^ normal child keys, and 2^31^ hardened child
|
||
keys. Each of these child keys has an index. The normal child keys use
|
||
indices 0 through 2^31^-1. The hardened child keys use indices 2^31^
|
||
through 2^32^-1. To ease notation for hardened key indices, a number
|
||
i~H~ represents i+2^31^.
|
||
|
||
[[child-key-derivation-ckd-functions]]
|
||
Child key derivation (CKD) functions
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Given a parent extended key and an index i, it is possible to compute
|
||
the corresponding child extended key. The algorithm to do so depends on
|
||
whether the child is a hardened key or not (or, equivalently, whether i
|
||
≥ 2^31^), and whether we're talking about private or public keys.
|
||
|
||
[[private-parent-key-private-child-key]]
|
||
Private parent key → private child key
|
||
++++++++++++++++++++++++++++++++++++++
|
||
|
||
The function CKDpriv((k~par~, c~par~), i) → (k~i~, c~i~) computes a
|
||
child extended private key from the parent extended private key:
|
||
|
||
* Check whether i ≥ 2^31^ (whether the child is a hardened key).
|
||
** If so (hardened child): let I = HMAC-SHA512(Key = c~par~, Data = 0x00
|
||
|| ser~256~(k~par~) || ser~32~(i)). (Note: The 0x00 pads the private key
|
||
to make it 33 bytes long.)
|
||
** If not (normal child): let I = HMAC-SHA512(Key = c~par~, Data =
|
||
ser~P~(point(k~par~)) || ser~32~(i)).
|
||
* Split I into two 32-byte sequences, I~L~ and I~R~.
|
||
* The returned child key k~i~ is parse~256~(I~L~) + k~par~ (mod n).
|
||
* The returned chain code c~i~ is I~R~.
|
||
* In case parse~256~(I~L~) ≥ n or k~i~ = 0, the resulting key is
|
||
invalid, and one should proceed with the next value for i. (Note: this
|
||
has probability lower than 1 in 2^127^.)
|
||
|
||
The HMAC-SHA512 function is specified in
|
||
http://tools.ietf.org/html/rfc4231[RFC 4231].
|
||
|
||
[[public-parent-key-public-child-key]]
|
||
Public parent key → public child key
|
||
++++++++++++++++++++++++++++++++++++
|
||
|
||
The function CKDpub((K~par~, c~par~), i) → (K~i~, c~i~) computes a child
|
||
extended public key from the parent extended public key. It is only
|
||
defined for non-hardened child keys.
|
||
|
||
* Check whether i ≥ 2^31^ (whether the child is a hardened key).
|
||
** If so (hardened child): return failure
|
||
** If not (normal child): let I = HMAC-SHA512(Key = c~par~, Data =
|
||
ser~P~(K~par~) || ser~32~(i)).
|
||
* Split I into two 32-byte sequences, I~L~ and I~R~.
|
||
* The returned child key K~i~ is point(parse~256~(I~L~)) + K~par~.
|
||
* The returned chain code c~i~ is I~R~.
|
||
* In case parse~256~(I~L~) ≥ n or K~i~ is the point at infinity, the
|
||
resulting key is invalid, and one should proceed with the next value for
|
||
i.
|
||
|
||
[[private-parent-key-public-child-key]]
|
||
Private parent key → public child key
|
||
+++++++++++++++++++++++++++++++++++++
|
||
|
||
The function N((k, c)) → (K, c) computes the extended public key
|
||
corresponding to an extended private key (the "neutered" version, as it
|
||
removes the ability to sign transactions).
|
||
|
||
* The returned key K is point(k).
|
||
* The returned chain code c is just the passed chain code.
|
||
|
||
To compute the public child key of a parent private key:
|
||
|
||
* N(CKDpriv((k~par~, c~par~), i)) (works always).
|
||
* CKDpub(N(k~par~, c~par~), i) (works only for non-hardened child keys).
|
||
|
||
The fact that they are equivalent is what makes non-hardened keys useful
|
||
(one can derive child public keys of a given parent key without knowing
|
||
any private key), and also what distinguishes them from hardened keys.
|
||
The reason for not always using non-hardened keys (which are more
|
||
useful) is security; see further for more information.
|
||
|
||
[[public-parent-key-private-child-key]]
|
||
Public parent key → private child key
|
||
+++++++++++++++++++++++++++++++++++++
|
||
|
||
This is not possible.
|
||
|
||
[[the-key-tree]]
|
||
The key tree
|
||
^^^^^^^^^^^^
|
||
|
||
The next step is cascading several CKD constructions to build a tree. We
|
||
start with one root, the master extended key m. By evaluating
|
||
CKDpriv(m,i) for several values of i, we get a number of level-1 derived
|
||
nodes. As each of these is again an extended key, CKDpriv can be applied
|
||
to those as well.
|
||
|
||
To shorten notation, we will write CKDpriv(CKDpriv(CKDpriv(m,3~H~),2),5)
|
||
as m/3~H~/2/5. Equivalently for public keys, we write
|
||
CKDpub(CKDpub(CKDpub(M,3),2,5) as M/3/2/5. This results in the following
|
||
identities:
|
||
|
||
* N(m/a/b/c) = N(m/a/b)/c = N(m/a)/b/c = N(m)/a/b/c = M/a/b/c.
|
||
* N(m/a~H~/b/c) = N(m/a~H~/b)/c = N(m/a~H~)/b/c.
|
||
|
||
However, N(m/a~H~) cannot be rewritten as N(m)/a~H~, as the latter is
|
||
not possible.
|
||
|
||
Each leaf node in the tree corresponds to an actual key, while the
|
||
internal nodes correspond to the collections of keys that descend from
|
||
them. The chain codes of the leaf nodes are ignored, and only their
|
||
embedded private or public key is relevant. Because of this
|
||
construction, knowing an extended private key allows reconstruction of
|
||
all descendant private keys and public keys, and knowing an extended
|
||
public keys allows reconstruction of all descendant non-hardened public
|
||
keys.
|
||
|
||
[[key-identifiers]]
|
||
Key identifiers
|
||
^^^^^^^^^^^^^^^
|
||
|
||
Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256)
|
||
of the serialized public key, ignoring the chain code. This corresponds
|
||
exactly to the data used in traditional Bitcoin addresses. It is not
|
||
advised to represent this data in base58 format though, as it may be
|
||
interpreted as an address that way (and wallet software is not required
|
||
to accept payment to the chain key itself).
|
||
|
||
The first 32 bits of the identifier are called the key fingerprint.
|
||
|
||
[[serialization-format]]
|
||
Serialization format
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Extended public and private keys are serialized as follows:
|
||
|
||
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private;
|
||
testnet: 0x043587CF public, 0x04358394 private)
|
||
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 derived keys,
|
||
....
|
||
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master
|
||
key)
|
||
* 4 bytes: child number. This is ser~32~(i) for i in x~i~ = x~par~/i,
|
||
with x~i~ the key being serialized. (0x00000000 if master key)
|
||
* 32 bytes: the chain code
|
||
* 33 bytes: the public key or private key data (ser~P~(K) for public
|
||
keys, 0x00 || ser~256~(k) for private keys)
|
||
|
||
This 78 byte structure can be encoded like other Bitcoin data in Base58,
|
||
by first adding 32 checksum bits (derived from the double SHA-256
|
||
checksum), and then converting to the Base58 representation. This
|
||
results in a Base58-encoded string of up to 112 characters. Because of
|
||
the choice of the version bytes, the Base58 representation will start
|
||
with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.
|
||
|
||
Note that the fingerprint of the parent only serves as a fast way to
|
||
detect parent and child nodes in software, and software must be willing
|
||
to deal with collisions. Internally, the full 160-bit identifier could
|
||
be used.
|
||
|
||
When importing a serialized extended public key, implementations must
|
||
verify whether the X coordinate in the public key data corresponds to a
|
||
point on the curve. If not, the extended public key is invalid.
|
||
|
||
[[master-key-generation]]
|
||
Master key generation
|
||
^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
The total number of possible extended keypairs is almost 2^512^, but the
|
||
produced keys are only 256 bits long, and offer about half of that in
|
||
terms of security. Therefore, master keys are not generated directly,
|
||
but instead from a potentially short seed value.
|
||
|
||
* Generate a seed byte sequence S of a chosen length (between 128 and
|
||
512 bits; 256 bits is advised) from a (P)RNG.
|
||
* Calculate I = HMAC-SHA512(Key = "Bitcoin seed", Data = S)
|
||
* Split I into two 32-byte sequences, I~L~ and I~R~.
|
||
* Use parse~256~(I~L~) as master secret key, and I~R~ as master chain
|
||
code.
|
||
|
||
In case I~L~ is 0 or ≥n, the master key is invalid.
|
||
|
||
[[specification-wallet-structure]]
|
||
Specification: Wallet structure
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The previous sections specified key trees and their nodes. The next step
|
||
is imposing a wallet structure on this tree. The layout defined in this
|
||
section is a default only, though clients are encouraged to mimick it
|
||
for compatibility, even if not all features are supported.
|
||
|
||
[[the-default-wallet-layout]]
|
||
The default wallet layout
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
An HDW is organized as several 'accounts'. Accounts are numbered, the
|
||
default account ("") being number 0. Clients are not required to support
|
||
more than one account - if not, they only use the default account.
|
||
|
||
Each account is composed of two keypair chains: an internal and an
|
||
external one. The external keychain is used to generate new public
|
||
addresses, while the internal keychain is used for all other operations
|
||
(change addresses, generation addresses, ..., anything that doesn't need
|
||
to be communicated). Clients that do not support separate keychains for
|
||
these should use the external one for everything.
|
||
|
||
* m/i~H~/0/k corresponds to the k'th keypair of the external chain of
|
||
account number i of the HDW derived from master m.
|
||
* m/i~H~/1/k corresponds to the k'th keypair of the internal chain of
|
||
account number i of the HDW derived from master m.
|
||
|
||
[[use-cases]]
|
||
Use cases
|
||
^^^^^^^^^
|
||
|
||
[[full-wallet-sharing-m]]
|
||
Full wallet sharing: m
|
||
++++++++++++++++++++++
|
||
|
||
In cases where two systems need to access a single shared wallet, and
|
||
both need to be able to perform spendings, one needs to share the master
|
||
private extended key. Nodes can keep a pool of N look-ahead keys cached
|
||
for external chains, to watch for incoming payments. The look-ahead for
|
||
internal chains can be very small, as no gaps are to be expected here.
|
||
An extra look-ahead could be active for the first unused account's
|
||
chains - triggering the creation of a new account when used. Note that
|
||
the name of the account will still need to be entered manually and
|
||
cannot be synchronized via the block chain.
|
||
|
||
[[audits-nm]]
|
||
Audits: N(m/*)
|
||
++++++++++++++
|
||
|
||
In case an auditor needs full access to the list of incoming and
|
||
outgoing payments, one can share all account public extended keys. This
|
||
will allow the auditor to see all transactions from and to the wallet,
|
||
in all accounts, but not a single secret key.
|
||
|
||
[[per-office-balances-mih]]
|
||
Per-office balances: m/i~H~
|
||
+++++++++++++++++++++++++++
|
||
|
||
When a business has several independent offices, they can all use
|
||
wallets derived from a single master. This will allow the headquarters
|
||
to maintain a super-wallet that sees all incoming and outgoing
|
||
transactions of all offices, and even permit moving money between the
|
||
offices.
|
||
|
||
[[recurrent-business-to-business-transactions-nmih0]]
|
||
Recurrent business-to-business transactions: N(m/i~H~/0)
|
||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
||
In case two business partners often transfer money, one can use the
|
||
extended public key for the external chain of a specific account (M/i
|
||
h/0) as a sort of "super address", allowing frequent transactions that
|
||
cannot (easily) be associated, but without needing to request a new
|
||
address for each payment. Such a mechanism could also be used by mining
|
||
pool operators as variable payout address.
|
||
|
||
[[unsecure-money-receiver-nmih0]]
|
||
Unsecure money receiver: N(m/i~H~/0)
|
||
++++++++++++++++++++++++++++++++++++
|
||
|
||
When an unsecure webserver is used to run an e-commerce site, it needs
|
||
to know public addresses that are used to receive payments. The
|
||
webserver only needs to know the public extended key of the external
|
||
chain of a single account. This means someone illegally obtaining access
|
||
to the webserver can at most see all incoming payments, but will not
|
||
(trivially) be able to distinguish outgoing transactions, nor see
|
||
payments received by other webservers if there are several ones.
|
||
|
||
[[compatibility]]
|
||
Compatibility
|
||
~~~~~~~~~~~~~
|
||
|
||
To comply with this standard, a client must at least be able to import
|
||
an extended public or private key, to give access to its direct
|
||
descendants as wallet keys. The wallet structure
|
||
(master/account/chain/subchain) presented in the second part of the
|
||
specification is advisory only, but is suggested as a minimal structure
|
||
for easy compatibility - even when no separate accounts or distinction
|
||
between internal and external chains is made. However, implementations
|
||
may deviate from it for specific needs; more complex applications may
|
||
call for a more complex tree structure.
|
||
|
||
[[security]]
|
||
Security
|
||
~~~~~~~~
|
||
|
||
In addition to the expectations from the EC public-key cryptography
|
||
itself:
|
||
|
||
* Given a public key K, an attacker cannot find the corresponding
|
||
private key more efficiently than by solving the EC discrete logarithm
|
||
problem (assumed to require 2^128^ group operations).
|
||
|
||
the intended security properties of this standard are:
|
||
|
||
* Given a child extended private key (k~i~,c~i~) and the integer i, an
|
||
attacker cannot find the parent private key k~par~ more efficiently than
|
||
a 2^256^ brute force of HMAC-SHA512.
|
||
* Given any number (2 ≤ N ≤ 2^32^-1) of (index, extended private key)
|
||
tuples (i~j~,(k~i~j~~,c~i~j~~)), with distinct i~j~'s, determining
|
||
whether they are derived from a common parent extended private key
|
||
(i.e., whether there exists a (k~par~,c~par~) such that for each j in
|
||
(0..N-1) CKDpriv((k~par~,c~par~),i~j~)=(k~i~j~~,c~i~j~~)), cannot be
|
||
done more efficiently than a 2^256^ brute force of HMAC-SHA512.
|
||
|
||
Note however that the following properties does not exist:
|
||
|
||
* Given a parent extended public key (K~par~,c~par~) and a child public
|
||
key (K~i~), it is hard to find i.
|
||
* Given a parent extended public key (K~par~,c~par~) and a non-hardened
|
||
child private key (k~i~), it is hard to find k~par~.
|
||
|
||
[[implications]]
|
||
Implications
|
||
^^^^^^^^^^^^
|
||
|
||
Private and public keys must be kept safe as usual. Leaking a private
|
||
key means access to coins - leaking a public key can mean loss of
|
||
privacy.
|
||
|
||
Somewhat more care must be taken regarding extended keys, as these
|
||
correspond to an entire (sub)tree of keys.
|
||
|
||
One weakness that may not be immediately obvious, is that knowledge of
|
||
the extended public key + any non-hardened private key descending from
|
||
it is equivalent to knowing the extended private key (and thus every
|
||
private and public key descending from it). This means that extended
|
||
public keys must be treated more carefully than regular public keys. It
|
||
is also the reason for the existence of hardened keys, and why they are
|
||
used for the account level in the tree. This way, a leak of
|
||
account-specific (or below) private key never risks compromising the
|
||
master or other accounts.
|
||
|
||
[[test-vectors]]
|
||
Test Vectors
|
||
~~~~~~~~~~~~
|
||
|
||
[[test-vector-1]]
|
||
Test vector 1
|
||
^^^^^^^^^^^^^
|
||
|
||
Master (hex): 000102030405060708090a0b0c0d0e0f
|
||
|
||
* Chain m
|
||
** ext pub:
|
||
xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8
|
||
** ext prv:
|
||
xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi
|
||
* Chain m/0~H~
|
||
** ext pub:
|
||
xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
|
||
** ext prv:
|
||
xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
|
||
* Chain m/0~H~/1
|
||
** ext pub:
|
||
xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47sSikHjJf3UFHKkNAWbWMiGj7Wf5uMash7SyYq527Hqck2AxYysAA7xmALppuCkwQ
|
||
** ext prv:
|
||
xprv9wTYmMFdV23N2TdNG573QoEsfRrWKQgWeibmLntzniatZvR9BmLnvSxqu53Kw1UmYPxLgboyZQaXwTCg8MSY3H2EU4pWcQDnRnrVA1xe8fs
|
||
* Chain m/0~H~/1/2~H~
|
||
** ext pub:
|
||
xpub6D4BDPcP2GT577Vvch3R8wDkScZWzQzMMUm3PWbmWvVJrZwQY4VUNgqFJPMM3No2dFDFGTsxxpG5uJh7n7epu4trkrX7x7DogT5Uv6fcLW5
|
||
** ext prv:
|
||
xprv9z4pot5VBttmtdRTWfWQmoH1taj2axGVzFqSb8C9xaxKymcFzXBDptWmT7FwuEzG3ryjH4ktypQSAewRiNMjANTtpgP4mLTj34bhnZX7UiM
|
||
* Chain m/0~H~/1/2~H~/2
|
||
** ext pub:
|
||
xpub6FHa3pjLCk84BayeJxFW2SP4XRrFd1JYnxeLeU8EqN3vDfZmbqBqaGJAyiLjTAwm6ZLRQUMv1ZACTj37sR62cfN7fe5JnJ7dh8zL4fiyLHV
|
||
** ext prv:
|
||
xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334
|
||
* Chain m/0~H~/1/2~H~/2/1000000000
|
||
** ext pub:
|
||
xpub6H1LXWLaKsWFhvm6RVpEL9P4KfRZSW7abD2ttkWP3SSQvnyA8FSVqNTEcYFgJS2UaFcxupHiYkro49S8yGasTvXEYBVPamhGW6cFJodrTHy
|
||
** ext prv:
|
||
xprvA41z7zogVVwxVSgdKUHDy1SKmdb533PjDz7J6N6mV6uS3ze1ai8FHa8kmHScGpWmj4WggLyQjgPie1rFSruoUihUZREPSL39UNdE3BBDu76
|
||
|
||
[[test-vector-2]]
|
||
Test vector 2
|
||
^^^^^^^^^^^^^
|
||
|
||
Master (hex):
|
||
fffcf9f6f3f0edeae7e4e1dedbd8d5d2cfccc9c6c3c0bdbab7b4b1aeaba8a5a29f9c999693908d8a8784817e7b7875726f6c696663605d5a5754514e4b484542
|
||
|
||
* Chain m
|
||
** ext pub:
|
||
xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB
|
||
** ext prv:
|
||
xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U
|
||
* Chain m/0
|
||
** ext pub:
|
||
xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH
|
||
** ext prv:
|
||
xprv9vHkqa6EV4sPZHYqZznhT2NPtPCjKuDKGY38FBWLvgaDx45zo9WQRUT3dKYnjwih2yJD9mkrocEZXo1ex8G81dwSM1fwqWpWkeS3v86pgKt
|
||
* Chain m/0/2147483647~H~
|
||
** ext pub:
|
||
xpub6ASAVgeehLbnwdqV6UKMHVzgqAG8Gr6riv3Fxxpj8ksbH9ebxaEyBLZ85ySDhKiLDBrQSARLq1uNRts8RuJiHjaDMBU4Zn9h8LZNnBC5y4a
|
||
** ext prv:
|
||
xprv9wSp6B7kry3Vj9m1zSnLvN3xH8RdsPP1Mh7fAaR7aRLcQMKTR2vidYEeEg2mUCTAwCd6vnxVrcjfy2kRgVsFawNzmjuHc2YmYRmagcEPdU9
|
||
* Chain m/0/2147483647~H~/1
|
||
** ext pub:
|
||
xpub6DF8uhdarytz3FWdA8TvFSvvAh8dP3283MY7p2V4SeE2wyWmG5mg5EwVvmdMVCQcoNJxGoWaU9DCWh89LojfZ537wTfunKau47EL2dhHKon
|
||
** ext prv:
|
||
xprv9zFnWC6h2cLgpmSA46vutJzBcfJ8yaJGg8cX1e5StJh45BBciYTRXSd25UEPVuesF9yog62tGAQtHjXajPPdbRCHuWS6T8XA2ECKADdw4Ef
|
||
* Chain m/0/2147483647~H~/1/2147483646~H~
|
||
** ext pub:
|
||
xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL
|
||
** ext prv:
|
||
xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc
|
||
* Chain m/0/2147483647~H~/1/2147483646~H~/2
|
||
** ext pub:
|
||
xpub6FnCn6nSzZAw5Tw7cgR9bi15UV96gLZhjDstkXXxvCLsUXBGXPdSnLFbdpq8p9HmGsApME5hQTZ3emM2rnY5agb9rXpVGyy3bdW6EEgAtqt
|
||
** ext prv:
|
||
xprvA2nrNbFZABcdryreWet9Ea4LvTJcGsqrMzxHx98MMrotbir7yrKCEXw7nadnHM8Dq38EGfSh6dqA9QWTyefMLEcBYJUuekgW4BYPJcr9E7j
|
||
|
||
[[implementations]]
|
||
Implementations
|
||
~~~~~~~~~~~~~~~
|
||
|
||
Two Python implementations exist:
|
||
|
||
PyCoin (https://github.com/richardkiss/pycoin) is a suite of utilities
|
||
for dealing with Bitcoin that includes BIP0032 wallet features.
|
||
BIP32Utils (https://github.com/jmcorgan/bip32utils) is a library and
|
||
command line interface specifically focused on BIP0032 wallets and
|
||
scripting.
|
||
|
||
A Java implementation is available at
|
||
https://github.com/bitsofproof/supernode/blob/1.1/api/src/main/java/com/bitsofproof/supernode/api/ExtendedKey.java
|
||
|
||
A C++ implementation is available at
|
||
https://github.com/CodeShark/CoinClasses/tree/master/tests/hdwallets
|
||
|
||
An Objective-C implementation is available at
|
||
https://github.com/oleganza/CoreBitcoin/blob/master/CoreBitcoin/BTCKeychain.h
|
||
|
||
A Ruby implementation is available at https://github.com/wink/money-tree
|
||
|
||
A Go implementation is available at
|
||
https://github.com/WeMeetAgain/go-hdwallet
|
||
|
||
A JavaScript implementation is available at
|
||
https://github.com/sarchar/brainwallet.github.com/tree/bip32
|
||
|
||
A PHP implemetation is available at
|
||
https://github.com/Bit-Wasp/bitcoin-lib-php
|
||
|
||
A C# implementation is available at
|
||
https://github.com/NicolasDorier/NBitcoin (ExtKey, ExtPubKey)
|
||
|
||
[[acknowledgements]]
|
||
Acknowledgements
|
||
~~~~~~~~~~~~~~~~
|
||
|
||
* Gregory Maxwell for the original idea of type-2 deterministic wallets,
|
||
and many discussions about it.
|
||
* Alan Reiner for the implementation of this scheme in Armory, and the
|
||
suggestions that followed from that.
|
||
* Mike Caldwell for the version bytes to obtain human-recognizable
|
||
Base58 strings.
|
||
|
||
--------------------------------------------------
|
||
BIP: 34
|
||
Title: Block v2, Height in Coinbase
|
||
Author: Gavin Andresen <gavinandresen@gmail.com>
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2012-07-06
|
||
--------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
Bitcoin blocks and transactions are versioned binary structures. Both
|
||
currently use version 1. This BIP introduces an upgrade path for
|
||
versioned transactions and blocks. A unique value is added to newly
|
||
produced coinbase transactions, and blocks are updated to version 2.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
1. Clarify and exercise the mechanism whereby the bitcoin network
|
||
collectively consents to upgrade transaction or block binary structures,
|
||
rules and behaviors.
|
||
2. Enforce block and transaction uniqueness, and assist unconnected
|
||
block validation.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
1. Treat transactions with a version greater than 1 as non-standard
|
||
(official Satoshi client will not mine or relay them).
|
||
2. Add height as the first item in the coinbase transaction's
|
||
scriptSig, and increase block version to 2. The format of the height is
|
||
"serialized CScript" -- first byte is number of bytes in the number
|
||
(will be 0x03 on main net for the next 300 or so years), following bytes
|
||
are little-endian representation of the number. Height is the height of
|
||
the mined block in the block chain, where the genesis block is height
|
||
zero (0).
|
||
3. 75% rule: If 750 of the last 1,000 blocks are version 2 or greater,
|
||
reject invalid version 2 blocks. (testnet3: 51 of last 100)
|
||
4. 95% rule ("Point of no return"): If 950 of the last 1,000 blocks are
|
||
version 2 or greater, reject all version 1 blocks. (testnet3: 75 of last
|
||
100)
|
||
|
||
[[backward-compatibility]]
|
||
Backward compatibility
|
||
~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
All older clients are compatible with this change. Users and merchants
|
||
should not be impacted. Miners are strongly recommended to upgrade to
|
||
version 2 blocks. Once 95% of the miners have upgraded to version 2, the
|
||
remainder will be orphaned if they fail to upgrade.
|
||
|
||
[[implementation]]
|
||
Implementation
|
||
~~~~~~~~~~~~~~
|
||
|
||
https://github.com/bitcoin/bitcoin/pull/1526
|
||
-------------------------------------------
|
||
BIP: 35
|
||
Title: mempool message
|
||
Author: Jeff Garzik <jgarzik@exmulti.com>
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2012-08-16
|
||
-------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
Make a network node's transaction memory pool accessible via a new
|
||
"mempool" message. Extend the existing "getdata" message behavior to
|
||
permit accessing the transaction memory pool.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
Several use cases make it desireable to expose a network node's
|
||
transaction memory pool:
|
||
|
||
1. SPV clients, wishing to obtain zero-confirmation transactions sent
|
||
or received.
|
||
2. Miners, to avoid missing lucrative fees, downloading existing
|
||
network transactions after a restart.
|
||
3. Remote network diagnostics.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
1. The mempool message is defined as an empty message where pchCommand
|
||
== "mempool"
|
||
2. Upon receipt of a "mempool" message, the node will respond with an
|
||
"inv" message containing MSG_TX hashes of all the transactions in the
|
||
node's transaction memory pool, if any.
|
||
3. The typical node behavior in response to an "inv" is "getdata".
|
||
However, the reference Satoshi implementation ignores requests for
|
||
transaction hashes outside that which is recently relayed. To support
|
||
"mempool", an implementation must extend its "getdata" message support
|
||
to querying the memory pool.
|
||
4. Feature discovery is enabled by checking two "version" message
|
||
attributes:
|
||
1. Protocol version >= 60002
|
||
2. NODE_NETWORK bit set in nServices
|
||
|
||
Note that existing implementations drop "inv" messages with a vector
|
||
size > 50000.
|
||
|
||
[[backward-compatibility]]
|
||
Backward compatibility
|
||
~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Older clients remain 100% compatible and interoperable after this
|
||
change.
|
||
|
||
[[implementation]]
|
||
Implementation
|
||
~~~~~~~~~~~~~~
|
||
|
||
https://github.com/bitcoin/bitcoin/pull/1641
|
||
-----------------------------------------------------------------------
|
||
BIP: 37
|
||
Title: Connection Bloom filtering
|
||
Author: Mike Hearn <hearn@google.com>, Matt Corallo <bip@bluematt.me>
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2012-10-24
|
||
-----------------------------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP adds new support to the peer-to-peer protocol that allows peers
|
||
to reduce the amount of transaction data they are sent. Peers have the
|
||
option of setting _filters_ on each connection they make after the
|
||
version handshake has completed. A filter is defined as a
|
||
http://en.wikipedia.org/wiki/Bloom_filter[Bloom filter] on data derived
|
||
from transactions. A Bloom filter is a probabilistic data structure
|
||
which allows for testing set membership - they can have false positives
|
||
but not false negatives.
|
||
|
||
This document will not go into the details of how Bloom filters work and
|
||
the reader is referred to Wikipedia for an introduction to the topic.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
As Bitcoin grows in usage the amount of bandwidth needed to download
|
||
blocks and transaction broadcasts increases. Clients implementing
|
||
_simplified payment verification_ do not attempt to fully verify the
|
||
block chain, instead just checking that block headers connect together
|
||
correctly and trusting that the transactions in a chain of high
|
||
difficulty are in fact valid. See the Bitcoin paper for more detail on
|
||
this mode.
|
||
|
||
Today, link:Simplified_Payment_Verification[SPV] clients have to
|
||
download the entire contents of blocks and all broadcast transactions,
|
||
only to throw away the vast majority of the transactions that are not
|
||
relevant to their wallets. This slows down their synchronization
|
||
process, wastes users bandwidth (which on phones is often metered) and
|
||
increases memory usage. All three problems are triggering real user
|
||
complaints for the Android "Bitcoin Wallet" app which implements SPV
|
||
mode. In order to make chain synchronization fast, cheap and able to run
|
||
on older phones with limited memory we want to have remote peers throw
|
||
away irrelevant transactions before sending them across the network.
|
||
|
||
[[design-rationale]]
|
||
Design rationale
|
||
~~~~~~~~~~~~~~~~
|
||
|
||
The most obvious way to implement the stated goal would be for clients
|
||
to upload lists of their keys to the remote node. We take a more complex
|
||
approach for the following reasons:
|
||
|
||
* Privacy: Because Bloom filters are probabilistic, with the false
|
||
positive rate chosen by the client, nodes can trade off precision vs
|
||
bandwidth usage. A node with access to lots of bandwidth may choose to
|
||
have a high FP rate, meaning the remote peer cannot accurately know
|
||
which transactions belong to the client and which don't. A node with
|
||
very little bandwidth may choose to use a very accurate filter meaning
|
||
that they only get sent transactions actually relevant to their wallet,
|
||
but remote peers may be able to correlate transactions with IP addresses
|
||
(and each other).
|
||
* Bloom filters are compact and testing membership in them is fast. This
|
||
results in satisfying performance characteristics with minimal risk of
|
||
opening up potential for DoS attacks.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
[[new-messages]]
|
||
New messages
|
||
^^^^^^^^^^^^
|
||
|
||
We start by adding three new messages to the protocol:
|
||
|
||
* `filterload`, which sets the current Bloom filter on the connection
|
||
* `filteradd`, which adds the given data element to the connections
|
||
current filter without requiring a completely new one to be set
|
||
* `filterclear`, which deletes the current filter and goes back to
|
||
regular pre-BIP37 usage.
|
||
|
||
Note that there is no filterremove command because by their nature,
|
||
Bloom filters are append-only data structures. Once an element is added
|
||
it cannot be removed again without rebuilding the entire structure from
|
||
scratch.
|
||
|
||
The `filterload` command is defined as follows:
|
||
|
||
[cols=",,,",options="header",]
|
||
|=======================================================================
|
||
|Field Size |Description |Data type |Comments
|
||
|? |filter |uint8_t[] |The filter itself is simply a bit field of
|
||
arbitrary byte-aligned size. The maximum size is 36,000 bytes.
|
||
|
||
|4 |nHashFuncs |uint32_t |The number of hash functions to use in this
|
||
filter. The maximum value allowed in this field is 50.
|
||
|
||
|4 |nTweak |uint32_t |A random value to add to the seed value in the
|
||
hash function used by the bloom filter.
|
||
|
||
|1 |nFlags |uint8_t |A set of flags that control how matched items are
|
||
added to the filter.
|
||
|=======================================================================
|
||
|
||
See below for a description of the Bloom filter algorithm and how to
|
||
select nHashFuncs and filter size for a desired false positive rate.
|
||
|
||
Upon receiving a `filterload` command, the remote peer will immediately
|
||
restrict the broadcast transactions it announces (in inv packets) to
|
||
transactions matching the filter, where the matching algorithm is
|
||
specified below. The flags control the update behaviour of the matching
|
||
algorithm.
|
||
|
||
The `filteradd` command is defined as follows:
|
||
|
||
[cols=",,,",options="header",]
|
||
|==================================================================
|
||
|Field Size |Description |Data type |Comments
|
||
|? |data |uint8_t[] |The data element to add to the current filter.
|
||
|==================================================================
|
||
|
||
The data field must be smaller than or equal to 520 bytes in size (the
|
||
maximum size of any potentially matched object).
|
||
|
||
The given data element will be added to the Bloom filter. A filter must
|
||
have been previously provided using `filterload`. This command is useful
|
||
if a new key or script is added to a clients wallet whilst it has
|
||
connections to the network open, it avoids the need to re-calculate and
|
||
send an entirely new filter to every peer (though doing so is usually
|
||
advisable to maintain anonymity).
|
||
|
||
The `filterclear` command has no arguments at all.
|
||
|
||
After a filter has been set, nodes don't merely stop announcing
|
||
non-matching transactions, they can also serve filtered blocks. A
|
||
filtered block is defined by the `merkleblock` message and is defined
|
||
like this:
|
||
|
||
[cols=",,,",options="header",]
|
||
|=======================================================================
|
||
|Field Size |Description |Data type |Comments
|
||
|4 |version |uint32_t |Block version information, based upon the
|
||
software version creating this block
|
||
|
||
|32 |prev_block |char[32] |The hash value of the previous block this
|
||
particular block references
|
||
|
||
|32 |merkle_root |char[32] |The reference to a Merkle tree collection
|
||
which is a hash of all transactions related to this block
|
||
|
||
|4 |timestamp |uint32_t |A timestamp recording when this block was
|
||
created (Limited to 2106!)
|
||
|
||
|4 |bits |uint32_t |The calculated difficulty target being used for this
|
||
block
|
||
|
||
|4 |nonce |uint32_t |The nonce used to generate this block… to allow
|
||
variations of the header and compute different hashes
|
||
|
||
|4 |total_transactions |uint32_t |Number of transactions in the block
|
||
(including unmatched ones)
|
||
|
||
|? |hashes |uint256[] |hashes in depth-first order (including standard
|
||
varint size prefix)
|
||
|
||
|? |flags |byte[] |flag bits, packed per 8 in a byte, least significant
|
||
bit first (including standard varint size prefix)
|
||
|=======================================================================
|
||
|
||
See below for the format of the partial merkle tree hashes and flags.
|
||
|
||
Thus, a `merkleblock` message is a block header, plus a part of a merkle
|
||
tree which can be used to extract identifying information for
|
||
transactions that matched the filter and prove that the matching
|
||
transaction data really did appear in the solved block. Clients can use
|
||
this data to be sure that the remote node is not feeding them fake
|
||
transactions that never appeared in a real block, although lying through
|
||
omission is still possible.
|
||
|
||
[[extensions-to-existing-messages]]
|
||
Extensions to existing messages
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
The `version` command is extended with a new field:
|
||
|
||
[cols=",,,",options="header",]
|
||
|=======================================================================
|
||
|Field Size |Description |Data type |Comments
|
||
|1 byte |fRelay |bool |If false then broadcast transactions will not be
|
||
announced until a filter\{load,add,clear} command is received. If
|
||
missing or true, no change in protocol behaviour occurs.
|
||
|=======================================================================
|
||
|
||
SPV clients that wish to use Bloom filtering would normally set fRelay
|
||
to false in the version message, then set a filter based on their wallet
|
||
(or a subset of it, if they are overlapping different peers). Being able
|
||
to opt-out of inv messages until the filter is set prevents a client
|
||
being flooded with traffic in the brief window of time between finishing
|
||
version handshaking and setting the filter.
|
||
|
||
The `getdata` command is extended to allow a new type in the `inv`
|
||
submessage. The type field can now be `MSG_FILTERED_BLOCK (== 3)` rather
|
||
than `MSG_BLOCK`. If no filter has been set on the connection, a request
|
||
for filtered blocks is ignored. If a filter has been set, a
|
||
`merkleblock` message is returned for the requested block hash. In
|
||
addition, because a `merkleblock` message contains only a list of
|
||
transaction hashes, transactions matching the filter should also be sent
|
||
in separate tx messages after the merkleblock is sent. This avoids a
|
||
slow roundtrip that would otherwise be required (receive hashes, didn't
|
||
see some of these transactions yet, ask for them). Note that because
|
||
there is currently no way to request transactions which are already in a
|
||
block from a node (aside from requesting the full block), the set of
|
||
matching transactions that the requesting node hasn't either received or
|
||
announced with an inv must be sent and any additional transactions which
|
||
match the filter may also be sent. This allows for clients (such as the
|
||
reference client) to limit the number of invs it must remember a given
|
||
node to have announced while still providing nodes with, at a minimum,
|
||
all the transactions it needs.
|
||
|
||
[[filter-matching-algorithm]]
|
||
Filter matching algorithm
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
The filter can be tested against arbitrary pieces of data, to see if
|
||
that data was inserted by the client. Therefore the question arises of
|
||
what pieces of data should be inserted/tested.
|
||
|
||
To determine if a transaction matches the filter, the following
|
||
algorithm is used. Once a match is found the algorithm aborts.
|
||
|
||
1. Test the hash of the transaction itself.
|
||
2. For each output, test each data element of the output script. This
|
||
means each hash and key in the output script is tested independently.
|
||
*Important:* if an output matches whilst testing a transaction, the node
|
||
might need to update the filter by inserting the serialized COutPoint
|
||
structure. See below for more details.
|
||
3. For each input, test the serialized COutPoint structure.
|
||
4. For each input, test each data element of the input script (note:
|
||
input scripts only ever contain data elements).
|
||
5. Otherwise there is no match.
|
||
|
||
In this way addresses, keys and script hashes (for P2SH outputs) can all
|
||
be added to the filter. You can also match against classes of
|
||
transactions that are marked with well known data elements in either
|
||
inputs or outputs, for example, to implement various forms of
|
||
link:Smart property[Smart property].
|
||
|
||
The test for outpoints is there to ensure you can find transactions
|
||
spending outputs in your wallet, even though you don't know anything
|
||
about their form. As you can see, once set on a connection the filter is
|
||
*not static* and can change throughout the connections lifetime. This is
|
||
done to avoid the following race condition:
|
||
|
||
1. A client sets a filter matching a key in their wallet. They then
|
||
start downloading the block chain. The part of the chain that the client
|
||
is missing is requested using getblocks.
|
||
2. The first block is read from disk by the serving peer. It contains
|
||
TX 1 which sends money to the clients key. It matches the filter and is
|
||
thus sent to the client.
|
||
3. The second block is read from disk by the serving peer. It contains
|
||
TX 2 which spends TX 1. However TX 2 does not contain any of the clients
|
||
keys and is thus not sent. The client does not know the money they
|
||
received was already spent.
|
||
|
||
By updating the bloom filter atomically in step 2 with the discovered
|
||
outpoint, the filter will match against TX 2 in step 3 and the client
|
||
will learn about all relevant transactions, despite that there is no
|
||
pause between the node processing the first and second blocks.
|
||
|
||
The nFlags field of the filter controls the nodes precise update
|
||
behaviour and is a bit field.
|
||
|
||
* `BLOOM_UPDATE_NONE (0)` means the filter is not adjusted when a match
|
||
is found.
|
||
* `BLOOM_UPDATE_ALL (1)` means if the filter matches any data element in
|
||
a scriptPubKey the outpoint is serialized and inserted into the filter.
|
||
* `BLOOM_UPDATE_P2PUBKEY_ONLY (2)` means the outpoint is inserted into
|
||
the filter only if a data element in the scriptPubKey is matched, and
|
||
that script is of the standard "pay to pubkey" or "pay to multisig"
|
||
forms.
|
||
|
||
These distinctions are useful to avoid too-rapid degradation of the
|
||
filter due to an increasing false positive rate. We can observe that a
|
||
wallet which expects to receive only payments of the standard
|
||
pay-to-address form doesn't need automatic filter updates because any
|
||
transaction that spends one of its own outputs has a predictable data
|
||
element in the input (the pubkey that hashes to the address). If a
|
||
wallet might receive pay-to-address outputs and also pay-to-pubkey or
|
||
pay-to-multisig outputs then BLOOM_UPDATE_P2PUBKEY_ONLY is appropriate,
|
||
as it avoids unnecessary expansions of the filter for the most common
|
||
types of output but still ensures correct behaviour with payments that
|
||
explicitly specify keys.
|
||
|
||
Obviously, nFlags == 1 or nFlags == 2 mean that the filter will get
|
||
dirtier as more of the chain is scanned. Clients should monitor the
|
||
observed false positive rate and periodically refresh the filter with a
|
||
clean one.
|
||
|
||
[[partial-merkle-branch-format]]
|
||
Partial Merkle branch format
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
A _Merkle tree_ is a way of arranging a set of items as leaf nodes of
|
||
tree in which the interior nodes are hashes of the concatenations of
|
||
their child hashes. The root node is called the _Merkle root_. Every
|
||
Bitcoin block contains a Merkle root of the tree formed from the blocks
|
||
transactions. By providing some elements of the trees interior nodes
|
||
(called a _Merkle branch_) a proof is formed that the given transaction
|
||
was indeed in the block when it was being mined, but the size of the
|
||
proof is much smaller than the size of the original block.
|
||
|
||
[[constructing-a-partial-merkle-tree-object]]
|
||
Constructing a partial merkle tree object
|
||
+++++++++++++++++++++++++++++++++++++++++
|
||
|
||
* Traverse the merkle tree from the root down, and for each encountered
|
||
node:
|
||
** Check whether this node corresponds to a leaf node (transaction) that
|
||
is to be included OR any parent thereof:
|
||
*** If so, append a '1' bit to the flag bits
|
||
*** Otherwise, append a '0' bit.
|
||
** Check whether this node is a internal node (non-leaf) AND is the
|
||
parent of an included leaf node:
|
||
*** If so:
|
||
**** Descend into its left child node, and process the subtree beneath
|
||
it entirely (depth-first).
|
||
**** If this node has a right child node too, descend into it as well.
|
||
*** Otherwise: append this node's hash to the hash list.
|
||
|
||
[[parsing-a-partial-merkle-tree-object]]
|
||
Parsing a partial merkle tree object
|
||
++++++++++++++++++++++++++++++++++++
|
||
|
||
As the partial block message contains the number of transactions in the
|
||
entire block, the shape of the merkle tree is known before hand. Again,
|
||
traverse this tree, computing traversed node's hashes along the way:
|
||
|
||
* Read a bit from the flag bit list:
|
||
** If it is '0':
|
||
*** Read a hash from the hashes list, and return it as this node's hash.
|
||
** If it is '1' and this is a leaf node:
|
||
*** Read a hash from the hashes list, store it as a matched txid, and
|
||
return it as this node's hash.
|
||
** If it is '1' and this is an internal node:
|
||
*** Descend into its left child tree, and store its computed hash as L.
|
||
*** If this node has a right child as well:
|
||
**** Descend into its right child, and store its computed hash as R.
|
||
**** If L == R, the partial merkle tree object is invalid.
|
||
**** Return Hash(L || R).
|
||
*** If this node has no right child, return Hash(L || L).
|
||
|
||
The partial merkle tree object is only valid if:
|
||
|
||
* All hashes in the hash list were consumed and no more.
|
||
* All bits in the flag bits list were consumed (except padding to make
|
||
it into a full byte), and no more.
|
||
* The hash computed for the root node matches the block header's merkle
|
||
root.
|
||
* The block header is valid, and matches its claimed proof of work.
|
||
* In two-child nodes, the hash of the left and right branches was never
|
||
equal.
|
||
|
||
[[bloom-filter-format]]
|
||
Bloom filter format
|
||
^^^^^^^^^^^^^^^^^^^
|
||
|
||
A Bloom filter is a bit-field in which bits are set based on feeding the
|
||
data element to a set of different hash functions. The number of hash
|
||
functions used is a parameter of the filter. In Bitcoin we use version 3
|
||
of the 32-bit Murmur hash function. To get N "different" hash functions
|
||
we simply initialize the Murmur algorithm with the following formula:
|
||
|
||
`nHashNum * 0xFBA4C795 + nTweak`
|
||
|
||
i.e. if the filter is initialized with 4 hash functions and a tweak of
|
||
0x00000005, when the second function (index 1) is needed h1 would be
|
||
equal to 4221880218.
|
||
|
||
When loading a filter with the `filterload` command, there are two
|
||
parameters that can be chosen. One is the size of the filter in bytes.
|
||
The other is the number of hash functions to use. To select the
|
||
parameters you can use the following formulas:
|
||
|
||
Let N be the number of elements you wish to insert into the set and P be
|
||
the probability of a false positive, where 1.0 is "match everything" and
|
||
zero is unachievable.
|
||
|
||
The size S of the filter in bytes is given by
|
||
`(-1 / pow(log(2), 2) * N * log(P)) / 8`. Of course you must ensure it
|
||
does not go over the maximum size (36,000: selected as it represents a
|
||
filter of 20,000 items with false positive rate of < 0.1% or 10,000
|
||
items and a false positive rate of < 0.0001%).
|
||
|
||
The number of hash functions required is given by `S * 8 / N * log(2)`.
|
||
|
||
[[copyright]]
|
||
Copyright
|
||
~~~~~~~~~
|
||
|
||
This document is placed in the public domain.
|
||
----------------------------------------------------------------------------------------------------------------------------------
|
||
BIP: 38
|
||
Title: Passphrase-protected private key
|
||
Authors: Mike Caldwell
|
||
Aaron Voisine <voisine@gmail.com>
|
||
Status: Draft (Some confusion applies: The announcements for this never made it to the list, so it hasn't had public discussion)
|
||
Type: Standards Track
|
||
Created: 2012-11-20
|
||
----------------------------------------------------------------------------------------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
A method is proposed for encrypting and encoding a passphrase-protected
|
||
Bitcoin private key record in the form of a 58-character
|
||
Base58Check-encoded printable string. Encrypted private key records are
|
||
intended for use on paper wallets and physical Bitcoins. Each record
|
||
string contains all the information needed to reconstitute the private
|
||
key except for a passphrase, and the methodology uses salting and
|
||
_scrypt_ to resist brute-force attacks.
|
||
|
||
The method provides two encoding methodologies - one permitting any
|
||
known private key to be encrypted with any passphrase, and another
|
||
permitting a shared private key generation scheme where the party
|
||
generating the final key string and its associated Bitcoin address (such
|
||
as a physical bitcoin manufacturer) knows only a string derived from the
|
||
original passphrase, and where the original passphrase is needed in
|
||
order to actually redeem funds sent to the associated Bitcoin address.
|
||
|
||
A 32-bit hash of the resulting Bitcoin address is encoded in plaintext
|
||
within each encrypted key, so it can be correlated to a Bitcoin address
|
||
with reasonable probability by someone not knowing the passphrase. The
|
||
complete Bitcoin address can be derived through successful decryption of
|
||
the key record.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
The motivation to make this proposal stems from observations of the way
|
||
physical bitcoins and paper wallets are used.
|
||
|
||
An issuer of physical bitcoins must be trustworthy and trusted. Even if
|
||
trustworthy, users are rightful to be skeptical about a third party with
|
||
theoretical access to take their funds. A physical bitcoin that cannot
|
||
be compromised by its issuer is always more intrinsically valuable than
|
||
one that can.
|
||
|
||
A two-factor physical bitcoin solution is highly useful to individuals
|
||
and organizations wishing to securely own bitcoins without any risk of
|
||
electronic theft and without the responsibility of climbing the
|
||
technological learning curve necessary to produce such an environment
|
||
themselves. Two-factor physical bitcoins allow a secure storage solution
|
||
to be put in a box and sold on the open market, greatly enlarging the
|
||
number of people who are able to securely store bitcoins.
|
||
|
||
Existing methodologies for creating two-factor physical bitcoins are
|
||
limited and cumbersome. At the time of this proposal, a user could
|
||
create their own private key, submit the public key to the physical
|
||
bitcoin issuer, and then receive a physical bitcoin that must be kept
|
||
together with some sort of record of the user-generated private key, and
|
||
finally, must be redeemed through a tool. The fact that the physical
|
||
bitcoin must be kept together with a user-produced private key negates
|
||
much of the benefit of the physical bitcoin - the user may as well just
|
||
print and maintain a private key.
|
||
|
||
A standardized password-protected private key format makes acquiring and
|
||
redeeming two-factor physical bitcoins simpler for the user. Instead of
|
||
maintaining a private key that cannot be memorized, the user may choose
|
||
a passphrase of their choice. The passphrase may be much shorter than
|
||
the length of a typical private key, short enough that they could use a
|
||
label or engraver to permanently commit their passphrase to their
|
||
physical Bitcoin piece once they have received it. By adopting a
|
||
standard way to encrypt a private key, we maximize the possibility that
|
||
they'll be able to redeem their funds in the venue of their choice,
|
||
rather than relying on an executable redemption tool they may not wish
|
||
to download.
|
||
|
||
Password and passphrase-protected private keys enable new practical use
|
||
cases for sending bitcoins from person to person. Someone wanting to
|
||
send bitcoins through postal mail could send a password-protected paper
|
||
wallet and give the recipient the passphrase over the phone or e-mail,
|
||
making the transfer safe from interception of either channel. A user of
|
||
paper wallets or Bitcoin banknote-style vouchers ("cash") could carry
|
||
funded encrypted private keys while leaving a copy at home as an element
|
||
of protection against accidental loss or theft. A user of paper wallets
|
||
who leaves bitcoins in a bank vault or safety deposit box could keep the
|
||
password at home or share it with trusted associates as protection
|
||
against someone at the bank gaining access to the paper wallets and
|
||
spending from them. The foreseeable and unforeseeable use cases for
|
||
password-protected private keys are numerous.
|
||
|
||
[[copyright]]
|
||
Copyright
|
||
~~~~~~~~~
|
||
|
||
This proposal is hereby placed in the public domain.
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
::
|
||
_*User story:* As a Bitcoin user who uses paper wallets, I would like
|
||
the ability to add encryption, so that my Bitcoin paper storage can be
|
||
two factor: something I have plus something I know._
|
||
+
|
||
_*User story:* As a Bitcoin user who would like to pay a person or a
|
||
company with a private key, I do not want to worry that any part of
|
||
the communication path may result in the interception of the key and
|
||
theft of my funds. I would prefer to offer an encrypted private key,
|
||
and then follow it up with the password using a different
|
||
communication channel (e.g. a phone call or SMS)._
|
||
+
|
||
_*User story:* (EC-multiplied keys) As a user of physical bitcoins, I
|
||
would like a third party to be able to create password-protected
|
||
Bitcoin private keys for me, without them knowing the password, so I
|
||
can benefit from the physical bitcoin without the issuer having access
|
||
to the private key. I would like to be able to choose a password whose
|
||
minimum length and required format does not preclude me from
|
||
memorizing it or engraving it on my physical bitcoin, without exposing
|
||
me to an undue risk of password cracking and/or theft by the
|
||
manufacturer of the item._
|
||
+
|
||
'*'User story:* (EC multiplied keys) As a user of paper wallets, I
|
||
would like the ability to generate a large number of Bitcoin addresses
|
||
protected by the same password, while enjoying a high degree of
|
||
security (highly expensive scrypt parameters), but without having to
|
||
incur the scrypt delay for each address I generate.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
This proposal makes use of the following functions and definitions:
|
||
|
||
* *AES256Encrypt, AES256Decrypt*: the simple form of the well-known AES
|
||
block cipher without consideration for initialization vectors or block
|
||
chaining. Each of these functions takes a 256-bit key and 16 bytes of
|
||
input, and deterministically yields 16 bytes of output.
|
||
* *SHA256*, a well-known hashing algorithm that takes an arbitrary
|
||
number of bytes as input and deterministically yields a 32-byte hash.
|
||
* *scrypt*: A well-known key derivation algorithm. It takes the
|
||
following parameters: (string) password, (string) salt, (int) n, (int)
|
||
r, (int) p, (int) length, and deterministically yields an array of bytes
|
||
whose length is equal to the length parameter.
|
||
* *ECMultiply*: Multiplication of an elliptic curve point by a scalar
|
||
integer with respect to the secp256k1 elliptic curve.
|
||
* *G, N*: Constants defined as part of the secp256k1 elliptic curve. G
|
||
is an elliptic curve point, and N is a large positive integer.
|
||
* *Base58Check*: a method for encoding arrays of bytes using 58
|
||
alphanumeric characters commonly used in the Bitcoin ecosystem.
|
||
|
||
[[prefix]]
|
||
Prefix
|
||
^^^^^^
|
||
|
||
It is proposed that the resulting Base58Check-encoded string start with
|
||
a '6'. The number '6' is intended to represent, from the perspective of
|
||
the user, "a private key that needs something else to be usable" - an
|
||
umbrella definition that could be understood in the future to include
|
||
keys participating in multisig transactions, and was chosen with
|
||
deference to the existing prefix '5' most commonly observed in
|
||
link:Wallet Import Format[Wallet Import Format] which denotes an
|
||
unencrypted private key.
|
||
|
||
It is proposed that the second character ought to give a hint as to what
|
||
is needed as a second factor, and for an encrypted key requiring a
|
||
passphrase, the uppercase letter P is proposed.
|
||
|
||
To keep the size of the encrypted key down, no initialization vectors
|
||
(IVs) are used in the AES encryption. Rather, suitable values for
|
||
IV-like use are derived using scrypt from the passphrase and from using
|
||
a 32-bit hash of the resulting Bitcoin address as salt.
|
||
|
||
[[proposed-specification]]
|
||
Proposed specification
|
||
^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* Object identifier prefix: 0x0142 (non-EC-multiplied) or 0x0143
|
||
(EC-multiplied). These are constant bytes that appear at the beginning
|
||
of the Base58Check-encoded record, and their presence causes the
|
||
resulting string to have a predictable prefix.
|
||
* How the user sees it: 58 characters always starting with '6P'
|
||
** Visual cues are present in the third character for visually
|
||
identifying the EC-multiply and compress flag.
|
||
* Count of payload bytes (beyond prefix): 37
|
||
** 1 byte (_flagbyte_):
|
||
*** the most significant two bits are set as follows to preserve the
|
||
visibility of the compression flag in the prefix, as well as to keep the
|
||
payload within the range of allowable values that keep the "6P" prefix
|
||
intact. For non-EC-multiplied keys, the bits are 11. For EC-multiplied
|
||
keys, the bits are 00.
|
||
*** the bit with value 0x20 when set indicates the key should be
|
||
converted to a bitcoin address using the compressed public key format.
|
||
*** the bits with values 0x10 and 0x08 are reserved for a future
|
||
specification that contemplates using multisig as a way to combine the
|
||
factors such that parties in possession of the separate factors can
|
||
independently sign a proposed transaction without requiring that any
|
||
party possess both factors. These bits must be 0 to comply with this
|
||
version of the specification.
|
||
*** the bit with value 0x04 indicates whether a lot and sequence number
|
||
are encoded into the first factor, and activates special behavior for
|
||
including them in the decryption process. This applies to EC-multiplied
|
||
keys only. Must be 0 for non-EC-multiplied keys.
|
||
*** remaining bits are reserved for future use and must all be 0 to
|
||
comply with this version of the specification.
|
||
** 4 bytes: SHA256(SHA256(expected_bitcoin_address))[0...3], used both
|
||
for typo checking and as salt
|
||
** 16 bytes: Contents depend on whether EC multiplication is used.
|
||
** 16 bytes: lasthalf: An AES-encrypted key material record (contents
|
||
depend on whether EC multiplication is used)
|
||
* Range in base58check encoding for non-EC-multiplied keys without
|
||
compression (prefix 6PR):
|
||
** Minimum value:
|
||
6PRHv1jg1ytiE4kT2QtrUz8gEjMQghZDWg1FuxjdYDzjUkcJeGdFj9q9Vi (based on 01
|
||
42 C0 plus thirty-six 00's)
|
||
** Maximum value:
|
||
6PRWdmoT1ZursVcr5NiD14p5bHrKVGPG7yeEoEeRb8FVaqYSHnZTLEbYsU (based on 01
|
||
42 C0 plus thirty-six FF's)
|
||
* Range in base58check encoding for non-EC-multiplied keys with
|
||
compression (prefix 6PY):
|
||
** Minimum value:
|
||
6PYJxKpVnkXUsnZAfD2B5ZsZafJYNp4ezQQeCjs39494qUUXLnXijLx6LG (based on 01
|
||
42 E0 plus thirty-six 00's)
|
||
** Maximum value:
|
||
6PYXg5tGnLYdXDRZiAqXbeYxwDoTBNthbi3d61mqBxPpwZQezJTvQHsCnk (based on 01
|
||
42 E0 plus thirty-six FF's)
|
||
* Range in base58check encoding for EC-multiplied keys without
|
||
compression (prefix 6Pf):
|
||
** Minimum value:
|
||
6PfKzduKZXAFXWMtJ19Vg9cSvbFg4va6U8p2VWzSjtHQCCLk3JSBpUvfpf (based on 01
|
||
43 00 plus thirty-six 00's)
|
||
** Maximum value:
|
||
6PfYiPy6Z7BQAwEHLxxrCEHrH9kasVQ95ST1NnuEnnYAJHGsgpNPQ9dTHc (based on 01
|
||
43 00 plus thirty-six FF's)
|
||
* Range in base58check encoding for non-EC-multiplied keys with
|
||
compression (prefix 6Pn):
|
||
** Minimum value:
|
||
6PnM2wz9LHo2BEAbvoGpGjMLGXCom35XwsDQnJ7rLiRjYvCxjpLenmoBsR (based on 01
|
||
43 20 plus thirty-six 00's)
|
||
** Maximum value:
|
||
6PnZki3vKspApf2zym6Anp2jd5hiZbuaZArPfa2ePcgVf196PLGrQNyVUh (based on 01
|
||
43 20 plus thirty-six FF's)
|
||
|
||
[[encryption-when-ec-multiply-flag-is-not-used]]
|
||
Encryption when EC multiply flag is not used
|
||
++++++++++++++++++++++++++++++++++++++++++++
|
||
|
||
Encrypting a private key without the EC multiplication offers the
|
||
advantage that any known private key can be encrypted. The party
|
||
performing the encryption must know the passphrase.
|
||
|
||
Encryption steps:
|
||
|
||
1. Compute the Bitcoin address (ASCII), and take the first four bytes
|
||
of SHA256(SHA256()) of it. Let's call this "addresshash".
|
||
2. Derive a key from the passphrase using scrypt
|
||
* Parameters: _passphrase_ is the passphrase itself encoded in UTF-8.
|
||
salt is _addresshash_ from the earlier step, n=16384, r=8, p=8,
|
||
length=64 (n, r, p are provisional and subject to consensus)
|
||
* Let's split the resulting 64 bytes in half, and call them
|
||
_derivedhalf1_ and _derivedhalf2_.
|
||
3. Do AES256Encrypt(bitcoinprivkey[0...15] xor derivedhalf1[0...15],
|
||
derivedhalf2), call the 16-byte result _encryptedhalf1_
|
||
4. Do AES256Encrypt(bitcoinprivkey[16...31] xor derivedhalf1[16...31],
|
||
derivedhalf2), call the 16-byte result _encryptedhalf2_
|
||
|
||
The encrypted private key is the Base58Check-encoded concatenation of
|
||
the following, which totals 39 bytes without Base58 checksum:
|
||
|
||
* 0x01 0x42 + _flagbyte_ + _salt_ + _encryptedhalf1_ + _encryptedhalf2_
|
||
|
||
Decryption steps:
|
||
|
||
1. Collect encrypted private key and passphrase from user.
|
||
2. Derive _derivedhalf1_ and _derivedhalf2_ by passing the passphrase
|
||
and _addresshash_ into scrypt function.
|
||
3. Decrypt _encryptedhalf1_ and _encryptedhalf2_ using AES256Decrypt,
|
||
merge them to form the encrypted private key.
|
||
4. Convert that private key into a Bitcoin address, honoring the
|
||
compression preference specified in _flagbyte_ of the encrypted key
|
||
record.
|
||
5. Hash the Bitcoin address, and verify that _addresshash_ from the
|
||
encrypted private key record matches the hash. If not, report that the
|
||
passphrase entry was incorrect.
|
||
|
||
[[encryption-when-ec-multiply-mode-is-used]]
|
||
Encryption when EC multiply mode is used
|
||
++++++++++++++++++++++++++++++++++++++++
|
||
|
||
Encrypting a private key with EC multiplication offers the ability for
|
||
someone to generate encrypted keys knowing only an EC point derived from
|
||
the original passphrase and some salt generated by the passphrase's
|
||
owner, and without knowing the passphrase itself. Only the person who
|
||
knows the original passphrase can decrypt the private key. A code known
|
||
as an _intermediate code_ conveys the information needed to generate
|
||
such a key without knowledge of the passphrase.
|
||
|
||
This methodology does not offer the ability to encrypt a known private
|
||
key - this means that the process of creating encrypted keys is also the
|
||
process of generating new addresses. On the other hand, this serves a
|
||
security benefit for someone possessing an address generated this way:
|
||
if the address can be recreated by decrypting its private key with a
|
||
passphrase, and it's a strong passphrase one can be certain only he
|
||
knows himself, then he can safely conclude that nobody could know the
|
||
private key to that address.
|
||
|
||
The person who knows the passphrase and who is the intended beneficiary
|
||
of the private keys is called the _owner_. He will generate one or more
|
||
"intermediate codes", which are the first factor of a two-factor
|
||
redemption system, and will give them to someone else we'll call
|
||
_printer_, who generates a key pair with an intermediate code can know
|
||
the address and encrypted private key, but cannot decrypt the private
|
||
key without the original passphrase.
|
||
|
||
An intermediate code should, but is not required to, embed a printable
|
||
"lot" and "sequence" number for the benefit of the user. The proposal
|
||
forces these lot and sequence numbers to be included in any valid
|
||
private keys generated from them. An owner who has requested multiple
|
||
private keys to be generated for him will be advised by applications to
|
||
ensure that each private key has a unique lot and sequence number
|
||
consistent with the intermediate codes he generated. These mainly help
|
||
protect _owner_ from potential mistakes and/or attacks that could be
|
||
made by _printer_.
|
||
|
||
The "lot" and "sequence" number are combined into a single 32 bit
|
||
number. 20 bits are used for the lot number and 12 bits are used for the
|
||
sequence number, such that the lot number can be any decimal number
|
||
between 0 and 1048575, and the sequence number can be any decimal number
|
||
between 0 and 4095. For programs that generate batches of intermediate
|
||
codes for an _owner_, it is recommended that lot numbers be chosen at
|
||
random within the range 100000-999999 and that sequence numbers are
|
||
assigned starting with 1.
|
||
|
||
Steps performed by _owner_ to generate a single intermediate code, if
|
||
lot and sequence numbers are being included:
|
||
|
||
1. Generate 4 random bytes, call them _ownersalt_.
|
||
2. Encode the lot and sequence numbers as a 4 byte quantity
|
||
(big-endian): lotnumber * 4096 + sequencenumber. Call these four bytes
|
||
_lotsequence_.
|
||
3. Concatenate _ownersalt_ + _lotsequence_ and call this
|
||
_ownerentropy_.
|
||
4. Derive a key from the passphrase using scrypt
|
||
* Parameters: _passphrase_ is the passphrase itself encoded in UTF-8.
|
||
salt is _ownersalt_. n=16384, r=8, p=8, length=32.
|
||
* Call the resulting 32 bytes _prefactor_.
|
||
* Take SHA256(SHA256(_prefactor_ + _ownerentropy_)) and call this
|
||
_passfactor_.
|
||
5. Compute the elliptic curve point G * _passfactor_, and convert the
|
||
result to compressed notation (33 bytes). Call this _passpoint_.
|
||
Compressed notation is used for this purpose regardless of whether the
|
||
intent is to create Bitcoin addresses with or without compressed public
|
||
keys.
|
||
6. Convey _ownersalt_ and _passpoint_ to the party generating the keys,
|
||
along with a checksum to ensure integrity.
|
||
* The following Base58Check-encoded format is recommended for this
|
||
purpose: magic bytes "2C E9 B3 E1 FF 39 E2 51" followed by
|
||
_ownerentropy_, and then _passpoint_. The resulting string will start
|
||
with the word "passphrase" due to the constant bytes, will be 72
|
||
characters in length, and encodes 49 bytes (8 bytes constant + 8 bytes
|
||
_ownerentropy_ + 33 bytes _passpoint_). The checksum is handled in the
|
||
Base58Check encoding. The resulting string is called
|
||
_intermediate_passphrase_string_.
|
||
|
||
If lot and sequence numbers are not being included, then follow the same
|
||
procedure with the following changes:
|
||
|
||
* _ownersalt_ is 8 random bytes instead of 4, and _lotsequence_ is
|
||
omitted. _ownerentropy_ becomes an alias for _ownersalt_.
|
||
* The SHA256 conversion of _prefactor_ to _passfactor_ is omitted.
|
||
Instead, the output of scrypt is used directly as _passfactor_.
|
||
* The magic bytes are "2C E9 B3 E1 FF 39 E2 53" instead (the last byte
|
||
is 0x53 instead of 0x51).
|
||
|
||
Steps to create new encrypted private keys given
|
||
_intermediate_passphrase_string_ from _owner_ (so we have
|
||
_ownerentropy_, and _passpoint_, but we do not have _passfactor_ or the
|
||
passphrase):
|
||
|
||
1. Set _flagbyte_.
|
||
* Turn on bit 0x20 if the Bitcoin address will be formed by hashing the
|
||
compressed public key (optional, saves space, but many Bitcoin
|
||
implementations aren't compatible with it)
|
||
* Turn on bit 0x04 if _ownerentropy_ contains a value for _lotsequence_.
|
||
(While it has no effect on the keypair generation process, the
|
||
decryption process needs this flag to know how to process
|
||
_ownerentropy_)
|
||
2. Generate 24 random bytes, call this _seedb_. Take
|
||
SHA256(SHA256(_seedb_)) to yield 32 bytes, call this _factorb_.
|
||
3. ECMultiply _passpoint_ by _factorb_. Use the resulting EC point as a
|
||
public key and hash it into a Bitcoin address using either compressed or
|
||
uncompressed public key methodology (specify which methodology is used
|
||
inside _flagbyte_). This is the generated Bitcoin address, call it
|
||
_generatedaddress_.
|
||
4. Take the first four bytes of SHA256(SHA256(_generatedaddress_)) and
|
||
call it _addresshash_.
|
||
5. Now we will encrypt _seedb_. Derive a second key from _passpoint_
|
||
using scrypt
|
||
* Parameters: _passphrase_ is _passpoint_ provided from the first party
|
||
(expressed in binary as 33 bytes). _salt_ is _addresshash_ +
|
||
_ownerentropy_, n=1024, r=1, p=1, length=64. The "+" operator is
|
||
concatenation.
|
||
* Split the result into two 32-byte halves and call them _derivedhalf1_
|
||
and _derivedhalf2_.
|
||
6. Do AES256Encrypt(seedb[0...15] xor derivedhalf1[0...15],
|
||
derivedhalf2), call the 16-byte result _encryptedpart1_
|
||
7. Do AES256Encrypt((encryptedpart1[8...15] + seedb[16...23]) xor
|
||
derivedhalf1[16...31], derivedhalf2), call the 16-byte result
|
||
_encryptedpart2_. The "+" operator is concatenation.
|
||
|
||
The encrypted private key is the Base58Check-encoded concatenation of
|
||
the following, which totals 39 bytes without Base58 checksum:
|
||
|
||
* 0x01 0x43 + _flagbyte_ + _addresshash_ + _ownerentropy_ +
|
||
_encryptedpart1_[0...7] + _encryptedpart2_
|
||
|
||
[[confirmation-code]]
|
||
Confirmation code
|
||
|
||
The party generating the Bitcoin address has the option to return a
|
||
_confirmation code_ back to _owner_ which allows _owner_ to
|
||
independently verify that he has been given a Bitcoin address that
|
||
actually depends on his passphrase, and to confirm the lot and sequence
|
||
numbers (if applicable). This protects _owner_ from being given a
|
||
Bitcoin address by the second party that is unrelated to the key
|
||
derivation and possibly spendable by the second party. If a Bitcoin
|
||
address given to _owner_ can be successfully regenerated through the
|
||
confirmation process, _owner_ can be reasonably assured that any
|
||
spending without the passphrase is infeasible. This confirmation code is
|
||
75 characters starting with "cfrm38".
|
||
|
||
To generate it, we need _flagbyte_, _ownerentropy_, _factorb_,
|
||
_derivedhalf1_ and _derivedhalf2_ from the original encryption
|
||
operation.
|
||
|
||
1. ECMultiply _factorb_ by G, call the result _pointb_. The result is
|
||
33 bytes.
|
||
2. The first byte is 0x02 or 0x03. XOR it by (derivedhalf2[31] & 0x01),
|
||
call the resulting byte _pointbprefix_.
|
||
3. Do AES256Encrypt(pointb[1...16] xor derivedhalf1[0...15],
|
||
derivedhalf2) and call the result _pointbx1_.
|
||
4. Do AES256Encrypt(pointb[17...32] xor derivedhalf1[16...31],
|
||
derivedhalf2) and call the result _pointbx2_.
|
||
5. Concatenate _pointbprefix_ + _pointbx1_ + _pointbx2_ (total 33
|
||
bytes) and call the result _encryptedpointb_.
|
||
|
||
The result is a Base58Check-encoded concatenation of the following:
|
||
|
||
* 0x64 0x3B 0xF6 0xA8 0x9A + _flagbyte_ + _addresshash_ + _ownerentropy_
|
||
+ _encryptedpointb_
|
||
|
||
A confirmation tool, given a passphrase and a confirmation code, can
|
||
recalculate the address, verify the address hash, and then assert the
|
||
following: "It is confirmed that Bitcoin address _address_ depends on
|
||
this passphrase". If applicable: "The lot number is _lotnumber_ and the
|
||
sequence number is _sequencenumber_."
|
||
|
||
To recalculate the address:
|
||
|
||
1. Derive _passfactor_ using scrypt with _ownerentropy_ and the user's
|
||
passphrase and use it to recompute _passpoint_
|
||
2. Derive decryption key for _pointb_ using scrypt with _passpoint_,
|
||
_addresshash_, and _ownerentropy_
|
||
3. Decrypt _encryptedpointb_ to yield _pointb_
|
||
4. ECMultiply _pointb_ by _passfactor_. Use the resulting EC point as a
|
||
public key and hash it into _address_ using either compressed or
|
||
uncompressed public key methodology as specifid in _flagbyte_.
|
||
|
||
[[decryption]]
|
||
Decryption
|
||
|
||
1. Collect encrypted private key and passphrase from user.
|
||
2. Derive _passfactor_ using scrypt with _ownerentropy_ and the user's
|
||
passphrase and use it to recompute _passpoint_
|
||
3. Derive decryption key for _seedb_ using scrypt with _passpoint_,
|
||
_addresshash_, and _ownersalt_
|
||
4. Decrypt _encryptedpart2_ using AES256Decrypt to yield the last 8
|
||
bytes of _seedb_ and the last 8 bytes of _encryptedpart1_.
|
||
5. Decrypt _encryptedpart1_ to yield the remainder of _seedb_.
|
||
6. Use _seedb_ to compute _factorb_.
|
||
7. Multiply _passfactor_ by _factorb_ mod N to yield the private key
|
||
associated with _generatedaddress_.
|
||
8. Convert that private key into a Bitcoin address, honoring the
|
||
compression preference specified in the encrypted key.
|
||
9. Hash the Bitcoin address, and verify that _addresshash_ from the
|
||
encrypted private key record matches the hash. If not, report that the
|
||
passphrase entry was incorrect.
|
||
|
||
[[backwards-compatibility]]
|
||
Backwards compatibility
|
||
~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Backwards compatibility is minimally applicable since this is a new
|
||
standard that at most extends link:Wallet Import Format[Wallet Import
|
||
Format]. It is assumed that an entry point for private key data may also
|
||
accept existing formats of private keys (such as hexadecimal and
|
||
link:Wallet Import Format[Wallet Import Format]); this draft uses a key
|
||
format that cannot be mistaken for any existing one and preserves
|
||
auto-detection capabilities.
|
||
|
||
[[suggestions-for-implementers-of-proposal-with-alt-chains]]
|
||
Suggestions for implementers of proposal with alt-chains
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
If this proposal is accepted into alt-chains, it is requested that the
|
||
unused flag bytes not be used for denoting that the key belongs to an
|
||
alt-chain.
|
||
|
||
Alt-chain implementers should exploit the address hash for this purpose.
|
||
Since each operation in this proposal involves hashing a text
|
||
representation of a coin address which (for Bitcoin) includes the
|
||
leading '1', an alt-chain can easily be denoted simply by using the
|
||
alt-chain's preferred format for representing an address. Alt-chain
|
||
implementers may also change the prefix such that encrypted addresses do
|
||
not start with "6P".
|
||
|
||
[[discussion-item-scrypt-parameters]]
|
||
Discussion item: scrypt parameters
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
This proposal leaves the scrypt parameters up in the air. The following
|
||
items are proposed for consideration:
|
||
|
||
The main goal of scrypt is to reduce the feasibility of brute force
|
||
attacks. It must be assumed that an attacker will be able to use an
|
||
efficient implementation of scrypt. The parameters should force a highly
|
||
efficient implementation of scrypt to wait a decent amount of time to
|
||
slow attacks.
|
||
|
||
On the other hand, an unavoidably likely place where scrypt will be
|
||
implemented is using slow interpreted languages such as javascript. What
|
||
might take milliseconds on an efficient scrypt implementation may take
|
||
seconds in javascript.
|
||
|
||
It is believed, however, that someone using a javascript implementation
|
||
is probably dealing with codes by hand, one at a time, rather than
|
||
generating or processing large batches of codes. Thus, a wait time of
|
||
several seconds is acceptable to a user.
|
||
|
||
A private key redemption process that forces a server to consume several
|
||
seconds of CPU time would discourage implementation by the server owner,
|
||
because they would be opening up a denial of service avenue by inviting
|
||
users to make numerous attempts to invoke the redemption process.
|
||
However, it's also feasible for the server owner to implement his
|
||
redemption process in such a way that the decryption is done by the
|
||
user's browser, offloading the task from his own server (and providing
|
||
another reason why the chosen scrypt parameters should be tolerant of
|
||
javascript-based decryptors).
|
||
|
||
The preliminary values of 16384, 8, and 8 are hoped to offer the
|
||
following properties:
|
||
|
||
* Encryption/decryption in javascript requiring several seconds per
|
||
operation
|
||
* Use of the parallelization parameter provides a modest opportunity for
|
||
speedups in environments where concurrent threading is available - such
|
||
environments would be selected for processes that must handle bulk
|
||
quantities of encryption/decryption operations. Estimated time for an
|
||
operation is in the tens or hundreds of milliseconds.
|
||
|
||
[[reference-implementation]]
|
||
Reference implementation
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Added to alpha version of Casascius Bitcoin Address Utility for Windows
|
||
available at:
|
||
|
||
* via https: https://casascius.com/btcaddress-alpha.zip
|
||
* at github: https://github.com/casascius/Bitcoin-Address-Utility
|
||
|
||
Click "Tools" then "PPEC Keygen" (provisional name)
|
||
|
||
[[test-vectors]]
|
||
Test vectors
|
||
~~~~~~~~~~~~
|
||
|
||
[[no-compression-no-ec-multiply]]
|
||
No compression, no EC multiply
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Test 1:
|
||
|
||
* Passphrase: TestingOneTwoThree
|
||
* Encrypted: 6PRVWUbkzzsbcVac2qwfssoUJAN1Xhrg6bNk8J7Nzm5H7kxEbn2Nh2ZoGg
|
||
* Unencrypted (WIF): 5KN7MzqK5wt2TP1fQCYyHBtDrXdJuXbUzm4A9rKAteGu3Qi5CVR
|
||
* Unencrypted (hex):
|
||
CBF4B9F70470856BB4F40F80B87EDB90865997FFEE6DF315AB166D713AF433A5
|
||
|
||
Test 2:
|
||
|
||
* Passphrase: Satoshi
|
||
* Encrypted: 6PRNFFkZc2NZ6dJqFfhRoFNMR9Lnyj7dYGrzdgXXVMXcxoKTePPX1dWByq
|
||
* Unencrypted (WIF): 5HtasZ6ofTHP6HCwTqTkLDuLQisYPah7aUnSKfC7h4hMUVw2gi5
|
||
* Unencrypted (hex):
|
||
09C2686880095B1A4C249EE3AC4EEA8A014F11E6F986D0B5025AC1F39AFBD9AE
|
||
|
||
[[compression-no-ec-multiply]]
|
||
Compression, no EC multiply
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Test 1:
|
||
|
||
* Passphrase: TestingOneTwoThree
|
||
* Encrypted: 6PYNKZ1EAgYgmQfmNVamxyXVWHzK5s6DGhwP4J5o44cvXdoY7sRzhtpUeo
|
||
* Unencrypted (WIF):
|
||
L44B5gGEpqEDRS9vVPz7QT35jcBG2r3CZwSwQ4fCewXAhAhqGVpP
|
||
* Unencrypted (hex):
|
||
CBF4B9F70470856BB4F40F80B87EDB90865997FFEE6DF315AB166D713AF433A5
|
||
|
||
Test 2:
|
||
|
||
* Passphrase: Satoshi
|
||
* Encrypted: 6PYLtMnXvfG3oJde97zRyLYFZCYizPU5T3LwgdYJz1fRhh16bU7u6PPmY7
|
||
* Unencrypted (WIF):
|
||
KwYgW8gcxj1JWJXhPSu4Fqwzfhp5Yfi42mdYmMa4XqK7NJxXUSK7
|
||
* Unencrypted (hex):
|
||
09C2686880095B1A4C249EE3AC4EEA8A014F11E6F986D0B5025AC1F39AFBD9AE
|
||
|
||
[[ec-multiply-no-compression-no-lotsequence-numbers]]
|
||
EC multiply, no compression, no lot/sequence numbers
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Test 1:
|
||
|
||
* Passphrase: TestingOneTwoThree
|
||
* Passphrase code:
|
||
passphrasepxFy57B9v8HtUsszJYKReoNDV6VHjUSGt8EVJmux9n1J3Ltf1gRxyDGXqnf9qm
|
||
* Encrypted key:
|
||
6PfQu77ygVyJLZjfvMLyhLMQbYnu5uguoJJ4kMCLqWwPEdfpwANVS76gTX
|
||
* Bitcoin address: 1PE6TQi6HTVNz5DLwB1LcpMBALubfuN2z2
|
||
* Unencrypted private key (WIF):
|
||
5K4caxezwjGCGfnoPTZ8tMcJBLB7Jvyjv4xxeacadhq8nLisLR2
|
||
* Unencrypted private key (hex):
|
||
A43A940577F4E97F5C4D39EB14FF083A98187C64EA7C99EF7CE460833959A519
|
||
|
||
Test 2:
|
||
|
||
* Passphrase: Satoshi
|
||
* Passphrase code:
|
||
passphraseoRDGAXTWzbp72eVbtUDdn1rwpgPUGjNZEc6CGBo8i5EC1FPW8wcnLdq4ThKzAS
|
||
* Encrypted key:
|
||
6PfLGnQs6VZnrNpmVKfjotbnQuaJK4KZoPFrAjx1JMJUa1Ft8gnf5WxfKd
|
||
* Bitcoin address: 1CqzrtZC6mXSAhoxtFwVjz8LtwLJjDYU3V
|
||
* Unencrypted private key (WIF):
|
||
5KJ51SgxWaAYR13zd9ReMhJpwrcX47xTJh2D3fGPG9CM8vkv5sH
|
||
* Unencrypted private key (hex):
|
||
C2C8036DF268F498099350718C4A3EF3984D2BE84618C2650F5171DCC5EB660A
|
||
|
||
[[ec-multiply-no-compression-lotsequence-numbers]]
|
||
EC multiply, no compression, lot/sequence numbers
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Test 1:
|
||
|
||
* Passphrase: MOLON LABE
|
||
* Passphrase code:
|
||
passphraseaB8feaLQDENqCgr4gKZpmf4VoaT6qdjJNJiv7fsKvjqavcJxvuR1hy25aTu5sX
|
||
* Encrypted key:
|
||
6PgNBNNzDkKdhkT6uJntUXwwzQV8Rr2tZcbkDcuC9DZRsS6AtHts4Ypo1j
|
||
* Bitcoin address: 1Jscj8ALrYu2y9TD8NrpvDBugPedmbj4Yh
|
||
* Unencrypted private key (WIF):
|
||
5JLdxTtcTHcfYcmJsNVy1v2PMDx432JPoYcBTVVRHpPaxUrdtf8
|
||
* Unencrypted private key (hex):
|
||
44EA95AFBF138356A05EA32110DFD627232D0F2991AD221187BE356F19FA8190
|
||
* Confirmation code:
|
||
cfrm38V8aXBn7JWA1ESmFMUn6erxeBGZGAxJPY4e36S9QWkzZKtaVqLNMgnifETYw7BPwWC9aPD
|
||
* Lot/Sequence: 263183/1
|
||
|
||
Test 2:
|
||
|
||
* Passphrase (all letters are Greek - test UTF-8 compatibility with
|
||
this): ΜΟΛΩΝ ΛΑΒΕ
|
||
* Passphrase code:
|
||
passphrased3z9rQJHSyBkNBwTRPkUGNVEVrUAcfAXDyRU1V28ie6hNFbqDwbFBvsTK7yWVK
|
||
* Encrypted private key:
|
||
6PgGWtx25kUg8QWvwuJAgorN6k9FbE25rv5dMRwu5SKMnfpfVe5mar2ngH
|
||
* Bitcoin address: 1Lurmih3KruL4xDB5FmHof38yawNtP9oGf
|
||
* Unencrypted private key (WIF):
|
||
5KMKKuUmAkiNbA3DazMQiLfDq47qs8MAEThm4yL8R2PhV1ov33D
|
||
* Unencrypted private key (hex):
|
||
CA2759AA4ADB0F96C414F36ABEB8DB59342985BE9FA50FAAC228C8E7D90E3006
|
||
* Confirmation code:
|
||
cfrm38V8G4qq2ywYEFfWLD5Cc6msj9UwsG2Mj4Z6QdGJAFQpdatZLavkgRd1i4iBMdRngDqDs51
|
||
* Lot/Sequence: 806938/1
|
||
|
||
----------------------------------------------------------
|
||
BIP: BIP-0039
|
||
Title: Mnemonic code for generating deterministic keys
|
||
Authors: Marek Palatinus <slush@satoshilabs.com>
|
||
Pavol Rusnak <stick@satoshilabs.com>
|
||
ThomasV <thomasv@bitcointalk.org>
|
||
Aaron Voisine <voisine@gmail.com>
|
||
Sean Bowe <ewillbefull@gmail.com>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Created: 2013-09-10
|
||
----------------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP describes the implementation of a mnemonic code or mnemonic
|
||
sentence -- a group of easy to remember words -- for the generation of
|
||
deterministic wallets.
|
||
|
||
It consists of two parts: generating the mnenomic, and converting it
|
||
into a binary seed. This seed can be later used to generate
|
||
deterministic wallets using BIP-0032 or similar methods.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
A mnenomic code or sentence is superior for human interaction compared
|
||
to the handling of raw binary or hexidecimal representations of a wallet
|
||
seed. The sentence could be written on paper or spoken over the
|
||
telephone.
|
||
|
||
This guide meant to be as a way to transport computer-generated
|
||
randomnes over human readable transcription. It's not a way how to
|
||
process user-created sentences (also known as brainwallet) to wallet
|
||
seed.
|
||
|
||
[[generating-the-mnemonic]]
|
||
Generating the mnemonic
|
||
~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
The mnemonic must encode entropy in any multiple of 32 bits. With larger
|
||
entropy security is improved but the sentence length increases. We can
|
||
refer to the initial entropy length as ENT. The recommended size of ENT
|
||
is 128-256 bits.
|
||
|
||
First, an initial entropy of ENT bits is generated. A checksum is
|
||
generated by taking the first
|
||
|
||
--------
|
||
ENT / 32
|
||
--------
|
||
|
||
bits of its SHA256 hash. This checksum is appended to the end of the
|
||
initial entropy. Next, these concatenated bits are are split into groups
|
||
of 11 bits, each encoding a number from 0-2047, serving as an index to a
|
||
wordlist. Later, we will convert these numbers into words and use the
|
||
joined words as a mnemonic sentence.
|
||
|
||
The following table describes the relation between the initial entropy
|
||
length (ENT), the checksum length (CS) and length of the generated
|
||
mnemonic sentence (MS) in words.
|
||
|
||
------------------------------
|
||
CS = ENT / 32
|
||
MS = (ENT + CS) / 11
|
||
|
||
| ENT | CS | ENT+CS | MS |
|
||
+-------+----+--------+------+
|
||
| 128 | 4 | 132 | 12 |
|
||
| 160 | 5 | 165 | 15 |
|
||
| 192 | 6 | 198 | 18 |
|
||
| 224 | 7 | 231 | 21 |
|
||
| 256 | 8 | 264 | 24 |
|
||
------------------------------
|
||
|
||
[[wordlist]]
|
||
Wordlist
|
||
~~~~~~~~
|
||
|
||
An ideal wordlist has the following characteristics:
|
||
|
||
\a) smart selection of words
|
||
|
||
` - wordlist is created in such way that it's enough to type the first four` +
|
||
` letters to unambiguously identify the word`
|
||
|
||
\b) similar words avoided
|
||
|
||
` - word pairs like "build" and "built", "woman" and "women", or "quick" and "quickly"` +
|
||
` not only make remembering the sentence difficult, but are also more error` +
|
||
` prone and more difficult to guess`
|
||
|
||
\c) sorted wordlists
|
||
|
||
` - wordlist is sorted which allows for more efficient lookup of the code words` +
|
||
` (i.e. implementation can use binary search instead of linear search)` +
|
||
` - this also allows trie (prefix tree) to be used, e.g. for better compression`
|
||
|
||
The wordlist can contain native characters, but they have to be encoded
|
||
in UTF-8 using Normalization Form Compatibility Decomposition (NFKD).
|
||
|
||
[[from-mnemonic-to-seed]]
|
||
From mnemonic to seed
|
||
~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
A user may decide to protect their mnemonic by passphrase. If a
|
||
passphrase is not present, an empty string "" is used instead.
|
||
|
||
To create a binary seed from the mnemonic, we use PBKDF2 function with a
|
||
mnemonic sentence (in UTF-8 NFKD) used as a password and string
|
||
"mnemonic" + passphrase (again in UTF-8 NFKD) used as a salt. Iteration
|
||
count is set to 2048 and HMAC-SHA512 is used as a pseudo-random
|
||
function. Desired length of the derived key is 512 bits (= 64 bytes).
|
||
|
||
This seed can be later used to generate deterministic wallets using
|
||
BIP-0032 or similar methods.
|
||
|
||
The conversion of the mnemonic sentence to binary seed is completely
|
||
independent from generating the sentence. This results in rather simple
|
||
code; there are no constraints on sentence structure and clients are
|
||
free to implement their own wordlists or even whole sentence generators,
|
||
allowing for flexibility in wordlists for typo detection or other
|
||
purposes.
|
||
|
||
Although using mnemonic not generated by algorithm described in
|
||
"Generating the mnemonic" section is possible, this is not advised and
|
||
software must compute checksum of the mnemonic sentence using wordlist
|
||
and issue a warning if it is invalid.
|
||
|
||
Described method also provides plausible deniability, because every
|
||
passphrase generates a valid seed (and thus deterministic wallet) but
|
||
only the correct one will make the desired wallet available.
|
||
|
||
[[wordlists]]
|
||
Wordlists
|
||
~~~~~~~~~
|
||
|
||
* link:bip-0039/english.txt[English]
|
||
|
||
[[test-vectors]]
|
||
Test vectors
|
||
~~~~~~~~~~~~
|
||
|
||
See https://github.com/trezor/python-mnemonic/blob/master/vectors.json
|
||
|
||
[[reference-implementation]]
|
||
Reference Implementation
|
||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Reference implementation including wordlists is available from
|
||
|
||
http://github.com/trezor/python-mnemonic
|
||
|
||
[[other-implementations]]
|
||
Other Implementations
|
||
~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Objective-C - https://github.com/nybex/NYMnemonic
|
||
------------------------------------------------------------
|
||
BIP: BIP-0044
|
||
Title: Multi-Account Hierarchy for Deterministic Wallets
|
||
Authors: Marek Palatinus <slush@satoshilabs.com>
|
||
Pavol Rusnak <stick@satoshilabs.com>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Created: 2014-04-24
|
||
------------------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP defines a logical hierarchy for deterministic wallets based on
|
||
an algorithm described in BIP-0032 (BIP32 from now on) and purpose
|
||
scheme described in BIP-0043 (BIP43 from now on).
|
||
|
||
This BIP is a particular application of BIP43.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
The hierarchy proposed in this paper is quite comprehensive. It allows
|
||
the handling of multiple coins, multiple accounts, external and internal
|
||
chains per account and millions of addresses per chain.
|
||
|
||
[[path-levels]]
|
||
Path levels
|
||
~~~~~~~~~~~
|
||
|
||
We define the following 5 levels in BIP32 path:
|
||
|
||
-------------------------------------------------------------
|
||
m / purpose' / coin_type' / account' / change / address_index
|
||
-------------------------------------------------------------
|
||
|
||
Apostrophe in the path indicates that BIP32 hardened derivation is used.
|
||
|
||
Each level has a special meaning, described in the chapters below.
|
||
|
||
[[purpose]]
|
||
Purpose
|
||
^^^^^^^
|
||
|
||
Purpose is a constant set to 44' (or 0x8000002C) following the BIP43
|
||
recommendation. It indicates that the subtree of this node is used
|
||
according to this specification.
|
||
|
||
Hardened derivation is used at this level.
|
||
|
||
[[coin-type]]
|
||
Coin type
|
||
^^^^^^^^^
|
||
|
||
One master node (seed) can be used for unlimited number of independent
|
||
cryptocoins such as Bitcoin, Litecoin or Namecoin. However, sharing the
|
||
same space for various cryptocoins has some disadvantages.
|
||
|
||
This level creates a separate subtree for every cryptocoin, avoiding
|
||
reusing addresses across cryptocoins and improving privacy issues.
|
||
|
||
Coin type is a constant, set for each cryptocoin. Cryptocoin developers
|
||
may ask for registering unused number for their project.
|
||
|
||
The list of already allocated coin types is in the chapter "Registered
|
||
coin types" below.
|
||
|
||
Hardened derivation is used at this level.
|
||
|
||
[[account]]
|
||
Account
|
||
^^^^^^^
|
||
|
||
This level splits the key space into independent user identities, so the
|
||
wallet never mixes the coins across different accounts.
|
||
|
||
Users can use these accounts to organize the funds in the same fashion
|
||
as bank accounts; for donation purposes (where all addresses are
|
||
considered public), for saving purposes, for common expenses etc.
|
||
|
||
Accounts are numbered from index 0 in sequentially increasing manner.
|
||
This number is used as child index in BIP32 derivation.
|
||
|
||
Hardened derivation is used at this level.
|
||
|
||
Software should prevent a creation of an account if a previous account
|
||
does not have a transaction history (meaning none of its addresses have
|
||
been used before).
|
||
|
||
Software needs to discover all used accounts after importing the seed
|
||
from an external source. Such an algorithm is described in "Account
|
||
discovery" chapter.
|
||
|
||
[[change]]
|
||
Change
|
||
^^^^^^
|
||
|
||
Constant 0 is used for external chain and constant 1 for internal chain
|
||
(also known as change addresses). External chain is used for addresses
|
||
that are meant to be visible outside of the wallet (e.g. for receiving
|
||
payments). Internal chain is used for addresses which are not meant to
|
||
be visible outside of the wallet and is used for return transaction
|
||
change.
|
||
|
||
Public derivation is used at this level.
|
||
|
||
[[index]]
|
||
Index
|
||
^^^^^
|
||
|
||
Addresses are numbered from index 0 in sequentially increasing manner.
|
||
This number is used as child index in BIP32 derivation.
|
||
|
||
Public derivation is used at this level.
|
||
|
||
[[account-discovery]]
|
||
Account discovery
|
||
~~~~~~~~~~~~~~~~~
|
||
|
||
When the master seed is imported from an external source the software
|
||
should start to discover the accounts in the following manner:
|
||
|
||
1. derive the first account's node (index = 0)
|
||
2. derive the external chain node of this account
|
||
3. scan addresses of the external chain; respect the gap limit
|
||
described below
|
||
4. if no transactions are found on the external chain, stop discovery
|
||
5. if there are some transactions, increase the account index and go to
|
||
step 1
|
||
|
||
This algorithm is successful because software should disallow creation
|
||
of new accounts if previous one has no transaction history, as described
|
||
in chapter "Account" above.
|
||
|
||
Please note that the algorithm works with the transaction history, not
|
||
account balances, so you can have an account with 0 total coins and the
|
||
algorithm will still continue with discovery.
|
||
|
||
[[address-gap-limit]]
|
||
Address gap limit
|
||
^^^^^^^^^^^^^^^^^
|
||
|
||
Address gap limit is currently set to 20. If the software hits 20 unused
|
||
addresses in a row, it expects there are no used addresses beyond this
|
||
point and stops searching the address chain.
|
||
|
||
Wallet software should warn when the user is trying to exceed the gap
|
||
limit on an external chain by generating a new address.
|
||
|
||
[[registered-coin-types]]
|
||
Registered coin types
|
||
~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
These are the registered coin types for usage in level 2 of BIP44
|
||
described in chapter "Coin type" above.
|
||
|
||
All these constants are used as hardened derivation.
|
||
|
||
[cols=",,",options="header",]
|
||
|==============================
|
||
|index |hexa |coin
|
||
|0 |0x80000000 |Bitcoin
|
||
|1 |0x80000001 |Bitcoin Testnet
|
||
|==============================
|
||
|
||
[[examples]]
|
||
Examples
|
||
~~~~~~~~
|
||
|
||
[cols=",,,,",options="header",]
|
||
|====================================================================
|
||
|coin |account |chain |address |path
|
||
|Bitcoin |first |external |first |m / 44' / 0' / 0' / 0 / 0
|
||
|Bitcoin |first |external |second |m / 44' / 0' / 0' / 0 / 1
|
||
|Bitcoin |first |change |first |m / 44' / 0' / 0' / 1 / 0
|
||
|Bitcoin |first |change |second |m / 44' / 0' / 0' / 1 / 1
|
||
|Bitcoin |second |external |first |m / 44' / 0' / 1' / 0 / 0
|
||
|Bitcoin |second |external |second |m / 44' / 0' / 1' / 0 / 1
|
||
|Bitcoin |second |change |first |m / 44' / 0' / 1' / 1 / 0
|
||
|Bitcoin |second |change |second |m / 44' / 0' / 1' / 1 / 1
|
||
|Bitcoin Testnet |first |external |first |m / 44' / 1' / 0' / 0 / 0
|
||
|Bitcoin Testnet |first |external |second |m / 44' / 1' / 0' / 0 / 1
|
||
|Bitcoin Testnet |first |change |first |m / 44' / 1' / 0' / 1 / 0
|
||
|Bitcoin Testnet |first |change |second |m / 44' / 1' / 0' / 1 / 1
|
||
|Bitcoin Testnet |second |external |first |m / 44' / 1' / 1' / 0 / 0
|
||
|Bitcoin Testnet |second |external |second |m / 44' / 1' / 1' / 0 / 1
|
||
|Bitcoin Testnet |second |change |first |m / 44' / 1' / 1' / 1 / 0
|
||
|Bitcoin Testnet |second |change |second |m / 44' / 1' / 1' / 1 / 1
|
||
|====================================================================
|
||
|
||
[[compatible-wallets]]
|
||
Compatible wallets
|
||
~~~~~~~~~~~~~~~~~~
|
||
|
||
* https://mytrezor.com[myTREZOR web wallet]
|
||
(https://github.com/trezor/webwallet[source])
|
||
|
||
[[reference]]
|
||
Reference
|
||
~~~~~~~~~
|
||
|
||
* link:bip-0032.mediawiki[BIP32 - Hierarchical Deterministic Wallets]
|
||
* link:bip-0043.mediawiki[BIP43 - Purpose Field for Deterministic
|
||
Wallets]
|
||
|
||
--------------------------------------------------
|
||
BIP: 70
|
||
Title: Payment Protocol
|
||
Author: Gavin Andresen <gavinandresen@gmail.com>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Created: 2013-07-29
|
||
--------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP describes a protocol for communication between a merchant and
|
||
their customer, enabling both a better customer experience and better
|
||
security against man-in-the-middle attacks on the payment process.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
The current, minimal Bitcoin payment protocol operates as follows:
|
||
|
||
1. Customer adds items to an online shopping basket, and decides to pay
|
||
using Bitcoin.
|
||
2. Merchant generates a unique payment address, associates it with the
|
||
customer's order, and asks the customer to pay.
|
||
3. Customer copies the Bitcoin address from the merchant's web page and
|
||
pastes it into whatever wallet they are using OR follows a bitcoin: link
|
||
and their wallet is launched with the amount to be paid.
|
||
4. Customer authorizes payment to the merchant's address and broadcasts
|
||
the transaction through the Bitcoin p2p network.
|
||
5. Merchant's server detects payment and after sufficient transaction
|
||
confirmations considers the transaction final.
|
||
|
||
This BIP extends the above protocol to support several new features:
|
||
|
||
1. Human-readable, secure payment destinations-- customers will be
|
||
asked to authorize payment to "example.com" instead of an inscrutable,
|
||
34-character bitcoin address.
|
||
2. Secure proof of payment, which the customer can use in case of a
|
||
dispute with the merchant.
|
||
3. Resistance from man-in-the-middle attacks that replace a merchant's
|
||
bitcoin address with an attacker's address before a transaction is
|
||
authorized with a hardware wallet.
|
||
4. Payment received messages, so the customer knows immediately that
|
||
the merchant has received, and has processed (or is processing) their
|
||
payment.
|
||
5. Refund addresses, automatically given to the merchant by the
|
||
customer's wallet software, so merchants do not have to contact
|
||
customers before refunding overpayments or orders that cannot be
|
||
fulfilled for some reason.
|
||
|
||
[[protocol]]
|
||
Protocol
|
||
~~~~~~~~
|
||
|
||
This BIP describes payment protocol messages encoded using Google's
|
||
Protocol Buffers, authenticated using X.509 certificates, and
|
||
communicated over http/https. Future BIPs might extend this payment
|
||
protocol to other encodings, PKI systems, or transport protocols.
|
||
|
||
The payment protocol consists of three messages; PaymentRequest,
|
||
Payment, and PaymentACK, and begins with the customer somehow indicating
|
||
that they are ready to pay and the merchant's server responding with a
|
||
PaymentRequest message:
|
||
|
||
[[messages]]
|
||
Messages
|
||
~~~~~~~~
|
||
|
||
The Protocol Buffers messages are defined in
|
||
link:bip-0070/paymentrequest.proto[paymentrequest.proto].
|
||
|
||
[[output]]
|
||
Output
|
||
^^^^^^
|
||
|
||
Outputs are used in PaymentRequest messages to specify where a payment
|
||
(or part of a payment) should be sent. They are also used in Payment
|
||
messages to specify where a refund should be sent.
|
||
|
||
---------------------------------------------
|
||
message Output {
|
||
optional uint64 amount = 1 [default = 0];
|
||
optional bytes script = 2;
|
||
}
|
||
---------------------------------------------
|
||
|
||
[cols=",",]
|
||
|=======================================================================
|
||
|amount |Number of satoshis (0.00000001 BTC) to be paid
|
||
|
||
|script |a "TxOut" script where payment should be sent. This will
|
||
normally be one of the standard Bitcoin transaction scripts (e.g. pubkey
|
||
OP_CHECKSIG). This is optional to enable future extensions to this
|
||
protocol that derive Outputs from a master public key and the
|
||
PaymentRequest data itself.
|
||
|=======================================================================
|
||
|
||
[[paymentdetailspaymentrequest]]
|
||
PaymentDetails/PaymentRequest
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Payment requests are split into two messages to support future
|
||
extensibility. The bulk of the information is contained in the
|
||
PaymentDetails message. It is wrapped inside a PaymentRequest message,
|
||
which contains meta-information about the merchant and a digital
|
||
signature.
|
||
|
||
-------------------------------------------------------
|
||
message PaymentDetails {
|
||
optional string network = 1 [default = "main"];
|
||
repeated Output outputs = 2;
|
||
required uint64 time = 3;
|
||
optional uint64 expires = 4;
|
||
optional string memo = 5;
|
||
optional string payment_url = 6;
|
||
optional bytes merchant_data = 7;
|
||
}
|
||
-------------------------------------------------------
|
||
|
||
[cols=",",]
|
||
|=======================================================================
|
||
|network |either "main" for payments on the production Bitcoin network,
|
||
or "test" for payments on test network. If a client receives a
|
||
PaymentRequest for a network it does not support it must reject the
|
||
request.
|
||
|
||
|outputs |one or more outputs where Bitcoins are to be sent. If the sum
|
||
of outputs.amount is zero, the customer will be asked how much to pay,
|
||
and the bitcoin client may choose any or all of the Outputs (if there
|
||
are more than one) for payment. If the sum of outputs.amount is
|
||
non-zero, then the customer will be asked to pay the sum, and the
|
||
payment shall be split among the Outputs with non-zero amounts (if there
|
||
are more than one; Outputs with zero amounts shall be ignored).
|
||
|
||
|time |Unix timestamp (seconds since 1-Jan-1970 UTC) when the
|
||
PaymentRequest was created.
|
||
|
||
|expires |Unix timestamp (UTC) after which the PaymentRequest should be
|
||
considered invalid.
|
||
|
||
|memo |UTF-8 encoded, plain-text (no formatting) note that should be
|
||
displayed to the customer, explaining what this PaymentRequest is for.
|
||
|
||
|payment_url |Secure (usually https) location where a Payment message
|
||
(see below) may be sent to obtain a PaymentACK.
|
||
|
||
|merchant_data |Arbitrary data that may be used by the merchant to
|
||
identify the PaymentRequest. May be omitted if the merchant does not
|
||
need to associate Payments with PaymentRequest or if they associate each
|
||
PaymentRequest with a separate payment address.
|
||
|=======================================================================
|
||
|
||
The payment_url specified in the PaymentDetails should remain valid at
|
||
least until the PaymentDetails expires (or as long as possible if the
|
||
PaymentDetails does not expire). Note that this is irrespective of any
|
||
state change in the underlying payment request; for example cancellation
|
||
of an order should not invalidate the payment_url, as it is important
|
||
that the merchant's server can record mis-payments in order to refund
|
||
the payment.
|
||
|
||
A PaymentRequest is PaymentDetails optionally tied to a merchant's
|
||
identity:
|
||
|
||
------------------------------------------------------------------
|
||
message PaymentRequest {
|
||
optional uint32 payment_details_version = 1 [default = 1];
|
||
optional string pki_type = 2 [default = "none"];
|
||
optional bytes pki_data = 3;
|
||
required bytes serialized_payment_details = 4;
|
||
optional bytes signature = 5;
|
||
}
|
||
------------------------------------------------------------------
|
||
|
||
[cols=",",]
|
||
|=======================================================================
|
||
|payment_details_version |See below for a discussion of
|
||
versioning/upgrading.
|
||
|
||
|pki_type |public-key infrastructure (PKI) system being used to identify
|
||
the merchant. All implementation should support "none", "x509+sha256"
|
||
and "x509+sha1".
|
||
|
||
|pki_data |PKI-system data that identifies the merchant and can be used
|
||
to create a digital signature. In the case of X.509 certificates,
|
||
pki_data contains one or more X.509 certificates (see Certificates
|
||
section below).
|
||
|
||
|serialized_payment_details |A protocol-buffer serialized PaymentDetails
|
||
message.
|
||
|
||
|signature |digital signature over a hash of the protocol buffer
|
||
serialized variation of the PaymentRequest message, with all fields
|
||
serialized in numerical order (all current protocol buffer
|
||
implementations serialize fields in numerical order) and signed using
|
||
the public key in pki_data. Before serialization, the signature field
|
||
must be set to an empty value so that the field is included in the
|
||
signed PaymentRequest hash but contains no data.
|
||
|=======================================================================
|
||
|
||
When a Bitcoin wallet application receives a PaymentRequest, it must
|
||
authorize payment by doing the following:
|
||
|
||
1. Validate the merchant's identity and signature using the PKI system,
|
||
if the pki_type is not "none".
|
||
2. Validate that customer's system unix time (UTC) is before
|
||
PaymentDetails.expires. If it is not, then the payment request must be
|
||
rejected.
|
||
3. Display the merchant's identity and ask the customer if they would
|
||
like to submit payment (e.g. display the "Common Name" in the first
|
||
X.509 certificate).
|
||
|
||
PaymentRequest messages larger than 50,000 bytes should be rejected by
|
||
the wallet application, to mitigate denial-of-service attacks.
|
||
|
||
[[payment]]
|
||
Payment
|
||
^^^^^^^
|
||
|
||
Payment messages are sent after the customer has authorized payment:
|
||
|
||
-----------------------------------------
|
||
message Payment {
|
||
optional bytes merchant_data = 1;
|
||
repeated bytes transactions = 2;
|
||
repeated Output refund_to = 3;
|
||
optional string memo = 4;
|
||
}
|
||
-----------------------------------------
|
||
|
||
[cols=",",]
|
||
|=======================================================================
|
||
|merchant_data |copied from PaymentDetails.merchant_data. Merchants may
|
||
use invoice numbers or any other data they require to match Payments to
|
||
PaymentRequests. Note that malicious clients may modify the
|
||
merchant_data, so should be authenticated in some way (for example,
|
||
signed with a merchant-only key).
|
||
|
||
|transactions |One or more valid, signed Bitcoin transactions that fully
|
||
pay the PaymentRequest
|
||
|
||
|refund_to |One or more outputs where the merchant may return funds, if
|
||
necessary. The merchant may return funds using these outputs for up to 2
|
||
months after the time of the payment request. After that time has
|
||
expired, parties must negotiate if returning of funds becomes necessary.
|
||
|
||
|memo |UTF-8 encoded, plain-text note from the customer to the merchant.
|
||
|=======================================================================
|
||
|
||
If the customer authorizes payment, then the Bitcoin client:
|
||
|
||
1. Creates and signs one or more transactions that satisfy (pay in
|
||
full) PaymentDetails.outputs
|
||
2. Validate that customer's system unix time (UTC) is still before
|
||
PaymentDetails.expires. If it is not, the payment should be cancelled.
|
||
3. Broadcast the transactions on the Bitcoin p2p network.
|
||
4. If PaymentDetails.payment_url is specified, POST a Payment message
|
||
to that URL. The Payment message is serialized and sent as the body of
|
||
the POST request.
|
||
|
||
Errors communicating with the payment_url server should be communicated
|
||
to the user. In the scenario where the merchant's server receives
|
||
multiple identical Payment messages for an individual PaymentRequest, it
|
||
must acknowledge each. The second and further PaymentACK messages sent
|
||
from the merchant's server may vary by memo field to indicate current
|
||
state of the Payment (for example number of confirmations seen on the
|
||
network). This is required in order to ensure that in case of a
|
||
transport level failure during transmission, recovery is possible by the
|
||
Bitcoin client re-sending the Payment message.
|
||
|
||
PaymentDetails.payment_url should be secure against man-in-the-middle
|
||
attacks that might alter Payment.refund_to (if using HTTP, it must be
|
||
TLS-protected).
|
||
|
||
Wallet software sending Payment messages via HTTP must set appropriate
|
||
Content-Type and Accept headers, as specified in BIP 71:
|
||
|
||
-----------------------------------------
|
||
Content-Type: application/bitcoin-payment
|
||
Accept: application/bitcoin-paymentack
|
||
-----------------------------------------
|
||
|
||
When the merchant's server receives the Payment message, it must
|
||
determine whether or not the transactions satisfy conditions of payment.
|
||
If and only if they do, if should broadcast the transaction(s) on the
|
||
Bitcoin p2p network.
|
||
|
||
Payment messages larger than 50,000 bytes should be rejected by the
|
||
merchant's server, to mitigate denial-of-service attacks.
|
||
|
||
[[paymentack]]
|
||
PaymentACK
|
||
^^^^^^^^^^
|
||
|
||
PaymentACK is the final message in the payment protocol; it is sent from
|
||
the merchant's server to the bitcoin wallet in response to a Payment
|
||
message:
|
||
|
||
-------------------------------------
|
||
message PaymentACK {
|
||
required Payment payment = 1;
|
||
optional string memo = 2;
|
||
}
|
||
-------------------------------------
|
||
|
||
[cols=",",]
|
||
|=======================================================================
|
||
|payment |Copy of the Payment message that triggered this PaymentACK.
|
||
Clients may ignore this if they implement another way of associating
|
||
Payments with PaymentACKs.
|
||
|
||
|memo |UTF-8 encoded note that should be displayed to the customer
|
||
giving the status of the transaction (e.g. "Payment of 1 BTC for eleven
|
||
tribbles accepted for processing.")
|
||
|=======================================================================
|
||
|
||
PaymentACK messages larger than 60,000 bytes should be rejected by the
|
||
wallet application, to mitigate denial-of-service attacks. This is
|
||
larger than the limits on Payment and PaymentRequest messages as
|
||
PaymentACK contains a full Payment message within it.
|
||
|
||
[[localization]]
|
||
Localization
|
||
~~~~~~~~~~~~
|
||
|
||
Merchants that support multiple languages should generate
|
||
language-specific PaymentRequests, and either associate the language
|
||
with the request or embed a language tag in the request's merchant_data.
|
||
They should also generate a language-specific PaymentACK based on the
|
||
original request.
|
||
|
||
For example: A greek-speaking customer browsing the Greek version of a
|
||
merchant's website clicks on a "Αγορά τώρα" link, which generates a
|
||
PaymentRequest with merchant_data set to "lang=el&basketId=11252". The
|
||
customer pays, their bitcoin client sends a Payment message, and the
|
||
merchant's website responds with PaymentACK.message "σας ευχαριστούμε".
|
||
|
||
[[certificates]]
|
||
Certificates
|
||
~~~~~~~~~~~~
|
||
|
||
The default PKI system is X.509 certificates (the same system used to
|
||
authenticate web servers). The format of pki_data when pki_type is
|
||
"x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate
|
||
chain:
|
||
|
||
---------------------------------------
|
||
message X509Certificates {
|
||
repeated bytes certificate = 1;
|
||
}
|
||
---------------------------------------
|
||
|
||
If pki_type is "x509+sha256", then the PaymentRequest message is hashed
|
||
using the SHA256 algorithm to produce the message digest that is signed.
|
||
If pki_type is "x509+sha1", then the SHA1 algorithm is used.
|
||
|
||
Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The
|
||
certificate containing the public key of the entity that digitally
|
||
signed the PaymentRequest must be the first certificate. This MUST be
|
||
followed by additional certificates, with each subsequent certificate
|
||
being the one used to certify the previous one, up to (but not
|
||
including) a trusted root authority. The trusted root authority MAY be
|
||
included. The recipient must verify the certificate chain according to
|
||
[RFC5280] and reject the PaymentRequest if any validation failure
|
||
occurs.
|
||
|
||
Trusted root certificates may be obtained from the operating system; if
|
||
validation is done on a device without an operating system, the
|
||
http://www.mozilla.org/projects/security/certs/included/index.html[Mozilla
|
||
root store] is recommended.
|
||
|
||
[[extensibility]]
|
||
Extensibility
|
||
~~~~~~~~~~~~~
|
||
|
||
The protocol buffers serialization format is designed to be extensible.
|
||
In particular, new, optional fields can be added to a message and will
|
||
be ignored (but saved/re-transmitted) by old implementations.
|
||
|
||
PaymentDetails messages may be extended with new optional fields and
|
||
still be considered "version 1." Old implementations will be able to
|
||
validate signatures against PaymentRequests containing the new fields,
|
||
but (obviously) will not be able to display whatever information is
|
||
contained in the new, optional fields to the user.
|
||
|
||
If it becomes necessary at some point in the future for merchants to
|
||
produce PaymentRequest messages that are accepted *only* by new
|
||
implementations, they can do so by defining a new PaymentDetails message
|
||
with version=2. Old implementations should let the user know that they
|
||
need to upgrade their software when they get an up-version
|
||
PaymentDetails message.
|
||
|
||
Implementations that need to extend messages in this specification shall
|
||
use tags starting at 1000, and shall update the
|
||
link:bip-0070/extensions.mediawiki[extensions page] via pull-req to
|
||
avoid conflicts with other extensions.
|
||
|
||
[[references]]
|
||
References
|
||
~~~~~~~~~~
|
||
|
||
link:bip-0071.mediawiki[BIP 0071] : Payment Protocol mime types
|
||
|
||
link:bip-0072.mediawiki[BIP 0072] : Payment Protocol bitcoin: URI
|
||
extensions
|
||
|
||
Public-Key Infrastructure (X.509) working group :
|
||
http://datatracker.ietf.org/wg/pkix/charter/
|
||
|
||
Protocol Buffers : https://developers.google.com/protocol-buffers/
|
||
|
||
[[see-also]]
|
||
See Also
|
||
~~~~~~~~
|
||
|
||
Javascript Object Signing and Encryption working group :
|
||
http://datatracker.ietf.org/wg/jose/
|
||
|
||
Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice
|
||
especially the list of Electronic Invoice standards
|
||
|
||
sipa's payment protocol proposal: https://gist.github.com/1237788
|
||
|
||
ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html
|
||
|
||
Homomorphic Payment Addresses and the Pay-to-Contract Protocol :
|
||
http://arxiv.org/abs/1212.3257
|
||
--------------------------------------------------
|
||
BIP: 71
|
||
Title: Payment Protocol MIME types
|
||
Author: Gavin Andresen <gavinandresen@gmail.com>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Created: 2013-07-29
|
||
--------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP defines a MIME (RFC 2046) Media Type for Bitcoin payment
|
||
request messages.
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
Wallet or server software that sends payment protocol messages over
|
||
email or http should follow Internet standards for properly
|
||
encapsulating the messages.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
The Media Type (Content-Type in HTML/email headers) for bitcoin protocol
|
||
messages shall be:
|
||
|
||
[cols=",",]
|
||
|==================================================
|
||
|Message |Type/Subtype
|
||
|PaymentRequest |application/bitcoin-paymentrequest
|
||
|Payment |application/bitcoin-payment
|
||
|PaymentACK |application/bitcoin-paymentack
|
||
|==================================================
|
||
|
||
Payment protocol messages are encoded in binary.
|
||
|
||
[[example]]
|
||
Example
|
||
~~~~~~~
|
||
|
||
A web server generating a PaymentRequest message to initiate the payment
|
||
protocol would precede the binary message data with the following
|
||
headers:
|
||
|
||
------------------------------------------------
|
||
Content-Type: application/bitcoin-paymentrequest
|
||
Content-Transfer-Encoding: binary
|
||
------------------------------------------------
|
||
-----------------------------------------------------
|
||
BIP: 72
|
||
Title: bitcoin: uri extensions for Payment Protocol
|
||
Author: Gavin Andresen <gavinandresen@gmail.com>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Created: 2013-07-29
|
||
-----------------------------------------------------
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP describes an extension to the bitcoin: URI scheme (BIP 21) to
|
||
support the payment protocol (BIP 70).
|
||
|
||
[[motivation]]
|
||
Motivation
|
||
~~~~~~~~~~
|
||
|
||
Allow users to click on a link in a web page or email to initiate the
|
||
payment protocol, while being backwards-compatible with existing bitcoin
|
||
wallets.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
The bitcoin: URI scheme is extended with an additional, optional "r"
|
||
parameter, whose value is a URL from which a PaymentRequest message
|
||
should be fetched (characters not allowed within the scope of a query
|
||
parameter must be percent-encoded as described in RFC 3986 and
|
||
bip-0021).
|
||
|
||
If the "r" parameter is provided and backwards compatibility is not
|
||
required, then the bitcoin address portion of the URI may be omitted
|
||
(the URI will be of the form: bitcoin:?r=... ).
|
||
|
||
When Bitcoin wallet software that supports this BIP receives a bitcoin:
|
||
URI with a request parameter, it should ignore the bitcoin
|
||
address/amount/label/message in the URI and instead fetch a
|
||
PaymentRequest message and then follow the payment protocol, as
|
||
described in BIP 70.
|
||
|
||
Bitcoin wallets must support fetching PaymentRequests via http and https
|
||
protocols; they may support other protocols. Wallets must include an
|
||
"Accept" HTTP header in HTTP(s) requests (as defined in RFC 2616):
|
||
|
||
------------------------------------------
|
||
Accept: application/bitcoin-paymentrequest
|
||
------------------------------------------
|
||
|
||
If a PaymentRequest cannot be obtained (perhaps the server is
|
||
unavailable), then the customer should be informed that the merchant's
|
||
payment processing system is unavailable. In the case of an HTTP
|
||
request, status codes which are neither success nor error (such as
|
||
redirect) should be handled as outlined in RFC 2616.
|
||
|
||
[[compatibility]]
|
||
Compatibility
|
||
~~~~~~~~~~~~~
|
||
|
||
Wallet software that does not support this BIP will simply ignore the r
|
||
parameter and will initiate a payment to bitcoin address.
|
||
|
||
[[examples]]
|
||
Examples
|
||
~~~~~~~~
|
||
|
||
A backwards-compatible request:
|
||
|
||
------------------------------------------------------------------------------------------------------
|
||
bitcoin:mq7se9wy2egettFxPbmn99cK8v5AFq55Lx?amount=0.11&r=https://merchant.com/pay.php?h%3D2a8628fc2fbe
|
||
------------------------------------------------------------------------------------------------------
|
||
|
||
Non-backwards-compatible equivalent:
|
||
|
||
--------------------------------------------------------
|
||
bitcoin:?r=https://merchant.com/pay.php?h%3D2a8628fc2fbe
|
||
--------------------------------------------------------
|
||
|
||
[[references]]
|
||
References
|
||
~~~~~~~~~~
|
||
|
||
http://www.w3.org/Protocols/rfc2616/rfc2616.html[RFC 2616] : Hypertext
|
||
Transfer Protocol -- HTTP/1.1
|