Finish description of sequence diagram

Author: emhane

discv5/discv5-theory.md

@@ -527,11 +527,13 @@ registration algorithm if the same topic is being registered and searched for.
 
 ## Hole punch asymmetric NATs
 
+### Message flow
+
 The protocol introduces the notification packet kind. There are 4 total message
 containers, these are abbreviated in the sequence diagram below as follows:
 - m - message packet
-- whoareyou - WHOEAREYOU packet
-- hm - handshake message packet
+- whoareyou - [WHOEAREYOU] packet
+- hm - [handshake message packet]
 - n - notification packet
 
 ```mermaid
@@ -543,29 +545,61 @@ containers, these are abbreviated in the sequence diagram below as follows:
         Relay-->>Alice: m(NODES[Bob's ENR])
         Alice->>Bob: m(nonce,FINDNODE)
         Note left of Alice:Hole punched in Alice's NAT for Bob
+        Note left of Alice:FINDNODE timed out
         Alice->>Relay: n(RELAYINIT[nonce])
         Relay->>Bob:n(RELAYMSG[nonce])
         Bob-->>Alice: whoareyou(nonce)
         Note right of Bob: Hole punched in Bob's NAT for Alice
 ```
-Bob is behind a NAT. Bob is in Relay's kbuckets, they have a session together.
+Bob is behind a NAT. Bob is in Relay's kbuckets, they have a session together and Bob
+has sent a packet to Relay in the last ~20 seconds[^1].
 
-As part of a periodic recursive query to fill its kbuckets, Alice sends a FINDNODE
+As part of a periodic recursive query to fill its kbuckets, Alice sends a [FINDNODE]
 request to Bob, who's ENR it received from Relay. By making an outgoing request to
 Bob, if Alice is behind a NAT, Alice's NAT adds the filtering rule
 `(Alice's-LAN-ip, Alice's-LAN-port, Bob's-WAN-ip, Bob's-WAN-port, entry-lifetime)` to
-it's UDP session table [^1][^2]. The request to Bob times out as Bob is behind a NAT.
+it's UDP session table[^2][^3]. This means a hole now is punched for Bob in Alice's NAT
+for the duration of `entry-lifetime`. The request to Bob times out as Bob is behind a NAT.
+
+Alice initiates an attempt to punch a hole in Bob's NAT via Relay. Alice reset the request
+time out on the timed out [FINDNODE] message and wraps the message's nonce in a [RELAYINIT]
+notification and sends it to Relay. The notification also contains its ENR and Bob's node
+id.
+
+Relay disassembles the [RELAYINIT] notification and uses the `tgt-id` to look up Bob's
+ENR in its kbuckets. With high probability, Relay will find Bob's ENR in its kbuckets
+as ~1 second ago, Relay assembled a [NODES] response for Alice containing Bob's ENR (see 
+[UDP Communication] for recommended time out times). Relay assembles a [RELAYMSG]
+notification with Alice's message nonce and ENR, then sends it to the address in Bob's
+ENR.
+
+Bob disassembles the [RELAYMSG] and uses the `nonce` to assemble a [WHOAREYOU packet],
+then sends it to Alice using the address in the `inr-enr`. Bob's NAT adds the filtering
+rule `(Bob's-LAN-ip, Bob's-LAN-port, Alice's-WAN-ip, Alice's-WAN-port, entry-lifetime)` to
+it's UDP session table[^2][^3]. A hole is punched in Bob's NAT for Alice for the duration
+of `entry-lifetime`.
 
+From here on it's business as usual. See [Sessions].
+
+### Redundancy of enrs in NODES responses and connectivity status assumptions about Relay and Bob
 
 [EIP-778]: ../enr.md
 [identity scheme]: ../enr.md#record-structure
+[message packet]: ./discv5-wire.md#ordinary-message-packet-flag--0
 [handshake message packet]: ./discv5-wire.md#handshake-message-packet-flag--2
 [WHOAREYOU packet]: ./discv5-wire.md#whoareyou-packet-flag--1
+[notification packet]: ./discv5-wire.md#notification-packet-flag--3
 [PING]: ./discv5-wire.md#ping-request-0x01
 [PONG]: ./discv5-wire.md#pong-response-0x02
 [FINDNODE]: ./discv5-wire.md#findnode-request-0x03
 [REGTOPIC]: ./discv5-wire.md#regtopic-request-0x07
 [REGCONFIRMATION]: ./discv5-wire.md#regconfirmation-response-0x09
 [TOPICQUERY]: ./discv5-wire.md#topicquery-request-0x0a
-[^1]: https://datatracker.ietf.org/doc/html/rfc4787
-[^2]: https://www.ietf.org/rfc/rfc6146.txt
+[RELAYINIT]: ./discv5-wire.md#relayinit-0x01
+[RELAYMSG]: ./discv5-wire.md#relaymsg-0x02
+
+[UDP communication]: ./discv5-wire.md#udp-communication
+
+[^1]: https://pdos.csail.mit.edu/papers/p2pnat.pdf
+[^2]: https://datatracker.ietf.org/doc/html/rfc4787
+[^3]: https://www.ietf.org/rfc/rfc6146.txt