vacp2p
/
rfc
mirror of https://github.com/vacp2p/rfc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
rfc/spec/23/index.html

483 lines
18 KiB
HTML
Raw Blame History

<!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="This document outlines recommended usage of topic names in Waku v2. In 10/WAKU2 spec there are two types of topics:
pubsub topics, used for routing Content topics, used for content-based filtering Pubsub Topics # Pubsub topics are used for routing of messages (see 11/WAKU2-RELAY), and can be named implicitly by Waku sharding (see 51/WAKU2-RELAY-SHARDING). This document comprises recommendations for explicitly naming pubsub topics (e.g. when choosing named sharding as specified in 51/WAKU2-RELAY-SHARDING).">
<meta name="theme-color" content="#FFFFFF"><meta property="og:title" content="23/WAKU2-TOPICS" />
<meta property="og:description" content="This document outlines recommended usage of topic names in Waku v2. In 10/WAKU2 spec there are two types of topics:
pubsub topics, used for routing Content topics, used for content-based filtering Pubsub Topics # Pubsub topics are used for routing of messages (see 11/WAKU2-RELAY), and can be named implicitly by Waku sharding (see 51/WAKU2-RELAY-SHARDING). This document comprises recommendations for explicitly naming pubsub topics (e.g. when choosing named sharding as specified in 51/WAKU2-RELAY-SHARDING)." />
<meta property="og:type" content="article" />
<meta property="og:url" content="https://rfc.vac.dev/spec/23/" /><meta property="article:section" content="docs" />
<title>23/WAKU2-TOPICS | 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&#43;JXczVV5nG&#43;8gEPyM=">
<script defer src="/en.search.min.5ded20501fd3debf92de0cd115de9de371f4bce78e8de5a9b2f50e06f822ce49.js" integrity="sha256-Xe0gUB/T3r&#43;S3gzRFd6d43H0vOeOjeWpsvUOBvgizkk="></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>
<li><a href="/spec/61/">61/STATUS-Community-History-Archives</a></li>
<li><a href="/spec/63/">63/STATUS-Keycard-Usage</a></li>
<li><a href="/spec/64/">64/WAKU2-NETWORK</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/"class=active>23/WAKU2-TOPICS</a></li>
<li><a href="/spec/26/">26/WAKU2-PAYLOAD</a></li>
<li><a href="/spec/27/">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>23/WAKU2-TOPICS</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>
<ul>
<li><a href="#pubsub-topics">Pubsub Topics</a>
<ul>
<li><a href="#pubsub-topic-format">Pubsub Topic Format</a></li>
<li><a href="#default-pubsub-topic">Default PubSub Topic</a></li>
<li><a href="#application-specific-names">Application Specific Names</a></li>
<li><a href="#named-topic-sharding-example">Named Topic Sharding Example</a></li>
</ul>
</li>
<li><a href="#content-topics">Content Topics</a>
<ul>
<li><a href="#content-topic-format">Content Topic Format</a></li>
<li><a href="#content-topic-naming-recommendations">Content Topic Naming Recommendations</a></li>
</ul>
</li>
<li><a href="#differences-with-waku-v1">Differences with Waku v1</a>
<ul>
<li><a href="#bridging-waku-v1-and-waku-v2">Bridging Waku v1 and Waku v2</a></li>
</ul>
</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="23waku2-topics">
23/WAKU2-TOPICS
<a class="anchor" href="#23waku2-topics">#</a>
</h1>
<h1 id="waku-v2-topic-usage-recommendations">
Waku v2 Topic Usage Recommendations
<a class="anchor" href="#waku-v2-topic-usage-recommendations">#</a>
</h1>
<img src="https://img.shields.io/badge/status-draft-blue?style=flat-square" />
<ul>
<li>Status: draft</li>
<li>Editor: Oskar Thoren <a href="mailto:oskar@status.im">oskar@status.im</a></li>
<li>Contributors:
Hanno Cornelius <a href="mailto:hanno@status.im">hanno@status.im</a>
,
Daniel Kaiser <a href="mailto:danielkaiser@status.im">danielkaiser@status.im</a>
</li>
</ul><p>This document outlines recommended usage of topic names in Waku v2.
In <a href="/spec/10">10/WAKU2 spec</a> there are two types of topics:</p>
<ul>
<li>pubsub topics, used for routing</li>
<li>Content topics, used for content-based filtering</li>
</ul>
<h2 id="pubsub-topics">
Pubsub Topics
<a class="anchor" href="#pubsub-topics">#</a>
</h2>
<p>Pubsub topics are used for routing of messages (see <a href="/spec/11">11/WAKU2-RELAY</a>),
and can be named implicitly by Waku sharding (see <a href="/spec/51">51/WAKU2-RELAY-SHARDING</a>).
This document comprises recommendations for explicitly naming pubsub topics (e.g. when choosing <em>named sharding</em> as specified in <a href="/spec/51">51/WAKU2-RELAY-SHARDING</a>).</p>
<h3 id="pubsub-topic-format">
Pubsub Topic Format
<a class="anchor" href="#pubsub-topic-format">#</a>
</h3>
<p>Pubsub topics SHOULD follow the following structure:</p>
<p><code>/waku/2/{topic-name}</code></p>
<p>This namespaced structure makes compatibility, discoverability, and automatic handling of new topics easier.</p>
<p>The first two parts indicate</p>
<ol>
<li>it relates to the Waku protocol domain, and</li>
<li>the version is 2.</li>
</ol>
<p>If applicable, it is RECOMMENDED to structure <code>{topic-name}</code> in a hierarchical way as well.</p>
<blockquote>
<p><em>Note</em>: In previous versions of this document, the structure was <code>/waku/2/{topic-name}/{encoding}</code>.
The now deprecated <code>/{encoding}</code> was always set to <code>/proto</code>,
which indicated that the <a href="/spec/11/#protobuf-definition">data field</a> in pubsub is serialized/encoded as protobuf.
The inspiration for this format was taken from
<a href="https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/p2p-interface.md#topics-and-messages">Ethereum 2 P2P spec</a>.
However, because the payload of messages transmitted over <a href="/spec/11">11/WAKU2-RELAY</a> must be a <a href="/spec/14">14/WAKU2-MESSAGE</a>,
which specifies the wire format as protobuf,<code>/proto</code> is the only valid encoding.
This makes the <code>/proto</code> indication obsolete.
The encoding of the <code>payload</code> field of a Waku Message is indicated by the <code>/{encoding}</code> part of the content topic name.
Specifying an encoding is only significant for the actual payload/data field.
Waku preserves this option by allowing to specify an encoding for the WakuMessage payload field as part of the content topic name.</p>
</blockquote>
<h3 id="default-pubsub-topic">
Default PubSub Topic
<a class="anchor" href="#default-pubsub-topic">#</a>
</h3>
<p>The Waku v2 default pubsub topic is:</p>
<p><code>/waku/2/default-waku/proto</code></p>
<p>The <code>{topic name}</code> part is <code>default-waku/proto</code>, which indicates it is default topic for exchanging WakuMessages;
<code>/proto</code> remains for backwards compatibility.</p>
<h3 id="application-specific-names">
Application Specific Names
<a class="anchor" href="#application-specific-names">#</a>
</h3>
<p>Larger apps can segregate their pubsub meshes using topics named like:</p>
<pre tabindex="0"><code>/waku/2/status/
/waku/2/walletconnect/
</code></pre><p>This indicates that these networks carry WakuMessages, but for different domains completely.</p>
<h3 id="named-topic-sharding-example">
Named Topic Sharding Example
<a class="anchor" href="#named-topic-sharding-example">#</a>
</h3>
<p>The following is an example of named sharding, as specified in <a href="/spec/51">51/WAKU2-RELAY-SHARDING</a>.</p>
<pre tabindex="0"><code>waku/2/waku-9_shard-0/
...
waku/2/waku-9_shard-9/
</code></pre><p>This indicates explicitly that the network traffic has been partitioned into 10 buckets.</p>
<h2 id="content-topics">
Content Topics
<a class="anchor" href="#content-topics">#</a>
</h2>
<p>The other type of topic that exists in Waku v2 is a content topic.
This is used for content based filtering.
See <a href="/spec/14">14/WAKU2-MESSAGE spec</a> for where this is specified.
Note that this doesn&rsquo;t impact routing of messages between relaying nodes,
but it does impact how request/reply protocols such as
<a href="https://rfc.vac.dev/spec/12/">12/WAKU2-FILTER</a> and <a href="https://rfc.vac.dev/spec/13/">13/WAKU2-STORE</a> are used.</p>
<p>This is especially useful for nodes that have limited bandwidth,
and only want to pull down messages that match this given content topic.</p>
<p>Since all messages are relayed using the relay protocol regardless of content topic,
you MAY use any content topic you wish without impacting how messages are relayed.</p>
<h3 id="content-topic-format">
Content Topic Format
<a class="anchor" href="#content-topic-format">#</a>
</h3>
<p>The format for content topics is as follows:</p>
<p><code>/{application-name}/{version-of-the-application}/{content-topic-name}/{encoding}</code></p>
<p>The name of a content topic is application-specific.
As an example, here&rsquo;s the content topic used for an upcoming testnet:</p>
<p><code>/toychat/2/huilong/proto</code></p>
<h3 id="content-topic-naming-recommendations">
Content Topic Naming Recommendations
<a class="anchor" href="#content-topic-naming-recommendations">#</a>
</h3>
<p>Application names should be unique to avoid conflicting issues with other protocols.
Applications should specify their version (if applicable) in the version field.
The <code>{content-topic-name}</code> portion of the content topic is up to the application,
and depends on the problem domain.
It can be hierarchical, for instance to separate content, or to indicate different bandwidth and privacy guarantees.
The encoding field indicates the serialization/encoding scheme for the <a href="/spec/14/#payloads">WakuMessage payload</a> field.</p>
<h2 id="differences-with-waku-v1">
Differences with Waku v1
<a class="anchor" href="#differences-with-waku-v1">#</a>
</h2>
<p>In <a href="/spec/6">6/WAKU1</a> there is no actual routing.
All messages are sent to all other nodes.
This means that we are implicitly using the same pubsub topic that would be something like:</p>
<pre tabindex="0"><code>/waku/1/default-waku/rlp
</code></pre><p>Topics in Waku v1 correspond to Content Topics in Waku v2.</p>
<h3 id="bridging-waku-v1-and-waku-v2">
Bridging Waku v1 and Waku v2
<a class="anchor" href="#bridging-waku-v1-and-waku-v2">#</a>
</h3>
<p>To bridge Waku v1 and Waku v2 we have a <a href="/spec/15">15/WAKU-BRIDGE</a>.
For mapping Waku v1 topics to Waku v2 content topics,
the following structure for the content topic SHOULD be used:</p>
<pre tabindex="0"><code>/waku/1/&lt;4bytes-waku-v1-topic&gt;/rfc26
</code></pre><p>The <code>&lt;4bytes-waku-v1-topic&gt;</code> SHOULD be the lowercase hex representation of the 4-byte Waku v1 topic.
A <code>0x</code> prefix SHOULD be used.
<code>/rfc26</code> indicates that the bridged content is encoded according to RFC <a href="/spec/26">26/WAKU-PAYLOAD</a>.
See <a href="/spec/15">15/WAKU-BRIDGE</a> for a description of the bridged fields.</p>
<p>This creates a direct mapping between the two protocols.
For example:</p>
<pre tabindex="0"><code>/waku/1/0x007f80ff/rfc26
</code></pre><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>
<ul>
<li><a href="/spec/10">10/WAKU2 spec</a></li>
<li><a href="/spec/11">11/WAKU2-RELAY</a></li>
<li><a href="/spec/51">51/WAKU2-RELAY-SHARDING</a></li>
<li><a href="https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/p2p-interface.md#topics-and-messages">Ethereum 2 P2P spec</a></li>
<li><a href="/spec/14">14/WAKU2-MESSAGE spec</a></li>
<li><a href="https://rfc.vac.dev/spec/12/">12/WAKU2-FILTER</a></li>
<li><a href="https://rfc.vac.dev/spec/13/">13/WAKU2-STORE</a></li>
<li><a href="/spec/6">6/WAKU1</a></li>
<li><a href="/spec/15">15/WAKU-BRIDGE</a></li>
<li><a href="/spec/26">26/WAKU-PAYLOAD</a></li>
</ul>
</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>
<ul>
<li><a href="#pubsub-topics">Pubsub Topics</a>
<ul>
<li><a href="#pubsub-topic-format">Pubsub Topic Format</a></li>
<li><a href="#default-pubsub-topic">Default PubSub Topic</a></li>
<li><a href="#application-specific-names">Application Specific Names</a></li>
<li><a href="#named-topic-sharding-example">Named Topic Sharding Example</a></li>
</ul>
</li>
<li><a href="#content-topics">Content Topics</a>
<ul>
<li><a href="#content-topic-format">Content Topic Format</a></li>
<li><a href="#content-topic-naming-recommendations">Content Topic Naming Recommendations</a></li>
</ul>
</li>
<li><a href="#differences-with-waku-v1">Differences with Waku v1</a>
<ul>
<li><a href="#bridging-waku-v1-and-waku-v2">Bridging Waku v1 and Waku v2</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#copyright">Copyright</a></li>
<li><a href="#references">References</a></li>
</ul>
</nav>
</div>
</aside>
</main>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink