# 25/LIBP2P-DNS-DISCOVERY | Vac Research
- Status: deleted

Skip to main content

# 25/LIBP2P-DNS-DISCOVERY

- Status: deleted
- Editor: Hanno Cornelius <hanno@status.im>

`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`). Also see this earlier explainer for more background on the suitability of DNS based discovery for Waku v2.

## List encoding​

The peer list MUST be encoded as a Merkle tree. EIP-1459 specifies the URL scheme to refer to such a DNS node list. This specification 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 MUST be contained within a DNS TXT record and 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.

## Entry types​

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

## Root entry​

The tree root entry MUST use 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

## Branch entry​

Branch entries MUST take the format:

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

where

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

## Leaf entries​

There are two types of leaf entries:

### Link entries​

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

    matree://<key>@<fqdn>

which links to a different list located in another domain.

### `multiaddr` entries​

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

    ma:<multiaddr>

which contains the `multiaddr` of a `libp2p` peer.

## Client protocol​

A client MUST adhere to the client protocol as specified in EIP-1459, and adapted for usage with `multiaddr` entry types below:

To find nodes at a given DNS name a client MUST perform the following steps:

1. Resolve the TXT record of the DNS 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.

## Copyright​

Copyright and related rights waived via CC0.

## References​

1. `10/WAKU2`
2. EIP-1459: Client Protocol
3. EIP-1459: Node Discovery via DNS
4. `libp2p`
5. `libp2p` peer identity
6. Merkle trees