bitcoinbook/selected BIPs/bip-0014.asciidoc

------------------------------------------------------------
  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.