https://tests.bitcoin.it/w/api.php?action=feedcontributions&user=Justmoon&feedformat=atomBitcoin Wiki - User contributions [en]2024-03-29T05:08:53ZUser contributionsMediaWiki 1.30.0https://tests.bitcoin.it/w/index.php?title=Bitcoin_Improvement_Proposals&diff=30612Bitcoin Improvement Proposals2012-09-09T19:14:03Z<p>Justmoon: Added BIP 0036 link.</p>
<hr />
<div>People wishing to submit BIPs, first should propose their idea or document to the mailing list. After discussion they should email Amir Taaki <genjix@riseup.net>. After copy-editing and acceptance, it will be published here.<br />
<br />
We are fairly liberal with approving BIPs, and try not to be too involved in decision making on behalf of the community. The exception is in very rare cases of dispute resolution when a decision is contentious and cannot be agreed upon. In those cases, the conservative option will always be preferred.<br />
<br />
Having a BIP here does not make it a formally accepted standard until its status becomes Active. For a BIP to become Active requires the mutual consent of the community.<br />
<br />
Those proposing changes should consider that ultimately consent may rest with the [[economic majority]].<br />
<br />
{| class="wikitable sortable" style="width: auto; text-align: center; font-size: smaller; table-layout: fixed;"<br />
!Number<br />
!Title<br />
!Owner<br />
!Status<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0001|1]]<br />
| BIP Purpose and Guidelines<br />
| Amir Taaki<br />
| Active<br />
|-<br />
| [[BIP 0010|10]]<br />
| Multi-Sig Transaction Distribution<br />
| Alan Reiner<br />
| Draft<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0011|11]]<br />
| M-of-N Standard Transactions<br />
| Gavin Andresen<br />
| Accepted<br />
|- style="background-color: #ffcfcf"<br />
| [[BIP 0012|12]]<br />
| OP_EVAL<br />
| Gavin Andresen<br />
| Withdrawn<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0013|13]]<br />
| Address Format for pay-to-script-hash<br />
| Gavin Andresen<br />
| Accepted<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0014|14]]<br />
| Protocol Version and User Agent<br />
| Amir Taaki, Patrick Strateman<br />
| Accepted<br />
|- style="background-color: #ffcfcf"<br />
| [[BIP 0015|15]]<br />
| Aliases<br />
| Amir Taaki<br />
| Withdrawn<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0016|16]]<br />
| Pay To Script Hash<br />
| Gavin Andresen<br />
| Accepted<br />
|- style="background-color: #ffcfcf"<br />
| [[BIP 0017|17]]<br />
| OP_CHECKHASHVERIFY (CHV)<br />
| Luke Dashjr<br />
| Withdrawn<br />
|-<br />
| [[BIP 0018|18]]<br />
| hashScriptCheck<br />
| Luke Dashjr<br />
| Draft<br />
|-<br />
| [[BIP 0019|19]]<br />
| M-of-N Standard Transactions (Low SigOp)<br />
| Luke Dashjr<br />
| Draft<br />
|- style="background-color: #ffcfcf"<br />
| [[BIP 0020|20]]<br />
| URI Scheme<br />
| Luke Dashjr<br />
| Replaced<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0021|21]]<br />
| URI Scheme<br />
| Nils Schneider, Matt Corallo<br />
| Accepted<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0022|22]]<br />
| getblocktemplate - Fundamentals<br />
| Luke Dashjr<br />
| Draft<br />
|-<br />
| [[BIP 0023|23]]<br />
| getblocktemplate - Pooled Mining<br />
| Luke Dashjr<br />
| Draft<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0030|30]]<br />
| Duplicate transactions<br />
| Pieter Wuille<br />
| Accepted<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0031|31]]<br />
| Pong message<br />
| Mike Hearn<br />
| Accepted<br />
|-<br />
| [[BIP 0032|32]]<br />
| Hierarchical Deterministic Wallets<br />
| Pieter Wuille<br />
| Draft<br />
|-<br />
| [[BIP 0033|33]]<br />
| Stratized Nodes<br />
| Amir Taaki<br />
| Draft<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0034|34]]<br />
| Block v2, Height in coinbase<br />
| Gavin Andresen<br />
| Accepted<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0035|35]]<br />
| mempool message<br />
| Jeff Garzik<br />
| Accepted<br />
|- style="background-color: #cfffcf"<br />
| [[BIP 0036|36]]<br />
| Custom Services<br />
| Stefan Thomas<br />
| Draft<br />
|}<br />
<br />
[[Hardfork Wishlist]]<br />
<br />
[[Category:BIP|Z]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29860User:Justmoon/BIP Draft: Custom Services2012-08-19T06:10:43Z<p>Justmoon: Set up redirect to final BIP location.</p>
<hr />
<div>#REDIRECT [[BIP 0036]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Service_Discovery&diff=29859User:Justmoon/BIP Draft: Custom Service Discovery2012-08-19T06:07:55Z<p>Justmoon: Update reference with actual BIP number.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Informational<br />
Created: 10-08-2012<br />
</pre><br />
<br />
== Abstract ==<br />
<br />
This BIP augments [[BIP 0036|BIP 36]] to provide a recommendation how nodes using a specific custom services might handle discovery of peers supporting the same service. This BIP introduces no changes to the Bitcoin protocol and is purely informational.<br />
<br />
== Motivation ==<br />
<br />
Each service can theoretically implement it's own protocol for node discovery. However, since efficient protocols for this tend to be complex, it would be nice to have a standard way which can be implemented once and used by multiple different services.<br />
<br />
== Specification ==<br />
<br />
Bitcoin includes the <code>services</code> field for each node in the <code>addr</code> message. This is very useful for discovering other nodes that support a specific service. For example a lightweight client may be interested in finding all the nodes capable of serving it.<br />
<br />
However, some services may not need this functionality whereas other services may need to communicate extra information per node. So rather than modifying the <code>addr</code> message, we instead send a service-specific message ahead of it. This message SHOULD use the addr subcommand, so for the <code>MySampleSvc</code> service it would be called <code>MySampleSvc:addr</code>. We'll refer to it here generically as the <code>*:addr</code> message.<br />
<br />
The <code>*:addr</code> of a service specifies which nodes in the next following <code>addr</code> list support that service. It uses the following format:<br />
<br />
* If <code>*:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>*:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>*:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>*:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
== Rationale ==<br />
<br />
The protocol above attempts to allow service discovery in a way that best fulfills the following criteria:<br />
<br />
* Minimize additional network traffic from custom service discovery<br />
* Ensure that custom services using this scheme can be migrated to become standard services<br />
<br />
To ensure that services using this scheme can become standardized, we provide exactly one bit per node and no additional information. This corresponds to the services field in the standard Bitcoin protocol, which also uses one bit per node and service.<br />
<br />
By allowing several different encodings, we allow the sending client to pick the most efficient one for any given scenario while ensuring that the receiving node will be able to understand it.<br />
<br />
== Copyright ==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=BIP_0036&diff=29858BIP 00362012-08-19T06:07:25Z<p>Justmoon: Move page to official URL.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: 36<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions <code>service[]</code> are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. This command SHOULD consist of the exact service identifier to avoid collisions with other services, prefixed by an underscore to avoid collisions with current or future Bitcoin protocol messages. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use a peer discovery mechanism which specifies one bit per node, same as the <code>services</code> field in <code>addr</code> messages<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.<br />
<br />
[[Category:Developer]]<br />
[[Category:Technical]]<br />
[[Category:BIP|D]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29732User:Justmoon/BIP Draft: Custom Services2012-08-13T07:25:37Z<p>Justmoon: Removed redundant terminology.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions <code>service[]</code> are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. This command SHOULD consist of the exact service identifier to avoid collisions with other services, prefixed by an underscore to avoid collisions with current or future Bitcoin protocol messages. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use a peer discovery mechanism which specifies one bit per node, same as the <code>services</code> field in <code>addr</code> messages<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29731User:Justmoon/BIP Draft: Custom Services2012-08-13T07:21:57Z<p>Justmoon: Added reference to the exact field being specified.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions <code>service[]</code> are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. This command SHOULD consist of the exact service identifier to avoid collisions with other services, prefixed by an underscore to avoid collisions with current or future Bitcoin protocol messages. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use a peer discovery mechanism which specifies one bit per node, same as the <code>services</code> field in <code>addr</code> messages<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29730User:Justmoon/BIP Draft: Custom Services2012-08-13T07:21:01Z<p>Justmoon: Small wording fix.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. This command SHOULD consist of the exact service identifier to avoid collisions with other services, prefixed by an underscore to avoid collisions with current or future Bitcoin protocol messages. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use a peer discovery mechanism which specifies one bit per node, same as the <code>services</code> field in <code>addr</code> messages<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Service_Discovery&diff=29658User:Justmoon/BIP Draft: Custom Service Discovery2012-08-10T19:41:18Z<p>Justmoon: Added standard BIP structure.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Informational<br />
Created: 10-08-2012<br />
</pre><br />
<br />
== Abstract ==<br />
<br />
This BIP augments BIP XX to provide a recommendation how nodes using a specific custom services might handle discovery of peers supporting the same service. This BIP introduces no changes to the Bitcoin protocol and is purely informational.<br />
<br />
== Motivation ==<br />
<br />
Each service can theoretically implement it's own protocol for node discovery. However, since efficient protocols for this tend to be complex, it would be nice to have a standard way which can be implemented once and used by multiple different services.<br />
<br />
== Specification ==<br />
<br />
Bitcoin includes the <code>services</code> field for each node in the <code>addr</code> message. This is very useful for discovering other nodes that support a specific service. For example a lightweight client may be interested in finding all the nodes capable of serving it.<br />
<br />
However, some services may not need this functionality whereas other services may need to communicate extra information per node. So rather than modifying the <code>addr</code> message, we instead send a service-specific message ahead of it. This message SHOULD use the addr subcommand, so for the <code>MySampleSvc</code> service it would be called <code>MySampleSvc:addr</code>. We'll refer to it here generically as the <code>*:addr</code> message.<br />
<br />
The <code>*:addr</code> of a service specifies which nodes in the next following <code>addr</code> list support that service. It uses the following format:<br />
<br />
* If <code>*:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>*:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>*:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>*:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
== Rationale ==<br />
<br />
The protocol above attempts to allow service discovery in a way that best fulfills the following criteria:<br />
<br />
* Minimize additional network traffic from custom service discovery<br />
* Ensure that custom services using this scheme can be migrated to become standard services<br />
<br />
To ensure that services using this scheme can become standardized, we provide exactly one bit per node and no additional information. This corresponds to the services field in the standard Bitcoin protocol, which also uses one bit per node and service.<br />
<br />
By allowing several different encodings, we allow the sending client to pick the most efficient one for any given scenario while ensuring that the receiving node will be able to understand it.<br />
<br />
== Copyright ==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29657User:Justmoon/BIP Draft: Custom Services2012-08-10T19:36:59Z<p>Justmoon: Disambiguation.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. This command SHOULD consist of the exact service identifier to avoid collisions with other services, prefixed by an underscore to avoid collisions with current or future Bitcoin protocol messages. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use a peer discovery mechanism which specifies one bit per node, same as the <code>services</code> field in <code>addr</code> messages<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29656User:Justmoon/BIP Draft: Custom Services2012-08-10T19:36:16Z<p>Justmoon: Formatting fix.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. This command SHOULD consist of the exact service identifier to avoid collisions with other services, prefixed by an underscore to avoid collisions with current or future Bitcoin protocol messages. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use a discovery mechanism which specifies one bit per node, same as the <code>services</code> field in <code>addr</code> messages<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29655User:Justmoon/BIP Draft: Custom Services2012-08-10T19:34:54Z<p>Justmoon: Rephrased first part of custom services section for clarity.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. This command SHOULD consist of the exact service identifier to avoid collisions with other services, prefixed by an underscore to avoid collisions with current or future Bitcoin protocol messages. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use a discovery mechanism which specifies one bit per node, same as the services field in <code>addr</code> messages<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29654User:Justmoon/BIP Draft: Custom Services2012-08-10T19:05:51Z<p>Justmoon: Removed reference to removed section.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. To avoid collision with other services the exact service identifier SHOULD be used, but to avoid collisions with current or future Bitcoin messages the service identifier SHOULD be prefixed with an underscore. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use a discovery mechanism which specifies one bit per node, same as the services field in <code>addr</code> messages<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29652User:Justmoon/BIP Draft: Custom Services2012-08-10T18:21:10Z<p>Justmoon: Fix whitespace.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. To avoid collision with other services the exact service identifier SHOULD be used, but to avoid collisions with current or future Bitcoin messages the service identifier SHOULD be prefixed with an underscore. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use the <code>*:addr</code> mechanism in this BIP; This specifies one bit per node, same as standard services<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29651User:Justmoon/BIP Draft: Custom Services2012-08-10T18:20:49Z<p>Justmoon: Split off service discovery into its own BIP.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. To avoid collision with other services the exact service identifier SHOULD be used, but to avoid collisions with current or future Bitcoin messages the service identifier SHOULD be prefixed with an underscore. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use the <code>*:addr</code> mechanism in this BIP; This specifies one bit per node, same as standard services<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Service_Discovery&diff=29650User:Justmoon/BIP Draft: Custom Service Discovery2012-08-10T18:20:21Z<p>Justmoon: Section split off from original BIP.</p>
<hr />
<div><br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> field for each node in the <code>addr</code> message. This is very useful for discovering other nodes that support a specific service. For example a lightweight client may be interested in finding all the nodes capable of serving it.<br />
<br />
However, some services may not need this functionality whereas other services may need to communicate extra information per node. So rather than modifying the <code>addr</code> message, we instead send a service-specific message ahead of it. This message SHOULD use the addr subcommand, so for the <code>MySampleSvc</code> service it would be called <code>MySampleSvc:addr</code>. We'll refer to it here generically as the <code>*:addr</code> message.<br />
<br />
The <code>*:addr</code> of a service specifies which nodes in the next following <code>addr</code> list support that service. It uses the following format:<br />
<br />
* If <code>*:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>*:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>*:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>*:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29388User:Justmoon/BIP Draft: Custom Services2012-08-04T08:48:23Z<p>Justmoon: Removed some now redundant information from Rationale.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. To avoid collision with other services the exact service identifier SHOULD be used, but to avoid collisions with current or future Bitcoin messages the service identifier SHOULD be prefixed with an underscore. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> field for each node in the <code>addr</code> message. This is very useful for discovering other nodes that support a specific service. For example a lightweight client may be interested in finding all the nodes capable of serving it.<br />
<br />
However, some services may not need this functionality whereas other services may need to communicate extra information per node. So rather than modifying the <code>addr</code> message, we instead send a service-specific message ahead of it. This message SHOULD use the addr subcommand, so for the <code>MySampleSvc</code> service it would be called <code>MySampleSvc:addr</code>. We'll refer to it here generically as the <code>*:addr</code> message.<br />
<br />
The <code>*:addr</code> of a service specifies which nodes in the next following <code>addr</code> list support that service. It uses the following format:<br />
<br />
* If <code>*:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>*:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>*:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>*:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use the <code>*:addr</code> mechanism in this BIP; This specifies one bit per node, same as standard services<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29387User:Justmoon/BIP Draft: Custom Services2012-08-04T08:46:48Z<p>Justmoon: Minor formatting and wording fixes.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. To avoid collision with other services the exact service identifier SHOULD be used, but to avoid collisions with current or future Bitcoin messages the service identifier SHOULD be prefixed with an underscore. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> field for each node in the <code>addr</code> message. This is very useful for discovering other nodes that support a specific service. For example a lightweight client may be interested in finding all the nodes capable of serving it.<br />
<br />
However, some services may not need this functionality whereas other services may need to communicate extra information per node. So rather than modifying the <code>addr</code> message, we instead send a service-specific message ahead of it. This message SHOULD use the addr subcommand, so for the <code>MySampleSvc</code> service it would be called <code>MySampleSvc:addr</code>. We'll refer to it here generically as the <code>*:addr</code> message.<br />
<br />
The <code>*:addr</code> of a service specifies which nodes in the next following <code>addr</code> list support that service. It uses the following format:<br />
<br />
* If <code>*:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>*:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>*:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>*:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use the <code>*:addr</code> mechanism in this BIP; This specifies one bit per node, same as standard services<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
While writing this BIP it became apparent that twelve characters were not sufficient to contain both the service identifier and the subcommand. This lead to the definition of a recommended encoding for service-specific messages. Services where this encoding is not appropriate are able to supercede it.<br />
<br />
For announcing other nodes supporting the service, it would have been possible to extend the <code>addr</code> message, however some services may not require this type of announcement whereas other services may wish to include additional information per node. Therefore we provide a recommended scheme that implements efficiently the same functionality provided by the <code>services</code> bitmask. Services for which this scheme is not appropriate can supercede these recommendations as needed.<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29386User:Justmoon/BIP Draft: Custom Services2012-08-04T08:44:15Z<p>Justmoon: Added section expanding on standardization.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. To avoid collision with other services the exact service identifier SHOULD be used, but to avoid collisions with current or future Bitcoin messages the service identifier SHOULD be prefixed with an underscore. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> field for each node in the <code>addr</code> message. This is very useful for discovering other nodes that support a specific service. For example a lightweight client may be interested in finding all the nodes capable of serving it.<br />
<br />
However, some services may not need this functionality whereas other services may need to communicate extra information per node. So rather than modifying the <code>addr</code> message, we instead send a service-specific message ahead of it. This message SHOULD use the addr subcommand, so for the <code>MySampleSvc</code> service it would be called <code>MySampleSvc:addr</code>. We'll refer to it here generically as the <code>*:addr</code> message.<br />
<br />
The <code>*:addr</code> of a service specifies which nodes in the next following <code>addr</code> list support that service. It uses the following format:<br />
<br />
* If <code>*:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>*:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>*:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>*:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
==Standardization==<br />
<br />
Custom services may become standard parts of the protocol. Services which wish to become part of the Bitcoin protocol MUST fulfill the following criteria:<br />
<br />
* MUST NOT use <code>service_data</code>; Standard services have no corresponding field<br />
* MUST use the *:addr mechanism; Standard services can specify one bit per node<br />
* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands<br />
<br />
The standardization process will usually take place as follows:<br />
<br />
# The service is implemented and tested.<br />
# Once the API is known to be relatively stable it is formalized and submitted as a BIP.<br />
# Once the BIP is accepted, the service is assigned a <code>NODE_*</code> constant and the transitional period starts:<br />
#* Clients MUST understand both the announcement of the service via the <code>services</code> field and via <code>service_list</code> and include both methods in their own <code>version</code> message.<br />
#* Clients MUST accept both the wrapped form messages like <code>MySampleSvc:search</code> as well as the corresponding non-namespaced messages like <code>search</code>. Clients MUST only send wrapped messages.<br />
#* During the transitional period the API of the service MUST NOT change.<br />
# After the transitional period:<br />
#* Clients MUST only announce the service via the <code>services</code> field.<br />
#* Clients MUST only send unwrapped messages.<br />
# Future changes to the service API now require a BIP and an increase in the Bitcoin protocol version.<br />
<br />
This process of adding a service to the Bitcoin protocol should only be undertaken for services where there is a strong rationale for doing so. Services MAY also be standardized as custom services via a BIP while maintaining the custom service format.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
While writing this BIP it became apparent that twelve characters were not sufficient to contain both the service identifier and the subcommand. This lead to the definition of a recommended encoding for service-specific messages. Services where this encoding is not appropriate are able to supercede it.<br />
<br />
For announcing other nodes supporting the service, it would have been possible to extend the <code>addr</code> message, however some services may not require this type of announcement whereas other services may wish to include additional information per node. Therefore we provide a recommended scheme that implements efficiently the same functionality provided by the <code>services</code> bitmask. Services for which this scheme is not appropriate can supercede these recommendations as needed.<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29385User:Justmoon/BIP Draft: Custom Services2012-08-04T08:22:41Z<p>Justmoon: Clarified *:addr message.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. To avoid collision with other services the exact service identifier SHOULD be used, but to avoid collisions with current or future Bitcoin messages the service identifier SHOULD be prefixed with an underscore. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> field for each node in the <code>addr</code> message. This is very useful for discovering other nodes that support a specific service. For example a lightweight client may be interested in finding all the nodes capable of serving it.<br />
<br />
However, some services may not need this functionality whereas other services may need to communicate extra information per node. So rather than modifying the <code>addr</code> message, we instead send a service-specific message ahead of it. This message SHOULD use the addr subcommand, so for the <code>MySampleSvc</code> service it would be called <code>MySampleSvc:addr</code>. We'll refer to it here generically as the <code>*:addr</code> message.<br />
<br />
The <code>*:addr</code> of a service specifies which nodes in the next following <code>addr</code> list support that service. It uses the following format:<br />
<br />
* If <code>*:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>*:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>*:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>*:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
While writing this BIP it became apparent that twelve characters were not sufficient to contain both the service identifier and the subcommand. This lead to the definition of a recommended encoding for service-specific messages. Services where this encoding is not appropriate are able to supercede it.<br />
<br />
For announcing other nodes supporting the service, it would have been possible to extend the <code>addr</code> message, however some services may not require this type of announcement whereas other services may wish to include additional information per node. Therefore we provide a recommended scheme that implements efficiently the same functionality provided by the <code>services</code> bitmask. Services for which this scheme is not appropriate can supercede these recommendations as needed.<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29384User:Justmoon/BIP Draft: Custom Services2012-08-04T07:56:52Z<p>Justmoon: Clarified service messages section.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Custom commands===<br />
<br />
Bitcoin command names are limited to 12 characters. That doesn't leave a lot of space for both the service identifier and the service command. Therefore we recommend that all service commands SHOULD be represented by a single "command" on the Bitcoin network. To avoid collision with other services the exact service identifier SHOULD be used, but to avoid collisions with current or future Bitcoin messages the service identifier SHOULD be prefixed with an underscore. For example: <code>_MySampleSvc</code><br />
<br />
The service-specific command name SHOULD then be specified in an extra header in the payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> for each node in the <code>addr</code> message. In order to provide the same functionality, a custom service X MAY define a message <code>X:addr</code> with the following format:<br />
<br />
* If <code>X:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>X:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>X:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>X:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
While writing this BIP it became apparent that twelve characters were not sufficient to contain both the service identifier and the subcommand. This lead to the definition of a recommended encoding for service-specific messages. Services where this encoding is not appropriate are able to supercede it.<br />
<br />
For announcing other nodes supporting the service, it would have been possible to extend the <code>addr</code> message, however some services may not require this type of announcement whereas other services may wish to include additional information per node. Therefore we provide a recommended scheme that implements efficiently the same functionality provided by the <code>services</code> bitmask. Services for which this scheme is not appropriate can supercede these recommendations as needed.<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29381User:Justmoon/BIP Draft: Custom Services2012-08-04T07:20:00Z<p>Justmoon: Recommend ASCII for service_data to ease introspection.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data. For ease of debugging/introspection, a human-readable (ASCII) format is generally recommended.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Service messages===<br />
<br />
All messages of a custom service SHOULD be represented by a single "command" on the Bitcoin network, consisting of an underscore, followed by the service identifier. For example: <code>_MySampleSvc</code><br />
<br />
To distinguish different messages within the service, the following format SHOULD be used:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> for each node in the <code>addr</code> message. In order to provide the same functionality, a custom service X MAY define a message <code>X:addr</code> with the following format:<br />
<br />
* If <code>X:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>X:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>X:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>X:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
While writing this BIP it became apparent that twelve characters were not sufficient to contain both the service identifier and the subcommand. This lead to the definition of a recommended encoding for service-specific messages. Services where this encoding is not appropriate are able to supercede it.<br />
<br />
For announcing other nodes supporting the service, it would have been possible to extend the <code>addr</code> message, however some services may not require this type of announcement whereas other services may wish to include additional information per node. Therefore we provide a recommended scheme that implements efficiently the same functionality provided by the <code>services</code> bitmask. Services for which this scheme is not appropriate can supercede these recommendations as needed.<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29380User:Justmoon/BIP Draft: Custom Services2012-08-04T07:18:06Z<p>Justmoon: Added link to service identifier registration wiki page.</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service. To register a new identifier, add it to the [[Service identifiers]] wiki page along with the name of the maintainer and a way to contact them. Please do not register identifiers unless you are actually using them.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Service messages===<br />
<br />
All messages of a custom service SHOULD be represented by a single "command" on the Bitcoin network, consisting of an underscore, followed by the service identifier. For example: <code>_MySampleSvc</code><br />
<br />
To distinguish different messages within the service, the following format SHOULD be used:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> for each node in the <code>addr</code> message. In order to provide the same functionality, a custom service X MAY define a message <code>X:addr</code> with the following format:<br />
<br />
* If <code>X:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>X:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>X:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>X:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
While writing this BIP it became apparent that twelve characters were not sufficient to contain both the service identifier and the subcommand. This lead to the definition of a recommended encoding for service-specific messages. Services where this encoding is not appropriate are able to supercede it.<br />
<br />
For announcing other nodes supporting the service, it would have been possible to extend the <code>addr</code> message, however some services may not require this type of announcement whereas other services may wish to include additional information per node. Therefore we provide a recommended scheme that implements efficiently the same functionality provided by the <code>services</code> bitmask. Services for which this scheme is not appropriate can supercede these recommendations as needed.<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29364User:Justmoon/BIP Draft: Custom Services2012-08-03T19:16:05Z<p>Justmoon: </p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Service messages===<br />
<br />
All messages of a custom service SHOULD be represented by a single "command" on the Bitcoin network, consisting of an underscore, followed by the service identifier. For example: <code>_MySampleSvc</code><br />
<br />
To distinguish different messages within the service, the following format SHOULD be used:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> for each node in the <code>addr</code> message. In order to provide the same functionality, a custom service X MAY define a message <code>X:addr</code> with the following format:<br />
<br />
* If <code>X:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>X:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>X:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>X:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
While writing this BIP it became apparent that twelve characters were not sufficient to contain both the service identifier and the subcommand. This lead to the definition of a recommended encoding for service-specific messages. Services where this encoding is not appropriate are able to supercede it.<br />
<br />
For announcing other nodes supporting the service, it would have been possible to extend the <code>addr</code> message, however some services may not require this type of announcement whereas other services may wish to include additional information per node. Therefore we provide a recommended scheme that implements efficiently the same functionality provided by the <code>services</code> bitmask. Services for which this scheme is not appropriate can supercede these recommendations as needed.<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/BIP_Draft:_Custom_Services&diff=29363User:Justmoon/BIP Draft: Custom Services2012-08-03T19:10:27Z<p>Justmoon: First draft</p>
<hr />
<div>{{bip}}<br />
<br />
<pre><br />
BIP: Draft<br />
Title: Custom Services<br />
Author: Stefan Thomas <justmoon@members.fsf.org><br />
Status: Draft<br />
Type: Standards Track<br />
Created: 03-08-2012<br />
</pre><br />
<br />
==Abstract==<br />
<br />
This BIP adds new fields to the <code>version</code> message which clients can use to announce custom services without polluting the limited 64-bit <code>services</code> field. It also makes some non-binding recommendations regarding the implementation of custom services.<br />
<br />
==Motivation==<br />
<br />
We would like to encourage experimentation with custom services that extend the Bitcoin protocol with useful functionality. Examples include Distributed Hash Tables (DHT), distributed pools, lightweight client support protocols, directed message routing and support for custom transports. However, without a general, extensible framework for protocol extensions, these custom services are likely to collide in various ways. This BIP provides such a framework.<br />
<br />
==Specification==<br />
<br />
Two new fields are added to the <code>version</code> command, after <code>extra_height</code>:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || service_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of extra services<br />
|-<br />
| ? || service_list || service[] || List of service definitions<br />
|}<br />
<br />
The service definitions are given in the following format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || service_name || [[#Variable length string|var_str]] || Unique service identifier<br />
|-<br />
| 4 || service_version || uint32_t || Identifies service version being used by the node<br />
|-<br />
| ? || service_data || [[#Variable length string|var_str]] || Additional service-specific data<br />
|}<br />
<br />
A node MUST NOT announce two services with the same <code>service_name</code>. If a remote node sends such a <code>version</code> message the client MAY disconnect.<br />
<br />
The <code>service_version</code> is service-specific and can be any integer. Higher versions SHOULD be higher integers. When a service is standardized, it is assigned a <code>NODE_*</code> constant for use with the <code>services</code> field and future iterations of the protocol depend on the Bitcoin protocol version. Both the <code>NODE_*</code> flag and the custom service entry MAY be provided for the duration of a transitional period.<br />
<br />
Services SHOULD pass an empty string (0x00) as <code>service_data</code> and use a custom handshake to initialize their protocol, exchange information about capabilities etc. Note that to become a standardized service, a service MUST NOT rely on <code>service_data</code> since there is no corresponding mechanism for the standard services defined in the <code>services</code> field.<br />
<br />
However, services MAY use <code>service_data</code> if they do not intend to become standard services and need a simple way to transmit a small amount of initialization data. For example, a node offering a custom transport like UDP or WebSocket, may choose to announce this as a service and include the port number in <code>service_data</code>. The format for <code>service_data</code> is service-specific and may be any binary or ASCII data.<br />
<br />
===Service identifier===<br />
<br />
Each service SHOULD choose a new identifier that is not used by any other service.<br />
<br />
Service identifiers that are reserved or used by an accepted BIP MUST NOT be used except in the way specified by that BIP.<br />
<br />
Service identifiers MUST be between five (5) and eleven (11) characters long. Service identifiers MUST use only ASCII characters, excluding: / * _ :<br />
<br />
Valid examples:<br />
* <code>MySampleSvc</code><br />
* <code>smartserv</code><br />
* <code>P-Pool</code><br />
<br />
Valid, but discouraged examples:<br />
<br />
* <code>MySVC 1.0</code> (use <code>service_version</code> to differentiate versions)<br />
* <code>@@---.</code> (identifiers should be pronounceable)<br />
* <code>lightweight</code> (avoid too generic names)<br />
<br />
Invalid examples:<br />
<br />
* <code>Pppc</code> (too short)<br />
* <code>SuperService</code> (too long)<br />
* <code>Cool_Svc</code> (invalid character)<br />
<br />
===Optional: Service messages===<br />
<br />
All messages of a custom service SHOULD be represented by a single "command" on the Bitcoin network, consisting of an underscore, followed by the service identifier. For example: <code>_MySampleSvc</code><br />
<br />
To distinguish different messages within the service, the following format SHOULD be used:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 12 || subcommand || char[12] || ASCII string identifying the service command, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| ? || subpayload || uchar[] || The actual data<br />
|}<br />
<br />
The length of <code>subpayload</code> is derived from the length of the total payload minus twelve (12) bytes for the <code>subcommand</code>. Implementations MUST NOT rely on this format to be used by unknown services. Clients SHOULD ignore any services or subcommands they don't explicitly understand.<br />
<br />
The recommended way to refer to messages following this format in documentation is by the service identifier, followed by a colon, followed by the subcommand. For example, the subcommand <code>search</code> for the <code>MySampleSvc</code> service would be referred to as: <code>MySampleSvc:search</code><br />
<br />
Full hexdump of an example <code>MySampleSvc:search</code> message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 5F 4D 79 53 61 6D 70 6C 65 53 76 63 ...._MySampleSvc<br />
0010 14 00 00 00 73 D5 56 77 73 65 61 72 63 68 00 00 ....s.Vwsearch..<br />
0020 00 00 00 00 12 34 56 78 9A BC DE F0 .....4Vx....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
5F 4D 79 53 61 6D 70 6C 65 53 76 63 - "_MySampleSvc" command<br />
14 00 00 00 - Payload is 20 bytes long<br />
(includes 12 bytes for subcommand)<br />
73 D5 56 77 - Checksum<br />
<br />
Service header:<br />
73 65 61 72 63 68 00 00 00 00 00 00 - "search" subcommand<br />
<br />
Search message:<br />
12 34 56 78 9A BC DE F0 - Payload<br />
</pre><br />
<br />
===Optional: Announcing known nodes===<br />
<br />
Bitcoin includes the <code>services</code> for each node in the <code>addr</code> message. In order to provide the same functionality, a custom service X MAY define a message <code>X:addr</code> with the following definition:<br />
<br />
* If <code>X:addr</code> is empty or starts with TYPE_ALL (0x00), then all addresses in the next <code>addr</code> message support the service.<br />
* If <code>X:addr</code> starts with TYPE_BITS (0x01), then the rest of the data is a bit array marking which nodes in the next addr message support the service. Any nodes not covered by the bitarray don't support the service.<br />
* If <code>X:addr</code> starts with TYPE_RLE (0x02), then the next byte determines whether the first address supports the service and the remaining data is a series of [[Protocol_specification#Variable_length_integer|var_ints]] determining the lengths of runs of nodes that support or don't support the service, not counting the first node in the run. Any nodes not covered by the RLE have the opposite value of the last node covered.<br />
* If there was no <code>X:addr</code> message since the last <code>addr</code> message or the beginning of the connection, then none of the nodes in the next <code>addr</code> message support the service.<br />
<br />
Examples:<br />
<br />
00 - TYPE_ALL - all nodes in the next addr message support the service<br />
<br />
01 - TYPE_BITS<br />
FC - 11111100 - First six nodes support the service, next two don't<br />
1F - 00011111 - Next three don't, next five do<br />
- Remaining nodes don't<br />
<br />
02 - TYPE_RLE<br />
01 - First set of nodes are nodes that support the service<br />
05 - First six nodes support the service<br />
FD 42 03 - Next 835 nodes don't<br />
00 - Next node does<br />
08 - Next nine nodes don't<br />
- Remaining nodes do<br />
<br />
Multiple <code>X:addr</code> messages for different services MUST all be applied to the next <code>addr</code> message. If there are multiple <code>X:addr</code> messages for the same service, only the most recent one is used.<br />
<br />
If a node knows about many different services, the recommendation is to store a bitmask of all the recognized services for each node, order by that field and then use <code>X:addr</code> messages using TYPE_RLE.<br />
<br />
==Rationale==<br />
<br />
This BIP aims to fulfill the following goals:<br />
<br />
* Minimize the risk of namespace collisions, ambiguities or other issues arising from conflicting custom services<br />
* Provide an easy upgrade path for custom services to become standardized services with their own <code>NODE_*</code> flag<br />
* Place minimum restrictions on custom service authors<br />
* Allow custom services to be created with minimum effort<br />
* Allow clients to support multiple/many custom services at once<br />
<br />
To achieve these goals this BIP adds two new fields to the <code>version</code> message. It would have been possible to avoid changes to <code>version</code> by adding a new message instead. However, it makes sense to keep both types of service announcements in the same message so that the life cycle of standardized services and custom services remains exactly the same. This also simplifies detecting a service which is in the transition from a custom to a standardized service (and being announced using both methods.)<br />
<br />
While writing this BIP it became apparent that twelve characters were not sufficient to contain both the service identifier and the subcommand. This lead to the definition of a recommended encoding for service-specific messages. Services where this encoding is not appropriate are able to supercede it.<br />
<br />
For announcing other nodes supporting the service, it would have been possible to extend the <code>addr</code> message, however some services may not require this type of announcement whereas other services may wish to include additional information per node. Therefore we provide a recommended scheme that implements efficiently the same functionality provided by the <code>services</code> bitmask. Services for which this scheme is not appropriate can supercede these recommendations as needed.<br />
<br />
Finally, this BIP defines both explicitly and implicitly some useful common nomenclature that can be used when discussing custom services, e.g. "subcommand", "subpayload", "service identifier" and the colon format for referring to subcommands.<br />
<br />
==Copyright==<br />
<br />
This document is placed in the public domain.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Protocol_documentation&diff=29362Protocol documentation2012-08-03T19:06:05Z<p>Justmoon: Did not mean to remove the "Payload:", re-added</p>
<hr />
<div>Sources:<br />
* [[Original Bitcoin client]] source<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[Getwork]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use '''Double''' SHA-256, and are built up as so:<br />
<br />
hash(a) = sha256(sha256(a))<br />
<br />
hash(a) hash(b) hash(c)<br />
hash(hash(a)+hash(b)) hash(hash(c)+hash(c))<br />
hash(hash(hash(a)+hash(b))+hash(hash(c)+hash(c)))<br />
<br />
They are paired up, with the last element being _duplicated_.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For ECDSA the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd. Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Scripting]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totaling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space. Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xfd || 1 || uint8_t<br />
|-<br />
| <= 0xffff || 3 || 0xfd followed by the length as uint16_t<br />
|-<br />
| <= 0xffffffff || 5 || 0xfe followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xff followed by the length as uint64_t<br />
|}<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. This protocol and structure supports IPv6, '''but note that the original client currently only supports IPv4 networking'''. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402)<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:10.0.0.1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Block version information, based upon the software version creating this block<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || uint8_t || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately advertise its version. The remote node will respond with its version. No futher communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || net_addr || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| version >= 106<br />
|-<br />
| 26 || addr_from || net_addr || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [[BIP_0014|User Agent]] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE. This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + net_addr)[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum payload length: 50000 bytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements.<br />
<br />
Payload (maximum payload length: 50000 bytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known (and correct) hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indices(int top_depth)<br />
{<br />
// Start at max_depth<br />
std::vector<size_t> indices;<br />
// Push last 10 indices first<br />
size_t step = 1, start = 0;<br />
for (int i = top_depth; i > 0; i -= step, ++start)<br />
{<br />
if (start >= 10)<br />
step *= 2;<br />
indices.push_back(i);<br />
}<br />
indices.push_back(0);<br />
return indices;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known (and correct) hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the blockchain where the contents of the transactions would be irrelevant (because they are not ours). <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_specification#Variable_length_integer|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''getdata''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Transaction data format version<br />
|-<br />
| 1+ || tx_in count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 8+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Always locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
A non-locked transaction must not be included in blocks, and it can be modified by broadcasting a new version before the time has expired (replacement is currently disabled in Bitcoin, however, so this is useless).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_specification#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Block version information, based upon the software version creating this block<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_specification#Block_Headers|block_header]][] || [[Protocol_specification#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers which are sent to miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with identifying potential nodes in the network. The response to receiving this message is to transmit an addr message with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== checkorder ===<br />
<br />
This message is used for [[IP Transactions]], to ask the peer if it accepts such transactions and allow it to look at the content of the order.<br />
<br />
It contains a CWalletTx object<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
|colspan="4"| Fields from CMerkleTx<br />
|-<br />
| ? || hashBlock<br />
|-<br />
| ? || vMerkleBranch<br />
|-<br />
| ? || nIndex<br />
|-<br />
|colspan="4"| Fields from CWalletTx<br />
|-<br />
| ? || vtxPrev<br />
|-<br />
| ? || mapValue<br />
|-<br />
| ? || vOrderForm<br />
|-<br />
| ? || fTimeReceivedIsTxTime<br />
|-<br />
| ? || nTimeReceived<br />
|-<br />
| ? || fFromMe<br />
|-<br />
| ? || fSpent<br />
|}<br />
<br />
=== submitorder ===<br />
<br />
Confirms an order has been submitted. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || Hash of the transaction<br />
|-<br />
| ? || wallet_entry || CWalletTx || Same payload as checkorder<br />
|}<br />
<br />
=== reply ===<br />
<br />
Generic reply for [[IP Transactions]]<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || reply || uint32_t || reply code<br />
|}<br />
<br />
Possible values:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || SUCCESS || The IP Transaction can proceed (''checkorder''), or has been accepted (''submitorder'')<br />
|-<br />
| 1 || WALLET_ERROR || AcceptWalletTransaction() failed<br />
|-<br />
| 2 || DENIED || IP Transactions are not accepted by this node<br />
|}<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. No reply is expected as a result of this message being sent nor any sort of action expected on the part of a client when it is used.<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || var_str || Serialized alert payload<br />
|-<br />
| ? || signature || var_str || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a var_str to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be canceled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int> || All alert IDs contained in this set should be canceled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
== Wireshark dissector ==<br />
A dissector for wireshark is being developed at https://github.com/blueCommand/bitcoin-dissector<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Protocol_documentation&diff=29361Protocol documentation2012-08-03T19:04:56Z<p>Justmoon: Limit for addr is 1000 entries, not 1000 bytes</p>
<hr />
<div>Sources:<br />
* [[Original Bitcoin client]] source<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[Getwork]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use '''Double''' SHA-256, and are built up as so:<br />
<br />
hash(a) = sha256(sha256(a))<br />
<br />
hash(a) hash(b) hash(c)<br />
hash(hash(a)+hash(b)) hash(hash(c)+hash(c))<br />
hash(hash(hash(a)+hash(b))+hash(hash(c)+hash(c)))<br />
<br />
They are paired up, with the last element being _duplicated_.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For ECDSA the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd. Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Scripting]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totaling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space. Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xfd || 1 || uint8_t<br />
|-<br />
| <= 0xffff || 3 || 0xfd followed by the length as uint16_t<br />
|-<br />
| <= 0xffffffff || 5 || 0xfe followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xff followed by the length as uint64_t<br />
|}<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. This protocol and structure supports IPv6, '''but note that the original client currently only supports IPv4 networking'''. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402)<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:10.0.0.1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Block version information, based upon the software version creating this block<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || uint8_t || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately advertise its version. The remote node will respond with its version. No futher communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || net_addr || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| version >= 106<br />
|-<br />
| 26 || addr_from || net_addr || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [[BIP_0014|User Agent]] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE. This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + net_addr)[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum payload length: 50000 bytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements.<br />
<br />
Payload (maximum payload length: 50000 bytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known (and correct) hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indices(int top_depth)<br />
{<br />
// Start at max_depth<br />
std::vector<size_t> indices;<br />
// Push last 10 indices first<br />
size_t step = 1, start = 0;<br />
for (int i = top_depth; i > 0; i -= step, ++start)<br />
{<br />
if (start >= 10)<br />
step *= 2;<br />
indices.push_back(i);<br />
}<br />
indices.push_back(0);<br />
return indices;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known (and correct) hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the blockchain where the contents of the transactions would be irrelevant (because they are not ours). <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_specification#Variable_length_integer|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''getdata''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Transaction data format version<br />
|-<br />
| 1+ || tx_in count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 8+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Always locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
A non-locked transaction must not be included in blocks, and it can be modified by broadcasting a new version before the time has expired (replacement is currently disabled in Bitcoin, however, so this is useless).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_specification#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Block version information, based upon the software version creating this block<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_specification#Block_Headers|block_header]][] || [[Protocol_specification#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers which are sent to miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with identifying potential nodes in the network. The response to receiving this message is to transmit an addr message with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== checkorder ===<br />
<br />
This message is used for [[IP Transactions]], to ask the peer if it accepts such transactions and allow it to look at the content of the order.<br />
<br />
It contains a CWalletTx object<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
|colspan="4"| Fields from CMerkleTx<br />
|-<br />
| ? || hashBlock<br />
|-<br />
| ? || vMerkleBranch<br />
|-<br />
| ? || nIndex<br />
|-<br />
|colspan="4"| Fields from CWalletTx<br />
|-<br />
| ? || vtxPrev<br />
|-<br />
| ? || mapValue<br />
|-<br />
| ? || vOrderForm<br />
|-<br />
| ? || fTimeReceivedIsTxTime<br />
|-<br />
| ? || nTimeReceived<br />
|-<br />
| ? || fFromMe<br />
|-<br />
| ? || fSpent<br />
|}<br />
<br />
=== submitorder ===<br />
<br />
Confirms an order has been submitted. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || Hash of the transaction<br />
|-<br />
| ? || wallet_entry || CWalletTx || Same payload as checkorder<br />
|}<br />
<br />
=== reply ===<br />
<br />
Generic reply for [[IP Transactions]]<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || reply || uint32_t || reply code<br />
|}<br />
<br />
Possible values:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || SUCCESS || The IP Transaction can proceed (''checkorder''), or has been accepted (''submitorder'')<br />
|-<br />
| 1 || WALLET_ERROR || AcceptWalletTransaction() failed<br />
|-<br />
| 2 || DENIED || IP Transactions are not accepted by this node<br />
|}<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. No reply is expected as a result of this message being sent nor any sort of action expected on the part of a client when it is used.<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || var_str || Serialized alert payload<br />
|-<br />
| ? || signature || var_str || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a var_str to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be canceled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int> || All alert IDs contained in this set should be canceled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
== Wireshark dissector ==<br />
A dissector for wireshark is being developed at https://github.com/blueCommand/bitcoin-dissector<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon&diff=29274User:Justmoon2012-08-02T13:49:46Z<p>Justmoon: Some linkifikation.</p>
<hr />
<div>Also known as Stefan Thomas, I'm the guy behind [http://www.weusecoins.com/ WeUseCoins] and [http://bitcoinjs.org BitcoinJS] - on the wiki, doing my best to help out.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon&diff=29273User:Justmoon2012-08-02T13:48:42Z<p>Justmoon: Now I have a page too! :)</p>
<hr />
<div>Also known as Stefan Thomas, I'm the guy behind WeUseCoins and BitcoinJS - on the wiki, doing my best to help out.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Clients&diff=29272Clients2012-08-02T09:58:18Z<p>Justmoon: Change My Wallet link from "eWallet" to "Web-based" - they're all eWallets, web-based is a more meaningful term.</p>
<hr />
<div>==Overview==<br />
<br />
This table compares the features of the different clients. All of the listed clients are open-source.<br />
<br />
===Feature key===<br />
<br />
; Wallet Security : How well the client protects your [[private key]]s from people with access to the machine the wallet is stored on. The private keys can be encrypted, for example.<br />
; Network Security : Clients which more fully implement the Bitcoin network protocol are safer -- they can't be as easily tricked by powerful attackers. A client which ''fully'' implements the protocol will always use the correct [[block chain]] and will never allow [[double-spending|double-spends]] or invalid transactions to exist in the block chain under any circumstances. Clients which only ''partially'' implement the protocol typically trust that 50% or more of the network's mining power is honest. Some clients trust one or more ''remote servers'' to protect them from double-spends and other network attacks.<br />
; Setup Time : Some clients require that you download and verify a large amount of data before you can send or receive BTC.<br />
; Maturity : When the project was started.<br />
<br />
===Table===<br />
<br />
<!-- please keep this alphabetic --><br />
{| class='wikitable' style='text-align: center'<br />
! Client !! Get Started !! Audience !! Wallet Security !! Network Security !! Backups !! Setup Time !! Disk Space !! Maturity !! Multi-user !! Available for<br />
|-<br />
! Armory<br />
|| [http://bitcoinarmory.com/index.php/get-armory Download] || Power users || {{CLGood|Encryption}} || Addon || {{CLBest|One-time}} || Varies || {{CLBad|2+ GB}} || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLWin}}<br />
|-<br />
! Bitcoin Wallet<br />
|| [https://play.google.com/store/apps/details?id=de.schildbach.wallet Download] || {{CLGood|End-users}} || {{CLGood|Isolated}} || Partial || Manual || 1 hour || 30 MB || Mar 2011 || No || {{CLAndroid}}<br />
|-<br />
! {{CLGood|Bitcoin-Qt}}<br />
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || {{CLGood|End-users}} || {{CLGood|Encryption}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|2+ GB}} || {{CLGood|May 2011}} || No || {{CLLinux}}{{CLMac}}{{CLWin}}<br />
|-<br />
! bitcoind<br />
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || Programmers || {{CLGood|Encryption}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|2+ GB}} || {{CLBest|Aug 2009}} || {{CLGood|Virtual accounts}} || {{CLLinux}}{{CLWin}}<br />
|-<br />
! Electrum<br />
|| [http://ecdsa.org/electrum/ Download] || Power users || {{CLGood|Encryption}} || Minimal || {{CLBest|Memorized}} || {{CLGood|Minutes}} || {{CLGood|5 MB}} || Nov 2011 || No || {{CLLinux}}{{CLWin}}<br />
|-<br />
! MultiBit<br />
|| [http://multibit.org/releases.html Download] || {{CLGood|End-users}} || {{CLBad|None}} || Partial || {{CLBad|No}} || 1 hour || 50 MB || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLMac}}{{CLWin}}<br />
|-<br />
! My Wallet<br />
|| [https://blockchain.info/wallet/new Web-based] || {{CLBest|Everyone}} || {{CLGood|Encryption}} || {{CLBad|Remote}} || {{CLGood|Automatic}} || {{CLGood|Minutes}} || {{CLBest|None}} || Dec 2011 || {{CLBest|Yes}} || {{CLAndroid}}{{CLiOS}}{{CLLinux}}{{CLMac}}{{CLWin}}<br />
|}<br />
<br />
<!-- For Wallet Security: CLBest is reserved for multisig-based --><br />
<br />
==For developers==<br />
<br />
This table shows additional information about various Bitcoin clients that may be relevant to developers.<br />
<br />
{| class='wikitable' style='text-align: center'<br />
! Client !! Website !! Source Code !! License !! Discussion !! Architecture<br />
|-<br />
! Armory<br />
|| [http://bitcoinarmory.com/ Link] ||[https://github.com/etotheipi/BitcoinArmory/ Github] || AGPLv3 || [https://bitcointalk.org/index.php?topic=56424.0 Bitcointalk] || Integrated<br />
|-<br />
! Bitcoin Wallet<br />
|| [http://code.google.com/p/bitcoin-wallet/ Link] || [http://code.google.com/p/bitcoin-wallet/source/checkout Google Code] || GPLv3 || None / [https://groups.google.com/forum/?fromgroups#!forum/bitcoinj Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]<br />
|-<br />
! Bitcoin-Qt / bitcoind<br />
|| [http://bitcoin.org/ Link] || [https://github.com/bitcoin/bitcoin Github] || MIT || [https://lists.sourceforge.net/lists/listinfo/bitcoin-development Sourceforge] || Integrated<br />
|-<br />
! Electrum<br />
|| [http://ecdsa.org/electrum/ Link] || [https://gitorious.org/electrum Gitorious] || GPLv3 || [https://lists.sourceforge.net/lists/listinfo/electrum-discuss Sourceforge] || [[Thin Client Security#Server-Trusting Clients|Server-Client]]<br />
|-<br />
! MultiBit<br />
|| [http://multibit.org/ Link] || [https://github.com/jim618/multibit Github] || MIT || [https://groups.google.com/forum/?fromgroups#!forum/bitcoin-multibit Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]<br />
|-<br />
! My Wallet<br />
|| [https://blockchain.info/wallet/ Link] || [https://github.com/blockchain/My-Wallet/ Github] || BSD* || None || [[Thin Client Security#Server-Trusting Clients|Server-Client]]<br />
|}<br />
<br />
<references/></div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Clients&diff=29271Clients2012-08-02T09:56:35Z<p>Justmoon: Fix markup - the whole table doesn't need to be bold</p>
<hr />
<div>==Overview==<br />
<br />
This table compares the features of the different clients. All of the listed clients are open-source.<br />
<br />
===Feature key===<br />
<br />
; Wallet Security : How well the client protects your [[private key]]s from people with access to the machine the wallet is stored on. The private keys can be encrypted, for example.<br />
; Network Security : Clients which more fully implement the Bitcoin network protocol are safer -- they can't be as easily tricked by powerful attackers. A client which ''fully'' implements the protocol will always use the correct [[block chain]] and will never allow [[double-spending|double-spends]] or invalid transactions to exist in the block chain under any circumstances. Clients which only ''partially'' implement the protocol typically trust that 50% or more of the network's mining power is honest. Some clients trust one or more ''remote servers'' to protect them from double-spends and other network attacks.<br />
; Setup Time : Some clients require that you download and verify a large amount of data before you can send or receive BTC.<br />
; Maturity : When the project was started.<br />
<br />
===Table===<br />
<br />
<!-- please keep this alphabetic --><br />
{| class='wikitable' style='text-align: center'<br />
! Client !! Get Started !! Audience !! Wallet Security !! Network Security !! Backups !! Setup Time !! Disk Space !! Maturity !! Multi-user !! Available for<br />
|-<br />
! Armory<br />
|| [http://bitcoinarmory.com/index.php/get-armory Download] || Power users || {{CLGood|Encryption}} || Addon || {{CLBest|One-time}} || Varies || {{CLBad|2+ GB}} || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLWin}}<br />
|-<br />
! Bitcoin Wallet<br />
|| [https://play.google.com/store/apps/details?id=de.schildbach.wallet Download] || {{CLGood|End-users}} || {{CLGood|Isolated}} || Partial || Manual || 1 hour || 30 MB || Mar 2011 || No || {{CLAndroid}}<br />
|-<br />
! {{CLGood|Bitcoin-Qt}}<br />
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || {{CLGood|End-users}} || {{CLGood|Encryption}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|2+ GB}} || {{CLGood|May 2011}} || No || {{CLLinux}}{{CLMac}}{{CLWin}}<br />
|-<br />
! bitcoind<br />
|| [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || Programmers || {{CLGood|Encryption}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|2+ GB}} || {{CLBest|Aug 2009}} || {{CLGood|Virtual accounts}} || {{CLLinux}}{{CLWin}}<br />
|-<br />
! Electrum<br />
|| [http://ecdsa.org/electrum/ Download] || Power users || {{CLGood|Encryption}} || Minimal || {{CLBest|Memorized}} || {{CLGood|Minutes}} || {{CLGood|5 MB}} || Nov 2011 || No || {{CLLinux}}{{CLWin}}<br />
|-<br />
! MultiBit<br />
|| [http://multibit.org/releases.html Download] || {{CLGood|End-users}} || {{CLBad|None}} || Partial || {{CLBad|No}} || 1 hour || 50 MB || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLMac}}{{CLWin}}<br />
|-<br />
! My Wallet<br />
|| [https://blockchain.info/wallet/new eWallet] || {{CLBest|Everyone}} || {{CLGood|Encryption}} || {{CLBad|Remote}} || {{CLGood|Automatic}} || {{CLGood|Minutes}} || {{CLBest|None}} || Dec 2011 || {{CLBest|Yes}} || {{CLAndroid}}{{CLiOS}}{{CLLinux}}{{CLMac}}{{CLWin}}<br />
|}<br />
<br />
<!-- For Wallet Security: CLBest is reserved for multisig-based --><br />
<br />
==For developers==<br />
<br />
This table shows additional information about various Bitcoin clients that may be relevant to developers.<br />
<br />
{| class='wikitable' style='text-align: center'<br />
! Client !! Website !! Source Code !! License !! Discussion !! Architecture<br />
|-<br />
! Armory<br />
|| [http://bitcoinarmory.com/ Link] ||[https://github.com/etotheipi/BitcoinArmory/ Github] || AGPLv3 || [https://bitcointalk.org/index.php?topic=56424.0 Bitcointalk] || Integrated<br />
|-<br />
! Bitcoin Wallet<br />
|| [http://code.google.com/p/bitcoin-wallet/ Link] || [http://code.google.com/p/bitcoin-wallet/source/checkout Google Code] || GPLv3 || None / [https://groups.google.com/forum/?fromgroups#!forum/bitcoinj Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]<br />
|-<br />
! Bitcoin-Qt / bitcoind<br />
|| [http://bitcoin.org/ Link] || [https://github.com/bitcoin/bitcoin Github] || MIT || [https://lists.sourceforge.net/lists/listinfo/bitcoin-development Sourceforge] || Integrated<br />
|-<br />
! Electrum<br />
|| [http://ecdsa.org/electrum/ Link] || [https://gitorious.org/electrum Gitorious] || GPLv3 || [https://lists.sourceforge.net/lists/listinfo/electrum-discuss Sourceforge] || [[Thin Client Security#Server-Trusting Clients|Server-Client]]<br />
|-<br />
! MultiBit<br />
|| [http://multibit.org/ Link] || [https://github.com/jim618/multibit Github] || MIT || [https://groups.google.com/forum/?fromgroups#!forum/bitcoin-multibit Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]<br />
|-<br />
! My Wallet<br />
|| [https://blockchain.info/wallet/ Link] || [https://github.com/blockchain/My-Wallet/ Github] || BSD* || None || [[Thin Client Security#Server-Trusting Clients|Server-Client]]<br />
|}<br />
<br />
<references/></div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Clients&diff=29270Clients2012-08-02T09:54:29Z<p>Justmoon: Create first break-out table "For developers"; move License column to new table</p>
<hr />
<div>==Overview==<br />
<br />
This table compares the features of the different clients. All of the listed clients are open-source.<br />
<br />
===Feature key===<br />
<br />
; Wallet Security : How well the client protects your [[private key]]s from people with access to the machine the wallet is stored on. The private keys can be encrypted, for example.<br />
; Network Security : Clients which more fully implement the Bitcoin network protocol are safer -- they can't be as easily tricked by powerful attackers. A client which ''fully'' implements the protocol will always use the correct [[block chain]] and will never allow [[double-spending|double-spends]] or invalid transactions to exist in the block chain under any circumstances. Clients which only ''partially'' implement the protocol typically trust that 50% or more of the network's mining power is honest. Some clients trust one or more ''remote servers'' to protect them from double-spends and other network attacks.<br />
; Setup Time : Some clients require that you download and verify a large amount of data before you can send or receive BTC.<br />
; Maturity : When the project was started.<br />
<br />
===Table===<br />
<br />
<!-- please keep this alphabetic --><br />
{| class='wikitable' style='text-align: center'<br />
! Client !! Get Started !! Audience !! Wallet Security !! Network Security !! Backups !! Setup Time !! Disk Space !! Maturity !! Multi-user !! Available for<br />
|-<br />
! Armory || [http://bitcoinarmory.com/index.php/get-armory Download] || Power users || {{CLGood|Encryption}} || Addon || {{CLBest|One-time}} || Varies || {{CLBad|2+ GB}} || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLWin}}<br />
|-<br />
! Bitcoin Wallet || [https://play.google.com/store/apps/details?id=de.schildbach.wallet Download] || {{CLGood|End-users}} || {{CLGood|Isolated}} || Partial || Manual || 1 hour || 30 MB || Mar 2011 || No || {{CLAndroid}}<br />
|-<br />
! {{CLGood|Bitcoin-Qt}} || [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || {{CLGood|End-users}} || {{CLGood|Encryption}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|2+ GB}} || {{CLGood|May 2011}} || No || {{CLLinux}}{{CLMac}}{{CLWin}}<br />
|-<br />
! bitcoind || [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || Programmers || {{CLGood|Encryption}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|2+ GB}} || {{CLBest|Aug 2009}} || {{CLGood|Virtual accounts}} || {{CLLinux}}{{CLWin}}<br />
|-<br />
! Electrum || [http://ecdsa.org/electrum/ Download] || Power users || {{CLGood|Encryption}} || Minimal || {{CLBest|Memorized}} || {{CLGood|Minutes}} || {{CLGood|5 MB}} || Nov 2011 || No || {{CLLinux}}{{CLWin}}<br />
|-<br />
! MultiBit || [http://multibit.org/releases.html Download] || {{CLGood|End-users}} || {{CLBad|None}} || Partial || {{CLBad|No}} || 1 hour || 50 MB || Jul 2011 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLMac}}{{CLWin}}<br />
|-<br />
! My Wallet || [https://blockchain.info/wallet/new eWallet] || {{CLBest|Everyone}} || {{CLGood|Encryption}} || {{CLBad|Remote}} || {{CLGood|Automatic}} || {{CLGood|Minutes}} || {{CLBest|None}} || Dec 2011 || {{CLBest|Yes}} || {{CLAndroid}}{{CLiOS}}{{CLLinux}}{{CLMac}}{{CLWin}}<br />
|}<br />
<br />
<!-- For Wallet Security: CLBest is reserved for multisig-based --><br />
<br />
==For developers==<br />
<br />
This table shows additional information about various Bitcoin clients that may be relevant to developers.<br />
<br />
{| class='wikitable' style='text-align: center'<br />
! Client !! Website !! Source Code !! License !! Discussion !! Architecture<br />
|-<br />
! Armory || [http://bitcoinarmory.com/ Link] ||[https://github.com/etotheipi/BitcoinArmory/ Github] || AGPLv3 || [https://bitcointalk.org/index.php?topic=56424.0 Bitcointalk] || Integrated<br />
|-<br />
! Bitcoin Wallet || [http://code.google.com/p/bitcoin-wallet/ Link] || [http://code.google.com/p/bitcoin-wallet/source/checkout Google Code] || GPLv3 || None / [https://groups.google.com/forum/?fromgroups#!forum/bitcoinj Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]<br />
|-<br />
! Bitcoin-Qt / bitcoind || [http://bitcoin.org/ Link] || [https://github.com/bitcoin/bitcoin Github] || MIT || [https://lists.sourceforge.net/lists/listinfo/bitcoin-development Sourceforge] || Integrated<br />
|-<br />
! Electrum || [http://ecdsa.org/electrum/ Link] || [https://gitorious.org/electrum Gitorious] || GPLv3 || [https://lists.sourceforge.net/lists/listinfo/electrum-discuss Sourceforge] || [[Thin Client Security#Server-Trusting Clients|Server-Client]]<br />
|-<br />
! MultiBit || [http://multibit.org/ Link] || [https://github.com/jim618/multibit Github] || MIT || [https://groups.google.com/forum/?fromgroups#!forum/bitcoin-multibit Google Groups] || [[Thin Client Security#Simplified Payment Verification (SPV)|SPV]]<br />
|-<br />
! My Wallet || [https://blockchain.info/wallet/ Link] || [https://github.com/blockchain/My-Wallet/ Github] || BSD* || None || [[Thin Client Security#Server-Trusting Clients|Server-Client]]<br />
|}<br />
<br />
<references/></div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Talk:Clients&diff=29267Talk:Clients2012-08-02T09:19:52Z<p>Justmoon: /* Orientation */</p>
<hr />
<div>What is "Isolated" wallet security? Is this some Android thing? --[[User:Luke-jr|Luke-jr]] ([[User talk:Luke-jr|talk]]) 00:15, 10 July 2012 (GMT)<br />
<br />
== Orientation ==<br />
<br />
Eventually there will be too many clients and the table will be too wide, so I recommend having clients on the left and features on the top. If there are too many features, break it up into multiple tables. This is how Wikipedia usually does "Comparison of ''x''" articles. [[User:Theymos|theymos]] ([[User talk:Theymos|talk]]) 00:30, 10 July 2012 (GMT)<br />
<br />
:I went ahead and did this, looks much better imho and I agree re: putting additional criteria in extra tables. --[[User:Justmoon|Justmoon]] ([[User talk:Justmoon|talk]]) 09:19, 2 August 2012 (GMT)<br />
<br />
== Ordering ==<br />
<br />
I don't like using alphabetization here because it can be easily gamed. How about ordering by popularity using user-agent stats, and resolving ties using maturity? [[User:Theymos|theymos]] ([[User talk:Theymos|talk]]) 02:05, 10 July 2012 (GMT)<br />
<br />
:I suggested this on the mailing list, but everyone else who commented preferred alphabetical ordering. Wikipedia also seems to be using alphabetical order for such lists. I think it makes sense to the extent that user statistics will likely be hard to collect and hard to compare. I think this will only get more difficult as clients get more diverse, forming subnetworks etc. --[[User:Justmoon|Justmoon]] ([[User talk:Justmoon|talk]]) 07:44, 2 August 2012 (GMT)</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Clients&diff=29266Clients2012-08-02T09:18:52Z<p>Justmoon: Transposed table switching rows and columns, see talk page "Orientation".</p>
<hr />
<div>This table compares the features of the different clients.<br />
<br />
===Feature key===<br />
<br />
; Wallet Security : How well the client protects your [[private key]]s from people with access to the machine the wallet is stored on. The private keys can be encrypted, for example.<br />
; Network Security : Clients which more fully implement the Bitcoin network protocol are safer -- they can't be as easily tricked by powerful attackers. A client which ''fully'' implements the protocol will always use the correct [[block chain]] and will never allow [[double-spending|double-spends]] or invalid transactions to exist in the block chain under any circumstances. Clients which only ''partially'' implement the protocol typically trust that 50% or more of the network's mining power is honest. Some clients trust one or more ''remote servers'' to protect them from double-spends and other network attacks.<br />
; Setup Time : Some clients require that you download and verify a large amount of data before you can send or receive BTC.<br />
; Maturity : When the project was started.<br />
<br />
===Table===<br />
<br />
<!-- please keep this alphabetic --><br />
{| class='wikitable' style='text-align: center'<br />
! Client !! Get Started !! Audience !! Wallet Security !! Network Security !! Backups !! Setup Time !! Disk Space !! Maturity !! License !! Multi-user !! Available for<br />
|-<br />
! Armory || [http://bitcoinarmory.com/index.php/get-armory Download] || Power users || {{CLGood|Encryption}} || Addon || {{CLBest|One-time}} || Varies || {{CLBad|2+ GB}} || Jul 2011 || AGPLv3 || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLWin}}<br />
|-<br />
! Bitcoin Wallet || [https://play.google.com/store/apps/details?id=de.schildbach.wallet Download] || {{CLGood|End-users}} || {{CLGood|Isolated}} || Partial || Manual || 1 hour || 30 MB || Mar 2011 || GPLv3 || No || {{CLAndroid}}<br />
|-<br />
! {{CLGood|Bitcoin-Qt}} || [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || {{CLGood|End-users}} || {{CLGood|Encryption}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|2+ GB}} || {{CLGood|May 2011}} || MIT || No || {{CLLinux}}{{CLMac}}{{CLWin}}<br />
|-<br />
! bitcoind || [http://sourceforge.net/projects/bitcoin/files/Bitcoin/ Download] || Programmers || {{CLGood|Encryption}} || {{CLBest|Full}} || Manual || {{CLBad|Hours}} || {{CLBad|2+ GB}} || {{CLBest|Aug 2009}} || MIT || {{CLGood|Virtual accounts}} || {{CLLinux}}{{CLWin}}<br />
|-<br />
! Electrum || [http://ecdsa.org/electrum/ Download] || Power users || {{CLGood|Encryption}} || Minimal || {{CLBest|Memorized}} || {{CLGood|Minutes}} || {{CLGood|5 MB}} || Nov 2011 || GPLv3 || No || {{CLLinux}}{{CLWin}}<br />
|-<br />
! MultiBit || [http://multibit.org/releases.html Download] || {{CLGood|End-users}} || {{CLBad|None}} || Partial || {{CLBad|No}} || 1 hour || 50 MB || Jul 2011 || MIT || {{CLBest|Multi-wallet}} || {{CLLinux}}{{CLMac}}{{CLWin}}<br />
|-<br />
! My Wallet || [https://blockchain.info/wallet/new eWallet] || {{CLBest|Everyone}} || {{CLGood|Encryption}} || {{CLBad|Remote}} || {{CLGood|Automatic}} || {{CLGood|Minutes}} || {{CLBest|None}} || Dec 2011 || BSD* || {{CLBest|Yes}} || {{CLAndroid}}{{CLiOS}}{{CLLinux}}{{CLMac}}{{CLWin}}<br />
|}<br />
<br />
<!-- For Wallet Security: CLBest is reserved for multisig-based --><br />
<br />
<references/></div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Talk:Clients&diff=29264Talk:Clients2012-08-02T07:44:37Z<p>Justmoon: /* Ordering */</p>
<hr />
<div>What is "Isolated" wallet security? Is this some Android thing? --[[User:Luke-jr|Luke-jr]] ([[User talk:Luke-jr|talk]]) 00:15, 10 July 2012 (GMT)<br />
<br />
== Orientation ==<br />
<br />
Eventually there will be too many clients and the table will be too wide, so I recommend having clients on the left and features on the top. If there are too many features, break it up into multiple tables. This is how Wikipedia usually does "Comparison of ''x''" articles. [[User:Theymos|theymos]] ([[User talk:Theymos|talk]]) 00:30, 10 July 2012 (GMT)<br />
<br />
== Ordering ==<br />
<br />
I don't like using alphabetization here because it can be easily gamed. How about ordering by popularity using user-agent stats, and resolving ties using maturity? [[User:Theymos|theymos]] ([[User talk:Theymos|talk]]) 02:05, 10 July 2012 (GMT)<br />
<br />
:I suggested this on the mailing list, but everyone else who commented preferred alphabetical ordering. Wikipedia also seems to be using alphabetical order for such lists. I think it makes sense to the extent that user statistics will likely be hard to collect and hard to compare. I think this will only get more difficult as clients get more diverse, forming subnetworks etc. --[[User:Justmoon|Justmoon]] ([[User talk:Justmoon|talk]]) 07:44, 2 August 2012 (GMT)</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Meetups&diff=24437Meetups2012-03-04T13:29:09Z<p>Justmoon: Updated Swiss meetup information and added link to mailing list</p>
<hr />
<div>Don't add everyone who's going in the "Who?" column, just prominent Bitcoin members and organizers. Also see [http://bitcoin.meetup.com bitcoin.meetup.com]<br />
<br />
{| class="wikitable"<br />
|-<br />
! Group<br />
! When?<br />
! Where?<br />
! Who?<br />
! Other Notes<br />
|-<br />
| [http://metalab.at/wiki/Bitcoins Vienna, Austria]<br />
| monthly - check the [http://metalab.at/wiki/Bitcoins wiki] or subscribe to the [http://lists.keisanki.net/listinfo/bitcoin mailinglist]<br />
| [http://metalab.at/wiki/Lage Metalab], Vienna hacker space, Rathausstraße 6, 1010 Wien<br />
| Bitcoin Group Austria <br />
| <br />
|-<br />
| [http://brmlab.cz brmlab, prague hackerspace]<br />
| 14th Nov 2011<br />
28th Nov 2011<br />
([http://brmlab.cz/event/bitcoin_seminar])<br />
| [http://brmlab.cz/place Brmlab, Bubenska 1]<br />
| brmlab crew, slush, genjix<br />
| <br />
|-<br />
| [http://www.facebook.com/groups/175596065827848/ Bitcoin Boston]<br />
| Bi-weekly on Saturday or Sunday ([http://www.facebook.com/groups/175596065827848/ See Facebook page])<br />
| Starbucks, Harvard Square<br />
| Anyone who wants to come!<br />
| So far our meetings have been pretty sporadic, but we hope to gain some regularity soon...<br />
|-<br />
| [http://www.meetup.com/bitcoin New York Bitcoin Users]<br />
| 6:00 PM, 3rd Sunday of every month ([http://www.meetup.com/bitcoin/events/past past meetings])<br />
| OnlyOneTV Studios - 290 Fifth Ave New York, NY<br />
| Bruce Wagner (Organizer) and others<br />
| <br />
|-<br />
|-<br />
| [http://www.meetup.com/bitcoin New York Bitcoin Users]<br />
| 6:00 PM, every Wednesday of every month ([http://www.meetup.com/bitcoin/events/past past meetings])<br />
| Just Sweet Dessert House - 83 Third Ave New York, NY<br />
| Yifu Guo (Organizer) and crew<br />
| hosted by Bitsyncom, the people behind [[Bitnavigator]], walk-ins welcome;<br />
|-<br />
| [http://www.meetup.com/PhillyBitcoin Philadelphia Bitcoin User Group]<br />
| TBD<br />
| TBD<br />
| Brian Cohen (Organizer) and others<br />
|<br />
|-<br />
| [http://www.meetup.com/BitcoinDC Washington, DC Bitcoin Users]<br />
| 7:00 PM, 1st Monday of every month ([http://www.meetup.com/BitcoinDC/#past past meetings])<br />
| Northside Social, 3211 Wilson Blvd Arlington, VA<br />
| [[User:Dduane|Darrell Duane]] (Organizer) and others<br />
|<br />
|-<br />
| [http://www.meetup.com/Silicon-Valley-Bitcoin-Users Silicon Valley Bitcoin Users]<br />
| 7:00 PM, Tuesday, June 14, 2011 ([http://www.meetup.com/Silicon-Valley-Bitcoin-Users/events/past past meetings])<br />
| 140B S Whisman Road Mountain View, CA <br />
| Brian Mcqueen and others<br />
|<br />
|-<br />
| [http://www.meetup.com/BitcoinChicago Chicago]<br />
| No regular schedule yet ([http://www.meetup.com/BitcoinChicago/events/past past meetings])<br />
| Sunnyvale Art Gallery Cafe, 251 W El Camino Real Sunnyvale, CA<br />
| Igor<br />
|<br />
|-<br />
| [http://www.meetup.com/denver-bitcoin Denver]<br />
| First meeting June 4th, 2011 ([http://www.meetup.com/denver-bitcoin/events/past past meetings])<br />
| Gypsy House Cafe - 1279 Marion St Denver, CO<br />
| bearbones<br />
|<br />
|-<br />
| [http://www.meetup.com/bitcoinSF Bitcoin SF]<br />
| Saturday, June 4, 2011 ([http://www.meetup.com/bitcoinSF past meetings])<br />
| SFSU - 1600 Holloway Ave. San Francisco, CA<br />
| Brian Mcqueen and others<br />
|<br />
|-<br />
| [http://www.meetup.com/Los-Angeles-Digital-Currency-Innovators-Group Los Angeles Digital Currency Innovators]<br />
| Thursday July 7th, 2011, 7 PM<br />
| (mt)/Media Temple, Culver City, CA<br />
| [[User:sgornick|Stephen Gornick]] (Interim organizer) and others<br />
| Seeking meetup coordinator<br />
|-<br />
| [http://www.meetup.com/Las-Vegas-Bitcoin-Users Las Vegas Bitcoin Users]<br />
| Monthly, check calendar ([http://www.meetup.com/Las-Vegas-Bitcoin-Users/#upcomming meetings])<br />
| Putters, 6945 South Rainbow Boulevard, Las Vegas, NV<br />
| Mark Russell, Julian Tosh<br />
|<br />
|-<br />
| [http://www.meetup.com/Bitcoin-Twin-Cities-Users-Meetup Bitcoin Twin Cities Users]<br />
| Friday, June 10, 2011, 6:30 PM<br />
| Joule - 1200 Washington Ave S Minneapolis, MN<br />
| Mac Manson<br />
|<br />
|-<br />
| [http://www.meetup.com/Portland-Bitcoin-Meetup-Users Portland Bitcoin Users Meetup Group]<br />
| forming<br />
| <br />
| Steven Wagner<br />
|<br />
|-<br />
| [http://www.meetup.com/Bitcoin-Orlando Bitcoin Orlando]<br />
| ([http://www.meetup.com/Bitcoin-Orlando#past past meetings])<br />
| Frank & Steins 150 S. Magnolia Ave, Orlando, FL<br />
| Antonio Gallippi<br />
|<br />
|-<br />
| [http://www.hive13.org/?p=310 Hive13 Hackerspace]<br />
| Bitcoin Exchange, Every Tuesday, 7:30 PM<br />
| Hive13 - 2929 Spring Grove Avenue, Cincinnati, OH<br />
| <br />
|<br />
|-<br />
| [[Melbourne Bitcoin Community]]<br />
| Forming<br />
| Suggest a location, and a date and time<br />
| @da2ce7 on Freenode Channel: #bitcoin-aus<br />
|<br />
|-<br />
| [[Bitcoin:Tokyo meetup|Tokyo]]<br />
| <br />
| <br />
| [[User:MagicalTux|Magical Tux]] (Organizer) and others<br />
|<br />
|-<br />
| [http://meetup.com/Bitcoin-Canada Vancouver Canada]<br />
| ([http://www.meetup.com/Bitcoin-Canada/#past past meetings])<br />
| The Brickhouse - 730 Main St.<br />
| humble (and others)<br />
|<br />
|-<br />
| [https://groups.google.com/d/forum/bitcoin-switzerland Zurich/Geneva Switzerland]<br />
| Semi-regular, about once a month<br />
| Oliver Twist Pub, Zurich; Lord Nelson Pub, Geneva<br />
| Stefan Thomas (WeUseCoins), Mike Hearn (BitcoinJ), bitdragon, Luzius (Wuala), more ... <br />
|<br />
|-<br />
| Seattle Bitcoin Meetup<br />
| [http://www.meetup.com/SeattleBitCoin/ Semi-regularly].<br />
| [http://maps.google.com/maps?q=cafe+solstice&daddr=4116+University+Way,+Seattle,+WA+98105-6214&hl=en&ll=47.657424,-122.31313&spn=0.007328,0.01929&gl=us&view=map&geocode=CRT9Bdg7zX3vFdcx1wIdWqa1-CFcJ9qrr9CcEQ&t=h&z=16 Solstice Cafe, 2pm]<br />
| [https://bitcointalk.org/index.php?action=profile;u=36217 indolering]<br />
|<br />
|-<br />
| [https://bitcointalk.org/index.php?topic=42262.0 Munich Germany]<br />
| Semi-regular, about once a month<br />
| Optimolwerke<br />
|<br />
|<br />
|-<br />
| [http://www.meetup.com/bitcoin-il/ Israel Bitcoin Meetup Group]<br />
| Occasional<br />
| TBD<br />
| Meni Rosenfeld<br />
|<br />
|-<br />
|}<br />
<br />
==See Also==<br />
<br />
* [http://hackerspaces.org/wiki/List_of_Hacker_Spaces List of Hacker Spaces]<br />
<br />
[[Category:Local]]<br />
<br />
[[de:Treffen]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/IMTUO&diff=23411User:Justmoon/IMTUO2012-02-05T14:30:04Z<p>Justmoon: Recent block headers are enough - thanks to cjd from #bitcoin-dev.</p>
<hr />
<div>== Prior Work ==<br />
<br />
This proposal is an extension of [https://bitcointalk.org/index.php?topic=21995.0 Greg Maxwell's proposal] of storing a merkle tree root of unspent transactions in a coinbase.<br />
<br />
The name is based on Alberto Torres' write-up called MTUT, more precisely Elden Tyrell's comment that MTUO is more correct.<br />
<br />
== Overview ==<br />
<br />
We propose a protocol and algorithms for a new type of Bitcoin node which uses a so-called Incremental Merkle Tree of Unspent Outputs (IMTUO).<br />
<br />
IMTUO nodes do not store old transactions at all (neither inputs nor outputs nor hashes), yet they can fully verify transactions, create new blocks including updating the IMTUO root and bootstrap each other. IMTUO nodes can function completely independently of full nodes, however we expect full nodes to survive for archival purposes and to provides indices.<br />
<br />
The proposal aims to solve two main problems:<br />
<br />
* Reduce Bitcoin's long-term storage requirements<br />
* Remove the need for a MAX_BLOCK_SIZE through better intrinsic incentives<br />
<br />
The proposal does not require any change to the block chain except for the addition of the IMTUO root hash as part of the coinbase. For more information on backwards compatibility and interoperability see the section Deployment.<br />
<br />
== Verification Information ==<br />
<br />
The basic difference to the classic Bitcoin network is that in an IMTUO Bitcoin network, the burden is on the publisher/relayer of a transaction to prove its validity - rather than on the verifier to look it up.<br />
<br />
In order to do that, the publisher creates a piece of data for each output - the so-called verification information or vinfo.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1 || merkle branch length || uint8_t || The number of entries in the merkle branch<br />
|-<br />
| 20+ || merkle branch || char[20] || Merkle hashes that form the heads of the side branches between the leaf and root nodes<br />
|-<br />
|? || merkle branch direction || uchar[] || Bitfield indicating where the side branches attach (0 - prefix; 1 - suffix); length is ceil(merkle branch length / 8)<br />
|-<br />
| 1+ || pubkey script length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the scriptPubKey<br />
|-<br />
|? || pubkey script || uchar[] || The script from the output that is being spent (the length is implied by the header length)<br />
|-<br />
| 8 || value || uint64_t || Output value, i.e. amount in Bitcoins<br />
|}<br />
<br />
If the transaction being spent is contained in a recent block, the vinfo is not needed and can be provided as a 0x00 byte. This is called a "null vinfo".<br />
<br />
If the output is a standard P2SH output, the script length is given as 0 and the script deduced from the input.<br />
<br />
The reason we include the script and the value is so that we can verify that those are correct, purely based on confirming that this hash is indeed an unspent output. The reason we include the outpoint structure is to ensure the resulting hash is globally unique and we use the outpoint for this because the outpoint is already available to us in the spending input.<br />
<br />
=== Transaction Transmission ===<br />
<br />
Transactions are always sent with their vinfo included.<br />
<br />
The vinfo can expire if the MTUO root it connects to moves out of the recent block list or - for null vinfos - if the transation it spends moves out of the recent blocks list. In that case the creator of the transaction or anyone with a vested interest in getting it included can choose to rebroadcast the transaction with an updated vinfo.<br />
<br />
=== Block Transmission ===<br />
<br />
Currently, Bitcoin sends all transactions again when a block is transmitted, even though the receiving node may know most of them already. We propose that blocks be transmitted including a list of transaction hashes and missing transactions be requested as needed.<br />
<br />
== MTUO ==<br />
<br />
The merkle tree used for this proposal consists of unspent outputs, the leafs of this tree are the hashes as per the following format:<br />
<br />
RIPEMD160( SHA256( [outpoint] [pubkey script] [value] ) )<br />
<br />
The specific data to be hashed is:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || outpoint || char[36] || The OutPoint structure pointing to this output in the block chain<br />
|-<br />
|? || pubkey script || uchar[] || The script from the output that is being spent (the length is implied by the header length)<br />
|-<br />
| 8 || value || uint64_t || Output value, i.e. amount in Bitcoins<br />
|}<br />
<br />
== Client Storage Requirements ==<br />
<br />
A full client stores:<br />
<br />
* Block headers<br />
* Coinbases<br />
* Merkle branch connecting coinbase tx to merkle root<br />
* Recent blocks (full blocks including vinfo)<br />
<br />
A lightweight client stores:<br />
<br />
* Recent block headers<br />
* Recent MTUO roots<br />
<br />
There should be a network-wide lower bound for what is considered "recent" that all nodes should agree on. This lower bound is called RECENT_BLOCK_INTERVAL and is chosen by the following criteria:<br />
<br />
* Chance of a reorganization beyond that point is negligible<br />
* Leaves enough blocks to initialize the IMTUO insertion spots cache (see section Incremental MTUO - Insertion)<br />
* Leaves enough blocks to trust the oldest MTUO root in the history without being able to verify it<br />
* Large enough that transactions' vinfos don't expire too quickly<br />
* Small enough that clients don't have to store too much data<br />
<br />
For the purposes of this proposal we will assume that RECENT_BLOCK_INTERVAL is chosen to be 1024.<br />
<br />
== Transaction Verification ==<br />
<br />
To verify an input, we follow this algorithm:<br />
<br />
# Calculate the hash of the vinfo header.<br />
# Using the result from 1. and the merkle branch provided in the vinfo, calculate the merkle root.<br />
# Reject if merkle root does not match any MTUO root in the recent blocks history<br />
# If it matched a MTUO root other than the current one, translate branch forward and test against latest MTUO root<br />
# (We now know that the previous output exists and is unspent.)<br />
# Verify script<br />
<br />
Other checks such as confirming the transaction hash, DoS checks, etc. work the same on a IMTUO node as they do on a classic node.<br />
<br />
== Protocol Changes ==<br />
<br />
IMTUO entails adding two commands to the Bitcoin protocol:<br />
<br />
# txvinfo: Requests a transaction including its verification information; also works for transactions in blocks<br />
# blocktxlist: Requests a block including the list of transaction hashes<br />
<br />
// TODO: Specify exactly the new message format<br />
<br />
== Incremental MTUO ==<br />
<br />
Rather than being regenerated by a node possessing the full blockchain, we propose the tree be incrementally updated by any miner knowing only the new transactions he wishes to include and their corresponding verification information.<br />
<br />
Consider the following merkle tree:<br />
<br />
A B C D E F G H<br />
\ / \ / \ / \ /<br />
AB CD EF GH<br />
\ / \ /<br />
ABCD EFGH<br />
\ /<br />
ABCDEFGH<br />
<br />
=== Deletion ===<br />
<br />
We want to remove the hash C from the merkle tree and calculate the new root using only the merkle branch verification information.<br />
<br />
First consider the verification information for C:<br />
<br />
C ---> CD ---> ABCD ---> ABCDEFGH <br />
/ / / <br />
D AB EFGH <br />
<br />
<br />
It's easy to see that with C removed this can be recalculated as:<br />
<br />
-> D ---> ABD ---> ABDEFGH <br />
/ / / <br />
D AB EFGH<br />
<br />
<br />
We will use the following notation to illustrate this removal:<br />
<br />
C ---> CD ---> ABCD ---> ABCDEFGH C -> 0 <br />
/ / / CD -> D <br />
D AB EFGH ABCD -> ABD <br />
<br />
D ABD ABDEFGH <br />
<br />
The table on the right is called the translation table. As we make more changes to the merkle tree we have to replace any occurrence of one of the hashes on the left hand side of the table with the corresponding value on the right hand side.<br />
<br />
So if we now wanted to remove B we would do similarly:<br />
<br />
B ---> AB ---> ABCD ---> ABCDEFGH B -> 0<br />
/ / / AB -> A<br />
A (CD) EFGH ABCD -> AD<br />
D <br />
<br />
A AD ACHEFGH<br />
<br />
Note that we had to replace the side branch CD with D as per our translation table.<br />
<br />
Here is another example, now we also remove E:<br />
<br />
E ---> EF ---> EFGH ---> ABCDEFGH E -> 0<br />
/ / / EF -> F<br />
F GH (ABCD) EFGH -> FGH<br />
AD <br />
<br />
F FGH ADFGH <br />
<br />
<br />
=== Insertion ===<br />
<br />
To insert, we can recycle one of the vinfo packets and simply reconnect the new hash at a location where another hash was previously removed.<br />
<br />
For example, to add a new hash I, we could use the branch information of the removed hash B and simply apply it to I instead:<br />
<br />
I ---> AI ---> AICD ---> AICDEFGH B -> I<br />
/ / / AB -> AI<br />
A (CD) (EFGH) ABCD -> AID<br />
D FGH <br />
<br />
AI AID AIDFGH<br />
<br />
We can add another transaction J the same way, be reusing the branch information for the previously removed hash E:<br />
<br />
J ---> JF ---> JFGH ---> ABCDJFGH E -> J<br />
/ / / EF -> JF<br />
F GH (ABCD) EFGH -> JFGH<br />
AID<br />
<br />
JF JFGH AIDJFGH<br />
<br />
If we have replaced all the removed hashes with new ones and we still need to add more, we can create new branches in place of any existing hash. For example to add yet another transaction to the branch currently occupied by J, we once again employ E's original branch information:<br />
<br />
K ---> EK ---> EKF ---> EKFGH ---> ABCDEFKGH E -> JK<br />
/ / / / EF -> JKF<br />
(E) F GH (ABCD) EFGH -> JKFGH<br />
J AID<br />
<br />
JK JKF JKFGH AIDJKFGH<br />
<br />
Based on our translation table, we know that E is now J and ABCD is now AID which leads us to calculate the correct final merkle root AIDJKFGH.<br />
<br />
=== Balancing the tree ===<br />
<br />
Each client keeps a cache of the lowest-degree insertion and removal points it has seen. For any new insertion it selects the oldest, lowest degree point available. This way the tree will balance itself over time.<br />
<br />
Clients will also reject insertion points that are too far above the best known insertion point. This means that even a malicious attacker will never be able to arbitrarily unbalance the tree. As soon as the tree starts to be unbalanced, block containing badly chosen insertion points will start to be rejected.<br />
<br />
Honest miner will never be affected by this because they learn their insertion points from the same data (recent blocks) of which the limits are calculated, so they will always have numerous insertion points available below the limit.<br />
<br />
If knowledge of a good insertion point is somehow lost it only needs to be references once by any miner and it will immediately be picked up by the miners following and any short branch in the tree will tend to be immediately filled up. However given that in any 1024 block interval there are likely to be at least a few blocks made by honest miners it is unlikely that good insertion points will ever be forgotten to begin with.<br />
<br />
== Wallets ==<br />
<br />
One of the main differences between a IMTUO node and a classic node is that a classic node has access to the full block chain archive and can rescan it to find outputs that match a specific public key for example.<br />
<br />
An IMTUO node can only scan the recent blocks. Also, if it is offline for more than 1024 blocks it will be unable to update its wallet on its own.<br />
<br />
However, indexing and storing large amounts of data for querying is a well understood and solved problem. It is easy to imagine a DHT that can be queried by public key hash or script hash to retrieve transaction and that is kept up-to-date by Bitcoin clients. Merely storing and indexing the information for occasional querying is not a difficult problem. This proposal however addresses the more difficult issue that verifying nodes need a full list of unspent outputs.<br />
<br />
== Resource Usage ==<br />
<br />
IMTUO is a storage/network tradeoff. We save most of the storage in exchange for increased network usage.<br />
<br />
=== Changed Incentives ===<br />
<br />
There is currently no way within the Bitcoin protocol to make a rogue miner liable for the costs he incurs for other miners by publishing a very large block. In order to mitigate this problem Bitcoin currently uses a hard-coded maximum block size limit MAX_BLOCK_SIZE.<br />
<br />
In an IMTUO network, the storage costs are negligible, since blocks are only stored temporarily. Instead, the network transmission costs are increased. Any miner is interested in getting its newly created block spread across the network so that other miners will build on it. Large blocks will spread more slowly and are therefore disadvantaged. IMTUO adds verification information and therefore increases this effect<br />
<br />
To create a block a miner will always have a certain cost to create the proof-of-work. The risk that a too large block will not ultimately make it into the chain is a natural incentive for miners to stay within reasonable limits.<br />
<br />
If desired, this can be exacerbated further by adding protocol rules that cause blocks not to be relayed and/or built upon unless a certain spread has been reached. This would but the burden on the creator to spread his (unusually large) block and/or pay other nodes to relay it.<br />
<br />
== Deployment ==<br />
<br />
IMTUO is a separate network from Bitcoin. Gateways have to run both a regular Bitcoin full node and store a full indexed copy of the IMTUO merkle tree (a 10-50% overhead over running a normal full node.)<br />
<br />
// TODO: How to handle the IMTUO root while IMTUO have a minority of mining power.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=User:Justmoon/IMTUO&diff=23408User:Justmoon/IMTUO2012-02-05T14:16:22Z<p>Justmoon: Initial draft</p>
<hr />
<div><br />
== Prior Work ==<br />
<br />
This proposal is an extension of [https://bitcointalk.org/index.php?topic=21995.0 Greg Maxwell's proposal] of storing a merkle tree root of unspent transactions in a coinbase.<br />
<br />
The name is based on Alberto Torres' write-up called MTUT, more precisely Elden Tyrell's comment that MTUO is more correct.<br />
<br />
== Overview ==<br />
<br />
We propose a protocol and algorithms for a new type of Bitcoin node which uses a so-called Incremental Merkle Tree of Unspent Outputs (IMTUO).<br />
<br />
IMTUO nodes do not store old transactions at all (neither inputs nor outputs nor hashes), yet they can fully verify transactions, create new blocks including updating the IMTUO root and bootstrap each other. IMTUO nodes can function completely independently of full nodes, however we expect full nodes to survive for archival purposes and to provides indices.<br />
<br />
The proposal aims to solve two main problems:<br />
<br />
* Reduce Bitcoin's long-term storage requirements<br />
* Remove the need for a MAX_BLOCK_SIZE through better intrinsic incentives<br />
<br />
The proposal does not require any change to the block chain except for the addition of the IMTUO root hash as part of the coinbase. For more information on backwards compatibility and interoperability see the section Deployment.<br />
<br />
== Verification Information ==<br />
<br />
The basic difference to the classic Bitcoin network is that in an IMTUO Bitcoin network, the burden is on the publisher/relayer of a transaction to prove its validity - rather than on the verifier to look it up.<br />
<br />
In order to do that, the publisher creates a piece of data for each output - the so-called verification information or vinfo.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1 || merkle branch length || uint8_t || The number of entries in the merkle branch<br />
|-<br />
| 20+ || merkle branch || char[20] || Merkle hashes that form the heads of the side branches between the leaf and root nodes<br />
|-<br />
|? || merkle branch direction || uchar[] || Bitfield indicating where the side branches attach (0 - prefix; 1 - suffix); length is ceil(merkle branch length / 8)<br />
|-<br />
| 1+ || pubkey script length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the scriptPubKey<br />
|-<br />
|? || pubkey script || uchar[] || The script from the output that is being spent (the length is implied by the header length)<br />
|-<br />
| 8 || value || uint64_t || Output value, i.e. amount in Bitcoins<br />
|}<br />
<br />
If the transaction being spent is contained in a recent block, the vinfo is not needed and can be provided as a 0x00 byte. This is called a "null vinfo".<br />
<br />
If the output is a standard P2SH output, the script length is given as 0 and the script deduced from the input.<br />
<br />
The reason we include the script and the value is so that we can verify that those are correct, purely based on confirming that this hash is indeed an unspent output. The reason we include the outpoint structure is to ensure the resulting hash is globally unique and we use the outpoint for this because the outpoint is already available to us in the spending input.<br />
<br />
=== Transaction Transmission ===<br />
<br />
Transactions are always sent with their vinfo included.<br />
<br />
The vinfo can expire if the MTUO root it connects to moves out of the recent block list or - for null vinfos - if the transation it spends moves out of the recent blocks list. In that case the creator of the transaction or anyone with a vested interest in getting it included can choose to rebroadcast the transaction with an updated vinfo.<br />
<br />
=== Block Transmission ===<br />
<br />
Currently, Bitcoin sends all transactions again when a block is transmitted, even though the receiving node may know most of them already. We propose that blocks be transmitted including a list of transaction hashes and missing transactions be requested as needed.<br />
<br />
== MTUO ==<br />
<br />
The merkle tree used for this proposal consists of unspent outputs, the leafs of this tree are the hashes as per the following format:<br />
<br />
RIPEMD160( SHA256( [outpoint] [pubkey script] [value] ) )<br />
<br />
The specific data to be hashed is:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || outpoint || char[36] || The OutPoint structure pointing to this output in the block chain<br />
|-<br />
|? || pubkey script || uchar[] || The script from the output that is being spent (the length is implied by the header length)<br />
|-<br />
| 8 || value || uint64_t || Output value, i.e. amount in Bitcoins<br />
|}<br />
<br />
== Client Storage Requirements ==<br />
<br />
A full client stores:<br />
<br />
* Block headers<br />
* Coinbases<br />
* Merkle branch connecting coinbase tx to merkle root<br />
* Recent blocks (full blocks including vinfo)<br />
<br />
A lightweight client stores:<br />
<br />
* Block headers<br />
* Recent MTUO roots<br />
<br />
There should be a network-wide lower bound for what is considered "recent" that all nodes should agree on. This lower bound is called RECENT_BLOCK_INTERVAL and is chosen by the following criteria:<br />
<br />
* Chance of a reorganization beyond that point is negligible<br />
* Leaves enough blocks to initialize the IMTUO insertion spots cache (see section Incremental MTUO - Insertion)<br />
* Leaves enough blocks to trust the oldest MTUO root in the history without being able to verify it<br />
* Large enough that transactions' vinfos don't expire too quickly<br />
* Small enough that clients don't have to store too much data<br />
<br />
For the purposes of this proposal we will assume that RECENT_BLOCK_INTERVAL is chosen to be 1024.<br />
<br />
== Transaction Verification ==<br />
<br />
To verify an input, we follow this algorithm:<br />
<br />
# Calculate the hash of the vinfo header.<br />
# Using the result from 1. and the merkle branch provided in the vinfo, calculate the merkle root.<br />
# Reject if merkle root does not match any MTUO root in the recent blocks history<br />
# If it matched a MTUO root other than the current one, translate branch forward and test against latest MTUO root<br />
# (We now know that the previous output exists and is unspent.)<br />
# Verify script<br />
<br />
Other checks such as confirming the transaction hash, DoS checks, etc. work the same on a IMTUO node as they do on a classic node.<br />
<br />
== Protocol Changes ==<br />
<br />
IMTUO entails adding two commands to the Bitcoin protocol:<br />
<br />
# txvinfo: Requests a transaction including its verification information; also works for transactions in blocks<br />
# blocktxlist: Requests a block including the list of transaction hashes<br />
<br />
// TODO: Specify exactly the new message format<br />
<br />
== Incremental MTUO ==<br />
<br />
Rather than being regenerated by a node possessing the full blockchain, we propose the tree be incrementally updated by any miner knowing only the new transactions he wishes to include and their corresponding verification information.<br />
<br />
Consider the following merkle tree:<br />
<br />
A B C D E F G H<br />
\ / \ / \ / \ /<br />
AB CD EF GH<br />
\ / \ /<br />
ABCD EFGH<br />
\ /<br />
ABCDEFGH<br />
<br />
=== Deletion ===<br />
<br />
We want to remove the hash C from the merkle tree and calculate the new root using only the merkle branch verification information.<br />
<br />
First consider the verification information for C:<br />
<br />
C ---> CD ---> ABCD ---> ABCDEFGH <br />
/ / / <br />
D AB EFGH <br />
<br />
<br />
It's easy to see that with C removed this can be recalculated as:<br />
<br />
-> D ---> ABD ---> ABDEFGH <br />
/ / / <br />
D AB EFGH<br />
<br />
<br />
We will use the following notation to illustrate this removal:<br />
<br />
C ---> CD ---> ABCD ---> ABCDEFGH C -> 0 <br />
/ / / CD -> D <br />
D AB EFGH ABCD -> ABD <br />
<br />
D ABD ABDEFGH <br />
<br />
The table on the right is called the translation table. As we make more changes to the merkle tree we have to replace any occurrence of one of the hashes on the left hand side of the table with the corresponding value on the right hand side.<br />
<br />
So if we now wanted to remove B we would do similarly:<br />
<br />
B ---> AB ---> ABCD ---> ABCDEFGH B -> 0<br />
/ / / AB -> A<br />
A (CD) EFGH ABCD -> AD<br />
D <br />
<br />
A AD ACHEFGH<br />
<br />
Note that we had to replace the side branch CD with D as per our translation table.<br />
<br />
Here is another example, now we also remove E:<br />
<br />
E ---> EF ---> EFGH ---> ABCDEFGH E -> 0<br />
/ / / EF -> F<br />
F GH (ABCD) EFGH -> FGH<br />
AD <br />
<br />
F FGH ADFGH <br />
<br />
<br />
=== Insertion ===<br />
<br />
To insert, we can recycle one of the vinfo packets and simply reconnect the new hash at a location where another hash was previously removed.<br />
<br />
For example, to add a new hash I, we could use the branch information of the removed hash B and simply apply it to I instead:<br />
<br />
I ---> AI ---> AICD ---> AICDEFGH B -> I<br />
/ / / AB -> AI<br />
A (CD) (EFGH) ABCD -> AID<br />
D FGH <br />
<br />
AI AID AIDFGH<br />
<br />
We can add another transaction J the same way, be reusing the branch information for the previously removed hash E:<br />
<br />
J ---> JF ---> JFGH ---> ABCDJFGH E -> J<br />
/ / / EF -> JF<br />
F GH (ABCD) EFGH -> JFGH<br />
AID<br />
<br />
JF JFGH AIDJFGH<br />
<br />
If we have replaced all the removed hashes with new ones and we still need to add more, we can create new branches in place of any existing hash. For example to add yet another transaction to the branch currently occupied by J, we once again employ E's original branch information:<br />
<br />
K ---> EK ---> EKF ---> EKFGH ---> ABCDEFKGH E -> JK<br />
/ / / / EF -> JKF<br />
(E) F GH (ABCD) EFGH -> JKFGH<br />
J AID<br />
<br />
JK JKF JKFGH AIDJKFGH<br />
<br />
Based on our translation table, we know that E is now J and ABCD is now AID which leads us to calculate the correct final merkle root AIDJKFGH.<br />
<br />
=== Balancing the tree ===<br />
<br />
Each client keeps a cache of the lowest-degree insertion and removal points it has seen. For any new insertion it selects the oldest, lowest degree point available. This way the tree will balance itself over time.<br />
<br />
Clients will also reject insertion points that are too far above the best known insertion point. This means that even a malicious attacker will never be able to arbitrarily unbalance the tree. As soon as the tree starts to be unbalanced, block containing badly chosen insertion points will start to be rejected.<br />
<br />
Honest miner will never be affected by this because they learn their insertion points from the same data (recent blocks) of which the limits are calculated, so they will always have numerous insertion points available below the limit.<br />
<br />
If knowledge of a good insertion point is somehow lost it only needs to be references once by any miner and it will immediately be picked up by the miners following and any short branch in the tree will tend to be immediately filled up. However given that in any 1024 block interval there are likely to be at least a few blocks made by honest miners it is unlikely that good insertion points will ever be forgotten to begin with.<br />
<br />
== Wallets ==<br />
<br />
One of the main differences between a IMTUO node and a classic node is that a classic node has access to the full block chain archive and can rescan it to find outputs that match a specific public key for example.<br />
<br />
An IMTUO node can only scan the recent blocks. Also, if it is offline for more than 1024 blocks it will be unable to update its wallet on its own.<br />
<br />
However, indexing and storing large amounts of data for querying is a well understood and solved problem. It is easy to imagine a DHT that can be queried by public key hash or script hash to retrieve transaction and that is kept up-to-date by Bitcoin clients. Merely storing and indexing the information for occasional querying is not a difficult problem. This proposal however addresses the more difficult issue that verifying nodes need a full list of unspent outputs.<br />
<br />
== Resource Usage ==<br />
<br />
IMTUO is a storage/network tradeoff. We save most of the storage in exchange for increased network usage.<br />
<br />
=== Changed Incentives ===<br />
<br />
There is currently no way within the Bitcoin protocol to make a rogue miner liable for the costs he incurs for other miners by publishing a very large block. In order to mitigate this problem Bitcoin currently uses a hard-coded maximum block size limit MAX_BLOCK_SIZE.<br />
<br />
In an IMTUO network, the storage costs are negligible, since blocks are only stored temporarily. Instead, the network transmission costs are increased. Any miner is interested in getting its newly created block spread across the network so that other miners will build on it. Large blocks will spread more slowly and are therefore disadvantaged. IMTUO adds verification information and therefore increases this effect<br />
<br />
To create a block a miner will always have a certain cost to create the proof-of-work. The risk that a too large block will not ultimately make it into the chain is a natural incentive for miners to stay within reasonable limits.<br />
<br />
If desired, this can be exacerbated further by adding protocol rules that cause blocks not to be relayed and/or built upon unless a certain spread has been reached. This would but the burden on the creator to spread his (unusually large) block and/or pay other nodes to relay it.<br />
<br />
== Deployment ==<br />
<br />
IMTUO is a separate network from Bitcoin. Gateways have to run both a regular Bitcoin full node and store a full indexed copy of the IMTUO merkle tree (a 10-50% overhead over running a normal full node.)<br />
<br />
// TODO: How to handle the IMTUO root while IMTUO have a minority of mining power.</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Incidents&diff=16204Incidents2011-09-06T16:05:21Z<p>Justmoon: Fixed link to incident forum topic.</p>
<hr />
<div>== Micropayment contamination ==<br />
Around September 29, 2010, people started [http://www.bitcoin.org/smf/index.php?topic=1306.0 reporting] that their sent transactions would not confirm. This happened because people modified Bitcoin to send sub-0.01 transactions without any fees. A 0.01 fee was at that time required by the network for such transactions (essentially prohibiting them), so the transactions remained at 0 confirmations forever. This became a more serious issue because Bitcoin would send transactions using bitcoins gotten from transactions with 0 confirmations, and these resulting transactions would also never confirm. Because Bitcoin tends to prefer sending smaller coins, these invalid transactions quickly multiplied, contaminating the wallets of everyone who received them.<br />
<br />
Bitcoin was changed to only select coins with at least 1 confirmation. The remaining sub-0.01 transactions were cleared by generators who modified their version of Bitcoin to not require the micropayment fee. It took a while for everything to get cleared, though, because many of the intermediate transactions had been forgotten by the network by this point and had to be rebroadcast by the original senders.<br />
<br />
== Value overflow ==<br />
<br />
On August 15 2010, it was [http://bitcointalk.org/index.php?topic=822.0 discovered] that block 74638 contained a transaction that created over 184 billion bitcoins for two different addresses. This was possible because the code used for checking transactions before including them in a block didn't account for the case of outputs so large that they overflowed when summed. A new version was published within a few hours of the discovery. The block chain had to be forked. Although many unpatched nodes continued to build on the "bad" block chain, the "good" block chain overtook it at a block height of 74691. The bad transaction no longer exists for people using the longest chain.<br />
<br />
The block and transaction:<br />
<pre>CBlock(hash=0000000000790ab3, ver=1, hashPrevBlock=0000000000606865, hashMerkleRoot=618eba,<br />
nTime=1281891957, nBits=1c00800e, nNonce=28192719, vtx=2)<br />
CTransaction(hash=012cd8, ver=1, vin.size=1, vout.size=1, nLockTime=0)<br />
CTxIn(COutPoint(000000, -1), coinbase 040e80001c028f00)<br />
CTxOut(nValue=50.51000000, scriptPubKey=0x4F4BA55D1580F8C3A8A2C7)<br />
CTransaction(hash=1d5e51, ver=1, vin.size=1, vout.size=2, nLockTime=0)<br />
CTxIn(COutPoint(237fe8, 0), scriptSig=0xA87C02384E1F184B79C6AC)<br />
CTxOut(nValue=92233720368.54275808, scriptPubKey=OP_DUP OP_HASH160 0xB7A7)<br />
CTxOut(nValue=92233720368.54275808, scriptPubKey=OP_DUP OP_HASH160 0x1512)<br />
vMerkleTree: 012cd8 1d5e51 618eba<br />
<br />
Block hash: 0000000000790ab3f22ec756ad43b6ab569abf0bddeb97c67a6f7b1470a7ec1c<br />
Transaction hash: 1d5e512a9723cbef373b970eb52f1e9598ad67e7408077a82fdac194b65333c9</pre><br />
<br />
== OP_CHECKSIG abuse ==<br />
<br />
On July 29 2010, it was discovered that block [http://blockexplorer.com/block/00000000000997f9fd2fe1ee376293ef8c42ad09193a5d2086dddf8e5c426b56 71036] contained several transactions with a ton of OP_CHECKSIG commands. There should only ever be one such command. This caused every node to do extra unnecessary work, and it could have been used as a denial-of-service attack. A new version of Bitcoin was quickly released. The new version did not cause a fork on the main network, though it did cause one on the test network (where someone had played around with the attack more).<br />
<br />
== LSHIFT and RETURN bugs ==<br />
<br />
On July 28 2010 two bugs were discovered and demonstrated on the test network. The first caused bitcoin to crash on some machines when processing a transaction containing an OP_LSHIFT. The second exploited another bug in the transaction handling code and allowed an attacker to spend coins that they did not own. Neither were exploited on the main network, and both were fixed by Bitcoin version 0.3.5.<br />
<br />
After these bugs were discovered, many currently-unused [[script]] words were disabled for safety.<br />
<br />
== ASCII embedding into blockchain ==<br />
<br />
Security researchers Dan Kaminsky and Travis Goodspeed successfully embedded [http://pastebin.com/raw.php?i=BUB3dygQ extraneous text] into the blockchain from a mined block. This was disclosed on July 31, 2011, prior to Kaminsky's presentation at the Black Hat Briefings conference entitled [http://www.slideshare.net/dakami/black-ops-of-tcpip-2011-black-hat-usa-2011 Black Ops Of TCP/IP 2011].<br />
<br />
Block chain embedding should not really be seen as an attack, as BitCoin is ultimately a channel by which arbitrary data is validated and retained over time. Indeed, the very first block in BitCoin (the [[genesis block]]) contains a text message. More worrisome was the observation that arbitrary content can be inserted into a transaction after it has been released to miners, but before it has been included into a block. This was done via an arbitrary prefix on the ScriptSig. Furthermore, IP deanonymization was shown to be relatively straightforward for an attacker who can connect to a large number of nodes.<br />
[[Category:Technical]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=BitcoinJS&diff=12264BitcoinJS2011-07-02T12:47:29Z<p>Justmoon: Added basic info for BitcoinJS</p>
<hr />
<div>A reimplementation of Bitcoin using Node.js and web technologies.<br />
<br />
It currently implements the basics of the Bitcoin protocol, enough to send and receive transactions via the [[Webcoin]] frontend. All official BitcoinJS components are released under the [http://www.opensource.org/licenses/mit-license.php MIT license].<br />
<br />
== Components ==<br />
<br />
BitcoinJS consists of several loosely coupled component that can be used in different combinations to solve different problems.<br />
<br />
=== node-bitcoin-p2p ===<br />
<br />
The main component implementing the Bitcoin P2P [[Protocol|protocol]] and parts of the [[API reference (JSON-RPC)|JSON-RPC API]]. You can think of it as the counterpart to the [[Original Bitcoin client|original client's]] CLI daemon, bitcoind.<br />
<br />
As the name implies, node-bitcoin-p2p is built using the [http://nodejs.org Node.js framework]. It also uses [http://www.mongodb.org/ MongoDB] for storage and indexing of the block chain data.<br />
<br />
=== node-bitcoin-exit ===<br />
<br />
Builds on top of node-bitcoin-p2p to provide access to balances and transaction information on a per-account basis. It also allows the upload of new transactions to the network. These two functions are enough to allow a client to access the network only through this server.<br />
<br />
=== Other ===<br />
<br />
Various other software builds on top of the basic BitcoinJS infrastructure. Notable examples include [[Webcoin]] and [[BitcoinJS/Explorer|BitcoinJS Explorer]].<br />
<br />
== History ==<br />
<br />
* First commit was uploaded on March 12th, 2011 <ref>[https://github.com/justmoon/node-bitcoin-p2p/commit/aaad1406cfc652560abb708619e201898672f1db "Initial commit."] committed, March 12th 2011</ref><br />
* Repository moved to separate BitcoinJS account on April 30th, 2011 <ref>[https://github.com/justmoon/node-bitcoin-p2p/commit/a585bbae384a523c3d2ee19973daffd8db3d199a "Added new README with link to new repo."] committed, April 30, 2011</ref><br />
* Official announcement including screencast on May 5th, 2011 <ref>[http://forum.bitcoin.org/?topic=7357.0 "Webcoin Alpha Sneak Preview"] on Bitcoin.org forums, May 5, 2011</ref><br />
<br />
== See Also ==<br />
<br />
* [[Webcoin]]<br />
<br />
== External Links ==<br />
<br />
* [http://bitcoinjs.org/ Official project website]<br />
* [https://github.com/bitcoinjs BitcoinJS project on Github]<br />
<br />
== References ==<br />
<references /><br />
<br />
[[Category:Nodes]]<br />
[[Category:Clients]]<br />
[[Category:Free Software]]<br />
[[Category:License/MIT-X11]]<br />
[[Category:Open Source]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Development_process&diff=12263Development process2011-07-02T12:36:07Z<p>Justmoon: With Satoshi having disappeared I think it's safe to say Bitcoin is no longer a "one-person software endeavor". :)</p>
<hr />
<div>== Bitcoin Open Source Development Process ==<br />
<br />
The [[Original_Bitcoin_client|Bitcoin client]] project has transitioned from what was essentially a one-person software endeavor, with Satoshi functioning as the primary developer and gatekeeper for all changes, to a more distributed, free software model of development. The Linux Kernel development process is being used as the model for how changes flow into the official Bitcoin application:<br />
# Developers work in their own source code trees, sharing and testing patches with each other. git using github is the preferred source control system for development.<br />
# When a developer thinks a patch is ready, they submit a pull request for the [https://github.com/bitcoin/bitcoin bitcoin github repository] and post a message on the [http://www.bitcoin.org/smf/index.php?board=6.0 Development and Technical Forum].<br />
# Pull requests are discussed on the forums and if there is consensus they're safe, tested, useful, well written, match coding style, etc. then they're merged into the 'master' branch.<br />
# The master github branch is regularly built and tested, and periodically pushed to the [http://sourceforge.net/projects/bitcoin/develop subversion repository] to become a "release candidate" and then the official, stable, released bitcoin.<br />
<br />
Please read and follow [https://github.com/bitcoin/bitcoin/blob/master/coding.txt coding.txt] (link offline) for a description of the bitcoin coding style.<br />
<br />
==See Also==<br />
<br />
* [[Original Bitcoin client]]<br />
* [[:Category:Open_Source|Open source]]<br />
<br />
[[Category:Developer]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Difficulty&diff=12202Difficulty2011-07-01T18:06:15Z<p>Justmoon: Not a good idea to refer to the packed target as "difficulty" if we're already calling the max_target/cur_target ratio "difficulty". Clarified and also added the term "Bits" which is used for this value in the code, JSON-RPC and on block explorer.</p>
<hr />
<div>''See also: [[target]]''<br />
<br />
=== What is "difficulty"? ===<br />
<br />
Difficulty is a measure of how difficult it is to find a new [[block]] compared to the easiest it can ever be.<br />
<br />
=== How often does the difficulty change? ===<br />
<br />
Every 2016 [[block|blocks]].<br />
<br />
=== What is the formula for difficulty? ===<br />
<br />
difficulty = maximum_target / current_target <br />
<br />
(target is a 256 bit number)<br />
<br />
===How is difficulty stored in blocks?===<br />
<br />
Each block stores a packed representation (called "Bits") for its actual hexadecimal [[target]]. The target can be derived from it via a predefined formula. For example, if the packed target in the block is 0x1b0404cb, the hexadecimal target is<br />
0x0404cb * 2**(8*(0x1b - 3)) = 0x00000000000404CB000000000000000000000000000000000000000000000000<br />
<br />
The highest possible target (difficulty 1) is defined as 0x1d00ffff, which gives us a hex target of<br />
0x00ffff * 2**(8*(0x1d - 3)) = 0x00000000FFFF0000000000000000000000000000000000000000000000000000<br />
<br />
So the difficulty at 0x1b0404cb is therefore:<br />
0x00000000FFFF0000000000000000000000000000000000000000000000000000 /<br />
0x00000000000404CB000000000000000000000000000000000000000000000000 <br />
= 16307.420938523983<br />
<br />
=== What is the current difficulty? ===<br />
[http://blockexplorer.com/q/getdifficulty Current difficulty], as output by BitCoin's getDifficulty.<br />
<br />
[http://dot-bit.org/tools/nextDifficulty.php Estimated next difficulty]<br />
<br />
[http://bitcoin.sipa.be Graphs]<br />
<br />
=== What is the maximum difficulty? ===<br />
The maximum difficulty is roughly: maximum_target / 1, which is a ridiculously huge number (about 2^224). <br />
<br />
The actual maximum difficulty is when current_target=0, but we would not be able to calculate the difficulty if that happened. (fortunately it never will, so we're ok.)<br />
<br />
=== Can the difficulty go down? ===<br />
Yes it can. See discussion in [[target]].<br />
<br />
=== What is the minimum difficulty? ===<br />
The minimum difficulty, when the target is at the maximum allowed value, is 1.<br />
<br />
=== What network hash rate results in a given difficulty? ===<br />
The difficulty is adjusted every 2016 blocks based on the time it took to find the previous 2016 blocks. At the desired rate of one block each 10 minutes, 2016 blocks would take exactly two weeks to find. If the previous 2016 blocks took more than two weeks to find, the difficulty is reduced. If they took less than two weeks, the difficulty is increased. The change in difficulty is in proportion to the amount of time over or under two weeks the previous 2016 blocks took to find.<br />
<br />
To find a block, the hash must be less than the target. The hash is effectively a random number between 0 and 2**256-1. The offset for difficulty 1 is<br />
0xffff * 2**208<br />
and for difficulty D is<br />
0xffff * 2**208)/D<br />
<br />
The expected number of hashes we need to calculate to find a block with difficulty D is therefore<br />
D * 2**256 / (0xffff * 2**208)<br />
or just<br />
D * 2**48 / 0xffff<br />
<br />
The difficulty is set such that the previous 2016 blocks would have been found at the rate of one every 10 minutes, so we were calculating (D * 2**48 / 0xffff) hashes in 600 seconds. That means the hash rate of the network was<br />
D * 2**48 / 0xffff / 600<br />
over the previous 2016 blocks. Can be further simplified to<br />
D * 2**32 / 600<br />
without much loss of accuracy.<br />
<br />
At difficulty 1, that is around 7 Mhashes per second.<br />
<br />
At the time of writing, the difficulty is 22012.4941572, which means that over the previous set of 2016 blocks found the average network hash rate was<br />
22012.4941572 * 2**32 / 600 = around 157 Ghashes per second.<br />
<br />
=== How soon might I expect to generate a block? ===<br />
(The [https://www.bitcoin.org/smf/index.php?topic=1682.0 eternal question].)<br />
<br />
The average time to find a block can be approximated by calculating:<br />
time = difficulty * 2**32 / hashrate<br />
where difficulty is the current difficulty, hashrate is the number of hashes your miner calculates per second, and time is the average in seconds between the blocks you find.<br />
<br />
For example, using Python we calculate the average time to generate a block using a 1Ghash/s mining rig when the difficulty is 20000:<br />
$ python -c "print 20000 * 2**32 / 10**9 / 60 / 60.0"<br />
23.85<br />
and find that it takes just under 24 hours on average.<br />
<br />
* Any one grinding of the hash stands the same chance of "winning" as any other. The numbers game is how many attempts your hardware can make per second.<br />
* You need to know the difficulty (above) and your khash/sec rate (reported by the client).<br />
** [[Mining Hardware Comparison]] has some stats that may help you predict what you could get.<br />
* Visit a calculator or perform the maths yourself,<br />
** http://www.alloscomp.com/bitcoin/calculator.php<br />
* Remember it's just probability! There are no guarantees you will win every N days.<br />
<br />
[[Category:Technical]]<br />
[[Category:Vocabulary]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Protocol_documentation&diff=8400Protocol documentation2011-05-15T21:58:00Z<p>Justmoon: getblocks and getheaders don't actually include a version integer - fixed.</p>
<hr />
<div>Sources:<br />
* [[Original Bitcoin client]] source<br />
* [http://www.bitcoin.org/wiki/doku.php?id=bitcoins_draft_spec_0_0_1 Draft spec on bitcoin wiki]<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] (ECDSA) to sign transactions. <br />
<br />
For ECDSA the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where x and y are 32 byte strings representing the coordinates of a point on the curve. Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the r and s components into a single byte stream (because this is what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
{{See also|OP_CHECKSIG}}<br />
<br />
The first transaction of a block is usually the generating transaction, which do not include any "in" transaction, and generate bitcoins (from fees for example) usually received by whoever solved the block containing this transaction.<br />
Such transactions are called a "coinbase transaction" and are accepted by bitcoin clients without any need to execute scripts, provided there is only one per block.<br />
<br />
If a transaction is not a coinbase, it references previous transaction hashes as input, and the index of the other transaction's output used as input for this transaction.<br />
The script from the in part of this transaction is executed.<br />
Then the script from the out part of the referenced transaction is executed.<br />
It is considered valid if the top element of the stack is true.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload)) (not included in version or verack)<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value<br />
|-<br />
| main || F9BEB4D9<br />
|-<br />
| testnet || FABFB5DA<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space. Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xfd || 1 || uint8_t<br />
|-<br />
| <= 0xffff || 3 || 0xfd + uint16_t<br />
|-<br />
| <= 0xffffffff || 5 || 0xfe + uint32_t<br />
|-<br />
| - || 9 || 0xff + uint64_t<br />
|}<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || var_int || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK? see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:10.0.0.1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Block version information, based upon the software version creating this block<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || uint8_t || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node receives an incoming connection, it will immediately advertise its version. No futher communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || uint64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_me || net_addr || The network address of the node emitting this message<br />
|-<br />
|colspan="4"| version >= 106<br />
|-<br />
| 26 || addr_you || net_addr || The network address seen by the node emitting this message (ie, the address of the receiving node)<br />
|-<br />
| 8 || nonce || uint64_t || Node random unique id. This id is used to detect connections to self<br />
|-<br />
| ? || sub_version_num || var_str || Secondary Version information (null terminated?)<br />
|-<br />
|colspan="4"| version >= 209<br />
|-<br />
| 4 || start_height || uint32_t || The last block received by the emitting node<br />
|}<br />
<br />
If the emitter of the packet has version >= 209, a "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (note the message header for this version message does not have a checksum):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 - Sender address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Recipient address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''version'' for clients >= 209. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 ....<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload (maximum payload length: 1000 bytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || var_int || Number of address entries<br />
|-<br />
| 30x? || addr_list || (uint32_t + net_addr)[] || Address of other nodes on the network. version < 209 will only read the first one<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 7F 85 39 C2 01 E2 15 10 4D 01 00 00 ......9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D .D(.. .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
7F 85 39 C2 - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum payload length: 50000 bytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || var_int || Number of inventory entries<br />
|-<br />
| 36x? || inventory || inv_vect[] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements.<br />
<br />
Payload (maximum payload length: 50000 bytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || var_int || Number of inventory entries<br />
|-<br />
| 36x? || inventory || inv_vect[] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting at hash_start, up to hash_stop or 500 blocks, whichever comes first. To receive the next blocks hashes, one needs to issue getblocks again with the last known hash.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || start count || var_int || number of hash_start entries<br />
|-<br />
| 32+ || hash_start || char[32] || hash of the last known block of the emitting node<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block. Set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers for blocks starting at hash_start, up to hash_stop or 2000 blocks, whichever comes first. To receive the next blocks hashes, one needs to issue getheaders again with the last known hash. The ''getheaders'' command is used by thin clients to quickly download the blockchain where the contents of the transactions would be irrelevant (because they are not ours). <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || start count || var_int || number of hash_start entries<br />
|-<br />
| 32+ || hash_start || char[32] || hash of the last known block of the emitting node<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block. Set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''getdata''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Transaction data format version<br />
|-<br />
| 1+ || tx_in count || var_int || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || var_int || Number of Transaction outputs<br />
|-<br />
| 8+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked, or 0 if the transaction is always locked. A non-locked transaction must not be included in blocks, and it can be modified by broadcasting a new version before the time has expired (replacement is currently disabled in Bitcoin, however, so this is useless).<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || var_int || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || sequence || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || uint64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || var_int || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Block version information, based upon the software version creating this block<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || var_int || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || var_int || Number of block headers<br />
|-<br />
| 77x? || headers || block_header[] || Block headers<br />
|}<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with identifying potential nodes in the network. The response to receiving this message is to transmit an addr message with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== checkorder ===<br />
<br />
This message is used for [[IP Transactions]], to ask the peer if it accepts such transactions and allow it to look at the content of the order.<br />
<br />
It contains a CWalletTx object<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
|colspan="4"| Fields from CMerkleTx<br />
|-<br />
| ? || hashBlock<br />
|-<br />
| ? || vMerkleBranch<br />
|-<br />
| ? || nIndex<br />
|-<br />
|colspan="4"| Fields from CWalletTx<br />
|-<br />
| ? || vtxPrev<br />
|-<br />
| ? || mapValue<br />
|-<br />
| ? || vOrderForm<br />
|-<br />
| ? || fTimeReceivedIsTxTime<br />
|-<br />
| ? || nTimeReceived<br />
|-<br />
| ? || fFromMe<br />
|-<br />
| ? || fSpent<br />
|}<br />
<br />
=== submitorder ===<br />
<br />
Confirms an order has been submitted. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || Hash of the transaction<br />
|-<br />
| ? || wallet_entry || CWalletTx || Same payload as checkorder<br />
|}<br />
<br />
=== reply ===<br />
<br />
Generic reply for [[IP Transactions]]<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || reply || uint32_t || reply code<br />
|}<br />
<br />
Possible values:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || SUCCESS || The IP Transaction can proceed (''checkorder''), or has been accepted (''submitorder'')<br />
|-<br />
| 1 || WALLET_ERROR || AcceptWalletTransaction() failed<br />
|-<br />
| 2 || DENIED || IP Transactions are not accepted by this node<br />
|}<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. No reply is expected as a result of this message being sent nor any sort of action expected on the part of a client when it is used.<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || message || var_str || System message which is coded to convey some information to all nodes in the network<br />
|-<br />
| ? || signature || var_str || A signature which can be confirmed with a public key verifying that it is Satoshi (the originator of Bitcoins) who has "authorized" or created the message<br />
|}<br />
<br />
The signature is to be compared to this ECDSA public key:<br />
<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
Source: [http://www.bitcoin.org/smf/index.php?topic=898.0]<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
<br />
[[Category:Technical]]<br />
[[Category:Developer]]</div>Justmoonhttps://tests.bitcoin.it/w/index.php?title=Fallback_Nodes&diff=5277Fallback Nodes2011-03-11T17:48:24Z<p>Justmoon: /* IPv4 Nodes */</p>
<hr />
<div>This is a list of nodes which are considered reliable. Nodes from this list which are down for more than 24 hours will be automatically removed and status of each node is displayed and updated every hour by [[User:WikiBot|WikiBot]].<br />
<br />
== How to use this list ==<br />
<br />
=== Connect to nodes ===<br />
<br />
You can connect to these nodes with the ''-addnode=ip'' switch instead of the usual node harvesting process (through IRC or via the embedded nodelist). You can connect to more than one node by using ''-addnode=ip'' more than once. It is usually a good idea to connect to more than one of these nodes.<br />
<br />
==== Nodes without a fixed ip ====<br />
<br />
If the node IP is not fixed (see "Fixed" column), you will have to resolve the node's name (first column) each time the IP changes. Some nodes may have their ip change once a day, some others once a month, and some others may stay on the same IP for years. Still, as long as the IP is not fixed, there is no guarantee it will stay the same.<br />
<br />
The [[Original Bitcoin client]] do not support hostnames to the ''-addnode'' parameter, so you must do the resolving part for it. For example on linux:<br />
bitcoind -addnode=$(host theymos.ath.cx |sed s/"^.*has address "//)<br />
<br />
=== IP Transactions ===<br />
<br />
You can also send [[IP Transactions]] to these nodes. If you include your bitcoin address in the "message" field, you may have your coins back.<br />
<br />
=== Tor network ===<br />
<br />
To use tor .onion addresses, you need to map virtual ips via the ''torrc'' file:<br />
<br />
mapaddress 192.0.2.2 ijzt2eeizty3p5xe.onion<br />
mapaddress 192.0.2.3 j43z65b6r2usg3vk.onion<br />
mapaddress 192.0.2.4 pvuif6nonbhj3o3r.onion<br />
<br />
Once you have configured and restarted tor, 192.0.2.2 will connect to ijzt2eeizty3p5xe.onion when accessed through the Tor proxy (and likewise for the other IPs/onions). You can then run Bitcoin with -addnode=192.0.2.2, or even send bitcoins to that IP address. You can use any arbitrary IP addresses with MapAddress, though some of the common non-routable ranges (10.*, 192.168.*) will not work due to a Bitcoin bug. 192.0.2.1-192.0.2.255 is the recommended range because it is both non-routable and compatible with Bitcoin.<br />
<br />
== Nodes list ==<br />
<br />
=== IPv4 Nodes ===<br />
<br />
{|class="wikitable sortable"<br />
! Hostname !! Owner !! IP !! Fixed !! Status !! Last Seen (GMT) !! Accepts IP transactions<br />
|-<br />
<!-- BEGIN NODELIST --><br />
| nat.router.dashjr.org || Luke-Jr || 71.1.73.218 || {{Table Value No}} || {{Fallback Nodes/Node Up|version=0.3.21}} || 2011-03-11 17:00:06 || ?<br />
|-<br />
| ndrix.com || mndrix || 64.22.103.150 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.20[.2]}} || 2011-03-11 17:00:06 || ?<br />
|-<br />
| bitcoin-otc.com || nanotube || 69.163.132.101 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.20[.2]}} || 2011-03-11 17:00:07 || No<br />
|-<br />
| 69.164.218.197 || Gavin Andresen || 69.164.218.197 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.20[.2]}} || 2011-03-11 17:00:07 || ?<br />
|-<br />
| bitcoins.ca || humble || 142.58.248.28 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.20[.2]}} || 2011-03-11 17:00:07 || Yes<br />
|-<br />
| 217.157.1.202 || kseistrup || 217.157.1.202 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.20[.2]}} || 2011-03-11 17:00:07 || ?<br />
|-<br />
| lfmcal.dontexist.org || lfm || 75.158.131.108 || {{Table Value Unknown}} || {{Fallback Nodes/Node Up|version=0.3.20[.2]}} || 2011-03-11 17:00:07 || Yes<br />
|-<br />
| btc1.justmoon.net || justmoon || 109.75.176.226 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.20[.2]}} || 2011-03-11 17:00:07 || Yes<br />
|-<br />
| bitcoin.samara-lab.ru || m0Ray || 95.128.160.162 || {{Table Value Unknown}} || {{Fallback Nodes/Node Up|version=0.3.20[.2]}} || 2011-03-11 17:00:08 || ?<br />
|-<br />
| 178.63.15.200 || hendi || 178.63.15.200 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.20[.1]}} || 2011-03-11 17:00:10 || ?<br />
|-<br />
| bitcoin.sipa.be || sipa || 178.18.90.41 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.19[.2]}} || 2011-03-11 17:00:08 || No<br />
|-<br />
| theymos.ath.cx || theymos || 99.27.237.13 || {{Table Value Unknown}} || {{Fallback Nodes/Node Up|version=0.3.19[.2]}} || 2011-03-11 17:00:08 || Yes<br />
|-<br />
| fallback1.bitcoin.me.uk || Vladimir || 91.85.220.84 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.19}} || 2011-03-11 17:00:08 || No<br />
|-<br />
| 109.75.176.193 || MagicalTux [DE] || 109.75.176.193 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.19}} || 2011-03-11 17:00:09 || No<br />
|-<br />
| 174.120.185.74 || MagicalTux [US] || 174.120.185.74 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.19}} || 2011-03-11 17:00:09 || No<br />
|-<br />
| 178.63.62.15 || MagicalTux [DE] || 178.63.62.15 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.19}} || 2011-03-11 17:00:09 || No<br />
|-<br />
| lyasoff.com || ? || 200.35.150.50 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.19}} || 2011-03-11 17:00:09 || ?<br />
|-<br />
| bitlex.co.cc || BitLex || 78.34.69.123 || {{Table Value No}} || {{Fallback Nodes/Node Up|version=0.3.19}} || 2011-03-11 17:00:09 || Yes<br />
|-<br />
| 74.82.216.10 || thufir || 74.82.216.10 || {{Table Value Yes}} || {{Fallback Nodes/Node Up|version=0.3.10}} || 2011-03-11 17:00:10 || Yes<br />
|-<br />
| 74.57.236.239 || ? || 74.57.236.239 || {{Table Value Yes}} || {{Fallback Nodes/Node Old|version=0.3.0}} || 2011-03-11 17:00:10 || ?<br />
<!-- END NODELIST --><br />
|}<br />
<br />
=== Tor nodes ===<br />
<br />
{|class="wikitable sortable"<br />
! Hostname !! Owner !! Status !! Last Seen (GMT) !! Accepts IP transactions<br />
|-<br />
| ijzt2eeizty3p5xe.onion || ? || ? || 2011-02-11 || Yes<br />
|-<br />
| j43z65b6r2usg3vk.onion || Dybbuk || ? || 2011-02-11 || Yes<br />
|-<br />
| pvuif6nonbhj3o3r.onion || ? || ? || 2011-02-11 || Yes<br />
|-<br />
| c5qvugpewwyyy5oz.onion || ? || ? || 2011-02-11 || Yes<br />
|-<br />
| vso3r6cmjoomhhgg.onion || echelon || ? || 2011-02-11 || Yes<br />
|-<br />
| rnam4cxam62nkcyf.onion || BitLex || ? || 2011-02-11 || Yes<br />
|-<br />
| bitcoinbudtoeks7.onion || ? || ? || 2011-02-11 || ?<br />
|-<br />
| iy6ni3wkqazp4ytu.onion || ? || ? || 2011-02-11 || ?<br />
|-<br />
| h4kklwodpcmo6cbq.onion || ? || ? || 2011-02-11 || ?<br />
|-<br />
| vv6kcfscuntybrzm.onion || ? || ? || 2011-02-11 || ?<br />
|-<br />
| nlnsivjku4x4lu5n.onion || ? || ? || 2011-02-11 || ?<br />
|-<br />
| xqzfakpeuvrobvpj.onion || ? || ? || 2010-11-13 || No<br />
|}<br />
<br />
== Adding a node ==<br />
<br />
Before adding yourself as a fallback node, you should be sure your node will stay online for a long time. If a node is offline for more than 24 hours it will be removed from the list. To accept IP transactions you will have to add the ''-allowreceivebyip'' flag to your command line parameters.<br />
<br />
To add a node in this list, you just need the ip/hostname and your name, the other fields will be filled automatically. Insert the following lines before the <tt>END NODELIST</tt> line:<br />
<br />
<nowiki>|-<br />
| ip || your name</nowiki><br />
<br />
Please note that a bot will connect to your node every hour to check its status and version.</div>Justmoon