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="25/LIBP2P-DNS-DISCOVERY specifies a scheme to implement libp2p peer discovery via DNS for Waku v2. The generalised purpose is to retrieve an arbitrarily long, authenticated, updateable list of libp2p peers to bootstrap connection to a libp2p network. Since 10/WAKU2 currently specifies use of libp2p peer identities, this method is suitable for a new Waku v2 node to discover other Waku v2 nodes to connect to.
|
|
This specification is largely based on EIP-1459, with the only deviation being the type of address being encoded (multiaddr vs enr).">
|
|
<meta name="theme-color" content="#FFFFFF"><meta property="og:title" content="25/LIBP2P-DNS-DISCOVERY" />
|
|
<meta property="og:description" content="25/LIBP2P-DNS-DISCOVERY specifies a scheme to implement libp2p peer discovery via DNS for Waku v2. The generalised purpose is to retrieve an arbitrarily long, authenticated, updateable list of libp2p peers to bootstrap connection to a libp2p network. Since 10/WAKU2 currently specifies use of libp2p peer identities, this method is suitable for a new Waku v2 node to discover other Waku v2 nodes to connect to.
|
|
This specification is largely based on EIP-1459, with the only deviation being the type of address being encoded (multiaddr vs enr)." />
|
|
<meta property="og:type" content="article" />
|
|
<meta property="og:url" content="https://rfc.vac.dev/spec/25/" /><meta property="article:section" content="docs" />
|
|
|
|
|
|
|
|
<title>25/LIBP2P-DNS-DISCOVERY | 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.63d0833c2423f05762cd743afc2b2d78c13d564374d961f99ba488bac6a2beef.js" integrity="sha256-Y9CDPCQj8FdizXQ6/CsteME9VkN02WH5m6SIusaivu8="></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>
|
|
<li><a href="/spec/66/">66/WAKU2-METADATA</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/">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>
|
|
<li><a href="/spec/65/">65/STATUS-ACCOUNTS</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>25/LIBP2P-DNS-DISCOVERY</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="#list-encoding">List encoding</a></li>
|
|
<li><a href="#entry-types">Entry types</a>
|
|
<ul>
|
|
<li><a href="#root-entry">Root entry</a></li>
|
|
<li><a href="#branch-entry">Branch entry</a></li>
|
|
<li><a href="#leaf-entries">Leaf entries</a>
|
|
<ul>
|
|
<li><a href="#link-entries">Link entries</a></li>
|
|
<li><a href="#multiaddr-entries"><code>multiaddr</code> entries</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#client-protocol">Client protocol</a></li>
|
|
<li><a href="#copyright">Copyright</a></li>
|
|
<li><a href="#references">References</a></li>
|
|
</ul>
|
|
</nav>
|
|
|
|
|
|
|
|
</aside>
|
|
|
|
|
|
</header>
|
|
|
|
|
|
|
|
<article class="markdown">
|
|
<h1 id="25libp2p-dns-discovery">
|
|
25/LIBP2P-DNS-DISCOVERY
|
|
<a class="anchor" href="#25libp2p-dns-discovery">#</a>
|
|
</h1>
|
|
|
|
|
|
<h1 id="libp2p-peer-discovery-via-dns">
|
|
Libp2p Peer Discovery via DNS
|
|
<a class="anchor" href="#libp2p-peer-discovery-via-dns">#</a>
|
|
</h1>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
<li>Status: deleted</li>
|
|
<li>Editor: Hanno Cornelius <a href="mailto:hanno@status.im">hanno@status.im</a></li>
|
|
|
|
</ul><p><code>25/LIBP2P-DNS-DISCOVERY</code> specifies a scheme to implement <a href="https://libp2p.io/"><code>libp2p</code></a> peer discovery via DNS for Waku v2.
|
|
The generalised purpose is to retrieve an arbitrarily long, authenticated, updateable list of <a href="https://docs.libp2p.io/concepts/peer-id/"><code>libp2p</code> peers</a> to bootstrap connection to a <code>libp2p</code> network.
|
|
Since <a href="https://rfc.vac.dev/spec/10/"><code>10/WAKU2</code></a> currently specifies use of <a href="https://docs.libp2p.io/concepts/peer-id/"><code>libp2p</code> peer identities</a>,
|
|
this method is suitable for a new Waku v2 node to discover other Waku v2 nodes to connect to.</p>
|
|
<p>This specification is largely based on <a href="https://eips.ethereum.org/EIPS/eip-1459">EIP-1459</a>,
|
|
with the only deviation being the type of address being encoded (<code>multiaddr</code> vs <code>enr</code>).
|
|
Also see <a href="https://vac.dev/dns-based-discovery">this earlier explainer</a> for more background on the suitability of DNS based discovery for Waku v2.</p>
|
|
<h1 id="list-encoding">
|
|
List encoding
|
|
<a class="anchor" href="#list-encoding">#</a>
|
|
</h1>
|
|
<p>The peer list MUST be encoded as a <a href="https://www.wikiwand.com/en/Merkle_tree">Merkle tree</a>.
|
|
EIP-1459 specifies <a href="https://eips.ethereum.org/EIPS/eip-1459#specification">the URL scheme</a> to refer to such a DNS node list.
|
|
This specification uses the same approach, but with a <code>matree</code> scheme:</p>
|
|
<pre tabindex="0"><code>matree://<key>@<fqdn>
|
|
</code></pre><p>where</p>
|
|
<ul>
|
|
<li><code>matree</code> is the selected <code>multiaddr</code> Merkle tree scheme</li>
|
|
<li><code><fqdn></code> is the fully qualified domain name on which the list can be found</li>
|
|
<li><code><key></code> is the base32 encoding of the compressed 32-byte binary public key that signed the list.</li>
|
|
</ul>
|
|
<p>The example URL from EIP-1459, adapted to the above scheme becomes:</p>
|
|
<pre tabindex="0"><code>matree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@peers.example.org
|
|
</code></pre><p>Each entry within the Merkle tree MUST be contained within a <a href="https://www.rfc-editor.org/rfc/rfc1035.txt">DNS TXT record</a>
|
|
and stored in a subdomain (except for the base URL <code>matree</code> entry).
|
|
The content of any TXT record MUST be small enough to fit into the 512-byte limit imposed on UDP DNS packets,
|
|
which limits the number of hashes that can be contained within a branch entry.
|
|
The subdomain name for each entry is the base32 encoding of the abbreviated keccak256 hash of its text content.
|
|
See <a href="https://eips.ethereum.org/EIPS/eip-1459#dns-record-structure">this example</a> of a fully populated tree for more information.</p>
|
|
<h1 id="entry-types">
|
|
Entry types
|
|
<a class="anchor" href="#entry-types">#</a>
|
|
</h1>
|
|
<p>The following entry types are derived from <a href="https://eips.ethereum.org/EIPS/eip-1459">EIP-1459</a>
|
|
and adapted for use with <code>multiaddrs</code>:</p>
|
|
<h2 id="root-entry">
|
|
Root entry
|
|
<a class="anchor" href="#root-entry">#</a>
|
|
</h2>
|
|
<p>The tree root entry MUST use the following format:</p>
|
|
<pre tabindex="0"><code>matree-root:v1 m=<ma-root> l=<link-root> seq=<sequence number> sig=<signature>
|
|
</code></pre><p>where</p>
|
|
<ul>
|
|
<li><code>ma-root</code> and <code>link-root</code> refer to the root hashes of subtrees
|
|
containing <code>multiaddrs</code> and links to other subtrees, respectively</li>
|
|
<li><code>sequence-number</code> is the tree’s update sequence number.
|
|
This number SHOULD increase with each update to the tree.</li>
|
|
<li><code>signature</code> is a 65-byte secp256k1 EC signature
|
|
over the keccak256 hash of the root record content,
|
|
excluding the <code>sig=</code> part,
|
|
encoded as URL-safe base64</li>
|
|
</ul>
|
|
<h2 id="branch-entry">
|
|
Branch entry
|
|
<a class="anchor" href="#branch-entry">#</a>
|
|
</h2>
|
|
<p>Branch entries MUST take the format:</p>
|
|
<pre tabindex="0"><code>matree-branch:<h₁>,<h₂>,...,<hₙ>
|
|
</code></pre><p>where</p>
|
|
<ul>
|
|
<li><code><h₁>,<h₂>,...,<hₙ></code> are the hashes of other subtree entries</li>
|
|
</ul>
|
|
<h2 id="leaf-entries">
|
|
Leaf entries
|
|
<a class="anchor" href="#leaf-entries">#</a>
|
|
</h2>
|
|
<p>There are two types of leaf entries:</p>
|
|
<h3 id="link-entries">
|
|
Link entries
|
|
<a class="anchor" href="#link-entries">#</a>
|
|
</h3>
|
|
<p>For the subtree pointed to by <code>link-root</code>,
|
|
leaf entries MUST take the format:</p>
|
|
<pre tabindex="0"><code>matree://<key>@<fqdn>
|
|
</code></pre><p>which links to a different list located in another domain.</p>
|
|
<h3 id="multiaddr-entries">
|
|
<code>multiaddr</code> entries
|
|
<a class="anchor" href="#multiaddr-entries">#</a>
|
|
</h3>
|
|
<p>For the subtree pointed to by <code>ma-root</code>,
|
|
leaf entries MUST take the format:</p>
|
|
<pre tabindex="0"><code>ma:<multiaddr>
|
|
</code></pre><p>which contains the <code>multiaddr</code> of a <code>libp2p</code> peer.</p>
|
|
<h1 id="client-protocol">
|
|
Client protocol
|
|
<a class="anchor" href="#client-protocol">#</a>
|
|
</h1>
|
|
<p>A client MUST adhere to the <a href="https://eips.ethereum.org/EIPS/eip-1459#client-protocol">client protocol</a> as specified in EIP-1459,
|
|
and adapted for usage with <code>multiaddr</code> entry types below:</p>
|
|
<p>To find nodes at a given DNS name a client MUST perform the following steps:</p>
|
|
<ol>
|
|
<li>Resolve the TXT record of the DNS name and check whether it contains a valid <code>matree-root:v1</code> entry.</li>
|
|
<li>Verify the signature on the root against the known public key
|
|
and check whether the sequence number is larger than or equal to any previous number seen for that name.</li>
|
|
<li>Resolve the TXT record of a hash subdomain indicated in the record
|
|
and verify that the content matches the hash.</li>
|
|
<li>If the resolved entry is of type:
|
|
<ul>
|
|
<li><code>matree-branch</code>: parse the list of hashes and continue resolving them (step 3).</li>
|
|
<li><code>ma</code>: import the <code>multiaddr</code> and add it to a local list of discovered nodes.</li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
<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/"><code>10/WAKU2</code></a></li>
|
|
<li><a href="https://eips.ethereum.org/EIPS/eip-1459#client-protocol">EIP-1459: Client Protocol</a></li>
|
|
<li><a href="https://eips.ethereum.org/EIPS/eip-1459">EIP-1459: Node Discovery via DNS </a></li>
|
|
<li><a href="https://libp2p.io/"><code>libp2p</code></a></li>
|
|
<li><a href="https://docs.libp2p.io/concepts/peer-id/"><code>libp2p</code> peer identity</a></li>
|
|
<li><a href="https://www.wikiwand.com/en/Merkle_tree">Merkle trees</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="#list-encoding">List encoding</a></li>
|
|
<li><a href="#entry-types">Entry types</a>
|
|
<ul>
|
|
<li><a href="#root-entry">Root entry</a></li>
|
|
<li><a href="#branch-entry">Branch entry</a></li>
|
|
<li><a href="#leaf-entries">Leaf entries</a>
|
|
<ul>
|
|
<li><a href="#link-entries">Link entries</a></li>
|
|
<li><a href="#multiaddr-entries"><code>multiaddr</code> entries</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#client-protocol">Client protocol</a></li>
|
|
<li><a href="#copyright">Copyright</a></li>
|
|
<li><a href="#references">References</a></li>
|
|
</ul>
|
|
</nav>
|
|
|
|
|
|
|
|
</div>
|
|
</aside>
|
|
|
|
</main>
|
|
|
|
|
|
</body>
|
|
|
|
</html>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|