mirror of
https://github.com/bitcoinbook/bitcoinbook
synced 2024-12-24 23:48:32 +00:00
174 lines
7.0 KiB
Plaintext
174 lines
7.0 KiB
Plaintext
------------------------------------------------------------
|
||
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.
|