27/WAKU2-PEERS #

Waku v2 Client Peer Management Recommendations #

Status: draft
Editor: Hanno Cornelius hanno@status.im

27/WAKU2-PEERS describes a recommended minimal set of peer storage and peer management features to be implemented by Waku v2 clients.

In this context, peer storage refers to a client’s ability to keep track of discovered or statically-configured peers and their metadata. It also deals with matters of peer persistence, or the ability to store peer data on disk to resume state after a client restart.

Peer management is a closely related concept and refers to the set of actions a client MAY choose to perform based on its knowledge of its connected peers, e.g. triggering reconnects/disconnects, keeping certain connections alive, etc.

Peer store #

The peer store SHOULD be an in-memory data structure where information about discovered or configured peers are stored. It SHOULD be considered the main source of truth for peer-related information in a Waku v2 client. Clients MAY choose to persist this store on-disk.

Tracked peer metadata #

It is RECOMMENDED that a Waku v2 client tracks at least the following information about each of its peers in a peer store:

Metadata	Description
Public key	The public key for this peer. This is related to the libp2p `Peer ID`.
Addresses	Known transport layer `multiaddrs` for this peer.
Protocols	The libp2p `protocol IDs` supported by this peer. This can be used to track the client’s connectivity to peers supporting different Waku v2 protocols, e.g. `11/WAKU2-RELAY` or `13/WAKU2-STORE`.
Connectivity	Tracks the peer’s current connectedness state. See Peer connectivity below.
Disconnect time	The timestamp at which this peer last disconnected. This becomes important when managing peer reconnections

Peer connectivity #

A Waku v2 client SHOULD track at least the following connectivity states for each of its peers:

NotConnected: The peer has been discovered or configured on this client, but no attempt has yet been made to connect to this peer. This is the default state for a new peer.
CannotConnect: The client attempted to connect to this peer, but failed.
CanConnect: The client was recently connected to this peer and disconnected gracefully.
Connected: The client is actively connected to this peer.

This list does not preclude clients from tracking more advanced connectivity metadata, such as a peer’s blacklist status (see (18/WAKU2-SWAP)[https://rfc.vac.dev/spec/18/]).

Persistence #

A Waku v2 client MAY choose to persist peers across restarts, using any offline storage technology, such as an on-disk database. Peer persistence MAY be used to resume peer connections after a client restart.

Peer management #

Waku v2 clients will have different requirements when it comes to managing the peers tracked in the peer store. It is RECOMMENDED that clients support:

automatic reconnection to peers under certain conditions
connection keep-alive

Reconnecting peers #

A Waku v2 client MAY choose to reconnect to previously connected, managed peers under certain conditions. Such conditions include, but are not limited to:

Reconnecting to all relay-capable peers after a client restart. This will require persistent peer storage.

If a client chooses to automatically reconnect to previous peers, it MUST respect the backing off period specified for GossipSub v1.1 before attempting to reconnect. This requires keeping track of the last time each peer was disconnected.

Connection keep-alive #

A Waku v2 client MAY choose to implement a keep-alive mechanism to certain peers. If a client chooses to implement keep-alive on a connection, it SHOULD do so by sending periodic libp2p pings as per 10/WAKU2 client recommendations. The recommended period between pings SHOULD be at most 50% of the shortest idle connection timeout for the specific client and transport. For example, idle TCP connections often times out after 10 to 15 minutes.

Implementation note: the nim-waku client currently implements a keep-alive mechanism every 5 minutes, in response to a TCP connection timeout of 10 minutes.