User:Justmoon/BIP Draft: Custom Service Discovery

From Bitcoin Wiki
< User:Justmoon
Revision as of 06:07, 19 August 2012 by Justmoon (talk | contribs) (Update reference with actual BIP number.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This page describes a BIP (Bitcoin Improvement Proposal).
Please see BIP 2 for more information about BIPs and creating them. Please do not just create a wiki page.

  BIP: Draft
  Title: Custom Services
  Author: Stefan Thomas <>
  Status: Draft
  Type: Informational
  Created: 10-08-2012


This BIP augments 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.


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.


Bitcoin includes the services field for each node in the addr 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 addr message, we instead send a service-specific message ahead of it. This message SHOULD use the addr subcommand, so for the MySampleSvc service it would be called MySampleSvc:addr. We'll refer to it here generically as the *:addr message.

The *:addr of a service specifies which nodes in the next following addr list support that service. It uses the following format:

  • If *:addr is empty or starts with TYPE_ALL (0x00), then all addresses in the next addr message support the service.
  • If *:addr 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 *:addr 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 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 *:addr message since the last addr message or the beginning of the connection, then none of the nodes in the next addr message support the service.


 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 X:addr messages for different services MUST all be applied to the next addr message. If there are multiple X:addr 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 X:addr messages using TYPE_RLE.


The protocol above attempts to allow service discovery in a way that best fulfills the following criteria:

  • Minimize additional network traffic from custom service discovery
  • Ensure that custom services using this scheme can be migrated to become standard services

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.

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.


This document is placed in the public domain.