mirror of https://github.com/waku-org/nwaku.git
Add basic tutorial for Waku v2 DNS-based discovery (#711)
* Added basic tutorial for Waku v2 DNS-based discovery
This commit is contained in:
Hanno Cornelius
GitHub
parent
f1ac1e9cf5
commit
d74ef67087
|
|
@ -6,7 +6,7 @@ This release contains the following:
|
|||
|
||||
### Features
|
||||
|
||||
- Start of Waku node discovery via DNS following [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459)
|
||||
- Waku v2 node discovery via DNS following [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459)
|
||||
|
||||
### Changes
|
||||
|
||||
|
|
@ -18,6 +18,7 @@ This release contains the following:
|
|||
#### Docs
|
||||
|
||||
- Added contributor guidelines on Waku v2 fleet monitoring and management.
|
||||
- Added basic tutorial on using Waku v2 DNS-based discovery
|
||||
|
||||
#### Schema
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,71 @@
|
|||
# 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
|
||||
```
|
||||
Loading…
Reference in New Issue