nwaku/docs/tutorial/dns-disc.md

72 lines
4.3 KiB
Markdown
Raw Normal View History

# Waku v2 DNS-based Discovery Basic Tutorial
## Background
Waku v2 DNS discovery is a method by which a node may find other peers by retrieving an encoded node list via DNS.
To achieve this, Waku v2 uses a Nim implementation of [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459).
According to EIP-1459, the peer list is encoded as a [Merkle tree](https://www.wikiwand.com/en/Merkle_tree) of TXT records.
Connectivity information for each peer, including [wire address](https://docs.libp2p.io/concepts/addressing/) and [peer ID](https://docs.libp2p.io/concepts/peer-id/), are encapsulated in signed [Ethereum Node Records (ENR)](https://eips.ethereum.org/EIPS/eip-778).
## Mapping ENR to `multiaddr`
EIP-1459 DNS discovery is a scheme for retrieving an ENR list via DNS.
Waku v2 addressing is based on [libp2p addressing](https://docs.libp2p.io/concepts/addressing/), which uses a `multiaddr` scheme.
The ENR is constructed according to [EIP-778](https://eips.ethereum.org/EIPS/eip-778).
It maps to the equivalent `libp2p` `multiaddr` for the Waku v2 node as follows:
| ENR Key | ENR Value |
|-------------|------------------------------------------------------------------------|
| `id` | name of identity scheme. For Waku v2 generally `v4` |
| `secp256k1` | the compressed `secp256k1` public key belong to the libp2p peer ID as per [specification](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#keys). This is used to construct the `/p2p/` portion of the node's `multiaddr` |
| ip | IPv4 address. Corresponds to `/ip4/` portion of the node's `multiaddr` |
| tcp | TCP port. Corresponds to `/tcp/` portion of the node's `multiaddr` |
The `nim-waku` implementation with integrated DNS discovery already takes care of the ENR to `multiaddr` conversion.
## Usage
Ensure you have built [`wakunode2`](https://github.com/status-im/nim-waku) or [`chat2`](./chat2.md) as per the linked instructions.
The following command line options are available for both `wakunode2` or `chat2`.
```
--dns-discovery Enable DNS Discovery
--dns-discovery-url URL for DNS node list in format 'enrtree://<key>@<fqdn>'
--dns-discovery-name-server DNS name server IPs to query. Argument may be repeated.
```
- `--dns-discovery` is used to enable DNS discovery on the node. Waku DNS discovery is disabled by default.
- `--dns-discovery-url` is mandatory if DNS discovery is enabled. It contains the URL for the node list. The URL must be in the format `enrtree://<key>@<fqdn>` where `<fqdn>` is the fully qualified domain name and `<key>` is the base32 encoding of the compressed 32-byte public key that signed the list at that location. See [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459#specification) or the example below to illustrate.
- `--dns-discovery-name-server` is optional and contains the IP(s) of the DNS name servers to query. If left unspecified, the Cloudflare servers `1.1.1.1` and `1.0.0.1` will be used by default.
A node will attempt connection to all discovered nodes.
## Example for `wakuv2.test` fleet
To illustrate the above and prove the concept,
a list of `wakuv2.test` fleet nodes was encoded according to EIP-1459 and deployed to `test.nodes.vac.dev`.
The list was signed by the public key `AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C`.
The complete URL for DNS discovery is therefore: `enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.nodes.vac.dev`.
To run a `wakunode2` with DNS-based discovery of `wakuv2.test` nodes:
```
./build/wakunode2 --dns-discovery:true --dns-discovery-url:enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.nodes.vac.dev
```
Similarly, for `chat2`:
```
./build/chat2 --dns-discovery:true --dns-discovery-url:enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.nodes.vac.dev
```
The node will discover and attempt connection to all `wakuv2.test` nodes during setup procedures.
To use specific DNS name servers, one or more `--dns-discovery-name-server` arguments can be added:
```
./build/wakunode2 --dns-discovery:true --dns-discovery-url:enrtree://AOFTICU2XWDULNLZGRMQS4RIZPAZEHYMV4FYHAPW563HNRAOERP7C@test.nodes.vac.dev --dns-dis
covery-name-server:8.8.8.8 --dns-discovery-name-server:8.8.4.4
```