27/WAKU2-PEERS
- 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).
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.
Copyright
Copyright and related rights waived via CC0.