Add sequence diagrams for message flows

docs/handshake.md

@@ -0,0 +1,35 @@
+## Handshake
+
+To establish a connection between a client node and a server node, a handshake is performed with two intermediary relay nodes; one chosen by the client and one chosen by the server. During the handshake, the client and server don't interact directly, but instead communicate through the intermediary relay nodes.
+
+```mermaid
+sequenceDiagram
+    actor c as client node
+    actor cr as client relay node (dht)
+    actor sr as server relay node
+    actor s as server node
+
+    note over cr, s: might be the same node
+    note over sr, s: might be the same node
+
+    c ->> cr: { command: FIND_PEER, target }
+    cr -->> c: { command: FIND_PEER, target, value: { publicKey, relayAddresses } }
+
+    c ->> sr: { command: PEER_HANDSHAKE, target, value: { mode: FROM_CLIENT, ... } }
+    sr ->> s: { command: PEER_HANDSHAKE, target, value: { mode: FROM_RELAY, ... } }
+    s ->> cr: { command: PEER_HANDSHAKE, target, value: { mode: FROM_SERVER, ... } }
+    cr -->> c: { command: PEER_HANDSHAKE, target, value: { mode: REPLY, ... } }
+```
+
+Prior to the handshake, the client node will issue a DHT query to locate the server node. If the chosen relay node does not know about the server node, it will instead forward the query to another node closer to the server node.
+
+Once the server node and its chosen relay node have been identified, the client node will begin the handshake by issuing a DHT query to the server relay node. The relay node forwards this query to the server node, which in turn forwards the query back to the chosen client relay node. The client relay node finally replies back to the client node with the address of the server node.
+
+Note that in the event that either of the relay nodes are also the server node, they will simply skip directly to the final handshake reply and not send the intermediate handshake messages.
+
+As a result of the handshake:
+
+- the client node has a firewall session with its own relay node and the server relay node; and
+- the server node has a firewall session with its own relay node and the client relay node.
+
+The client node may then begin holepunching a connection directly to the server node as it now knows its address.

docs/holepunch.md

@@ -0,0 +1,34 @@
+## Holepunch
+
+After the [handshake](handshake.md) completes, the client may attempt to holepunch a direct connection to the server. Prior to this, the client checks if it has already established a direction connection to the server; this will be the case if the server also acted as the relay node during the handshake.
+
+```mermaid
+sequenceDiagram
+    actor c as client node
+    actor sr as server relay node
+    actor s as server node
+
+    c ->> sr: { command: PEER_HOLEPUNCH, target, value: { mode: FROM_CLIENT, ... } }
+    sr ->> s: { command: PEER_HOLEPUNCH, target, value: { mode: FROM_RELAY, ... } }
+    s ->> sr: { command: PEER_HOLEPUNCH, target, value: { mode: FROM_SERVER, payload: { token, ... }, ... } }
+    sr -->> c: { command: PEER_HOLEPUNCH, target, value: { mode: REPLY, payload, ... } }
+```
+
+```mermaid
+sequenceDiagram
+    actor c as client node
+    actor cr as client relay node (dht)
+    actor s as server node
+
+    c ->> cr: { command: PEER_HOLEPUNCH, target, value: { mode: FROM_CLIENT, payload: { token, remoteToken }, ... } }
+    cr ->> s: { command: PEER_HOLEPUNCH, target, value: { mode: FROM_RELAY, payload,... } }
+
+    note left of s: server can now verify that address of client is correct based on remote token
+
+    s ->> cr: { command: PEER_HOLEPUNCH, target, value: { mode: FROM_SERVER, payload: { remoteToken, ... }, ... } }
+    cr -->> c: { command: PEER_HOLEPUNCH, target, value: { mode: REPLY, payload, ... } }
+
+    note right of c: client can now verify that address of server is correct based on remote token
+```
+
+In tandem with the holepunch messages, the client and server will attempt to ping what they believe to be the address of the other peer. The holepunch messages provide feedback to each peer of the network conditions of the other, including additional addresses that they may attempt to holepunch to. The process ends when both peers have received a ping from the other and a direction connection has then been established.