feat: add private-to-private docs

content/concepts/transports/webrtc.md

@@ -101,17 +101,85 @@ Authenticity is achieved by succeeding the
 
 <!-- TO ADD DIAGRAM -->
 
-### Coming soon: Browser-to-Browser
+### WebRTC W3C (Hole punching to achieve Browser-to-Browser connectivity)
 
-Eventually, libp2p will have support for communication between two
-browsers.
+Thanks to js-libp2p and rust-libp2p (complied to Wasm), libp2p can run in the browser environment.
+However, browsers impose certain restrictions on application code (such as libp2p browser nodes).
+Applications are sandboxed and face constraints on security and networking.
+For instance, browsers do not permit direct access to raw network sockets.
+Additionally, it's a sure bet that libp2p browser nodes will be behind a NAT/firewall.
+Due to these restrictions, browser nodes cannot listen for incoming connections,
+and as a result, they cannot communicate with other browser nodes.
 
-The technical specification and initial implementations of WebRTC
-Browser-to-Browser connectivity is planned for release in early 2023.
-Track the progress [here](https://github.com/libp2p/specs/issues/475).
+Thankfully, libp2p solves this problem and enables browser node to browser node connectivity by supporting a transport called WebRTC W3C.
+
+{{< alert icon="" context="info">}}
+Due to the restrictions mentioned above, libp2p browser nodes are private nodes (meaning they cannot be dialed from outside of their local network).
+However, in principle, this use case can be thought of not just as browser-to-browser but private node to private node.
+This WebRTC solution enables connectivity between two non browser nodes behind a NAT/firewall as well
+{{< /alert >}}
+
+#### Transport Internals
+
+The libp2p WebRTC W3C transport is enabled by supporting the [W3C defined](https://w3c.github.io/webrtc-pc/#introduction) `RTCPeerConnection` API.
+This core API enables p2p connectivity and provides methods for establishing connections and transferring streams of data between peers.
+Running instances of libp2p that support this transport will have `/webrtc-w3c` in their multiaddr.
+
+However, there's more to p2p connections that what `RTCPeerConnection` provides. Crucially, signaling isn't built into the WebRTC API.
+{{< alert icon="" context="info">}}
+Signaling is the process of coordinating communication and exchanging metadata about the communication (i.e. initializing, closing, or reporting errors about connections).
+{{< /alert >}}
+
+For this transport, libp2p supports its own signaling protocol which has the protocol id: `webrtc-w3c-signaling`.
+
+#### How browser-to-browser connectivity works
 
 <!-- TO ADD DIAGRAM -->
 
+Suppose we have three network entities:
+
+- _Node A_ - a libp2p node running in the browser
+- _Node B_ - another browser libp2p node running on a different browser instance
+- _Relay R_ - a libp2p relay node
+
+In this connectivity scenario, _A_ wants to connect to _B_.
+This roughly works as follows:
+
+- _A_ and _B_ are both connected to _R_
+- _B_ appends `webrtc-w3c` to its multiaddress and that multiaddress is relayed by _R_.
+- _A_ will discover _B_'s multiaddress via _R_
+- _A_ sees that _B_ supports `webrtc-w3c` and establishes a relayed connection to _B_
+- Over the relayed connection, _A_ will:
+  - Create an _outbound_ `RTCPeerConnection`
+  - Send a SDP offer via the WebRTC API
+  - Initiate the `webrtc-w3c-signaling` signaling protocol via a stream
+- On _B_'s end (over the same relayed connection), _B_ will
+  - Receive _A_'s SDP offer sent via the signaling protocol stream
+  - Create an _inbound_ `RTCPeerConnection` and provide the offer to its peer connection via the WebRTC API
+  - Send an answer back to _A_ over the signaling protocol stream
+- Once _A_ gets the answer from _B_, _A_ sets the session description with answer
+- Via the signaling protocol stream, _A_ and _B_ now both exchange information about the network connection (in WebRTC parlance this is called [exchanging ICE candidates](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Connectivity#ice_candidates))
+- After this whole process is done, there can be one of two results:
+  - A successful direct connection is established between _A_ and _B_
+    - In this case, both browser nodes will close the signaling protocol stream
+    - The relayed connection is closed
+  - A failed direction connection
+    - In this case, the signaling stream is reset
+    - It's important to note that libp2p does not specify transferring data over the relayed connection if the direct connection fails
+
+{{< alert icon="" context="info">}}
+As mentioned, a browser node is private and behind a NAT/firewall.
+It needs to discover it's public IP address and port to send to the remote peer.
+To do this, libp2p's `webrtc-w3c` solution depends on STUN servers.
+STUN servers are the only way to discover ones own public IP address and port in the browser.
+Public STUN servers can be used or you may choose to operate a dedicate STUN server(s) for your libp2p network.
+In the above connectivity example, the browser nodes need not use the same STUN server.
+{{< /alert >}}
+
+In summary, `webrtc-w3c` makes us of the WebRTC API to establish connectivity.
+It also relies on relay nodes and STUN servers to create relay connections to discover a browser node's public IP address and port.
+Lastly, it uses the signaling protocol to hole punch across NATs/firewalls and establish a direct connection between two browser nodes.
+
 {{< alert icon="💡" context="note" text="See the WebRTC <a class=\"text-muted\" href=\"https://github.com/libp2p/specs/blob/master/webrtc/README.md\">technical specification</a> for more details." />}}
 
 ## Comparing WebRTC and WebTransport