From 5ee72ee8bfd8b8646c9e5cca55c64db93a203cf6 Mon Sep 17 00:00:00 2001 From: "fryorcraken.eth" Date: Tue, 6 Jun 2023 16:27:17 +1000 Subject: [PATCH 1/2] add diagrams to explain discovery --- static/discv5.md | 29 +++++++++++++++++++++++++++++ static/dns_discovery.md | 20 ++++++++++++++++++++ static/peer_exchange.md | 22 ++++++++++++++++++++++ 3 files changed, 71 insertions(+) create mode 100644 static/discv5.md create mode 100644 static/dns_discovery.md create mode 100644 static/peer_exchange.md diff --git a/static/discv5.md b/static/discv5.md new file mode 100644 index 0000000..ebfeb8e --- /dev/null +++ b/static/discv5.md @@ -0,0 +1,29 @@ + +```mermaid +sequenceDiagram + Alice->>DNS Server: (1) Execute DNS Discovery + DNS Server-->>Alice: (2) Bob's connection details (UDP + TCP) + activate Alice + Alice->>Bob: (3) Execute Discv5 over UDP + Bob-->>Alice: (4) ENRs (UDP + TCP): Carol, David, Erin + Alice->>Alice: (5) Decode ENRs + Alice->>Carol: (6) Execute Discv5 over UDP + Carol-->>Alice: (7) ENRs (UDP + TCP): Frank, Gwen, Harry + Alice->>Alice: (8) Decode ENRs + deactivate Alice + Alice->>Alice: (9) Select peers to dial + Alice->>David: (10) Libp2p dial (TCP) + Alice->>Frank: (10) Libp2p dial (TCP) + Alice->>Gwen: (10) Libp2p dial (TCP) +``` + +1. DNS Discovery protocol is executed. +2. Alice's retrieves Bob's ENR (Ethereum Node Record) from DNS Server. +3. Alice executes Discv5 protocol with Bob using UDP connection details from ENR. +4. Bob returns Carol's, David's and Erin's ENRs to Alice. +5. Alice Decodes ENRs and extracts Carol's, David's and Erin's TCP and UDP connections details. +6. Alice executes Discv5 protocol with Carol using UDP connection details from ENR. +7. Carol returns Frank's, Gwen's and Harry's ENRs to Alice. +8. Alice Decodes ENRs and extracts Frank's, Gwen's and Harry's TCP and UDP connections details. +9. Alice selects to dial David, Frank and Gwen. +10. Alice dials David, Frank and Gwen over libp2p using TCP connections details from ENRs. diff --git a/static/dns_discovery.md b/static/dns_discovery.md new file mode 100644 index 0000000..e7a2e85 --- /dev/null +++ b/static/dns_discovery.md @@ -0,0 +1,20 @@ + + +```mermaid +sequenceDiagram + Waku Node->>DNS Server: (1) Lookup TXT example.com + DNS Server-->>Waku Node: (2) enrtree-root:v1 e=U3...3Y ... + Waku Node->>DNS Server: (3) Lookup TXT U3...3Y.example.com + DNS Server-->>Waku Node: (4) enrtree-branch:DU...VQ,J3..HU,IC...WE + Waku Node->> DNS Server: (5) Lookup TXT DU...VQ.example.com + DNS Server-->>Waku Node: (6) enr:-M-4QLdAB-Kyz...Wt1Mg8 + Waku Node ->> Waku Node: (7) Decode ENR: Peer's connection details +``` + +1. DNS lookup query to retrieve TXT data stored on `example.com` domain. +2. `entree-root` is returned, value of `e` is the `enr-root`, root hash of the node subtree. +3. DNS lookup query to retrieve TXT data stored on `.example.com` domain. +4. `entree-branch` is returned, this tree contains hashes of node subtrees. +5. DNS lookup query to retrieve TXT data stored on, `DU...VQ.example.com` domain, the first leaf of `entree-branch`. +6. `enr` record is returned. +7. Returned value is decoded, peer connection details such as ip address and port are learned. diff --git a/static/peer_exchange.md b/static/peer_exchange.md new file mode 100644 index 0000000..6390362 --- /dev/null +++ b/static/peer_exchange.md @@ -0,0 +1,22 @@ + +```mermaid +sequenceDiagram + Alice->>DNS Server: (1) Execute DNS Discovery + DNS Server-->>Alice: (2) Bob's multiaddr (websocket) + Alice-->>Bob: (3) Dial + Alice->>Bob: (4) Peer Exchange Query + Bob-->>Alice: (5) Carol's ENR, David's ENR + Alice->>Alice: (6) Decode ENRs + Alice->>Carol: (7) Dial + Alice->>David: (7) Dial + Alice-->>Bob: (8) Disconnect +``` + +1. DNS Discovery protocol is executed. +2. Alice's retrieves Bob's websocket multiaddr from DNS Server. +3. Alice dials Bob using libp2p protocols. +4. Alice executes a Peer Exchange Query to Bob. +5. Bob returns Carol's and David's ENR to Alice. +6. Alice Decodes ENRs and extracts Carol's and David's websocket multiaddrs. +7. Alice dials Carol and David. +8. Alice can now drop the connection with Bob (bootstrap node), Alice has 2 connections to the Waku Network. From 445f78017ade05b13270e5cfe987be073b7cd333 Mon Sep 17 00:00:00 2001 From: "fryorcraken.eth" Date: Tue, 6 Jun 2023 16:40:12 +1000 Subject: [PATCH 2/2] add enrtree to dict --- .cspell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.cspell.json b/.cspell.json index 0eab76b..b05c6d3 100644 --- a/.cspell.json +++ b/.cspell.json @@ -15,6 +15,7 @@ "nwaku", "deanonymization", "ECIES", + "enrtree", "Discv5", "Gossipsub", "LIGHTPUSH",