---
slug: 25
title: 25/LIBP2P-DNS-DISCOVERY
name: Libp2p Peer Discovery via DNS
status: raw
editor: Hanno Cornelius <hanno@status.im>
contributors:
---

`25/LIBP2P-DNS-DISCOVERY` specifies a scheme to implement [`libp2p`](https://libp2p.io/) peer discovery via DNS for Waku v2.
The generalised purpose is to retrieve an arbitrarily long, authenticated, updateable list of [`libp2p` peers](https://docs.libp2p.io/concepts/peer-id/) to bootstrap connection to a `libp2p` network.
Since [`10/WAKU2`](https://rfc.vac.dev/spec/10/) currently specifies use of [`libp2p` peer identities](https://docs.libp2p.io/concepts/peer-id/),
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](https://eips.ethereum.org/EIPS/eip-1459),
with the only deviation being the type of address being encoded (`multiaddr` vs `enr`).
Also see [this earlier explainer](https://vac.dev/dns-based-discovery) 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](https://www.wikiwand.com/en/Merkle_tree).
EIP-1459 specifies [the URL scheme](https://eips.ethereum.org/EIPS/eip-1459#specification) 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](https://www.rfc-editor.org/rfc/rfc1035.txt)
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](https://eips.ethereum.org/EIPS/eip-1459#dns-record-structure) of a fully populated tree for more information.

# Entry types

The following entry types are derived from [EIP-1459](https://eips.ethereum.org/EIPS/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](https://eips.ethereum.org/EIPS/eip-1459#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](https://creativecommons.org/publicdomain/zero/1.0/).

# References

1. [`10/WAKU2`](https://rfc.vac.dev/spec/10/)
1. [EIP-1459: Client Protocol](https://eips.ethereum.org/EIPS/eip-1459#client-protocol)
1. [EIP-1459: Node Discovery via DNS ](https://eips.ethereum.org/EIPS/eip-1459)
1. [`libp2p`](https://libp2p.io/)
1. [`libp2p` peer identity](https://docs.libp2p.io/concepts/peer-id/)
1. [Merkle trees](https://www.wikiwand.com/en/Merkle_tree)