Skip to main content

extensible-peer-records

  • Status: raw
  • Category: Standards Track
  • Editor: Hanno Cornelius <hanno@status.im>

Abstract​

This RFC proposes Extensible Peer Records, an extension of libp2p's routing records, that enables peers to encode an arbitrary list of supported services and essential service-related information in distributable records. This version of routing records allows peers to communicate capabilities such as protocol support, and essential information related to such capabilities. This is especially useful when (signed) records are used in peer discovery, allowing discoverers to filter for peers matching a desired set of capability criteria. Extensible Peer Records maintain backwards compatibility with standard libp2p routing records, while adding an extensible service information field that supports finer-grained capability communication.

> A note on terminology: We opt to call this structure a "peer record", even though the corresponding libp2p specification refers to a "routing record". This is because the libp2p specification itself defines an internal PeerRecord type, and, when serialised into a signed envelope, this is most often called a "signed peer record" (see, for example, here).

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in 2119.

Motivation​

We propose a new peer record as an extension of libp2p's RFC003 Routing Records that allows encoding an arbitrary list of services, and essential information pertaining to those services, supported by the peer.

There are at least two reasons why a peer might want to encode service information in its peer records:

  1. To augment identify with peer capabilities: The libp2p identify protocol allows peers to exchange critical information, such as supported protocols, on first connection. The peer record (in a signed envelope) can also be exchanged during identify. However, peers may want to exchange finer-grained information related to supported protocols/services, that would otherwise require an application-level negotiation protocol, or that is critical to connect to the service in the first place. An example would be nodes supporting libp2p mix protocol also needing to exchange the mix key before the service can be used.
  2. To advertise supported services: If the peer record is used as the discoverable record for a peer (as we propose for various discovery methods) that peer may want to encode a list of supported services in its advertised record. These services may be (but is not limited to) a list of supported libp2p protocols and critical information pertaining to that service (such as the mix key, explained above). Discoverers can then filter discovered records for desired capabilities based on the encoded service information or use it to initiate the service.

Wire protocol​

Extensible Peer Records​

Extensible Peer Records MUST adhere to the following structure:

syntax = "proto3";

package peer.pb;

// ExtensiblePeerRecord messages contain information that is useful to share with other peers.
// Currently, an ExtensiblePeerRecord contains the public listen addresses for a peer
// and an extensible list of supported services as key-value pairs.
//
// ExtensiblePeerRecords are designed to be serialised to bytes and placed inside of
// SignedEnvelopes before sharing with other peers.
message ExtensiblePeerRecord {

  // AddressInfo is a wrapper around a binary multiaddr. It is defined as a
  // separate message to allow us to add per-address metadata in the future.
  message AddressInfo {
    bytes multiaddr = 1;
  }

  // peer_id contains a libp2p peer id in its binary representation.
  bytes peer_id = 1;

  // seq contains a monotonically-increasing sequence counter to order ExtensiblePeerRecords in time.
  uint64 seq = 2;

  // addresses is a list of public listen addresses for the peer.
  repeated AddressInfo addresses = 3;

  message ServiceInfo{
    string id = 1;
    optional bytes data = 2;
  }

   // Extensible list of advertised services
  repeated ServiceInfo services = 4;
}

A peer MAY include a list of supported services in the services field. These services could be libp2p protocols, in which case it is RECOMMENDED that the ServiceInfo id field be derived from the libp2p protocol identifier. In any case, for each supported service, the id field MUST be populated with a string identifier for that service. In addition, the data field MAY be populated with additional information about the service. It is RECOMMENDED that each data field be no more than 33 bytes. (We choose 33 here to allow for the encoding of 256 bit keys with parity. Also see Size constraints for recommendations on limiting the overall record size.)

The rest of the ExtensiblePeerRecord MUST be populated as per the libp2p PeerRecord specification. Due to the natural extensibility of protocol buffers, serialised ExtensiblePeerRecords are backwards compatible with libp2p PeerRecords, only adding the functionality related to service info exchange.

Size constraints​

To limit the impact on resources, ExtensiblePeerRecords SHOULD NOT be used to encode information that is not essential for discovery or service initiation. Since these records are likely to be exchanged frequently, they should be kept as small as possible while still providing all necessary functionality. Although specific applications MAY choose to enforce a smaller size, it is RECOMMENDED that an absolute maximum size of 1024 bytes is enforced for valid records. Extensible Peer Records may be included in size-constrained protocols that further limit the size (such as DNS).

Wrapping in Signed Peer Envelopes​

Extensible Peer Records MUST be wrapped in libp2p signed envelopes before distributing them to peers. The corresponding ExtensiblePeerRecord message is serialised into the signed envelope's payload field.

Signed Envelope Domain​

Extensible Peer Records MUST use libp2p-routing-state as domain separator string for the envelope signature. This is the same as for ordinary libp2p routing records.

Signed Envelope Payload Type​

Extensible Peer Records MUST use the UTF8 string /libp2p/extensible-peer-record/ as the payload_type value.

> Note: this will make Extensible Peer Records a subtype of the "namespace" multicodec. In future we may define a more compact multicodec type for Extensible Peer Records.

Copyright and related rights waived via CC0.

References​