nwaku/docs/tutorial/dns-disc.md

4.3 KiB

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. According to EIP-1459, the peer list is encoded as a Merkle tree of TXT records. Connectivity information for each peer, including wire address and peer ID, are encapsulated in signed Ethereum Node Records (ENR).

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, which uses a multiaddr scheme.

The ENR is constructed according to 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. 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 or chat2 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 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