mirror of https://github.com/vacp2p/rfc.git
433 lines
15 KiB
HTML
433 lines
15 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en" dir="ltr">
|
|
|
|
<head>
|
|
<meta name="generator" content="Hugo 0.106.0">
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="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.">
|
|
<meta name="theme-color" content="#FFFFFF"><meta property="og:title" content="27/WAKU2-PEERS" />
|
|
<meta property="og:description" content="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." />
|
|
<meta property="og:type" content="article" />
|
|
<meta property="og:url" content="https://rfc.vac.dev/spec/27/" /><meta property="article:section" content="docs" />
|
|
|
|
|
|
|
|
<title>27/WAKU2-PEERS | Vac RFC</title>
|
|
<link rel="manifest" href="/manifest.json">
|
|
<link rel="icon" href="/favicon.png" type="image/x-icon">
|
|
<link rel="stylesheet" href="/book.min.e935e20bd0d469378cb482f0958edf258c731a4f895dccd55799c6fbc8043f23.css" integrity="sha256-6TXiC9DUaTeMtILwlY7fJYxzGk+JXczVV5nG+8gEPyM=">
|
|
<script defer src="/en.search.min.c5d1bce82efdf18368df717201616946c115a4bae1b1e271bf9f2d1e7aeef92e.js" integrity="sha256-xdG86C798YNo33FyAWFpRsEVpLrhseJxv58tHnru+S4="></script>
|
|
<!--
|
|
Made with Book Theme
|
|
https://github.com/alex-shpak/hugo-book
|
|
-->
|
|
|
|
|
|
</head>
|
|
|
|
<body dir="ltr">
|
|
<input type="checkbox" class="hidden toggle" id="menu-control" />
|
|
<input type="checkbox" class="hidden toggle" id="toc-control" />
|
|
<main class="container flex">
|
|
<aside class="book-menu">
|
|
<div class="book-menu-content">
|
|
|
|
<nav>
|
|
<h2 class="book-brand">
|
|
<a href="/"><span>Vac RFC</span>
|
|
</a>
|
|
</h2>
|
|
|
|
|
|
<div class="book-search">
|
|
<input type="text" id="book-search-input" placeholder="Search" aria-label="Search" maxlength="64" data-hotkeys="s/" />
|
|
<div class="book-search-spinner hidden"></div>
|
|
<ul id="book-search-results"></ul>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
<li>Raw
|
|
<ul>
|
|
<li><a href="/spec/20/">20/TOY-ETH-PM</a></li>
|
|
<li><a href="/spec/24/">24/STATUS-CURATION</a></li>
|
|
<li><a href="/spec/28/">28/STATUS-FEATURING</a></li>
|
|
<li><a href="/spec/31/">31/WAKU2-ENR</a></li>
|
|
<li><a href="/spec/32/">32/RLN-V1</a></li>
|
|
<li><a href="/spec/34/">34/WAKU2-PEER-EXCHANGE</a></li>
|
|
<li><a href="/spec/35/">35/WAKU2-NOISE</a></li>
|
|
<li><a href="/spec/37/">37/WAKU2-NOISE-SESSIONS</a></li>
|
|
<li><a href="/spec/38/">38/CONSENSUS-CLARO</a></li>
|
|
<li><a href="/spec/43/">43/WAKU2-NOISE-PAIRING</a></li>
|
|
<li><a href="/spec/44/">44/WAKU2-DANDELION</a></li>
|
|
<li><a href="/spec/45/">45/WAKU2-ADVERSARIAL-MODELS</a></li>
|
|
<li><a href="/spec/46/">46/GOSSIPSUB-TOR-PUSH</a></li>
|
|
<li><a href="/spec/47/">47/WAKU2-TOR-PUSH</a></li>
|
|
<li><a href="/spec/48/">48/RLN-INTEREP-SPEC</a></li>
|
|
<li><a href="/spec/51/">51/WAKU2-RELAY-SHARDING</a></li>
|
|
<li><a href="/spec/52/">52/WAKU2-RELAY-STATIC-SHARD-ALLOC</a></li>
|
|
<li><a href="/spec/57/">57/STATUS-Simple-Scaling</a></li>
|
|
<li><a href="/spec/58/">58/RLN-V2</a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Draft
|
|
<ul>
|
|
<li><a href="/spec/1/">1/COSS</a></li>
|
|
<li><a href="/spec/3/">3/REMOTE-LOG</a></li>
|
|
<li><a href="/spec/4/">4/MVDS-META</a></li>
|
|
<li><a href="/spec/10/">10/WAKU2</a></li>
|
|
<li><a href="/spec/12/">12/WAKU2-FILTER</a></li>
|
|
<li><a href="/spec/13/">13/WAKU2-STORE</a></li>
|
|
<li><a href="/spec/14/">14/WAKU2-MESSAGE</a></li>
|
|
<li><a href="/spec/15/">15/WAKU2-BRIDGE</a></li>
|
|
<li><a href="/spec/16/">16/WAKU2-RPC</a></li>
|
|
<li><a href="/spec/17/">17/WAKU2-RLN-RELAY</a></li>
|
|
<li><a href="/spec/18/">18/WAKU2-SWAP</a></li>
|
|
<li><a href="/spec/19/">19/WAKU2-LIGHTPUSH</a></li>
|
|
<li><a href="/spec/21/">21/WAKU2-FTSTORE</a></li>
|
|
<li><a href="/spec/22/">22/TOY-CHAT</a></li>
|
|
<li><a href="/spec/23/">23/WAKU2-TOPICS</a></li>
|
|
<li><a href="/spec/26/">26/WAKU2-PAYLOAD</a></li>
|
|
<li><a href="/spec/27/"class=active>27/WAKU2-PEERS</a></li>
|
|
<li><a href="/spec/29/">29/WAKU2-CONFIG</a></li>
|
|
<li><a href="/spec/30/">30/ADAPTIVE-NODES</a></li>
|
|
<li><a href="/spec/33/">33/WAKU2-DISCV5</a></li>
|
|
<li><a href="/spec/36/">36/WAKU2-BINDINGS-API</a></li>
|
|
<li><a href="/spec/53/">53/WAKU2-X3DH</a></li>
|
|
<li><a href="/spec/54/">54/WAKU2-X3DH-SESSIONS</a></li>
|
|
<li><a href="/spec/55/">55/STATUS-1TO1-CHAT</a></li>
|
|
<li><a href="/spec/56/">56/STATUS-COMMUNITIES</a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Stable
|
|
<ul>
|
|
<li><a href="/spec/2/">2/MVDS</a></li>
|
|
<li><a href="/spec/6/">6/WAKU1</a></li>
|
|
<li><a href="/spec/7/">7/WAKU-DATA</a></li>
|
|
<li><a href="/spec/8/">8/WAKU-MAIL</a></li>
|
|
<li><a href="/spec/9/">9/WAKU-RPC</a></li>
|
|
<li><a href="/spec/11/">11/WAKU2-RELAY</a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Deprecated
|
|
<ul>
|
|
<li><a href="/spec/5/">5/WAKU0</a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Retired</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</nav>
|
|
|
|
|
|
|
|
|
|
<script>(function(){var e=document.querySelector("aside.book-menu nav");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script>
|
|
|
|
|
|
|
|
</div>
|
|
</aside>
|
|
|
|
<div class="book-page">
|
|
<header class="book-header">
|
|
|
|
<div class="flex align-center justify-between">
|
|
<label for="menu-control">
|
|
<img src="/svg/menu.svg" class="book-icon" alt="Menu" />
|
|
</label>
|
|
|
|
<strong>27/WAKU2-PEERS</strong>
|
|
|
|
<label for="toc-control">
|
|
|
|
<img src="/svg/toc.svg" class="book-icon" alt="Table of Contents" />
|
|
|
|
</label>
|
|
</div>
|
|
|
|
|
|
|
|
<aside class="hidden clearfix">
|
|
|
|
|
|
<nav id="TableOfContents">
|
|
<ul>
|
|
<li><a href="#peer-store">Peer store</a>
|
|
<ul>
|
|
<li><a href="#tracked-peer-metadata">Tracked peer metadata</a></li>
|
|
<li><a href="#peer-connectivity">Peer connectivity</a></li>
|
|
<li><a href="#persistence">Persistence</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#peer-management">Peer management</a>
|
|
<ul>
|
|
<li><a href="#reconnecting-peers">Reconnecting peers</a></li>
|
|
<li><a href="#connection-keep-alive">Connection keep-alive</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#copyright">Copyright</a></li>
|
|
<li><a href="#references">References</a></li>
|
|
</ul>
|
|
</nav>
|
|
|
|
|
|
|
|
</aside>
|
|
|
|
|
|
</header>
|
|
|
|
|
|
|
|
<article class="markdown">
|
|
<h1 id="27waku2-peers">
|
|
27/WAKU2-PEERS
|
|
<a class="anchor" href="#27waku2-peers">#</a>
|
|
</h1>
|
|
|
|
|
|
<h1 id="waku-v2-client-peer-management-recommendations">
|
|
Waku v2 Client Peer Management Recommendations
|
|
<a class="anchor" href="#waku-v2-client-peer-management-recommendations">#</a>
|
|
</h1>
|
|
|
|
|
|
|
|
|
|
|
|
<img src="https://img.shields.io/badge/status-draft-blue?style=flat-square" />
|
|
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
<li>Status: draft</li>
|
|
<li>Editor: Hanno Cornelius <a href="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>
|
|
<h1 id="peer-store">
|
|
Peer store
|
|
<a class="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>
|
|
<h2 id="tracked-peer-metadata">
|
|
Tracked peer metadata
|
|
<a class="anchor" href="#tracked-peer-metadata">#</a>
|
|
</h2>
|
|
<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 <a href="https://docs.libp2p.io/concepts/peer-id/"><code>Peer ID</code></a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><em>Addresses</em></td>
|
|
<td>Known transport layer <a href="https://docs.libp2p.io/concepts/addressing/"><code>multiaddrs</code></a> for this peer.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><em>Protocols</em></td>
|
|
<td>The libp2p <a href="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. <a href="https://rfc.vac.dev/spec/11/"><code>11/WAKU2-RELAY</code></a> or <a href="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 <a href="#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 <a href="#reconnecting-peers">peer reconnections</a></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h2 id="peer-connectivity">
|
|
Peer connectivity
|
|
<a class="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>
|
|
<h2 id="persistence">
|
|
Persistence
|
|
<a class="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>
|
|
<h1 id="peer-management">
|
|
Peer management
|
|
<a class="anchor" href="#peer-management">#</a>
|
|
</h1>
|
|
<p>Waku v2 clients will have different requirements when it comes to managing the peers tracked in the <a href="#peer-store"><strong>peer store</strong></a>.
|
|
It is RECOMMENDED that clients support:</p>
|
|
<ul>
|
|
<li><a href="#reconnecting-peers">automatic reconnection</a> to peers under certain conditions</li>
|
|
<li><a href="#connection-keep-alive">connection keep-alive</a></li>
|
|
</ul>
|
|
<h2 id="reconnecting-peers">
|
|
Reconnecting peers
|
|
<a class="anchor" href="#reconnecting-peers">#</a>
|
|
</h2>
|
|
<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 <a href="#persistence">persistent peer storage</a>.</li>
|
|
</ul>
|
|
<p>If a client chooses to automatically reconnect to previous peers,
|
|
it MUST respect the <a href="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 <a href="#tracked-peer-metadata">last time each peer was disconnected</a>.</p>
|
|
<h2 id="connection-keep-alive">
|
|
Connection keep-alive
|
|
<a class="anchor" href="#connection-keep-alive">#</a>
|
|
</h2>
|
|
<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 <a href="https://docs.libp2p.io/concepts/protocols/#ping">libp2p pings</a> as per <code>10/WAKU2</code> <a href="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>
|
|
</blockquote>
|
|
<h1 id="copyright">
|
|
Copyright
|
|
<a class="anchor" href="#copyright">#</a>
|
|
</h1>
|
|
<p>Copyright and related rights waived via
|
|
<a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
|
|
<h1 id="references">
|
|
References
|
|
<a class="anchor" href="#references">#</a>
|
|
</h1>
|
|
<ol>
|
|
<li><a href="https://rfc.vac.dev/spec/10/#recommendations-for-clients"><code>10/WAKU2</code> client recommendations</a></li>
|
|
<li><a href="https://rfc.vac.dev/spec/11/"><code>11/WAKU2-RELAY</code></a></li>
|
|
<li><a href="https://rfc.vac.dev/spec/13/"><code>13/WAKU2-STORE</code></a></li>
|
|
<li><a href="https://docs.libp2p.io/concepts/peer-id/"><code>libp2p</code> peer ID</a></li>
|
|
<li><a href="https://docs.libp2p.io/concepts/protocols/#ping"><code>libp2p</code> ping protocol</a></li>
|
|
<li><a href="https://docs.libp2p.io/concepts/protocols/#protocol-ids"><code>libp2p</code> protocol IDs</a></li>
|
|
<li><a href="https://docs.libp2p.io/concepts/addressing/"><code>multiaddrs</code></a></li>
|
|
</ol>
|
|
</article>
|
|
|
|
|
|
|
|
<footer class="book-footer">
|
|
|
|
<div class="flex flex-wrap justify-between">
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
</footer>
|
|
|
|
|
|
|
|
<div class="book-comments">
|
|
|
|
</div>
|
|
|
|
|
|
|
|
<label for="menu-control" class="hidden book-menu-overlay"></label>
|
|
</div>
|
|
|
|
|
|
<aside class="book-toc">
|
|
<div class="book-toc-content">
|
|
|
|
|
|
<nav id="TableOfContents">
|
|
<ul>
|
|
<li><a href="#peer-store">Peer store</a>
|
|
<ul>
|
|
<li><a href="#tracked-peer-metadata">Tracked peer metadata</a></li>
|
|
<li><a href="#peer-connectivity">Peer connectivity</a></li>
|
|
<li><a href="#persistence">Persistence</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#peer-management">Peer management</a>
|
|
<ul>
|
|
<li><a href="#reconnecting-peers">Reconnecting peers</a></li>
|
|
<li><a href="#connection-keep-alive">Connection keep-alive</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#copyright">Copyright</a></li>
|
|
<li><a href="#references">References</a></li>
|
|
</ul>
|
|
</nav>
|
|
|
|
|
|
|
|
</div>
|
|
</aside>
|
|
|
|
</main>
|
|
|
|
|
|
</body>
|
|
|
|
</html>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|