discv5: hole punching text updates

Author: fjl

discv5/discv5-theory.md

@@ -334,70 +334,96 @@ the distance to retrieve more nodes from adjacent k-buckets on `B`:
 Node `A` now sorts all received nodes by distance to the lookup target and proceeds by
 repeating the lookup procedure on another, closer node.
 
-## Hole punch asymmetric NATs
+## Hole-punching Asymmetric NATs
+
+This section explains the hole punching mechanism built into the protocol, which is
+enabled by the [RELAYINIT] and [RELAYMSG] message types. Compared to other protocol
+messages, these require deeper interaction with the session layer in order to ensure the
+hole punching mechanism operates safely.
+
+In the examples below, we assume that node `A` (Alice) has the goal of sending a request
+message (e.g. FINDNODE) to node `B` (Bob).
+
+Bob operates behind a network-adress-translation (NAT) layer, and is unable to receive UDP
+packets from Alice initially. However, Bob has previously communicated with a third node
+`R` (Relay), and is able to receive incoming packets from the Relay node. We further
+assume Bob's NAT is 'asymmetric', i.e. the IP/Port of Bob's packets will be the same
+regardless of the host they are sent to. The hole-punching mechanism does not work for
+'symmetric' NAT where every destination host has a unique mapping.
+
+Node Alice may or may not behind a symmetric NAT.
+
+Finally, it is assumed that a common lower bound on lifetime of NAT mappings is 20
+seconds, and that mappings will be refreshed when any packet is sent through them. For
+more background information about common NAT setups, please consult [RFC4787], [RFC6146]
+and [this paper][natpaper].
 
 ### Message flow
 
-There are 4 total message containers, these are abbreviated in the sequence diagram below
-as follows:
+In the wire protocol, there are four packet types. Since the NAT-related messages require
+deeper integration with the packet/session layer, the packet type is explicitly shown for
+each message in the diagram below. We use these abbreviations:
 
-- m - [message packet]
 - whoareyou - [WHOAREYOU packet]
-- hm - [handshake message packet]
-- s - [session message packet]
+- `m(X)`: [message packet] containing request `X`
+- `H(X)`: [handshake message packet] containing request `X`
+- `s(M)`: [session message packet] containing message `M`
 
     ```mermaid
         sequenceDiagram
             participant Alice
             participant Relay
             participant Bob
 
-            Relay-->>Alice: m(NODES[Bob's ENR])
+            Relay-->>Alice: s(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: s(RELAYINIT[nonce])
             Relay->>Bob: s(RELAYMSG[nonce])
             Bob-->>Alice: whoareyou(nonce)
             Note right of Bob: Hole punched in Bob's NAT for Alice
-            Alice-->>Bob: hm(FINDNODE)
+            Alice-->>Bob: H(FINDNODE)
     ```
 
-Bob is behind 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 hence Relay can get through Bob's NAT[^1].
+Preconditions: Bob is behind NAT. Bob is contained in Relay's node table, they have an
+established session and Bob has sent a packet to Relay in the last ~20 seconds hence Relay
+can get through Bob's NAT.
 
 As part of recursive query for peers, 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 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[^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 NAT.
-
-Alice initiates an attempt to punch a hole in Bob's NAT via Relay. Alice resets 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 `target-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 duration). Relay assembles a [RELAYMSG]
-notification with Alice's message nonce and ENR, then sends it to the address in Bob's
-ENR.
+it just received from the Relay. By making an outgoing request to Bob, if Alice is behind
+NAT, Alice's NAT adds a mapping `(Alice's-LAN-ip, Alice's-LAN-port, Bob's-WAN-ip,
+Bob's-WAN-port, entry-lifetime)`. This means a hole now is punched for Bob in Alice's NAT
+for the duration of `entry-lifetime`. However, Alice's request is not delivered as Bob is
+behind NAT.
+
+Alice detects the timeout, and initiates an attempt to punch a hole in Bob's NAT via
+Relay. Alice resets 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.
+
+The Relay node validates the [RELAYINIT] notification and uses the `target-id` to look up
+Bob's ENR in its node table. Bob is very likely to be a member of the Relay's table
+because it was just sent to Alice in a [NODES] response. Note that, if Bob is not
+contained in the table, communication ends here.
+
+The Relay sends a [RELAYMSG] notification containing Alice's message nonce and ENR to Bob.
 
 Bob disassembles the [RELAYMSG] and uses the `nonce` to assemble a [WHOAREYOU packet],
-then sends it to Alice using the address in the `initiator-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`.
+then sends it to Alice. Bob knows about Alice's endpoint from the `initiator-enr` given in
+in RELAYMSG.
+
+Bob's NAT adds the mapping `(Bob's-LAN-ip, Bob's-LAN-port, Alice's-WAN-ip,
+Alice's-WAN-port, entry-lifetime)`. 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
 
 Often the same peers get passed around in NODES responses by different peers. The chance
 of seeing a peer received in a NODES response again in another NODES response is high as
-kbuckets favour long lived connections to new ones[^4]. This makes the need for a storing
+k-buckets favour long lived connections to new ones. This makes the need for a storing
 back up relays for peers small.
 
 Apart from the state that is saved by not storing more than the last peer to send us an
@@ -408,51 +434,54 @@ hence of its ability to relay.
 ### Job of keeping the hole punched falls on Bob and Bob's incentive to do so
 
 UDP session table entry lifetimes are configurable, though a common lower bound is 20
-seconds[^1]. Bob must periodically reset the session table entry for Alice in its NAT to
-keep the hole for Alice punched. If Alice too is behind NAT, it must do the same for Bob.
+seconds. Bob must periodically reset the session table entry for Alice in its NAT to keep
+the hole for Alice punched. If Alice too is behind NAT, it must do the same for Bob.
 Implementations must ensure, when a node behind NAT does not send a packet to a peer
 within the entry lifetime then an empty packet is sent that is dropped by the peer.
 
 NAT hole punching unavoidably creates overhead for all nodes in the network but once a
 hole is punched, keeping it punched requires no interaction between peers. The incentive
 for nodes behind NAT to keep holes for its peers punched is to avoid reestablishing a
-session. If there is no hole for Alice in Bob's NAT when Alice carries out a
-[liveness check], Bob is considered offline and the session to Bob useless. If the node
-behind NAT intends to frequently communicate with a peer, reestablishing the session is
-more costly than managing the interval of sent packets to that peer.
+session. If there is no hole for Alice in Bob's NAT when Alice carries out a [liveness
+check], Bob is considered offline and the session to Bob useless. If the node behind NAT
+intends to frequently communicate with a peer, reestablishing the session is more costly
+than managing the interval of sent packets to that peer.
 
 ### Discovering if the local node is behind NAT and must keep holes for peers punched
 
-A node may at start-up be assigned an externally reachable socket to advertise as well as a
-listen socket. If those sockets are not equivalent, the node is behind NAT and the
+A node may at start-up be assigned an externally reachable socket to advertise as well as
+a listen socket. If those sockets are not equivalent, the node is behind NAT and the
 [mechanism for keeping holes punched] is activated. Like so, a node assumes it is behind
 NAT if an externally reachable socket is omitted from the initial configuration and must
-activate the [mechanism for keeping holes punched]. [Runtime address discovery] asses the
-external socket used by the local node. Once a new externally reachable socket is known,
-implementations will try to bind to its IP address at some number of randomly selected ports
-from a given range of probably unused ports. If binding succeeds with any port, the node is
-not behind NAT and the [mechanism for keeping holes punched] is deactivated. This solution
-assumes, in most scenarios where port-forwarding cannot be configured the local node host's
-address is private to the address realm of the device operating the NAT level furthest from
-the local node host[^1]. If the host and NAT device use the same IP address, binding will
-always succeed, so this method may give a false negative. However, this is not detrimental.
-A node behind NAT that deactivates the [mechanism for keeping holes punched] will more
-frequently have to re-establish sessions to its peers.
+activate the mechanism for keeping holes punched. The [runtime address discovery]
+mechanism can discovery the external endpoint address used by the local node. Once a new
+externally reachable endpoint is known, implementations will try to bind to its IP address
+at some number of randomly selected ports from a given range of probably unused ports. If
+binding succeeds with any port, the node is not behind NAT and the mechanism for keeping
+holes punched is deactivated.
+
+This solution assumes, in most scenarios where port-forwarding cannot be configured the
+local node host's address is private to the address realm of the device operating the NAT
+level furthest from the local node host. If the host and NAT device use the same IP
+address, binding will always succeed, so this method may give a false negative. However,
+this is not detrimental. A node behind NAT that deactivates the mechanism for keeping
+holes punched will more frequently have to re-establish sessions to its peers.
 
 ### Limiting resource consumption of peers behind symmetric NATs, useful for light-clients
 
-Peers with unreachable ENRs do not get inserted into kbuckets. Nodes that are behind
-symmetric NATs will naturally never succeed in pinpointing one external socket for peers
-to reach them on by [runtime address discovery] and therefore their unreachable ENRs
-will never update to reachable ENRs. This means, these peers will never respond to
-requests, as only peers in kbucktes are sent requests. This does not cohere with the
-p2p-model, rather the server-client model where the peer with a unreachable ENR acts
-as the client. This misalignment is especially bothersome for well behaving (externally
-reachable) light-clients operating on limited resources. Discv5.2 corrects this
-side-effect of [runtime address discovery] by setting introducing a configurable limit to
-the number of sessions at a time with peers with unreachable ENRs, the lower limit
-being 1. Nodes must accept sessions with at least one peer with a unreachable ENR to
-for [runtime address discovery] to be enabled on the discv5.2 network.
+Peers with unreachable ENRs do not get inserted into node table buckets. Nodes that are
+behind symmetric NATs will naturally never succeed in pinpointing one external socket for
+peers to reach them on by [runtime address discovery] and therefore their unreachable ENRs
+will never update to reachable ENRs.
+
+This means, these peers will never respond to requests, as only peers in the node table
+are sent requests. This does not cohere with the p2p-model, rather the server-client model
+where the peer with a unreachable ENR acts as the client. This misalignment is especially
+bothersome for well behaving (externally reachable) light-clients operating on limited
+resources. Discv5.2 corrects this side-effect of runtime address discovery by introducing
+a configurable limit to the number of sessions at a time with peers with unreachable ENRs,
+the lower limit being 1. Nodes must accept sessions with at least one peer with a
+unreachable ENR to for runtime address discovery to be enabled on the discv5.2 network.
 
 ### Fault tolerance
 
@@ -475,11 +504,9 @@ number of retries) that peer is considered unresponsive and the session can be f
 [UDP communication]: ./discv5-wire.md#udp-communication
 [Sessions]: ./discv5-theory.md#sessions
 [liveness check]: ./discv5-theory.md#table-maintenance-in-practice
-[Runtime address discovery]: ./discv5-theory.md#maintaining-the-local-node-record
 [runtime address discovery]: ./discv5-theory.md#maintaining-the-local-node-record
 [mechanism for keeping holes punched]: ./discv5-theory.md#job-of-keeping-the-hole-punched-falls-on-bob-and-bob's-incentive-to-do-so
 
-[^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
-[^4]: https://pdos.csail.mit.edu/~petar/papers/maymounkov-kademlia-lncs.pdf
+[natpaper]: https://pdos.csail.mit.edu/papers/p2pnat.pdf
+[RFC4787]: https://datatracker.ietf.org/doc/html/rfc4787
+[RFC6146]: https://datatracker.ietf.org/doc/html/rfc6146