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.">
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." />
<li>Editor: Hanno Cornelius <ahref="mailto:hanno@status.im">hanno@status.im</a></li>
</ul><p><code>27/WAKU2-PEERS</code> describes a recommended minimal set of peer storage and peer management features to be implemented by Waku v2 clients.</p>
<p>In this context, peer <em>storage</em> 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 <em>persistence</em>,
or the ability to store peer data on disk to resume state after a client restart.</p>
<p>Peer <em>management</em> 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.</p>
<h1id="peer-store">
Peer store
<aclass="anchor"href="#peer-store">#</a>
</h1>
<p>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.</p>
<p>It is RECOMMENDED that a Waku v2 client tracks at least the following information about each of its peers in a peer store:</p>
<table>
<thead>
<tr>
<th>Metadata</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>Public key</em></td>
<td>The public key for this peer. This is related to the libp2p <ahref="https://docs.libp2p.io/concepts/peer-id/"><code>Peer ID</code></a>.</td>
</tr>
<tr>
<td><em>Addresses</em></td>
<td>Known transport layer <ahref="https://docs.libp2p.io/concepts/addressing/"><code>multiaddrs</code></a> for this peer.</td>
</tr>
<tr>
<td><em>Protocols</em></td>
<td>The libp2p <ahref="https://docs.libp2p.io/concepts/protocols/#protocol-ids"><code>protocol IDs</code></a> supported by this peer. This can be used to track the client’s connectivity to peers supporting different Waku v2 protocols, e.g. <ahref="https://rfc.vac.dev/spec/11/"><code>11/WAKU2-RELAY</code></a> or <ahref="https://rfc.vac.dev/spec/13/"><code>13/WAKU2-STORE</code></a>.</td>
</tr>
<tr>
<td><em>Connectivity</em></td>
<td>Tracks the peer’s current connectedness state. See <ahref="#peer-connectivity"><strong>Peer connectivity</strong></a> below.</td>
</tr>
<tr>
<td><em>Disconnect time</em></td>
<td>The timestamp at which this peer last disconnected. This becomes important when managing <ahref="#reconnecting-peers">peer reconnections</a></td>
</tr>
</tbody>
</table>
<h2id="peer-connectivity">
Peer connectivity
<aclass="anchor"href="#peer-connectivity">#</a>
</h2>
<p>A Waku v2 client SHOULD track <em>at least</em> the following connectivity states for each of its peers:</p>
<ul>
<li><strong><code>NotConnected</code></strong>: 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.</li>
<li><strong><code>CannotConnect</code></strong>: The client attempted to connect to this peer, but failed.</li>
<li><strong><code>CanConnect</code></strong>: The client was recently connected to this peer and disconnected gracefully.</li>
<li><strong><code>Connected</code></strong>: The client is actively connected to this peer.</li>
</ul>
<p>This list does not preclude clients from tracking more advanced connectivity metadata,
such as a peer’s blacklist status (see (<code>18/WAKU2-SWAP</code>)[https://rfc.vac.dev/spec/18/]).</p>
<h2id="persistence">
Persistence
<aclass="anchor"href="#persistence">#</a>
</h2>
<p>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.</p>
<h1id="peer-management">
Peer management
<aclass="anchor"href="#peer-management">#</a>
</h1>
<p>Waku v2 clients will have different requirements when it comes to managing the peers tracked in the <ahref="#peer-store"><strong>peer store</strong></a>.
It is RECOMMENDED that clients support:</p>
<ul>
<li><ahref="#reconnecting-peers">automatic reconnection</a> to peers under certain conditions</li>
<p>A Waku v2 client MAY choose to reconnect to previously connected, managed peers under certain conditions.
Such conditions include, but are not limited to:</p>
<ul>
<li>Reconnecting to all <code>relay</code>-capable peers after a client restart. This will require <ahref="#persistence">persistent peer storage</a>.</li>
</ul>
<p>If a client chooses to automatically reconnect to previous peers,
it MUST respect the <ahref="https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md#prune-backoff-and-peer-exchange">backing off period</a> specified for GossipSub v1.1 before attempting to reconnect.
This requires keeping track of the <ahref="#tracked-peer-metadata">last time each peer was disconnected</a>.</p>
<p>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 <ahref="https://docs.libp2p.io/concepts/protocols/#ping">libp2p pings</a> as per <code>10/WAKU2</code><ahref="https://rfc.vac.dev/spec/10/#recommendations-for-clients">client recommendations</a>.
The recommended period between pings SHOULD be <em>at most</em> 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.</p>
<blockquote>
<p><strong>Implementation note:</strong> the <code>nim-waku</code> client currently implements a keep-alive mechanism every <code>5 minutes</code>,
in response to a TCP connection timeout of <code>10 minutes</code>.</p>
