Proposal: Waku v2 peer discovery via DNS

[jm-clius]

1. Abstract

This document proposes a scheme to implement libp2p peer discovery via DNS in nim-waku. The main purpose is to retrieve an arbitrarily long, authenticated, updateable list of libp2p peers to bootstrap connection to a libp2p network. Since Waku v2 currently implements libp2p, this method is suitable for a new Waku v2 node to discover other Waku v2 nodes to connect to.

This proposal is largely based on EIP-1459, with the only deviation being the type of address being encoded (multiaddr vs enr). Also see Dean's earlier explainer for more background.

2. List encoding

The peer list is encoded as a Merkle tree. EIP-1459 specifies the URL scheme to refer to such a DNS node list. This proposal uses the same approach, but with a matree scheme:

matree://<key>@<fqdn>

where

• matree is the selected multiaddr Merkle tree scheme
• <fqdn> is the fully qualified domain name on which the list can be found
• <key> is the base32 encoding of the compressed 32-byte binary public key that signed the list.

The example URL from EIP-1459, adapted to the above scheme becomes:

matree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@peers.example.org

Each entry within the Merkle tree is contained within a DNS TXT record and is stored in a subdomain (except for the base URL matree 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 this example of a fully populated tree for more information.

3. Entry types

The following entry types are derived from EIP-1459 and adapted for use with multiaddrs:

3.1. Root entry

The tree root entry has the following format:

matree-root:v1 m=<ma-root> l=<link-root> seq=<sequence number> sig=<signature>

where

• ma-root and link-root refer to the root hashes of subtrees containing multiaddrs and links to other subtrees, respectively
• sequence-number is the tree's update sequence number. This number SHOULD increase with each update to the tree.
• signature is a 65-byte secp256k1 EC signature over the keccak256 hash of the root record content, excluding the sig= part, encoded as URL-safe base64

3.2. Branch entry

Branch entries take the format:

matree-branch:<h₁>,<h₂>,...,<hₙ>

where

• <h₁>,<h₂>,...,<hₙ> are the hashes of other subtree entries

3.3. Leaf entries

There are two types of leaf entries.

3.3.1. Link entries

For the subtree pointed to by link-root, leaf entries take the format:

matree://<key>@<fqdn>

which links to a different list located in another domain.

3.3.2. multiaddr entries

For the subtree pointed to by ma-root, leaf entries take the format:

ma:<multiaddr>

which contains the multiaddr of a libp2p peer.

4. Work breakdown

In order to implement the above proposal in Nim and specifically for Waku v2, the following discrete efforts can be identified. The overall approach is based on the geth implementation of EIP-1459. Each component below can be seen as a sub-task of the greater effort. Except for the work on the specification, each component roughly corresponds to a separate Nim module.

4.1. Specification

Once some consensus is reached on the proposal above, it must be raised to a raw specification.

4.2. DNS Resolver

The DNS Resolver is able to lookup TXT records from a given subdomain. This component is easy to stub, so can be developed last.

4.3. Merkle tree

This is the core implementation of a Merkle tree constructed from the entry types listed above.
It must be able to:

• parse each entry type,
• traverse a tree and retrieve all leaf nodes,
• validate hashes
  etc.

4.3. DNS Discovery Client

A client find peers by downloading and interacting with the Merkle tree. It makes use of synchronisation utilities to do so.

A client MUST adhere to the client protocol specified in EIP-1459. I partially repeat it here for clarity and to specify usage with multiaddr entry types.
To find nodes at a given DNS name a client performs the following steps:

1. Resolve the TXT record of the name and check whether it contains a valid matree-root:v1 entry.
2. 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.
3. Resolve the TXT record of a hash subdomain indicated in the record and verify that the content matches the hash.
4. If the resolved entry is of type:
   • matree-branch: parse the list of hashes and continue resolving them (step 3).
   • ma: import the multiaddr and add it to a local list of discovered nodes.

[jm-clius]

cc @oskarth @staheri14 @EbubeUd

[oskarth]

Thanks for the detailed write-up, I might have more specific feedback later but in general LGTM!

[oskarth]

Generic message follows

I'm going to go ahead and close this discussion as:

1. It is quite old and we are moving away from GH discussions (in favor of either forum.vac.dev or normal issues)

2. Existing discussion has evolved and is captured in more targeted issues already

If you feel like this is in error, please create a thread on Vac forum or a new issue.