diff --git a/vac/25/libp2p-dns-discovery.md b/vac/25/libp2p-dns-discovery.md new file mode 100644 index 0000000..a15e4e2 --- /dev/null +++ b/vac/25/libp2p-dns-discovery.md @@ -0,0 +1,134 @@ +--- +slug: 25 +title: 25/LIBP2P-DNS-DISCOVERY +name: Libp2p Peer Discovery via DNS +status: deleted +editor: Hanno Cornelius +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://@ +``` + +where +- `matree` is the selected `multiaddr` Merkle tree scheme +- `` is the fully qualified domain name on which the list can be found +- `` 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= l= seq= sig= +``` + +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:,,..., +``` + +where +- `,,...,` 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://@ +``` + +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: +``` + +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)