User:Justmoon/BIP Draft: Custom Services - Revision history

Justmoon: Set up redirect to final BIP location.

2012-08-19T06:10:43Z

Set up redirect to final BIP location.

Justmoon: Removed redundant terminology.

2012-08-13T07:25:37Z

Removed redundant terminology.

← Older revision		Revision as of 07:25, 13 August 2012
Line 48:		Line 48:
	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.		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.

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

	===Service identifier===		===Service identifier===

Justmoon: Added reference to the exact field being specified.

2012-08-13T07:21:57Z

Added reference to the exact field being specified.

← Older revision		Revision as of 07:21, 13 August 2012
Line 30:		Line 30:
	\|}		\|}

	The service definitions are given in the following format:		The service definitions <code>service[]</code> are given in the following format:

	{\|class="wikitable"		{\|class="wikitable"

Justmoon: Small wording fix.

2012-08-13T07:21:01Z

Small wording fix.

← Older revision		Revision as of 07:21, 13 August 2012
Line 16:		Line 16:
	==Motivation==		==Motivation==

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

	==Specification==		==Specification==

Justmoon: Disambiguation.

2012-08-10T19:36:59Z

Disambiguation.

← Older revision		Revision as of 19:36, 10 August 2012
Line 119:		Line 119:

	* MUST NOT use <code>service_data</code>; Standard services have no corresponding field		* MUST NOT use <code>service_data</code>; Standard services have no corresponding field
	* MUST use a discovery mechanism which specifies one bit per node, same as the <code>services</code> field in <code>addr</code> messages		* MUST use a peer discovery mechanism which specifies one bit per node, same as the <code>services</code> field in <code>addr</code> messages
	* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands		* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands

Justmoon: Formatting fix.

2012-08-10T19:36:16Z

Formatting fix.

← Older revision		Revision as of 19:36, 10 August 2012
Line 119:		Line 119:

	* MUST NOT use <code>service_data</code>; Standard services have no corresponding field		* MUST NOT use <code>service_data</code>; Standard services have no corresponding field
	* MUST use a discovery mechanism which specifies one bit per node, same as the services field in <code>addr</code> messages		* MUST use a discovery mechanism which specifies one bit per node, same as the <code>services</code> field in <code>addr</code> messages
	* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands		* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands

Justmoon: Rephrased first part of custom services section for clarity.

2012-08-10T19:34:54Z

Rephrased first part of custom services section for clarity.

← Older revision		Revision as of 19:34, 10 August 2012
Line 77:		Line 77:
	===Optional: Custom commands===		===Optional: Custom commands===

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

	The service-specific command name SHOULD then be specified in an extra header in the payload:		The service-specific command name SHOULD then be specified in an extra header in the payload:

Justmoon: Removed reference to removed section.

2012-08-10T19:05:51Z

Removed reference to removed section.

← Older revision		Revision as of 19:05, 10 August 2012
Line 119:		Line 119:

	* MUST NOT use <code>service_data</code>; Standard services have no corresponding field		* MUST NOT use <code>service_data</code>; Standard services have no corresponding field
	* MUST use ~~the <code>*:addr</code>~~ mechanism ~~in this BIP; This~~ specifies one bit per node, same as ~~standard~~ services		* MUST use a discovery mechanism which specifies one bit per node, same as the services field in <code>addr</code> messages
	* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands		* MUST NOT use any subcommands that conflict with current or planned Bitcoin protocol commands

Justmoon: Fix whitespace.

2012-08-10T18:21:10Z

Fix whitespace.

← Older revision		Revision as of 18:21, 10 August 2012
Line 113:		Line 113:
	12 34 56 78 9A BC DE F0 - Payload		12 34 56 78 9A BC DE F0 - Payload
	</pre>		</pre>


	==Standardization==		==Standardization==

Justmoon: Split off service discovery into its own BIP.

2012-08-10T18:20:49Z

Split off service discovery into its own BIP.

← Older revision		Revision as of 18:20, 10 August 2012
Line 114:		Line 114:
	</pre>		</pre>

	~~===Optional: Announcing known nodes===~~

	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.

	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.

	~~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:~~

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

	~~Examples:~~

	~~00 - TYPE_ALL - all nodes in the next addr message support the service~~

	~~01 - TYPE_BITS~~
	~~FC - 11111100 - First six nodes support the service, next two don't~~
	~~1F - 00011111 - Next three don't, next five do~~
	~~- Remaining nodes don't~~

	~~02 - TYPE_RLE~~
	~~01 - First set of nodes are nodes that support the service~~
	~~05 - First six nodes support the service~~
	~~FD 42 03 - Next 835 nodes don't~~
	~~00 - Next node does~~
	~~08 - Next nine nodes don't~~
	~~- Remaining nodes do~~

	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.

	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.

	==Standardization==		==Standardization==